oxbrbtx/PrimAITE
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix typos and TODOs

Browse Source
This commit is contained in:
Marek Wolan
2025-01-21 10:42:09 +00:00
parent 18a665e562
commit 4b79c88ae5
8 changed files with 67 additions and 100 deletions
Download Patch File Download Diff File Expand all files Collapse all files

121
docs/source/action_masking.rst
View File

@@ -20,131 +20,120 @@ Masking Logic
=============
The following logic is applied:
..only:: comment
TODO: update table
+------------------------------------------+---------------------------------------------------------------------+
| Action | Action Mask Logic |
+==========================================+=====================================================================+
| **DONOTHING** | Always Possible. |
| **do_nothing** | Always Possible. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_SERVICE_SCAN** | Node is on. Service is running. |
| **node_service_scan** | Node is on. Service is running. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_SERVICE_STOP** | Node is on. Service is running. |
| **node_service_stop** | Node is on. Service is running. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_SERVICE_START** | Node is on. Service is stopped. |
| **node_service_start** | Node is on. Service is stopped. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_SERVICE_PAUSE** | Node is on. Service is running. |
| **node_service_pause** | Node is on. Service is running. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_SERVICE_RESUME** | Node is on. Service is paused. |
| **node_service_resume** | Node is on. Service is paused. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_SERVICE_RESTART** | Node is on. Service is running. |
| **node_service_restart** | Node is on. Service is running. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_SERVICE_DISABLE** | Node is on. |
| **node_service_disable** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_SERVICE_ENABLE** | Node is on. Service is disabled. |
| **node_service_enable** | Node is on. Service is disabled. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_SERVICE_FIX** | Node is on. Service is running. |
| **node_service_fix** | Node is on. Service is running. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_APPLICATION_EXECUTE** | Node is on. |
| **node_application_execute** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_APPLICATION_SCAN** | Node is on. Application is running. |
| **node_application_scan** | Node is on. Application is running. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_APPLICATION_CLOSE** | Node is on. Application is running. |
| **node_application_close** | Node is on. Application is running. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_APPLICATION_FIX** | Node is on. Application is running. |
| **node_application_fix** | Node is on. Application is running. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_APPLICATION_INSTALL** | Node is on. |
| **node_application_install** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_APPLICATION_REMOVE** | Node is on. |
| **node_application_remove** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_FILE_SCAN** | Node is on. File exists. File not deleted. |
| **node_file_scan** | Node is on. File exists. File not deleted. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_FILE_CREATE** | Node is on. |
| **node_file_create** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_FILE_CHECKHASH** | Node is on. File exists. File not deleted. |
| **node_file_checkhash** | Node is on. File exists. File not deleted. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_FILE_DELETE** | Node is on. File exists. |
| **node_file_delete** | Node is on. File exists. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_FILE_REPAIR** | Node is on. File exists. File not deleted. |
| **node_file_repair** | Node is on. File exists. File not deleted. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_FILE_RESTORE** | Node is on. File exists. File is deleted. |
| **node_file_restore** | Node is on. File exists. File is deleted. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_FILE_CORRUPT** | Node is on. File exists. File not deleted. |
| **node_file_corrupt** | Node is on. File exists. File not deleted. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_FILE_ACCESS** | Node is on. File exists. File not deleted. |
| **node_file_access** | Node is on. File exists. File not deleted. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_FOLDER_CREATE** | Node is on. |
| **node_folder_create** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_FOLDER_SCAN** | Node is on. Folder exists. Folder not deleted. |
| **node_folder_scan** | Node is on. Folder exists. Folder not deleted. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_FOLDER_CHECKHASH** | Node is on. Folder exists. Folder not deleted. |
| **node_folder_checkhash** | Node is on. Folder exists. Folder not deleted. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_FOLDER_REPAIR** | Node is on. Folder exists. Folder not deleted. |
| **node_folder_repair** | Node is on. Folder exists. Folder not deleted. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_FOLDER_RESTORE** | Node is on. Folder exists. Folder is deleted. |
| **node_folder_restore** | Node is on. Folder exists. Folder is deleted. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_OS_SCAN** | Node is on. |
| **node_os_scan** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **HOST_NIC_ENABLE** | NIC is disabled. Node is on. |
| **host_nic_enable** | NIC is disabled. Node is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **HOST_NIC_DISABLE** | NIC is enabled. Node is on. |
| **host_nic_disable** | NIC is enabled. Node is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_SHUTDOWN** | Node is on. |
| **node_shutdown** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_STARTUP** | Node is off. |
| **node_startup** | Node is off. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_RESET** | Node is on. |
| **node_reset** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_NMAP_PING_SCAN** | Node is on. |
| **node_nmap_ping_scan** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_NMAP_PORT_SCAN** | Node is on. |
| **node_nmap_port_scan** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_NMAP_NETWORK_SERVICE_RECON** | Node is on. |
| **node_network_service_recon** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **NETWORK_PORT_ENABLE** | Node is on. Router is on. |
| **network_port_enable** | Node is on. Router is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **NETWORK_PORT_DISABLE** | Router is on. |
| **network_port_disable** | Router is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **ROUTER_ACL_ADDRULE** | Router is on. |
| **router_acl_addrule** | Router is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **ROUTER_ACL_REMOVERULE** | Router is on. |
| **router_acl_removerule** | Router is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **FIREWALL_ACL_ADDRULE** | Firewall is on. |
| **firewall_acl_addrule** | Firewall is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **FIREWALL_ACL_REMOVERULE** | Firewall is on. |
| **firewall_acl_removerule** | Firewall is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_NMAP_PING_SCAN** | Node is on. |
| **configure_database_client** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_NMAP_PORT_SCAN** | Node is on. |
| **configure_ransomware_script** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_NMAP_NETWORK_SERVICE_RECON** | Node is on. |
| **c2_server_ransomware_configure** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **CONFIGURE_DATABASE_CLIENT** | Node is on. |
| **configure_dos_bot** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **c2_server_ransomware_configure** | Node is on. |
| **configure_c2_beacon** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **configure_dos_bot** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **CONFIGURE_C2_BEACON** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **C2_SERVER_RANSOMWARE_LAUNCH** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **C2_SERVER_RANSOMWARE_CONFIGURE** | Node is on. |
| **c2_server_ransomware_launch** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **c2_server_terminal_command** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **C2_SERVER_DATA_EXFILTRATE** | Node is on. |
| **c2_server_data_exfiltrate** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **node_account_change_password** | Node is on. |
| **node_account_change_password** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **node_session_remote_login** | Node is on. |
| **node_session_remote_login** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **node_session_remote_logoff** | Node is on. |
| **node_session_remote_logoff** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **NODE_SEND_REMOTE_COMMAND** | Node is on. |
| **node_send_remote_command** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+

