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

111
docs/source/action_masking.rst
View File

@@ -20,123 +20,112 @@ Masking Logic
============= =============
The following logic is applied: The following logic is applied:
..only:: comment
TODO: update table
+------------------------------------------+---------------------------------------------------------------------+ +------------------------------------------+---------------------------------------------------------------------+
| Action | Action Mask Logic | | 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. |
+------------------------------------------+---------------------------------------------------------------------+
| **CONFIGURE_DATABASE_CLIENT** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+ +------------------------------------------+---------------------------------------------------------------------+
| **c2_server_ransomware_configure** | Node is on. | | **c2_server_ransomware_configure** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+ +------------------------------------------+---------------------------------------------------------------------+
| **configure_dos_bot** | Node is on. | | **configure_dos_bot** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+ +------------------------------------------+---------------------------------------------------------------------+
| **CONFIGURE_C2_BEACON** | Node is on. | | **configure_c2_beacon** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+ +------------------------------------------+---------------------------------------------------------------------+
| **C2_SERVER_RANSOMWARE_LAUNCH** | Node is on. | | **c2_server_ransomware_launch** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+
| **C2_SERVER_RANSOMWARE_CONFIGURE** | Node is on. |
+------------------------------------------+---------------------------------------------------------------------+ +------------------------------------------+---------------------------------------------------------------------+
| **c2_server_terminal_command** | 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. |
+------------------------------------------+---------------------------------------------------------------------+ +------------------------------------------+---------------------------------------------------------------------+
@@ -144,7 +133,7 @@ The following logic is applied:
+------------------------------------------+---------------------------------------------------------------------+ +------------------------------------------+---------------------------------------------------------------------+
| **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 #. Unique Identifier
#. `from_request` method. #. `form_request` method.
ConfigSchema 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`. 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**: #. **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 Changes to YAML file
==================== ====================

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

@@ -2,7 +2,7 @@
from __future__ import annotations from __future__ import annotations
from abc import ABC 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.game.agent.actions.manager import AbstractAction
from primaite.interface.request import RequestFormat from primaite.interface.request import RequestFormat
@@ -59,7 +59,7 @@ class RouterACLAddRuleAction(ACLAddRuleAbstractAction, identifier="router_acl_ad
target_router: str target_router: str
@classmethod @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 the action formatted as a request which can be ingested by the PrimAITE simulation."""
return [ return [
"network", "network",
@@ -143,7 +143,7 @@ class FirewallACLRemoveRuleAction(ACLRemoveRuleAbstractAction, identifier="firew
firewall_port_direction: str firewall_port_direction: str
@classmethod @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 the action formatted as a request which can be ingested by the PrimAITE simulation."""
return [ return [
"network", "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 gymnasium import spaces
from pydantic import BaseModel, ConfigDict, Field, field_validator 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.game.agent.actions.abstract import AbstractAction
from primaite.interface.request import RequestFormat 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" config: "NodeNMAPPingScanAction.ConfigSchema"
@classmethod @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 the action formatted as a request which can be ingested by the PrimAITE simulation."""
return [ return [
"network", "network",
@@ -137,10 +137,7 @@ class NodeNMAPPortScanAction(NodeNMAPAbstractAction, identifier="node_nmap_port_
show: Optional[bool] = (False,) show: Optional[bool] = (False,)
@classmethod @classmethod
def form_request( def form_request(cls, config: ConfigSchema) -> RequestFormat:
cls,
config: ConfigSchema,
) -> List[str]: # noqa
"""Return the action formatted as a request which can be ingested by the PrimAITE simulation.""" """Return the action formatted as a request which can be ingested by the PrimAITE simulation."""
return [ return [
"network", "network",
@@ -171,10 +168,7 @@ class NodeNetworkServiceReconAction(NodeNMAPAbstractAction, identifier="node_net
show: Optional[bool] = (False,) show: Optional[bool] = (False,)
@classmethod @classmethod
def form_request( def form_request(cls, config: ConfigSchema) -> RequestFormat:
cls,
config: ConfigSchema,
) -> List[str]: # noqa
"""Return the action formatted as a request which can be ingested by the PrimAITE simulation.""" """Return the action formatted as a request which can be ingested by the PrimAITE simulation."""
return [ return [
"network", "network",

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

@@ -2,7 +2,7 @@
from typing import List, Optional, Union 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.game.agent.actions.manager import AbstractAction
from primaite.interface.request import RequestFormat from primaite.interface.request import RequestFormat
@@ -100,21 +100,6 @@ class ConfigureC2BeaconAction(AbstractAction, identifier="configure_c2_beacon"):
masquerade_protocol: str = Field(default="TCP") masquerade_protocol: str = Field(default="TCP")
masquerade_port: str = Field(default="HTTP") 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 @classmethod
def form_request(self, config: ConfigSchema) -> RequestFormat: def form_request(self, config: ConfigSchema) -> RequestFormat:
"""Return the action formatted as a request that can be ingested by the simulation.""" """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 # then use a bespoke conversion to take 1-40 int back into CAOS action
return ("do_nothing", {}) 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. # 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 # 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.""" """Format action into format expected by the simulator, and apply execution definition if applicable."""