From 4b79c88ae50b9d2b6aecda345ec03639ad1bbff9 Mon Sep 17 00:00:00 2001 From: Marek Wolan Date: Tue, 21 Jan 2025 10:42:09 +0000 Subject: [PATCH] Fix typos and TODOs --- docs/source/action_masking.rst | 121 ++++++++---------- .../how_to_guides/extensible_actions.rst | 6 +- .../how_to_guides/extensible_agents.rst | 2 +- src/primaite/game/agent/actions/acl.py | 6 +- src/primaite/game/agent/actions/manager.py | 1 - src/primaite/game/agent/actions/node.py | 12 +- src/primaite/game/agent/actions/software.py | 17 +-- src/primaite/game/agent/interface.py | 2 +- 8 files changed, 67 insertions(+), 100 deletions(-) diff --git a/docs/source/action_masking.rst b/docs/source/action_masking.rst index 359ad452..4331b090 100644 --- a/docs/source/action_masking.rst +++ b/docs/source/action_masking.rst @@ -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. | +------------------------------------------+---------------------------------------------------------------------+ diff --git a/docs/source/how_to_guides/extensible_actions.rst b/docs/source/how_to_guides/extensible_actions.rst index 0064a3a7..93a6cf21 100644 --- a/docs/source/how_to_guides/extensible_actions.rst +++ b/docs/source/how_to_guides/extensible_actions.rst @@ -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. diff --git a/docs/source/how_to_guides/extensible_agents.rst b/docs/source/how_to_guides/extensible_agents.rst index 4b6f8598..256e96ca 100644 --- a/docs/source/how_to_guides/extensible_agents.rst +++ b/docs/source/how_to_guides/extensible_agents.rst @@ -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 ==================== diff --git a/src/primaite/game/agent/actions/acl.py b/src/primaite/game/agent/actions/acl.py index a097b906..3341868f 100644 --- a/src/primaite/game/agent/actions/acl.py +++ b/src/primaite/game/agent/actions/acl.py @@ -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", diff --git a/src/primaite/game/agent/actions/manager.py b/src/primaite/game/agent/actions/manager.py index a6e235c5..3e5b21b1 100644 --- a/src/primaite/game/agent/actions/manager.py +++ b/src/primaite/game/agent/actions/manager.py @@ -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 diff --git a/src/primaite/game/agent/actions/node.py b/src/primaite/game/agent/actions/node.py index 95bf5c34..fbab18f0 100644 --- a/src/primaite/game/agent/actions/node.py +++ b/src/primaite/game/agent/actions/node.py @@ -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", diff --git a/src/primaite/game/agent/actions/software.py b/src/primaite/game/agent/actions/software.py index 12462ede..e0d602ed 100644 --- a/src/primaite/game/agent/actions/software.py +++ b/src/primaite/game/agent/actions/software.py @@ -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.""" diff --git a/src/primaite/game/agent/interface.py b/src/primaite/game/agent/interface.py index b58cdf29..05e3643a 100644 --- a/src/primaite/game/agent/interface.py +++ b/src/primaite/game/agent/interface.py @@ -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."""