Merged PR 480: merged 3.2.0 into main for git history alignment

merged 3.2.0 into main for git history alignment

Related work items: #2438, #2620, #2623, #2641, #2656, #2688, #2697, #2700, #2701, #2702, #2705, #2716, #2725, #2734, #2739, #2740, #2745, #2747, #2757

.azure/azure-ci-build-pipeline.yaml

@@ -107,11 +107,39 @@ stages:
               coverage html -d htmlcov -i
             displayName: 'Run tests and code coverage'
 
+          # Run the notebooks
+          - script: |
+              pytest --nbmake -n=auto src/primaite/notebooks --junit-xml=./notebook-tests/notebooks.xml
+              notebooks_exit_code=$?
+              pytest --nbmake -n=auto src/primaite/simulator/_package_data --junit-xml=./notebook-tests/package-notebooks.xml
+              package_notebooks_exit_code=$?
+              # Fail step if either of these do not have exit code 0
+              if [ $notebooks_exit_code -ne 0 ] || [ $package_notebooks_exit_code -ne 0 ]; then
+                exit 1
+              fi
+            displayName: 'Run notebooks on Linux and macOS'
+            condition: or(eq(variables['Agent.OS'], 'Linux'), eq(variables['Agent.OS'], 'Darwin'))
+
+          # Run notebooks
+          - script: |
+              pytest --nbmake -n=auto src/primaite/notebooks --junit-xml=./notebook-tests/notebooks.xml
+              set notebooks_exit_code=%ERRORLEVEL%
+              pytest --nbmake -n=auto src/primaite/simulator/_package_data --junit-xml=./notebook-tests/package-notebooks.xml
+              set package_notebooks_exit_code=%ERRORLEVEL%
+              rem Fail step if either of these do not have exit code 0
+              if %notebooks_exit_code% NEQ 0 exit /b 1
+              if %package_notebooks_exit_code% NEQ 0 exit /b 1
+            displayName: 'Run notebooks on Windows'
+            condition: eq(variables['Agent.OS'], 'Windows_NT')
+
           - task: PublishTestResults@2
             condition: succeededOrFailed()
+            displayName: 'Publish Test Results'
             inputs:
               testRunner: JUnit
-              testResultsFiles: 'junit/**.xml'
+              testResultsFiles: |
+                'junit/**.xml'
+                'notebook-tests/**.xml'
               testRunTitle: 'Publish test results'
               failTaskOnFailedTests: true
 

.gitignore

@@ -54,6 +54,7 @@ cover/
 tests/assets/**/*.png
 tests/assets/**/tensorboard_logs/
 tests/assets/**/checkpoints/
