diff --git a/docs/source/about.rst b/docs/source/about.rst index 3f905933..782103d6 100644 --- a/docs/source/about.rst +++ b/docs/source/about.rst @@ -41,11 +41,11 @@ The game layer is built on top of the simulator and it consumes the simulation a * Hardware State (ON, OFF, RESETTING, SHUTTING_DOWN, BOOTING - enumeration) Active Nodes also have the following attributes (Class: Active Node): * IP Address - * Software State (GOOD, PATCHING, COMPROMISED - enumeration) + * Software State (GOOD, FIXING, COMPROMISED - enumeration) * File System State (GOOD, CORRUPT, DESTROYED, REPAIRING, RESTORING - enumeration) Service Nodes also have the following attributes (Class: Service Node): * List of Services (where service is composed of service name and port). There is no theoretical limit on the number of services that can be modelled. Services and protocols are currently intrinsically linked (i.e. a service is an application on a node transmitting traffic of this protocol type) - * Service state (GOOD, PATCHING, COMPROMISED, OVERWHELMED - enumeration) + * Service state (GOOD, FIXING, COMPROMISED, OVERWHELMED - enumeration) Passive Nodes are currently not used (but may be employed for non IP-based components such as machinery actuators in future releases). **Links** Links are modelled both as network edges (networkx) and as Python classes, in order to extend their functionality. Links include the following attributes: @@ -70,8 +70,8 @@ The game layer is built on top of the simulator and it consumes the simulation a * Running status (i.e. on / off) The application of green agent IERs between a source and destination follows a number of rules. Specifically: 1. Does the current simulation time step fall between IER start and end step - 2. Is the source node operational (both physically and at an O/S level), and is the service (protocol / port) associated with the IER (a) present on this node, and (b) in an operational state (i.e. not PATCHING) - 3. Is the destination node operational (both physically and at an O/S level), and is the service (protocol / port) associated with the IER (a) present on this node, and (b) in an operational state (i.e. not PATCHING) + 2. Is the source node operational (both physically and at an O/S level), and is the service (protocol / port) associated with the IER (a) present on this node, and (b) in an operational state (i.e. not FIXING) + 3. Is the destination node operational (both physically and at an O/S level), and is the service (protocol / port) associated with the IER (a) present on this node, and (b) in an operational state (i.e. not FIXING) 4. Are there any Access Control List rules in place that prevent the application of this IER 5. Are all switches in the (OSPF) path between source and destination operational (both physically and at an O/S level) For red agent IERs, the application of IERs between a source and destination follows a number of subtly different rules. Specifically: @@ -95,7 +95,7 @@ The game layer is built on top of the simulator and it consumes the simulation a * Active Nodes and Service Nodes: * Software State: * GOOD - * PATCHING - when a status of patching is entered, the node will automatically exit this state after a number of steps (as defined by the osPatchingDuration configuration item) after which it returns to a GOOD state + * FIXING - when a status of FIXING is entered, the node will automatically exit this state after a number of steps (as defined by the osFIXINGDuration configuration item) after which it returns to a GOOD state * COMPROMISED * File System State: * GOOD @@ -106,7 +106,7 @@ The game layer is built on top of the simulator and it consumes the simulation a * Service Nodes only: * Service State (for any associated service): * GOOD - * PATCHING - when a status of patching is entered, the service will automatically exit this state after a number of steps (as defined by the servicePatchingDuration configuration item) after which it returns to a GOOD state + * FIXING - when a status of FIXING is entered, the service will automatically exit this state after a number of steps (as defined by the serviceFIXINGDuration configuration item) after which it returns to a GOOD state * COMPROMISED * OVERWHELMED Red agent pattern-of-life has an additional feature not found in the green pattern-of-life. This is the ability to influence the state of the attributes of a node via a number of different conditions: @@ -211,8 +211,8 @@ The game layer is built on top of the simulator and it consumes the simulation a Hardware State (1=ON, 2=OFF, 3=RESETTING, 4=SHUTTING_DOWN, 5=BOOTING) Operating System State (0=none, 1=GOOD, 2=PATCHING, 3=COMPROMISED) File System State (0=none, 1=GOOD, 2=CORRUPT, 3=DESTROYED, 4=REPAIRING, 5=RESTORING) - Service1/Protocol1 state (0=none, 1=GOOD, 2=PATCHING, 3=COMPROMISED) - Service2/Protocol2 state (0=none, 1=GOOD, 2=PATCHING, 3=COMPROMISED) + Service1/Protocol1 state (0=none, 1=GOOD, 2=FIXING, 3=COMPROMISED) + Service2/Protocol2 state (0=none, 1=GOOD, 2=FIXING, 3=COMPROMISED) ] (Note that each service available in the network is provided as a column, although not all nodes may utilise all services) For the links, the following statuses are represented: @@ -241,8 +241,8 @@ The game layer is built on top of the simulator and it consumes the simulation a hardware_state (0=none, 1=ON, 2=OFF, 3=RESETTING, 4=SHUTTING_DOWN, 5=BOOTING) software_state (0=none, 1=GOOD, 2=PATCHING, 3=COMPROMISED) file_system_state (0=none, 1=GOOD, 2=CORRUPT, 3=DESTROYED, 4=REPAIRING, 5=RESTORING) - service1_state (0=none, 1=GOOD, 2=PATCHING, 3=COMPROMISED) - service2_state (0=none, 1=GOOD, 2=PATCHING, 3=COMPROMISED) + service1_state (0=none, 1=GOOD, 2=FIXING, 3=COMPROMISED) + service2_state (0=none, 1=GOOD, 2=FIXING, 3=COMPROMISED) ] In a network with three nodes and two services, the full observation space would have 15 elements. It can be written with ``gym`` notation to indicate the number of discrete options for each of the elements of the observation space. For example: .. code-block:: @@ -278,7 +278,7 @@ The game layer is built on top of the simulator and it consumes the simulation a 3. Any (Agent can take both node-based and ACL-based actions) The choice of action space used during a training session is determined in the config_[name].yaml file. **Node-Based** - The agent is able to influence the status of nodes by switching them off, resetting, or patching operating systems and services. In this instance, the action space is a Gymnasium spaces.Discrete type, as follows: + The agent is able to influence the status of nodes by switching them off, resetting, or FIXING operating systems and services. In this instance, the action space is a Gymnasium spaces.Discrete type, as follows: * Dictionary item {... ,1: [x1, x2, x3,x4] ...} The placeholders inside the list under the key '1' mean the following: * [0, num nodes] - Node ID (0 = nothing, node ID) diff --git a/src/primaite/notebooks/Data-Manipulation-E2E-Demonstration.ipynb b/src/primaite/notebooks/Data-Manipulation-E2E-Demonstration.ipynb index 7ec58b2c..ebe0f329 100644 --- a/src/primaite/notebooks/Data-Manipulation-E2E-Demonstration.ipynb +++ b/src/primaite/notebooks/Data-Manipulation-E2E-Demonstration.ipynb @@ -520,7 +520,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "The patching takes two steps, so the reward hasn't changed yet. Let's do nothing for another timestep, the reward should improve.\n", + "The fixing takes two steps, so the reward hasn't changed yet. Let's do nothing for another timestep, the reward should improve.\n", "\n", "The reward will increase slightly as soon as the file finishes restoring. Then, the reward will increase to 1 when both green agents make successful requests.\n", "\n", diff --git a/src/primaite/simulator/system/services/database/database_service.py b/src/primaite/simulator/system/services/database/database_service.py index 411359a2..541a15c2 100644 --- a/src/primaite/simulator/system/services/database/database_service.py +++ b/src/primaite/simulator/system/services/database/database_service.py @@ -305,7 +305,7 @@ class DatabaseService(Service): return super().apply_timestep(timestep) def _update_fix_status(self) -> None: - """Perform a database restore when the patching countdown is finished.""" + """Perform a database restore when the FIXING countdown is finished.""" super()._update_fix_status() if self._fixing_countdown is None: self.restore_backup() diff --git a/src/primaite/simulator/system/software.py b/src/primaite/simulator/system/software.py index 9b54f802..ab60adde 100644 --- a/src/primaite/simulator/system/software.py +++ b/src/primaite/simulator/system/software.py @@ -43,8 +43,8 @@ class SoftwareHealthState(Enum): "Unused state." GOOD = 1 "The software is in a good and healthy condition." - PATCHING = 2 - "The software is undergoing patching or updates." + FIXING = 2 + "The software is undergoing FIXING or updates." COMPROMISED = 3 "The software's security has been compromised." OVERWHELMED = 4 @@ -198,7 +198,7 @@ class Software(SimComponent): """Perform a fix on the software.""" if self.health_state_actual in (SoftwareHealthState.COMPROMISED, SoftwareHealthState.GOOD): self._fixing_countdown = self.fixing_duration - self.set_health_state(SoftwareHealthState.PATCHING) + self.set_health_state(SoftwareHealthState.FIXING) return True return False @@ -221,7 +221,7 @@ class Software(SimComponent): :param timestep: The current timestep of the simulation. """ super().apply_timestep(timestep) - if self.health_state_actual == SoftwareHealthState.PATCHING: + if self.health_state_actual == SoftwareHealthState.FIXING: self._update_fix_status() diff --git a/tests/integration_tests/game_layer/test_actions.py b/tests/integration_tests/game_layer/test_actions.py index 5aa93e27..b3a52cd8 100644 --- a/tests/integration_tests/game_layer/test_actions.py +++ b/tests/integration_tests/game_layer/test_actions.py @@ -69,7 +69,7 @@ def test_node_service_fix_integration(game_and_agent: Tuple[PrimaiteGame, ProxyA """ Test that the NodeServiceFixAction can form a request and that it is accepted by the simulation. - When you initiate a patch action, the software health state turns to PATCHING, then after a few steps, it goes + When you initiate a patch action, the software health state turns to FIXING, then after a few steps, it goes to GOOD. """ game, agent = game_and_agent @@ -83,8 +83,8 @@ def test_node_service_fix_integration(game_and_agent: Tuple[PrimaiteGame, ProxyA agent.store_action(action) game.step() - # 3: Check that the service is now in the patching state - assert svc.health_state_actual == SoftwareHealthState.PATCHING + # 3: Check that the service is now in the FIXING state + assert svc.health_state_actual == SoftwareHealthState.FIXING # 4: perform a few do-nothing steps and check that the service is now in the good state action = ("DONOTHING", {}) @@ -413,7 +413,7 @@ def test_node_application_scan_integration(game_and_agent: Tuple[PrimaiteGame, P def test_node_application_fix_integration(game_and_agent: Tuple[PrimaiteGame, ProxyAgent]): """Test that the NodeApplicationFixAction can form a request and that it is accepted by the simulation. - When you initiate a fix action, the software health state turns to PATCHING, then after a few steps, it goes + When you initiate a fix action, the software health state turns to FIXING, then after a few steps, it goes to GOOD.""" game, agent = game_and_agent @@ -428,8 +428,8 @@ def test_node_application_fix_integration(game_and_agent: Tuple[PrimaiteGame, Pr agent.store_action(action) game.step() - # 3: Check that the application is now in the patching state - assert browser.health_state_actual == SoftwareHealthState.PATCHING + # 3: Check that the application is now in the FIXING state + assert browser.health_state_actual == SoftwareHealthState.FIXING # 4: perform a few do-nothing steps and check that the application is now in the good state action = ("DONOTHING", {}) diff --git a/tests/unit_tests/_primaite/_simulator/_system/_applications/test_applications.py b/tests/unit_tests/_primaite/_simulator/_system/_applications/test_applications.py index fbdd9bef..90c3f303 100644 --- a/tests/unit_tests/_primaite/_simulator/_system/_applications/test_applications.py +++ b/tests/unit_tests/_primaite/_simulator/_system/_applications/test_applications.py @@ -47,4 +47,4 @@ def test_application_describe_states(application): assert SoftwareHealthState.COMPROMISED.value == application.describe_state().get("health_state_actual") application.fix() - assert SoftwareHealthState.PATCHING.value == application.describe_state().get("health_state_actual") + assert SoftwareHealthState.FIXING.value == application.describe_state().get("health_state_actual") diff --git a/tests/unit_tests/_primaite/_simulator/_system/_services/test_service_actions.py b/tests/unit_tests/_primaite/_simulator/_system/_services/test_service_actions.py index dd2d7752..edc111e3 100644 --- a/tests/unit_tests/_primaite/_simulator/_system/_services/test_service_actions.py +++ b/tests/unit_tests/_primaite/_simulator/_system/_services/test_service_actions.py @@ -86,8 +86,8 @@ def test_service_fix(service): assert service.health_state_actual == SoftwareHealthState.GOOD service.apply_request(["fix"]) - assert service.health_state_actual == SoftwareHealthState.PATCHING + assert service.health_state_actual == SoftwareHealthState.FIXING service.apply_timestep(1) - assert service.health_state_actual == SoftwareHealthState.PATCHING + assert service.health_state_actual == SoftwareHealthState.FIXING service.apply_timestep(2) assert service.health_state_actual == SoftwareHealthState.GOOD diff --git a/tests/unit_tests/_primaite/_simulator/_system/_services/test_services.py b/tests/unit_tests/_primaite/_simulator/_system/_services/test_services.py index 59d9499b..4deeef74 100644 --- a/tests/unit_tests/_primaite/_simulator/_system/_services/test_services.py +++ b/tests/unit_tests/_primaite/_simulator/_system/_services/test_services.py @@ -93,7 +93,7 @@ def test_restart_compromised(service): """ Service should be compromised even after reset. - Only way to remove compromised status is via patching. + Only way to remove compromised status is via FIXING. """ timestep = 0 @@ -143,7 +143,7 @@ def test_service_fixing(service): service.set_health_state(SoftwareHealthState.COMPROMISED) service.fix() - assert service.health_state_actual == SoftwareHealthState.PATCHING + assert service.health_state_actual == SoftwareHealthState.FIXING for i in range(service.fixing_duration + 1): service.apply_timestep(i)