6
docs/source/how_to_guides/extensible_actions.rst
View File

@@ -22,7 +22,7 @@ Custom actions within PrimAITE must be a sub-class of `AbstractAction`, and cont
#. Unique Identifier
#. `from_request` method.
#. `form_request` method.
ConfigSchema
@@ -61,7 +61,7 @@ When declaring a custom class, it must have a unique identifier string, that all
The above action would fail pydantic validation as the identifier "node_folder_create" is already used by the `NodeFolderCreateAction`, and would create a duplicate listing within `AbstractAction._registry`.
from_request method
form_request method
###################
PrimAITE actions need to be have a `from_request` method, which can be passed to the `RequestManager` for processing. This allows the custom action to be actioned within the simulation environment.
PrimAITE actions need to have a `form_request` method, which can be passed to the `RequestManager` for processing. This allows the custom action to be actioned within the simulation environment.

2
docs/source/how_to_guides/extensible_agents.rst
View File

@@ -66,7 +66,7 @@ The core features that should be implemented in any new agent are detailed below
#. **Identifiers**:
All agent classes should have a ``identifier`` attribute, a unique kebab-case string, for when they are added to the base ``AbstractAgent`` registry. This is then specified in your configuration YAML, and used by PrimAITE to generate the correct Agent.
All agent classes should have an ``identifier`` attribute, a unique kebab-case string, for when they are added to the base ``AbstractAgent`` registry. This is then specified in your configuration YAML, and used by PrimAITE to generate the correct Agent.
Changes to YAML file
====================

6
src/primaite/game/agent/actions/acl.py
View File