+notebook-tests/*.xml
 
 # Translations
 *.mo

CHANGELOG.md

@@ -2,9 +2,31 @@
 
 All notable changes to this project will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+### Added
+
+-   **show_bandwidth_load Function**: Displays current bandwidth load for each frequency in the airspace.
+-   **Bandwidth Tracking**: Tracks data transmission across each frequency.
+-   **New Tests**: Added to validate the respect of bandwidth capacities and the correct parsing of airspace configurations from YAML files.
+-   **New Logging**: Added a new agent behaviour log which are more human friendly than agent history. These Logs are found in session log directory and can be enabled in the I/O settings in a yaml configuration file.
+
+### Changed
+
+-   **NetworkInterface Speed Type**: The `speed` attribute of `NetworkInterface` has been changed from `int` to `float`.
+-   **Transmission Feasibility Check**: Updated `_can_transmit` function in `Link` to account for current load and total bandwidth capacity, ensuring transmissions do not exceed limits.
+-   **Frame Size Details**: Frame `size` attribute now includes both core size and payload size in bytes.
+-   **Transmission Blocking**: Enhanced `AirSpace` logic to block transmissions that would exceed the available capacity.
+
+### Fixed
+
+-   **Transmission Permission Logic**: Corrected the logic in `can_transmit_frame` to accurately prevent overloads by checking if the transmission of a frame stays within allowable bandwidth limits after considering current load.
+
+
+[//]: # (This file needs tidying up between 2.0.0 and this line as it hasn't been segmented into 3.0.0 and 3.1.0 and isn't compliant with https://keepachangelog.com/en/1.1.0/)
+
 ## 3.0.0b9
 - Removed deprecated `PrimaiteSession` class.
 - Added ability to set log levels via configuration.
@@ -26,8 +48,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Refactored all air-space usage to that a new instance of AirSpace is created for each instance of Network. This 1:1 relationship between network and airspace will allow parallelization.
 - Added notebook to demonstrate use of SubprocVecEnv from SB3 to vectorise environments to speed up training.
 
-
-
 ## [Unreleased]
 - Made requests fail to reach their target if the node is off
 - Added responses to requests

benchmark/report.py

@@ -17,8 +17,6 @@ PLOT_CONFIG = {
     "size": {"auto_size": False, "width": 1500, "height": 900},
     "template": "plotly_white",
     "range_slider": False,
-    "av_s_per_100_steps_10_nodes_benchmark_threshold": 5,
-    "benchmark_line_color": "grey",
 }
 
 
@@ -229,10 +227,7 @@ def _plot_av_s_per_100_steps_10_nodes(
     """
     Creates a bar chart visualising the performance of each version of PrimAITE.
 
-    Performance is based on the average training time per 100 steps on 10 nodes. The function also includes a benchmark
-    line indicating the target maximum time.
-
-    Versions that perform under this time are marked in green, and those over are marked in red.
+    Performance is based on the average training time per 100 steps on 10 nodes.
 
     :param version_times_dict: A dictionary with software versions as keys and average times as values.
     :return: A Plotly figure object representing the bar chart of the performance metrics.
@@ -256,7 +251,6 @@ def _plot_av_s_per_100_steps_10_nodes(
     versions = sorted(list(version_times_dict.keys()))
     times = [version_times_dict[version] for version in versions]
     av_s_per_100_steps_10_nodes_benchmark_threshold = PLOT_CONFIG["av_s_per_100_steps_10_nodes_benchmark_threshold"]
-    benchmark_line_color = PLOT_CONFIG["benchmark_line_color"]
 
     # Calculate the appropriate maximum y-axis value
     max_y_axis_value = max(max(times), av_s_per_100_steps_10_nodes_benchmark_threshold) + 1
@@ -265,28 +259,11 @@ def _plot_av_s_per_100_steps_10_nodes(
         go.Bar(
             x=versions,
             y=times,
-            marker_color=[
-                "green" if time < av_s_per_100_steps_10_nodes_benchmark_threshold else "red" for time in times
-            ],
             text=times,
             textposition="auto",
         )
     )
 
-    # Add a horizontal line for the benchmark
-    fig.add_shape(
-        type="line",
-        x0=-0.5,  # start slightly before the first bar
-        x1=len(versions) - 0.5,  # end slightly after the last bar
-        y0=av_s_per_100_steps_10_nodes_benchmark_threshold,
-        y1=av_s_per_100_steps_10_nodes_benchmark_threshold,
-        line=dict(
-            color=benchmark_line_color,
-            width=2,
-            dash="dot",
-        ),
-    )
-
     fig.update_layout(
         xaxis_title="PrimAITE Version",
         yaxis_title="Avg Time per 100 Steps on 10 Nodes (seconds)",

benchmark/results/v3/v3.1.0/session_metadata/1.json

@@ -1006,4 +1006,4 @@
         "999": 112.00000000000009,
         "1000": 102.55000000000008
     }
-}
+}

benchmark/results/v3/v3.1.0/session_metadata/2.json

@@ -1006,4 +1006,4 @@
         "999": 110.30000000000007,
         "1000": 118.05000000000011
     }
-}
+}

benchmark/results/v3/v3.1.0/session_metadata/3.json

@@ -1006,4 +1006,4 @@
         "999": 118.44999999999996,
         "1000": 108.20000000000029
     }
-}
+}

benchmark/results/v3/v3.1.0/session_metadata/4.json

@@ -1006,4 +1006,4 @@
         "999": 99.50000000000009,
         "1000": 98.70000000000006
     }
-}
+}

benchmark/results/v3/v3.1.0/session_metadata/5.json

@@ -1006,4 +1006,4 @@
         "999": 118.45000000000007,
         "1000": 116.3000000000001
     }
-}
+}

benchmark/results/v3/v3.1.0/v3.1.0_benchmark_metadata.json

@@ -7441,4 +7441,4 @@
             }
         }
     }
-}
+}

benchmark/results/v3/v3.2.0/PrimAITE v3.2.0 Benchmark Report.md

@@ -0,0 +1,38 @@
+# PrimAITE v3.2.0 Learning Benchmark
+## PrimAITE Dev Team
+### 2024-07-21
+
+---
+## 1 Introduction
+PrimAITE v3.2.0 was benchmarked automatically upon release. Learning rate metrics were captured to be referenced during system-level testing and user acceptance testing (UAT).
+The benchmarking process consists of running 5 training session using the same config file. Each session trains an agent for 1000 episodes, with each episode consisting of 128 steps.
+The total reward per episode from each session is captured. This is then used to calculate an caverage total reward per episode from the 5 individual sessions for smoothing. Finally, a 25-widow rolling average of the average total reward per session is calculated for further smoothing.
+## 2 System Information
+### 2.1 Python
+**Version:** 3.10.14 (main, Apr  6 2024, 18:45:05) [GCC 9.4.0]
+### 2.2 System
+- **OS:** Linux
+- **OS Version:** #76~20.04.1-Ubuntu SMP Thu Jun 13 18:00:23 UTC 2024
+- **Machine:** x86_64
+- **Processor:** x86_64
+### 2.3 CPU
+- **Physical Cores:** 2
+- **Total Cores:** 4
+- **Max Frequency:** 0.00Mhz
+### 2.4 Memory
+- **Total:** 15.62GB
+- **Swap Total:** 0.00B
+## 3 Stats
+- **Total Sessions:** 5
+- **Total Episodes:** 5005
+- **Total Steps:** 640000
+- **Av Session Duration (s):** 1691.5034
+- **Av Step Duration (s):** 0.0529
+- **Av Duration per 100 Steps per 10 Nodes (s):** 5.2859
+## 4 Graphs
+### 4.1 v3.2.0 Learning Benchmark Plot
+![PrimAITE 3.2.0 Learning Benchmark Plot](PrimAITE v3.2.0 Learning Benchmark.png)
+### 4.2 Learning Benchmark of Minor and Bugfix Releases for Major Version 3
+![Learning Benchmark of Minor and Bugfix Releases for Major Version 3](PrimAITE Learning Benchmark of Minor and Bugfix Releases for Major Version 3.png)
+### 4.3 Performance of Minor and Bugfix Releases for Major Version 3
+![Performance of Minor and Bugfix Releases for Major Version 3](PrimAITE Performance of Minor and Bugfix Releases for Major Version 3.png)

docs/index.rst

@@ -8,6 +8,46 @@ Welcome to PrimAITE's documentation
 What is PrimAITE?
 -----------------
 
+.. toctree::
+   :maxdepth: 8
+   :caption: About PrimAITE:
+   :hidden:
+
+   source/about
+   source/dependencies
+   source/glossary
+
+.. toctree::
+   :caption: Usage:
+   :hidden:
+
+   source/getting_started
+   source/game_layer
+   source/simulation
+   source/config
+   source/customising_scenarios
+   source/varying_config_files
+   source/environment
+   source/action_masking
+
+.. toctree::
+   :caption: Notebooks:
+   :hidden:
+
+   source/example_notebooks
+   source/notebooks/executed_notebooks
+
+.. toctree::
+   :caption: Developer information:
+   :hidden:
+
+   source/developer_tools
+   source/state_system
+   source/request_system
+   PrimAITE API <source/_autosummary/primaite>
+   PrimAITE Tests <source/_autosummary/tests>
+
+
 Overview
 ^^^^^^^^
 
@@ -36,107 +76,6 @@ PrimAITE incorporates the following features:
 - A PCAP service is seamlessly integrated within the simulation, automatically capturing and logging frames for both
   inbound and outbound traffic at the network interface level. This automatic functionality, combined with the ability
   to separate traffic directions, significantly enhances network analysis and troubleshooting capabilities;
-- Agent action logs provide a description of every action taken by each agent during the episode. This includes timestep, action, parameters, request and response, for all Blue agent activity, which is aligned with the Track 2 Common Action / Observation Space (CAOS) format. Action logs also details of all scripted / stochastic red / green agent actions;
+- Agent action logs provide a description of every action taken by each agent during the episode. This includes timestep, action, parameters, request and response, for all Blue agent activity, which is aligned with the Track 2 Common Action / Observation Space (CAOS) format. Action logs also detail all scripted / stochastic red / green agent actions;
 - Environment ground truth is provided at every timestep, providing a full description of the environment’s true state;
 - Alignment with CAOS provides the ability to transfer agents between CAOS compliant environments.
-
-Architecture
-^^^^^^^^^^^^
-
-PrimAITE is a Python application and will operate on multiple Operating Systems (Windows, Linux and Mac);
-a comprehensive installation and user guide is provided with each release to support its usage.
-
-Configuration of PrimAITE is achieved via included YAML files which support full control over the network / system laydown being modelled, background pattern of life, adversarial (red agent) behaviour, and step and episode count.
-A Simulation Controller layer manages the overall running of the simulation, keeping track of all low-level objects.
-
-It is agnostic to the number of agents, their action / observation spaces, and the RL library being used.
-
-It presents a public API providing a method for describing the current state of the simulation, a method that accepts action requests and provides responses, and a method that triggers a timestep advancement.
-The Game Layer converts the simulation into a playable game for the agent(s).
-
-It translates between simulation state and Gymnasium.Spaces to pass action / observation data between the agent(s) and the simulation. It is responsible for calculating rewards, managing Multi-Agent RL (MARL) action turns, and via a single agent interface can interact with Blue, Red and Green agents.
-
-Agents can either generate their own scripted behaviour or accept input behaviour from an RL agent.
-
-Finally, a Gymnasium / Ray RLlib Environment Layer forwards requests to the Game Layer as the agent sends them. This layer also manages most of the I/O, such as reading in the configuration files and saving agent logs.
-
-.. image:: ../../_static/primAITE_architecture.png
-    :width: 500
-    :align: center
-
-
-Training & Evaluation Capability
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-PrimAITE provides a training and evaluation capability to AI agents in the context of cyber-attack, via its Gymnasium / Ray RLlib compliant interface.
-
-Scenarios can be constructed to reflect network / system laydowns consisting of any configuration of nodes (e.g., PCs, servers etc.) and the networking equipment and links between them.
-
-All nodes can be configured to contain applications, services, folders and files (and their status).
-
-Traffic flows between services and applications as directed by an ‘execution definition,’ with the traffic flow on the network governed by the network equipment (switches, routers and firewalls) and the ACL rules and routing tables they employ.
-
-Highlights of PrimAITE’s training and evaluation capability are:
-
-- The scenario is not bound to a representation of any platform, system, or technology;
-- Fully configurable (network / system laydown, green pattern-of-life, red personas, reward function, ACL rules for each device, number of episodes / steps, action / observation space) and repeatable to suit the requirements of AI agents;
-- Can integrate with any Gymnasium / Ray RLlib compliant AI agent .
-
-
-PrimAITE provides a number of use cases (network and red/green action configurations) by default which the user is able to extend and modify as required.
-
-What is PrimAITE built with
----------------------------
-
-* `Gymnasium <https://gymnasium.farama.org/>`_ is used as the basis for AI blue agent interaction with the PrimAITE environment
-* `Networkx <https://github.com/networkx/networkx>`_ is used as the underlying data structure used for the PrimAITE environment
-* `Stable Baselines 3 <https://github.com/DLR-RM/stable-baselines3>`_ is used as a default source of RL algorithms (although PrimAITE is not limited to SB3 agents)
-* `Ray RLlib <https://github.com/ray-project/ray>`_ is used as an additional source of RL algorithms
-* `Typer <https://github.com/tiangolo/typer>`_ is used for building CLIs (Command Line Interface applications)
-* `Jupyterlab <https://github.com/jupyterlab/jupyterlab>`_ is used as an extensible environment for interactive and reproducible computing, based on the Jupyter Notebook Architecture
-* `Platformdirs <https://github.com/platformdirs/platformdirs>`_ is used for finding the right location to store user data and configuration but varies per platform
-* `Plotly <https://github.com/plotly/plotly.py>`_ is used for building high level charts
-
-
-Getting Started with PrimAITE
------------------------------
-
-Head over to the :ref:`getting-started` page to install and setup PrimAITE!
-
-.. toctree::
-   :maxdepth: 8
-   :caption: About PrimAITE:
-   :hidden:
-
-   source/about
-   source/dependencies
-   source/glossary
-
-.. toctree::
-   :caption: Usage:
-   :hidden:
-
-   source/getting_started
-   source/simulation
-   source/game_layer
-   source/config
-   source/environment
-   source/customising_scenarios
-   source/varying_config_files
-
-.. toctree::
-   :caption: Notebooks:
-   :hidden:
-
-   source/example_notebooks
-   source/notebooks/executed_notebooks
-
-.. toctree::
-   :caption: Developer information:
-   :hidden:
-
-   source/developer_tools
-   source/state_system
-   source/request_system
-   PrimAITE API <source/_autosummary/primaite>
-   PrimAITE Tests <source/_autosummary/tests>

docs/source/about.rst

@@ -7,27 +7,68 @@
 About PrimAITE
 ==============
 
-PrimAITE is a simulation environment for training agents to protect a computer network from cyber attacks.
+Architecture
+^^^^^^^^^^^^
 
-Features
-********
+PrimAITE is a Python application and will operate on multiple Operating Systems (Windows, Linux and Mac);
+a comprehensive installation and user guide is provided with each release to support its usage.
 
-PrimAITE provides the following features:
+Configuration of PrimAITE is achieved via included YAML files which support full control over the network / system laydown being modelled, background pattern of life, adversarial (red agent) behaviour, and step and episode count.
+A Simulation Controller layer manages the overall running of the simulation, keeping track of all low-level objects.
 
-* A flexible system for defining network layouts and host configurations
-* Highly configurable network hosts, including definition of software, file system, and network interfaces,
-* Realistic network traffic simulation, including address and sending packets via internet protocols like TCP, UDP, ICMP, etc.
-* Routers with traffic routing and firewall capabilities
-* Simulation of customisable deterministic agents
-* Support for multiple agents, each having their own customisable observation space, action space, and reward function definition.
+It is agnostic to the number of agents, their action / observation spaces, and the RL library being used.
+
+It presents a public API providing a method for describing the current state of the simulation, a method that accepts action requests and provides responses, and a method that triggers a timestep advancement.
+The Game Layer converts the simulation into a playable game for the agent(s).
+
+It translates between simulation state and Gymnasium.Spaces to pass action / observation data between the agent(s) and the simulation. It is responsible for calculating rewards, managing Multi-Agent RL (MARL) action turns, and via a single agent interface can interact with Blue, Red and Green agents.
+
+Agents can either generate their own scripted behaviour or accept input behaviour from an RL agent.
+
+Finally, a Gymnasium / Ray RLlib Environment Layer forwards requests to the Game Layer as the agent sends them. This layer also manages most of the I/O, such as reading in the configuration files and saving agent logs.
+
+.. image:: ../../_static/primAITE_architecture.png
+    :width: 500
+    :align: center
 
 
-Structure
-*********
+Training & Evaluation Capability
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-PrimAITE consists of a simulator and a 'game' layer that allows agents to interact with the simulator. The simulator is built in a modular way where each component such as network hosts, links, networking devices, softwares, etc. are implemented as instances of a base class, meaning they all support the same interface. This allows for standardised configuration using either the Python API or YAML files.
-The game layer is built on top of the simulator and it consumes the simulation action/state interface to allow agents to interact with the simulator. The game layer is also responsible for defining the reward function and observation space for the agents.
+PrimAITE provides a training and evaluation capability to AI agents in the context of cyber-attack, via its Gymnasium / Ray RLlib compliant interface.
 
+Scenarios can be constructed to reflect network / system laydowns consisting of any configuration of nodes (e.g., PCs, servers etc.) and the networking equipment and links between them.
+
+All nodes can be configured to contain applications, services, folders and files (and their status).
+
+Traffic flows between services and applications as directed by an ‘execution definition’, with the traffic flow on the network governed by the network equipment (switches, routers and firewalls) and the ACL rules and routing tables they employ.
+
+Highlights of PrimAITE’s training and evaluation capability are:
+
+- The scenario is not bound to a representation of any platform, system, or technology;
+- Fully configurable (network / system laydown, green pattern-of-life, red personas, reward function, ACL rules for each device, number of episodes / steps, action / observation space) and repeatable to suit the requirements of AI agents;
+- Can integrate with any Gymnasium / Ray RLlib compliant AI agent.
+
+
+PrimAITE provides a number of use cases (network and red/green action configurations) by default which the user is able to extend and modify as required.
+
+What is PrimAITE built with
+---------------------------
+
+* `Gymnasium <https://gymnasium.farama.org/>`_ is used as the basis for AI blue agent interaction with the PrimAITE environment
+* `Networkx <https://github.com/networkx/networkx>`_ is used as the underlying data structure used for the PrimAITE environment
+* `Stable Baselines 3 <https://github.com/DLR-RM/stable-baselines3>`_ is used as a default source of RL algorithms (although PrimAITE is not limited to SB3 agents)
+* `Ray RLlib <https://github.com/ray-project/ray>`_ is used as an additional source of RL algorithms
+* `Typer <https://github.com/tiangolo/typer>`_ is used for building CLIs (Command Line Interface applications)
+* `Jupyterlab <https://github.com/jupyterlab/jupyterlab>`_ is used as an extensible environment for interactive and reproducible computing, based on the Jupyter Notebook Architecture
+* `Platformdirs <https://github.com/platformdirs/platformdirs>`_ is used for finding the right location to store user data and configuration but varies per platform
+* `Plotly <https://github.com/plotly/plotly.py>`_ is used for building high level charts
+
+
+Getting Started with PrimAITE
+-----------------------------
+
+Head over to the :ref:`getting-started` page to install and setup PrimAITE!
 
 ..
   Architecture - Nodes and Links

docs/source/action_masking.rst

@@ -0,0 +1,129 @@
+.. only:: comment
+
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+
+Action Masking
+**************
+The PrimAITE simulation is able to provide action masks in the environment output. These action masks let the agents know
+about which actions are invalid based on the current environment state. For instance, it's not possible to install
+software on a node that is turned off. Therefore, if an agent has a NODE_SOFTWARE_INSTALL in it's action map for that node,
+the action mask will show `0` in the corresponding entry.
+
+Configuration
+=============
+Action masking is supported for agents that use the `ProxyAgent` class (the class used for connecting to RL algorithms).
+In order to use action masking, set the agent_settings.action_masking parameter to True in the config file.
+
+Masking Logic
+=============
+The following logic is applied:
+
++------------------------------------------+---------------------------------------------------------------------+
+| Action                                   | Action Mask Logic                                                   |
++==========================================+=====================================================================+
+| **DONOTHING**                            | Always Possible.                                                    |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_SERVICE_SCAN**               | Node is on. Service is running.                                     |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_SERVICE_STOP**               | Node is on. Service is running.                                     |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_SERVICE_START**              | Node is on. Service is stopped.                                     |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_SERVICE_PAUSE**              | Node is on. Service is running.                                     |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_SERVICE_RESUME**             | Node is on. Service is paused.                                      |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_SERVICE_RESTART**            | Node is on. Service is running.                                     |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_SERVICE_DISABLE**            | Node is on.                                                         |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_SERVICE_ENABLE**             | Node is on. Service is disabled.                                    |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_SERVICE_FIX**                | Node is on. Service is running.                                     |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_APPLICATION_EXECUTE**        | Node is on.                                                         |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_APPLICATION_SCAN**           | Node is on. Application is running.                                 |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_APPLICATION_CLOSE**          | Node is on. Application is running.                                 |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_APPLICATION_FIX**            | Node is on. Application is running.                                 |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_APPLICATION_INSTALL**        | Node is on.                                                         |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_APPLICATION_REMOVE**         | Node is on.                                                         |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_FILE_SCAN**                  | Node is on. File exists. File not deleted.                          |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_FILE_CREATE**                | Node is on.                                                         |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_FILE_CHECKHASH**             | Node is on. File exists. File not deleted.                          |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_FILE_DELETE**                | Node is on. File exists.                                            |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_FILE_REPAIR**                | Node is on. File exists. File not deleted.                          |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_FILE_RESTORE**               | Node is on. File exists. File is deleted.                           |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_FILE_CORRUPT**               | Node is on. File exists. File not deleted.                          |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_FILE_ACCESS**                | Node is on. File exists. File not deleted.                          |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_FOLDER_CREATE**              | Node is on.                                                         |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_FOLDER_SCAN**                | Node is on. Folder exists. Folder not deleted.                      |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_FOLDER_CHECKHASH**           | Node is on. Folder exists. Folder not deleted.                      |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_FOLDER_REPAIR**              | Node is on. Folder exists. Folder not deleted.                      |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_FOLDER_RESTORE**             | Node is on. Folder exists. Folder is deleted.                       |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_OS_SCAN**                    | Node is on.                                                         |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_NIC_ENABLE**                 | NIC is disabled. Node is on.                                        |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_NIC_DISABLE**                | NIC is enabled. Node is on.                                         |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_SHUTDOWN**                   | Node is on.                                                         |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_STARTUP**                    | Node is off.                                                        |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_RESET**                      | Node is on.                                                         |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_NMAP_PING_SCAN**             | Node is on.                                                         |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_NMAP_PORT_SCAN**             | Node is on.                                                         |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_HOST_NMAP_NETWORK_SERVICE_RECON** | Node is on.                                                         |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_ROUTER_PORT_ENABLE**              | Router is on.                                                       |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_ROUTER_PORT_DISABLE**             | Router is on.                                                       |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_ROUTER_ACL_ADDRULE**              | Router is on.                                                       |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_ROUTER_ACL_REMOVERULE**           | Router is on.                                                       |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_FIREWALL_PORT_ENABLE**            | Firewall is on.                                                     |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_FIREWALL_PORT_DISABLE**           | Firewall is on.                                                     |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_FIREWALL_ACL_ADDRULE**            | Firewall is on.                                                     |
++------------------------------------------+---------------------------------------------------------------------+
+| **NODE_FIREWALL_ACL_REMOVERULE**         | Firewall is on.                                                     |
++------------------------------------------+---------------------------------------------------------------------+
+
+
+Mechanism
+=========
+The environment iterates over the RL agent's ``action_map`` and generates the corresponding simulator request string.
+It uses the ``RequestManager.check_valid()`` method to invoke the relevant ``RequestPermissionValidator`` without
+actually running the request on the simulation.
+
+Current Limitations
+===================
+Currently, action masking only considers whether the action as a whole is possible, it doesn't verify that the exact
+parameter combination passed to the action make sense in the current context. For instance, if ACL rule 3 on router_1 is
+already populated, the action for adding another rule at position 3 will be available regardless, as long as that router
+is turned on. This will never block valid actions. It will just occasionally allow invalid actions.

docs/source/configuration/io_settings.rst

@@ -18,8 +18,11 @@ This section configures how PrimAITE saves data during simulation and training.
         save_step_metadata: False
         save_pcap_logs: False
         save_sys_logs: False
+        save_agent_logs: False
         write_sys_log_to_terminal: False
+        write_agent_log_to_terminal: False
         sys_log_level: WARNING
+        agent_log_level: INFO
 
 
 ``save_logs``
@@ -57,6 +60,12 @@ Optional. Default value is ``False``.
 
 If ``True``, then the log files which contain all node actions during the simulation will be saved.
 
+``save_agent_logs``
+-----------------
+
+Optional. Default value is ``False``.
+
+If ``True``, then the log files which contain all human readable agent behaviour during the simulation will be saved.
 
 ``write_sys_log_to_terminal``
 -----------------------------
@@ -65,16 +74,25 @@ Optional. Default value is ``False``.
 
 If ``True``, PrimAITE will print sys log to the terminal.
 
+``write_agent_log_to_terminal``
+-----------------------------
 
-``sys_log_level``
--------------
+Optional. Default value is ``False``.
+
+If ``True``, PrimAITE will print all human readable agent behaviour logs to the terminal.
+
+
+``sys_log_level & agent_log_level``
+---------------------------------
 
 Optional. Default value is ``WARNING``.
 
-The level of logging that should be visible in the sys logs or the logs output to the terminal.
+The level of logging that should be visible in the syslog, agent logs or the logs output to the terminal.
 
 ``save_sys_logs`` or ``write_sys_log_to_terminal`` has to be set to ``True`` for this setting to be used.
 
+This is also true for agent behaviour logging.
+
 Available options are:
 
 - ``DEBUG``: Debug level items and the items below

docs/source/configuration/simulation.rst

@@ -7,7 +7,7 @@
 ==============
 In this section the network layout is defined. This part of the config follows a hierarchical structure. Almost every component defines a ``ref`` field which acts as a human-readable unique identifier, used by other parts of the config, such as agents.
 
-At the top level of the network are ``nodes`` and ``links``.
+At the top level of the network are ``nodes``, ``links`` and ``airspace``.
 
 e.g.
 
@@ -19,6 +19,9 @@ e.g.
             ...
             links:
             ...
+            airspace:
+            ...
+
 
 ``nodes``
 ---------
@@ -101,3 +104,27 @@ This accepts an integer value e.g. if port 1 is to be connected, the configurati
 ``bandwidth``
 
 This is an integer value specifying the allowed bandwidth across the connection. Units are in Mbps.
+
+``airspace``
+------------
+
+This section configures settings specific to the wireless network's virtual airspace.
+
+``frequency_max_capacity_mbps``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This setting allows the user to override the default maximum bandwidth capacity set for each frequency. The key should
+be the AirSpaceFrequency name and the value be the desired maximum bandwidth capacity in mbps (megabits per second) for
+a single timestep.
+
+The below example would permit 123.45 megabits to be transmit across the WiFi 2.4 GHz frequency in a single timestep.
+Setting a frequencies max capacity to 0.0 blocks that frequency on the airspace.
+
+.. code-block:: yaml
+
+    simulation:
+      network:
+        airspace:
+          frequency_max_capacity_mbps:
+            WIFI_2_4: 123.45
+            WIFI_5: 0.0

docs/source/developer_tools.rst

@@ -49,36 +49,68 @@ dev-mode configuration
 
 The following configures some specific items that the dev-mode overrides, if enabled.
 
-`--sys-log-level` or `-level`
-----------------------------
+`--sys-log-level` or `-slevel`
+-----------------------------
 
 The level of system logs can be overridden by dev-mode.
 
 By default, this is set to DEBUG
 
-The available options are [DEBUG|INFO|WARNING|ERROR|CRITICAL]
+The available options for both system and agent logs are:
 
-.. code-block::
-
-    primaite dev-mode config -level INFO
-
-or
++-------------------+
+| Log Level         |
++===================+
+| DEBUG             |
++-------------------+
+| INFO              |
++-------------------+
+| WARNING           |
++-------------------+
+| ERROR             |
++-------------------+
+| CRITICAL          |
++-------------------+
 
 .. code-block::
 
     primaite dev-mode config --sys-log-level INFO
 
+or
+
+.. code-block::
+
+    primaite dev-mode config -slevel INFO
+
+
+`--agent-log-level` or `-alevel`
+--------------------------------
+
+The level of agent logs can be overridden by dev-mode.
+
+By default, this is set to DEBUG.
+
+.. code-block::
+
+    primaite dev-mode config --agent-log-level INFO
+
+or
+
+.. code-block::
+
+    primaite dev-mode config -alevel INFO
+
 `--output-sys-logs` or `-sys`
 -----------------------------
 
-The outputting of system logs can be overridden by dev-mode.
+The output of system logs can be overridden by dev-mode.
 
 By default, this is set to False
 
 Enabling system logs
 """"""""""""""""""""
 
-To enable outputting of system logs
+To enable output of system logs
 
 .. code-block::
 
@@ -93,7 +125,7 @@ or
 Disabling system logs
 """""""""""""""""""""
 
-To disable outputting of system logs
+To disable output of system logs
 
 .. code-block::
 
@@ -105,17 +137,47 @@ or
 
     primaite dev-mode config -nsys
 
+Enabling agent logs
+""""""""""""""""""""
+
+To enable output of system logs
+
+.. code-block::
+
+    primaite dev-mode config --output-agent-logs
+
+or
+
+.. code-block::
+
+    primaite dev-mode config -agent
+
+Disabling system logs
+"""""""""""""""""""""
+
+To disable output of system logs
+
+.. code-block::
+
+    primaite dev-mode config --no-agent-logs
+
+or
+
+.. code-block::
+
+    primaite dev-mode config -nagent
+
 `--output-pcap-logs` or `-pcap`
 -------------------------------
 
-The outputting of packet capture logs can be overridden by dev-mode.
+The output of packet capture logs can be overridden by dev-mode.
 
 By default, this is set to False
 
 Enabling PCAP logs
 """"""""""""""""""
 
-To enable outputting of packet capture logs
+To enable output of packet capture logs
 
 .. code-block::
 
@@ -130,7 +192,7 @@ or
 Disabling PCAP logs
 """""""""""""""""""
 
-To disable outputting of packet capture logs
+To disable output of packet capture logs
 
 .. code-block::
 
@@ -145,14 +207,14 @@ or
 `--output-to-terminal` or `-t`
 ------------------------------
 
-The outputting of system logs to the terminal can be overridden by dev-mode.
+The output of system logs to the terminal can be overridden by dev-mode.
 
 By default, this is set to False
 
 Enabling system log output to terminal
 """"""""""""""""""""""""""""""""""""""
 
-To enable outputting of system logs to terminal
+To enable output of system logs to terminal
 
 .. code-block::
 
@@ -167,7 +229,7 @@ or
 Disabling system log output to terminal
 """""""""""""""""""""""""""""""""""""""
 
-To disable outputting of system logs to terminal
+To disable output of system logs to terminal
 
 .. code-block::
 

docs/source/example_notebooks.rst

@@ -2,6 +2,8 @@
 
     © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
 
+.. _example jupyter notebooks:
+
 Example Jupyter Notebooks
 =========================
 
@@ -18,6 +20,7 @@ Running Jupyter Notebooks
 -------------------------
 
 1. Navigate to the PrimAITE directory
+"""""""""""""""""""""""""""""""""""""
 
 .. code-block:: bash
     :caption: Unix
@@ -29,7 +32,10 @@ Running Jupyter Notebooks
 
     cd ~\primaite\{VERSION}
 
-2. Run jupyter notebook (the python environment to which you installed PrimAITE must be active)
+2. Run jupyter notebook
+"""""""""""""""""""""""
+
+**Please note that the python environment to which you installed PrimAITE must be active.**
 
 .. code-block:: bash
     :caption: Unix
@@ -42,11 +48,13 @@ Running Jupyter Notebooks
     jupyter notebook
 
 3. Opening the jupyter webpage (optional)
+"""""""""""""""""""""""""""""""""""""""""
 
 The default web browser may automatically open the webpage. However, if that is not the case, click the link shown in your command prompt output. It should look like this: ``http://localhost:8888/?token=0123456798abc0123456789abc``
 
 
 4. Navigate to the list of notebooks
+"""""""""""""""""""""""""""""""""""""""""
 
 The example notebooks are located in ``notebooks/example_notebooks/``. The file system shown in the jupyter webpage is relative to the location in which the ``jupyter notebook`` command was used.
 
@@ -77,6 +85,6 @@ The following extensions should now be installed
     :width: 300
     :align: center
 
-VSCode will then ask for a Python environment version to use. PrimAITE is compatible with Python versions 3.9 - 3.11
+VSCode will then ask for a Python environment version to use. PrimAITE is compatible with Python versions 3.8 - 3.11
 
 You should now be able to interact with the notebook.

docs/source/game_layer.rst

@@ -42,49 +42,50 @@ An agent's reward function is managed by the ``RewardManager``. It calculates re
 Reward Components
 -----------------
 
-Currently implemented are reward components tailored to the data manipulation scenario. View the full API and description of how they work here: :py:module:`primaite.game.agent.reward`.
+Currently implemented are reward components tailored to the data manipulation scenario. View the full API and description of how they work here: :py:modules:`primaite.game.agent.rewards`.
 
 Reward Sharing
 --------------
 
 An agent's reward can be based on rewards of other agents. This is particularly useful for modelling a situation where the blue agent's job is to protect the ability of green agents to perform their pattern-of-life. This can be configured in the YAML file this way:
 
-```yaml
-green_agent_1: # this agent sometimes tries to access the webpage, and sometimes the database
-    # actions, observations, and agent settings go here
-    reward_function:
-      reward_components:
+.. code-block:: yaml
 
-        # When the webpage loads, the reward goes up by 0.25 when it fails to load, it goes down to -0.25
-        - type: WEBPAGE_UNAVAILABLE_PENALTY
-          weight: 0.25
-          options:
-            node_hostname: client_2
+  green_agent_1: # this agent sometimes tries to access the webpage, and sometimes the database
+      # actions, observations, and agent settings go here
+      reward_function:
+        reward_components:
 
-        # When the database is reachable, the reward goes up by 0.05, when it is unreachable it goes down to -0.05
-        - type: GREEN_ADMIN_DATABASE_UNREACHABLE_PENALTY
-          weight: 0.05
-          options:
-            node_hostname: client_2
+          # When the webpage loads, the reward goes up by 0.25 when it fails to load, it goes down to -0.25
+          - type: WEBPAGE_UNAVAILABLE_PENALTY
+            weight: 0.25
+            options:
+              node_hostname: client_2
 
-blue_agent:
-    # actions, observations, and agent settings go here
-    reward_function:
-      reward_components:
+          # When the database is reachable, the reward goes up by 0.05, when it is unreachable it goes down to -0.05
+          - type: GREEN_ADMIN_DATABASE_UNREACHABLE_PENALTY
+            weight: 0.05
+            options:
+              node_hostname: client_2
 
-        # When the database file is in a good state, blue's reward is 0.4, when it's in a corrupted state the reward is -0.4
-        - type: DATABASE_FILE_INTEGRITY
-          weight: 0.40
-          options:
-            node_hostname: database_server
-            folder_name: database
-            file_name: database.db
+  blue_agent:
+      # actions, observations, and agent settings go here
+      reward_function:
+        reward_components:
+
+          # When the database file is in a good state, blue's reward is 0.4, when it's in a corrupted state the reward is -0.4
+          - type: DATABASE_FILE_INTEGRITY
+            weight: 0.40
+            options:
+              node_hostname: database_server
+              folder_name: database
+              file_name: database.db
+
+          # The green's reward is added onto the blue's reward.
+          - type: SHARED_REWARD
+            weight: 1.0
+            options:
+              agent_name: client_2_green_user
 
-        # The green's reward is added onto the blue's reward.
-        - type: SHARED_REWARD
-          weight: 1.0
-          options:
-            agent_name: client_2_green_user
-```
 
 When defining agent reward sharing, users must be careful to avoid circular references, as that would lead to an infinite calculation loop. PrimAITE will prevent circular dependencies and provide a helpful error message if they are detected in the yaml.

docs/source/primaite-dependencies.rst

@@ -2,40 +2,44 @@
 
     © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
 
-+-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+----------------------------------------------+
-| Name              | Version | License                            | Description                                                                                           | URL                                          |
-+===================+=========+====================================+=======================================================================================================+==============================================+
-| gymnasium         | 0.28.1  | MIT License                        | A standard API for reinforcement learning and a diverse set of reference environments (formerly Gym). | https://farama.org                           |
-+-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+----------------------------------------------+
-| ipywidgets        | 8.1.3   | BSD License                        | Jupyter interactive widgets                                                                           | http://jupyter.org                           |
-+-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+----------------------------------------------+
-| jupyterlab        | 3.6.1   | BSD License                        | JupyterLab computational environment                                                                  | https://jupyter.org                          |
-+-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+----------------------------------------------+
-| kaleido           | 0.2.1   | MIT                                | Static image export for web-based visualization libraries with zero dependencies                      | https://github.com/plotly/Kaleido            |
-+-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+----------------------------------------------+
-| matplotlib        | 3.7.1   | Python Software Foundation License | Python plotting package                                                                               | https://matplotlib.org                       |
-+-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+----------------------------------------------+
-| networkx          | 3.1     | BSD License                        | Python package for creating and manipulating graphs and networks                                      | https://networkx.org/                        |
-+-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+----------------------------------------------+
-| numpy             | 1.23.5  | BSD License                        | NumPy is the fundamental package for array computing with Python.                                     | https://www.numpy.org                        |
-+-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+----------------------------------------------+
-| platformdirs      | 3.5.1   | MIT License                        | A small Python package for determining appropriate platform-specific dirs, e.g. a "user data dir".    | https://github.com/platformdirs/platformdirs |
-+-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+----------------------------------------------+
-| plotly            | 5.15.0  | MIT License                        | An open-source, interactive data visualization library for Python                                     | https://plotly.com/python/                   |
-+-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+----------------------------------------------+
-| polars            | 0.18.4  | MIT License                        | Blazingly fast DataFrame library                                                                      | https://www.pola.rs/                         |
-+-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+----------------------------------------------+
-| prettytable       | 3.8.0   | BSD License (BSD (3 clause))       | A simple Python library for easily displaying tabular data in a visually appealing ASCII table format | https://github.com/jazzband/prettytable      |
-+-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+----------------------------------------------+
-| pydantic          | 2.7.0   | MIT License                        | Data validation using Python type hints                                                               | https://github.com/pydantic/pydantic         |
-+-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+----------------------------------------------+
-| PyYAML            | 6.0     | MIT License                        | YAML parser and emitter for Python                                                                    | https://pyyaml.org/                          |
-+-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+----------------------------------------------+
-| ray               | 2.23.0  | Apache 2.0                         | Ray provides a simple, universal API for building distributed applications.                           | https://github.com/ray-project/ray           |
-+-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+----------------------------------------------+
-| stable-baselines3 | 2.1.0   | MIT                                | Pytorch version of Stable Baselines, implementations of reinforcement learning algorithms.            | https://github.com/DLR-RM/stable-baselines3  |
-+-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+----------------------------------------------+
-| tensorflow        | 2.12.0  | Apache Software License            | TensorFlow is an open source machine learning framework for everyone.                                 | https://www.tensorflow.org/                  |
-+-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+----------------------------------------------+
-| typer             | 0.9.0   | MIT License                        | Typer, build great CLIs. Easy to code. Based on Python type hints.                                    | https://github.com/tiangolo/typer            |
-+-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+----------------------------------------------+
++-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+
+| Name              | Version | License                            | Description                                                                                           | URL                                                                |
++===================+=========+====================================+=======================================================================================================+====================================================================+
+| gymnasium         | 0.28.1  | MIT License                        | A standard API for reinforcement learning and a diverse set of reference environments (formerly Gym). | https://farama.org                                                 |
++-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+
+| ipywidgets        | 8.1.3   | BSD License                        | Jupyter interactive widgets                                                                           | http://jupyter.org                                                 |
++-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+
+| jupyterlab        | 3.6.1   | BSD License                        | JupyterLab computational environment                                                                  | https://jupyter.org                                                |
++-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+
+| kaleido           | 0.2.1   | MIT                                | Static image export for web-based visualization libraries with zero dependencies                      | https://github.com/plotly/Kaleido                                  |
++-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+
+| matplotlib        | 3.7.1   | Python Software Foundation License | Python plotting package                                                                               | https://matplotlib.org                                             |
++-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+
+| networkx          | 3.1     | BSD License                        | Python package for creating and manipulating graphs and networks                                      | https://networkx.org/                                              |
++-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+
+| numpy             | 1.23.5  | BSD License                        | NumPy is the fundamental package for array computing with Python.                                     | https://www.numpy.org                                              |
++-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+
+| platformdirs      | 3.5.1   | MIT License                        | A small Python package for determining appropriate platform-specific dirs, e.g. a "user data dir".    | https://github.com/platformdirs/platformdirs                       |
++-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+
+| plotly            | 5.15.0  | MIT License                        | An open-source, interactive data visualization library for Python                                     | https://plotly.com/python/                                         |
++-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+
+| polars            | 0.18.4  | MIT License                        | Blazingly fast DataFrame library                                                                      | https://www.pola.rs/                                               |
++-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+
+| prettytable       | 3.8.0   | BSD License (BSD (3 clause))       | A simple Python library for easily displaying tabular data in a visually appealing ASCII table format | https://github.com/jazzband/prettytable                            |
++-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+
+| pydantic          | 2.7.0   | MIT License                        | Data validation using Python type hints                                                               | https://github.com/pydantic/pydantic                               |
++-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+
+| PyYAML            | 6.0     | MIT License                        | YAML parser and emitter for Python                                                                    | https://pyyaml.org/                                                |
++-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+
+| ray               | 2.23.0  | Apache 2.0                         | Ray provides a simple, universal API for building distributed applications.                           | https://github.com/ray-project/ray                                 |
++-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+
+| stable-baselines3 | 2.1.0   | MIT                                | Pytorch version of Stable Baselines, implementations of reinforcement learning algorithms.            | https://github.com/DLR-RM/stable-baselines3                        |
++-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+
+| tensorflow        | 2.12.0  | Apache Software License            | TensorFlow is an open source machine learning framework for everyone.                                 | https://www.tensorflow.org/                                        |
++-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+
+| typer             | 0.9.0   | MIT License                        | Typer, build great CLIs. Easy to code. Based on Python type hints.                                    | https://github.com/tiangolo/typer                                  |
++-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+
+| Deepdiff          | 7.0.1   | MIT License                        | Deep difference of dictionaries, iterables, strings, and any other object objects.                    | https://github.com/seperman/deepdiff                               |
++-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+
+| sb3_contrib       | 2.3.0   | MIT License                        | Contrib package for Stable-Baselines3 - Experimental reinforcement learning (RL) code (Action Masking)| https://github.com/Stable-Baselines-Team/stable-baselines3-contrib |
++-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+

docs/source/request_system.rst

@@ -9,49 +9,55 @@ Request System
 
 Just like other aspects of SimComponent, the request types are not managed centrally for the whole simulation, but instead they are dynamically created and updated based on the nodes, links, and other components that currently exist in the simulation. This is achieved in the following way:
 
-- API
-    When requesting an action within the simulation, these two arguments must be provided:
+When requesting an action within the simulation, these two arguments must be provided:
 
-    1. ``request`` - selects which action you want to take on this ``SimComponent``. This is formatted as a list of strings such as ``['network', 'node', '<node-name>', 'service', '<service-name>', 'restart']``.
-    2. ``context`` - optional extra information that can be used to decide how to process the request. This is formatted as a dictionary. For example, if the request requires authentication, the context can include information about the user that initiated the request to decide if their permissions are sufficient.
+1. ``request`` - selects which action you want to take on this ``SimComponent``. This is formatted as a list of strings such as ``['network', 'node', '<node-name>', 'service', '<service-name>', 'restart']``.
+2. ``context`` - optional extra information that can be used to decide how to process the request. This is formatted as a dictionary. For example, if the request requires authentication, the context can include information about the user that initiated the request to decide if their permissions are sufficient.
 
-    When a request is resolved, it returns a success status, and optional additional data about the request.
+When a request is resolved, it returns a success status, and optional additional data about the request.
 
-    ``status`` can be one of:
+``status`` can be one of:
 
-    * ``success``: the request was executed
-    * ``failure``: the request could not be executed
-    * ``unreachable``: the target for the request was not found
-    * ``pending``: the request was initiated, but has not finished during this step
+* ``success``: the request was executed
+* ``failure``: the request could not be executed
+* ``unreachable``: the target for the request was not found
+* ``pending``: the request was initiated, but has not finished during this step
 
-    ``data`` can be a dictionary with any arbitrary JSON-like data to describe the outcome of the request.
+``data`` can be a dictionary with any arbitrary JSON-like data to describe the outcome of the request.
 
-- ``request`` detail
-    The request is a list of strings which help specify who should handle the request. The strings in the request list help RequestManagers traverse the 'ownership tree' of SimComponent. The example given above would be handled in the following way:
+Requests:
+"""""""""
 
-    1. ``Simulation`` receives ``['network', 'node', 'computer_1', 'service', 'DNSService', 'restart']``.
-        The first element of the request is ``network``, therefore it passes the request down to its network.
-    2. ``Network`` receives ``['node', 'computer_1', 'service', 'DNSService', 'restart']``.
-        The first element of the request is ``node``, therefore the network looks at the node name and passes the request down to the node with that name.
-    3. ``computer_1`` receives ``['service', 'DNSService', 'restart']``.
-        The first element of the request is ``service``, therefore the node looks at the service name and passes the rest of the request to the service with that name.
-    4. ``DNSService`` receives ``['restart']``.
-        Since ``restart`` is a defined request type in the service's own RequestManager, the service performs a restart.
+Request Syntax
+---------------
 
-- ``context`` detail
+The request is a list of strings which help specify who should handle the request. The strings in the request list help RequestManagers traverse the 'ownership tree' of SimComponent. The example given above would be handled in the following way:
+
+1. ``Simulation`` receives ``['network', 'node', 'computer_1', 'service', 'DNSService', 'restart']``.
+    The first element of the request is ``network``, therefore it passes the request down to its network.
+2. ``Network`` receives ``['node', 'computer_1', 'service', 'DNSService', 'restart']``.
+    The first element of the request is ``node``, therefore the network looks at the node name and passes the request down to the node with that name.
+3. ``computer_1`` receives ``['service', 'DNSService', 'restart']``.
+    The first element of the request is ``service``, therefore the node looks at the service name and passes the rest of the request to the service with that name.
+4. ``DNSService`` receives ``['restart']``.
+    Since ``restart`` is a defined request type in the service's own RequestManager, the service performs a restart.
+
+- ``context``
     The context is not used by any of the currently implemented components or requests.
 
-- Request response
-    When the simulator receives a request, it returns a response with a success status. The possible statuses are:
+Request responses
+-----------------
 
-    * **success**: The request was received and successfully executed.
-        * For example, the agent tries to add an ACL rule and specifies correct parameters, and the ACL rule is added successfully.
+When the simulator receives a request, it returns a response with a success status. The possible statuses are:
 
-    * **failure**: The request was received, but it could not be executed, or it failed while executing.
-        * For example, the agent tries to execute the ``WebBrowser`` application, but the webpage wasn't retrieved because the DNS server is not setup on the node.
+* **success**: The request was received and successfully executed.
+    * For example, the agent tries to add an ACL rule and specifies correct parameters, and the ACL rule is added successfully.
 
-    * **unreachable**: The request was sent to a simulation component that does not exist.
-        * For example, the agent tries to scan a file that has not been created yet.
+* **failure**: The request was received, but it could not be executed, or it failed while executing.
+    * For example, the agent tries to execute the ``WebBrowser`` application, but the webpage wasn't retrieved because the DNS server is not setup on the node.
+
+* **unreachable**: The request was sent to a simulation component that does not exist.
+    * For example, the agent tries to scan a file that has not been created yet.
 
 For more information, please refer to the ``Requests-and-Responses.ipynb`` jupyter notebook
 

docs/source/simulation.rst

@@ -27,6 +27,7 @@ Contents
    simulation_components/network/nodes/firewall
    simulation_components/network/switch
    simulation_components/network/network
+   simulation_components/network/airspace
    simulation_components/system/internal_frame_processing
    simulation_components/system/sys_log
    simulation_components/system/pcap

docs/source/simulation_components/network/airspace.rst

@@ -0,0 +1,42 @@
+.. only:: comment
+
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+
+.. _airspace:
+
+AirSpace
+========
+
+
+1. Introduction
+---------------
+
+The AirSpace class is the central component for wireless networks in PrimAITE and is designed to model and manage the behavior and interactions of wireless network interfaces within a simulated wireless network environment. This documentation provides a detailed overview of the AirSpace class, its components, and how they interact to create a realistic simulation of wireless network dynamics.
+
+2. Overview of the AirSpace System
+----------------------------------
+
+The AirSpace is a virtual representation of a physical wireless environment, managing multiple wireless network interfaces that simulate devices connected to the wireless network. These interfaces communicate over radio frequencies, with their interactions influenced by various factors modeled within the AirSpace.
+
+2.1 Key Components
+^^^^^^^^^^^^^^^^^^
+
+- **Wireless Network Interfaces**: Representations of network interfaces connected physical devices like routers, computers, or IoT devices that can send and receive data wirelessly.
+- **Bandwidth Management**: Tracks data transmission over frequencies to prevent overloading and simulate real-world network congestion.
+
+
+3. Managing Wireless Network Interfaces
+---------------------------------------
+
+- Interfaces can be dynamically added or removed.
+- Configurations can be changed in real-time.
+- The AirSpace handles data transmissions, ensuring data sent by an interface is received by all other interfaces on the same frequency.
+
+
+4. AirSpace Inspection
+----------------------
+
+The AirSpace class provides methods for visualizing network behavior:
+
+- ``show_wireless_interfaces()``: Displays current state of all interfaces
+- ``show_bandwidth_load()``: Shows bandwidth utilisation

docs/source/simulation_components/network/nodes/wireless_router.rst

@@ -37,7 +37,7 @@ additional steps to configure wireless settings:
 .. code-block:: python
 
     from primaite.simulator.network.hardware.nodes.network.wireless_router import WirelessRouter
-    from primaite.simulator.network.airspace import AirSpaceFrequency
+    from primaite.simulator.network.airspace import AirSpaceFrequency, ChannelWidth
 
     # Instantiate the WirelessRouter
     wireless_router = WirelessRouter(hostname="MyWirelessRouter")
@@ -49,7 +49,7 @@ additional steps to configure wireless settings:
     wireless_router.configure_wireless_access_point(
         port=1, ip_address="192.168.2.1",
         subnet_mask="255.255.255.0",
-        frequency=AirSpaceFrequency.WIFI_2_4
+        frequency=AirSpaceFrequency.WIFI_2_4,
     )
 
 
@@ -71,7 +71,7 @@ ICMP traffic, ensuring basic network connectivity and ping functionality.
 
 .. code-block:: python
 
-    from primaite.simulator.network.airspace import AIR_SPACE, AirSpaceFrequency
+    from primaite.simulator.network.airspace import AirSpaceFrequency, ChannelWidth
     from primaite.simulator.network.container import Network
     from primaite.simulator.network.hardware.nodes.host.computer import Computer
     from primaite.simulator.network.hardware.nodes.network.router import ACLAction
@@ -130,13 +130,13 @@ ICMP traffic, ensuring basic network connectivity and ping functionality.
         port=1,
         ip_address="192.168.1.1",
         subnet_mask="255.255.255.0",
-        frequency=AirSpaceFrequency.WIFI_2_4
+        frequency=AirSpaceFrequency.WIFI_2_4,
     )
     router_2.configure_wireless_access_point(
         port=1,
         ip_address="192.168.1.2",
         subnet_mask="255.255.255.0",
-        frequency=AirSpaceFrequency.WIFI_2_4
+        frequency=AirSpaceFrequency.WIFI_2_4,
     )
 
     # Configure routes for inter-router communication

docs/source/simulation_components/system/applications/dos_bot.rst

@@ -7,7 +7,10 @@
 DoSBot
 ######
 
-The ``DoSBot`` is an implementation of a Denial of Service attack within the PrimAITE simulation. This specifically simulates a `Slow Loris attack <https://en.wikipedia.org/wiki/Slowloris_(computer_security)>`.
+The ``DoSBot`` is an implementation of a Denial of Service attack within the PrimAITE simulation.
+This specifically simulates a `Slow Loris attack`_.
+
+.. _Slow Loris Attack: https://en.wikipedia.org/wiki/Slowloris_(computer_security)
 
 Key features
 ============

docs/source/simulation_components/system/applications/nmap.rst

@@ -5,10 +5,10 @@
 .. _NMAP:
 
 NMAP
-====
+####
 
 Overview
---------
+========
 
 The NMAP application is used to simulate network scanning activities. NMAP is a powerful tool that helps in discovering
 hosts and services on a network. It provides functionalities such as ping scans to discover active hosts and port scans
@@ -19,8 +19,8 @@ structure, identify active devices, and find potential vulnerabilities by discov
 However, it is also a tool frequently used by attackers during the reconnaissance stage of a cyber attack to gather
 information about the target network.
 
-Scan Types
-----------
+Scan Type
+=========
 
 Ping Scan
 ^^^^^^^^^
@@ -46,7 +46,7 @@ identifying potential entry points for attacks. There are three types of port sc
   It gives a comprehensive view of the network's service landscape.
 
 Example Usage
--------------
+^^^^^^^^^^^^^
 
 The network we use for these examples is defined below:
 
@@ -345,3 +345,11 @@ Perform a full box scan on all ports, over both TCP and UDP, on a whole subnet:
    | 192.168.1.13 | 123  | NTP             | UDP      |
    | 192.168.1.13 | 219  | ARP             | UDP      |
    +--------------+------+-----------------+----------+
+
+Configuration
+=============
+
+.. include:: ../common/common_configuration.rst
+
+.. |SOFTWARE_NAME| replace:: NMAP
+.. |SOFTWARE_NAME_BACKTICK| replace:: ``NMAP``

docs/source/simulation_components/system/applications/ransomware_script.rst

@@ -0,0 +1,85 @@
+.. only:: comment
+
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+
+.. _RansomwareScript:
+
+RansomwareScript
+###################
+
+The RansomwareScript class provides functionality to connect to a :ref:`DatabaseService` and set a database's database.db into a ``CORRUPTED`` state.
+
+Overview
+========
+
+The ransomware script intends to simulate a generic implementation of ransomware.
+
+Currently, due to simulation restraints, the ransomware script is unable to attack a host without an active database service.
+
+The ransomware script is similar to that of the data_manipulation_bot but does not have any separate stages or configurable probabilities.
+
+Additionally, similar to the data_manipulation_bot, the ransomware script must be installed on a host with a pre-existing :ref:`DatabaseClient` application installed.
+
+Usage
+=====
+
+- Create an instance and call ``configure`` to set:
+    - Target Database IP
+    - Database password (if needed)
+- Call ``Execute`` to connect and execute the ransomware script.
+
+This application handles connections to the database server and the connection made to encrypt the database but it does not handle disconnections.
+
+Implementation
+==============
+
+Currently, the ransomware script connects to a :ref:`DatabaseClient` and leverages its connectivity. The host running ``RansomwareScript`` must also have a :ref:`DatabaseClient` installed on it.
+
+- Uses the Application base class for lifecycle management.
+- Target IP and other options set via ``configure``.
+- ``execute`` handles connecting and encrypting.
+
+
+Examples
+========
+
+Python
+""""""
+.. code-block:: python
+
+    from primaite.simulator.network.hardware.nodes.host.computer import Computer
+    from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState
+    from primaite.simulator.system.applications.red_applications.RansomwareScript import RansomwareScript
+    from primaite.simulator.system.applications.database_client import DatabaseClient
+
+    client_1 = Computer(
+        hostname="client_1",
+        ip_address="192.168.10.21",
+        subnet_mask="255.255.255.0",
+        default_gateway="192.168.10.1",
+        operating_state=NodeOperatingState.ON # initialise the computer in an ON state
+    )
+    network.connect(endpoint_b=client_1.network_interface[1], endpoint_a=switch_2.network_interface[1])
+    client_1.software_manager.install(DatabaseClient)
+    client_1.software_manager.install(RansomwareScript)
+    RansomwareScript: RansomwareScript = client_1.software_manager.software.get("RansomwareScript")
+    RansomwareScript.configure(server_ip_address=IPv4Address("192.168.1.14"))
+    RansomwareScript.execute()
+
+
+Configuration
+=============
+
+The RansomwareScript inherits configuration options such as ``fix_duration`` from its parent class. However, for the ``RansomwareScript`` the most relevant option is ``server_ip``.
+
+.. include:: ../common/common_configuration.rst
+
+.. |SOFTWARE_NAME| replace:: RansomwareScript
+.. |SOFTWARE_NAME_BACKTICK| replace:: ``RansomwareScript``
+
+``server_ip``
+"""""""""""""
+
+IP address of the :ref:`DatabaseService` which the ``RansomwareScript`` will encrypt.
+
+This must be a valid octet i.e. in the range of ``0.0.0.0`` and ``255.255.255.255``.

docs/source/simulation_components/system/applications/web_browser.rst

@@ -23,7 +23,7 @@ Usage
 =====
 
 - Install on a Node via the ``SoftwareManager`` to start the ``WebBrowser``.
-- Service runs on HTTP port 80 by default. (TODO: HTTPS)
+- Service runs on HTTP port 80 by default.
 - Execute sending an HTTP GET request with ``get_webpage``
 
 Implementation

docs/source/simulation_components/system/common/common_configuration.rst

@@ -16,3 +16,12 @@ The type of software that should be added. To add |SOFTWARE_NAME| this must be |
 ===========
 
 The configuration options are the attributes that fall under the options for an application.
+
+
+
+``fix_duration``
+""""""""""""""""
+
+Optional. Default value is ``2``.
+
+The number of timesteps the |SOFTWARE_NAME| will remain in a ``FIXING`` state before going into a ``GOOD`` state.

docs/source/simulation_components/system/list_of_applications.rst

@@ -8,7 +8,7 @@
 
     applications/*
 
-More info :py:mod:`primaite.game.game.APPLICATION_TYPES_MAPPING`
+More info :py:mod:`primaite.simulator.system.applications.application.Application`
 
 .. include:: list_of_system_applications.rst
 

docs/source/simulation_components/system/services/ftp_client.rst

@@ -87,5 +87,3 @@ Configuration
 
 .. |SOFTWARE_NAME| replace:: FTPClient
 .. |SOFTWARE_NAME_BACKTICK| replace:: ``FTPClient``
-
-**FTPClient has no configuration options**

docs/source/simulation_components/system/services/ntp_server.rst

@@ -82,5 +82,3 @@ Configuration
 
 .. |SOFTWARE_NAME| replace:: NTPServer
 .. |SOFTWARE_NAME_BACKTICK| replace:: ``NTPServer``
-
-**NTPServer has no configuration options**

docs/source/simulation_components/system/services/web_server.rst

@@ -82,5 +82,3 @@ Configuration
 
 .. |SOFTWARE_NAME| replace:: WebServer
 .. |SOFTWARE_NAME_BACKTICK| replace:: ``WebServer``
-
-**WebServer has no configuration options**

docs/source/simulation_structure.rst

@@ -15,7 +15,7 @@ when a component's ``describe_state()`` method is called, it will include the st
 ``apply_request()`` method can be used to act on a component or one of its descendants. The diagram below shows the
 relationship between components.
 
-.. image:: ../../_static/component_relationship.png
+.. image:: ../_static/component_relationship.png
     :width: 500
     :align: center
     :alt: ::    The top level simulation object owns a NetworkContainer and a DomainController. The DomainController has a

docs/source/varying_config_files.rst

@@ -3,7 +3,7 @@
     © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
 
 Defining variations in the config files
-================
+=======================================
 
 PrimAITE supports the ability to use different variations on a scenario at different episodes. This can be used to increase domain randomisation to prevent overfitting, or to set up curriculum learning to train agents to perform more complicated tasks.
 
@@ -15,7 +15,7 @@ Base scenario
 
 The base scenario is essentially the same as a fixed YAML configuration, but it can contain placeholders that are populated with episode-specific data at runtime. The base scenario contains any network, agent, or settings that remain fixed for the entire training/evaluation session.
 
-The placeholders are defined as YAML Aliases and they are denoted by an asterisk (*placeholder).
+The placeholders are defined as YAML Aliases and they are denoted by an asterisk (* *placeholder*)
 
 Variations
 **********
@@ -46,4 +46,4 @@ It takes the following format:
 
 For more information please refer to the ``Using Episode Schedules`` notebook in either :ref:`Executed Notebooks` or run the notebook interactively in ``notebooks/example_notebooks/``.
 
-For further information around notebooks in general refer to the :ref:`Example Jupyter Notebooks`.
+For further information around notebooks in general refer to the :ref:`example_notebooks` page.

pyproject.toml

@@ -55,6 +55,7 @@ rl = [
     "ray[rllib] >= 2.20.0, < 3",
     "tensorflow==2.12.0",
     "stable-baselines3[extra]==2.1.0",
+    "sb3-contrib==2.1.0",
 ]
 dev = [
     "build==0.10.0",
@@ -64,7 +65,6 @@ dev = [
     "gputil==1.4.0",
     "pip-licenses==4.3.0",
     "pre-commit==2.20.0",
-    "pylatex==1.4.1",
     "pytest==7.2.0",
     "pytest-xdist==3.3.1",
     "pytest-cov==4.0.0",
@@ -73,7 +73,9 @@ dev = [
     "Sphinx==7.1.2",
     "sphinx-copybutton==0.5.2",
     "wheel==0.38.4",
-    "nbsphinx==0.9.4"
+    "nbsphinx==0.9.4",
+    "nbmake==1.5.4",
+    "pytest-xdist==3.3.1"
 ]
 
 [project.scripts]

src/primaite/VERSION

@@ -1 +1 @@
-3.1.0
+3.2.0

src/primaite/config/_package_data/data_manipulation.yaml

@@ -739,10 +739,9 @@ agents:
           options:
             agent_name: client_2_green_user
 
-
-
     agent_settings:
       flatten_obs: true
+      action_masking: true
 
 
 

src/primaite/config/_package_data/data_manipulation_marl.yaml

@@ -733,6 +733,7 @@ agents:
 
     agent_settings:
       flatten_obs: true
+      action_masking: true
 
   - ref: defender_2
     team: BLUE
@@ -1316,6 +1317,7 @@ agents:
 
     agent_settings:
       flatten_obs: true
+      action_masking: true
 
 
 

src/primaite/config/load.py

@@ -44,3 +44,18 @@ def data_manipulation_config_path() -> Path:
         _LOGGER.error(msg)
         raise FileNotFoundError(msg)
     return path
+
+
+def data_manipulation_marl_config_path() -> Path:
+    """
+    Get the path to the MARL example config.
+
+    :return: Path to yaml config file for the MARL scenario.
+    :rtype: Path
+    """
+    path = _EXAMPLE_CFG / "data_manipulation_marl.yaml"
+    if not path.exists():
+        msg = f"Example config does not exist: {path}. Have you run `primaite setup`?"
+        _LOGGER.error(msg)
+        raise FileNotFoundError(msg)
+    return path

src/primaite/game/agent/actions.py

@@ -14,9 +14,10 @@ from abc import ABC, abstractmethod
 from typing import Dict, List, Literal, Optional, Tuple, TYPE_CHECKING, Union
 
 from gymnasium import spaces
-from pydantic import BaseModel, Field, field_validator, ValidationInfo
+from pydantic import BaseModel, ConfigDict, Field, field_validator, ValidationInfo
 
 from primaite import getLogger
+from primaite.interface.request import RequestFormat
 
 _LOGGER = getLogger(__name__)
 
@@ -48,7 +49,7 @@ class AbstractAction(ABC):
         objects."""
 
     @abstractmethod
-    def form_request(self) -> List[str]:
+    def form_request(self) -> RequestFormat:
         """Return the action formatted as a request which can be ingested by the PrimAITE simulation."""
         return []
 
@@ -66,7 +67,7 @@ class DoNothingAction(AbstractAction):
         # i.e. a choice between one option. To make enumerating this action easier, we are adding a 'dummy' paramter
         # with one option. This just aids the Action Manager to enumerate all possibilities.
 
-    def form_request(self, **kwargs) -> List[str]:
+    def form_request(self, **kwargs) -> RequestFormat:
         """Return the action formatted as a request which can be ingested by the PrimAITE simulation."""
         return ["do_nothing"]
 
@@ -85,7 +86,7 @@ class NodeServiceAbstractAction(AbstractAction):
         self.shape: Dict[str, int] = {"node_id": num_nodes, "service_id": num_services}
         self.verb: str  # define but don't initialise: defends against children classes not defining this
 
-    def form_request(self, node_id: int, service_id: int) -> List[str]:
+    def form_request(self, node_id: int, service_id: int) -> RequestFormat:
         """Return the action formatted as a request which can be ingested by the PrimAITE simulation."""
         node_name = self.manager.get_node_name_by_idx(node_id)
         service_name = self.manager.get_service_name_by_idx(node_id, service_id)
@@ -180,7 +181,7 @@ class NodeApplicationAbstractAction(AbstractAction):
         self.shape: Dict[str, int] = {"node_id": num_nodes, "application_id": num_applications}
         self.verb: str  # define but don't initialise: defends against children classes not defining this
 
-    def form_request(self, node_id: int, application_id: int) -> List[str]:
+    def form_request(self, node_id: int, application_id: int) -> RequestFormat:
         """Return the action formatted as a request which can be ingested by the PrimAITE simulation."""
         node_name = self.manager.get_node_name_by_idx(node_id)
         application_name = self.manager.get_application_name_by_idx(node_id, application_id)
@@ -228,7 +229,7 @@ class NodeApplicationInstallAction(AbstractAction):
         super().__init__(manager=manager)
         self.shape: Dict[str, int] = {"node_id": num_nodes}
 
-    def form_request(self, node_id: int, application_name: str, ip_address: str) -> List[str]:
+    def form_request(self, node_id: int, application_name: str) -> RequestFormat:
         """Return the action formatted as a request which can be ingested by the PrimAITE simulation."""
         node_name = self.manager.get_node_name_by_idx(node_id)
         if node_name is None:
@@ -241,10 +242,81 @@ class NodeApplicationInstallAction(AbstractAction):
             "application",
             "install",
             application_name,
-            ip_address,
         ]
 
 
+class ConfigureDatabaseClientAction(AbstractAction):
+    """Action which sets config parameters for a database client on a node."""
+
+    class _Opts(BaseModel):
+        """Schema for options that can be passed to this action."""
+
+        model_config = ConfigDict(extra="forbid")
+        server_ip_address: Optional[str] = None
+        server_password: Optional[str] = None
+
+    def __init__(self, manager: "ActionManager", **kwargs) -> None:
+        super().__init__(manager=manager)
+
+    def form_request(self, node_id: int, config: Dict) -> RequestFormat:
+        """Return the action formatted as a request that can be ingested by the simulation."""
+        node_name = self.manager.get_node_name_by_idx(node_id)
+        if node_name is None:
+            return ["do_nothing"]
+        ConfigureDatabaseClientAction._Opts.model_validate(config)  # check that options adhere to schema
+        return ["network", "node", node_name, "application", "DatabaseClient", "configure", config]
+
+
+class ConfigureRansomwareScriptAction(AbstractAction):
+    """Action which sets config parameters for a ransomware script on a node."""
+
+    class _Opts(BaseModel):
+        """Schema for options that can be passed to this option."""
+
+        model_config = ConfigDict(extra="forbid")
+        server_ip_address: Optional[str] = None
+        server_password: Optional[str] = None
+        payload: Optional[str] = None
+
+    def __init__(self, manager: "ActionManager", **kwargs) -> None:
+        super().__init__(manager=manager)
+
+    def form_request(self, node_id: int, config: Dict) -> RequestFormat:
+        """Return the action formatted as a request that can be ingested by the simulation."""
+        node_name = self.manager.get_node_name_by_idx(node_id)
+        if node_name is None:
+            return ["do_nothing"]
+        ConfigureRansomwareScriptAction._Opts.model_validate(config)  # check that options adhere to schema
+        return ["network", "node", node_name, "application", "RansomwareScript", "configure", config]
+
+
+class ConfigureDoSBotAction(AbstractAction):
+    """Action which sets config parameters for a DoS bot on a node."""
+
+    class _Opts(BaseModel):
+        """Schema for options that can be passed to this option."""
+
+        model_config = ConfigDict(extra="forbid")
+        target_ip_address: Optional[str] = None
+        target_port: Optional[str] = None
+        payload: Optional[str] = None
+        repeat: Optional[bool] = None
+        port_scan_p_of_success: Optional[float] = None
+        dos_intensity: Optional[float] = None
+        max_sessions: Optional[int] = None
+
+    def __init__(self, manager: "ActionManager", **kwargs) -> None:
+        super().__init__(manager=manager)
+
+    def form_request(self, node_id: int, config: Dict) -> RequestFormat:
+        """Return the action formatted as a request that can be ingested by the simulation."""
+        node_name = self.manager.get_node_name_by_idx(node_id)
+        if node_name is None:
+            return ["do_nothing"]
+        self._Opts.model_validate(config)  # check that options adhere to schema
+        return ["network", "node", node_name, "application", "DoSBot", "configure", config]
+
+
 class NodeApplicationRemoveAction(AbstractAction):
     """Action which removes/uninstalls an application."""
 
@@ -252,7 +324,7 @@ class NodeApplicationRemoveAction(AbstractAction):
         super().__init__(manager=manager)
         self.shape: Dict[str, int] = {"node_id": num_nodes}
 
-    def form_request(self, node_id: int, application_name: str) -> List[str]:
+    def form_request(self, node_id: int, application_name: str) -> RequestFormat:
         """Return the action formatted as a request which can be ingested by the PrimAITE simulation."""
         node_name = self.manager.get_node_name_by_idx(node_id)
         if node_name is None:
@@ -274,7 +346,7 @@ class NodeFolderAbstractAction(AbstractAction):
         self.shape: Dict[str, int] = {"node_id": num_nodes, "folder_id": num_folders}
         self.verb: str  # define but don't initialise: defends against children classes not defining this
 
-    def form_request(self, node_id: int, folder_id: int) -> List[str]:
+    def form_request(self, node_id: int, folder_id: int) -> RequestFormat:
         """Return the action formatted as a request which can be ingested by the PrimAITE simulation."""
         node_name = self.manager.get_node_name_by_idx(node_id)
         folder_name = self.manager.get_folder_name_by_idx(node_idx=node_id, folder_idx=folder_id)
@@ -322,7 +394,9 @@ class NodeFileCreateAction(AbstractAction):
         super().__init__(manager, num_nodes=num_nodes, num_folders=num_folders, **kwargs)
         self.verb: str = "create"
 
-    def form_request(self, node_id: int, folder_name: str, file_name: str, force: Optional[bool] = False) -> List[str]:
+    def form_request(
+        self, node_id: int, folder_name: str, file_name: str, force: Optional[bool] = False
+    ) -> RequestFormat:
         """Return the action formatted as a request which can be ingested by the PrimAITE simulation."""
         node_name = self.manager.get_node_name_by_idx(node_id)
         if node_name is None or folder_name is None or file_name is None:
@@ -337,7 +411,7 @@ class NodeFolderCreateAction(AbstractAction):
         super().__init__(manager, num_nodes=num_nodes, num_folders=num_folders, **kwargs)
         self.verb: str = "create"
 
-    def form_request(self, node_id: int, folder_name: str) -> List[str]:
+    def form_request(self, node_id: int, folder_name: str) -> RequestFormat:
         """Return the action formatted as a request which can be ingested by the PrimAITE simulation."""
         node_name = self.manager.get_node_name_by_idx(node_id)
         if node_name is None or folder_name is None:
@@ -358,7 +432,7 @@ class NodeFileAbstractAction(AbstractAction):
         self.shape: Dict[str, int] = {"node_id": num_nodes, "folder_id": num_folders, "file_id": num_files}
         self.verb: str  # define but don't initialise: defends against children classes not defining this
 
-    def form_request(self, node_id: int, folder_id: int, file_id: int) -> List[str]:
+    def form_request(self, node_id: int, folder_id: int, file_id: int) -> RequestFormat:
         """Return the action formatted as a request which can be ingested by the PrimAITE simulation."""
         node_name = self.manager.get_node_name_by_idx(node_id)
         folder_name = self.manager.get_folder_name_by_idx(node_idx=node_id, folder_idx=folder_id)
@@ -391,7 +465,7 @@ class NodeFileDeleteAction(NodeFileAbstractAction):
         super().__init__(manager, num_nodes=num_nodes, num_folders=num_folders, num_files=num_files, **kwargs)
         self.verb: str = "delete"
 
-    def form_request(self, node_id: int, folder_id: int, file_id: int) -> List[str]:
+    def form_request(self, node_id: int, folder_id: int, file_id: int) -> RequestFormat:
         """Return the action formatted as a request which can be ingested by the PrimAITE simulation."""
         node_name = self.manager.get_node_name_by_idx(node_id)
         folder_name = self.manager.get_folder_name_by_idx(node_idx=node_id, folder_idx=folder_id)
@@ -432,7 +506,7 @@ class NodeFileAccessAction(AbstractAction):
         super().__init__(manager, num_nodes=num_nodes, num_folders=num_folders, **kwargs)
         self.verb: str = "access"
 
-    def form_request(self, node_id: int, folder_name: str, file_name: str) -> List[str]:
+    def form_request(self, node_id: int, folder_name: str, file_name: str) -> RequestFormat:
         """Return the action formatted as a request which can be ingested by the PrimAITE simulation."""
         node_name = self.manager.get_node_name_by_idx(node_id)
         if node_name is None or folder_name is None or file_name is None:
@@ -453,7 +527,7 @@ class NodeAbstractAction(AbstractAction):
         self.shape: Dict[str, int] = {"node_id": num_nodes}
         self.verb: str  # define but don't initialise: defends against children classes not defining this
 
-    def form_request(self, node_id: int) -> List[str]:
+    def form_request(self, node_id: int) -> RequestFormat:
         """Return the action formatted as a request which can be ingested by the PrimAITE simulation."""
         node_name = self.manager.get_node_name_by_idx(node_id)
         return ["network", "node", node_name, self.verb]
@@ -668,7 +742,7 @@ class RouterACLRemoveRuleAction(AbstractAction):
         super().__init__(manager=manager)
         self.shape: Dict[str, int] = {"position": max_acl_rules}
 
-    def form_request(self, target_router: str, position: int) -> List[str]:
+    def form_request(self, target_router: str, position: int) -> RequestFormat:
         """Return the action formatted as a request which can be ingested by the PrimAITE simulation."""
         return ["network", "node", target_router, "acl", "remove_rule", position]
 
@@ -851,7 +925,7 @@ class HostNICAbstractAction(AbstractAction):
         self.shape: Dict[str, int] = {"node_id": num_nodes, "nic_id": max_nics_per_node}
         self.verb: str  # define but don't initialise: defends against children classes not defining this
 
-    def form_request(self, node_id: int, nic_id: int) -> List[str]:
+    def form_request(self, node_id: int, nic_id: int) -> RequestFormat:
         """Return the action formatted as a request which can be ingested by the PrimAITE simulation."""
         node_name = self.manager.get_node_name_by_idx(node_idx=node_id)
         nic_num = self.manager.get_nic_num_by_idx(node_idx=node_id, nic_idx=nic_id)
@@ -888,7 +962,7 @@ class NetworkPortEnableAction(AbstractAction):
         super().__init__(manager=manager)
         self.shape: Dict[str, int] = {"port_id": max_nics_per_node}
 
-    def form_request(self, target_nodename: str, port_id: int) -> List[str]:
+    def form_request(self, target_nodename: str, port_id: int) -> RequestFormat:
         """Return the action formatted as a request which can be ingested by the PrimAITE simulation."""
         if target_nodename is None or port_id is None:
             return ["do_nothing"]
@@ -907,7 +981,7 @@ class NetworkPortDisableAction(AbstractAction):
         super().__init__(manager=manager)
         self.shape: Dict[str, int] = {"port_id": max_nics_per_node}
 
-    def form_request(self, target_nodename: str, port_id: int) -> List[str]:
+    def form_request(self, target_nodename: str, port_id: int) -> RequestFormat:
         """Return the action formatted as a request which can be ingested by the PrimAITE simulation."""
         if target_nodename is None or port_id is None:
             return ["do_nothing"]
@@ -1045,6 +1119,9 @@ class ActionManager:
         "NODE_NMAP_PING_SCAN": NodeNMAPPingScanAction,
         "NODE_NMAP_PORT_SCAN": NodeNMAPPortScanAction,
         "NODE_NMAP_NETWORK_SERVICE_RECON": NodeNetworkServiceReconAction,
+        "CONFIGURE_DATABASE_CLIENT": ConfigureDatabaseClientAction,
+        "CONFIGURE_RANSOMWARE_SCRIPT": ConfigureRansomwareScriptAction,
+        "CONFIGURE_DOSBOT": ConfigureDoSBotAction,
     }
     """Dictionary which maps action type strings to the corresponding action class."""
 
@@ -1240,7 +1317,7 @@ class ActionManager:
         act_identifier, act_options = self.action_map[action]
         return act_identifier, act_options
 
-    def form_request(self, action_identifier: str, action_options: Dict) -> List[str]:
+    def form_request(self, action_identifier: str, action_options: Dict) -> RequestFormat:
         """Take action in CAOS format and use the execution definition to change it into PrimAITE request format."""
         act_obj = self.actions[action_identifier]
         return act_obj.form_request(**action_options)

src/primaite/game/agent/agent_log.py

@@ -0,0 +1,188 @@
+# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+import logging
+from pathlib import Path
+
+from prettytable import MARKDOWN, PrettyTable
+
+from primaite.simulator import LogLevel, SIM_OUTPUT
+
+
+class _NotJSONFilter(logging.Filter):
+    def filter(self, record: logging.LogRecord) -> bool:
+        """
+        Determines if a log message does not start and end with '{' and '}' (i.e., it is not a JSON-like message).
+
+        :param record: LogRecord object containing all the information pertinent to the event being logged.
+        :return: True if log message is not JSON-like, False otherwise.
+        """
+        return not record.getMessage().startswith("{") and not record.getMessage().endswith("}")
+
+
+class AgentLog:
+    """
+    A Agent Log class is a simple logger dedicated to managing and writing logging updates and information for an agent.
+
+    Each log message is written to a file located at: <simulation output directory>/agent_name/agent_name.log
+    """
+
+    def __init__(self, agent_name: str):
+        """
+        Constructs a Agent Log instance for a given hostname.
+
+        :param hostname: The hostname associated with the system logs being recorded.
+        """
+        self.agent_name = agent_name
+        self.current_episode: int = 1
+        self.current_timestep: int = 0
+        self.setup_logger()
+
+    @property
+    def timestep(self) -> int:
+        """Returns the current timestep. Used for log indexing.
+
+        :return: The current timestep as an Int.
+        """
+        return self.current_timestep
+
+    def update_timestep(self, new_timestep: int):
+        """
+        Updates the self.current_timestep attribute with the given parameter.
+
+        This method is called within .step() to ensure that all instances of Agent Logs
+        are in sync with one another.
+
+        :param new_timestep: The new timestep.
+        """
+        self.current_timestep = new_timestep
+
+    def setup_logger(self):
+        """
+        Configures the logger for this Agent Log instance.
+
+        The logger is set to the DEBUG level, and is equipped with a handler that writes to a file and filters out
+        JSON-like messages.
+        """
+        if not SIM_OUTPUT.save_agent_logs:
+            return
+
+        log_path = self._get_log_path()
+        file_handler = logging.FileHandler(filename=log_path)
+        file_handler.setLevel(logging.DEBUG)
+
+        log_format = "%(timestep)s::%(levelname)s::%(message)s"
+        file_handler.setFormatter(logging.Formatter(log_format))
+
+        self.logger = logging.getLogger(f"{self.agent_name}_log")
+        for handler in self.logger.handlers:
+            self.logger.removeHandler(handler)
+        self.logger.setLevel(logging.DEBUG)
+        self.logger.addHandler(file_handler)
+
+    def _get_log_path(self) -> Path:
+        """
+        Constructs the path for the log file based on the agent name.
+
+        :return: Path object representing the location of the log file.
+        """
+        root = SIM_OUTPUT.agent_behaviour_path / f"episode_{self.current_episode}" / self.agent_name
+        root.mkdir(exist_ok=True, parents=True)
+        return root / f"{self.agent_name}.log"
+
+    def _write_to_terminal(self, msg: str, level: str, to_terminal: bool = False):
+        if to_terminal or SIM_OUTPUT.write_agent_log_to_terminal:
+            print(f"{self.agent_name}: ({ self.timestep}) ({level}) {msg}")
+
+    def debug(self, msg: str, to_terminal: bool = False):
+        """
+        Logs a message with the DEBUG level.
+
+        :param msg: The message to be logged.
+        :param to_terminal: If True, prints to the terminal too.
+        """
+        if SIM_OUTPUT.agent_log_level > LogLevel.DEBUG:
+            return
+
+        if SIM_OUTPUT.save_agent_logs:
+            self.logger.debug(msg, extra={"timestep": self.timestep})
+        self._write_to_terminal(msg, "DEBUG", to_terminal)
+
+    def info(self, msg: str, to_terminal: bool = False):
+        """
+        Logs a message with the INFO level.
+
+        :param msg: The message to be logged.
+        :param timestep: The current timestep.
+        :param to_terminal: If True, prints to the terminal too.
+        """
+        if SIM_OUTPUT.agent_log_level > LogLevel.INFO:
+            return
+
+        if SIM_OUTPUT.save_agent_logs:
+            self.logger.info(msg, extra={"timestep": self.timestep})
+        self._write_to_terminal(msg, "INFO", to_terminal)
+
+    def warning(self, msg: str, to_terminal: bool = False):
+        """
+        Logs a message with the WARNING level.
+
+        :param msg: The message to be logged.
+        :param timestep: The current timestep.
+        :param to_terminal: If True, prints to the terminal too.
+        """
+        if SIM_OUTPUT.agent_log_level > LogLevel.WARNING:
+            return
+
+        if SIM_OUTPUT.save_agent_logs:
+            self.logger.warning(msg, extra={"timestep": self.timestep})
+        self._write_to_terminal(msg, "WARNING", to_terminal)
+
+    def error(self, msg: str, to_terminal: bool = False):
+        """
+        Logs a message with the ERROR level.
+
+        :param msg: The message to be logged.
+        :param timestep: The current timestep.
+        :param to_terminal: If True, prints to the terminal too.
+        """
+        if SIM_OUTPUT.agent_log_level > LogLevel.ERROR:
+            return
+
+        if SIM_OUTPUT.save_agent_logs:
+            self.logger.error(msg, extra={"timestep": self.timestep})
+        self._write_to_terminal(msg, "ERROR", to_terminal)
+
+    def critical(self, msg: str, to_terminal: bool = False):
+        """
+        Logs a message with the CRITICAL level.
+
+        :param msg: The message to be logged.
+        :param timestep: The current timestep.
+        :param to_terminal: If True, prints to the terminal too.
+        """
+        if LogLevel.CRITICAL < SIM_OUTPUT.agent_log_level:
+            return
+
+        if SIM_OUTPUT.save_agent_logs:
+            self.logger.critical(msg, extra={"timestep": self.timestep})
+        self._write_to_terminal(msg, "CRITICAL", to_terminal)
+
+    def show(self, last_n: int = 10, markdown: bool = False):
+        """
+        Print an Agents Log as a table.
+
+        Generate and print PrettyTable instance that shows the agents behaviour log, with columns Time step,
+        Level and Message.
+
+        :param markdown: Use Markdown style in table output. Defaults to False.
+        """
+        table = PrettyTable(["Time Step", "Level", "Message"])
+        if markdown:
+            table.set_style(MARKDOWN)
+        table.align = "l"
+        table.title = f"{self.agent_name} Behaviour Log"
+        if self._get_log_path().exists():
+            with open(self._get_log_path()) as file:
+                lines = file.readlines()
+            for line in lines[-last_n:]:
+                table.add_row(line.strip().split("::"))
+        print(table)

src/primaite/game/agent/interface.py

@@ -7,6 +7,7 @@ from gymnasium.core import ActType, ObsType
 from pydantic import BaseModel, model_validator
 
 from primaite.game.agent.actions import ActionManager
+from primaite.game.agent.agent_log import AgentLog
 from primaite.game.agent.observations.observation_manager import ObservationManager
 from primaite.game.agent.rewards import RewardFunction
 from primaite.interface.request import RequestFormat, RequestResponse
@@ -69,6 +70,8 @@ class AgentSettings(BaseModel):
     "Configuration for when an agent begins performing it's actions"
     flatten_obs: bool = True
     "Whether to flatten the observation space before passing it to the agent. True by default."
+    action_masking: bool = False
+    "Whether to return action masks at each step."
 
     @classmethod
     def from_config(cls, config: Optional[Dict]) -> "AgentSettings":
@@ -116,6 +119,7 @@ class AbstractAgent(ABC):
         self.reward_function: Optional[RewardFunction] = reward_function
         self.agent_settings = agent_settings or AgentSettings()
         self.history: List[AgentHistoryItem] = []
+        self.logger = AgentLog(agent_name)
 
     def update_observation(self, state: Dict) -> ObsType:
         """
@@ -205,6 +209,7 @@ class ProxyAgent(AbstractAgent):
         )
         self.most_recent_action: ActType
         self.flatten_obs: bool = agent_settings.flatten_obs if agent_settings else False
+        self.action_masking: bool = agent_settings.action_masking if agent_settings else False
 
     def get_action(self, obs: ObsType, timestep: int = 0) -> Tuple[str, Dict]:
         """

src/primaite/game/agent/rewards.py

@@ -8,6 +8,7 @@ weighed sum of the components.
 
 The reward function is typically specified using a config yaml file or a config dictionary. The following example shows
 the structure:
+
 ```yaml
     reward_function:
         reward_components:
@@ -360,6 +361,38 @@ class SharedReward(AbstractReward):
         return cls(agent_name=agent_name)
 
 
+class ActionPenalty(AbstractReward):
+    """Apply a negative reward when taking any action except DONOTHING."""
+
+    def __init__(self, action_penalty: float, do_nothing_penalty: float) -> None:
+        """
+        Initialise the reward.
+
+        Reward or penalise agents for doing nothing or taking actions.
+
+        :param action_penalty: Reward to give agents for taking any action except DONOTHING
+        :type action_penalty: float
+        :param do_nothing_penalty: Reward to give agent for taking the DONOTHING action
+        :type do_nothing_penalty: float
+        """
+        self.action_penalty = action_penalty
+        self.do_nothing_penalty = do_nothing_penalty
+
+    def calculate(self, state: Dict, last_action_response: "AgentHistoryItem") -> float:
+        """Calculate the penalty to be applied."""
+        if last_action_response.action == "DONOTHING":
+            return self.do_nothing_penalty
+        else:
+            return self.action_penalty
+
+    @classmethod
+    def from_config(cls, config: Dict) -> "ActionPenalty":
+        """Build the ActionPenalty object from config."""
+        action_penalty = config.get("action_penalty", -1.0)
+        do_nothing_penalty = config.get("do_nothing_penalty", 0.0)
+        return cls(action_penalty=action_penalty, do_nothing_penalty=do_nothing_penalty)
+
+
 class RewardFunction:
     """Manages the reward function for the agent."""
 
@@ -370,6 +403,7 @@ class RewardFunction:
         "WEBPAGE_UNAVAILABLE_PENALTY": WebpageUnavailablePenalty,
         "GREEN_ADMIN_DATABASE_UNREACHABLE_PENALTY": GreenAdminDatabaseUnreachablePenalty,
         "SHARED_REWARD": SharedReward,
+        "ACTION_PENALTY": ActionPenalty,
     }
     """List of reward class identifiers."""
 

src/primaite/game/agent/scripted_agents/data_manipulation_bot.py

@@ -38,10 +38,11 @@ class DataManipulationAgent(AbstractScriptedAgent):
         :rtype: Tuple[str, Dict]
         """
         if timestep < self.next_execution_timestep:
+            self.logger.debug(msg="Performing do NOTHING")
             return "DONOTHING", {}
 
         self._set_next_execution_timestep(timestep + self.agent_settings.start_settings.frequency)
-
+        self.logger.info(msg="Performing a data manipulation attack!")
         return "NODE_APPLICATION_EXECUTE", {"node_id": self.starting_node_idx, "application_id": 0}
 
     def setup_agent(self) -> None:
@@ -54,3 +55,4 @@ class DataManipulationAgent(AbstractScriptedAgent):
         # we are assuming that every node in the node manager has a data manipulation application at idx 0
         num_nodes = len(self.action_manager.node_names)
         self.starting_node_idx = random.randint(0, num_nodes - 1)
+        self.logger.debug(msg=f"Select Start Node ID: {self.starting_node_idx}")

src/primaite/game/agent/scripted_agents/probabilistic_agent.py

@@ -85,4 +85,5 @@ class ProbabilisticAgent(AbstractScriptedAgent):
         :rtype: Tuple[str, Dict]
         """
         choice = self.rng.choice(len(self.action_manager.action_map), p=self.probabilities)
+        self.logger.info(f"Performing Action: {choice}")
         return self.action_manager.get_action(choice)

src/primaite/game/agent/scripted_agents/tap001.py

@@ -55,7 +55,6 @@ class TAP001(AbstractScriptedAgent):
             return "NODE_APPLICATION_INSTALL", {
                 "node_id": self.starting_node_idx,
                 "application_name": "RansomwareScript",
-                "ip_address": self.ip_address,
             }
 
         return "NODE_APPLICATION_EXECUTE", {"node_id": self.starting_node_idx, "application_id": 0}

src/primaite/game/game.py

@@ -3,6 +3,7 @@
 from ipaddress import IPv4Address
 from typing import Dict, List, Optional
 
+import numpy as np
 from pydantic import BaseModel, ConfigDict
 
 from primaite import DEFAULT_BANDWIDTH, getLogger
@@ -15,6 +16,8 @@ from primaite.game.agent.scripted_agents.probabilistic_agent import Probabilisti
 from primaite.game.agent.scripted_agents.random_agent import PeriodicAgent
 from primaite.game.agent.scripted_agents.tap001 import TAP001
 from primaite.game.science import graph_has_cycle, topological_sort
+from primaite.simulator import SIM_OUTPUT
+from primaite.simulator.network.airspace import AirSpaceFrequency
 from primaite.simulator.network.hardware.base import NodeOperatingState
 from primaite.simulator.network.hardware.nodes.host.computer import Computer
 from primaite.simulator.network.hardware.nodes.host.host_node import NIC
@@ -26,11 +29,14 @@ from primaite.simulator.network.hardware.nodes.network.wireless_router import Wi
 from primaite.simulator.network.nmne import set_nmne_config
 from primaite.simulator.network.transmission.transport_layer import Port
 from primaite.simulator.sim_container import Simulation
-from primaite.simulator.system.applications.database_client import DatabaseClient
-from primaite.simulator.system.applications.red_applications.data_manipulation_bot import DataManipulationBot
-from primaite.simulator.system.applications.red_applications.dos_bot import DoSBot
-from primaite.simulator.system.applications.red_applications.ransomware_script import RansomwareScript
-from primaite.simulator.system.applications.web_browser import WebBrowser
+from primaite.simulator.system.applications.application import Application
+from primaite.simulator.system.applications.database_client import DatabaseClient  # noqa: F401
+from primaite.simulator.system.applications.red_applications.data_manipulation_bot import (  # noqa: F401
+    DataManipulationBot,
+)
+from primaite.simulator.system.applications.red_applications.dos_bot import DoSBot  # noqa: F401
+from primaite.simulator.system.applications.red_applications.ransomware_script import RansomwareScript  # noqa: F401
+from primaite.simulator.system.applications.web_browser import WebBrowser  # noqa: F401
 from primaite.simulator.system.services.database.database_service import DatabaseService
 from primaite.simulator.system.services.dns.dns_client import DNSClient
 from primaite.simulator.system.services.dns.dns_server import DNSServer
@@ -42,15 +48,6 @@ from primaite.simulator.system.services.web_server.web_server import WebServer
 
 _LOGGER = getLogger(__name__)
 
-APPLICATION_TYPES_MAPPING = {
-    "WebBrowser": WebBrowser,
-    "DatabaseClient": DatabaseClient,
-    "DataManipulationBot": DataManipulationBot,
-    "DoSBot": DoSBot,
-    "RansomwareScript": RansomwareScript,
-}
-"""List of available applications that can be installed on nodes in the PrimAITE Simulation."""
-
 SERVICE_TYPES_MAPPING = {
     "DNSClient": DNSClient,
     "DNSServer": DNSServer,
@@ -170,6 +167,8 @@ class PrimaiteGame:
         for _, agent in self.agents.items():
             obs = agent.observation_manager.current_observation
             action_choice, parameters = agent.get_action(obs, timestep=self.step_counter)
+            if SIM_OUTPUT.save_agent_logs:
+                agent.logger.debug(f"Chosen Action: {action_choice}")
             request = agent.format_request(action_choice, parameters)
             response = self.simulation.apply_request(request)
             agent.process_action_response(
@@ -188,8 +187,14 @@ class PrimaiteGame:
         """Advance timestep."""
         self.step_counter += 1
         _LOGGER.debug(f"Advancing timestep to {self.step_counter} ")
+        self.update_agent_loggers()
         self.simulation.apply_timestep(self.step_counter)
 
+    def update_agent_loggers(self) -> None:
+        """Updates Agent Loggers with new timestep."""
+        for agent in self.agents.values():
+            agent.logger.update_timestep(self.step_counter)
+
     def calculate_truncated(self) -> bool:
         """Calculate whether the episode is truncated."""
         current_step = self.step_counter
@@ -198,6 +203,23 @@ class PrimaiteGame:
             return True
         return False
 
+    def action_mask(self, agent_name: str) -> np.ndarray:
+        """
+        Return the action mask for the agent.
+
+        This is a boolean list corresponding to the agent's action space. A False entry means this action cannot be
+        performed during this step.
+
+        :return: Action mask
+        :rtype: List[bool]
+        """
+        agent = self.agents[agent_name]
+        mask = [True] * len(agent.action_manager.action_map)
+        for i, action in agent.action_manager.action_map.items():
+            request = agent.action_manager.form_request(action_identifier=action[0], action_options=action[1])
+            mask[i] = self.simulation._request_manager.check_valid(request, {})
+        return np.asarray(mask, dtype=np.int8)
+
     def close(self) -> None:
         """Close the game, this will close the simulation."""
         return NotImplemented
@@ -233,6 +255,12 @@ class PrimaiteGame:
 
         simulation_config = cfg.get("simulation", {})
         network_config = simulation_config.get("network", {})
+        airspace_cfg = network_config.get("airspace", {})
+        frequency_max_capacity_mbps_cfg = airspace_cfg.get("frequency_max_capacity_mbps", {})
+
+        frequency_max_capacity_mbps_cfg = {AirSpaceFrequency[k]: v for k, v in frequency_max_capacity_mbps_cfg.items()}
+
+        net.airspace.frequency_max_capacity_mbps_ = frequency_max_capacity_mbps_cfg
 
         nodes_cfg = network_config.get("nodes", [])
         links_cfg = network_config.get("links", [])
@@ -297,6 +325,10 @@ class PrimaiteGame:
                         new_node.software_manager.install(SERVICE_TYPES_MAPPING[service_type])
                         new_service = new_node.software_manager.software[service_type]
 
+                        # fixing duration for the service
+                        if "fix_duration" in service_cfg.get("options", {}):
+                            new_service.fixing_duration = service_cfg["options"]["fix_duration"]
+
                         # start the service
                         new_service.start()
                     else:
@@ -319,7 +351,8 @@ class PrimaiteGame:
                         if "options" in service_cfg:
                             opt = service_cfg["options"]
                             new_service.password = opt.get("db_password", None)
-                            new_service.configure_backup(backup_server=IPv4Address(opt.get("backup_server_ip")))
+                            if "backup_server_ip" in opt:
+                                new_service.configure_backup(backup_server=IPv4Address(opt.get("backup_server_ip")))
                     if service_type == "FTPServer":
                         if "options" in service_cfg:
                             opt = service_cfg["options"]
@@ -333,9 +366,13 @@ class PrimaiteGame:
                     new_application = None
                     application_type = application_cfg["type"]
 
-                    if application_type in APPLICATION_TYPES_MAPPING:
-                        new_node.software_manager.install(APPLICATION_TYPES_MAPPING[application_type])
-                        new_application = new_node.software_manager.software[application_type]
+                    if application_type in Application._application_registry:
+                        new_node.software_manager.install(Application._application_registry[application_type])
+                        new_application = new_node.software_manager.software[application_type]  # grab the instance
+
+                        # fixing duration for the application
+                        if "fix_duration" in application_cfg.get("options", {}):
+                            new_application.fixing_duration = application_cfg["options"]["fix_duration"]
                     else:
                         msg = f"Configuration contains an invalid application type: {application_type}"
                         _LOGGER.error(msg)
@@ -358,7 +395,7 @@ class PrimaiteGame:
                         if "options" in application_cfg:
                             opt = application_cfg["options"]
                             new_application.configure(
-                                server_ip_address=IPv4Address(opt.get("server_ip")),
+                                server_ip_address=IPv4Address(opt.get("server_ip")) if opt.get("server_ip") else None,
                                 server_password=opt.get("server_password"),
                                 payload=opt.get("payload", "ENCRYPT"),
                             )

src/primaite/notebooks/Action-masking.ipynb

@@ -0,0 +1,220 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Action Masking\n",
+    "\n",
+    "© Crown-owned copyright 2024, Defence Science and Technology Laboratory UK\n",
+    "\n",
+    "PrimAITE environments support action masking. The action mask shows which of the agent's actions are applicable with the current environment state. For example, a node can only be turned on if it is currently turned off."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from primaite.session.environment import PrimaiteGymEnv\n",
+    "from primaite.config.load import data_manipulation_config_path\n",
+    "from prettytable import PrettyTable\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "env = PrimaiteGymEnv(data_manipulation_config_path())\n",
+    "env.action_masking = True"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The action mask is a list of booleans that specifies whether each action in the agent's action map is currently possible. Demonstrated here:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "act_table = PrettyTable((\"number\", \"action\", \"parameters\", \"mask\"))\n",
+    "mask = env.action_masks()\n",
+    "actions = env.agent.action_manager.action_map\n",
+    "max_str_len = 70\n",
+    "for act,mask in zip(actions.items(), mask):\n",
+    "    act_num, act_data = act\n",
+    "    act_type, act_params = act_data\n",
+    "    act_params = s if len(s:=str(act_params))<max_str_len else f\"{s[:max_str_len-3]}...\"\n",
+    "    act_table.add_row((act_num, act_type, act_params, mask))\n",
+    "print(act_table)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Action masking for Stable Baselines3 agents\n",
+    "SB3 agents automatically use the action_masks method during the training loop"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from sb3_contrib import MaskablePPO\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "model = MaskablePPO(\"MlpPolicy\", env, gamma=0.4, seed=32)\n",
+    "model.learn(1024)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Action masking for Ray RLLib agents\n",
+    "Ray uses a different API to obtain action masks, but this is handled by the PrimaiteRayEnv and PrimaiteRayMarlEnv classes"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from primaite.session.ray_envs import PrimaiteRayEnv\n",
+    "from ray.rllib.algorithms.ppo import PPOConfig\n",
+    "import yaml\n",
+    "from ray import air, tune\n",
+    "from ray.rllib.examples.rl_modules.classes.action_masking_rlm import ActionMaskingTorchRLModule\n",
+    "from ray.rllib.core.rl_module.rl_module import SingleAgentRLModuleSpec\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "with open(data_manipulation_config_path(), 'r') as f:\n",
+    "    cfg = yaml.safe_load(f)\n",
+    "for agent in cfg['agents']:\n",
+    "    if agent[\"ref\"] == \"defender\":\n",
+    "        agent['agent_settings']['flatten_obs'] = True\n",
+    "env_config = cfg\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "config = (\n",
+    "    PPOConfig()\n",
+    "    .api_stack(enable_rl_module_and_learner=True, enable_env_runner_and_connector_v2=True)\n",
+    "    .environment(env=PrimaiteRayEnv, env_config=cfg, action_mask_key=\"action_mask\")\n",
+    "    .rl_module(rl_module_spec=SingleAgentRLModuleSpec(module_class = ActionMaskingTorchRLModule))\n",
+    "    .env_runners(num_env_runners=0)\n",
+    "    .training(train_batch_size=128)\n",
+    ")\n",
+    "algo = config.build()\n",
+    "for i in range(2):\n",
+    "    results = algo.train()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Action masking with MARL in Ray RLLib\n",
+    "Each agent has their own action mask, this is useful if the agents have different action spaces."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from ray.rllib.core.rl_module.marl_module import MultiAgentRLModuleSpec\n",
+    "from primaite.session.ray_envs import PrimaiteRayMARLEnv\n",
+    "from primaite.config.load import data_manipulation_marl_config_path"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "with open(data_manipulation_marl_config_path(), 'r') as f:\n",
+    "    cfg = yaml.safe_load(f)\n",
+    "env_config = cfg\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "config = (\n",
+    "    PPOConfig()\n",
+    "    .multi_agent(\n",
+    "        policies={'defender_1','defender_2'}, # These names are the same as the agents defined in the example config.\n",
+    "        policy_mapping_fn=lambda agent_id, *args, **kwargs: agent_id,\n",
+    "        )\n",
+    "    .api_stack(enable_rl_module_and_learner=True, enable_env_runner_and_connector_v2=True)\n",
+    "    .environment(env=PrimaiteRayMARLEnv, env_config=cfg, action_mask_key=\"action_mask\")\n",
+    "    .rl_module(rl_module_spec=MultiAgentRLModuleSpec(module_specs={\n",
+    "        \"defender_1\":SingleAgentRLModuleSpec(module_class=ActionMaskingTorchRLModule),\n",
+    "        \"defender_2\":SingleAgentRLModuleSpec(module_class=ActionMaskingTorchRLModule),\n",
+    "        }))\n",
+    "    .env_runners(num_env_runners=0)\n",
+    "    .training(train_batch_size=128)\n",
+    ")\n",
+    "algo = config.build()\n",
+    "for i in range(2):\n",
+    "    results = algo.train()"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.8"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

src/primaite/notebooks/Data-Manipulation-E2E-Demonstration.ipynb

@@ -507,8 +507,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now service 1 on node 2 has `health_status = 3`, indicating that the webapp is compromised.\n",
-    "File 1 in folder 1 on node 3 has `health_status = 2`, indicating that the database file is compromised."
+    "Now service 1 on HOST1 has `health_status = 3`, indicating that the webapp is compromised.\n",
+    "File 1 in folder 1 on HOST2 has `health_status = 2`, indicating that the database file is compromised."
    ]
   },
   {
@@ -545,9 +545,9 @@
    "source": [
     "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",
+    "The reward will increase slightly as soon as the file finishes restoring. Then, the reward will increase to 0.9 when both green agents make successful requests.\n",
     "\n",
-    "Run the following cell until the green action is `NODE_APPLICATION_EXECUTE` for application 0, then the reward should become 1. If you run it enough times, another red attack will happen and the reward will drop again."
+    "Run the following cell until the green action is `NODE_APPLICATION_EXECUTE` for application 0, then the reward should increase. If you run it enough times, another red attack will happen and the reward will drop again."
    ]
   },
   {
@@ -708,7 +708,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.8"
+   "version": "3.10.12"
   }
  },
  "nbformat": 4,

src/primaite/notebooks/multi-processing.ipynb

@@ -143,7 +143,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.12"
+   "version": "3.10.11"
   }
  },
  "nbformat": 4,

src/primaite/session/environment.py

@@ -4,6 +4,7 @@ from os import PathLike
 from typing import Any, Dict, Optional, SupportsFloat, Tuple, Union
 
 import gymnasium
+import numpy as np
 from gymnasium.core import ActType, ObsType
 
 from primaite import getLogger
@@ -41,6 +42,21 @@ class PrimaiteGymEnv(gymnasium.Env):
         self.total_reward_per_episode: Dict[int, float] = {}
         """Average rewards of agents per episode."""
 
+    def action_masks(self) -> np.ndarray:
+        """
+        Return the action mask for the agent.
+
+        This is a boolean list corresponding to the agent's action space. A False entry means this action cannot be
+        performed during this step.
+
+        :return: Action mask
+        :rtype: List[bool]
+        """
+        if not self.agent.action_masking:
+            return np.asarray([True] * len(self.agent.action_manager.action_map))
+        else:
+            return self.game.action_mask(self._agent_name)
+
     @property
     def agent(self) -> ProxyAgent:
         """Grab a fresh reference to the agent object because it will be reinstantiated each episode."""

src/primaite/session/io.py

@@ -35,10 +35,16 @@ class PrimaiteIO:
         """Whether to save PCAP logs."""
         save_sys_logs: bool = True
         """Whether to save system logs."""
+        save_agent_logs: bool = True
+        """Whether to save agent logs."""
         write_sys_log_to_terminal: bool = False
         """Whether to write the sys log to the terminal."""
+        write_agent_log_to_terminal: bool = False
+        """Whether to write the agent log to the terminal."""
         sys_log_level: LogLevel = LogLevel.INFO
-        """The level of log that should be included in the logfiles/logged into terminal."""
+        """The level of sys logs that should be included in the logfiles/logged into terminal."""
+        agent_log_level: LogLevel = LogLevel.INFO
+        """The level of agent logs that should be included in the logfiles/logged into terminal."""
 
     def __init__(self, settings: Optional[Settings] = None) -> None:
         """
@@ -51,27 +57,31 @@ class PrimaiteIO:
         self.session_path: Path = self.generate_session_path()
         # set global SIM_OUTPUT path
         SIM_OUTPUT.path = self.session_path / "simulation_output"
+        SIM_OUTPUT.agent_behaviour_path = self.session_path / "agent_behaviour"
         SIM_OUTPUT.save_pcap_logs = self.settings.save_pcap_logs
         SIM_OUTPUT.save_sys_logs = self.settings.save_sys_logs
+        SIM_OUTPUT.save_agent_logs = self.settings.save_agent_logs
+        SIM_OUTPUT.write_agent_log_to_terminal = self.settings.write_agent_log_to_terminal
         SIM_OUTPUT.write_sys_log_to_terminal = self.settings.write_sys_log_to_terminal
         SIM_OUTPUT.sys_log_level = self.settings.sys_log_level
+        SIM_OUTPUT.agent_log_level = self.settings.agent_log_level
 
     def generate_session_path(self, timestamp: Optional[datetime] = None) -> Path:
         """Create a folder for the session and return the path to it."""
-        if timestamp is None:
-            timestamp = datetime.now()
-        date_str = timestamp.strftime("%Y-%m-%d")
-        time_str = timestamp.strftime("%H-%M-%S")
-
-        session_path = PRIMAITE_PATHS.user_sessions_path / date_str / time_str
+        session_path = PRIMAITE_PATHS.user_sessions_path / SIM_OUTPUT.date_str / SIM_OUTPUT.time_str
 
         # check if running in dev mode
         if is_dev_mode():
-            session_path = _PRIMAITE_ROOT.parent.parent / "sessions" / date_str / time_str
+            session_path = _PRIMAITE_ROOT.parent.parent / "sessions" / SIM_OUTPUT.date_str / SIM_OUTPUT.time_str
 
             # check if there is an output directory set in config
             if PRIMAITE_CONFIG["developer_mode"]["output_dir"]:
-                session_path = Path(PRIMAITE_CONFIG["developer_mode"]["output_dir"]) / "sessions" / date_str / time_str
+                session_path = (
+                    Path(PRIMAITE_CONFIG["developer_mode"]["output_dir"])
+                    / "sessions"
+                    / SIM_OUTPUT.date_str
+                    / SIM_OUTPUT.time_str
+                )
 
         session_path.mkdir(exist_ok=True, parents=True)
         return session_path
@@ -115,6 +125,9 @@ class PrimaiteIO:
         if config.get("sys_log_level"):
             config["sys_log_level"] = LogLevel[config["sys_log_level"].upper()]  # convert to enum
 
+        if config.get("agent_log_level"):
+            config["agent_log_level"] = LogLevel[config["agent_log_level"].upper()]  # convert to enum
+
         new = cls(settings=cls.Settings(**config))
 
         return new

src/primaite/session/ray_envs.py

@@ -3,6 +3,7 @@ import json
 from typing import Dict, SupportsFloat, Tuple
 
 import gymnasium
+from gymnasium import spaces
 from gymnasium.core import ActType, ObsType
 from ray.rllib.env.multi_agent_env import MultiAgentEnv
 
@@ -38,15 +39,19 @@ class PrimaiteRayMARLEnv(MultiAgentEnv):
 
         self.terminateds = set()
         self.truncateds = set()
-        self.observation_space = gymnasium.spaces.Dict(
-            {
-                name: gymnasium.spaces.flatten_space(agent.observation_manager.space)
-                for name, agent in self.agents.items()
-            }
-        )
-        self.action_space = gymnasium.spaces.Dict(
-            {name: agent.action_manager.space for name, agent in self.agents.items()}
+        self.observation_space = spaces.Dict(
+            {name: spaces.flatten_space(agent.observation_manager.space) for name, agent in self.agents.items()}
         )
+        for agent_name in self._agent_ids:
+            agent = self.game.rl_agents[agent_name]
+            if agent.action_masking:
+                self.observation_space[agent_name] = spaces.Dict(
+                    {
+                        "action_mask": spaces.MultiBinary(agent.action_manager.space.n),
+                        "observations": self.observation_space[agent_name],
+                    }
+                )
+        self.action_space = spaces.Dict({name: agent.action_manager.space for name, agent in self.agents.items()})
         self._obs_space_in_preferred_format = True
         self._action_space_in_preferred_format = True
         super().__init__()
@@ -131,13 +136,17 @@ class PrimaiteRayMARLEnv(MultiAgentEnv):
 
     def _get_obs(self) -> Dict[str, ObsType]:
         """Return the current observation."""
-        obs = {}
+        all_obs = {}
         for agent_name in self._agent_ids:
             agent = self.game.rl_agents[agent_name]
             unflat_space = agent.observation_manager.space
             unflat_obs = agent.observation_manager.current_observation
-            obs[agent_name] = gymnasium.spaces.flatten(unflat_space, unflat_obs)
-        return obs
+            obs = gymnasium.spaces.flatten(unflat_space, unflat_obs)
+            if agent.action_masking:
+                all_obs[agent_name] = {"action_mask": self.game.action_mask(agent_name), "observations": obs}
+            else:
+                all_obs[agent_name] = obs
+        return all_obs
 
     def close(self):
         """Close the simulation."""
@@ -158,15 +167,30 @@ class PrimaiteRayEnv(gymnasium.Env):
         self.env = PrimaiteGymEnv(env_config=env_config)
         # self.env.episode_counter -= 1
         self.action_space = self.env.action_space
-        self.observation_space = self.env.observation_space
+        if self.env.agent.action_masking:
+            self.observation_space = spaces.Dict(
+                {"action_mask": spaces.MultiBinary(self.env.action_space.n), "observations": self.env.observation_space}
+            )
+        else:
+            self.observation_space = self.env.observation_space
 
     def reset(self, *, seed: int = None, options: dict = None) -> Tuple[ObsType, Dict]:
         """Reset the environment."""
+        if self.env.agent.action_masking:
+            obs, *_ = self.env.reset(seed=seed)
+            new_obs = {"action_mask": self.env.action_masks(), "observations": obs}
+            return new_obs, *_
         return self.env.reset(seed=seed)
 
     def step(self, action: ActType) -> Tuple[ObsType, SupportsFloat, bool, bool, Dict]:
         """Perform a step in the environment."""
-        return self.env.step(action)
+        # if action masking is enabled, intercept the step method and add action mask to observation
+        if self.env.agent.action_masking:
+            obs, *_ = self.env.step(action)
+            new_obs = {"action_mask": self.game.action_mask(self.env._agent_name), "observations": obs}
+            return new_obs, *_
+        else:
+            return self.env.step(action)
 
     def close(self):
         """Close the simulation."""

src/primaite/setup/_package_data/primaite_config.yaml

@@ -3,6 +3,8 @@
 developer_mode:
   enabled: False  # not enabled by default
   sys_log_level: DEBUG # level of output for system logs, DEBUG by default
+  agent_log_level: DEBUG # level of output for agent logs, DEBUG by default
+  output_agent_logs: False # level of output for system logs, DEBUG by default
   output_sys_logs: False  # system logs not output by default
   output_pcap_logs: False  # pcap logs not output by default
   output_to_terminal: False  # do not output to terminal by default

src/primaite/simulator/__init__.py

@@ -34,10 +34,14 @@ class _SimOutput:
         path = PRIMAITE_PATHS.user_sessions_path / self.date_str / self.time_str
 
         self._path = path
+        self._agent_behaviour_path = path
         self._save_pcap_logs: bool = False
         self._save_sys_logs: bool = False
+        self._save_agent_logs: bool = False
         self._write_sys_log_to_terminal: bool = False
+        self._write_agent_log_to_terminal: bool = False
         self._sys_log_level: LogLevel = LogLevel.WARNING  # default log level is at WARNING
+        self._agent_log_level: LogLevel = LogLevel.WARNING
 
     @property
     def path(self) -> Path:
@@ -61,6 +65,28 @@ class _SimOutput:
         self._path = new_path
         self._path.mkdir(exist_ok=True, parents=True)
 
+    @property
+    def agent_behaviour_path(self) -> Path:
+        if is_dev_mode():
+            # if dev mode is enabled, if output dir is not set, print to primaite repo root
+            path: Path = _PRIMAITE_ROOT.parent.parent / "sessions" / self.date_str / self.time_str / "agent_behaviour"
+            # otherwise print to output dir
+            if PRIMAITE_CONFIG["developer_mode"]["output_dir"]:
+                path: Path = (
+                    Path(PRIMAITE_CONFIG["developer_mode"]["output_dir"])
+                    / "sessions"
+                    / self.date_str
+                    / self.time_str
+                    / "agent_behaviour"
+                )
+            self._agent_behaviour_path = path
+        return self._agent_behaviour_path
+
+    @agent_behaviour_path.setter
+    def agent_behaviour_path(self, new_path: Path) -> None:
+        self._agent_behaviour_path = new_path
+        self._agent_behaviour_path.mkdir(exist_ok=True, parents=True)
+
     @property
     def save_pcap_logs(self) -> bool:
         if is_dev_mode():
@@ -81,6 +107,16 @@ class _SimOutput:
     def save_sys_logs(self, save_sys_logs: bool) -> None:
         self._save_sys_logs = save_sys_logs
 
+    @property
+    def save_agent_logs(self) -> bool:
+        if is_dev_mode():
+            return PRIMAITE_CONFIG.get("developer_mode").get("output_agent_logs")
+        return self._save_agent_logs
+
+    @save_agent_logs.setter
+    def save_agent_logs(self, save_agent_logs: bool) -> None:
+        self._save_agent_logs = save_agent_logs
+
     @property
     def write_sys_log_to_terminal(self) -> bool:
         if is_dev_mode():
@@ -91,6 +127,17 @@ class _SimOutput:
     def write_sys_log_to_terminal(self, write_sys_log_to_terminal: bool) -> None:
         self._write_sys_log_to_terminal = write_sys_log_to_terminal
 
+    # Should this be separate from sys_log?
+    @property
+    def write_agent_log_to_terminal(self) -> bool:
+        if is_dev_mode():
+            return PRIMAITE_CONFIG.get("developer_mode").get("output_to_terminal")
+        return self._write_agent_log_to_terminal
+
+    @write_agent_log_to_terminal.setter
+    def write_agent_log_to_terminal(self, write_agent_log_to_terminal: bool) -> None:
+        self._write_agent_log_to_terminal = write_agent_log_to_terminal
+
     @property
     def sys_log_level(self) -> LogLevel:
         if is_dev_mode():
@@ -101,5 +148,15 @@ class _SimOutput:
     def sys_log_level(self, sys_log_level: LogLevel) -> None:
         self._sys_log_level = sys_log_level
 
+    @property
+    def agent_log_level(self) -> LogLevel:
+        if is_dev_mode():
+            return LogLevel[PRIMAITE_CONFIG.get("developer_mode").get("agent_log_level")]
+        return self._agent_log_level
+
+    @agent_log_level.setter
+    def agent_log_level(self, agent_log_level: LogLevel) -> None:
+        self._agent_log_level = agent_log_level
+
 
 SIM_OUTPUT = _SimOutput()

src/primaite/simulator/_package_data/create-simulation_demo.ipynb

@@ -171,7 +171,7 @@
     "from primaite.simulator.file_system.file_system import FileSystem\n",
     "\n",
     "# no applications exist yet so we will create our own.\n",
-    "class MSPaint(Application):\n",
+    "class MSPaint(Application, identifier=\"MSPaint\"):\n",
     "    def describe_state(self):\n",
     "        return super().describe_state()"
    ]

src/primaite/simulator/core.py

@@ -3,9 +3,10 @@
 """Core of the PrimAITE Simulator."""
 import warnings
 from abc import abstractmethod
-from typing import Callable, Dict, List, Literal, Optional, Union
+from typing import Callable, Dict, Iterable, List, Literal, Optional, Tuple, Union
 from uuid import uuid4
 
+from prettytable import PrettyTable
 from pydantic import BaseModel, ConfigDict, Field, validate_call
 
 from primaite import getLogger
@@ -34,6 +35,20 @@ class RequestPermissionValidator(BaseModel):
         """Message that is reported when a request is rejected by this validator."""
         return "request rejected"
 
+    def __add__(self, other: "RequestPermissionValidator") -> "_CombinedValidator":
+        return _CombinedValidator(validators=[self, other])
+
+
+class _CombinedValidator(RequestPermissionValidator):
+    validators: List[RequestPermissionValidator] = []
+
+    def __call__(self, request, context) -> bool:
+        return all(x(request, context) for x in self.validators)
+
+    @property
+    def fail_message(self):
+        return f"One of the following conditions are not met: {[v.fail_message for v in self.validators]}"
+
 
 class AllowAllValidator(RequestPermissionValidator):
     """Always allows the request."""
@@ -150,8 +165,17 @@ class RequestManager(BaseModel):
 
         self.request_types.pop(name)
 
-    def get_request_types_recursively(self) -> List[List[str]]:
-        """Recursively generate request tree for this component."""
+    def get_request_types_recursively(self) -> List[RequestFormat]:
+        """
+        Recursively generate request tree for this component.
+
+        :param parent_valid: Whether this sub-request's parent request was valid. This value should not be specified by
+                             users, it is used by the recursive call.
+        :type parent_valid: bool
+        :returns: A list of tuples where the first tuple element is the request string and the second is whether that
+                  request is currently possible to execute.
+        :rtype: List[Tuple[RequestFormat, bool]]
+        """
         requests = []
         for req_name, req in self.request_types.items():
             if isinstance(req.func, RequestManager):
@@ -162,6 +186,30 @@ class RequestManager(BaseModel):
                 requests.append([req_name])
         return requests
 
+    def show(self) -> None:
+        """Display all currently available requests."""
+        table = PrettyTable(["requests"])
+        table.align = "l"
+        table.add_rows([[x] for x in self.get_request_types_recursively()])
+        print(table)
+
+    def check_valid(self, request: RequestFormat, context: Dict) -> bool:
+        """Check if this request would be valid in the current state of the simulation without invoking it."""
+
+        request_key = request[0]
+        request_options = request[1:]
+
+        if request_key not in self.request_types:
+            return False
+
+        request_type = self.request_types[request_key]
+
+        # recurse if we are not at a leaf node
+        if isinstance(request_type.func, RequestManager):
+            return request_type.func.check_valid(request_options, context)
+
+        return request_type.validator(request_options, context)
+
 
 class SimComponent(BaseModel):
     """Extension of pydantic BaseModel with additional methods that must be defined by all classes in the simulator."""
@@ -196,7 +244,7 @@ class SimComponent(BaseModel):
 
         ..code::python
 
-            class WebBrowser(Application):
+            class WebBrowser(Application, identifier="WebBrowser"):
             def _init_request_manager(self) -> RequestManager:
                 rm = super()._init_request_manager() # all requests generic to any Application get initialised
                 rm.add_request(...) # initialise any requests specific to the web browser

src/primaite/simulator/domain/controller.py

@@ -52,6 +52,8 @@ class GroupMembershipValidator(RequestPermissionValidator):
     def __call__(self, request: List[str], context: Dict) -> bool:
         """Permit the action if the request comes from an account which belongs to the right group."""
         # if context request source is part of any groups mentioned in self.allow_groups, return true, otherwise false
+        if not context:
+            return False
         requestor_groups: List[str] = context["request_source"]["groups"]
         for allowed_group in self.allowed_groups:
             if allowed_group.name in requestor_groups:

src/primaite/simulator/file_system/file_system.py

@@ -6,8 +6,8 @@ from typing import Any, Dict, List, Optional
 
 from prettytable import MARKDOWN, PrettyTable
 
-from primaite.interface.request import RequestResponse
-from primaite.simulator.core import RequestManager, RequestType, SimComponent
+from primaite.interface.request import RequestFormat, RequestResponse
+from primaite.simulator.core import RequestManager, RequestPermissionValidator, RequestType, SimComponent
 from primaite.simulator.file_system.file import File
 from primaite.simulator.file_system.file_type import FileType
 from primaite.simulator.file_system.folder import Folder
@@ -42,6 +42,10 @@ class FileSystem(SimComponent):
 
         More information in user guide and docstring for SimComponent._init_request_manager.
         """
+        self._folder_exists = FileSystem._FolderExistsValidator(file_system=self)
+        self._folder_not_deleted = FileSystem._FolderNotDeletedValidator(file_system=self)
+        self._file_exists = FileSystem._FileExistsValidator(file_system=self)
+
         rm = super()._init_request_manager()
 
         self._delete_manager = RequestManager()
@@ -50,13 +54,15 @@ class FileSystem(SimComponent):
             request_type=RequestType(
                 func=lambda request, context: RequestResponse.from_bool(
                     self.delete_file(folder_name=request[0], file_name=request[1])
-                )
+                ),
+                validator=self._file_exists,
             ),
         )
         self._delete_manager.add_request(
             name="folder",
             request_type=RequestType(
-                func=lambda request, context: RequestResponse.from_bool(self.delete_folder(folder_name=request[0]))
+                func=lambda request, context: RequestResponse.from_bool(self.delete_folder(folder_name=request[0])),
+                validator=self._folder_exists,
             ),
         )
         rm.add_request(
@@ -144,10 +150,13 @@ class FileSystem(SimComponent):
         )
 
         self._folder_request_manager = RequestManager()
-        rm.add_request("folder", RequestType(func=self._folder_request_manager))
+        rm.add_request(
+            "folder",
+            RequestType(func=self._folder_request_manager, validator=self._folder_exists + self._folder_not_deleted),
+        )
 
         self._file_request_manager = RequestManager()
-        rm.add_request("file", RequestType(func=self._file_request_manager))
+        rm.add_request("file", RequestType(func=self._file_request_manager, validator=self._file_exists))
 
         return rm
 
@@ -626,3 +635,62 @@ class FileSystem(SimComponent):
                 self.sys_log.error(f"Unable to access file that does not exist. (file name: {file_name})")
 
         return False
+
+    class _FolderExistsValidator(RequestPermissionValidator):
+        """
+        When requests come in, this validator will only let them through if the Folder exists.
+
+        Actions cannot be performed on a non-existent folder.
+        """
+
+        file_system: FileSystem
+        """Save a reference to the FileSystem instance."""
+
+        def __call__(self, request: RequestFormat, context: Dict) -> bool:
+            """Returns True if folder exists."""
+            return self.file_system.get_folder(folder_name=request[0]) is not None
+
+        @property
+        def fail_message(self) -> str:
+            """Message that is reported when a request is rejected by this validator."""
+            return "Cannot perform request on folder because it does not exist."
+
+    class _FolderNotDeletedValidator(RequestPermissionValidator):
+        """
+        When requests come in, this validator will only let them through if the Folder has not been deleted.
+
+        Actions cannot be performed on a deleted folder.
+        """
+
+        file_system: FileSystem
+        """Save a reference to the FileSystem instance."""
+
+        def __call__(self, request: RequestFormat, context: Dict) -> bool:
+            """Returns True if folder exists and is not deleted."""
+            # get folder
+            folder = self.file_system.get_folder(folder_name=request[0], include_deleted=True)
+            return folder is not None and not folder.deleted
+
+        @property
+        def fail_message(self) -> str:
+            """Message that is reported when a request is rejected by this validator."""
+            return "Cannot perform request on folder because it is deleted."
+
+    class _FileExistsValidator(RequestPermissionValidator):
+        """
+        When requests come in, this validator will only let them through if the File exists.
+
+        Actions cannot be performed on a non-existent file.
+        """
+
+        file_system: FileSystem
+        """Save a reference to the FileSystem instance."""
+
+        def __call__(self, request: RequestFormat, context: Dict) -> bool:
+            """Returns True if file exists."""
+            return self.file_system.get_file(folder_name=request[0], file_name=request[1]) is not None
+
+        @property
+        def fail_message(self) -> str:
+            """Message that is reported when a request is rejected by this validator."""
+            return "Cannot perform request on a file that does not exist."

src/primaite/simulator/file_system/file_type.py

@@ -185,5 +185,5 @@ file_type_sizes_bytes = {
     FileType.ZIP: 1024000,
     FileType.TAR: 1024000,
     FileType.GZ: 819200,
-    FileType.DB: 15360000,
+    FileType.DB: 5_000_000,
 }

src/primaite/simulator/file_system/folder.py

@@ -6,8 +6,8 @@ from typing import Dict, Optional
 
 from prettytable import MARKDOWN, PrettyTable
 
-from primaite.interface.request import RequestResponse
-from primaite.simulator.core import RequestManager, RequestType
+from primaite.interface.request import RequestFormat, RequestResponse
+from primaite.simulator.core import RequestManager, RequestPermissionValidator, RequestType
 from primaite.simulator.file_system.file import File
 from primaite.simulator.file_system.file_system_item_abc import FileSystemItemABC, FileSystemItemHealthStatus
 
@@ -55,6 +55,9 @@ class Folder(FileSystemItemABC):
 
         More information in user guide and docstring for SimComponent._init_request_manager.
         """
+        self._file_exists = Folder._FileExistsValidator(folder=self)
+        self._file_not_deleted = Folder._FileNotDeletedValidator(folder=self)
+
         rm = super()._init_request_manager()
         rm.add_request(
             name="delete",
@@ -65,7 +68,9 @@ class Folder(FileSystemItemABC):
         self._file_request_manager = RequestManager()
         rm.add_request(
             name="file",
-            request_type=RequestType(func=self._file_request_manager),
+            request_type=RequestType(
+                func=self._file_request_manager, validator=self._file_exists + self._file_not_deleted
+            ),
         )
         return rm
 
@@ -469,3 +474,42 @@ class Folder(FileSystemItemABC):
 
         self.deleted = True
         return True
+
+    class _FileExistsValidator(RequestPermissionValidator):
+        """
+        When requests come in, this validator will only let them through if the File exists.
+
+        Actions cannot be performed on a non-existent file.
+        """
+
+        folder: Folder
+        """Save a reference to the Folder instance."""
+
+        def __call__(self, request: RequestFormat, context: Dict) -> bool:
+            """Returns True if file exists."""
+            return self.folder.get_file(file_name=request[0]) is not None
+
+        @property
+        def fail_message(self) -> str:
+            """Message that is reported when a request is rejected by this validator."""
+            return "Cannot perform request on a file that does not exist."
+
+    class _FileNotDeletedValidator(RequestPermissionValidator):
+        """
+        When requests come in, this validator will only let them through if the File is not deleted.
+
+        Actions cannot be performed on a deleted file.
+        """
+
+        folder: Folder
+        """Save a reference to the Folder instance."""
+
+        def __call__(self, request: RequestFormat, context: Dict) -> bool:
+            """Returns True if file exists and is not deleted."""
+            file = self.folder.get_file(file_name=request[0])
+            return file is not None and not file.deleted
+
+        @property
+        def fail_message(self) -> str:
+            """Message that is reported when a request is rejected by this validator."""
+            return "Cannot perform request on a file that is deleted."

src/primaite/simulator/network/airspace.py

@@ -3,9 +3,10 @@ from __future__ import annotations
 
 from abc import ABC, abstractmethod
 from enum import Enum
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List
 
-from prettytable import PrettyTable
+from prettytable import MARKDOWN, PrettyTable
+from pydantic import BaseModel, Field
 
 from primaite import getLogger
 from primaite.simulator.network.hardware.base import Layer3Interface, NetworkInterface, WiredNetworkInterface
@@ -15,90 +16,29 @@ from primaite.simulator.system.core.packet_capture import PacketCapture
 
 _LOGGER = getLogger(__name__)
 
-__all__ = ["AirSpaceFrequency", "WirelessNetworkInterface", "IPWirelessNetworkInterface"]
 
+def format_hertz(hertz: float, format_terahertz: bool = False, decimals: int = 3) -> str:
+    """
+    Convert a frequency in Hertz to a formatted string using the most appropriate unit.
 
-class AirSpace:
-    """Represents a wireless airspace, managing wireless network interfaces and handling wireless transmission."""
+    Optionally includes formatting for Terahertz.
 
-    def __init__(self):
-        self._wireless_interfaces: Dict[str, WirelessNetworkInterface] = {}
-        self._wireless_interfaces_by_frequency: Dict[AirSpaceFrequency, List[WirelessNetworkInterface]] = {}
-
-    def show(self, frequency: Optional[AirSpaceFrequency] = None):
-        """
-        Displays a summary of wireless interfaces in the airspace, optionally filtered by a specific frequency.
-
-        :param frequency: The frequency band to filter devices by. If None, devices for all frequencies are shown.
-        """
-        table = PrettyTable()
-        table.field_names = ["Connected Node", "MAC Address", "IP Address", "Subnet Mask", "Frequency", "Status"]
-
-        # If a specific frequency is provided, filter by it; otherwise, use all frequencies.
-        frequencies_to_show = [frequency] if frequency else self._wireless_interfaces_by_frequency.keys()
-
-        for freq in frequencies_to_show:
-            interfaces = self._wireless_interfaces_by_frequency.get(freq, [])
-            for interface in interfaces:
-                status = "Enabled" if interface.enabled else "Disabled"
-                table.add_row(
-                    [
-                        interface._connected_node.hostname,  # noqa
-                        interface.mac_address,
-                        interface.ip_address if hasattr(interface, "ip_address") else None,
-                        interface.subnet_mask if hasattr(interface, "subnet_mask") else None,
-                        str(freq),
-                        status,
-                    ]
-                )
-
-        print(table)
-
-    def add_wireless_interface(self, wireless_interface: WirelessNetworkInterface):
-        """
-        Adds a wireless network interface to the airspace if it's not already present.
-
-        :param wireless_interface: The wireless network interface to be added.
-        """
-        if wireless_interface.mac_address not in self._wireless_interfaces:
-            self._wireless_interfaces[wireless_interface.mac_address] = wireless_interface
-            if wireless_interface.frequency not in self._wireless_interfaces_by_frequency:
-                self._wireless_interfaces_by_frequency[wireless_interface.frequency] = []
-            self._wireless_interfaces_by_frequency[wireless_interface.frequency].append(wireless_interface)
-
-    def remove_wireless_interface(self, wireless_interface: WirelessNetworkInterface):
-        """
-        Removes a wireless network interface from the airspace if it's present.
-
-        :param wireless_interface: The wireless network interface to be removed.
-        """
-        if wireless_interface.mac_address in self._wireless_interfaces:
-            self._wireless_interfaces.pop(wireless_interface.mac_address)
-            self._wireless_interfaces_by_frequency[wireless_interface.frequency].remove(wireless_interface)
-
-    def clear(self):
-        """
-        Clears all wireless network interfaces and their frequency associations from the airspace.
-
-        After calling this method, the airspace will contain no wireless network interfaces, and transmissions cannot
-        occur until new interfaces are added again.
-        """
-        self._wireless_interfaces.clear()
-        self._wireless_interfaces_by_frequency.clear()
-
-    def transmit(self, frame: Frame, sender_network_interface: WirelessNetworkInterface):
-        """
-        Transmits a frame to all enabled wireless network interfaces on a specific frequency within the airspace.
-
-        This ensures that a wireless interface does not receive its own transmission.
-
-        :param frame: The frame to be transmitted.
-        :param sender_network_interface: The wireless network interface sending the frame. This interface will be
-            excluded from the list of receivers to prevent it from receiving its own transmission.
-        """
-        for wireless_interface in self._wireless_interfaces_by_frequency.get(sender_network_interface.frequency, []):
-            if wireless_interface != sender_network_interface and wireless_interface.enabled:
-                wireless_interface.receive_frame(frame)
+    :param hertz: Frequency in Hertz.
+    :param format_terahertz: Whether to format frequency in Terahertz, default is False.
+    :param decimals: Number of decimal places to round to, default is 3.
+    :returns: Formatted string with the frequency in the most suitable unit.
+    """
+    format_str = f"{{:.{decimals}f}}"
+    if format_terahertz and hertz >= 1e12:  # Terahertz
+        return format_str.format(hertz / 1e12) + " THz"
+    elif hertz >= 1e9:  # Gigahertz
+        return format_str.format(hertz / 1e9) + " GHz"
+    elif hertz >= 1e6:  # Megahertz
+        return format_str.format(hertz / 1e6) + " MHz"
+    elif hertz >= 1e3:  # Kilohertz
+        return format_str.format(hertz / 1e3) + " kHz"
+    else:  # Hertz
+        return format_str.format(hertz) + " Hz"
 
 
 class AirSpaceFrequency(Enum):
@@ -110,12 +50,231 @@ class AirSpaceFrequency(Enum):
     """WiFi 5 GHz. Known for its higher data transmission speeds and reduced interference from other devices."""
 
     def __str__(self) -> str:
+        hertz_str = format_hertz(hertz=self.value)
         if self == AirSpaceFrequency.WIFI_2_4:
-            return "WiFi 2.4 GHz"
-        elif self == AirSpaceFrequency.WIFI_5:
-            return "WiFi 5 GHz"
-        else:
-            return "Unknown Frequency"
+            return f"WiFi {hertz_str}"
+        if self == AirSpaceFrequency.WIFI_5:
+            return f"WiFi {hertz_str}"
+        return "Unknown Frequency"
+
+    @property
+    def maximum_data_rate_bps(self) -> float:
+        """
+        Retrieves the maximum data transmission rate in bits per second (bps) for the frequency.
+
+        The maximum rates are predefined for known frequencies:
+            - For WIFI_2_4, it returns 100,000,000 bps (100 Mbps).
+            - For WIFI_5, it returns 500,000,000 bps (500 Mbps).
+
+        :return: The maximum data rate in bits per second. If the frequency is not recognized, returns 0.0.
+        """
+        if self == AirSpaceFrequency.WIFI_2_4:
+            return 100_000_000.0  # 100 Megabits per second
+        if self == AirSpaceFrequency.WIFI_5:
+            return 500_000_000.0  # 500 Megabits per second
+        return 0.0
+
+    @property
+    def maximum_data_rate_mbps(self) -> float:
+        """
+        Retrieves the maximum data transmission rate in megabits per second (Mbps).
+
+        This is derived by converting the maximum data rate from bits per second, as defined
+        in `maximum_data_rate_bps`, to megabits per second.
+
+        :return: The maximum data rate in megabits per second.
+        """
+        return self.maximum_data_rate_bps / 1_000_000.0
+
+
+class AirSpace(BaseModel):
+    """
+    Represents a wireless airspace, managing wireless network interfaces and handling wireless transmission.
+
+    This class provides functionalities to manage a collection of wireless network interfaces, each associated with
+    specific frequencies. It includes methods to add and remove wireless interfaces, and handle data transmission
+    across these interfaces.
+    """
+
+    wireless_interfaces: Dict[str, WirelessNetworkInterface] = Field(default_factory=lambda: {})
+    wireless_interfaces_by_frequency: Dict[AirSpaceFrequency, List[WirelessNetworkInterface]] = Field(
+        default_factory=lambda: {}
+    )
+    bandwidth_load: Dict[AirSpaceFrequency, float] = Field(default_factory=lambda: {})
+    frequency_max_capacity_mbps_: Dict[AirSpaceFrequency, float] = Field(default_factory=lambda: {})
+
+    def get_frequency_max_capacity_mbps(self, frequency: AirSpaceFrequency) -> float:
+        """
+        Retrieves the maximum data transmission capacity for a specified frequency.
+
+        This method checks a dictionary holding custom maximum capacities. If the frequency is found, it returns the
+        custom set maximum capacity. If the frequency is not found in the dictionary, it defaults to the standard
+        maximum data rate associated with that frequency.
+
+        :param frequency: The frequency for which the maximum capacity is queried.
+
+        :return: The maximum capacity in Mbps for the specified frequency.
+        """
+        if frequency in self.frequency_max_capacity_mbps_:
+            return self.frequency_max_capacity_mbps_[frequency]
+        return frequency.maximum_data_rate_mbps
+
+    def set_frequency_max_capacity_mbps(self, cfg: Dict[AirSpaceFrequency, float]):
+        """
+        Sets custom maximum data transmission capacities for multiple frequencies.
+
+        :param cfg: A dictionary mapping frequencies to their new maximum capacities in Mbps.
+        """
+        self.frequency_max_capacity_mbps_ = cfg
+        for freq, mbps in cfg.items():
+            print(f"Overriding {freq} max capacity as {mbps:.3f} mbps")
+
+    def show_bandwidth_load(self, markdown: bool = False):
+        """
+        Prints a table of the current bandwidth load for each frequency on the airspace.
+
+        This method prints a tabulated view showing the utilisation of available bandwidth capacities for all
+        frequencies. The table includes the current capacity usage as a percentage of the maximum capacity, alongside
+        the absolute maximum capacity values in Mbps.
+
+        :param markdown: Flag indicating if output should be in markdown format.
+        """
+        headers = ["Frequency", "Current Capacity (%)", "Maximum Capacity (Mbit)"]
+        table = PrettyTable(headers)
+        if markdown:
+            table.set_style(MARKDOWN)
+        table.align = "l"
+        table.title = "Airspace Frequency Channel Loads"
+        for frequency, load in self.bandwidth_load.items():
+            maximum_capacity = self.get_frequency_max_capacity_mbps(frequency)
+            load_percent = load / maximum_capacity if maximum_capacity > 0 else 0.0
+            if load_percent > 1.0:
+                load_percent = 1.0
+            table.add_row([format_hertz(frequency.value), f"{load_percent:.0%}", f"{maximum_capacity:.3f}"])
+        print(table)
+
+    def show_wireless_interfaces(self, markdown: bool = False):
+        """
+        Prints a table of wireless interfaces in the airspace.
+
+        :param markdown: Flag indicating if output should be in markdown format.
+        """
+        headers = [
+            "Connected Node",
+            "MAC Address",
+            "IP Address",
+            "Subnet Mask",
+            "Frequency",
+            "Speed (Mbps)",
+            "Status",
+        ]
+        table = PrettyTable(headers)
+        if markdown:
+            table.set_style(MARKDOWN)
+        table.align = "l"
+        table.title = "Devices on Air Space"
+
+        for interface in self.wireless_interfaces.values():
+            status = "Enabled" if interface.enabled else "Disabled"
+            table.add_row(
+                [
+                    interface._connected_node.hostname,  # noqa
+                    interface.mac_address,
+                    interface.ip_address if hasattr(interface, "ip_address") else None,
+                    interface.subnet_mask if hasattr(interface, "subnet_mask") else None,
+                    format_hertz(interface.frequency.value),
+                    f"{interface.speed:.3f}",
+                    status,
+                ]
+            )
+        print(table.get_string(sortby="Frequency"))
+
+    def show(self, markdown: bool = False):
+        """
+        Prints a summary of the current state of the airspace, including both wireless interfaces and bandwidth loads.
+
+        This method is a convenient wrapper that calls two separate methods to display detailed tables: one for
+        wireless interfaces and another for bandwidth load across all frequencies managed within the airspace. It
+        provides a holistic view of the operational status and performance metrics of the airspace.
+
+        :param markdown: Flag indicating if output should be in markdown format.
+        """
+        self.show_wireless_interfaces(markdown)
+        self.show_bandwidth_load(markdown)
+
+    def add_wireless_interface(self, wireless_interface: WirelessNetworkInterface):
+        """
+        Adds a wireless network interface to the airspace if it's not already present.
+
+        :param wireless_interface: The wireless network interface to be added.
+        """
+        if wireless_interface.mac_address not in self.wireless_interfaces:
+            self.wireless_interfaces[wireless_interface.mac_address] = wireless_interface
+            if wireless_interface.frequency not in self.wireless_interfaces_by_frequency:
+                self.wireless_interfaces_by_frequency[wireless_interface.frequency] = []
+            self.wireless_interfaces_by_frequency[wireless_interface.frequency].append(wireless_interface)
+
+    def remove_wireless_interface(self, wireless_interface: WirelessNetworkInterface):
+        """
+        Removes a wireless network interface from the airspace if it's present.
+
+        :param wireless_interface: The wireless network interface to be removed.
+        """
+        if wireless_interface.mac_address in self.wireless_interfaces:
+            self.wireless_interfaces.pop(wireless_interface.mac_address)
+            self.wireless_interfaces_by_frequency[wireless_interface.frequency].remove(wireless_interface)
+
+    def clear(self):
+        """
+        Clears all wireless network interfaces and their frequency associations from the airspace.
+
+        After calling this method, the airspace will contain no wireless network interfaces, and transmissions cannot
+        occur until new interfaces are added again.
+        """
+        self.wireless_interfaces.clear()
+        self.wireless_interfaces_by_frequency.clear()
+
+    def reset_bandwidth_load(self):
+        """
+        Resets the bandwidth load tracking for all frequencies in the airspace.
+
+        This method clears the current load metrics for all operating frequencies, effectively setting the load to zero.
+        """
+        self.bandwidth_load = {}
+
+    def can_transmit_frame(self, frame: Frame, sender_network_interface: WirelessNetworkInterface) -> bool:
+        """
+        Determines if a frame can be transmitted by the sender network interface based on the current bandwidth load.
+
+        This method checks if adding the size of the frame to the current bandwidth load of the frequency used by the
+        sender network interface would exceed the maximum allowed bandwidth for that frequency. It returns True if the
+        frame can be transmitted without exceeding the limit, and False otherwise.
+
+        :param frame: The frame to be transmitted, used to check its size against the frequency's bandwidth limit.
+        :param sender_network_interface: The network interface attempting to transmit the frame, used to determine the
+             relevant frequency and its current bandwidth load.
+        :return: True if the frame can be transmitted within the bandwidth limit, False if it would exceed the limit.
+        """
+        if sender_network_interface.frequency not in self.bandwidth_load:
+            self.bandwidth_load[sender_network_interface.frequency] = 0.0
+        return self.bandwidth_load[
+            sender_network_interface.frequency
+        ] + frame.size_Mbits <= self.get_frequency_max_capacity_mbps(sender_network_interface.frequency)
+
+    def transmit(self, frame: Frame, sender_network_interface: WirelessNetworkInterface):
+        """
+        Transmits a frame to all enabled wireless network interfaces on a specific frequency within the airspace.
+
+        This ensures that a wireless interface does not receive its own transmission.
+
+        :param frame: The frame to be transmitted.
+        :param sender_network_interface: The wireless network interface sending the frame. This interface will be
+            excluded from the list of receivers to prevent it from receiving its own transmission.
+        """
+        self.bandwidth_load[sender_network_interface.frequency] += frame.size_Mbits
+        for wireless_interface in self.wireless_interfaces_by_frequency.get(sender_network_interface.frequency, []):
+            if wireless_interface != sender_network_interface and wireless_interface.enabled:
+                wireless_interface.receive_frame(frame)
 
 
 class WirelessNetworkInterface(NetworkInterface, ABC):
@@ -185,13 +344,18 @@ class WirelessNetworkInterface(NetworkInterface, ABC):
         :param frame: The network frame to be sent.
         :return: True if the frame is sent successfully, False if the network interface is disabled.
         """
-        if self.enabled:
-            frame.set_sent_timestamp()
-            self.pcap.capture_outbound(frame)
-            self.airspace.transmit(frame, self)
-            return True
-        # Cannot send Frame as the network interface is not enabled
-        return False
+        if not self.enabled:
+            return False
+        if not self.airspace.can_transmit_frame(frame, self):
+            # Drop frame for now. Queuing will happen here (probably) if it's done in the future.
+            self._connected_node.sys_log.info(f"{self}: Frame dropped as Link is at capacity")
+            return False
+
+        super().send_frame(frame)
+        frame.set_sent_timestamp()
+        self.pcap.capture_outbound(frame)
+        self.airspace.transmit(frame, self)
+        return True
 
     def receive_frame(self, frame: Frame) -> bool:
         """

src/primaite/simulator/network/container.py

@@ -96,6 +96,8 @@ class Network(SimComponent):
         """Apply pre-timestep logic."""
         super().pre_timestep(timestep)
 
+        self.airspace.reset_bandwidth_load()
+
         for node in self.nodes.values():
             node.pre_timestep(timestep)
 

src/primaite/simulator/network/hardware/base.py

@@ -6,7 +6,7 @@ import secrets
 from abc import ABC, abstractmethod
 from ipaddress import IPv4Address, IPv4Network
 from pathlib import Path
-from typing import Any, Dict, Optional, Type, TypeVar, Union
+from typing import Any, Dict, Optional, TypeVar, Union
 
 from prettytable import MARKDOWN, PrettyTable
 from pydantic import BaseModel, Field
@@ -87,7 +87,7 @@ class NetworkInterface(SimComponent, ABC):
     mac_address: str = Field(default_factory=generate_mac_address)
     "The MAC address of the interface."
 
-    speed: int = 100
+    speed: float = 100.0
     "The speed of the interface in Mbps. Default is 100 Mbps."
 
     mtu: int = 1500
@@ -130,10 +130,25 @@ class NetworkInterface(SimComponent, ABC):
 
         More information in user guide and docstring for SimComponent._init_request_manager.
         """
+        _is_network_interface_enabled = NetworkInterface._EnabledValidator(network_interface=self)
+        _is_network_interface_disabled = NetworkInterface._DisabledValidator(network_interface=self)
+
         rm = super()._init_request_manager()
 
-        rm.add_request("enable", RequestType(func=lambda request, context: RequestResponse.from_bool(self.enable())))
-        rm.add_request("disable", RequestType(func=lambda request, context: RequestResponse.from_bool(self.disable())))
+        rm.add_request(
+            "enable",
+            RequestType(
+                func=lambda request, context: RequestResponse.from_bool(self.enable()),
+                validator=_is_network_interface_disabled,
+            ),
+        )
+        rm.add_request(
+            "disable",
+            RequestType(
+                func=lambda request, context: RequestResponse.from_bool(self.disable()),
+                validator=_is_network_interface_enabled,
+            ),
+        )
 
         return rm
 
@@ -332,6 +347,50 @@ class NetworkInterface(SimComponent, ABC):
         super().pre_timestep(timestep)
         self.traffic = {}
 
+    class _EnabledValidator(RequestPermissionValidator):
+        """
+        When requests come in, this validator will only let them through if the NetworkInterface is enabled.
+
+        This is useful because most actions should be being resolved if the NetworkInterface is disabled.
+        """
+
+        network_interface: NetworkInterface
+        """Save a reference to the node instance."""
+
+        def __call__(self, request: RequestFormat, context: Dict) -> bool:
+            """Return whether the NetworkInterface is enabled or not."""
+            return self.network_interface.enabled
+
+        @property
+        def fail_message(self) -> str:
+            """Message that is reported when a request is rejected by this validator."""
+            return (
+                f"Cannot perform request on NetworkInterface "
+                f"'{self.network_interface.mac_address}' because it is not enabled."
+            )
+
+    class _DisabledValidator(RequestPermissionValidator):
+        """
+        When requests come in, this validator will only let them through if the NetworkInterface is disabled.
+
+        This is useful because some actions should be being resolved if the NetworkInterface is disabled.
+        """
+
+        network_interface: NetworkInterface
+        """Save a reference to the node instance."""
+
+        def __call__(self, request: RequestFormat, context: Dict) -> bool:
+            """Return whether the NetworkInterface is disabled or not."""
+            return not self.network_interface.enabled
+
+        @property
+        def fail_message(self) -> str:
+            """Message that is reported when a request is rejected by this validator."""
+            return (
+                f"Cannot perform request on NetworkInterface "
+                f"'{self.network_interface.mac_address}' because it is not disabled."
+            )
+
 
 class WiredNetworkInterface(NetworkInterface, ABC):
     """
@@ -440,14 +499,17 @@ class WiredNetworkInterface(NetworkInterface, ABC):
         :param frame: The network frame to be sent.
         :return: True if the frame is sent, False if the Network Interface is disabled or not connected to a link.
         """
+        if not self.enabled:
+            return False
+        if not self._connected_link.can_transmit_frame(frame):
+            # Drop frame for now. Queuing will happen here (probably) if it's done in the future.
+            self._connected_node.sys_log.info(f"{self}: Frame dropped as Link is at capacity")
+            return False
         super().send_frame(frame)
-        if self.enabled:
-            frame.set_sent_timestamp()
-            self.pcap.capture_outbound(frame)
-            self._connected_link.transmit_frame(sender_nic=self, frame=frame)
-            return True
-        # Cannot send Frame as the NIC is not enabled
-        return False
+        frame.set_sent_timestamp()
+        self.pcap.capture_outbound(frame)
+        self._connected_link.transmit_frame(sender_nic=self, frame=frame)
+        return True
 
     @abstractmethod
     def receive_frame(self, frame: Frame) -> bool:
@@ -678,12 +740,21 @@ class Link(SimComponent):
         """
         return self.endpoint_a.enabled and self.endpoint_b.enabled
 
-    def _can_transmit(self, frame: Frame) -> bool:
+    def can_transmit_frame(self, frame: Frame) -> bool:
+        """
+        Determines whether a frame can be transmitted considering the current Link load and the Link's bandwidth.
+
+        This method assesses if the transmission of a given frame is possible without exceeding the Link's total
+        bandwidth capacity. It checks if the current load of the Link plus the size of the frame (expressed in Mbps)
+        would remain within the defined bandwidth limits. The transmission is only feasible if the Link is active
+        ('up') and the total load including the new frame does not surpass the bandwidth limit.
+
+        :param frame: The frame intended for transmission, which contains its size in Mbps.
+        :return: True if the frame can be transmitted without exceeding the bandwidth limit, False otherwise.
+        """
         if self.is_up:
             frame_size_Mbits = frame.size_Mbits  # noqa - Leaving it as Mbits as this is how they're expressed
-            # return self.current_load + frame_size_Mbits <= self.bandwidth
-            # TODO: re add this check once packet size limiting and MTU checks are implemented
-            return True
+            return self.current_load + frame.size_Mbits <= self.bandwidth
         return False
 
     def transmit_frame(self, sender_nic: WiredNetworkInterface, frame: Frame) -> bool:
@@ -694,11 +765,6 @@ class Link(SimComponent):
         :param frame: The network frame to be sent.
         :return: True if the Frame can be sent, otherwise False.
         """
-        can_transmit = self._can_transmit(frame)
-        if not can_transmit:
-            _LOGGER.debug(f"Cannot transmit frame as {self} is at capacity")
-            return False
-
         receiver = self.endpoint_a
         if receiver == sender_nic:
             receiver = self.endpoint_b
@@ -878,13 +944,88 @@ class Node(SimComponent):
             """Message that is reported when a request is rejected by this validator."""
             return f"Cannot perform request on node '{self.node.hostname}' because it is not turned on."
 
+    class _NodeIsOffValidator(RequestPermissionValidator):
+        """
+        When requests come in, this validator will only let them through if the node is off.
+
+        This is useful because some actions require the node to be in an off state.
+        """
+
+        node: Node
+        """Save a reference to the node instance."""
+
+        def __call__(self, request: RequestFormat, context: Dict) -> bool:
+            """Return whether the node is on or off."""
+            return self.node.operating_state == NodeOperatingState.OFF
+
+        @property
+        def fail_message(self) -> str:
+            """Message that is reported when a request is rejected by this validator."""
+            return f"Cannot perform request on node '{self.node.hostname}' because it is not turned off."
+
     def _init_request_manager(self) -> RequestManager:
         """
         Initialise the request manager.
 
         More information in user guide and docstring for SimComponent._init_request_manager.
         """
+
+        def _install_application(request: RequestFormat, context: Dict) -> RequestResponse:
+            """
+            Allows agents to install applications to the node.
+
+            :param request: list containing the application name as the only element
+            :type request: RequestFormat
+            :param context: additional context for resolving this action, currently unused
+            :type context: dict
+            :return: Request response with a success code if the application was installed.
+            :rtype: RequestResponse
+            """
+            application_name = request[0]
+            if self.software_manager.software.get(application_name):
+                self.sys_log.warning(f"Can't install {application_name}. It's already installed.")
+                return RequestResponse.from_bool(False)
+            application_class = Application._application_registry[application_name]
+            self.software_manager.install(application_class)
+            application_instance = self.software_manager.software.get(application_name)
+            self.applications[application_instance.uuid] = application_instance
+            _LOGGER.debug(f"Added application {application_instance.name} to node {self.hostname}")
+            self._application_request_manager.add_request(
+                application_name, RequestType(func=application_instance._request_manager)
+            )
+            application_instance.install()
+            if application_name in self.software_manager.software:
+                return RequestResponse.from_bool(True)
+            else:
+                return RequestResponse.from_bool(False)
+
+        def _uninstall_application(request: RequestFormat, context: Dict) -> RequestResponse:
+            """
+            Uninstall and completely remove application from this node.
+
+            This method is useful for allowing agents to take this action.
+
+            :param request: list containing the application name as the only element
+            :type request: RequestFormat
+            :param context: additional context for resolving this action, currently unused
+            :type context: dict
+            :return: Request response with a success code if the application was uninstalled.
+            :rtype: RequestResponse
+            """
+            application_name = request[0]
+            if application_name not in self.software_manager.software:
+                self.sys_log.warning(f"Can't uninstall {application_name}. It's not installed.")
+                return RequestResponse.from_bool(False)
+
+            application_instance = self.software_manager.software.get(application_name)
+            self.software_manager.uninstall(application_instance.name)
+            if application_instance.name not in self.software_manager.software:
+                return RequestResponse.from_bool(True)
+            else:
+                return RequestResponse.from_bool(False)
+
         _node_is_on = Node._NodeIsOnValidator(node=self)
+        _node_is_off = Node._NodeIsOffValidator(node=self)
 
         rm = super()._init_request_manager()
         # since there are potentially many services, create an request manager that can map service name
@@ -914,7 +1055,12 @@ class Node(SimComponent):
                 func=lambda request, context: RequestResponse.from_bool(self.power_off()), validator=_node_is_on
             ),
         )
-        rm.add_request("startup", RequestType(func=lambda request, context: RequestResponse.from_bool(self.power_on())))
+        rm.add_request(
+            "startup",
+            RequestType(
+                func=lambda request, context: RequestResponse.from_bool(self.power_on()), validator=_node_is_off
+            ),
+        )
         rm.add_request(
             "reset",
             RequestType(func=lambda request, context: RequestResponse.from_bool(self.reset()), validator=_node_is_on),
@@ -940,25 +1086,8 @@ class Node(SimComponent):
             name="application", request_type=RequestType(func=self._application_manager)
         )
 
-        self._application_manager.add_request(
-            name="install",
-            request_type=RequestType(
-                func=lambda request, context: RequestResponse.from_bool(
-                    self.application_install_action(
-                        application=self._read_application_type(request[0]), ip_address=request[1]
-                    )
-                )
-            ),
-        )
-
-        self._application_manager.add_request(
-            name="uninstall",
-            request_type=RequestType(
-                func=lambda request, context: RequestResponse.from_bool(
-                    self.application_uninstall_action(application=self._read_application_type(request[0]))
-                )
-            ),
-        )
+        self._application_manager.add_request(name="install", request_type=RequestType(func=_install_application))
+        self._application_manager.add_request(name="uninstall", request_type=RequestType(func=_uninstall_application))
 
         return rm
 
@@ -966,29 +1095,6 @@ class Node(SimComponent):
         """Install System Software - software that is usually provided with the OS."""
         pass
 
-    def _read_application_type(self, application_class_str: str) -> Type[IOSoftwareClass]:
-        """Wrapper that converts the string from the request manager into the appropriate class for the application."""
-        if application_class_str == "DoSBot":
-            from primaite.simulator.system.applications.red_applications.dos_bot import DoSBot
-
-            return DoSBot
-        elif application_class_str == "DataManipulationBot":
-            from primaite.simulator.system.applications.red_applications.data_manipulation_bot import (
-                DataManipulationBot,
-            )
-
-            return DataManipulationBot
-        elif application_class_str == "WebBrowser":
-            from primaite.simulator.system.applications.web_browser import WebBrowser
-
-            return WebBrowser
-        elif application_class_str == "RansomwareScript":
-            from primaite.simulator.system.applications.red_applications.ransomware_script import RansomwareScript
-
-            return RansomwareScript
-        else:
-            return 0
-
     def describe_state(self) -> Dict:
         """
         Produce a dictionary describing the current state of this object.
@@ -1417,76 +1523,6 @@ class Node(SimComponent):
         self.sys_log.info(f"Uninstalled application {application.name}")
         self._application_request_manager.remove_request(application.name)
 
-    def application_install_action(self, application: Application, ip_address: Optional[str] = None) -> bool:
-        """
-        Install an application on this node and configure it.
-
-        This method is useful for allowing agents to take this action.
-
-        :param application: Application object that has not been installed on any node yet.
-        :type application: Application
-        :param ip_address: IP address used to configure the application
-        (target IP for the DoSBot or server IP for the DataManipulationBot)
-        :type ip_address: str
-        :return: True if the application is installed successfully, otherwise False.
-        """
-        if application in self:
-            _LOGGER.warning(
-                f"Can't add application {application.__name__}" + f"to node {self.hostname}. It's already installed."
-            )
-            return True
-
-        self.software_manager.install(application)
-        application_instance = self.software_manager.software.get(str(application.__name__))
-        self.applications[application_instance.uuid] = application_instance
-        _LOGGER.debug(f"Added application {application_instance.name} to node {self.hostname}")
-        self._application_request_manager.add_request(
-            application_instance.name, RequestType(func=application_instance._request_manager)
-        )
-
-        # Configure application if additional parameters are given
-        if ip_address:
-            if application_instance.name == "DoSBot":
-                application_instance.configure(target_ip_address=IPv4Address(ip_address))
-            elif application_instance.name == "DataManipulationBot":
-                application_instance.configure(server_ip_address=IPv4Address(ip_address))
-            elif application_instance.name == "RansomwareScript":
-                application_instance.configure(server_ip_address=IPv4Address(ip_address))
-            else:
-                pass
-        application_instance.install()
-        if application_instance.name in self.software_manager.software:
-            return True
-        else:
-            return False
-
-    def application_uninstall_action(self, application: Application) -> bool:
-        """
-        Uninstall and completely remove application from this node.
-
-        This method is useful for allowing agents to take this action.
-
-        :param application: Application object that is currently associated with this node.
-        :type application: Application
-        :return: True if the application is uninstalled successfully, otherwise False.
-        """
-        if application.__name__ not in self.software_manager.software:
-            _LOGGER.warning(
-                f"Can't remove application {application.__name__}" + f"from node {self.hostname}. It's not installed."
-            )
-            return True
-
-        application_instance = self.software_manager.software.get(
-            str(application.__name__)
-        )  # This works because we can't have two applications with the same name on the same node
-        # self.uninstall_application(application_instance)
-        self.software_manager.uninstall(application_instance.name)
-
-        if application_instance.name not in self.software_manager.software:
-            return True
-        else:
-            return False
-
     def _shut_down_actions(self):
         """Actions to perform when the node is shut down."""
         # Turn off all the services in the node

src/primaite/simulator/network/hardware/nodes/network/switch.py

@@ -58,12 +58,16 @@ class SwitchPort(WiredNetworkInterface):
         :param frame: The network frame to be sent.
         :return: A boolean indicating whether the frame was successfully sent.
         """
-        if self.enabled:
-            self.pcap.capture_outbound(frame)
-            self._connected_link.transmit_frame(sender_nic=self, frame=frame)
-            return True
-        # Cannot send Frame as the SwitchPort is not enabled
-        return False
+        if not self.enabled:
+            return False
+        if not self._connected_link.can_transmit_frame(frame):
+            # Drop frame for now. Queuing will happen here (probably) if it's done in the future.
+            self._connected_node.sys_log.info(f"{self}: Frame dropped as Link is at capacity")
+            return False
+
+        self.pcap.capture_outbound(frame)
+        self._connected_link.transmit_frame(sender_nic=self, frame=frame)
+        return True
 
     def receive_frame(self, frame: Frame) -> bool:
         """

src/primaite/simulator/network/hardware/nodes/network/wireless_router.py

@@ -1,6 +1,6 @@
 # © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
 from ipaddress import IPv4Address
-from typing import Any, Dict, Union
+from typing import Any, Dict, Optional, Union
 
 from pydantic import validate_call
 
@@ -153,7 +153,7 @@ class WirelessRouter(Router):
         self,
         ip_address: IPV4Address,
         subnet_mask: IPV4Address,
-        frequency: AirSpaceFrequency = AirSpaceFrequency.WIFI_2_4,
+        frequency: Optional[AirSpaceFrequency] = AirSpaceFrequency.WIFI_2_4,
     ):
         """
         Configures a wireless access point (WAP).
@@ -170,13 +170,20 @@ class WirelessRouter(Router):
             enum. This determines the frequency band (e.g., 2.4 GHz or 5 GHz) the access point will use for wireless
             communication. Default is AirSpaceFrequency.WIFI_2_4.
         """
+        if not frequency:
+            frequency = AirSpaceFrequency.WIFI_2_4
+        self.sys_log.info("Configuring wireless access point")
+
         self.wireless_access_point.disable()  # Temporarily disable the WAP for reconfiguration
+
         network_interface = self.network_interface[1]
+
         network_interface.ip_address = ip_address
         network_interface.subnet_mask = subnet_mask
-        self.sys_log.info(f"Configured WAP {network_interface}")
+
         self.wireless_access_point.frequency = frequency  # Set operating frequency
         self.wireless_access_point.enable()  # Re-enable the WAP with new settings
+        self.sys_log.info(f"Configured WAP {network_interface}")
 
     @property
     def router_interface(self) -> RouterInterface:

src/primaite/simulator/network/transmission/data_link_layer.py

@@ -133,10 +133,11 @@ class Frame(BaseModel):
     def size(self) -> float:  # noqa - Keep it as MBits as this is how they're expressed
         """The size of the Frame in Bytes."""
         # get the payload size if it is a data packet
+        payload_size = 0.0
         if isinstance(self.payload, DataPacket):
-            return self.payload.get_packet_size()
+            payload_size = self.payload.get_packet_size()
 
-        return float(len(self.model_dump_json().encode("utf-8")))
+        return float(len(self.model_dump_json().encode("utf-8"))) + payload_size
 
     @property
     def size_Mbits(self) -> float:  # noqa - Keep it as MBits as this is how they're expressed

src/primaite/simulator/system/applications/application.py

@@ -1,10 +1,12 @@
 # © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+from __future__ import annotations
+
 from abc import abstractmethod
 from enum import Enum
-from typing import Any, Dict, Optional, Set
+from typing import Any, ClassVar, Dict, Optional, Set, Type
 
-from primaite.interface.request import RequestResponse
-from primaite.simulator.core import RequestManager, RequestType
+from primaite.interface.request import RequestFormat, RequestResponse
+from primaite.simulator.core import RequestManager, RequestPermissionValidator, RequestType
 from primaite.simulator.system.software import IOSoftware, SoftwareHealthState
 
 
@@ -39,6 +41,22 @@ class Application(IOSoftware):
     install_countdown: Optional[int] = None
     "The countdown to the end of the installation process. None if not currently installing"
 
+    _application_registry: ClassVar[Dict[str, Type["Application"]]] = {}
+    """Registry of application types. Automatically populated when subclasses are defined."""
+
+    def __init_subclass__(cls, identifier: str, **kwargs: Any) -> None:
+        """
+        Register an application type.
+
+        :param identifier: Uniquely specifies an application class by name. Used for finding items by config.
+        :type identifier: str
+        :raises ValueError: When attempting to register an application with a name that is already allocated.
+        """
+        super().__init_subclass__(**kwargs)
+        if identifier in cls._application_registry:
+            raise ValueError(f"Tried to define new application {identifier}, but this name is already reserved.")
+        cls._application_registry[identifier] = cls
+
     def __init__(self, **kwargs):
         super().__init__(**kwargs)
 
@@ -48,9 +66,27 @@ class Application(IOSoftware):
 
         More information in user guide and docstring for SimComponent._init_request_manager.
         """
-        rm = super()._init_request_manager()
+        _is_application_running = Application._StateValidator(application=self, state=ApplicationOperatingState.RUNNING)
 
-        rm.add_request("close", RequestType(func=lambda request, context: RequestResponse.from_bool(self.close())))
+        rm = super()._init_request_manager()
+        rm.add_request(
+            "scan",
+            RequestType(
+                func=lambda request, context: RequestResponse.from_bool(self.scan()), validator=_is_application_running
+            ),
+        )
+        rm.add_request(
+            "close",
+            RequestType(
+                func=lambda request, context: RequestResponse.from_bool(self.close()), validator=_is_application_running
+            ),
+        )
+        rm.add_request(
+            "fix",
+            RequestType(
+                func=lambda request, context: RequestResponse.from_bool(self.fix()), validator=_is_application_running
+            ),
+        )
         return rm
 
     @abstractmethod
@@ -153,3 +189,28 @@ class Application(IOSoftware):
         :return: True if successful, False otherwise.
         """
         return super().receive(payload=payload, session_id=session_id, **kwargs)
+
+    class _StateValidator(RequestPermissionValidator):
+        """
+        When requests come in, this validator will only let them through if the application is in the correct state.
+
+        This is useful because most actions require the application to be in a specific state.
+        """
+
+        application: Application
+        """Save a reference to the application instance."""
+
+        state: ApplicationOperatingState
+        """The state of the application to validate."""
+
+        def __call__(self, request: RequestFormat, context: Dict) -> bool:
+            """Return whether the application is in the state we are validating for."""
+            return self.application.operating_state == self.state
+
+        @property
+        def fail_message(self) -> str:
+            """Message that is reported when a request is rejected by this validator."""
+            return (
+                f"Cannot perform request on application '{self.application.name}' because it is not in the "
+                f"{self.state.name} state."
+            )

src/primaite/simulator/system/applications/database_client.py

@@ -8,13 +8,14 @@ from uuid import uuid4
 from prettytable import MARKDOWN, PrettyTable
 from pydantic import BaseModel
 
-from primaite.interface.request import RequestResponse
+from primaite.interface.request import RequestFormat, RequestResponse
 from primaite.simulator.core import RequestManager, RequestType
 from primaite.simulator.network.hardware.nodes.host.host_node import HostNode
 from primaite.simulator.network.transmission.network_layer import IPProtocol
 from primaite.simulator.network.transmission.transport_layer import Port
 from primaite.simulator.system.applications.application import Application
 from primaite.simulator.system.core.software_manager import SoftwareManager
+from primaite.utils.validators import IPV4Address
 
 
 class DatabaseClientConnection(BaseModel):
@@ -54,7 +55,7 @@ class DatabaseClientConnection(BaseModel):
             self.client._disconnect(self.connection_id)  # noqa
 
 
-class DatabaseClient(Application):
+class DatabaseClient(Application, identifier="DatabaseClient"):
     """
     A DatabaseClient application.
 
@@ -96,6 +97,14 @@ class DatabaseClient(Application):
         """
         rm = super()._init_request_manager()
         rm.add_request("execute", RequestType(func=lambda request, context: RequestResponse.from_bool(self.execute())))
+
+        def _configure(request: RequestFormat, context: Dict) -> RequestResponse:
+            ip, pw = request[-1].get("server_ip_address"), request[-1].get("server_password")
+            ip = None if ip is None else IPV4Address(ip)
+            success = self.configure(server_ip_address=ip, server_password=pw)
+            return RequestResponse.from_bool(success)
+
+        rm.add_request("configure", RequestType(func=_configure))
         return rm
 
     def execute(self) -> bool:
@@ -141,16 +150,17 @@ class DatabaseClient(Application):
             table.add_row([connection_id, connection.is_active])
         print(table.get_string(sortby="Connection ID"))
 
-    def configure(self, server_ip_address: IPv4Address, server_password: Optional[str] = None):
+    def configure(self, server_ip_address: Optional[IPv4Address] = None, server_password: Optional[str] = None) -> bool:
         """
         Configure the DatabaseClient to communicate with a DatabaseService.
 
         :param server_ip_address: The IP address of the Node the DatabaseService is on.
         :param server_password: The password on the DatabaseService.
         """
-        self.server_ip_address = server_ip_address
-        self.server_password = server_password
+        self.server_ip_address = server_ip_address or self.server_ip_address
+        self.server_password = server_password or self.server_password
         self.sys_log.info(f"{self.name}: Configured the {self.name} with {server_ip_address=}, {server_password=}.")
+        return True
 
     def connect(self) -> bool:
         """Connect the native client connection."""

src/primaite/simulator/system/applications/nmap.py

@@ -44,7 +44,7 @@ class PortScanPayload(SimComponent):
         return state
 
 
-class NMAP(Application):
+class NMAP(Application, identifier="NMAP"):
     """
     A class representing the NMAP application for network scanning.
 

src/primaite/simulator/system/applications/red_applications/data_manipulation_bot.py

@@ -37,7 +37,7 @@ class DataManipulationAttackStage(IntEnum):
     "Signifies that the attack has failed."
 
 
-class DataManipulationBot(Application):
+class DataManipulationBot(Application, identifier="DataManipulationBot"):
     """A bot that simulates a script which performs a SQL injection attack."""
 
     payload: Optional[str] = None

src/primaite/simulator/system/applications/red_applications/dos_bot.py

@@ -1,11 +1,11 @@
 # © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
 from enum import IntEnum
 from ipaddress import IPv4Address
-from typing import Optional
+from typing import Dict, Optional
 
 from primaite import getLogger
 from primaite.game.science import simulate_trial
-from primaite.interface.request import RequestResponse
+from primaite.interface.request import RequestFormat, RequestResponse
 from primaite.simulator.core import RequestManager, RequestType
 from primaite.simulator.network.transmission.transport_layer import Port
 from primaite.simulator.system.applications.database_client import DatabaseClient
@@ -29,7 +29,7 @@ class DoSAttackStage(IntEnum):
     "Attack is completed."
 
 
-class DoSBot(DatabaseClient):
+class DoSBot(DatabaseClient, identifier="DoSBot"):
     """A bot that simulates a Denial of Service attack."""
 
     target_ip_address: Optional[IPv4Address] = None
@@ -71,6 +71,24 @@ class DoSBot(DatabaseClient):
             request_type=RequestType(func=lambda request, context: RequestResponse.from_bool(self.run())),
         )
 
+        def _configure(request: RequestFormat, context: Dict) -> RequestResponse:
+            """
+            Configure the DoSBot.
+
+            :param request: List with one element that is a dict of options to pass to the configure method.
+            :type request: RequestFormat
+            :param context: additional context for resolving this action, currently unused
+            :type context: dict
+            :return: Request Response object with a success code determining if the configuration was successful.
+            :rtype: RequestResponse
+            """
+            if "target_ip_address" in request[-1]:
+                request[-1]["target_ip_address"] = IPv4Address(request[-1]["target_ip_address"])
+            if "target_port" in request[-1]:
+                request[-1]["target_port"] = Port[request[-1]["target_port"]]
+            return RequestResponse.from_bool(self.configure(**request[-1]))
+
+        rm.add_request("configure", request_type=RequestType(func=_configure))
         return rm
 
     def configure(
@@ -82,7 +100,7 @@ class DoSBot(DatabaseClient):
         port_scan_p_of_success: float = 0.1,
         dos_intensity: float = 1.0,
         max_sessions: int = 1000,
-    ):
+    ) -> bool:
         """
         Configure the Denial of Service bot.
 
@@ -90,10 +108,12 @@ class DoSBot(DatabaseClient):
         :param: target_port: The port of the target service. Optional - Default is `Port.HTTP`
         :param: payload: The payload the DoS Bot will throw at the target service. Optional - Default is `None`
         :param: repeat: If True, the bot will maintain the attack. Optional - Default is `True`
-        :param: port_scan_p_of_success: The chance of the port scan being sucessful. Optional - Default is 0.1 (10%)
+        :param: port_scan_p_of_success: The chance of the port scan being successful. Optional - Default is 0.1 (10%)
         :param: dos_intensity: The intensity of the DoS attack.
             Multiplied with the application's max session - Default is 1.0
         :param: max_sessions: The maximum number of sessions the DoS bot will attack with. Optional - Default is 1000
+        :return: Always returns True
+        :rtype: bool
         """
         self.target_ip_address = target_ip_address
         self.target_port = target_port
@@ -106,6 +126,7 @@ class DoSBot(DatabaseClient):
             f"{self.name}: Configured the {self.name} with {target_ip_address=}, {target_port=}, {payload=}, "
             f"{repeat=}, {port_scan_p_of_success=}, {dos_intensity=}, {max_sessions=}."
         )
+        return True
 
     def run(self) -> bool:
         """Run the Denial of Service Bot."""
@@ -117,6 +138,9 @@ class DoSBot(DatabaseClient):
         The main application loop for the Denial of Service bot.
 
         The loop goes through the stages of a DoS attack.
+
+        :return: True if the application loop could be executed, False otherwise.
+        :rtype: bool
         """
         if not self._can_perform_action():
             return False
@@ -126,7 +150,7 @@ class DoSBot(DatabaseClient):
             self.sys_log.warning(
                 f"{self.name} is not properly configured. {self.target_ip_address=}, {self.target_port=}"
             )
-            return True
+            return False
 
         self.clear_connections()
         self._perform_port_scan(p_of_success=self.port_scan_p_of_success)

src/primaite/simulator/system/applications/red_applications/ransomware_script.py

@@ -2,7 +2,7 @@
 from ipaddress import IPv4Address
 from typing import Dict, Optional
 
-from primaite.interface.request import RequestResponse
+from primaite.interface.request import RequestFormat, RequestResponse
 from primaite.simulator.core import RequestManager, RequestType
 from primaite.simulator.network.transmission.network_layer import IPProtocol
 from primaite.simulator.network.transmission.transport_layer import Port
@@ -10,7 +10,7 @@ from primaite.simulator.system.applications.application import Application
 from primaite.simulator.system.applications.database_client import DatabaseClient, DatabaseClientConnection
 
 
-class RansomwareScript(Application):
+class RansomwareScript(Application, identifier="RansomwareScript"):
     """Ransomware Kill Chain - Designed to be used by the TAP001 Agent on the example layout Network.
 
     :ivar payload: The attack stage query payload. (Default ENCRYPT)
@@ -62,6 +62,25 @@ class RansomwareScript(Application):
             name="execute",
             request_type=RequestType(func=lambda request, context: RequestResponse.from_bool(self.attack())),
         )
+
+        def _configure(request: RequestFormat, context: Dict) -> RequestResponse:
+            """
+            Request for configuring the target database and payload.
+
+            :param request: Request with one element contianing a dict of parameters for the configure method.
+            :type request: RequestFormat
+            :param context: additional context for resolving this action, currently unused
+            :type context: dict
+            :return: RequestResponse object with a success code reflecting whether the configuration could be applied.
+            :rtype: RequestResponse
+            """
+            ip = request[-1].get("server_ip_address")
+            ip = None if ip is None else IPv4Address(ip)
+            pw = request[-1].get("server_password")
+            payload = request[-1].get("payload")
+            return RequestResponse.from_bool(self.configure(ip, pw, payload))
+
+        rm.add_request("configure", request_type=RequestType(func=_configure))
         return rm
 
     def run(self) -> bool:
@@ -88,10 +107,10 @@ class RansomwareScript(Application):
 
     def configure(
         self,
-        server_ip_address: IPv4Address,
+        server_ip_address: Optional[IPv4Address] = None,
         server_password: Optional[str] = None,
         payload: Optional[str] = None,
-    ):
+    ) -> bool:
         """
         Configure the Ransomware Script to communicate with a DatabaseService.
 
@@ -108,6 +127,7 @@ class RansomwareScript(Application):
         self.sys_log.info(
             f"{self.name}: Configured the {self.name} with {server_ip_address=}, {payload=}, {server_password=}."
         )
+        return True
 
     def attack(self) -> bool:
         """Perform the attack steps after opening the application."""

src/primaite/simulator/system/applications/web_browser.py

@@ -23,7 +23,7 @@ from primaite.simulator.system.services.dns.dns_client import DNSClient
 _LOGGER = getLogger(__name__)
 
 
-class WebBrowser(Application):
+class WebBrowser(Application, identifier="WebBrowser"):
     """
     Represents a web browser in the simulation environment.
 

src/primaite/simulator/system/services/database/database_service.py

@@ -197,7 +197,11 @@ class DatabaseService(Service):
             status_code = 503  # service unavailable
             if self.health_state_actual == SoftwareHealthState.OVERWHELMED:
                 self.sys_log.error(f"{self.name}: Connect request for {src_ip=} declined. Service is at capacity.")
-            if self.health_state_actual == SoftwareHealthState.GOOD:
+            if self.health_state_actual in [
+                SoftwareHealthState.GOOD,
+                SoftwareHealthState.FIXING,
+                SoftwareHealthState.COMPROMISED,
+            ]:
                 if self.password == password:
                     status_code = 200  # ok
                     connection_id = self._generate_connection_id()
@@ -244,6 +248,10 @@ class DatabaseService(Service):
             self.sys_log.error(f"{self.name}: Failed to run {query} because the database file is missing.")
             return {"status_code": 404, "type": "sql", "data": False}
 
+        if self.health_state_actual is not SoftwareHealthState.GOOD:
+            self.sys_log.error(f"{self.name}: Failed to run {query} because the database service is unavailable.")
+            return {"status_code": 500, "type": "sql", "data": False}
+
         if query == "SELECT":
             if self.db_file.health_status == FileSystemItemHealthStatus.CORRUPT:
                 return {

src/primaite/simulator/system/services/service.py

@@ -1,11 +1,13 @@
 # © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+from __future__ import annotations
+
 from abc import abstractmethod
 from enum import Enum
 from typing import Any, Dict, Optional
 
 from primaite import getLogger
-from primaite.interface.request import RequestResponse
-from primaite.simulator.core import RequestManager, RequestType
+from primaite.interface.request import RequestFormat, RequestResponse
+from primaite.simulator.core import RequestManager, RequestPermissionValidator, RequestType
 from primaite.simulator.system.software import IOSoftware, SoftwareHealthState
 
 _LOGGER = getLogger(__name__)
@@ -40,6 +42,7 @@ class Service(IOSoftware):
 
     restart_duration: int = 5
     "How many timesteps does it take to restart this service."
+
     restart_countdown: Optional[int] = None
     "If currently restarting, how many timesteps remain until the restart is finished."
 
@@ -86,15 +89,61 @@ class Service(IOSoftware):
 
         More information in user guide and docstring for SimComponent._init_request_manager.
         """
+        _is_service_running = Service._StateValidator(service=self, state=ServiceOperatingState.RUNNING)
+        _is_service_stopped = Service._StateValidator(service=self, state=ServiceOperatingState.STOPPED)
+        _is_service_paused = Service._StateValidator(service=self, state=ServiceOperatingState.PAUSED)
+        _is_service_disabled = Service._StateValidator(service=self, state=ServiceOperatingState.DISABLED)
+
         rm = super()._init_request_manager()
-        rm.add_request("scan", RequestType(func=lambda request, context: RequestResponse.from_bool(self.scan())))
-        rm.add_request("stop", RequestType(func=lambda request, context: RequestResponse.from_bool(self.stop())))
-        rm.add_request("start", RequestType(func=lambda request, context: RequestResponse.from_bool(self.start())))
-        rm.add_request("pause", RequestType(func=lambda request, context: RequestResponse.from_bool(self.pause())))
-        rm.add_request("resume", RequestType(func=lambda request, context: RequestResponse.from_bool(self.resume())))
-        rm.add_request("restart", RequestType(func=lambda request, context: RequestResponse.from_bool(self.restart())))
+        rm.add_request(
+            "scan",
+            RequestType(
+                func=lambda request, context: RequestResponse.from_bool(self.scan()), validator=_is_service_running
+            ),
+        )
+        rm.add_request(
+            "stop",
+            RequestType(
+                func=lambda request, context: RequestResponse.from_bool(self.stop()), validator=_is_service_running
+            ),
+        )
+        rm.add_request(
+            "start",
+            RequestType(
+                func=lambda request, context: RequestResponse.from_bool(self.start()), validator=_is_service_stopped
+            ),
+        )
+        rm.add_request(
+            "pause",
+            RequestType(
+                func=lambda request, context: RequestResponse.from_bool(self.pause()), validator=_is_service_running
+            ),
+        )
+        rm.add_request(
+            "resume",
+            RequestType(
+                func=lambda request, context: RequestResponse.from_bool(self.resume()), validator=_is_service_paused
+            ),
+        )
+        rm.add_request(
+            "restart",
+            RequestType(
+                func=lambda request, context: RequestResponse.from_bool(self.restart()), validator=_is_service_running
+            ),
+        )
         rm.add_request("disable", RequestType(func=lambda request, context: RequestResponse.from_bool(self.disable())))
-        rm.add_request("enable", RequestType(func=lambda request, context: RequestResponse.from_bool(self.enable())))
+        rm.add_request(
+            "enable",
+            RequestType(
+                func=lambda request, context: RequestResponse.from_bool(self.enable()), validator=_is_service_disabled
+            ),
+        )
+        rm.add_request(
+            "fix",
+            RequestType(
+                func=lambda request, context: RequestResponse.from_bool(self.fix()), validator=_is_service_running
+            ),
+        )
         return rm
 
     @abstractmethod
@@ -191,3 +240,28 @@ class Service(IOSoftware):
                 self.sys_log.debug(f"Restarting finished for service {self.name}")
                 self.operating_state = ServiceOperatingState.RUNNING
             self.restart_countdown -= 1
+
+    class _StateValidator(RequestPermissionValidator):
+        """
+        When requests come in, this validator will only let them through if the service is in the correct state.
+
+        This is useful because most actions require the service to be in a specific state.
+        """
+
+        service: Service
+        """Save a reference to the service instance."""
+
+        state: ServiceOperatingState
+        """The state of the service to validate."""
+
+        def __call__(self, request: RequestFormat, context: Dict) -> bool:
+            """Return whether the service is in the state we are validating for."""
+            return self.service.operating_state == self.state
+
+        @property
+        def fail_message(self) -> str:
+            """Message that is reported when a request is rejected by this validator."""
+            return (
+                f"Cannot perform request on service '{self.service.name}' because it is not in the "
+                f"{self.state.name} state."
+            )

src/primaite/utils/cli/dev_cli.py

@@ -76,18 +76,37 @@ def config_callback(
         LogLevel,
         typer.Option(
             "--sys-log-level",
-            "-level",
+            "-slevel",
             click_type=click.Choice(LogLevel._member_names_, case_sensitive=False),
             help="The level of system logs to output.",
             show_default=False,
         ),
     ] = None,
+    agent_log_level: Annotated[
+        LogLevel,
+        typer.Option(
+            "--agent-log-level",
+            "-alevel",
+            click_type=click.Choice(LogLevel._member_names_, case_sensitive=False),
+            help="The level of agent behaviour logs to output.",
+            show_default=False,
+        ),
+    ] = None,
     output_sys_logs: Annotated[
         bool,
         typer.Option(
             "--output-sys-logs/--no-sys-logs", "-sys/-nsys", help="Output system logs to file.", show_default=False
         ),
     ] = None,
+    output_agent_logs: Annotated[
+        bool,
+        typer.Option(
+            "--output-agent-logs/--no-agent-logs",
+            "-agent/-nagent",
+            help="Output agent logs to file.",
+            show_default=False,
+        ),
+    ] = None,
     output_pcap_logs: Annotated[
         bool,
         typer.Option(
@@ -109,10 +128,18 @@ def config_callback(
         PRIMAITE_CONFIG["developer_mode"]["sys_log_level"] = ctx.params.get("sys_log_level")
         print(f"PrimAITE dev-mode config updated sys_log_level={ctx.params.get('sys_log_level')}")
 
+    if ctx.params.get("agent_log_level") is not None:
+        PRIMAITE_CONFIG["developer_mode"]["agent_log_level"] = ctx.params.get("agent_log_level")
+        print(f"PrimAITE dev-mode config updated agent_log_level={ctx.params.get('agent_log_level')}")
+
     if output_sys_logs is not None:
         PRIMAITE_CONFIG["developer_mode"]["output_sys_logs"] = output_sys_logs
         print(f"PrimAITE dev-mode config updated {output_sys_logs=}")
 
+    if output_agent_logs is not None:
+        PRIMAITE_CONFIG["developer_mode"]["output_agent_logs"] = output_agent_logs
+        print(f"PrimAITE dev-mode config updated {output_agent_logs=}")
+
     if output_pcap_logs is not None:
         PRIMAITE_CONFIG["developer_mode"]["output_pcap_logs"] = output_pcap_logs
         print(f"PrimAITE dev-mode config updated {output_pcap_logs=}")

tests/assets/configs/action_penalty.yaml

@@ -0,0 +1,792 @@
+io_settings:
+  save_agent_actions: false
+  save_step_metadata: false
+  save_pcap_logs: false
+  save_sys_logs: false
+
+
+game:
+  max_episode_length: 256
+  ports:
+  - HTTP
+  - POSTGRES_SERVER
+  protocols:
+  - ICMP
+  - TCP
+  - UDP
+  thresholds:
+    nmne:
+      high: 10
+      medium: 5
+      low: 0
+
+agents:
+
+  - ref: defender
+    team: BLUE
+    type: ProxyAgent
+
+    observation_space:
+      type: CUSTOM
+      options:
+        components:
+          - type: NODES
+            label: NODES
+            options:
+              hosts:
+                - hostname: domain_controller
+                - hostname: web_server
+                  services:
+                    - service_name: WebServer
+                - hostname: database_server
+                  folders:
+                    - folder_name: database
+                      files:
+                      - file_name: database.db
+                - hostname: backup_server
+                - hostname: security_suite
+                - hostname: client_1
+                - hostname: client_2
+              num_services: 1
+              num_applications: 0
+              num_folders: 1
+              num_files: 1
+              num_nics: 2
+              include_num_access: false
+              include_nmne: true
+              routers:
+                - hostname: router_1
+              num_ports: 0
+              ip_list:
+                - 192.168.1.10
+                - 192.168.1.12
+                - 192.168.1.14
+                - 192.168.1.16
+                - 192.168.1.110
+                - 192.168.10.21
+                - 192.168.10.22
+                - 192.168.10.110
+              wildcard_list:
+                - 0.0.0.1
+              port_list:
+                - 80
+                - 5432
+              protocol_list:
+                - ICMP
+                - TCP
+                - UDP
+              num_rules: 10
+
+          - type: LINKS
+            label: LINKS
+            options:
+              link_references:
+                - router_1:eth-1<->switch_1:eth-8
+                - router_1:eth-2<->switch_2:eth-8
+                - switch_1:eth-1<->domain_controller:eth-1
+                - switch_1:eth-2<->web_server:eth-1
+                - switch_1:eth-3<->database_server:eth-1
+                - switch_1:eth-4<->backup_server:eth-1
+                - switch_1:eth-7<->security_suite:eth-1
+                - switch_2:eth-1<->client_1:eth-1
+                - switch_2:eth-2<->client_2:eth-1
+                - switch_2:eth-7<->security_suite:eth-2
+          - type: "NONE"
+            label: ICS
+            options: {}
+
+    action_space:
+      action_list:
+        - type: DONOTHING
+        - type: NODE_SERVICE_SCAN
+        - type: NODE_SERVICE_STOP
+        - type: NODE_SERVICE_START
+        - type: NODE_SERVICE_PAUSE
+        - type: NODE_SERVICE_RESUME
+        - type: NODE_SERVICE_RESTART
+        - type: NODE_SERVICE_DISABLE
+        - type: NODE_SERVICE_ENABLE
+        - type: NODE_SERVICE_FIX
+        - type: NODE_FILE_SCAN
+        - type: NODE_FILE_CHECKHASH
+        - type: NODE_FILE_DELETE
+        - type: NODE_FILE_REPAIR
+        - type: NODE_FILE_RESTORE
+        - type: NODE_FOLDER_SCAN
+        - type: NODE_FOLDER_CHECKHASH
+        - type: NODE_FOLDER_REPAIR
+        - type: NODE_FOLDER_RESTORE
+        - type: NODE_OS_SCAN
+        - type: NODE_SHUTDOWN
+        - type: NODE_STARTUP
+        - type: NODE_RESET
+        - type: ROUTER_ACL_ADDRULE
+        - type: ROUTER_ACL_REMOVERULE
+        - type: HOST_NIC_ENABLE
+        - type: HOST_NIC_DISABLE
+
+      action_map:
+          0:
+            action: DONOTHING
+            options: {}
+          # scan webapp service
+          1:
+            action: NODE_SERVICE_SCAN
+            options:
+              node_id: 1
+              service_id: 0
+          # stop webapp service
+          2:
+            action: NODE_SERVICE_STOP
+            options:
+              node_id: 1
+              service_id: 0
+          # start webapp service
+          3:
+            action: "NODE_SERVICE_START"
+            options:
+              node_id: 1
+              service_id: 0
+          4:
+            action: "NODE_SERVICE_PAUSE"
+            options:
+              node_id: 1
+              service_id: 0
+          5:
+            action: "NODE_SERVICE_RESUME"
+            options:
+              node_id: 1
+              service_id: 0
+          6:
+            action: "NODE_SERVICE_RESTART"
+            options:
+              node_id: 1
+              service_id: 0
+          7:
+            action: "NODE_SERVICE_DISABLE"
+            options:
+              node_id: 1
+              service_id: 0
+          8:
+            action: "NODE_SERVICE_ENABLE"
+            options:
+              node_id: 1
+              service_id: 0
+          9: # check database.db file
+            action: "NODE_FILE_SCAN"
+            options:
+              node_id: 2
+              folder_id: 0
+              file_id: 0
+          10:
+            action: "NODE_FILE_CHECKHASH"
+            options:
+              node_id: 2
+              folder_id: 0
+              file_id: 0
+          11:
+            action: "NODE_FILE_DELETE"
+            options:
+              node_id: 2
+              folder_id: 0
+              file_id: 0
+          12:
+            action: "NODE_FILE_REPAIR"
+            options:
+              node_id: 2
+              folder_id: 0
+              file_id: 0
+          13:
+            action: "NODE_SERVICE_FIX"
+            options:
+              node_id: 2
+              service_id: 0
+          14:
+            action: "NODE_FOLDER_SCAN"
+            options:
+              node_id: 2
+              folder_id: 0
+          15:
+            action: "NODE_FOLDER_CHECKHASH"
+            options:
+              node_id: 2
+              folder_id: 0
+          16:
+            action: "NODE_FOLDER_REPAIR"
+            options:
+              node_id: 2
+              folder_id: 0
+          17:
+            action: "NODE_FOLDER_RESTORE"
+            options:
+              node_id: 2
+              folder_id: 0
+          18:
+            action: "NODE_OS_SCAN"
+            options:
+              node_id: 0
+          19:
+            action: "NODE_SHUTDOWN"
+            options:
+              node_id: 0
+          20:
+            action: NODE_STARTUP
+            options:
+              node_id: 0
+          21:
+            action: NODE_RESET
+            options:
+              node_id: 0
+          22:
+            action: "NODE_OS_SCAN"
+            options:
+              node_id: 1
+          23:
+            action: "NODE_SHUTDOWN"
+            options:
+              node_id: 1
+          24:
+            action: NODE_STARTUP
+            options:
+              node_id: 1
+          25:
+            action: NODE_RESET
+            options:
+              node_id: 1
+          26: # old action num: 18
+            action: "NODE_OS_SCAN"
+            options:
+                node_id: 2
+          27:
+            action: "NODE_SHUTDOWN"
+            options:
+              node_id: 2
+          28:
+            action: NODE_STARTUP
+            options:
+              node_id: 2
+          29:
+            action: NODE_RESET
+            options:
+              node_id: 2
+          30:
+            action: "NODE_OS_SCAN"
+            options:
+              node_id: 3
+          31:
+            action: "NODE_SHUTDOWN"
+            options:
+              node_id: 3
+          32:
+            action: NODE_STARTUP
+            options:
+              node_id: 3
+          33:
+            action: NODE_RESET
+            options:
+              node_id: 3
+          34:
+            action: "NODE_OS_SCAN"
+            options:
+              node_id: 4
+          35:
+            action: "NODE_SHUTDOWN"
+            options:
+              node_id: 4
+          36:
+            action: NODE_STARTUP
+            options:
+              node_id: 4
+          37:
+            action: NODE_RESET
+            options:
+              node_id: 4
+          38:
+            action: "NODE_OS_SCAN"
+            options:
+              node_id: 5
+          39: # old action num: 19 # shutdown client 1
+            action: "NODE_SHUTDOWN"
+            options:
+              node_id: 5
+          40: # old action num: 20
+            action: NODE_STARTUP
+            options:
+              node_id: 5
+          41: # old action num: 21
+            action: NODE_RESET
+            options:
+              node_id: 5
+          42:
+            action: "NODE_OS_SCAN"
+            options:
+              node_id: 6
+          43:
+            action: "NODE_SHUTDOWN"
+            options:
+              node_id: 6
+          44:
+            action: NODE_STARTUP
+            options:
+              node_id: 6
+          45:
+            action: NODE_RESET
+            options:
+              node_id: 6
+
+          46: # old action num: 22 # "ACL: ADDRULE - Block outgoing traffic from client 1"
+            action: "ROUTER_ACL_ADDRULE"
+            options:
+                target_router_nodename: router_1
+                position: 1
+                permission: 2
+                source_ip_id: 7 # client 1
+                dest_ip_id: 1 # ALL
+                source_port_id: 1
+                dest_port_id: 1
+                protocol_id: 1
+                source_wildcard_id: 0
+                dest_wildcard_id: 0
+          47: # old action num: 23 # "ACL: ADDRULE - Block outgoing traffic from client 2"
+            action: "ROUTER_ACL_ADDRULE"
+            options:
+                target_router_nodename: router_1
+                position: 2
+                permission: 2
+                source_ip_id: 8 # client 2
+                dest_ip_id: 1 # ALL
+                source_port_id: 1
+                dest_port_id: 1
+                protocol_id: 1
+                source_wildcard_id: 0
+                dest_wildcard_id: 0
+          48: # old action num: 24 # block tcp traffic from client 1 to web app
+            action: "ROUTER_ACL_ADDRULE"
+            options:
+                target_router_nodename: router_1
+                position: 3
+                permission: 2
+                source_ip_id: 7 # client 1
+                dest_ip_id: 3 # web server
+                source_port_id: 1
+                dest_port_id: 1
+                protocol_id: 3
+                source_wildcard_id: 0
+                dest_wildcard_id: 0
+          49: # old action num: 25 # block tcp traffic from client 2 to web app
+            action: "ROUTER_ACL_ADDRULE"
+            options:
+                target_router_nodename: router_1
+                position: 4
+                permission: 2
+                source_ip_id: 8 # client 2
+                dest_ip_id: 3 # web server
+                source_port_id: 1
+                dest_port_id: 1
+                protocol_id: 3
+                source_wildcard_id: 0
+                dest_wildcard_id: 0
+          50: # old action num: 26
+            action: "ROUTER_ACL_ADDRULE"
+            options:
+                target_router_nodename: router_1
+                position: 5
+                permission: 2
+                source_ip_id: 7 # client 1
+                dest_ip_id: 4 # database
+                source_port_id: 1
+                dest_port_id: 1
+                protocol_id: 3
+                source_wildcard_id: 0
+                dest_wildcard_id: 0
+          51: # old action num: 27
+            action: "ROUTER_ACL_ADDRULE"
+            options:
+                target_router_nodename: router_1
+                position: 6
+                permission: 2
+                source_ip_id: 8 # client 2
+                dest_ip_id: 4 # database
+                source_port_id: 1
+                dest_port_id: 1
+                protocol_id: 3
+                source_wildcard_id: 0
+                dest_wildcard_id: 0
+          52: # old action num: 28
+            action: "ROUTER_ACL_REMOVERULE"
+            options:
+                target_router_nodename: router_1
+                position: 0
+          53: # old action num: 29
+            action: "ROUTER_ACL_REMOVERULE"
+            options:
+                target_router_nodename: router_1
+                position: 1
+          54: # old action num: 30
+            action: "ROUTER_ACL_REMOVERULE"
+            options:
+                target_router_nodename: router_1
+                position: 2
+          55: # old action num: 31
+            action: "ROUTER_ACL_REMOVERULE"
+            options:
+                target_router_nodename: router_1
+                position: 3
+          56: # old action num: 32
+            action: "ROUTER_ACL_REMOVERULE"
+            options:
+                target_router_nodename: router_1
+                position: 4
+          57: # old action num: 33
+            action: "ROUTER_ACL_REMOVERULE"
+            options:
+                target_router_nodename: router_1
+                position: 5
+          58: # old action num: 34
+            action: "ROUTER_ACL_REMOVERULE"
+            options:
+                target_router_nodename: router_1
+                position: 6
+          59: # old action num: 35
+            action: "ROUTER_ACL_REMOVERULE"
+            options:
+                target_router_nodename: router_1
+                position: 7
+          60: # old action num: 36
+            action: "ROUTER_ACL_REMOVERULE"
+            options:
+                target_router_nodename: router_1
+                position: 8
+          61: # old action num: 37
+            action: "ROUTER_ACL_REMOVERULE"
+            options:
+                target_router_nodename: router_1
+                position: 9
+          62: # old action num: 38
+            action: "HOST_NIC_DISABLE"
+            options:
+                node_id: 0
+                nic_id: 0
+          63: # old action num: 39
+            action: "HOST_NIC_ENABLE"
+            options:
+                node_id: 0
+                nic_id: 0
+          64: # old action num: 40
+            action: "HOST_NIC_DISABLE"
+            options:
+                node_id: 1
+                nic_id: 0
+          65: # old action num: 41
+            action: "HOST_NIC_ENABLE"
+            options:
+                node_id: 1
+                nic_id: 0
+          66: # old action num: 42
+            action: "HOST_NIC_DISABLE"
+            options:
+                node_id: 2
+                nic_id: 0
+          67: # old action num: 43
+            action: "HOST_NIC_ENABLE"
+            options:
+                node_id: 2
+                nic_id: 0
+          68: # old action num: 44
+            action: "HOST_NIC_DISABLE"
+            options:
+                node_id: 3
+                nic_id: 0
+          69: # old action num: 45
+            action: "HOST_NIC_ENABLE"
+            options:
+                node_id: 3
+                nic_id: 0
+          70: # old action num: 46
+            action: "HOST_NIC_DISABLE"
+            options:
+                node_id: 4
+                nic_id: 0
+          71: # old action num: 47
+            action: "HOST_NIC_ENABLE"
+            options:
+                node_id: 4
+                nic_id: 0
+          72: # old action num: 48
+            action: "HOST_NIC_DISABLE"
+            options:
+                node_id: 4
+                nic_id: 1
+          73: # old action num: 49
+            action: "HOST_NIC_ENABLE"
+            options:
+                node_id: 4
+                nic_id: 1
+          74: # old action num: 50
+            action: "HOST_NIC_DISABLE"
+            options:
+                node_id: 5
+                nic_id: 0
+          75: # old action num: 51
+            action: "HOST_NIC_ENABLE"
+            options:
+                node_id: 5
+                nic_id: 0
+          76: # old action num: 52
+            action: "HOST_NIC_DISABLE"
+            options:
+                node_id: 6
+                nic_id: 0
+          77: # old action num: 53
+            action: "HOST_NIC_ENABLE"
+            options:
+                node_id: 6
+                nic_id: 0
+
+
+
+      options:
+        nodes:
+        - node_name: domain_controller
+        - node_name: web_server
+          applications:
+          - application_name: DatabaseClient
+          services:
+          - service_name: WebServer
+        - node_name: database_server
+          folders:
+          - folder_name: database
+            files:
+            - file_name: database.db
+          services:
+          - service_name: DatabaseService
+        - node_name: backup_server
+        - node_name: security_suite
+        - node_name: client_1
+        - node_name: client_2
+
+        max_folders_per_node: 2
+        max_files_per_folder: 2
+        max_services_per_node: 2
+        max_nics_per_node: 8
+        max_acl_rules: 10
+        ip_list:
+          - 192.168.1.10
+          - 192.168.1.12
+          - 192.168.1.14
+          - 192.168.1.16
+          - 192.168.1.110
+          - 192.168.10.21
+          - 192.168.10.22
+          - 192.168.10.110
+
+
+    reward_function:
+      reward_components:
+        - type: ACTION_PENALTY
+          weight: 1.0
+          options:
+            action_penalty: -0.75
+            do_nothing_penalty: 0.125
+
+
+    agent_settings:
+      flatten_obs: true
+
+
+
+simulation:
+  network:
+    nmne_config:
+      capture_nmne: true
+      nmne_capture_keywords:
+        - DELETE
+    nodes:
+
+    - hostname: router_1
+      type: router
+      num_ports: 5
+      ports:
+        1:
+          ip_address: 192.168.1.1
+          subnet_mask: 255.255.255.0
+        2:
+          ip_address: 192.168.10.1
+          subnet_mask: 255.255.255.0
+      acl:
+        18:
+          action: PERMIT
+          src_port: POSTGRES_SERVER
+          dst_port: POSTGRES_SERVER
+        19:
+          action: PERMIT
+          src_port: DNS
+          dst_port: DNS
+        20:
+          action: PERMIT
+          src_port: FTP
+          dst_port: FTP
+        21:
+          action: PERMIT
+          src_port: HTTP
+          dst_port: HTTP
+        22:
+          action: PERMIT
+          src_port: ARP
+          dst_port: ARP
+        23:
+          action: PERMIT
+          protocol: ICMP
+
+    - hostname: switch_1
+      type: switch
+      num_ports: 8
+
+    - hostname: switch_2
+      type: switch
+      num_ports: 8
+
+    - hostname: domain_controller
+      type: server
+      ip_address: 192.168.1.10
+      subnet_mask: 255.255.255.0
+      default_gateway: 192.168.1.1
+      services:
+      - type: DNSServer
+        options:
+          domain_mapping:
+            arcd.com: 192.168.1.12 # web server
+
+    - hostname: web_server
+      type: server
+      ip_address: 192.168.1.12
+      subnet_mask: 255.255.255.0
+      default_gateway: 192.168.1.1
+      dns_server: 192.168.1.10
+      services:
+      - type: WebServer
+      applications:
+      - type: DatabaseClient
+        options:
+          db_server_ip: 192.168.1.14
+
+
+    - hostname: database_server
+      type: server
+      ip_address: 192.168.1.14
+      subnet_mask: 255.255.255.0
+      default_gateway: 192.168.1.1
+      dns_server: 192.168.1.10
+      services:
+      - type: DatabaseService
+        options:
+          backup_server_ip: 192.168.1.16
+      - type: FTPClient
+
+    - hostname: backup_server
+      type: server
+      ip_address: 192.168.1.16
+      subnet_mask: 255.255.255.0
+      default_gateway: 192.168.1.1
+      dns_server: 192.168.1.10
+      services:
+      - type: FTPServer
+
+    - hostname: security_suite
+      type: server
+      ip_address: 192.168.1.110
+      subnet_mask: 255.255.255.0
+      default_gateway: 192.168.1.1
+      dns_server: 192.168.1.10
+      network_interfaces:
+        2: # unfortunately this number is currently meaningless, they're just added in order and take up the next available slot
+          ip_address: 192.168.10.110
+          subnet_mask: 255.255.255.0
+
+    - hostname: client_1
+      type: computer
+      ip_address: 192.168.10.21
+      subnet_mask: 255.255.255.0
+      default_gateway: 192.168.10.1
+      dns_server: 192.168.1.10
+      applications:
+      - type: DataManipulationBot
+        options:
+          port_scan_p_of_success: 0.8
+          data_manipulation_p_of_success: 0.8
+          payload: "DELETE"
+          server_ip: 192.168.1.14
+      - type: WebBrowser
+        options:
+          target_url: http://arcd.com/users/
+      - type: DatabaseClient
+        options:
+          db_server_ip: 192.168.1.14
+      services:
+      - type: DNSClient
+
+    - hostname: client_2
+      type: computer
+      ip_address: 192.168.10.22
+      subnet_mask: 255.255.255.0
+      default_gateway: 192.168.10.1
+      dns_server: 192.168.1.10
+      applications:
+      - type: WebBrowser
+        options:
+          target_url: http://arcd.com/users/
+      - type: DataManipulationBot
+        options:
+          port_scan_p_of_success: 0.8
+          data_manipulation_p_of_success: 0.8
+          payload: "DELETE"
+          server_ip: 192.168.1.14
+      - type: DatabaseClient
+        options:
+          db_server_ip: 192.168.1.14
+      services:
+      - type: DNSClient
+
+
+
+    links:
+    - endpoint_a_hostname: router_1
+      endpoint_a_port: 1
+      endpoint_b_hostname: switch_1
+      endpoint_b_port: 8
+    - endpoint_a_hostname: router_1
+      endpoint_a_port: 2
+      endpoint_b_hostname: switch_2
+      endpoint_b_port: 8
+    - endpoint_a_hostname: switch_1
+      endpoint_a_port: 1
+      endpoint_b_hostname: domain_controller
+      endpoint_b_port: 1
+    - endpoint_a_hostname: switch_1
+      endpoint_a_port: 2
+      endpoint_b_hostname: web_server
+      endpoint_b_port: 1
+    - endpoint_a_hostname: switch_1
+      endpoint_a_port: 3
+      endpoint_b_hostname: database_server
+      endpoint_b_port: 1
+    - endpoint_a_hostname: switch_1
+      endpoint_a_port: 4
+      endpoint_b_hostname: backup_server
+      endpoint_b_port: 1
+    - endpoint_a_hostname: switch_1
+      endpoint_a_port: 7
+      endpoint_b_hostname: security_suite
+      endpoint_b_port: 1
+    - endpoint_a_hostname: switch_2
+      endpoint_a_port: 1
+      endpoint_b_hostname: client_1
+      endpoint_b_port: 1
+    - endpoint_a_hostname: switch_2
+      endpoint_a_port: 2
+      endpoint_b_hostname: client_2
+      endpoint_b_port: 1
+    - endpoint_a_hostname: switch_2
+      endpoint_a_port: 7
+      endpoint_b_hostname: security_suite
+      endpoint_b_port: 2

tests/assets/configs/basic_switched_network.yaml

@@ -9,6 +9,9 @@ io_settings:
   save_pcap_logs: true
   save_sys_logs: true
   sys_log_level: WARNING
+  agent_log_level: INFO
+  save_agent_logs: true
+  write_agent_log_to_terminal: True
 
 
 game:

tests/assets/configs/fix_duration_one_item.yaml

@@ -0,0 +1,248 @@
+#  Basic Switched network
+#
+#  --------------      --------------      --------------
+#  |  client_1  |------|  switch_1  |------|  client_2  |
+#  --------------      --------------      --------------
+#
+io_settings:
+  save_step_metadata: false
+  save_pcap_logs: true
+  save_sys_logs: true
+  sys_log_level: WARNING
+
+
+game:
+  max_episode_length: 256
+  ports:
+  - ARP
+  - DNS
+  - HTTP
+  - POSTGRES_SERVER
+  protocols:
+  - ICMP
+  - TCP
+  - UDP
+
+agents:
+  - ref: client_2_green_user
+    team: GREEN
+    type: ProbabilisticAgent
+    observation_space: null
+    action_space:
+      action_list:
+        - type: DONOTHING
+        - type: NODE_APPLICATION_EXECUTE
+      action_map:
+        0:
+          action: DONOTHING
+          options: {}
+        1:
+          action: NODE_APPLICATION_EXECUTE
+          options:
+            node_id: 0
+            application_id: 0
+      options:
+        nodes:
+        - node_name: client_2
+          applications:
+            - application_name: WebBrowser
+        max_folders_per_node: 1
+        max_files_per_folder: 1
+        max_services_per_node: 1
+        max_applications_per_node: 1
+
+    reward_function:
+      reward_components:
+        - type: DUMMY
+
+    agent_settings:
+      start_settings:
+        start_step: 5
+        frequency: 4
+        variance: 3
+
+
+
+  - ref: defender
+    team: BLUE
+    type: ProxyAgent
+
+    observation_space:
+      type: CUSTOM
+      options:
+        components:
+          - type: NODES
+            label: NODES
+            options:
+              hosts:
+                - hostname: client_1
+                - hostname: client_2
+                - hostname: client_3
+              num_services: 1
+              num_applications: 0
+              num_folders: 1
+              num_files: 1
+              num_nics: 2
+              include_num_access: false
+              monitored_traffic:
+                icmp:
+                    - NONE
+                tcp:
+                    - DNS
+              include_nmne: true
+              routers:
+                - hostname: router_1
+              num_ports: 0
+              ip_list:
+                - 192.168.10.21
+                - 192.168.10.22
+                - 192.168.10.23
+              wildcard_list:
+                - 0.0.0.1
+              port_list:
+                - 80
+                - 5432
+              protocol_list:
+                - ICMP
+                - TCP
+                - UDP
+              num_rules: 10
+
+          - type: LINKS
+            label: LINKS
+            options:
+              link_references:
+                - switch_1:eth-1<->client_1:eth-1
+                - switch_1:eth-2<->client_2:eth-1
+          - type: "NONE"
+            label: ICS
+            options: {}
+
+    action_space:
+      action_list:
+        - type: DONOTHING
+
+      action_map:
+          0:
+            action: DONOTHING
+            options: {}
+      options:
+        nodes:
+        - node_name: switch
+        - node_name: client_1
+        - node_name: client_2
+        - node_name: client_3
+        max_folders_per_node: 2
+        max_files_per_folder: 2
+        max_services_per_node: 2
+        max_nics_per_node: 8
+        max_acl_rules: 10
+        ip_list:
+          - 192.168.10.21
+          - 192.168.10.22
+          - 192.168.10.23
+
+    reward_function:
+      reward_components:
+        - type: DATABASE_FILE_INTEGRITY
+          weight: 0.5
+          options:
+            node_hostname: database_server
+            folder_name: database
+            file_name: database.db
+
+
+        - type: WEB_SERVER_404_PENALTY
+          weight: 0.5
+          options:
+            node_hostname: web_server
+            service_name: web_server_web_service
+
+
+    agent_settings:
+      flatten_obs: true
+
+simulation:
+  network:
+    nodes:
+
+    - type: switch
+      hostname: switch_1
+      num_ports: 8
+
+    - hostname: client_1
+      type: computer
+      ip_address: 192.168.10.21
+      subnet_mask: 255.255.255.0
+      default_gateway: 192.168.10.1
+      dns_server: 192.168.1.10
+      applications:
+      - type: RansomwareScript
+      - type: WebBrowser
+        options:
+          target_url: http://arcd.com/users/
+      - type: DatabaseClient
+        options:
+          db_server_ip: 192.168.1.10
+          server_password: arcd
+          fix_duration: 1
+      - type: DataManipulationBot
+        options:
+          port_scan_p_of_success: 0.8
+          data_manipulation_p_of_success: 0.8
+          payload: "DELETE"
+          server_ip: 192.168.1.21
+          server_password: arcd
+      - type: DoSBot
+        options:
+          target_ip_address: 192.168.10.21
+          payload: SPOOF DATA
+          port_scan_p_of_success: 0.8
+      services:
+      - type: DNSClient
+        options:
+          dns_server: 192.168.1.10
+      - type: DNSServer
+        options:
+          domain_mapping:
+            arcd.com: 192.168.1.10
+      - type: DatabaseService
+        options:
+          fix_duration: 5
+          backup_server_ip: 192.168.1.10
+      - type: WebServer
+      - type: FTPClient
+      - type: FTPServer
+        options:
+          server_password: arcd
+      - type: NTPClient
+        options:
+          ntp_server_ip: 192.168.1.10
+      - type: NTPServer
+    - hostname: client_2
+      type: computer
+      ip_address: 192.168.10.22
+      subnet_mask: 255.255.255.0
+      default_gateway: 192.168.10.1
+      dns_server: 192.168.1.10
+      applications:
+        - type: DatabaseClient
+          options:
+            db_server_ip: 192.168.1.10
+            server_password: arcd
+      services:
+        - type: DNSClient
+          options:
+            dns_server: 192.168.1.10
+
+    links:
+    - endpoint_a_hostname: switch_1
+      endpoint_a_port: 1
+      endpoint_b_hostname: client_1
+      endpoint_b_port: 1
+      bandwidth: 200
+    - endpoint_a_hostname: switch_1
+      endpoint_a_port: 2
+      endpoint_b_hostname: client_2
+      endpoint_b_port: 1
+      bandwidth: 200

tests/assets/configs/install_and_configure_apps.yaml

@@ -0,0 +1,142 @@
+io_settings:
+  save_step_metadata: false
+  save_pcap_logs: false
+  save_sys_logs: false
+  save_agent_actions: false
+
+game:
+  max_episode_length: 256
+  ports:
+    - ARP
+    - DNS
+  protocols:
+    - ICMP
+    - TCP
+
+agents:
+  - ref: agent_1
+    team: BLUE
+    type: ProxyAgent
+
+    observation_space: null
+    action_space:
+      action_list:
+        - type: DONOTHING
+        - type: NODE_APPLICATION_INSTALL
+        - type: CONFIGURE_DATABASE_CLIENT
+        - type: CONFIGURE_DOSBOT
+        - type: CONFIGURE_RANSOMWARE_SCRIPT
+        - type: NODE_APPLICATION_REMOVE
+      action_map:
+        0:
+          action: DONOTHING
+          options: {}
+        1:
+          action: NODE_APPLICATION_INSTALL
+          options:
+            node_id: 0
+            application_name: DatabaseClient
+        2:
+          action: NODE_APPLICATION_INSTALL
+          options:
+            node_id: 1
+            application_name: RansomwareScript
+        3:
+          action: NODE_APPLICATION_INSTALL
+          options:
+            node_id: 2
+            application_name: DoSBot
+        4:
+          action: CONFIGURE_DATABASE_CLIENT
+          options:
+            node_id: 0
+            config:
+              server_ip_address: 10.0.0.5
+        5:
+          action: CONFIGURE_DATABASE_CLIENT
+          options:
+            node_id: 0
+            config:
+              server_password: correct_password
+        6:
+          action: CONFIGURE_RANSOMWARE_SCRIPT
+          options:
+            node_id: 1
+            config:
+              server_ip_address: 10.0.0.5
+              server_password: correct_password
+              payload: ENCRYPT
+        7:
+          action: CONFIGURE_DOSBOT
+          options:
+            node_id: 2
+            config:
+              target_ip_address: 10.0.0.5
+              target_port: POSTGRES_SERVER
+              payload: DELETE
+              repeat: true
+              port_scan_p_of_success: 1.0
+              dos_intensity: 1.0
+              max_sessions: 1000
+        8:
+          action: NODE_APPLICATION_INSTALL
+          options:
+            node_id: 1
+            application_name: DatabaseClient
+      options:
+        nodes:
+          - node_name: client_1
+          - node_name: client_2
+          - node_name: client_3
+        ip_list: []
+    reward_function:
+      reward_components:
+        - type: DUMMY
+
+simulation:
+  network:
+    nodes:
+      - type: computer
+        hostname: client_1
+        ip_address: 10.0.0.2
+        subnet_mask: 255.255.255.0
+        default_gateway: 10.0.0.1
+      - type: computer
+        hostname: client_2
+        ip_address: 10.0.0.3
+        subnet_mask: 255.255.255.0
+        default_gateway: 10.0.0.1
+      - type: computer
+        hostname: client_3
+        ip_address: 10.0.0.4
+        subnet_mask: 255.255.255.0
+        default_gateway: 10.0.0.1
+      - type: switch
+        hostname: switch_1
+        num_ports: 8
+      - type: server
+        hostname: server_1
+        ip_address: 10.0.0.5
+        subnet_mask: 255.255.255.0
+        default_gateway: 10.0.0.1
+        services:
+          - type: DatabaseService
+            options:
+              db_password: correct_password
+    links:
+      - endpoint_a_hostname: client_1
+        endpoint_a_port: 1
+        endpoint_b_hostname: switch_1
+        endpoint_b_port: 1
+      - endpoint_a_hostname: client_2
+        endpoint_a_port: 1
+        endpoint_b_hostname: switch_1
+        endpoint_b_port: 2
+      - endpoint_a_hostname: client_3
+        endpoint_a_port: 1
+        endpoint_b_hostname: switch_1
+        endpoint_b_port: 3
+      - endpoint_a_hostname: server_1
+        endpoint_a_port: 1
+        endpoint_b_hostname: switch_1
+        endpoint_b_port: 8

tests/assets/configs/nmap_port_scan_red_agent_config.yaml

@@ -41,6 +41,12 @@ agents:
           options:
             source_node: client_1
             target_ip_address: 192.168.10.0/24
+            target_port:
+              - 21
+              - 53
+              - 80
+              - 123
+              - 219
 
     reward_function:
       reward_components:

tests/assets/configs/software_fix_duration.yaml

@@ -0,0 +1,266 @@
+#  Basic Switched network
+#
+#  --------------      --------------      --------------
+#  |  client_1  |------|  switch_1  |------|  client_2  |
+#  --------------      --------------      --------------
+#
+io_settings:
+  save_step_metadata: false
+  save_pcap_logs: true
+  save_sys_logs: true
+  sys_log_level: WARNING
+
+
+game:
+  max_episode_length: 256
+  ports:
+  - ARP
+  - DNS
+  - HTTP
+  - POSTGRES_SERVER
+  protocols:
+  - ICMP
+  - TCP
+  - UDP
+
+agents:
+  - ref: client_2_green_user
+    team: GREEN
+    type: ProbabilisticAgent
+    observation_space: null
+    action_space:
+      action_list:
+        - type: DONOTHING
+        - type: NODE_APPLICATION_EXECUTE
+      action_map:
+        0:
+          action: DONOTHING
+          options: {}
+        1:
+          action: NODE_APPLICATION_EXECUTE
+          options:
+            node_id: 0
+            application_id: 0
+      options:
+        nodes:
+        - node_name: client_2
+          applications:
+            - application_name: WebBrowser
+        max_folders_per_node: 1
+        max_files_per_folder: 1
+        max_services_per_node: 1
+        max_applications_per_node: 1
+
+    reward_function:
+      reward_components:
+        - type: DUMMY
+
+    agent_settings:
+      start_settings:
+        start_step: 5
+        frequency: 4
+        variance: 3
+
+
+
+  - ref: defender
+    team: BLUE
+    type: ProxyAgent
+
+    observation_space:
+      type: CUSTOM
+      options:
+        components:
+          - type: NODES
+            label: NODES
+            options:
+              hosts:
+                - hostname: client_1
+                - hostname: client_2
+                - hostname: client_3
+              num_services: 1
+              num_applications: 0
+              num_folders: 1
+              num_files: 1
+              num_nics: 2
+              include_num_access: false
+              monitored_traffic:
+                icmp:
+                    - NONE
+                tcp:
+                    - DNS
+              include_nmne: true
+              routers:
+                - hostname: router_1
+              num_ports: 0
+              ip_list:
+                - 192.168.10.21
+                - 192.168.10.22
+                - 192.168.10.23
+              wildcard_list:
+                - 0.0.0.1
+              port_list:
+                - 80
+                - 5432
+              protocol_list:
+                - ICMP
+                - TCP
+                - UDP
+              num_rules: 10
+
+          - type: LINKS
+            label: LINKS
+            options:
+              link_references:
+                - switch_1:eth-1<->client_1:eth-1
+                - switch_1:eth-2<->client_2:eth-1
+          - type: "NONE"
+            label: ICS
+            options: {}
+
+    action_space:
+      action_list:
+        - type: DONOTHING
+
+      action_map:
+          0:
+            action: DONOTHING
+            options: {}
+      options:
+        nodes:
+        - node_name: switch
+        - node_name: client_1
+        - node_name: client_2
+        - node_name: client_3
+        max_folders_per_node: 2
+        max_files_per_folder: 2
+        max_services_per_node: 2
+        max_nics_per_node: 8
+        max_acl_rules: 10
+        ip_list:
+          - 192.168.10.21
+          - 192.168.10.22
+          - 192.168.10.23
+
+    reward_function:
+      reward_components:
+        - type: DATABASE_FILE_INTEGRITY
+          weight: 0.5
+          options:
+            node_hostname: database_server
+            folder_name: database
+            file_name: database.db
+
+
+        - type: WEB_SERVER_404_PENALTY
+          weight: 0.5
+          options:
+            node_hostname: web_server
+            service_name: web_server_web_service
+
+
+    agent_settings:
+      flatten_obs: true
+
+simulation:
+  network:
+    nodes:
+
+    - type: switch
+      hostname: switch_1
+      num_ports: 8
+
+    - hostname: client_1
+      type: computer
+      ip_address: 192.168.10.21
+      subnet_mask: 255.255.255.0
+      default_gateway: 192.168.10.1
+      dns_server: 192.168.1.10
+      applications:
+      - type: NMAP
+        options:
+          fix_duration: 1
+      - type: RansomwareScript
+        options:
+          fix_duration: 1
+      - type: WebBrowser
+        options:
+          target_url: http://arcd.com/users/
+          fix_duration: 1
+      - type: DatabaseClient
+        options:
+          db_server_ip: 192.168.1.10
+          server_password: arcd
+          fix_duration: 1
+      - type: DataManipulationBot
+        options:
+          port_scan_p_of_success: 0.8
+          data_manipulation_p_of_success: 0.8
+          payload: "DELETE"
+          server_ip: 192.168.1.21
+          server_password: arcd
+          fix_duration: 1
+      - type: DoSBot
+        options:
+          target_ip_address: 192.168.10.21
+          payload: SPOOF DATA
+          port_scan_p_of_success: 0.8
+          fix_duration: 1
+      services:
+      - type: DNSClient
+        options:
+          dns_server: 192.168.1.10
+          fix_duration: 3
+      - type: DNSServer
+        options:
+          fix_duration: 3
+          domain_mapping:
+            arcd.com: 192.168.1.10
+      - type: DatabaseService
+        options:
+          backup_server_ip: 192.168.1.10
+          fix_duration: 3
+      - type: WebServer
+        options:
+          fix_duration: 3
+      - type: FTPClient
+        options:
+          fix_duration: 3
+      - type: FTPServer
+        options:
+          server_password: arcd
+          fix_duration: 3
+      - type: NTPClient
+        options:
+          ntp_server_ip: 192.168.1.10
+          fix_duration: 3
+      - type: NTPServer
+        options:
+          fix_duration: 3
+    - hostname: client_2
+      type: computer
+      ip_address: 192.168.10.22
+      subnet_mask: 255.255.255.0
+      default_gateway: 192.168.10.1
+      dns_server: 192.168.1.10
+      applications:
+        - type: DatabaseClient
+          options:
+            db_server_ip: 192.168.1.10
+            server_password: arcd
+      services:
+        - type: DNSClient
+          options:
+            dns_server: 192.168.1.10
+
+    links:
+    - endpoint_a_hostname: switch_1
+      endpoint_a_port: 1
+      endpoint_b_hostname: client_1
+      endpoint_b_port: 1
+      bandwidth: 200
+    - endpoint_a_hostname: switch_1
+      endpoint_a_port: 2
+      endpoint_b_hostname: client_2
+      endpoint_b_port: 1
+      bandwidth: 200

tests/assets/configs/test_application_install.yaml

@@ -260,6 +260,7 @@ agents:
         - type: NODE_APPLICATION_INSTALL
         - type: NODE_APPLICATION_REMOVE
         - type: NODE_APPLICATION_EXECUTE
+        - type: CONFIGURE_DOSBOT
 
       action_map:
           0:
@@ -683,7 +684,6 @@ agents:
             options:
               node_id: 0
               application_name: DoSBot
-              ip_address: 192.168.1.14
           79:
             action: NODE_APPLICATION_REMOVE
             options:
@@ -699,6 +699,14 @@ agents:
             options:
               node_id: 0
               application_id: 0
+          82:
+            action: CONFIGURE_DOSBOT
+            options:
+              node_id: 0
+              config:
+                target_ip_address: 192.168.1.14
+                target_port: POSTGRES_SERVER
+
 
 
 

tests/assets/configs/test_primaite_session.yaml

@@ -243,25 +243,25 @@ agents:
             action: "NODE_FILE_SCAN"
             options:
                 node_id: 2
-                folder_id: 1
+                folder_id: 0
                 file_id: 0
           10:
             action: "NODE_FILE_CHECKHASH"
             options:
                 node_id: 2
-                folder_id: 1
+                folder_id: 0
                 file_id: 0
           11:
             action: "NODE_FILE_DELETE"
             options:
                 node_id: 2
-                folder_id: 1
+                folder_id: 0
                 file_id: 0
           12:
             action: "NODE_FILE_REPAIR"
             options:
                 node_id: 2
-                folder_id: 1
+                folder_id: 0
                 file_id: 0
           13:
             action: "NODE_SERVICE_FIX"
@@ -272,22 +272,22 @@ agents:
             action: "NODE_FOLDER_SCAN"
             options:
                 node_id: 2
-                folder_id: 1
+                folder_id: 0
           15:
             action: "NODE_FOLDER_CHECKHASH"
             options:
                 node_id: 2
-                folder_id: 1
+                folder_id: 0
           16:
             action: "NODE_FOLDER_REPAIR"
             options:
                 node_id: 2
-                folder_id: 1
+                folder_id: 0
           17:
             action: "NODE_FOLDER_RESTORE"
             options:
                 node_id: 2
-                folder_id: 1
+                folder_id: 0
           18:
             action: "NODE_OS_SCAN"
             options:
@@ -518,11 +518,22 @@ agents:
         nodes:
         - node_name: domain_controller
         - node_name: web_server
+          applications:
+          - application_name: DatabaseClient
+          services:
+          - service_name: WebServer
         - node_name: database_server
+          folders:
+          - folder_name: database
+            files:
+            - file_name: database.db
+          services:
+          - service_name: DatabaseService
         - node_name: backup_server
         - node_name: security_suite
         - node_name: client_1
         - node_name: client_2
+
         max_folders_per_node: 2
         max_files_per_folder: 2
         max_services_per_node: 2
@@ -557,6 +568,7 @@ agents:
 
     agent_settings:
       flatten_obs: true
+      action_masking: true
 
 
 
@@ -634,6 +646,8 @@ simulation:
       dns_server: 192.168.1.10
       services:
       - type: DatabaseService
+        options:
+          backup_server_ip: 192.168.1.16
 
     - type: server
       hostname: backup_server

tests/assets/configs/wireless_wan_network_config_freq_max_override.yaml

@@ -0,0 +1,81 @@
+game:
+  max_episode_length: 256
+  ports:
+    - ARP
+  protocols:
+    - ICMP
+    - TCP
+    - UDP
+
+simulation:
+  network:
+    airspace:
+      frequency_max_capacity_mbps:
+        WIFI_2_4: 123.45
+        WIFI_5: 0.0
+    nodes:
+      - type: computer
+        hostname: pc_a
+        ip_address: 192.168.0.2
+        subnet_mask: 255.255.255.0
+        default_gateway: 192.168.0.1
+        start_up_duration: 0
+
+      - type: computer
+        hostname: pc_b
+        ip_address: 192.168.2.2
+        subnet_mask: 255.255.255.0
+        default_gateway: 192.168.2.1
+        start_up_duration: 0
+
+      - type: wireless_router
+        hostname: router_1
+        start_up_duration: 0
+
+        router_interface:
+          ip_address: 192.168.0.1
+          subnet_mask: 255.255.255.0
+
+        wireless_access_point:
+          ip_address: 192.168.1.1
+          subnet_mask: 255.255.255.0
+          frequency: WIFI_2_4
+        acl:
+          1:
+            action: PERMIT
+        routes:
+          - address: 192.168.2.0 # PC B subnet
+            subnet_mask: 255.255.255.0
+            next_hop_ip_address: 192.168.1.2
+            metric: 0
+
+      - type: wireless_router
+        hostname: router_2
+        start_up_duration: 0
+
+        router_interface:
+          ip_address: 192.168.2.1
+          subnet_mask: 255.255.255.0
+
+        wireless_access_point:
+          ip_address: 192.168.1.2
+          subnet_mask: 255.255.255.0
+          frequency: WIFI_2_4
+        acl:
+          1:
+            action: PERMIT
+        routes:
+          - address: 192.168.0.0 # PC A subnet
+            subnet_mask: 255.255.255.0
+            next_hop_ip_address: 192.168.1.1
+            metric: 0
+    links:
+      - endpoint_a_hostname: pc_a
+        endpoint_a_port: 1
+        endpoint_b_hostname: router_1
+        endpoint_b_port: 2
+
+      - endpoint_a_hostname: pc_b
+        endpoint_a_port: 1
+        endpoint_b_hostname: router_2
+        endpoint_b_port: 2

tests/assets/configs/wireless_wan_network_config_freq_max_override_blocked.yaml

@@ -0,0 +1,81 @@
+game:
+  max_episode_length: 256
+  ports:
+    - ARP
+  protocols:
+    - ICMP
+    - TCP
+    - UDP
+
+simulation:
+  network:
+    airspace:
+      frequency_max_capacity_mbps:
+        WIFI_2_4: 0.0
+        WIFI_5: 0.0
+    nodes:
+      - type: computer
+        hostname: pc_a
+        ip_address: 192.168.0.2
+        subnet_mask: 255.255.255.0
+        default_gateway: 192.168.0.1
+        start_up_duration: 0
+
+      - type: computer
+        hostname: pc_b
+        ip_address: 192.168.2.2
+        subnet_mask: 255.255.255.0
+        default_gateway: 192.168.2.1
+        start_up_duration: 0
+
+      - type: wireless_router
+        hostname: router_1
+        start_up_duration: 0
+
+        router_interface:
+          ip_address: 192.168.0.1
+          subnet_mask: 255.255.255.0
+
+        wireless_access_point:
+          ip_address: 192.168.1.1
+          subnet_mask: 255.255.255.0
+          frequency: WIFI_2_4
+        acl:
+          1:
+            action: PERMIT
+        routes:
+          - address: 192.168.2.0 # PC B subnet
+            subnet_mask: 255.255.255.0
+            next_hop_ip_address: 192.168.1.2
+            metric: 0
+
+      - type: wireless_router
+        hostname: router_2
+        start_up_duration: 0
+
+        router_interface:
+          ip_address: 192.168.2.1
+          subnet_mask: 255.255.255.0
+
+        wireless_access_point:
+          ip_address: 192.168.1.2
+          subnet_mask: 255.255.255.0
+          frequency: WIFI_2_4
+        acl:
+          1:
+            action: PERMIT
+        routes:
+          - address: 192.168.0.0 # PC A subnet
+            subnet_mask: 255.255.255.0
+            next_hop_ip_address: 192.168.1.1
+            metric: 0
+    links:
+      - endpoint_a_hostname: pc_a
+        endpoint_a_port: 1
+        endpoint_b_hostname: router_1
+        endpoint_b_port: 2
+
+      - endpoint_a_hostname: pc_b
+        endpoint_a_port: 1
+        endpoint_b_hostname: router_2
+        endpoint_b_port: 2

tests/conftest.py

@@ -3,6 +3,7 @@ from typing import Any, Dict, Tuple
 
 import pytest
 import yaml
+from ray import init as rayinit
 
 from primaite import getLogger, PRIMAITE_PATHS
 from primaite.game.agent.actions import ActionManager
@@ -29,6 +30,7 @@ from primaite.simulator.system.services.service import Service
 from primaite.simulator.system.services.web_server.web_server import WebServer
 from tests import TEST_ASSETS_ROOT
 
+rayinit(local_mode=True)
 ACTION_SPACE_NODE_VALUES = 1
 ACTION_SPACE_NODE_ACTION_VALUES = 1
 
@@ -51,11 +53,11 @@ class TestService(Service):
         pass
 
 
-class TestApplication(Application):
+class DummyApplication(Application, identifier="DummyApplication"):
     """Test Application class"""
 
     def __init__(self, **kwargs):
-        kwargs["name"] = "TestApplication"
+        kwargs["name"] = "DummyApplication"
         kwargs["port"] = Port.HTTP
         kwargs["protocol"] = IPProtocol.TCP
         super().__init__(**kwargs)
@@ -85,15 +87,18 @@ def service_class():
 
 
 @pytest.fixture(scope="function")
-def application(file_system) -> TestApplication:
-    return TestApplication(
-        name="TestApplication", port=Port.ARP, file_system=file_system, sys_log=SysLog(hostname="test_application")
+def application(file_system) -> DummyApplication:
+    return DummyApplication(
+        name="DummyApplication",
+        port=Port.ARP,
+        file_system=file_system,
+        sys_log=SysLog(hostname="dummy_application"),
     )
 
 
 @pytest.fixture(scope="function")
 def application_class():
-    return TestApplication
+    return DummyApplication
 
 
 @pytest.fixture(scope="function")
@@ -252,8 +257,7 @@ def example_network() -> Network:
     server_2.power_on()
     network.connect(endpoint_b=server_2.network_interface[1], endpoint_a=switch_1.network_interface[2])
 
-    router_1.acl.add_rule(action=ACLAction.PERMIT, src_port=Port.ARP, dst_port=Port.ARP, position=22)
-    router_1.acl.add_rule(action=ACLAction.PERMIT, protocol=IPProtocol.ICMP, position=23)
+    router_1.acl.add_rule(action=ACLAction.PERMIT, position=1)
 
     assert all(link.is_up for link in network.links.values())
 

tests/e2e_integration_tests/action_masking/__init__.py

@@ -0,0 +1 @@
+# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK