From 0ee454b13ef69f3ba58064d1edd2573720c51a2a Mon Sep 17 00:00:00 2001 From: Charlie Crane Date: Fri, 3 Jan 2025 14:53:54 +0000 Subject: [PATCH] #2912 - Rename actions/config.py to actions/software.py --- .../how_to_guides/extensible_actions.rst | 69 +------------------ src/primaite/game/agent/actions/__init__.py | 6 +- src/primaite/game/agent/actions/abstract.py | 2 +- src/primaite/game/agent/actions/acl.py | 2 +- .../game/agent/actions/application.py | 2 +- src/primaite/game/agent/actions/file.py | 2 +- src/primaite/game/agent/actions/folder.py | 2 +- src/primaite/game/agent/actions/host_nic.py | 2 +- src/primaite/game/agent/actions/manager.py | 2 +- src/primaite/game/agent/actions/network.py | 2 +- src/primaite/game/agent/actions/node.py | 2 +- src/primaite/game/agent/actions/service.py | 2 +- src/primaite/game/agent/actions/session.py | 2 +- .../agent/actions/{config.py => software.py} | 2 +- src/primaite/game/agent/rewards.py | 3 +- .../actions/test_configure_actions.py | 2 +- 16 files changed, 19 insertions(+), 85 deletions(-) rename src/primaite/game/agent/actions/{config.py => software.py} (99%) diff --git a/docs/source/how_to_guides/extensible_actions.rst b/docs/source/how_to_guides/extensible_actions.rst index 6e44a905..f2e053aa 100644 --- a/docs/source/how_to_guides/extensible_actions.rst +++ b/docs/source/how_to_guides/extensible_actions.rst @@ -1,70 +1,3 @@ .. only:: comment - © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK - -.. _about: - -Extensible Actions -****************** - -Actions defined within PrimAITE have been updated to allow for easier creation of new bespoke actions, without the need to make changes to the ActionManager class within the core PrimAITE repository. - - -Developing Actions for PrimAITE -=============================== - -When developing new actions for PrimAITE, it's important to ensure new actions inherit from the AbstractAction class. This is so that the `ActionManager` has visibility -of the new action through the `AbstractAction` registry attribute. This also removes the need for actions to contain an `__init__` method. - -New actions to be used within PrimAITE require: - -#. **ConfigSchema**: - - This should be a nested class that defines the required configuration items for the new action. - - .. code-block:: python - - class ExampleAction(AbstractAction, identifier="Example_action"): - """An example action for demonstration purposes.""" - - config: "ExampleAction.ConfigSchema" - - class ConfigSchema(AbstractAction.ConfigSchema): - """The configuration schema with all attributes expected goes here.""" - target_application: str - - The ConfigSchema is used when the class is called to form the action, within the `form_request` method, detailed below. - - -#. **Unique Identifier**: - - New actions should have a Unique identifier when declared. This is used by the `ActionManager` when forming/processing action commands from agents. See the example code block in ConfigSchema for how this should be implemented. - -#. **form_request method**: - - New actions need a `form_request()` method, to convert the action into a ``Requestformat`` that can be ingested by PrimAITE's `RequestManager`. - The below is an example of how this is done, taken from the `NodeFolderCreateAction`. - - .. code-block:: python - - @classmethod - def form_request(cls, config: ConfigSchema) -> RequestFormat: - """Return the action formatted as a request which can be ingested by the PrimAITE simulation.""" - if config.node_name is None or config.folder_name is None: - return ["do_nothing"] - return [ - "network", - "node", - config.node_name, - "file_system", - config.verb, - "folder", - config.folder_name, - ] - -There is no longer a need for a `from_config()` method to be defined within new actions, as this is handled within the base `AbstractAction` class. - -Changes to YAML file. -===================== - -Action identifiers now follow the snake_case naming style, instead of the MACRO_CASE that has been seen previously. Please review any custom YAML files for any issues seen. This should be backwards compatible. + © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK diff --git a/src/primaite/game/agent/actions/__init__.py b/src/primaite/game/agent/actions/__init__.py index 016a09ba..8517ded8 100644 --- a/src/primaite/game/agent/actions/__init__.py +++ b/src/primaite/game/agent/actions/__init__.py @@ -1,10 +1,9 @@ -# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK +# © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK from primaite.game.agent.actions import ( abstract, acl, application, - config, file, folder, host_nic, @@ -13,6 +12,7 @@ from primaite.game.agent.actions import ( node, service, session, + software, ) from primaite.game.agent.actions.manager import ActionManager @@ -20,7 +20,7 @@ __all__ = ( "abstract", "acl", "application", - "config", + "software", "file", "folder", "host_nic", diff --git a/src/primaite/game/agent/actions/abstract.py b/src/primaite/game/agent/actions/abstract.py index 8c332d5e..15c9b4cb 100644 --- a/src/primaite/game/agent/actions/abstract.py +++ b/src/primaite/game/agent/actions/abstract.py @@ -1,4 +1,4 @@ -# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK +# © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK from __future__ import annotations from abc import ABC diff --git a/src/primaite/game/agent/actions/acl.py b/src/primaite/game/agent/actions/acl.py index d2846ddb..6fefeeda 100644 --- a/src/primaite/game/agent/actions/acl.py +++ b/src/primaite/game/agent/actions/acl.py @@ -1,4 +1,4 @@ -# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK +# © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK from __future__ import annotations from ipaddress import IPv4Address diff --git a/src/primaite/game/agent/actions/application.py b/src/primaite/game/agent/actions/application.py index 91e34eae..96609f93 100644 --- a/src/primaite/game/agent/actions/application.py +++ b/src/primaite/game/agent/actions/application.py @@ -1,4 +1,4 @@ -# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK +# © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK from typing import ClassVar from primaite.game.agent.actions.abstract import AbstractAction diff --git a/src/primaite/game/agent/actions/file.py b/src/primaite/game/agent/actions/file.py index b5e47c8a..e5ca1c46 100644 --- a/src/primaite/game/agent/actions/file.py +++ b/src/primaite/game/agent/actions/file.py @@ -1,4 +1,4 @@ -# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK +# © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK from typing import ClassVar from primaite.game.agent.actions.manager import AbstractAction diff --git a/src/primaite/game/agent/actions/folder.py b/src/primaite/game/agent/actions/folder.py index a27ca89b..d1fd5ef1 100644 --- a/src/primaite/game/agent/actions/folder.py +++ b/src/primaite/game/agent/actions/folder.py @@ -1,4 +1,4 @@ -# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK +# © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK from typing import ClassVar from primaite.game.agent.actions.manager import AbstractAction diff --git a/src/primaite/game/agent/actions/host_nic.py b/src/primaite/game/agent/actions/host_nic.py index e2adf7d7..7b290103 100644 --- a/src/primaite/game/agent/actions/host_nic.py +++ b/src/primaite/game/agent/actions/host_nic.py @@ -1,4 +1,4 @@ -# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK +# © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK from typing import ClassVar from primaite.game.agent.actions.manager import AbstractAction diff --git a/src/primaite/game/agent/actions/manager.py b/src/primaite/game/agent/actions/manager.py index a6a4f5a6..b612d9ce 100644 --- a/src/primaite/game/agent/actions/manager.py +++ b/src/primaite/game/agent/actions/manager.py @@ -1,4 +1,4 @@ -# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK +# © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK """yaml example. agents: diff --git a/src/primaite/game/agent/actions/network.py b/src/primaite/game/agent/actions/network.py index 346da9b7..fa1c4451 100644 --- a/src/primaite/game/agent/actions/network.py +++ b/src/primaite/game/agent/actions/network.py @@ -1,4 +1,4 @@ -# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK +# © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK from typing import ClassVar diff --git a/src/primaite/game/agent/actions/node.py b/src/primaite/game/agent/actions/node.py index 480cb8da..c6b74f2e 100644 --- a/src/primaite/game/agent/actions/node.py +++ b/src/primaite/game/agent/actions/node.py @@ -1,4 +1,4 @@ -# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK +# © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK from abc import abstractmethod from typing import ClassVar, List, Optional, Union diff --git a/src/primaite/game/agent/actions/service.py b/src/primaite/game/agent/actions/service.py index 7ccffb0a..fa47ffb1 100644 --- a/src/primaite/game/agent/actions/service.py +++ b/src/primaite/game/agent/actions/service.py @@ -1,4 +1,4 @@ -# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK +# © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK from typing import ClassVar from primaite.game.agent.actions.manager import AbstractAction diff --git a/src/primaite/game/agent/actions/session.py b/src/primaite/game/agent/actions/session.py index a0805a49..1191987b 100644 --- a/src/primaite/game/agent/actions/session.py +++ b/src/primaite/game/agent/actions/session.py @@ -1,4 +1,4 @@ -# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK +# © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK from abc import abstractmethod from primaite.game.agent.actions.manager import AbstractAction diff --git a/src/primaite/game/agent/actions/config.py b/src/primaite/game/agent/actions/software.py similarity index 99% rename from src/primaite/game/agent/actions/config.py rename to src/primaite/game/agent/actions/software.py index 050e9b94..760e8dfa 100644 --- a/src/primaite/game/agent/actions/config.py +++ b/src/primaite/game/agent/actions/software.py @@ -1,4 +1,4 @@ -# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK +# © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK from typing import List, Optional, Union diff --git a/src/primaite/game/agent/rewards.py b/src/primaite/game/agent/rewards.py index f065d888..8f0bd24b 100644 --- a/src/primaite/game/agent/rewards.py +++ b/src/primaite/game/agent/rewards.py @@ -381,15 +381,16 @@ class ActionPenalty(AbstractReward, identifier="ACTION_PENALTY"): class ConfigSchema(AbstractReward.ConfigSchema): """Config schema for ActionPenalty. + :param action_penalty: Reward to give agents for taking any action except do_nothing :type action_penalty: float :param do_nothing_penalty: Reward to give agent for taking the do_nothing action :type do_nothing_penalty: float """ + action_penalty: float = -1.0 do_nothing_penalty: float = 0.0 - def calculate(self, state: Dict, last_action_response: "AgentHistoryItem") -> float: """Calculate the penalty to be applied. diff --git a/tests/integration_tests/game_layer/actions/test_configure_actions.py b/tests/integration_tests/game_layer/actions/test_configure_actions.py index 8c97573a..338bd049 100644 --- a/tests/integration_tests/game_layer/actions/test_configure_actions.py +++ b/tests/integration_tests/game_layer/actions/test_configure_actions.py @@ -4,7 +4,7 @@ from ipaddress import IPv4Address import pytest from pydantic import ValidationError -from primaite.game.agent.actions.config import ( +from primaite.game.agent.actions.software import ( ConfigureDatabaseClientAction, ConfigureDoSBotAction, ConfigureRansomwareScriptAction,