@@ -2,7 +2,7 @@
from __future__ import annotations
from abc import ABC
from typing import List, Literal, Union
from typing import Literal, Union
from primaite.game.agent.actions.manager import AbstractAction
from primaite.interface.request import RequestFormat
@@ -59,7 +59,7 @@ class RouterACLAddRuleAction(ACLAddRuleAbstractAction, identifier="router_acl_ad
target_router: str
@classmethod
def form_request(cls, config: ConfigSchema) -> List[str]:
def form_request(cls, config: ConfigSchema) -> RequestFormat:
"""Return the action formatted as a request which can be ingested by the PrimAITE simulation."""
return [
"network",
@@ -143,7 +143,7 @@ class FirewallACLRemoveRuleAction(ACLRemoveRuleAbstractAction, identifier="firew
firewall_port_direction: str
@classmethod
def form_request(cls, config: ConfigSchema) -> List[str]:
def form_request(cls, config: ConfigSchema) -> RequestFormat:
"""Return the action formatted as a request which can be ingested by the PrimAITE simulation."""
return [
"network",

1
src/primaite/game/agent/actions/manager.py
View File

@@ -18,7 +18,6 @@ from typing import Dict, Tuple
from gymnasium import spaces
from pydantic import BaseModel, ConfigDict, Field, field_validator
# from primaite.game.game import PrimaiteGame # TODO: Breaks things
from primaite.game.agent.actions.abstract import AbstractAction
from primaite.interface.request import RequestFormat

12
src/primaite/game/agent/actions/node.py
View File

@@ -110,7 +110,7 @@ class NodeNMAPPingScanAction(NodeNMAPAbstractAction, identifier="node_nmap_ping_
config: "NodeNMAPPingScanAction.ConfigSchema"
@classmethod
def form_request(cls, config: "NodeNMAPPingScanAction.ConfigSchema") -> List[str]: # noqa
def form_request(cls, config: "NodeNMAPPingScanAction.ConfigSchema") -> RequestFormat:
"""Return the action formatted as a request which can be ingested by the PrimAITE simulation."""
return [
"network",
@@ -137,10 +137,7 @@ class NodeNMAPPortScanAction(NodeNMAPAbstractAction, identifier="node_nmap_port_
show: Optional[bool] = (False,)
@classmethod
def form_request(
cls,
config: ConfigSchema,
) -> List[str]: # noqa
def form_request(cls, config: ConfigSchema) -> RequestFormat:
"""Return the action formatted as a request which can be ingested by the PrimAITE simulation."""
return [
"network",
@@ -171,10 +168,7 @@ class NodeNetworkServiceReconAction(NodeNMAPAbstractAction, identifier="node_net
show: Optional[bool] = (False,)
@classmethod
def form_request(
cls,
config: ConfigSchema,
) -> List[str]: # noqa
def form_request(cls, config: ConfigSchema) -> RequestFormat:
"""Return the action formatted as a request which can be ingested by the PrimAITE simulation."""
return [
"network",

17
src/primaite/game/agent/actions/software.py
View File

@@ -2,7 +2,7 @@
from typing import List, Optional, Union
from pydantic import ConfigDict, Field, field_validator, ValidationInfo
from pydantic import ConfigDict, Field
from primaite.game.agent.actions.manager import AbstractAction
from primaite.interface.request import RequestFormat
@@ -100,21 +100,6 @@ class ConfigureC2BeaconAction(AbstractAction, identifier="configure_c2_beacon"):
masquerade_protocol: str = Field(default="TCP")
masquerade_port: str = Field(default="HTTP")
# TODO: this validator should not be needed anymore, test what happens if removed.
@field_validator(
"c2_server_ip_address",
"keep_alive_frequency",
"masquerade_protocol",
"masquerade_port",
mode="before",
)
@classmethod
def not_none(cls, v: str, info: ValidationInfo) -> int:
"""If None is passed, use the default value instead."""
if v is None:
return cls.model_fields[info.field_name].default
return v
@classmethod
def form_request(self, config: ConfigSchema) -> RequestFormat:
"""Return the action formatted as a request that can be ingested by the simulation."""

2
src/primaite/game/agent/interface.py
View File

@@ -132,7 +132,7 @@ class AbstractAgent(BaseModel, ABC):
# then use a bespoke conversion to take 1-40 int back into CAOS action
return ("do_nothing", {})
def format_request(self, action: Tuple[str, Dict], options: Dict[str, int]) -> List[str]:
def format_request(self, action: Tuple[str, Dict], options: Dict[str, int]) -> RequestFormat:
# this will take something like APPLICATION.EXECUTE and add things like target_ip_address in simulator.
# therefore the execution definition needs to be a mapping from CAOS into SIMULATOR
"""Format action into format expected by the simulator, and apply execution definition if applicable."""