Merged PR 633: #3110 Final user guide comments.

## Summary
Feedback following James' comments

## Test process

## Checklist
- [x ] PR is linked to a **work item**
- [x] **acceptance criteria** of linked ticket are met
- [x] performed **self-review** of the code
- [x] written **tests** for any new functionality added with this PR
- [x] updated the **documentation** if this PR changes or adds functionality
- [x] written/updated **design docs** if this PR implements new functionality
- [x] updated the **change log**
- [x] ran **pre-commit** checks for code style
- [x] attended to any **TO-DOs** left in the code

#3110 Final user guide comments.

Related work items: #3110

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

@@ -14,33 +14,38 @@ parameters:
   - name: matrix
     type: object
     default:
-    # - job_name: 'UbuntuPython38'
-    #   py: '3.8'
-    #   img: 'ubuntu-latest'
-    #   every_time: false
-    #   publish_coverage: false
-    - job_name: 'UbuntuPython311'
-      py: '3.11'
+    - job_name: 'UbuntuPython39'
+      py: 'v3.9'
+      img: 'ubuntu-latest'
+      every_time: false
+      publish_coverage: false
+    - job_name: 'UbuntuPython310'
+      py: 'v3.10'
       img: 'ubuntu-latest'
       every_time: true
       publish_coverage: true
-    # - job_name: 'WindowsPython38'
-    #   py: '3.8'
-    #   img: 'windows-latest'
-    #   every_time: false
-    #   publish_coverage: false
-    - job_name: 'WindowsPython311'
-      py: '3.11'
+    - job_name: 'UbuntuPython311'
+      py: 'v3.11'
+      img: 'ubuntu-latest'
+      every_time: false
+      publish_coverage: false
+    - job_name: 'WindowsPython39'
+      py: 'v3.9'
       img: 'windows-latest'
       every_time: false
       publish_coverage: false
-    # - job_name: 'MacOSPython38'
-    #   py: '3.8'
-    #   img: 'macOS-latest'
-    #   every_time: false
-    #   publish_coverage: false
+    - job_name: 'WindowsPython311'
+      py: 'v3.11'
+      img: 'windows-latest'
+      every_time: false
+      publish_coverage: false
+    - job_name: 'MacOSPython39'
+      py: 'v3.9'
+      img: 'macOS-latest'
+      every_time: false
+      publish_coverage: false
     - job_name: 'MacOSPython311'
-      py: '3.11'
+      py: 'v3.11'
       img: 'macOS-latest'
       every_time: false
       publish_coverage: false
@@ -63,7 +68,7 @@ stages:
             displayName: 'Use Python ${{ item.py }}'
 
           - script: |
-              python -m pip install pre-commit
+              python -m pip install pre-commit>=6.1
               pre-commit install
               pre-commit run --all-files
             displayName: 'Run pre-commits'
@@ -71,7 +76,6 @@ stages:
           - script: |
               python -m pip install --upgrade pip==23.0.1
               pip install wheel==0.38.4 --upgrade
-              pip install setuptools==66 --upgrade
               pip install build==0.10.0
               pip install pytest-azurepipelines
             displayName: 'Install build dependencies'
@@ -102,19 +106,15 @@ stages:
               version: '2.1.x'
 
           - script: |
-              coverage run -m --source=primaite pytest -v -o junit_family=xunit2 --junitxml=junit/test-results.xml --cov-fail-under=80
-              coverage xml -o coverage.xml -i
-              coverage html -d htmlcov -i
+              python run_test_and_coverage.py
             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
+              # Fail step if exit code not equal to 0
+              if [ $notebooks_exit_code -ne 0 ]; then
                 exit 1
               fi
             displayName: 'Run notebooks on Linux and macOS'
@@ -124,11 +124,8 @@ stages:
           - 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
+              rem Fail step if exit code not equal to 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')
 

.github/workflows/build-sphinx.yml

@@ -1,8 +1,8 @@
 name: build-sphinx-to-github-pages
 
 env:
-  GITHUB_ACTOR: {todo:fill in URL}
-  GITHUB_REPOSITORY: {todo:fill in URL}/PrimAITE
+  GITHUB_ACTOR: Autonomous-Resilient-Cyber-Defence
+  GITHUB_REPOSITORY: Autonomous-Resilient-Cyber-Defence/PrimAITE
   GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN}}
 
 on:

.pre-commit-config.yaml

@@ -31,7 +31,7 @@ repos:
       - id: isort
         args: [ "--profile", "black" ]
   - repo: http://github.com/PyCQA/flake8
-    rev: 6.0.0
+    rev: 6.1.0
     hooks:
       - id: flake8
         additional_dependencies:

CHANGELOG.md

@@ -5,6 +5,88 @@ 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.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.0.0] = 2025-03-XX
+
+### Added
+-   Log observation space data by episode and step.
+-   Added ability to set the observation threshold for NMNE, file access and application executions.
+-   Added `show_history` method to Agents, allowing you to view actions taken by an agent per step. By default, `do-nothing` actions are omitted.
+-   New ``node-send-local-command`` action implemented which grants agents the ability to execute commands locally. (Previously limited to remote only)
+-   Added ability to set the observation threshold for NMNE, file access and application executions
+-   UC7 Scenario model changes including Threat Actor Profile, TAP001 and TAP003 agents plus config files and example notebooks.
+-   New how-to guides describing how to use the new extension system to customise actions, environments and rewards.
+-   Added version and plugin fields to YAML configs to ensure compatibility with future versions.
+-   Network Node Adder class provides a framework for adding nodes to a network in a standardised way.
+
+### Changed
+-   ACLs are no longer applied to layer-2 traffic.
+-   Random number seed values are recorded in simulation/seed.log if the seed is set in the config file
+    or `generate_seed_value` is set to `true`.
+-   ARP .show() method will now include the port number associated with each entry.
+-   The behaviour that services, applications, files and folders require scanning before their observations are updated is now optional.
+-   Updated the `Terminal` class to provide response information when sending remote command execution.
+-   Agents now follow a common configuration format, simplifying the configuration of agents and their extensibilty.
+-   Actions within PrimAITE are now extensible, allowing for plugin support.
+-   Added a config schema to `ObservationManager`, `ActionManager`, and `RewardFunction`.
+-   Streamlined the way agents are created from config
+-   Agent config no longer requires a dummy action space if the action space is empty, the same applies for observation space and reward function
+-   Actions now support a config schema, to allow yaml data validation and default parameter values
+-   Action parameters are no longer defined through IDs, instead meaningful data is provided directly in the action map
+-   Test and example YAMLs have been updated to match the new agent and action schemas, such as:
+    -   Removed empty action spaces, observation spaces, or reward spaces for agent which didn't use them
+    -   Relabelled action parameters to match the new action config schemas, and updated the values to no longer rely on indices
+    -   Removed action space options which were previously used for assigning meaning to action space IDs
+-   Updated tests that don't use YAMLs to still use the new action and agent schemas
+-   Nodes now use a config schema and are extensible, allowing for plugin support.
+-   Node tests have been updated to use the new node config schemas when not using YAML files.
+-   Documentation has been updated to include details of extensibility with PrimAITE.
+-   Software is created in the GOOD health state instead of UNUSED.
+-   Standardised naming convention for YAML config files using kebab-case.
+    This naming convention is used for configuring software, observations, actions and node types.
+    NB: A migration guide will be available with this release.
+
+### Fixed
+-   DNS client no longer fails to check its cache if a DNS server address is missing.
+-   DNS client now correctly inherits the node's DNS address configuration setting.
+-   ACL observations now include the ACL at index 0.
+-   SoftwareManager.show() correctly displays all the software associated with a port whether the software is listening or not.
+
+
+## [3.3.0] - 2024-09-04
+### Added
+-   Random Number Generator Seeding by specifying a random number seed in the config file.
+-   Implemented Terminal service class, providing a generic terminal simulation.
+-   Added `User`, `UserManager` and `UserSessionManager` to enable the creation of user accounts and login on Nodes.
+-   Added actions to establish SSH connections, send commands remotely and terminate SSH connections.
+-   Added actions to change users' passwords.
+-   Added a `listen_on_ports` set in the `IOSoftware` class to enable software listening on ports in addition to the
+    main port they're assigned.
+-   Added two new red applications: ``C2Beacon`` and ``C2Server`` which aim to simulate malicious network infrastructure.
+    Refer to the ``Command and Control Application Suite E2E Demonstration`` notebook for more information.
+-   Added reward calculation details to AgentHistoryItem.
+-   Added a new Privilege-Escalation-and Data-Loss-Example.ipynb notebook with a realistic cyber scenario focusing on
+    internal privilege escalation and data loss through the manipulation of SSH access and Access Control Lists (ACLs).
+-   Added a new extensible `NetworkNodeAdder` class for convenient addition of sets of nodes based on a simplified config.
+
+### Changed
+-   File and folder observations can now be configured to always show the true health status, or require scanning like before.
+-   It's now possible to disable stickiness on reward components, meaning their value returns to 0 during timesteps where agent don't issue the corresponding action. Affects `GreenAdminDatabaseUnreachablePenalty`, `WebpageUnavailablePenalty`, `WebServer404Penalty`
+-   Node observations can now be configured to show the number of active local and remote logins.
+-   Ports and IP Protocols no longer use enums. They are defined in dictionary lookups and are handled by custom validation to enable extensibility with plugins.
+-   Changed AirSpaceFrequency to a data transfer object with a registry to allow extensibility
+-   Changed the Office LAN creation convenience function to follow the new `NetworkNodeAdder` pattern. Office LANs can now also be defined in YAML config.
+
+### Fixed
+-   Folder observations showing the true health state without scanning (the old behaviour can be reenabled via config)
+-   Updated `SoftwareManager` `install` and `uninstall` to handle all functionality that was being done at the `install`
+    and `uninstall` methods in the `Node` class.
+-   Updated the `receive_payload_from_session_manager` method in `SoftwareManager` so that it now sends a copy of the
+    payload to any software listening on the destination port of the `Frame`.
+-   Made the `show` method of `Network` show all node types, including ones registered at runtime
+
+### Removed
+-   Removed the `install` and `uninstall` methods in the `Node` class.
+
 
 ## [3.2.0] - 2024-07-18
 
@@ -17,7 +99,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 -   Tests to verify that airspace bandwidth is applied correctly and can be configured via YAML
 -   Agent logging for agents' internal decision logic
 -   Action masking in all PrimAITE environments
-
 ### Changed
 -   Application registry was moved to the `Application` class and now updates automatically when Application is subclassed
 -   Databases can no longer respond to request while performing a backup
@@ -27,6 +108,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 -   Frame `size` attribute now includes both core size and payload size in bytes
 -   The `speed` attribute of `NetworkInterface` has been changed from `int` to `float`
 -   Tidied up CHANGELOG
+-   Enhanced `AirSpace` logic to block transmissions that would exceed the available capacity.
+-   Updated `_can_transmit` function in `Link` to account for current load and total bandwidth capacity, ensuring transmissions do not exceed limits.
 
 ### Fixed
 -   Links and airspaces can no longer transmit data if this would exceed their bandwidth

CONTRIBUTING.md

@@ -4,17 +4,17 @@
 ### **Did you find a bug?**
 
 
-* **Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/{todo:fill in URL}/PrimAITE/issues).
-* If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/{todo:fill in URL}/PrimAITE/issues/new?assignees=&labels=bug&projects=&template=bug_report.md&title=%5BBUG%5D+-+%3Cbug+title+goes+here%3E). Be sure to follow our bug report template with the headers **Describe the bug**, **To Reproduce**, **Expected behaviour**, **Screenshots/Outputs**, **Environment**, and **Additional context**
+* **Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE/issues).
+* If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE/issues/new?assignees=&labels=bug&projects=&template=bug_report.md&title=%5BBUG%5D+-+%3Cbug+title+goes+here%3E). Be sure to follow our bug report template with the headers **Describe the bug**, **To Reproduce**, **Expected behaviour**, **Screenshots/Outputs**, **Environment**, and **Additional context**
 
 
 ### **Do you have a solution to fix the bug?**
 
-* [Fork the repository](https://github.com/{todo:fill in URL}/PrimAITE/fork).
+* [Fork the repository](https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE/fork).
 * Install the pre-commit hook with `pre-commit install`.
 * Implement the bug fix.
-* Commit the bug fix to the dev branch on your fork. If the bug has an open issue under [Issues](https://github.com/{todo:fill in URL}/PrimAITE/issues), reference the issue in the commit message (e.g. #1 references issue 1).
-* Submit a pull request from your dev branch to the {todo:fill in URL}/PrimAITE dev branch. Again, if the bug has an open issue under [Issues](https://github.com/{todo:fill in URL}/PrimAITE/issues), reference the issue in the pull request description.
+* Commit the bug fix to the dev branch on your fork. If the bug has an open issue under [Issues](https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE/issues), reference the issue in the commit message (e.g. #1 references issue 1).
+* Submit a pull request from your dev branch to the Autonomous-Resilient-Cyber-Defence/PrimAITE dev branch. Again, if the bug has an open issue under [Issues](https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE/issues), reference the issue in the pull request description.
 
 ### **Did you fix whitespace, format code, or make a purely cosmetic patch?**
 
@@ -22,7 +22,7 @@ Changes that are cosmetic in nature and do not add anything substantial to the s
 
 ### **Do you intend to add a new feature or change an existing one?**
 
-* Submit a [feature request issue](https://github.com/{todo:fill in URL}/PrimAITE/issues/new?assignees=&labels=feature_request&projects=&template=feature_request.md&title=%5BREQUEST%5D+-+%3Crequest+title+goes+here%3E).
+* Submit a [feature request issue](https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE/issues/new?assignees=&labels=feature_request&projects=&template=feature_request.md&title=%5BREQUEST%5D+-+%3Crequest+title+goes+here%3E).
 * Know how to implement the new feature or change? Follow the same steps in the bug fix section above to fork, build, document, test, commit, and submit a pull request.
 
 ### **Do you have questions about the source code?**

LICENSE

@@ -4,24 +4,21 @@ MIT License Conditions
 
 These MIT License conditions confirm the provision of the following artefacts as MIT License by Defence Science and Technology
 of this software and associated documentation files (the "Software"), to deal
-request to the QQ or FNC mailbox):
+in the Software without restriction, including without limitation the rights
 
 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
-- Use Case Release Packs
 furnished to do so, subject to the following conditions:
 
-Suppliers are required to read and confirm acceptance of the {todo:fill in URL} Foundry SyOPs (https://github.com/{todo:fill in URL}/foundry-syops) before being admitted access to material hosted on the {todo:fill in URL} Foundry GitHub site.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 
-The material is supplied in confidence to QQ / FNC and their subcontractors under SERAPIS, and is issued to inform only those
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-
-
-of DSTL. The material must be stored and protected appropriately. All material must be destroyed at the end of the task.
-

MANIFEST.in

@@ -1,3 +1,2 @@
 include src/primaite/setup/_package_data/primaite_config.yaml
 include src/primaite/config/_package_data/*.yaml
-include src/primaite/simulator/_package_data/*.ipynb

README.md

@@ -24,6 +24,8 @@ PrimAITE presents the following features:
 
 - Support for multiple agents, each having their own customisable observation space, action space, and reward function definition, and either deterministic or RL-directed behaviour
 
+Whilst PrimAITE ships with a number of example modelled scenarios (a.k.a. Use Cases), it has not been developed to mandate the solving of a single cyber challenge, and instead provides a highly flexible environment application that can be extended and reconfigured by the user to suit their specific cyber defence training and evaluation needs. PrimAITE provides default networks, red agent and green agent behaviour, reward functions, and action / observation space configuration, all of which can be utilised out of the box, but which ultimately can (and in some instances should) be built upon and / or reconfigured to meet the needs of different defensive agent developers. The PrimAITE user guide provides comprehensive instruction on all PrimAITE features, functionality and components, and can be consulted in order to help guide users in any reconfiguration or enhancements they wish to undertake; a library of example Jupyter notebooks are also provided to support such work.
+
 ## Getting Started with PrimAITE
 
 ### 💫 Installation
@@ -77,7 +79,7 @@ To make your own changes to PrimAITE, perform the install from source (developer
 
 #### 1. Clone the PrimAITE repository
 ``` unix
-git clone git@github.com:{todo:fill in URL}/PrimAITE.git
+git clone git@github.com:Autonomous-Resilient-Cyber-Defence/PrimAITE.git
 ```
 
 #### 2. CD into the repo directory

benchmark/benchmark.py

@@ -1,4 +1,4 @@
-# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+# © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 from typing import Any, Dict, Optional, Tuple
 
 from gymnasium.core import ObsType

benchmark/primaite_benchmark.py

@@ -1,11 +1,11 @@
-# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+# © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 import json
 import shutil
 from datetime import datetime
 from pathlib import Path
 from typing import Any, Dict, Final, Tuple
 
-from report import build_benchmark_md_report
+from report import build_benchmark_md_report, md2pdf
 from stable_baselines3 import PPO
 
 import primaite
@@ -159,6 +159,13 @@ def run(
     learning_rate: float = 3e-4,
 ) -> None:
     """Run the PrimAITE benchmark."""
+    # generate report folder
+    v_str = f"v{primaite.__version__}"
+
+    version_result_dir = _RESULTS_ROOT / v_str
+    version_result_dir.mkdir(exist_ok=True, parents=True)
+    output_path = version_result_dir / f"PrimAITE {v_str} Benchmark Report.md"
+
     benchmark_start_time = datetime.now()
 
     session_metadata_dict = {}
@@ -193,6 +200,12 @@ def run(
         session_metadata=session_metadata_dict,
         config_path=data_manipulation_config_path(),
         results_root_path=_RESULTS_ROOT,
+        output_path=output_path,
+    )
+    md2pdf(
+        md_path=output_path,
+        pdf_path=str(output_path).replace(".md", ".pdf"),
+        css_path="static/styles.css",
     )
 
 

benchmark/report.py

@@ -1,7 +1,8 @@
-# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+# © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 import json
 import sys
 from datetime import datetime
+from os import PathLike
 from pathlib import Path
 from typing import Dict, Optional
 
@@ -14,7 +15,7 @@ from utils import _get_system_info
 import primaite
 
 PLOT_CONFIG = {
-    "size": {"auto_size": False, "width": 1500, "height": 900},
+    "size": {"auto_size": False, "width": 800, "height": 640},
     "template": "plotly_white",
     "range_slider": False,
 }
@@ -144,6 +145,20 @@ def _plot_benchmark_metadata(
         yaxis={"title": "Total Reward"},
         title=title,
     )
+    fig.update_layout(
+        legend=dict(
+            yanchor="top",
+            y=0.99,
+            xanchor="left",
+            x=0.01,
+            bgcolor="rgba(255,255,255,0.3)",
+        )
+    )
+    for trace in fig["data"]:
+        if trace["name"].startswith("Session"):
+            trace["showlegend"] = False
+    fig["data"][0]["name"] = "Individual Sessions"
+    fig["data"][0]["showlegend"] = True
 
     return fig
 
@@ -194,6 +209,7 @@ def _plot_all_benchmarks_combined_session_av(results_directory: Path) -> Figure:
         title=title,
     )
     fig["data"][0]["showlegend"] = True
+    fig.update_layout(legend=dict(yanchor="top", y=-0.2, xanchor="left", x=0.01, orientation="h"))
 
     return fig
 
@@ -234,10 +250,7 @@ def _plot_av_s_per_100_steps_10_nodes(
     """
     major_v = primaite.__version__.split(".")[0]
     title = f"Performance of Minor and Bugfix Releases for Major Version {major_v}"
-    subtitle = (
-        f"Average Training Time per 100 Steps on 10 Nodes "
-        f"(target: <= {PLOT_CONFIG['av_s_per_100_steps_10_nodes_benchmark_threshold']} seconds)"
-    )
+    subtitle = "Average Training Time per 100 Steps on 10 Nodes "
     title = f"{title} <br><sub>{subtitle}</sub>"
 
     layout = go.Layout(
@@ -250,24 +263,12 @@ 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"]
 
-    # Calculate the appropriate maximum y-axis value
-    max_y_axis_value = max(max(times), av_s_per_100_steps_10_nodes_benchmark_threshold) + 1
-
-    fig.add_trace(
-        go.Bar(
-            x=versions,
-            y=times,
-            text=times,
-            textposition="auto",
-        )
-    )
+    fig.add_trace(go.Bar(x=versions, y=times, text=times, textposition="auto", texttemplate="%{y:.3f}"))
 
     fig.update_layout(
         xaxis_title="PrimAITE Version",
         yaxis_title="Avg Time per 100 Steps on 10 Nodes (seconds)",
-        yaxis=dict(range=[0, max_y_axis_value]),
         title=title,
     )
 
@@ -275,7 +276,11 @@ def _plot_av_s_per_100_steps_10_nodes(
 
 
 def build_benchmark_md_report(
-    benchmark_start_time: datetime, session_metadata: Dict, config_path: Path, results_root_path: Path
+    benchmark_start_time: datetime,
+    session_metadata: Dict,
+    config_path: Path,
+    results_root_path: Path,
+    output_path: PathLike,
 ) -> None:
     """
     Generates a Markdown report for a benchmarking session, documenting performance metrics and graphs.
@@ -327,7 +332,7 @@ def build_benchmark_md_report(
     data = benchmark_metadata_dict
     primaite_version = data["primaite_version"]
 
-    with open(version_result_dir / f"PrimAITE v{primaite_version} Benchmark Report.md", "w") as file:
+    with open(output_path, "w") as file:
         # Title
         file.write(f"# PrimAITE v{primaite_version} Learning Benchmark\n")
         file.write("## PrimAITE Dev Team\n")
@@ -401,3 +406,15 @@ def build_benchmark_md_report(
             f"![Performance of Minor and Bugfix Releases for Major Version {major_v}]"
             f"({performance_benchmark_plot_path.name})\n"
         )
+
+
+def md2pdf(md_path: PathLike, pdf_path: PathLike, css_path: PathLike) -> None:
+    """Generate PDF version of Markdown report."""
+    from md2pdf.core import md2pdf
+
+    md2pdf(
+        pdf_file_path=pdf_path,
+        md_file_path=md_path,
+        base_url=Path(md_path).parent,
+        css_file_path=css_path,
+    )

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

@@ -1006,4 +1006,4 @@
         "999": 78.49999999999996,
         "1000": 84.69999999999993
     }
-}
+}

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

@@ -1006,4 +1006,4 @@
         "999": 97.59999999999975,
         "1000": 103.34999999999978
     }
-}
+}

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

@@ -1006,4 +1006,4 @@
         "999": 101.14999999999978,
         "1000": 80.94999999999976
     }
-}
+}

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

@@ -1006,4 +1006,4 @@
         "999": 118.0500000000001,
         "1000": 77.95000000000005
     }
-}
+}

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

@@ -1006,4 +1006,4 @@
         "999": 55.849999999999916,
         "1000": 96.95000000000007
     }
-}
+}

benchmark/results/v3/v3.2.0/v3.2.0_benchmark_metadata.json

@@ -7442,4 +7442,4 @@
             }
         }
     }
-}
+}

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

@@ -1,10 +1,10 @@
-# PrimAITE v3.0.0 Learning Benchmark
+# PrimAITE v3.3.0 Learning Benchmark
 ## PrimAITE Dev Team
-### 2024-07-20
+### 2024-09-02
 
 ---
 ## 1 Introduction
-PrimAITE v3.0.0 was benchmarked automatically upon release. Learning rate metrics were captured to be referenced during system-level testing and user acceptance testing (UAT).
+PrimAITE v3.3.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
@@ -26,12 +26,12 @@ The total reward per episode from each session is captured. This is then used to
 - **Total Sessions:** 5
 - **Total Episodes:** 5005
 - **Total Steps:** 640000
-- **Av Session Duration (s):** 1452.5910
-- **Av Step Duration (s):** 0.0454
-- **Av Duration per 100 Steps per 10 Nodes (s):** 4.5393
+- **Av Session Duration (s):** 1458.2831
+- **Av Step Duration (s):** 0.0456
+- **Av Duration per 100 Steps per 10 Nodes (s):** 4.5571
 ## 4 Graphs
-### 4.1 v3.0.0 Learning Benchmark Plot
-![PrimAITE 3.0.0 Learning Benchmark Plot](PrimAITE v3.0.0 Learning Benchmark.png)
+### 4.1 v3.3.0 Learning Benchmark Plot
+![PrimAITE 3.3.0 Learning Benchmark Plot](PrimAITE v3.3.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

benchmark/static/styles.css

@@ -0,0 +1,34 @@
+body {
+    font-family: 'Arial', sans-serif;
+    line-height: 1.6;
+    /* margin: 1cm; */
+}
+h1, h2, h3, h4, h5, h6 {
+    font-weight: bold;
+    /* margin: 1em 0; */
+}
+p {
+    /* margin: 0.5em 0; */
+}
+ul, ol {
+    margin: 1em 0;
+    padding-left: 1.5em;
+}
+pre {
+    background: #f4f4f4;
+    padding: 0.5em;
+    overflow-x: auto;
+}
+img {
+    max-width: 100%;
+    height: auto;
+}
+table {
+    width: 100%;
+    border-collapse: collapse;
+    margin: 1em 0;
+}
+th, td {
+    padding: 0.5em;
+    border: 1px solid #ddd;
+}

benchmark/utils.py

@@ -1,4 +1,4 @@
-# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+# © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 import platform
 from typing import Dict
 

docs/Makefile

@@ -1,4 +1,4 @@
-# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+# © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 # Minimal makefile for Sphinx documentation
 # You can set these variables from the command line, and also
 # from the environment for the first two.
@@ -8,16 +8,18 @@ SOURCEDIR     = .
 BUILDDIR      = _build
 
 AUTOSUMMARY="source/_autosummary"
+NOTEBOOKS="source/notebooks/notebooks"
 
 # Remove command is different depending on OS
 ifdef OS
-	RM = IF exist $(AUTOSUMMARY) (  RMDIR $(AUTOSUMMARY) /s /q )
+	RM = IF exist $(AUTOSUMMARY) (RMDIR $(AUTOSUMMARY) /s /q) & IF exist $(NOTEBOOKS) (RMDIR $(NOTEBOOKS) /s /q)
 else
    ifeq ($(shell uname), Linux)
-      RM = rm -rf $(AUTOSUMMARY)
+      RM = rm -rf $(AUTOSUMMARY) $(NOTEBOOKS)
    endif
 endif
 
+
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_templates/custom-class-template.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 ..
     Credit to https://github.com/JamesALeedham/Sphinx-Autosummary-Recursion for the custom templates.
@@ -12,7 +12,8 @@
 .. autoclass:: {{ objname }}
    :members:
    :show-inheritance:
-   :inherited-members:
+   :inherited-members: BaseModel
+   :exclude-members: model_computed_fields, model_config, model_fields
    :special-members: __init__, __call__, __add__, __mul__
 
    {% block methods %}
@@ -22,7 +23,14 @@
    .. autosummary::
       :nosignatures:
    {% for item in methods %}
-      {%- if not item.startswith('_') %}
+      {%- if not item.startswith('_') and item not in [
+         'construct', 'copy', 'dict', 'from_orm', 'json', 'model_construct',
+         'model_copy', 'model_dump', 'model_dump_json', 'model_json_schema',
+         'model_parametrized_name', 'model_post_init', 'model_rebuild', '',
+         'model_validate', 'model_validate_json', 'model_validate_strings',
+         'parse_file', 'parse_obj', 'parse_raw', 'schema', 'schema_json',
+         'update_forward_refs', 'validate',
+      ] %}
       ~{{ name }}.{{ item }}
       {%- endif -%}
    {%- endfor %}
@@ -35,7 +43,12 @@
 
    .. autosummary::
    {% for item in attributes %}
+      {%- if not item.startswith('_') and item not in [
+         'model_computed_fields', 'model_config', 'model_extra', 'model_fields',
+         'model_fields_set',
+      ] %}
       ~{{ name }}.{{ item }}
+      {%- endif -%}
    {%- endfor %}
    {% endif %}
    {% endblock %}

docs/_templates/custom-module-template.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 ..
     Credit to https://github.com/JamesALeedham/Sphinx-Autosummary-Recursion for the custom templates.

docs/api.rst

@@ -2,7 +2,7 @@
 
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 ..
    DO NOT DELETE THIS FILE! It contains the all-important `.. autosummary::` directive with `:recursive:` option, without

docs/build-sphinx-docs-to-github-pages.sh

@@ -1,4 +1,4 @@
-# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+# © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 #!/bin/bash
 set -x
 
@@ -43,7 +43,7 @@ touch .nojekyll
 # Add README
 cat > README.md <<EOF
 # README for the Sphinx Docs GitHub Pages Branch
-This branch is simply a cache for the website served from https://{todo:fill in URL}.github.io/PrimAITE/,
+This branch is simply a cache for the website served from https://Autonomous-Resilient-Cyber-Defence.github.io/PrimAITE/,
 and is  not intended to be viewed on github.com.
 For more information on how this site is built using Sphinx, Read the Docs, GitHub Actions/Pages, and demo
 implementation from https://github.com/annegentle, see:

docs/conf.py

@@ -1,4 +1,4 @@
-# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+# © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 # Configuration file for the Sphinx documentation builder.
 #
 # For the full list of built-in configuration values, see the documentation:

docs/index.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 Welcome to PrimAITE's documentation
 ====================================
@@ -17,6 +17,23 @@ What is PrimAITE?
    source/dependencies
    source/glossary
 
+.. toctree::
+   :maxdepth: 8
+   :caption: How To
+   :hidden:
+
+   source/how_to
+   source/how_to_guides/custom_actions
+   source/how_to_guides/custom_environments
+   source/how_to_guides/custom_rewards
+   source/how_to_guides/custom_software
+   source/how_to_guides/using_dev_cli
+   source/how_to_guides/extensible_actions
+   source/how_to_guides/extensible_agents
+   source/how_to_guides/extensible_nodes
+   source/how_to_guides/extensible_rewards
+   source/how_to_guides/primaite_yaml_migration_guide
+
 .. toctree::
    :caption: Usage:
    :hidden:
@@ -25,10 +42,11 @@ What is PrimAITE?
    source/game_layer
    source/simulation
    source/config
-   source/customising_scenarios
+   source/rewards
    source/varying_config_files
    source/environment
    source/action_masking
+   source/node_sets
 
 .. toctree::
    :caption: Notebooks:
@@ -59,6 +77,8 @@ The ARCD Primary-level AI Training Environment (**PrimAITE**) provides an effect
 - Modelling background (green) pattern-of-life;
 - Operates at machine-speed to enable fast training cycles via Reinforcement Learning (RL).
 
+PrimAITE has been designed as an extensible environment and toolkit to support the development, test, training and evaluation of AI-based cyber defensive agents. Whilst PrimAITE ships with a number of example modelled scenarios (a.k.a. Use Cases), it has not been developed to mandate the solving of a single cyber challenge, and instead provides a highly flexible environment application that can be extended and reconfigured by the user to suit their specific cyber defence training and evaluation needs. PrimAITE provides default networks, red agent and green agent behaviour, reward functions, and action / observation space configuration, all of which can be utilised out of the box, but which ultimately can (and in some instances should) be built upon and / or reconfigured to meet the needs of different defensive agent developers. The PrimAITE user guide provides comprehensive instruction on all PrimAITE features, functionality and components, and can be consulted in order to help guide users in any reconfiguration or enhancements they wish to undertake; a library of example Jupyter notebooks are also provided to support such work.
+
 Features
 ^^^^^^^^
 
@@ -66,7 +86,7 @@ PrimAITE incorporates the following features:
 
 - Architected with a separate Simulation layer and Game layer. This separation of concerns defines a clear path towards transfer learning with environments of differing fidelity;
 - Ability to reconfigure an RL reward function based on (a) the ability to counter the modelled adversarial cyber-attack, and (b) the ability to ensure success for green agents;
-- Access Control List (ACL) functions for network devices (routers and firewalls), following standard ACL rule format (e.g., DENY / ALLOW, source / destination IP addresses, protocol and port);
+- Access Control List (ACL) functions for network devices (routers and firewalls), following standard ACL rule format (e.g., DENY / PERMIT, source / destination IP addresses, protocol and port);
 - Application of traffic to the links of the system laydown adheres to the ACL rulesets and routing tables contained within each network device;
 - Provides RL environments adherent to the Farama Foundation Gymnasium (Previously OpenAI Gym) API, allowing integration with any compliant RL Agent frameworks;
 - Provides RL environments adherent to Ray RLlib environment specifications for single-agent and multi-agent scenarios;

docs/source/about.rst

@@ -39,14 +39,15 @@ PrimAITE provides a training and evaluation capability to AI agents in the conte
 
 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).
+All nodes can be configured to contain applications, services, folders, and files (and their status), including a powerful terminal simulation for SSH tunnelling and remote command execution.
 
-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.
+Realistic network traffic generated by software or by users. Packets move through the network devices (switches, routers, firewalls, network interfaces) in accordance to control rules such as: internet protocols, Access control lists (ACLs), and routing tables.
 
-Highlights of PrimAITE’s training and evaluation capability are:
+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;
+- Domain randomisation through stochastic agent behaviour and the ability to switch between scenario variants between environment episodes.
+- Extensible through plugins to model any network behaviour.
 - Can integrate with any Gymnasium / Ray RLlib compliant AI agent.
 
 
@@ -56,303 +57,16 @@ 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)
+* `Pydantic <https://docs.pydantic.dev/latest/>`_ is used for data validation
+* `Platformdirs <https://github.com/platformdirs/platformdirs>`_ is used for storing user data and configuration correctly between platforms
+* `Typer <https://github.com/tiangolo/typer>`_ is used for the Command Line Interface
 * `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
+* `Stable Baselines 3 <https://github.com/DLR-RM/stable-baselines3>`_ is used for ensuring compatibility with RL libraries
+* `Ray RLlib <https://github.com/ray-project/ray>`_ is also used for ensuring compatibility with RL libraries
 
 
 Getting Started with PrimAITE
 -----------------------------
 
 Head over to the :ref:`getting-started` page to install and setup PrimAITE!
-
-..
-  Architecture - Nodes and Links
-  ******************************
-  **Nodes**
-  An inheritance model has been adopted in order to model nodes. All nodes have the following base attributes (Class: Node):
-  * ID
-  * Name
-  * Type (e.g. computer, switch, RTU - enumeration)
-  * Priority (P1, P2, P3, P4 or P5 - enumeration)
-  * Hardware State (ON, OFF, RESETTING, SHUTTING_DOWN, BOOTING - enumeration)
-  Active Nodes also have the following attributes (Class: Active Node):
-  * IP Address
-  * Software State (GOOD, FIXING, COMPROMISED - enumeration)
-  * File System State (GOOD, CORRUPT, DESTROYED, REPAIRING, RESTORING - enumeration)
-  Service Nodes also have the following attributes (Class: Service Node):
-  * List of Services (where service is composed of service name and port). There is no theoretical limit on the number of services that can be modelled. Services and protocols are currently intrinsically linked (i.e. a service is an application on a node transmitting traffic of this protocol type)
-  * Service state (GOOD, FIXING, COMPROMISED, OVERWHELMED - enumeration)
-  Passive Nodes are currently not used (but may be employed for non IP-based components such as machinery actuators in future releases).
-  **Links**
-  Links are modelled both as network edges (networkx) and as Python classes, in order to extend their functionality. Links include the following attributes:
-  * ID
-  * Name
-  * Bandwidth (bits/s)
-  * Source node ID
-  * Destination node ID
-  * Protocol list (containing the loading of protocols currently running on the link)
-  When the simulation runs, IERs are applied to the links in order to model traffic loading, individually assigned to each protocol. This allows green (background) and red agent behaviour to be modelled, and defensive agents to identify suspicious traffic patterns at a protocol / traffic loading level of fidelity.
-  Information Exchange Requirements (IERs)
-  ****************************************
-  PrimAITE adopts the concept of Information Exchange Requirements (IERs) to model both green agent (background) and red agent (adversary) behaviour. IERs are used to initiate modelling of traffic loading on the network, and have the following attributes:
-  * ID
-  * Start step (i.e. which step in the training episode should the IER start)
-  * End step (i.e. which step in the training episode should the IER end)
-  * Source node ID
-  * Destination node ID
-  * Load (bits/s)
-  * Protocol
-  * Port
-  * Running status (i.e. on / off)
-  The application of green agent IERs between a source and destination follows a number of rules. Specifically:
-  1. Does the current simulation time step fall between IER start and end step
-  2. Is the source node operational (both physically and at an O/S level), and is the service (protocol / port) associated with the IER (a) present on this node, and (b) in an operational state (i.e. not FIXING)
-  3. Is the destination node operational (both physically and at an O/S level), and is the service (protocol / port) associated with the IER (a) present on this node, and (b) in an operational state (i.e. not FIXING)
-  4. Are there any Access Control List rules in place that prevent the application of this IER
-  5. Are all switches in the (OSPF) path between source and destination operational (both physically and at an O/S level)
-  For red agent IERs, the application of IERs between a source and destination follows a number of subtly different rules. Specifically:
-  1. Does the current simulation time step fall between IER start and end step
-  2. Is the source node operational, and is the service (protocol / port) associated with the IER (a) present on that node and (b) already in a compromised state
-  3. Is the destination node operational, and is the service (protocol / port) associated with the IER present on that node
-  4. Are there any Access Control List rules in place that prevent the application of this IER
-  5. Are all switches in the (OSPF) path between source and destination operational (both physically and at an O/S level)
-  Assuming the rules pass, the IER is applied to all relevant links (based on use of OSPF) between source and destination.
-  Node Pattern-of-Life
-  ********************
-  Every node can be impacted (i.e. have a status change applied to it) by either green agent pattern-of-life or red agent pattern-of-life. This is distinct from IERs, and allows for attacks (and defence) to be modelled purely within the confines of a node.
-  The status changes that can be made to a node are as follows:
-  * All Nodes:
-    * Hardware State:
-        * ON
-        * OFF
-        * RESETTING - when a status of resetting is entered, the node will automatically exit this state after a number of steps (as defined by the nodeResetDuration configuration item) after which it returns to an ON state
-        * BOOTING
-        * SHUTTING_DOWN
-  * Active Nodes and Service Nodes:
-    * Software State:
-        * GOOD
-        * FIXING - when a status of FIXING is entered, the node will automatically exit this state after a number of steps (as defined by the osFIXINGDuration configuration item) after which it returns to a GOOD state
-        * COMPROMISED
-    * File System State:
-        * GOOD
-        * CORRUPT (can be resolved by repair or restore)
-        * DESTROYED (can be resolved by restore only)
-        * REPAIRING - when a status of repairing is entered, the node will automatically exit this state after a number of steps (as defined by the fileSystemRepairingLimit configuration item) after which it returns to a GOOD state
-        * RESTORING - when a status of repairing is entered, the node will automatically exit this state after a number of steps (as defined by the fileSystemRestoringLimit configuration item) after which it returns to a GOOD state
-  * Service Nodes only:
-    * Service State (for any associated service):
-        * GOOD
-        * FIXING - when a status of FIXING is entered, the service will automatically exit this state after a number of steps (as defined by the serviceFIXINGDuration configuration item) after which it returns to a GOOD state
-        * COMPROMISED
-        * OVERWHELMED
-  Red agent pattern-of-life has an additional feature not found in the green pattern-of-life. This is the ability to influence the state of the attributes of a node via a number of different conditions:
-    * DIRECT:
-    The pattern-of-life described by the configuration file item will be applied regardless of any other conditions in the network. This is particularly useful for direct red agent entry into the network.
-    * IER:
-    The pattern-of-life described by the configuration file item will be applied to the service on the node, only if there is an IER of the same protocol / service type incoming at the specified timestep.
-    * SERVICE:
-    The pattern-of-life described by the configuration file item will be applied to the node based on the state of a service. The service can either be on the same node, or a different node within the network.
-  Access Control List modelling
-  *****************************
-  An Access Control List (ACL) is modelled to provide the means to manage traffic flows in the system. This will allow defensive agents the means to turn on / off rules, or potentially create new rules, to counter an attack.
-  The ACL follows a standard network firewall format. For example:
-  .. list-table:: ACL example
-    :widths: 25 25 25 25 25
-    :header-rows: 1
-    * - Permission
-      - Source IP
-      - Dest IP
-      - Protocol
-      - Port
-    * - DENY
-      - 192.168.1.2
-      - 192.168.1.3
-      - HTTPS
-      - 443
-    * - ALLOW
-      - 192.168.1.4
-      - ANY
-      - SMTP
-      - 25
-    * - DENY
-      - ANY
-      - 192.168.1.5
-      - ANY
-      - ANY
-  All ACL rules are considered when applying an IER. Logic follows the order of rules, so a DENY or ALLOW for the same parameters will override an earlier entry.
-  Observation Spaces
-  ******************
-  The observation space provides the blue agent with information about the current status of nodes and links.
-  PrimAITE builds on top of Gymnasium Spaces to create an observation space that is easily configurable for users. It's made up of components which are managed by the :py:class:`primaite.environment.observations.ObservationsHandler`. Each training scenario can define its own observation space, and the user can choose which information to inlude, and how it should be formatted.
-  NodeLinkTable component
-  -----------------------
-  For example, the :py:class:`primaite.environment.observations.NodeLinkTable` component represents the status of nodes and links as a ``gym.spaces.Box`` with an example format shown below:
-  An example observation space is provided below:
-  .. list-table:: Observation Space example
-    :widths: 25 25 25 25 25 25 25
-    :header-rows: 1
-    * -
-      - ID
-      - Hardware State
-      - Software State
-      - File System State
-      - Service / Protocol A
-      - Service / Protocol B
-    * - Node A
-      - 1
-      - 1
-      - 1
-      - 1
-      - 1
-      - 1
-    * - Node B
-      - 2
-      - 1
-      - 3
-      - 1
-      - 1
-      - 1
-    * - Node C
-      - 3
-      - 2
-      - 1
-      - 1
-      - 3
-      - 2
-    * - Link 1
-      - 5
-      - 0
-      - 0
-      - 0
-      - 0
-      - 10000
-    * - Link 2
-      - 6
-      - 0
-      - 0
-      - 0
-      - 0
-      - 10000
-    * - Link 3
-      - 7
-      - 0
-      - 0
-      - 0
-      - 5000
-      - 0
-  For the nodes, the following values are represented:
-  .. code-block::
-    [
-      ID
-      Hardware State            (1=ON,   2=OFF,  3=RESETTING,  4=SHUTTING_DOWN, 5=BOOTING)
-      Operating System State    (0=none, 1=GOOD, 2=PATCHING,   3=COMPROMISED)
-      File System State         (0=none, 1=GOOD, 2=CORRUPT,    3=DESTROYED,  4=REPAIRING, 5=RESTORING)
-      Service1/Protocol1 state  (0=none, 1=GOOD, 2=FIXING,   3=COMPROMISED)
-      Service2/Protocol2 state  (0=none, 1=GOOD, 2=FIXING,   3=COMPROMISED)
-    ]
-  (Note that each service available in the network is provided as a column, although not all nodes may utilise all services)
-  For the links, the following statuses are represented:
-  .. code-block::
-    [
-      ID
-      Hardware State            (0=not applicable)
-      Operating System State    (0=not applicable)
-      File System State         (0=not applicable)
-      Service1/Protocol1 state  (Traffic load from this protocol on this link)
-      Service2/Protocol2 state  (Traffic load from this protocol on this link)
-    ]
-  NodeStatus component
-  ----------------------
-  This is a MultiDiscrete observation space that can be though of as a one-dimensional vector of discrete states.
-  The example above would have the following structure:
-  .. code-block::
-    [
-      node1_info
-      node2_info
-      node3_info
-    ]
-  Each ``node_info`` contains the following:
-  .. code-block::
-    [
-      hardware_state    (0=none, 1=ON,   2=OFF,      3=RESETTING, 4=SHUTTING_DOWN, 5=BOOTING)
-      software_state    (0=none, 1=GOOD, 2=PATCHING, 3=COMPROMISED)
-      file_system_state (0=none, 1=GOOD, 2=CORRUPT,  3=DESTROYED, 4=REPAIRING, 5=RESTORING)
-      service1_state    (0=none, 1=GOOD, 2=FIXING, 3=COMPROMISED)
-      service2_state    (0=none, 1=GOOD, 2=FIXING, 3=COMPROMISED)
-    ]
-  In a network with three nodes and two services, the full observation space would have 15 elements. It can be written with ``gym`` notation to indicate the number of discrete options for each of the elements of the observation space. For example:
-  .. code-block::
-    gym.spaces.MultiDiscrete([4,5,6,4,4,4,5,6,4,4,4,5,6,4,4])
-  .. note::
-    NodeStatus observation component provides information only about nodes. Links are not considered.
-  LinkTrafficLevels
-  -----------------
-  This component is a MultiDiscrete space showing the traffic flow levels on the links in the network, after applying a threshold to convert it from a continuous to a discrete value.
-  There are two configurable parameters:
-  * ``quantisation_levels`` determines how many discrete bins to use for converting the continuous traffic value to discrete (default is 5).
-  * ``combine_service_traffic`` determines whether to separately output traffic use for each network protocol or whether to combine them into an overall value for the link. (default is ``True``)
-  For example, with default parameters and a network with three links, the structure of this component would be:
-  .. code-block::
-    [
-      link1_status
-      link2_status
-      link3_status
-    ]
-  Each ``link_status`` is a number from 0-4 representing the network load in relation to bandwidth.
-  .. code-block::
-    0 = No traffic (0%)
-    1 = low traffic (1%-33%)
-    2 = medium traffic (33%-66%)
-    3 = high traffic (66%-99%)
-    4 = max traffic/ overwhelmed (100%)
-  Using ``gym`` notation, the shape of the obs space is: ``gym.spaces.MultiDiscrete([5,5,5])``.
-  Action Spaces
-  **************
-  The action space available to the blue agent comes in two types:
-  1. Node-based
-  2. Access Control List
-  3. Any (Agent can take both node-based and ACL-based actions)
-  The choice of action space used during a training session is determined in the config_[name].yaml file.
-  **Node-Based**
-  The agent is able to influence the status of nodes by switching them off, resetting, or FIXING operating systems and services. In this instance, the action space is a Gymnasium spaces.Discrete type, as follows:
-  * Dictionary item {... ,1: [x1, x2, x3,x4] ...}
-    The placeholders inside the list under the key '1' mean the following:
-      * [0, num nodes] - Node ID (0 = nothing, node ID)
-      * [0, 4] - What property it's acting on (0 = nothing, 1 = state, 2 = SoftwareState, 3 = service state, 4 = file system state)
-      * [0, 3] - Action on property (0 = nothing, 1 = on / scan, 2 = off / repair, 3 = reset / patch / restore)
-      * [0, num services] - Resolves to service ID (0 = nothing, resolves to service)
-  **Access Control List**
-  The blue agent is able to influence the configuration of the Access Control List rule set (which implements a system-wide firewall). In this instance, the action space is an Gymnasium spaces.Discrete type, as follows:
-    * Dictionary item {... ,1: [x1, x2, x3, x4, x5, x6] ...}
-    The placeholders inside the list under the key '1' mean the following:
-      * [0, 2] - Action (0 = do nothing, 1 = create rule, 2 = delete rule)
-      * [0, 1] - Permission (0 = DENY, 1 = ALLOW)
-      * [0, num nodes] - Source IP (0 = any, then 1 -> x resolving to IP addresses)
-      * [0, num nodes] - Dest IP (0 = any, then 1 -> x resolving to IP addresses)
-      * [0, num services] - Protocol (0 = any, then 1 -> x resolving to protocol)
-      * [0, num ports] - Port (0 = any, then 1 -> x resolving to port)
-  **ANY**
-  The agent is able to carry out both **Node-Based** and **Access Control List** operations.
-  This means the dictionary will contain key-value pairs in the format of BOTH Node-Based and Access Control List as seen above.
-  Rewards
-  *******
-  A reward value is presented back to the blue agent on the conclusion of every step. The reward value is calculated via two methods which combine to give the total value:
-  1. Node and service status
-  2. IER status
-  **Node and service status**
-  On every step, the status of each node is compared against both a reference environment (simulating the situation if the red and blue agents had not impacted the environment)
-  and the before and after state of the environment. If the comparison against the reference environment shows no difference, then the score provided is "AllOK". If there is a
-  difference with respect to the reference environment, the before and after states are compared, and a score determined. See :ref:`config` for details of reward values.
-  **IER status**
-  On every step, the full IER set is examined to determine whether green and red agent IERs are being permitted to run. Any red agent IERs running incur a penalty; any green agent
-  IERs not permitted to run also incur a penalty. See :ref:`config` for details of reward values.
-  Future Enhancements
-  *******************
-  The PrimAITE project has an ambition to include the following enhancements in future releases:
-  * Integration with a suitable standardised framework to allow multi-agent integration
-  * Integration with external threat emulation tools, either using off-line data, or integrating at runtime

docs/source/action_masking.rst

@@ -1,14 +1,18 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+
+.. _action_masking:
 
 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,
+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.
 
+*Note: just because an action is available in the action mask does not mean it will be successful when executed. It just means it's possible to try to execute the action at this time.*
+
 Configuration
 =============
 Action masking is supported for agents that use the `ProxyAgent` class (the class used for connecting to RL algorithms).
@@ -18,112 +22,127 @@ 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.                                                     |
-+------------------------------------------+---------------------------------------------------------------------+
++------------------------------------------+------------------------------------------------+
+| Action                                   | Action Mask Logic                              |
++==========================================+================================================+
+| **do-nothing**                           | Always Possible.                               |
++------------------------------------------+------------------------------------------------+
+| **node-service-scan**                    | Node is on. Service is running.                |
++------------------------------------------+------------------------------------------------+
+| **node-service-stop**                    | Node is on. Service is running.                |
++------------------------------------------+------------------------------------------------+
+| **node-service-start**                   | Node is on. Service is stopped.                |
++------------------------------------------+------------------------------------------------+
+| **node-service-pause**                   | Node is on. Service is running.                |
++------------------------------------------+------------------------------------------------+
+| **node-service-resume**                  | Node is on. Service is paused.                 |
++------------------------------------------+------------------------------------------------+
+| **node-service-restart**                 | Node is on. Service is running.                |
++------------------------------------------+------------------------------------------------+
+| **node-service-disable**                 | Node is on.                                    |
++------------------------------------------+------------------------------------------------+
+| **node-service-enable**                  | Node is on. Service is disabled.               |
++------------------------------------------+------------------------------------------------+
+| **node-service-fix**                     | Node is on. Service is running.                |
++------------------------------------------+------------------------------------------------+
+| **node-application-execute**             | Node is on.                                    |
++------------------------------------------+------------------------------------------------+
+| **node-application-scan**                | Node is on. Application is running.            |
++------------------------------------------+------------------------------------------------+
+| **node-application-close**               | Node is on. Application is running.            |
++------------------------------------------+------------------------------------------------+
+| **node-application-fix**                 | Node is on. Application is running.            |
++------------------------------------------+------------------------------------------------+
+| **node-application-install**             | Node is on.                                    |
++------------------------------------------+------------------------------------------------+
+| **node-application-remove**              | Node is on.                                    |
++------------------------------------------+------------------------------------------------+
+| **node-file-scan**                       | Node is on. File exists. File not deleted.     |
++------------------------------------------+------------------------------------------------+
+| **node-file-create**                     | Node is on.                                    |
++------------------------------------------+------------------------------------------------+
+| **node-file-checkhash**                  | Node is on. File exists. File not deleted.     |
++------------------------------------------+------------------------------------------------+
+| **node-file-delete**                     | Node is on. File exists.                       |
++------------------------------------------+------------------------------------------------+
+| **node-file-repair**                     | Node is on. File exists. File not deleted.     |
++------------------------------------------+------------------------------------------------+
+| **node-file-restore**                    | Node is on. File exists. File is deleted.      |
++------------------------------------------+------------------------------------------------+
+| **node-file-corrupt**                    | Node is on. File exists. File not deleted.     |
++------------------------------------------+------------------------------------------------+
+| **node-file-access**                     | Node is on. File exists. File not deleted.     |
++------------------------------------------+------------------------------------------------+
+| **node-folder-create**                   | Node is on.                                    |
++------------------------------------------+------------------------------------------------+
+| **node-folder-scan**                     | Node is on. Folder exists. Folder not deleted. |
++------------------------------------------+------------------------------------------------+
+| **node-folder-checkhash**                | Node is on. Folder exists. Folder not deleted. |
++------------------------------------------+------------------------------------------------+
+| **node-folder-repair**                   | Node is on. Folder exists. Folder not deleted. |
++------------------------------------------+------------------------------------------------+
+| **node-folder-restore**                  | Node is on. Folder exists. Folder is deleted.  |
++------------------------------------------+------------------------------------------------+
+| **node-os-scan**                         | Node is on.                                    |
++------------------------------------------+------------------------------------------------+
+| **host-nic-enable**                      | NIC is disabled. Node is on.                   |
++------------------------------------------+------------------------------------------------+
+| **host-nic-disable**                     | NIC is enabled. Node is on.                    |
++------------------------------------------+------------------------------------------------+
+| **node-shutdown**                        | Node is on.                                    |
++------------------------------------------+------------------------------------------------+
+| **node-startup**                         | Node is off.                                   |
++------------------------------------------+------------------------------------------------+
+| **node-reset**                           | Node is on.                                    |
++------------------------------------------+------------------------------------------------+
+| **node-nmap-ping-scan**                  | Node is on.                                    |
++------------------------------------------+------------------------------------------------+
+| **node-nmap-port-scan**                  | Node is on.                                    |
++------------------------------------------+------------------------------------------------+
+| **node-network-service-recon**           | Node is on.                                    |
++------------------------------------------+------------------------------------------------+
+| **network-port-enable**                  | Node is on. Router is on.                      |
++------------------------------------------+------------------------------------------------+
+| **network-port-disable**                 | Router is on.                                  |
++------------------------------------------+------------------------------------------------+
+| **router-acl-add-rule**                  | Router is on.                                  |
++------------------------------------------+------------------------------------------------+
+| **router-acl-remove-rule**               | Router is on.                                  |
++------------------------------------------+------------------------------------------------+
+| **firewall-acl-add-rule**                | Firewall is on.                                |
++------------------------------------------+------------------------------------------------+
+| **firewall-acl-remove-rule**             | Firewall is on.                                |
++------------------------------------------+------------------------------------------------+
+| **configure-database-client**            | Node is on.                                    |
++------------------------------------------+------------------------------------------------+
+| **configure-ransomware-script**          | Node is on.                                    |
++------------------------------------------+------------------------------------------------+
+| **c2-server-ransomware-configure**       | Node is on.                                    |
++------------------------------------------+------------------------------------------------+
+| **configure-dos-bot**                    | Node is on.                                    |
++------------------------------------------+------------------------------------------------+
+| **configure-c2-beacon**                  | Node is on.                                    |
++------------------------------------------+------------------------------------------------+
+| **c2-server-ransomware-launch**          | Node is on.                                    |
++------------------------------------------+------------------------------------------------+
+| **c2-server-terminal-command**           | Node is on.                                    |
++------------------------------------------+------------------------------------------------+
+| **c2-server-data-exfiltrate**            | Node is on.                                    |
++------------------------------------------+------------------------------------------------+
+| **node-account-change-password**         | Node is on.                                    |
++------------------------------------------+------------------------------------------------+
+| **node-session-remote-login**            | Node is on.                                    |
++------------------------------------------+------------------------------------------------+
+| **node-session-remote-logoff**           | Node is on.                                    |
++------------------------------------------+------------------------------------------------+
+| **node-send-remote-command**             | Node 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.
+The environment iterates over the RL agent's ``action_map`` and generates the corresponding simulator :ref:`request <request_system>` string. It uses the :py:meth:`RequestManager.check_valid()<primaite.simulator.core.RequestManager.check_valid>` method to invoke the relevant :py:class:`RequestPermissionValidator <primaite.simulator.core.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.
+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. or 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/config.rst

@@ -1,6 +1,8 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+
+.. _Configurable_Items:
 
 PrimAITE |VERSION| Configuration
 ********************************

docs/source/configuration/agents.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 
 ``agents``
@@ -13,39 +13,19 @@ Agents can be scripted (deterministic and stochastic), or controlled by a reinfo
 .. code-block:: yaml
 
     agents:
-        - ref: red_agent_example
-            ...
-        - ref: blue_agent_example
-            ...
-        - ref: green_agent_example
-            team: GREEN
-            type: ProbabilisticAgent
-            observation_space:
-                type: UC2GreenObservation
-            action_space:
-                action_list:
-                - type: DONOTHING
-                - type: NODE_APPLICATION_EXECUTE
-            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
+    - ref: red_agent_example
+        ...
+    - ref: blue_agent_example
+        ...
+    - ref: green_agent_example
+    team: GREEN
+    type: probabilistic-agent
 
-            reward_function:
-                reward_components:
-                - type: DUMMY
-
-            agent_settings:
-                start_settings:
-                    start_step: 5
-                    frequency: 4
-            variance: 3
-            flatten_obs: False
+    agent_settings:
+      start_step: 5
+      frequency: 4
+      variance: 3
+      flatten_obs: False
 
 ``ref``
 -------
@@ -57,13 +37,13 @@ Specifies if the agent is malicious (``RED``), benign (``GREEN``), or defensive
 
 ``type``
 --------
-Specifies which class should be used for the agent. ``ProxyAgent`` is used for agents that receive instructions from an RL algorithm. Scripted agents like ``RedDatabaseCorruptingAgent`` and ``ProbabilisticAgent`` generate their own behaviour.
+Specifies which class should be used for the agent. ``proxy-agent`` is used for agents that receive instructions from an RL algorithm. Scripted agents like ``red-database-corrupting-agent`` and ``probabilistic-agent`` generate their own behaviour.
 
 Available agent types:
 
-- ``ProbabilisticAgent``
-- ``ProxyAgent``
-- ``RedDatabaseCorruptingAgent``
+- ``probabilistic-agent``
+- ``proxy-agent``
+- ``red-database-corrupting-agent``
 
 ``observation_space``
 ---------------------
@@ -79,10 +59,10 @@ selects which python class from the :py:mod:`primaite.game.agent.observation` mo
 
 Allows configuration of the chosen observation type. These are optional.
 
-    * ``num_services_per_node``, ``num_folders_per_node``, ``num_files_per_folder``, ``num_nics_per_node`` all define the shape of the observation space. The size and shape of the obs space must remain constant, but the number of files, folders, ACL rules, and other components can change within an episode. Therefore padding is performed and these options set the size of the obs space.
+    * ``num_services_per_node``, ``num_folders_per_node``, ``num_files_per_folder``, ``num_nics_per_node`` all define the shape of the observation space. The size and shape of the obs space must remain constant, but the number of files, folders, acl rules, and other components can change within an episode. Therefore padding is performed and these options set the size of the obs space.
     * ``nodes``: list of nodes that will be present in this agent's observation space. The ``node_ref`` relates to the human-readable unique reference defined later in the ``simulation`` part of the config. Each node can also be configured with services, and files that should be monitored.
     * ``links``: list of links that will be present in this agent's observation space. The ``link_ref`` relates to the human-readable unique reference defined later in the ``simulation`` part of the config.
-    * ``acl``: configure how the agent reads the access control list on the router in the simulation. ``router_node_ref`` is for selecting which router's ACL table should be used. ``ip_list`` sets the encoding of ip addresses as integers within the observation space.
+    * ``acl``: configure how the agent reads the access control list on the router in the simulation. ``router_node_ref`` is for selecting which router's acl table should be used. ``ip_list`` sets the encoding of ip addresses as integers within the observation space.
 
 For more information see :py:mod:`primaite.game.agent.observations`
 
@@ -91,10 +71,6 @@ For more information see :py:mod:`primaite.game.agent.observations`
 
 The action space is configured to be made up of individual action types. Once configured, the agent can select an action type and some optional action parameters at every step. For example: The ``NODE_SERVICE_SCAN`` action takes the parameters ``node_id`` and ``service_id``.
 
-``action_list``
-^^^^^^^^^^^^^^^
-
-A list of action modules. The options are listed in the :py:mod:`primaite.game.agent.actions.ActionManager.act_class_identifiers` module.
 
 ``action_map``
 ^^^^^^^^^^^^^^
@@ -120,16 +96,21 @@ Similar to action space, this is defined as a list of components from the :py:mo
 
 ``reward_components``
 ^^^^^^^^^^^^^^^^^^^^^
-
-A list of reward types from :py:mod:`primaite.game.agent.rewards.RewardFunction.rew_class_identifiers`
+A list of available reward types from :py:mod:`primaite.game.agent.rewards.RewardFunction.rew_class_identifiers`
 
 e.g.
 
 .. code-block:: yaml
 
     reward_components:
-        - type: DUMMY
-        - type: DATABASE_FILE_INTEGRITY
+        - type: dummy
+          weight: 1.0
+        - type: database-file-integrity
+          weight: 0.40
+          options:
+            node_hostname: database_server
+            folder_name: database
+            file_name: database.db
 
 
 ``agent_settings``
@@ -142,10 +123,9 @@ e.g.
 .. code-block:: yaml
 
     agent_settings:
-        start_settings:
-            start_step: 25
-            frequency: 20
-            variance: 5
+        start_step: 25
+        frequency: 20
+        variance: 5
 
 ``start_step``
 ^^^^^^^^^^^^^^
@@ -172,3 +152,9 @@ The amount of timesteps that the frequency can randomly change.
 ---------------
 
 If ``True``, gymnasium flattening will be performed on the observation space before sending to the agent. Set this to ``True`` if your agent does not support nested observation spaces.
+
+``Agent History``
+-----------------
+
+Agents will record their action log for each step. This is a summary of what the agent did, along with response information from requests within the simulation.
+A summary of the actions taken by the agent can be viewed using the `show_history()` function. By default, this will display all actions taken apart from ``do-nothing``.

docs/source/configuration/game.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 
 ``game``
@@ -28,6 +28,7 @@ This section defines high-level settings that apply across the game, currently i
                 high: 10
                 medium: 5
                 low: 0
+        seed: 1
 
 ``max_episode_length``
 ----------------------
@@ -41,16 +42,21 @@ The maximum number of episodes a Reinforcement Learning agent(s) can be trained
 
 A list of ports that the Reinforcement Learning agent(s) are able to see in the observation space.
 
-See :ref:`List of Ports <List of Ports>` for a list of ports.
+See :py:const:`primaite.utils.validation.port.PORT_LOOKUP` for a list of ports.
 
 ``protocols``
 -------------
 
 A list of protocols that the Reinforcement Learning agent(s) are able to see in the observation space.
 
-See :ref:`List of IPProtocols <List of IPProtocols>` for a list of protocols.
+See :py:const:`primaite.utils.validation.ip_protocol.PROTOCOL_LOOKUP` for a list of protocols.
 
 ``thresholds``
 --------------
 
 These are used to determine the thresholds of high, medium and low categories for counted observation occurrences.
+
+``seed``
+--------
+
+Used to configure the random seeds used within PrimAITE, ensuring determinism within episode/session runs. If empty or set to -1, no seed is set. The given seed value is logged (by default) in ``primaite/<VERSION>/sessions/<DATE>/<TIME>/simulation_output``.

docs/source/configuration/io_settings.rst

@@ -1,7 +1,8 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
+.. _io_settings:
 
 ``io_settings``
 ===============
@@ -13,7 +14,6 @@ This section configures how PrimAITE saves data during simulation and training.
 .. code-block:: yaml
 
     io_settings:
-        # save_logs: True
         save_agent_actions: True
         save_step_metadata: False
         save_pcap_logs: False
@@ -25,11 +25,6 @@ This section configures how PrimAITE saves data during simulation and training.
         agent_log_level: INFO
 
 
-``save_logs``
--------------
-
-*currently unused*.
-
 ``save_agent_actions``
 ----------------------
 

docs/source/configuration/simulation.rst

@@ -1,12 +1,11 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 
 ``simulation``
 ==============
-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.
-
+In this section the network layout is defined. This part of the config follows a hierarchical structure.
 At the top level of the network are ``nodes``, ``links`` and ``airspace``.
 
 e.g.
@@ -26,7 +25,7 @@ e.g.
 ``nodes``
 ---------
 
-This is where the list of nodes are defined. Some items will differ according to the node type, however, there will be common items such as a node's reference (which is used by the agent), the node's ``type`` and ``hostname``
+This is where the list of nodes are defined. Some items will differ according to the node type, however, there will be common items such as a node's hostname (which is used by the agent) and the node's ``type``.
 
 To see the configuration for these nodes, refer to the following:
 
@@ -74,10 +73,6 @@ this results in:
         endpoint_b_port: 2 # port 2 on switch
         bandwidth: 100
 
-``ref``
-^^^^^^^
-
-The human readable name for the link. Not used in code, however is useful for a human to understand what the link is for.
 
 ``endpoint_a_hostname``
 ^^^^^^^^^^^^^^^^^^^^^^^

docs/source/configuration/simulation/nodes/common/common.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 .. _Node Attributes:
 

docs/source/configuration/simulation/nodes/common/common_host_node_attributes.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 .. _common_host_node_attributes:
 

docs/source/configuration/simulation/nodes/common/common_network_node_attributes.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 .. _common_network_node_attributes:
 

docs/source/configuration/simulation/nodes/common/common_node_attributes.rst

@@ -1,14 +1,9 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 .. _common_node_attributes:
 
-``ref``
--------
-
-Human readable name used as reference for the |NODE|. Not used in code.
-
 ``hostname``
 ------------
 
@@ -53,3 +48,60 @@ The number of time steps required to occur in order for the node to cycle from `
 Optional. Default value is ``3``.
 
 The number of time steps required to occur in order for the node to cycle from ``ON`` to ``SHUTTING_DOWN`` and then finally ``OFF``.
+
+``file_system``
+---------------
+
+Optional.
+
+The file system of the node. This configuration allows nodes to be initialised with files and/or folders.
+
+The file system takes a list of folders and files.
+
+Example:
+
+.. code-block:: yaml
+
+    simulation:
+      network:
+        nodes:
+        - hostname: client_1
+          type: computer
+          ip_address: 192.168.10.11
+          subnet_mask: 255.255.255.0
+          default_gateway: 192.168.10.1
+          file_system:
+            - empty_folder  # example of an empty folder
+            - downloads:
+              - "test_1.txt"  # files in the downloads folder
+              - "test_2.txt"
+            - root:
+              - passwords:  # example of file with size and type
+                  size: 69  # size in bytes
+                  type: TXT  # See FileType for list of available file types
+
+List of file types: :py:mod:`primaite.simulator.file_system.file_type.FileType`
+
+``users``
+---------
+
+The list of pre-existing users that are additional to the default admin user (``username=admin``, ``password=admin``).
+Additional users are configured as an array and must contain a ``username``, ``password``, and can contain an optional
+boolean ``is_admin``.
+
+Example of adding two additional users to a node:
+
+.. code-block:: yaml
+
+    simulation:
+      network:
+        nodes:
+        - hostname: [hostname]
+          type: [Node Type]
+          users:
+            - username: jane.doe
+              password: '1234'
+              is_admin: true
+            - username: john.doe
+              password: password_1
+              is_admin: false

docs/source/configuration/simulation/nodes/common/node_type_list.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 ``type``
 --------
@@ -12,6 +12,7 @@ Available options are:
 - ``computer``
 - ``firewall``
 - ``router``
+- ``wireless_router``
 - ``server``
 - ``switch``
 

docs/source/configuration/simulation/nodes/computer.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 .. _computer_configuration:
 
@@ -17,19 +17,18 @@ example computer
 .. code-block:: yaml
 
     simulation:
-        network:
-            nodes:
-                - ref: client_1
-                hostname: client_1
-                type: computer
-                ip_address: 192.168.0.10
-                subnet_mask: 255.255.255.0
-                default_gateway: 192.168.0.1
-                dns_server: 192.168.1.10
-                applications:
-                    ...
-                services:
-                    ...
+      network:
+        nodes:
+        - hostname: client_1
+          type: computer
+          ip_address: 192.168.0.10c
+          subnet_mask: 255.255.255.0
+          default_gateway: 192.168.0.1
+          dns_server: 192.168.1.10
+          applications:
+            ...
+          services:
+            ...
 
 .. include:: common/common_node_attributes.rst
 

docs/source/configuration/simulation/nodes/firewall.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 .. _firewall_configuration:
 
@@ -19,38 +19,35 @@ example firewall
 .. code-block:: yaml
 
     simulation:
-        network:
-            nodes:
-                - ref: firewall
-                    hostname: firewall
-                    type: firewall
-                    start_up_duration: 0
-                    shut_down_duration: 0
-                    ports:
-                        external_port: # port 1
-                            ip_address: 192.168.20.1
-                            subnet_mask: 255.255.255.0
-                        internal_port: # port 2
-                            ip_address: 192.168.1.2
-                            subnet_mask: 255.255.255.0
-                        dmz_port: # port 3
-                            ip_address: 192.168.10.1
-                            subnet_mask: 255.255.255.0
-                    acl:
-                        internal_inbound_acl:
-                            ...
-                        internal_outbound_acl:
-                            ...
-                        dmz_inbound_acl:
-                            ...
-                        dmz_outbound_acl:
-                            ...
-                        external_inbound_acl:
-                            ...
-                        external_outbound_acl:
-                            ...
-                    routes:
-                        ...
+      network:
+        nodes:
+          - hostname: firewall
+            type: firewall
+            ports:
+              external_port: # port 1
+                ip_address: 192.168.20.1
+                subnet_mask: 255.255.255.0
+              internal_port: # port 2
+                ip_address: 192.168.1.2
+                subnet_mask: 255.255.255.0
+              dmz_port: # port 3
+                ip_address: 192.168.10.1
+                subnet_mask: 255.255.255.0
+            acl:
+              internal_inbound_acl:
+                ...
+              internal_outbound_acl:
+                ...
+              dmz_inbound_acl:
+                ...
+              dmz_outbound_acl:
+                ...
+              external_inbound_acl:
+                ...
+              external_outbound_acl:
+                ...
+            routes:
+                ...
 
 .. include:: common/common_node_attributes.rst
 
@@ -70,18 +67,18 @@ The ports should be defined with an ip address and subnet mask e.g.
 .. code-block:: yaml
 
     nodes:
-        - ref: firewall
-        ...
+      - hostname: firewall
+      ...
         ports:
-            external_port: # port 1
-                ip_address: 192.168.20.1
-                subnet_mask: 255.255.255.0
-            internal_port: # port 2
-                ip_address: 192.168.1.2
-                subnet_mask: 255.255.255.0
-            dmz_port: # port 3
-                ip_address: 192.168.10.1
-                subnet_mask: 255.255.255.0
+          external_port: # port 1
+            ip_address: 192.168.20.1
+            subnet_mask: 255.255.255.0
+          internal_port: # port 2
+            ip_address: 192.168.1.2
+            subnet_mask: 255.255.255.0
+          dmz_port: # port 3
+            ip_address: 192.168.10.1
+            subnet_mask: 255.255.255.0
 
 ``ip_address``
 """"""""""""""
@@ -129,21 +126,21 @@ example:
 .. code-block:: yaml
 
     nodes:
-        - ref: firewall
+      - hostname: firewall
         ...
         acl:
-            internal_inbound_acl:
-                21: # position 21 on ACL list
-                    action: PERMIT  # allow packets that
-                    src_port: POSTGRES_SERVER   # are emitted from the POSTGRES_SERVER port
-                    dst_port: POSTGRES_SERVER   # are going towards an POSTGRES_SERVER port
-                22: # position 22 on ACL list
-                    action: PERMIT  # allow packets that
-                    src_port: ARP   # are emitted from the ARP port
-                    dst_port: ARP   # are going towards an ARP port
-                23: # position 23 on ACL list
-                    action: PERMIT  # allow packets that
-                    protocol: ICMP  # are ICMP
+          internal_inbound_acl:
+            21: # position 21 on ACL list
+              action: PERMIT  # allow packets that
+              src_port: POSTGRES_SERVER   # are emitted from the POSTGRES_SERVER port
+              dst_port: POSTGRES_SERVER   # are going towards an POSTGRES_SERVER port
+            22: # position 22 on ACL list
+              action: PERMIT  # allow packets that
+              src_port: ARP   # are emitted from the ARP port
+              dst_port: ARP   # are going towards an ARP port
+            23: # position 23 on ACL list
+              action: PERMIT  # allow packets that
+              protocol: ICMP  # are ICMP
 
 ``internal_outbound_acl``
 """""""""""""""""""""""""
@@ -155,21 +152,21 @@ example:
 .. code-block:: yaml
 
     nodes:
-        - ref: firewall
-        ...
+      - hostname: firewall
+      ...
         acl:
-            internal_outbound_acl:
-                21: # position 21 on ACL list
-                    action: PERMIT  # allow packets that
-                    src_port: POSTGRES_SERVER   # are emitted from the POSTGRES_SERVER port
-                    dst_port: POSTGRES_SERVER   # are going towards an POSTGRES_SERVER port
-                22: # position 22 on ACL list
-                    action: PERMIT  # allow packets that
-                    src_port: ARP   # are emitted from the ARP port
-                    dst_port: ARP   # are going towards an ARP port
-                23: # position 23 on ACL list
-                    action: PERMIT  # allow packets that
-                    protocol: ICMP  # are ICMP
+          internal_outbound_acl:
+            21: # position 21 on ACL list
+              action: PERMIT  # allow packets that
+              src_port: POSTGRES_SERVER   # are emitted from the POSTGRES_SERVER port
+              dst_port: POSTGRES_SERVER   # are going towards an POSTGRES_SERVER port
+            22: # position 22 on ACL list
+              action: PERMIT  # allow packets that
+              src_port: ARP   # are emitted from the ARP port
+              dst_port: ARP   # are going towards an ARP port
+            23: # position 23 on ACL list
+              action: PERMIT  # allow packets that
+              protocol: ICMP  # are ICMP
 
 
 ``dmz_inbound_acl``
@@ -216,29 +213,29 @@ example:
 .. code-block:: yaml
 
     nodes:
-        - ref: firewall
-        ...
-        acl:
-            dmz_outbound_acl:
-                19: # position 19 on ACL list
-                    action: PERMIT  # allow packets that
-                    src_port: POSTGRES_SERVER   # are emitted from the POSTGRES_SERVER port
-                    dst_port: POSTGRES_SERVER   # are going towards an POSTGRES_SERVER port
-                20: # position 20 on ACL list
-                    action: PERMIT  # allow packets that
-                    src_port: HTTP   # are emitted from the HTTP port
-                    dst_port: HTTP   # are going towards an HTTP port
-                21: # position 21 on ACL list
-                    action: PERMIT  # allow packets that
-                    src_port: HTTPS   # are emitted from the HTTPS port
-                    dst_port: HTTPS   # are going towards an HTTPS port
-                22: # position 22 on ACL list
-                    action: PERMIT  # allow packets that
-                    src_port: ARP   # are emitted from the ARP port
-                    dst_port: ARP   # are going towards an ARP port
-                23: # position 23 on ACL list
-                    action: PERMIT  # allow packets that
-                    protocol: ICMP  # are ICMP
+      - hostname: firewall
+      ...
+      acl:
+        dmz_outbound_acl:
+          19: # position 19 on ACL list
+            action: PERMIT  # allow packets that
+            src_port: POSTGRES_SERVER   # are emitted from the POSTGRES_SERVER port
+            dst_port: POSTGRES_SERVER   # are going towards an POSTGRES_SERVER port
+          20: # position 20 on ACL list
+            action: PERMIT  # allow packets that
+            src_port: HTTP   # are emitted from the HTTP port
+            dst_port: HTTP   # are going towards an HTTP port
+          21: # position 21 on ACL list
+            action: PERMIT  # allow packets that
+            src_port: HTTPS   # are emitted from the HTTPS port
+            dst_port: HTTPS   # are going towards an HTTPS port
+          22: # position 22 on ACL list
+            action: PERMIT  # allow packets that
+            src_port: ARP   # are emitted from the ARP port
+            dst_port: ARP   # are going towards an ARP port
+          23: # position 23 on ACL list
+            action: PERMIT  # allow packets that
+            protocol: ICMP  # are ICMP
 
 
 
@@ -254,21 +251,21 @@ example:
 .. code-block:: yaml
 
     nodes:
-        - ref: firewall
-        ...
-        acl:
-            external_inbound_acl:
-                21: # position 19 on ACL list
-                    action: DENY  # deny packets that
-                    src_port: POSTGRES_SERVER   # are emitted from the POSTGRES_SERVER port
-                    dst_port: POSTGRES_SERVER   # are going towards an POSTGRES_SERVER port
-                22: # position 22 on ACL list
-                    action: PERMIT  # allow packets that
-                    src_port: ARP   # are emitted from the ARP port
-                    dst_port: ARP   # are going towards an ARP port
-                23: # position 23 on ACL list
-                    action: PERMIT  # allow packets that
-                    protocol: ICMP  # are ICMP
+      - hostname: firewall
+      ...
+      acl:
+        external_inbound_acl:
+          21: # position 19 on ACL list
+            action: DENY  # deny packets that
+            src_port: POSTGRES_SERVER   # are emitted from the POSTGRES_SERVER port
+            dst_port: POSTGRES_SERVER   # are going towards an POSTGRES_SERVER port
+          22: # position 22 on ACL list
+            action: PERMIT  # allow packets that
+            src_port: ARP   # are emitted from the ARP port
+            dst_port: ARP   # are going towards an ARP port
+          23: # position 23 on ACL list
+            action: PERMIT  # allow packets that
+            protocol: ICMP  # are ICMP
 
 ``external_outbound_acl``
 """""""""""""""""""""""""
@@ -282,17 +279,17 @@ example:
 .. code-block:: yaml
 
     nodes:
-        - ref: firewall
-        ...
+      - hotsname: firewall
+      ...
         acl:
-            external_outbound_acl:
-                22: # position 22 on ACL list
-                    action: PERMIT  # allow packets that
-                    src_port: ARP   # are emitted from the ARP port
-                    dst_port: ARP   # are going towards an ARP port
-                23: # position 23 on ACL list
-                    action: PERMIT  # allow packets that
-                    protocol: ICMP  # are ICMP
+          external_outbound_acl:
+            22: # position 22 on ACL list
+              action: PERMIT  # allow packets that
+              src_port: ARP   # are emitted from the ARP port
+              dst_port: ARP   # are going towards an ARP port
+            23: # position 23 on ACL list
+              action: PERMIT  # allow packets that
+              protocol: ICMP  # are ICMP
 
 .. include:: common/common_network_node_attributes.rst
 

docs/source/configuration/simulation/nodes/network_examples.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 .. _network_examples:
 
@@ -389,7 +389,7 @@ connections, but the ACL that allows the nodes in the LAN to communicate with th
     pc_1 = network.get_node_by_hostname("pc_1")
     pc_1.ping(pc_1.default_gateway)
 
-pc_1.sys_log.show()
+    pc_1.sys_log.show()
 
 If SysLog capture is toggled on and the simulation log level is set to INFO, the `pc_1` the result of the ping should be
 captured in the `pc_1` SysLog:
@@ -443,7 +443,8 @@ SomeTech. This extended network includes detailed sub-networks with specialised
 complex routing capabilities, and robust security protocols implemented through Access Control Lists (ACLs). Designed
 to mimic the intricacies of actual network environments, this network provides a detailed look at how various network
 components interact and function together to support both internal corporate activities and external communications.
-
+NB: the network described here is not the same as the UC7 network used by notebooks such as ``UC7-Training,ipynb`` or
+the network in ``Privilege-Escalation-and-Data-Loss-Example.ipynb``.
 
 .. image:: images/primaite_example_multi_lan_with_internet_network_dark.png
     :align: center
@@ -617,10 +618,10 @@ Each node is configured to ensure it meets the specific security and operational
             default_gateway: 192.168.1.1
             dns_server: 8.8.8.2
             applications:
-              - type: DatabaseClient
+              - type: database-client
                 options:
                   db_server_ip: 10.10.1.11
-              - type: WebBrowser
+              - type: web-browser
                 options:
                   target_url: http://sometech.ai
 
@@ -631,10 +632,10 @@ Each node is configured to ensure it meets the specific security and operational
             default_gateway: 192.168.1.1
             dns_server: 8.8.8.2
             applications:
-              - type: DatabaseClient
+              - type: database-client
                 options:
                   db_server_ip: 10.10.1.11
-              - type: WebBrowser
+              - type: web-browser
                 options:
                   target_url: http://sometech.ai
 
@@ -700,7 +701,7 @@ Each node is configured to ensure it meets the specific security and operational
             default_gateway: 8.8.8.1
             services:
               - ref: dns_server
-                type: DNSServer
+                type: dns-server
                 options:
                   domain_mapping:
                     sometech.ai: 94.10.180.6
@@ -794,9 +795,9 @@ Each node is configured to ensure it meets the specific security and operational
             dns_server: 8.8.8.2
             services:
               - ref: web_server
-                type: WebServer
+                type: web-server
             applications:
-              - type: DatabaseClient
+              - type: database-client
                 options:
                   db_server_ip: 10.10.1.11
 
@@ -903,10 +904,10 @@ Each node is configured to ensure it meets the specific security and operational
             default_gateway: 10.10.1.1
             dns_server: 8.8.8.2
             services:
-              - type: DatabaseService
+              - type: database-service
                 options:
                   backup_server_ip: 10.10.1.12 # The some_tech_storage_srv server
-              - type: FTPClient
+              - type: ftp-client
 
           - hostname: some_tech_storage_srv
             type: server
@@ -915,7 +916,7 @@ Each node is configured to ensure it meets the specific security and operational
             default_gateway: 10.10.1.1
             dns_server: 8.8.8.2
             services:
-              - type: FTPServer
+              - type: ftp-server
 
           - hostname: some_tech_hr_1
             type: computer
@@ -924,10 +925,10 @@ Each node is configured to ensure it meets the specific security and operational
             default_gateway: 10.10.3.1
             dns_server: 8.8.8.2
             applications:
-              - type: DatabaseClient
+              - type: database-client
                 options:
                   db_server_ip: 10.10.1.11
-              - type: WebBrowser
+              - type: web-browser
                 options:
                   target_url: http://sometech.ai
 
@@ -938,10 +939,10 @@ Each node is configured to ensure it meets the specific security and operational
             default_gateway: 10.10.2.1
             dns_server: 8.8.8.2
             applications:
-              - type: DatabaseClient
+              - type: database-client
                 options:
                   db_server_ip: 10.10.1.11
-              - type: WebBrowser
+              - type: web-browser
                 options:
                   target_url: http://sometech.ai
 
@@ -952,10 +953,10 @@ Each node is configured to ensure it meets the specific security and operational
             default_gateway: 10.10.2.1
             dns_server: 8.8.8.2
             applications:
-              - type: DatabaseClient
+              - type: database-client
                 options:
                   db_server_ip: 10.10.1.11
-              - type: WebBrowser
+              - type: web-browser
                 options:
                   target_url: http://sometech.ai
 
@@ -1177,8 +1178,8 @@ ACLs permitting or denying traffic as per our configured ACL rules.
     some_tech_storage_srv = network.get_node_by_hostname("some_tech_storage_srv")
     some_tech_storage_srv.file_system.create_file(file_name="test.png")
 
-    pc_1_ftp_client: FTPClient = network.get_node_by_hostname("pc_1").software_manager.software["FTPClient"]
-    pc_2_ftp_client: FTPClient = network.get_node_by_hostname("pc_2").software_manager.software["FTPClient"]
+    pc_1_ftp_client: FTPClient = network.get_node_by_hostname("pc_1").software_manager.software["ftp-client"]
+    pc_2_ftp_client: FTPClient = network.get_node_by_hostname("pc_2").software_manager.software["ftp-client"]
 
     assert not pc_1_ftp_client.request_file(
         dest_ip_address=some_tech_storage_srv.network_interface[1].ip_address,
@@ -1224,7 +1225,7 @@ ACLs permitting or denying traffic as per our configured ACL rules.
 
     web_server: Server = network.get_node_by_hostname("some_tech_web_srv")
 
-    web_ftp_client: FTPClient = web_server.software_manager.software["FTPClient"]
+    web_ftp_client: FTPClient = web_server.software_manager.software["ftp-client"]
 
     assert not web_ftp_client.request_file(
         dest_ip_address=some_tech_storage_srv.network_interface[1].ip_address,
@@ -1269,7 +1270,7 @@ ACLs permitting or denying traffic as per our configured ACL rules.
     some_tech_storage_srv.file_system.create_file(file_name="test.png")
 
     some_tech_snr_dev_pc: Computer = network.get_node_by_hostname("some_tech_snr_dev_pc")
-    snr_dev_ftp_client: FTPClient = some_tech_snr_dev_pc.software_manager.software["FTPClient"]
+    snr_dev_ftp_client: FTPClient = some_tech_snr_dev_pc.software_manager.software["ftp-client"]
 
     assert snr_dev_ftp_client.request_file(
         dest_ip_address=some_tech_storage_srv.network_interface[1].ip_address,
@@ -1294,7 +1295,7 @@ ACLs permitting or denying traffic as per our configured ACL rules.
     some_tech_storage_srv.file_system.create_file(file_name="test.png")
 
     some_tech_jnr_dev_pc: Computer = network.get_node_by_hostname("some_tech_jnr_dev_pc")
-    jnr_dev_ftp_client: FTPClient = some_tech_jnr_dev_pc.software_manager.software["FTPClient"]
+    jnr_dev_ftp_client: FTPClient = some_tech_jnr_dev_pc.software_manager.software["ftp-client"]
 
     assert not jnr_dev_ftp_client.request_file(
         dest_ip_address=some_tech_storage_srv.network_interface[1].ip_address,
@@ -1337,7 +1338,7 @@ ACLs permitting or denying traffic as per our configured ACL rules.
     some_tech_storage_srv.file_system.create_file(file_name="test.png")
 
     some_tech_hr_pc: Computer = network.get_node_by_hostname("some_tech_hr_1")
-    hr_ftp_client: FTPClient = some_tech_hr_pc.software_manager.software["FTPClient"]
+    hr_ftp_client: FTPClient = some_tech_hr_pc.software_manager.software["ftp-client"]
 
     assert not hr_ftp_client.request_file(
         dest_ip_address=some_tech_storage_srv.network_interface[1].ip_address,

docs/source/configuration/simulation/nodes/router.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 .. _router_configuration:
 
@@ -17,16 +17,15 @@ example router
 .. code-block:: yaml
 
     simulation:
-        network:
-            nodes:
-                - ref: router_1
-                hostname: router_1
-                type: router
-                num_ports: 5
-                ports:
-                    ...
-                acl:
-                    ...
+      network:
+        nodes:
+          - hostname: router_1
+            type: router
+            num_ports: 5
+            ports:
+                ...
+            acl:
+                ...
 
 .. include:: common/common_node_attributes.rst
 
@@ -49,15 +48,15 @@ Example of setting ports for a router with 2 ports:
 .. code-block:: yaml
 
     nodes:
-        - ref: router_1
+        - hostname: router_1
         ...
         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
+          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
 
 ``ip_address``
 """"""""""""""
@@ -74,23 +73,19 @@ The subnet mask setting for the port.
 ``acl``
 -------
 
-Sets up the ACL rules for the router.
+Sets up the ACL rules for the router to apply to layer-3 traffic. These are not applied to layer-2 traffic such as ARP.
 
 e.g.
 
 .. code-block:: yaml
 
     nodes:
-        - ref: router_1
+        - hostname: router_1
         ...
         acl:
-            1:
-                action: PERMIT
-                src_port: ARP
-                dst_port: ARP
-            2:
-                action: PERMIT
-                protocol: ICMP
+          1:
+            action: PERMIT
+            protocol: ICMP
 
 See :py:mod:`primaite.simulator.network.hardware.nodes.network.router.AccessControlList`
 

docs/source/configuration/simulation/nodes/server.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 .. _server_configuration:
 
@@ -19,16 +19,15 @@ example server
     simulation:
         network:
             nodes:
-                - ref: server_1
-                hostname: server_1
-                type: server
-                ip_address: 192.168.10.10
-                subnet_mask: 255.255.255.0
-                default_gateway: 192.168.10.1
-                dns_server: 192.168.1.10
-                applications:
+                - hostname: server_1
+                  type: server
+                  ip_address: 192.168.10.10
+                  subnet_mask: 255.255.255.0
+                  default_gateway: 192.168.10.1
+                  dns_server: 192.168.1.10
+                  applications:
                     ...
-                services:
+                  services:
                     ...
 
 .. include:: common/common_node_attributes.rst

docs/source/configuration/simulation/nodes/switch.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 .. _switch_configuration:
 
@@ -17,12 +17,11 @@ example switch
 .. code-block:: yaml
 
     simulation:
-        network:
-            nodes:
-                - ref: switch_1
-                hostname: switch_1
-                type: switch
-                num_ports: 8
+      network:
+        nodes:
+          hostname: switch_1
+          type: switch
+          num_ports: 8
 
 .. include:: common/common_node_attributes.rst
 

docs/source/configuration/simulation/software/applications.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 ``applications``
 ----------------
@@ -14,12 +14,10 @@ Applications takes a list of applications as shown in the example below.
 
 .. code-block:: yaml
 
-    - ref: client_1
-    hostname: client_1
-    type: computer
+    - hostname: client_1
+      type: computer
     ...
     applications:
-        - ref: example_application
         type: example_application_type
         options:
             # this section is different for each application

docs/source/configuration/simulation/software/services.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 ``services``
 ------------
@@ -14,12 +14,10 @@ Services takes a list of services as shown in the example below.
 
 .. code-block:: yaml
 
-    - ref: client_1
     hostname: client_1
     type: computer
     ...
     applications:
-        - ref: example_service
         type: example_service_type
         options:
             # this section is different for each service

docs/source/customising_scenarios.rst

@@ -1,8 +0,0 @@
-.. only:: comment
-
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
-
-Customising Agents
-******************
-
-For an example of how to customise red agent behaviour in the Data Manipulation scenario, please refer to the notebook ``Data-Manipulation-Customising-Red-Agent.ipynb``.

docs/source/dependencies.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 .. role::  raw-html(raw)
     :format: html

docs/source/developer_tools.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 .. _Developer Tools:
 

docs/source/environment.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 RL Environments
 ***************

docs/source/example_notebooks.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 .. _example jupyter notebooks:
 

docs/source/game_layer.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 PrimAITE Game layer
 *******************
@@ -42,7 +42,7 @@ 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:modules:`primaite.game.agent.rewards`.
+Currently implemented are reward components tailored to the data manipulation scenario. View the full API and description of how they work here: :py:mod:`primaite.game.agent.rewards`.
 
 Reward Sharing
 --------------
@@ -57,13 +57,13 @@ An agent's reward can be based on rewards of other agents. This is particularly
         reward_components:
 
           # 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
+          - type: webpage-unavailable-penalty
             weight: 0.25
             options:
               node_hostname: client_2
 
           # 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
+          - type: green-admin-database-unreachable-penalty
             weight: 0.05
             options:
               node_hostname: client_2
@@ -74,7 +74,7 @@ An agent's reward can be based on rewards of other agents. This is particularly
         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
+          - type: database-file-integrity
             weight: 0.40
             options:
               node_hostname: database_server
@@ -82,7 +82,7 @@ An agent's reward can be based on rewards of other agents. This is particularly
               file_name: database.db
 
           # The green's reward is added onto the blue's reward.
-          - type: SHARED_REWARD
+          - type: shared-reward
             weight: 1.0
             options:
               agent_name: client_2_green_user

docs/source/getting_started.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 .. _getting-started:
 
@@ -113,7 +113,7 @@ For example:
 
 .. code-block:: bash
 
-    git clone https://github.com/{todo:fill in URL}/PrimAITE
+    git clone https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE
     cd primaite
 
 2. Create and activate your Python virtual environment (venv)

docs/source/glossary.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 Glossary
 =============
@@ -9,10 +9,10 @@ Glossary
     :sorted:
 
     Network
-        The network in primaite is a logical representation of a computer network containing :term:`Nodes<Node>` and :term:`Links<Link>`.
+        The network in primaite is a logical representation of a computer network containing :term:`Nodes<Node>` and :term:`Links<Link>`. See :ref:`network`.
 
     Node
-        A Node represents a network endpoint. For example a computer, server, switch, or an actuator.
+        A Node represents a network endpoint. For example a computer, server, switch, or an actuator. See :ref:`node_description`
 
     Link
         A Link represents the connection between two Nodes. For example, a physical wire between a computer and a switch or a wireless connection.
@@ -21,7 +21,7 @@ Glossary
         Protocols are used by links to separate different types of network traffic. Common examples would be HTTP, TCP, and UDP.
 
     Service
-        A service represents a piece of software that is installed on a node, such as a web server or a database.
+        A service represents a piece of software that is installed on a node, such as a web server or a database. See :ref:`software`
 
     Access Control List
         PrimAITE blocks or allows certain traffic on the network by simulating firewall rules, which are defined in the Access Control List.
@@ -42,7 +42,7 @@ Glossary
         PoLs allow agents to change the current hardware, OS, file system, or service statuses of nodes during the course of an episode. For example, a green agent may restart a server node to represent scheduled maintainance. A red agent's Pattern-of-Life can be used to attack nodes by changing their states to CORRUPTED or COMPROMISED.
 
     Reward
-        The reward is a single number used by the blue agent to understand whether it's performing well or poorly. RL agents change their behaviour in an attempt to increase the expected reward each episode. The reward is generated based on the current states of the environment and is impacted positively by things like green PoL running successfully and negatively by things like nodes being compromised.
+        The reward is a single number used by the blue agent to understand whether it's performing well or poorly. RL agents change their behaviour in an attempt to increase the expected reward each episode. The reward is generated based on the current states of the environment and is impacted positively by things like green PoL running successfully and negatively by things like nodes being compromised. See :ref:`Rewards`
 
     Observation
         An observation is a representation of the current state of the environment that is given to the learning agent so it can decide on which action to perform. If the environment is 'fully observable', the observation contains information about every possible aspect of the environment. More commonly, the environment is 'partially observable' which means the learning agent has to make decisions without knowing every detail of the current environment state.
@@ -50,6 +50,9 @@ Glossary
     Action
         The learning agent decides on an action to take on every step in the simulation. The action has the chance to positively or negatively impact the environment state. Over time, the agent aims to learn which actions to take when to maximise the expected reward.
 
+    Action mask
+        An input to RL algorithms that contains information about which of the actions in the action space are currently valid. See :ref:`action_masking`
+
     Training
         During training, an RL agent is placed in the simulated network and it learns which actions to take in which scenarios to obtain maximum reward.
 
@@ -69,4 +72,13 @@ Glossary
         PrimAITE uses the Gymnasium reinforcement learning framework API to create a training environment and interface with RL agents. Gymnasium defines a common way of creating observations, actions, and rewards.
 
     User app home
-        PrimAITE supports upgrading software version while retaining user data. The user data directory is where configs, notebooks, and results are stored, this location is `~/primaite<version>/` on linux/darwin and `C:\\Users\\<username>\\primaite<version>` on Windows.
+        PrimAITE supports upgrading software version while retaining user data. The user data directory is where configs, notebooks, and results are stored, this location is ``~/primaite/<version>/`` on linux/darwin and ``C:\\Users\\<username>\\primaite\\<version>`` on Windows.
+
+    Episode schedule
+        The strategy for selecting different variants around the same scenario when advancing from one episode to another in the environment.
+
+    Discriminator
+        A unique string given to extensible components in PrimAITE that allow them to be mapped from a YAML config definition to a simulation class.
+
+    Plugin
+        A python package that extends base PrimAITE classes.

docs/source/how_to.rst

@@ -0,0 +1,10 @@
+.. only:: comment
+
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+
+How-To Guides
+=============
+
+These how-to guides aim to provide a starting point for development within PrimAITE, creating your own custom components and environments for use when training agents. More detailed information for each section can be found within the documentation.
+
+There are also some additional notebooks which provide a walkthrough of established content. It's encouraged to reference these when developing for PrimAITE.

docs/source/how_to_guides/custom_actions.rst

@@ -0,0 +1,58 @@
+.. only:: comment
+
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+
+.. _custom_actions:
+
+Creating Custom Actions in PrimAITE
+***********************************
+
+PrimAITE contains a selection of possible actions that can be exercised within a training environment. Actions provided as a part of PrimAITE can be seen within `src/primaite/game/agent/actions`. `Note`: Agents are only able to perform the actions listed within it's action_map, defined within it's configuration YAML. See :ref:`custom_environment` for more information.
+
+Developing Custom Actions
+=========================
+
+Actions within PrimAITE follow a default format, as seen below and in ``actions.py``. It's important that they have an identifier when declared, as this is used when creating the training environment.
+
+An example of a custom action is seen below, with key information about what is required for new actions in :ref:`extensible_actions`.
+
+.. code:: Python
+
+    class ExampleActionClass(AbstractAction, discriminator="ExampleActions"):
+        """Example Action Class"""
+
+        config: ExampleAction.ConfigSchema(AbstractAction.ConfigSchema)
+
+        class ConfigSchema(AbstractAction.ConfigSchema)
+
+            node_name: str
+
+        @classmethod
+        def form_request(cls, config: ConfigSchema) -> RequestFormat:
+            return [config.node_name, "example_action"]
+
+Integration with PrimAITE ActionManager
+=======================================
+
+Any custom actions should then be added to the `ActionManager` class, and the `act_class_identifiers` dictionary. This will map the action class to the corresponding action type string that would be passed through the PrimAITE `request_system`.
+
+
+Interaction with the PrimAITE Request Manager
+=============================================
+
+Where an action would cause a request to be sent through the PrimAITE RequestManager, a `form_request` method is expected to be defined within the Action Class. This should format  the action into a format that can be ingested by the `RequestManager`. Examples of this include the `NodeFolderCreateAction`, which sends a formed request to create a folder on a given node (seen below):
+
+.. code:: Python
+
+    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:
+            return ["do_nothing"]
+        return ["network", "node", node_name, "file_system", "create", "folder", folder_name]
+
+Action Masking
+==============
+
+Agents which use the `ProxyAgent` class within PrimAITE are able to use Action Masking. This allows the agent to know if the actions are valid/invalid based on the current environment.
+Information on how to ensure this can be applied to your custom action can be found in :ref:`action_masking`

docs/source/how_to_guides/custom_environments.rst

@@ -0,0 +1,45 @@
+.. only:: comment
+
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+
+.. _custom_environments:
+
+Creating Custom Environments for PrimAITE
+*****************************************
+
+PrimAITE generates it's training configuration/Environments through ingestion of YAML files. A detailed walkthrough of how to create your own environment can be found within the ``Creating-Custom-Environments`` jupyter notebook.
+
+You configuration file should follow the hierarchy seen below:
+
+.. code:: yaml
+
+    metadata:
+        version: 4.0
+
+    required_plugins:
+        - name: Example_Plugin
+          version: 1.0
+
+    io_settings:
+    ...
+    game:
+    ...
+    agents:
+    ...
+    simulation:
+    ...
+
+MetaData
+========
+
+It's important to include the metadata tag within your YAML file, as this is used to ensure PrimAITE can interpret the configuration correctly. This should also include any plugins that are required for the defined environment, along with their respective version.
+
+Required Plugins
+================
+
+Should your custom environment need any additional PrimAITE plugins, each must be specified under the `required_plugins` tab, as seen in the above example.
+
+Configuration Items
+===================
+
+For detailed information about the remaining configuration items found within the configuration file, see :ref:`Configurable_Items`.

docs/source/how_to_guides/custom_rewards.rst

@@ -0,0 +1,48 @@
+.. only:: comment
+
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+
+.. _custom_rewards:
+
+Creating Custom Rewards in PrimAITE
+***********************************
+
+Rewards within PrimAITE are contained within ``rewards.py``, which details the rewards available for all agents within training sessions, how they are calculated and any other specific information where necessary.
+
+Rewards within PrimAITE have been updated to facilitate extensibility and the creation of plugins with the release of PrimAITE version 4.0. Additional information about this is covered within :ref:`extensible_rewards`.
+
+Custom Rewards within PrimAITE should inherit from the ``AbstractReward`` class, found in ``rewards.py``. It's important to include an identifier for any class created within PrimAITE.
+
+.. code:: Python
+
+    class ExampleAward(AbstractReward, identifier="ExampleAward"):
+        """Example Reward Class """
+
+        def calculate(self, state: Dict, last_action_response: "AgentHistoryItem") -> float:
+            """Calculate the reward for the current state."""
+            return 1.0
+
+        @classmethod
+        def from_config(cls, config: dict) -> "AbstractReward":
+            """Create a reward function component from a config dictionary."""
+            return cls()
+
+
+Custom rewards that have been created should be added to the ``rew_class_identifiers`` dictionary within the ``RewardFunction`` class in ``rewards.py``.
+
+Including Custom Rewards within PrimAITE configuration
+======================================================
+
+Custom rewards can then be included within an agents configuration by it's inclusion within the training session configuration YAML.
+
+.. code:: yaml
+
+    agents:
+      - ref: agent_name
+        reward_function:
+          reward_components:
+            - type: DUMMY
+              weight: 1.0
+
+
+More detailed information about rewards within PrimAITE can be found within :ref:`Rewards`

docs/source/how_to_guides/custom_software.rst

@@ -0,0 +1,80 @@
+.. only:: comment
+
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+
+.. _custom_software:
+
+Creating Custom Software for PrimAITE
+*************************************
+
+This page aims to provide a how-to guide on how to create your own custom software for use within PrimAITE.
+
+PrimAITE has a base software class which should be inherited from when building custom software. Examples of this can be seen in the ``IOSoftware`` and ``Process`` classes.
+It's important that any new software created within PrimAITE has the ``identifier`` attribute defined, for use when generating the environment.
+
+Some default attributes may need to be adjusted to align with the intended application of the custom software.
+
+
+.. code:: Python
+
+    from src.primaite.simulator.system.software import Software
+
+    class CustomSoftware(Software, identifier="CustomSoftware"):
+        """
+        An example of Custom Software within PrimAITE.
+        """
+
+        operating_state: OperatingState
+        "The current operating state of the Custom software"
+
+        def describe_state(self) -> Dict:
+            """
+            Produce a dictionary describing the current state of this object.
+
+            :return: Current state of this object and child objects.
+            :rtype: Dict
+            """
+            state = super().describe_state()
+            state.update({"operating_state": self.operating_state.value})
+
+Default Install
+###############
+
+Software can be set to auto-install onto a Node by adding it to the ``SYSTEM_SOFTWARE`` dictionary for the node. An example can be seen in the ``HostNode`` class, which pre-installs some key software that is expected on Nodes, such as the ``NTPClient`` and ``UserManager``.
+
+Requirements
+############
+
+Any custom software will need to provide an implementation of the ``describe_state`` method, and conform to the general Pydantic requirements.
+It's a good idea, if possible, to also create a ``.show()`` method, as this can be used for visualising the software's status when developing within PrimAITE.
+
+Interaction with the PrimAITE Request System
+############################################
+
+If the software is intended to be used by an agent via a :ref:`custom_action`, then it will likely need an implementation of the ``RequestManager``.
+Detailed information about the PrimAITE request system can be seen in :ref:`request_system`. An example implementation, derived from the `Application` class is seen below:
+
+.. code:: Python
+
+    def _init_request_manager(self) -> RequestManager:
+        """
+        Initialise the request manager.
+
+        More information in user guide and docstring for SimComponent._init_request_manager.
+        """
+        _is_application_running = Application._StateValidator(application=self, state=ApplicationOperatingState.RUNNING)
+
+        rm = super()._init_request_manager()
+        rm.add_request(
+            "scan",
+            RequestType(
+                func=lambda request, context: RequestResponse.from_bool(self.scan()), validator=_is_application_running
+            ),
+        )
+        return rm
+
+
+Further information
+###################
+
+For more detailed information about the implementation of software within PrimAITE, see :ref:`software`.

docs/source/how_to_guides/extensible_actions.rst

@@ -0,0 +1,68 @@
+.. only:: comment
+
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+
+.. _extensible_actions:
+
+Extensible Actions
+******************
+
+Changes to Actions class Structure.
+===================================
+
+Actions within PrimAITE have been updated to inherit from a base class, AbstractAction, standardising their format and allowing for easier creation of custom actions. Actions now use a ``ConfigSchema`` to define the possible configuration variables, and use pydantic to enforce correct parameters are passed through.
+
+
+Developing Custom Actions.
+==========================
+
+Custom actions within PrimAITE must be a sub-class of `AbstractAction`, and contain 3 key items:
+
+#. ConfigSchema class
+
+#. Unique discriminator
+
+#. `form_request` method.
+
+
+ConfigSchema
+############
+
+The ConfigSchema sub-class of the action must contain all `configurable` variables within the action, that would be specified within the environments configuration YAML file.
+
+
+Unique discriminator
+####################
+
+When declaring a custom class, it must have a unique discriminator string, that allows PrimAITE to generate the correct action when needed.
+
+.. code:: Python
+
+    class CreateDirectoryAction(AbstractAction, discriminator="node-folder-create")
+
+        config: CreateDirectoryAction.ConfigSchema
+
+        class ConfigSchema(AbstractAction.ConfigSchema):
+
+            verb: ClassVar[str] = "create"
+            node_name: str
+            directory_name: str
+
+        @classmethod
+        def form_request(cls, config: ConfigSchema) -> RequestFormat:
+            return ["network",
+                    "node",
+                    config.node_name,
+                    "file_system",
+                    config.verb,
+                    "folder",
+                    config.directory_name,
+                ]
+
+The above action would fail pydantic validation as the discriminator "node-folder-create" is already used by the `NodeFolderCreateAction`, and would create a duplicate listing within `AbstractAction._registry`.
+
+
+form_request method
+###################
+
+PrimAITE actions need to have a `form_request` method, which can be passed to the `RequestManager` for processing. This allows the custom action to be actioned within the simulation environment. Further information and an example of this can be seen in :ref:`custom_actions`.

docs/source/how_to_guides/extensible_agents.rst

@@ -0,0 +1,75 @@
+.. only:: comment
+
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+
+.. _extensible_agents:
+
+Extensible Agents
+*****************
+
+Agents defined within PrimAITE have been updated to allow for easier creation of new bespoke agents for use in custom environments.
+
+
+Developing Agents for PrimAITE
+==============================
+
+All agent types within PrimAITE must be subclassed from ``AbstractAgent`` in order to be used from configuration YAML files. This then allows you to implement any custom agent logic for the new agent in your training scenario. Examples of implementing custom agent logic can be seen in pre-existing agents, such as the ``DataManipulationBot`` and ``RandomAgent``.
+
+The core features that should be implemented in any new agent are detailed below:
+
+**ConfigSchema**:
+
+Configurable items within a new agent within PrimAITE should contain a ``ConfigSchema`` which holds all configurable variables of the agent. This should not include parameters related to its *state*, these would be listed seperately.
+Agent generation will fail pydantic checks if incorrect or invalid parameters are passed to the ConfigSchema of the chosen Agent.
+
+
+.. code-block:: python
+
+    class ExampleAgent(AbstractAgent, discriminator = "ExampleAgent"):
+        """An example agent for demonstration purposes."""
+
+        config: "ExampleAgent.ConfigSchema" = Field(default_factory= lambda: ExampleAgent.ConfigSchema())
+        """Agent configuration"""
+        num_executions: int = 0
+        """Number of action executions by agent"""
+
+        class ConfigSchema(AbstractAgent.ConfigSchema):
+            """ExampleAgent configuration schema"""
+
+            type: str = "ExampleAgent
+            """Name of agent"""
+            starting_host: int
+            """Host node that this agent should start from in the given environment."""
+
+
+.. code-block:: yaml
+
+    - ref: example_green_agent
+      team: GREEN
+      type: example-agent
+
+      agent_settings:
+        start_step: 25
+        frequency: 20
+        variance: 5
+        starting_host: "Server_1"
+
+      action_space:
+      action_map:
+        0:
+          action: do-nothing
+          options: {}
+
+
+**discriminators**:
+
+    All agent classes should have an ``discriminator`` attribute, a unique kebab-case string, for when they are added to the base ``AbstractAgent`` registry. This is then specified in your configuration YAML, and used by PrimAITE to generate the correct Agent.
+
+Changes to YAML file
+====================
+
+PrimAITE v4.0.0 introduces some breaking changes to how environment configuration yaml files are created. YAML files created for Primaite versions 3.3.0 should be compatible through a translation function, though it is encouraged that these are updated to reflect the updated format of 4.0.0+.
+
+Agents now follow a more standardised settings definition, so should be more consistent across YAML files and the available agent types with PrimAITE.
+
+All configurable items for agents sit under the ``agent_settings`` heading within your YAML files. There is no need for the inclusion of  a ``start_settings``. Please see the above YAML example for full changes to agents.

docs/source/how_to_guides/extensible_nodes.rst

@@ -0,0 +1,55 @@
+.. only:: comment
+
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+
+.. _extensible_nodes:
+
+
+Extensible Nodes
+****************
+
+Node classes within PrimAITE have been updated to allow for easier generation of custom nodes within simulations.
+
+
+Changes to Node Class structure.
+================================
+
+Node classes all inherit from the base Node Class, though new classes should inherit from either HostNode or NetworkNode, subject to the intended application of the Node.
+
+The use of an `__init__` method is not necessary, as configurable variables for the class should be specified within the `config` of the class, and passed at run time via your YAML configuration using the `from_config` method.
+
+An example of how additional Node classes is below, taken from `router.py` within PrimAITE.
+
+.. code-block:: Python
+
+    class Router(NetworkNode, identifier="router"):
+        """ Represents a network router within the simulation, managing routing and forwarding of IP packets across network interfaces."""
+
+        SYSTEM_SOFTWARE: ClassVar[Dict] = {
+            "user-session-manager": UserSessionManager,
+            "user-manager": UserManager,
+            "terminal": Terminal,
+        }
+
+        network_interfaces: Dict[str, RouterInterface] = {}
+        "The Router Interfaces on the node."
+        network_interface: Dict[int, RouterInterface] = {}
+        "The Router Interfaces on the node by port id."
+
+        sys_log: SysLog
+
+        config: "Router.ConfigSchema" = Field(default_factory=lambda: Router.ConfigSchema())
+
+        class ConfigSchema(NetworkNode.ConfigSchema):
+            """Configuration Schema for Router Objects."""
+
+            num_ports: int = 5
+
+            hostname: str = "Router"
+
+
+
+Changes to YAML file.
+=====================
+
+While effort has been made to ensure that nodes defined within configuration YAML files for use with PrimAITE 3.X remain compatible with PrimAITE v4+, it is encouraged to review for minor changes needed.

docs/source/how_to_guides/extensible_rewards.rst

@@ -0,0 +1,55 @@
+.. only:: comment
+
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+
+.. _extensible_rewards:
+
+Extensible Rewards
+******************
+Extensible Rewards differ from the previous reward mechanism used in PrimAITE v3.x as new reward
+types can be added without requiring a change to the RewardFunction class in rewards.py (PrimAITE
+core repository).
+
+Changes to reward class structure.
+==================================
+
+Reward classes are inherited from AbstractReward (a sub-class of Pydantic's BaseModel).
+Within the reward class there is a ConfigSchema class responsible for ensuring the config file data
+is in the correct format. This also means there is little (if no) requirement for and `__init__`
+method. The `.from_config` method is no longer required as it's inherited from `AbstractReward`.
+Each class requires an discriminator string which is used by the ConfigSchema class to verify that it
+hasn't previously been added to the registry.
+
+Inheriting from `BaseModel` removes the need for an `__init__` method but means that object
+attributes need to be passed by keyword.
+
+To add a new reward class follow the example below. Note that the type attribute in the
+`ConfigSchema` class should match the type used in the config file to define the reward.
+
+.. code-block:: Python
+
+    class DatabaseFileIntegrity(AbstractReward, discriminator="database-file-integrity"):
+        """Reward function component which rewards the agent for maintaining the integrity of a database file."""
+
+        config: "DatabaseFileIntegrity.ConfigSchema"
+        location_in_state: List[str] = [""]
+        reward: float = 0.0
+
+        class ConfigSchema(AbstractReward.ConfigSchema):
+            """ConfigSchema for DatabaseFileIntegrity."""
+
+            type: str = "database-file-integrity"
+            node_hostname: str
+            folder_name: str
+            file_name: str
+
+        def calculate(self, state: Dict, last_action_response: "AgentHistoryItem") -> float:
+            """Calculate the reward for the current state.
+            pass
+
+
+
+Changes to YAML file.
+=====================
+    There's no longer a need to provide a `dns_server` as an option in the simulation section
+    of the config file.

docs/source/how_to_guides/primaite_yaml_migration_guide.rst

@@ -0,0 +1,411 @@
+.. only:: comment
+
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+
+.. _migration_guide:
+
+
+PrimAITE 4.0.0 YAML Configuration Migration Guide
+*************************************************
+
+Users upgrading from previous PrimAITE versions will be required to update their pre-existing YAML configs.
+
+This migration guide details how to update any 3.0.0 yaml configs section by section to match the new 4.0.0 schema.
+
+Any users accustomed to PrimAITE 2.0.0 are encouraged to make a fresh start to fully adapt to the changes since 2.0.0 release.
+
+``io_settings``
+===============
+
+No major schema alterations are required for ``io_settings``.
+
+However, a few more options have been introduced:
+
+.. code-block:: yaml
+
+    io_settings:
+        save_agent_actions: false
+        save_step_metadata: false
+        save_pcap_logs: false
+        save_sys_logs: false
+        save_agent_logs: false
+        write_sys_log_to_terminal: false
+        sys_log_level: WARNING
+        agent_log_level: INFO
+
+More information can be found in the detailed in the configuration page: :ref:`io_settings`.
+
+``game``
+========
+
+No reformatting required for ``game`` section.
+
+If users have installed plugins that introduce new ports or protocols then the game can be configured with use them.
+
+This can be done by adding to the ``ports`` and ``protocols`` list as shown in the yaml snippet below:
+
+.. code-block:: yaml
+
+    game:
+    max_episode_length: 128
+    ports:
+    - HTTP
+    - POSTGRES_SERVER
+    - <EXAMPLE_PLUGIN_PORT>
+    protocols:
+    - ICMP
+    - TCP
+    - UDP
+    - <EXAMPLE_PLUGIN_PROTOCOL>
+    thresholds:
+        nmne:
+        high: 10
+        medium: 5
+        low: 0
+
+
+``agents``
+==========
+
+PrimAITE 4.0.0 changes action parameters to use meaningful names instead of indexes.
+
+To match the new schema, agent configs written for PrimAITE 3.X should make the following changes:
+
+``action_space``
+----------------
+
+- remove the ``options``,  and ``action_list`` sections.
+- update the ``action_map`` to use the new naming schema for actions, they use kebab case instead of camel case. A conversion table is provided below.
+- update the ``action_map`` to follow the new parameter schemas. ID-based parameters were replaced with name-based parameters. Use your old config's ``action_space.options`` field to find the appropriate mapping for action parameters in your particular scenario.
+    - ``node_id`` is now ``node_name``
+    - ``application_id`` is now ``application_name``
+    - ``service_id`` is now ``service_name``
+    - ``folder_id`` is now ``folder_name``
+    - ``nic_id`` is now ``nic_num`` (and is now 1-indexed instead of 0-indexed for consistency with the simulation)
+    - ``port_id`` is now ``port_num`` (and is now 1-indexed instead of 0-indexed for consistency with the simulation)
+    - ``source_ip_id`` is now ``src_ip``
+    - ``source_wildcard_id`` is now ``src_wildcard``
+    - ``source_port_id`` is now ``src_port``
+    - ``dest_port_id`` is now ``dst_port``
+    - ``dest_wildcard_id`` is now ``dst_wildcard``
+    - ``dest_port_id`` is now ``dst_port``
+    - ``protocol_id`` is now ``protocol``
+
+**Example on how to map old paramater IDs to new paramter names**
+
+.. code-block:: yaml
+
+    game:
+    max_episode_length: 128
+    ports:
+        - FTP
+        - HTTP
+    protocols:
+        - TCP
+        - UDP
+
+    # ...
+
+      options:
+        nodes:
+          - node_name: PC-1
+            applications:
+              - application_name: DatabaseClient
+            folders:
+              - folder_name: downloads
+                files:
+                  - file_name: chrome.exe
+              - folder_name: other_folder
+                files:
+                  - file_name: firefox.exe
+          - node_name: PC-2
+            applications:
+              - application_name: WebBrowser
+            folders:
+              - folder_name: folder_1
+                files:
+                  - file_name: file2.jpg
+              - folder_name: folder_2
+                files:
+                  - file_name: file3.jpg
+          - node_name: PC-3
+            services:
+              - service_name: FTPClient
+          - node_name: PC-4
+          - node_name: PC-5
+
+        max_folders_per_node: 1
+        max_files_per_folder: 1
+        max_services_per_node: 2
+        max_nics_per_node: 8
+        max_acl_rules: 10
+        ip_list:
+                         #  0 reserved for padding to align with observations
+                         #  1 reserved for ALL ips
+          - 192.168.1.11 #  2
+          - 200.10.1.10  #  3
+
+
+        wildcard_list:
+          - 0.0.0.1      # 0
+          - 0.0.0.255    # 1
+          - 0.0.255.255  # 2
+
+From the above old-style YAML ``action_space.options`` example, the following changes should be made to action map:
+
+- Actions with ``node_id: 0`` should use ``node_name: PC-1``
+- Actions with ``node_id: 1`` should use ``node_name: PC-2``
+- Actions with ``node_id: 2`` should use ``node_name: PC-3``
+- Actions with ``node_id: 3`` should use ``node_name: PC-4``
+- Actions with ``node_id: 4`` should use ``node_name: PC-5``
+- Actions with ``node_id: 0`` and ``application_id: 0`` should use ``application_name: DatabaseClient`` (The application list is specific to each node)
+- Actions with ``node_id: 1`` and ``application_id: 0`` should use ``application_name: WebBrowser`` (The application list is specific to each node)
+- Actions with ``node_id: 0`` and ``folder_id: 0`` should use ``folder_name: downloads`` (The folder list is specific to each node)
+- Actions with ``node_id: 0`` and ``folder_id: 1`` should use ``folder_name: other_folder`` (The folder list is specific to each node)
+- Actions with ``node_id: 1`` and ``folder_id: 0`` should use ``folder_name: folder_1`` (The folder list is specific to each node)
+- Actions with ``node_id: 1`` and ``folder_id: 1`` should use ``folder_name: folder_2`` (The folder list is specific to each node)
+- Actions with ``node_id: 0`` and ``folder_id: 0`` and ``file_id: 0`` should use ``file_name: chrome.exe`` (The file list is specific to each node and folder)
+- Actions with ``node_id: 0`` and ``folder_id: 1`` and ``file_id: 0`` should use ``file_name: firefox.exe`` (The file list is specific to each node and folder)
+- Actions with ``node_id: 1`` and ``folder_id: 0`` and ``file_id: 0`` should use ``file_name: file2.jpg`` (The file list is specific to each node and folder)
+- Actions with ``node_id: 1`` and ``folder_id: 1`` and ``file_id: 0`` should use ``file_name: file3.jpg`` (The file list is specific to each node and folder)
+- Actions with ``nic_id: <N>`` should use ``nic_num: <N+1>``
+- Actions with ``port_id: <N>`` should use ``port_num: <N+1>``
+- Actions with ``source_ip_id: 0`` should not be present in your original config as this has no effect
+- Actions with ``source_ip_id: 1`` should use ``src_ip: ALL``
+- Actions with ``source_ip_id: 2`` should use ``src_ip: 192.168.1.11``
+- Actions with ``source_ip_id: 3`` should use ``src_ip: 200.10.1.10``
+- Actions with ``dest_ip_id: 0`` should not be present in your original config as this has no effect
+- Actions with ``dest_ip_id: 1`` should use ``dst_ip: ALL``
+- Actions with ``dest_ip_id: 2`` should use ``dst_ip: 192.168.1.11``
+- Actions with ``dest_ip_id: 3`` should use ``dst_ip: 200.10.1.10``
+- Actions with ``source_wildcard_id: 0`` should use ``src_wildcard: 0.0.0.1``
+- Actions with ``source_wildcard_id: 0`` should use ``src_wildcard: 0.0.0.255``
+- Actions with ``source_wildcard_id: 0`` should use ``src_wildcard: 0.0.255.255``
+- Actions with ``dest_wildcard_id: 0`` should use ``dst_wildcard: 0.0.0.1``
+- Actions with ``dest_wildcard_id: 0`` should use ``dst_wildcard: 0.0.0.255``
+- Actions with ``dest_wildcard_id: 0`` should use ``dst_wildcard: 0.0.255.255``
+- Actions with ``source_port_id: 0`` should not be present in your original config as this has no effect
+- Actions with ``source_port_id: 1`` should use ``src_port: ALL``
+- Actions with ``source_port_id: 2`` should use ``src_port: FTP``
+- Actions with ``source_port_id: 3`` should use ``src_port: HTTP``
+- Actions with ``dest_port_id: 0`` should not be present in your original config as this has no effect
+- Actions with ``dest_port_id: 1`` should use ``dst_port: ALL``
+- Actions with ``dest_port_id: 2`` should use ``dst_port: FTP``
+- Actions with ``dest_port_id: 3`` should use ``dst_port: HTTP``
+- Actions with ``protocol_id: 0`` should not be present in your original config as this has no effect
+- Actions with ``protocol_id: 1`` should use ``protocol: ALL``
+- Actions with ``protocol_id: 2`` should use ``protocol: TCP``
+- Actions with ``protocol_id: 3`` should use ``protocol: UDP``
+
+``observation_space``
+---------------------
+
+    - the ``type`` parameter values now use lower kebab case. A conversion table is provided below.
+
+``reward_function``
+-------------------
+    - the ``type`` parameter values now use lower kebab case. A conversion table is provided below.
+
+
++-------------------------------------+-------------------------------------+
+| *3.0.0 action name*                 | *4.0.0 action name*                 |
++=====================================+=====================================+
+| ``DONOTHING``                       | ``do-nothing``                      |
++-------------------------------------+-------------------------------------+
+| ``NODE_SERVICE_SCAN``               | ``node-service-scan``               |
++-------------------------------------+-------------------------------------+
+| ``NODE_SERVICE_STOP``               | ``node-service-stop``               |
++-------------------------------------+-------------------------------------+
+| ``NODE_SERVICE_START``              | ``node-service-start``              |
++-------------------------------------+-------------------------------------+
+| ``NODE_SERVICE_PAUSE``              | ``node-service-pause``              |
++-------------------------------------+-------------------------------------+
+| ``NODE_SERVICE_RESUME``             | ``node-service-resume``             |
++-------------------------------------+-------------------------------------+
+| ``NODE_SERVICE_RESTART``            | ``node-service-restart``            |
++-------------------------------------+-------------------------------------+
+| ``NODE_SERVICE_DISABLE``            | ``node-service-disable``            |
++-------------------------------------+-------------------------------------+
+| ``NODE_SERVICE_ENABLE``             | ``node-service-enable``             |
++-------------------------------------+-------------------------------------+
+| ``NODE_SERVICE_FIX``                | ``node-service-fix``                |
++-------------------------------------+-------------------------------------+
+| ``NODE_APPLICATION_REMOVE``         | ``node-application-remove``         |
++-------------------------------------+-------------------------------------+
+| ``NODE_APPLICATION_CLOSE``          | ``node-application-close``          |
++-------------------------------------+-------------------------------------+
+| ``NODE_APPLICATION_SCAN``           | ``node-application-scan``           |
++-------------------------------------+-------------------------------------+
+| ``NODE_APPLICATION_FIX``            | ``node-application-fix``            |
++-------------------------------------+-------------------------------------+
+| ``NODE_FILE_SCAN``                  | ``node-file-scan``                  |
++-------------------------------------+-------------------------------------+
+| ``NODE_FILE_CHECKHASH``             | ``node-file-checkhash``             |
++-------------------------------------+-------------------------------------+
+| ``NODE_FILE_DELETE``                | ``node-file-delete``                |
++-------------------------------------+-------------------------------------+
+| ``NODE_FILE_REPAIR``                | ``node-file-repair``                |
++-------------------------------------+-------------------------------------+
+| ``NODE_FILE_RESTORE``               | ``node-file-restore``               |
++-------------------------------------+-------------------------------------+
+| ``NODE_FOLDER_SCAN``                | ``node-folder-scan``                |
++-------------------------------------+-------------------------------------+
+| ``NODE_FOLDER_CHECKHASH``           | ``node-folder-checkhash``           |
++-------------------------------------+-------------------------------------+
+| ``NODE_FOLDER_REPAIR``              | ``node-folder-repair``              |
++-------------------------------------+-------------------------------------+
+| ``NODE_FOLDER_RESTORE``             | ``node-folder-restore``             |
++-------------------------------------+-------------------------------------+
+| ``NODE_OS_SCAN``                    | ``node-os-scan``                    |
++-------------------------------------+-------------------------------------+
+| ``NODE_SHUTDOWN``                   | ``node-shutdown``                   |
++-------------------------------------+-------------------------------------+
+| ``NODE_STARTUP``                    | ``node-startup``                    |
++-------------------------------------+-------------------------------------+
+| ``NODE_RESET``                      | ``node-reset``                      |
++-------------------------------------+-------------------------------------+
+| ``HOST_NIC_ENABLE``                 | ``host-nic-enable``                 |
++-------------------------------------+-------------------------------------+
+| ``HOST_NIC_DISABLE``                | ``host-nic-disable``                |
++-------------------------------------+-------------------------------------+
+| ``NETWORK_PORT_ENABLE``             | ``network-port-enable``             |
++-------------------------------------+-------------------------------------+
+| ``NETWORK_PORT_DISABLE``            | ``network-port-disable``            |
++-------------------------------------+-------------------------------------+
+| ``ROUTER_ACL_ADDRULE``              | ``router-acl-addrule``              |
++-------------------------------------+-------------------------------------+
+| ``ROUTER_ACL_REMOVERULE``           | ``router-acl-removerule``           |
++-------------------------------------+-------------------------------------+
+| ``FIREWALL_ACL_ADDRULE``            | ``firewall-acl-addrule``            |
++-------------------------------------+-------------------------------------+
+| ``FIREWALL_ACL_REMOVERULE``         | ``firewall-acl-removerule``         |
++-------------------------------------+-------------------------------------+
+| ``NODE_APPLICATION_EXECUTE``        | ``node-application-execute``        |
++-------------------------------------+-------------------------------------+
+| ``NODE_APPLICATION_INSTALL``        | ``node-application-install``        |
++-------------------------------------+-------------------------------------+
+| ``NODE_FOLDER_CREATE``              | ``node-folder-create``              |
++-------------------------------------+-------------------------------------+
+| ``NODE_FILE_CREATE``                | ``node-file-create``                |
++-------------------------------------+-------------------------------------+
+| ``NODE_FILE_ACCESS``                | ``node-file-access``                |
++-------------------------------------+-------------------------------------+
+| ``NODE_NMAP_PING_SCAN``             | ``node-nmap-ping-scan``             |
++-------------------------------------+-------------------------------------+
+| ``NODE_NMAP_PORT_SCAN``             | ``node-nmap-port-scan``             |
++-------------------------------------+-------------------------------------+
+| ``NODE_NMAP_NETWORK_SERVICE_RECON`` | ``node-nmap-network-service-recon`` |
++-------------------------------------+-------------------------------------+
+| ``CONFIGURE_RANSOMWARE_SCRIPT``     | ``configure-ransomware-script``     |
++-------------------------------------+-------------------------------------+
+| ``CONFIGURE_C2_BEACON``             | ``configure-c2-beacon``             |
++-------------------------------------+-------------------------------------+
+| ``CONFIGURE_DATABASE_CLIENT``       | ``configure-database-client``       |
++-------------------------------------+-------------------------------------+
+| ``CONFIGURE_DOS_BOT``               | ``configure-dos-bot``               |
++-------------------------------------+-------------------------------------+
+| ``C2_SERVER_RANSOMWARE_LAUNCH``     | ``c2-server-ransomware-launch``     |
++-------------------------------------+-------------------------------------+
+| ``C2_SERVER_RANSOMWARE_CONFIGURE``  | ``c2-server-ransomware-configure``  |
++-------------------------------------+-------------------------------------+
+| ``C2_SERVER_TERMINAL_COMMAND``      | ``c2-server-terminal-command``      |
++-------------------------------------+-------------------------------------+
+| ``C2_SERVER_DATA_EXFILTRATE``       | ``c2-server-data-exfiltrate``       |
++-------------------------------------+-------------------------------------+
+| ``HOST_NIC_ENABLE``                 | ``host-nic-enable``                 |
++-------------------------------------+-------------------------------------+
+| ``HOST_NIC_DISABLE``                | ``host-nic-disable``                |
++-------------------------------------+-------------------------------------+
+| ``NODE_FILE_CORRUPT``               | ``node-file-corrupt``               |
++-------------------------------------+-------------------------------------+
+| ``NODE_SESSION_REMOTE_LOGIN``       | ``node-session-remote-login``       |
++-------------------------------------+-------------------------------------+
+| ``NODE_SESSION_REMOTE_LOGOFF``      | ``node-session-remote-logoff``      |
++-------------------------------------+-------------------------------------+
+| ``NODE_ACCOUNT_CHANGE_PASSWORD``    | ``node-account-change-password``    |
++-------------------------------------+-------------------------------------+
+| ``NODE_SEND_REMOTE_COMMAND``        | ``node-send-remote-command``        |
++-------------------------------------+-------------------------------------+
+
+
+- All reward component types must be converted to kebab-case. (``SHARED_REWARD`` - ``shared-reward``)
+
++----------------------------------------------+----------------------------------------------+
+| *3.0.0 reward type*                          | *4.0.0 reward name*                          |
++==============================================+==============================================+
+| ``SHARED_REWARD``                            | ``shared-reward``                            |
++----------------------------------------------+----------------------------------------------+
+| ``WEB_SERVER_404_PENALTY``                   | ``web-server-404-penalty``                   |
++----------------------------------------------+----------------------------------------------+
+| ``WEBPAGE_UNAVAILABLE_PENALTY``              | ``webpage-unavailable-penalty``              |
++----------------------------------------------+----------------------------------------------+
+| ``GREEN_ADMIN_DATABASE_UNREACHABLE_PENALTY`` | ``green-admin-database-unreachable-penalty`` |
++----------------------------------------------+----------------------------------------------+
+| ``ACTION_PENALTY``                           | ``action-penalty``                           |
++----------------------------------------------+----------------------------------------------+
+| ``DATABASE_FILE_INTEGRITY``                  | ``database-file-integrity``                  |
++----------------------------------------------+----------------------------------------------+
+
+
+- All agent types must be converted to kebab-case. (``ProxyAgent`` - ``proxy-agent``)
+
++--------------------------------+-----------------------------------+
+| *3.0.0 action type*            | *4.0.0 agent type*                |
++================================+===================================+
+| ``ProxyAgent``                 | ``proxy-agent``                   |
++--------------------------------+-----------------------------------+
+| ``RedDatabaseCorruptingAgent`` | ``red-database-corrupting-agent`` |
++--------------------------------+-----------------------------------+
+| ``ProbabilisticAgent``         | ``probabilistic-agent``           |
++--------------------------------+-----------------------------------+
+| ``RandomAgent``                | ``random-agent``                  |
++--------------------------------+-----------------------------------+
+| ``PeriodicAgent``              | ``periodic-agent``                |
++--------------------------------+-----------------------------------+
+
+
+``simulation``
+==============
+
+The only simulation yaml changes are that all software has been renamed to use kebab-case:
+
++-----------------------+------------------------+
+|*3.0.0 software name*  |*4.0.0 software name*   |
++=======================+========================+
+| ``WebBrowser``        | ``web-browser``        |
++-----------------------+------------------------+
+| ``DatabaseClient``    | ``database-client``    |
++-----------------------+------------------------+
+| ``DNSClient``         | ``dns-client``         |
++-----------------------+------------------------+
+| ``FTPServer``         | ``ftp-server``         |
++-----------------------+------------------------+
+| ``C2Beacon``          | ``c2-beacon``          |
++-----------------------+------------------------+
+| ``C2Server``          | ``c2-server``          |
++-----------------------+------------------------+
+| ``RansomwareScript``  | ``ransomware-script``  |
++-----------------------+------------------------+
+| ``WebServer``         | ``web-server``         |
++-----------------------+------------------------+
+| ``DOSBot``            | ``dos-bot``            |
++-----------------------+------------------------+
+| ``FTPClient``         | ``ftp-client``         |
++-----------------------+------------------------+
+| ``DNSServer``         | ``dns-server``         |
++-----------------------+------------------------+
+| ``Terminal``          | ``terminal``           |
++-----------------------+------------------------+
+| ``NTPClient``         | ``ntp-client``         |
++-----------------------+------------------------+
+| ``NTPServer``         | ``ntp-server``         |
++-----------------------+------------------------+
+| ``NMAP``              | ``nmap``               |
++-----------------------+------------------------+
+| ``HostARP``           | ``host-arp``           |
++-----------------------+------------------------+
+| ``ICMP``              | ``icmp``               |
++-----------------------+------------------------+
+
+
+A simple search and replace can be used with the lists above to update any configs.

docs/source/how_to_guides/using_dev_cli.rst

@@ -0,0 +1,8 @@
+.. only:: comment
+
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+
+Utilising the PrimAITE dev-mode cli
+***********************************
+
+A guide for utilising `primaite dev-mode` can be found within the ``How-To-Use-Primaite-Dev-Mode`` jupyter notebook, and also :ref:`Developer Tools`.

docs/source/node_sets.rst

@@ -0,0 +1,116 @@
+.. only:: comment
+
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+
+.. _network_node_adder:
+
+Network Node Adder Module
+#########################
+
+This module provides a framework for adding nodes to a network in a standardised way. It defines a base class ``NetworkNodeAdder``, which can be extended to create specific node adders, and utility functions to calculate network infrastructure requirements.
+
+The module allows you to use the pre-defined node adders, ``OfficeLANAdder``, or create custom ones by extending the base class.
+
+How It Works
+============
+
+The main class in the module is ``NetworkNodeAdder``, which defines the interface for adding nodes to a network. Child classes are expected to:
+
+1. Define a ``ConfigSchema`` nested class to define configuration options.
+2. Implement the ``add_nodes_to_net(config, network)`` method, which adds the nodes to the network according to the configuration object.
+
+The ``NetworkNodeAdder`` base class handles node adders defined in the primAITE config YAML file as well. It does this by keeping a registry of node adder classes, and uses the ``type`` field of the config to select the appropriate class to which to pass the configuration.
+
+Example Usage
+=============
+
+Via Python API
+--------------
+
+Adding nodes to a network can be done using the python API by constructing the relevant ``ConfigSchema`` object like this:
+
+.. code-block:: python
+
+    net = Network()
+
+    office_lan_config = OfficeLANAdder.ConfigSchema(
+        lan_name="CORP-LAN",
+        subnet_base=2,
+        pcs_ip_block_start=10,
+        num_pcs=8,
+        include_router=False,
+        bandwidth=150,
+    )
+    OfficeLANAdder.add_nodes_to_net(config=office_lan_config, network=net)
+
+In this example, a network with 8 computers connected by a switch will be added to the network object.
+
+
+Via YAML Config
+---------------
+
+.. code-block:: yaml
+
+    simulation:
+      network:
+        nodes:
+          # ... nodes go here
+        node_sets:
+          - type: office-lan
+            lan_name: CORP_LAN
+            subnet_base: 2
+            pcs_ip_block_start: 10
+            num_pcs: 8
+            include_router: False
+            bandwidth: 150
+          # ... additional node sets can be added below
+
+``NetworkNodeAdder`` reads the ``type`` property of the config, then constructs and passes the configuration to ``OfficeLANAdder.add_nodes_to_net()``.
+
+In this example, a network with 8 computers connected by a switch will be added to the network object. Equivalent to the above.
+
+
+Creating Custom Node Adders
+===========================
+To create a custom node adder, subclass NetworkNodeAdder and define:
+
+* A ConfigSchema class that defines the configuration schema for the node adder.
+* The add_nodes_to_net method that implements how nodes should be added to the network.
+
+Example: DataCenterAdder
+------------------------
+Here is an example of creating a custom node adder, DataCenterAdder:
+
+.. code-block:: python
+
+    class DataCenterAdder(NetworkNodeAdder, discriminator="data-center"):
+        class ConfigSchema(NetworkNodeAdder.ConfigSchema):
+            type: Literal["data-center"] = "data-center"
+            num_servers: int
+            data_center_name: str
+
+        @classmethod
+        def add_nodes_to_net(cls, config: ConfigSchema, network: Network) -> None:
+            for i in range(config.num_servers):
+                server = Computer(
+                    hostname=f"server_{i}_{config.data_center_name}",
+                    ip_address=f"192.168.100.{i + 8}",
+                    subnet_mask="255.255.255.0",
+                    default_gateway="192.168.100.1",
+                    start_up_duration=0
+                )
+                server.power_on()
+                network.add_node(server)
+
+**Using the Custom Node Adder:**
+
+.. code-block:: python
+
+    config = {
+        "type": "data-center",
+        "num_servers": 5,
+        "data_center_name": "dc1"
+    }
+
+    network = Network()
+    DataCenterAdder.from_config(config, network)

docs/source/notebooks/executed_notebooks.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 .. _Executed Notebooks:
 

docs/source/primaite-dependencies.rst

@@ -1,45 +1,47 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, 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                                  |
-+-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+
-| 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 |
-+-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+
++-------------------+---------------------+---------------+--------------------------------------+--------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
+| Name              | Supported Version   | Built Version | License                              | Description                                                                                            | URL                                                                 |
++===================+=====================+===============+======================================+========================================================================================================+=====================================================================+
+| gymnasium         | 0.28.1              | 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.0               | 8.1.5         |  BSD License                         | Jupyter interactive widgets                                                                            |  http://jupyter.org                                                 |
++-------------------+---------------------+---------------+--------------------------------------+--------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
+| jupyterlab        | 3.6.1               | 3.6.1         |  BSD License                         | JupyterLab computational environment                                                                   |  https://jupyter.org                                                |
++-------------------+---------------------+---------------+--------------------------------------+--------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
+| kaleido           | ==0.2.1             | 0.2.1         |  MIT                                 | Static image export for web-based visualization libraries with zero dependencies                       |  https://github.com/plotly/Kaleido                                  |
++-------------------+---------------------+---------------+--------------------------------------+--------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
+| matplotlib        | >=3.7.1             | 3.10.1        |  Python Software Foundation License  | Python plotting package                                                                                |  https://matplotlib.org                                             |
++-------------------+---------------------+---------------+--------------------------------------+--------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
+| matplotlib-inline | >=0.1.7             | 0.1.7         |  BSD License                         | Matplotlib Inline Back-end for IPython and Jupyter                                                     |  https://github.com/ipython/matplotlib-inline                       |
++-------------------+---------------------+---------------+--------------------------------------+--------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
+| networkx          | 3.1                 | 3.1           |  BSD License                         | Python package for creating and manipulating graphs and networks                                       |  https://networkx.org/                                              |
++-------------------+---------------------+---------------+--------------------------------------+--------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
+| numpy             | ~1.23               | 1.23.5        |  BSD License                         | NumPy is the fundamental package for array computing with Python.                                      |  https://www.numpy.org                                              |
++-------------------+---------------------+---------------+--------------------------------------+--------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
+| platformdirs      | 3.5.1               | 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                | 5.15.0        |  MIT License                         | An open-source, interactive data visualization library for Python                                      |  https://plotly.com/python/                                         |
++-------------------+---------------------+---------------+--------------------------------------+--------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
+| polars            | 0.20.30             | 0.20.30       |  MIT License                         | Blazingly fast DataFrame library                                                                       |  https://www.pola.rs/                                               |
++-------------------+---------------------+---------------+--------------------------------------+--------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
+| prettytable       | 3.8.0               | 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               | 2.7.0         |  MIT License                         | Data validation using Python type hints                                                                |  https://github.com/pydantic/pydantic                               |
++-------------------+---------------------+---------------+--------------------------------------+--------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
+| PyYAML            | >=6.0               | 6.0.2         |  MIT License                         | YAML parser and emitter for Python                                                                     |  https://pyyaml.org/                                                |
++-------------------+---------------------+---------------+--------------------------------------+--------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
+| ray               | >=2.20, <2.33       | 2.32.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               | 2.1.0         |  MIT                                 | Pytorch version of Stable Baselines, implementations of reinforcement learning algorithms.             |  https://github.com/DLR-RM/stable-baselines3                        |
++-------------------+---------------------+---------------+--------------------------------------+--------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
+| tensorflow        | ~=2.12              | 2.12.0        |  Apache Software License             | TensorFlow is an open source machine learning framework for everyone.                                  |  https://www.tensorflow.org/                                        |
++-------------------+---------------------+---------------+--------------------------------------+--------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
+| typer             | >=0.9               | 0.15.2        |  MIT License                         | Typer, build great CLIs. Easy to code. Based on Python type hints.                                     |  https://github.com/tiangolo/typer                                  |
++-------------------+---------------------+---------------+--------------------------------------+--------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
+| Deepdiff          | >=8.0.1             | 8.3.0         |  MIT License                         | Deep difference of dictionaries, iterables, strings, and any other object objects.                     |  https://github.com/seperman/deepdiff                               |
++-------------------+---------------------+---------------+--------------------------------------+--------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
+| sb3_contrib       | 2.1.0               | 2.1.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

@@ -1,6 +1,8 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+
+.. _request_system:
 
 Request System
 **************
@@ -51,10 +53,10 @@ Request responses
 When the simulator receives a request, it returns a response with a success status. The possible statuses are:
 
 * **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.
+    * For example, the agent tries to add an acl rule and specifies correct parameters, and the acl rule is added successfully.
 
 * **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.
+    * For example, the agent tries to execute the ``web-browser`` 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.
@@ -76,17 +78,26 @@ The ``RequestType`` object stores a reference to a method that executes the requ
 
 The ``RequestManager`` object stores a mapping between strings and request types. It is responsible for processing the request and passing it down the ownership tree. Technically, the ``RequestManager`` is itself a callable that accepts `request, context` tuple, and so it can be chained with other request managers.
 
-A simple example without chaining can be seen in the :py:class:`primaite.simulator.file_system.file_system.File` class.
+A simple example without chaining can be seen in the :py:class:`primaite.simulator.file_system.file_systemfile_system_item_abc.FileSystemItemABC` class.
 
 .. code-block:: python
 
-    class File(FileSystemItemABC):
+    class FileSystemItemABC(SimComponent):
         ...
         def _init_request_manager(self):
             ...
-            request_manager.add_request("scan", RequestType(func=lambda request, context: RequestResponse.from_bool(self.scan())))
-            request_manager.add_request("repair", RequestType(func=lambda request, context: RequestResponse.from_bool(self.repair())))
-            request_manager.add_request("restore", RequestType(func=lambda request, context: RequestResponse.from_bool(self.restore())))
+            rm.add_request(
+            name="scan", request_type=RequestType(func=lambda request, context: RequestResponse.from_bool(self.scan()))
+        )
+        rm.add_request(
+            name="checkhash",
+            request_type=RequestType(func=lambda request, context: RequestResponse.from_bool(self.check_hash())),
+        )
+        rm.add_request(
+            name="repair",
+            request_type=RequestType(func=lambda request, context: RequestResponse.from_bool(self.repair())),
+        )
+        ...
 
 *ellipses (``...``) used to omit code impertinent to this explanation*
 
@@ -101,27 +112,18 @@ An example of how this works is in the :py:class:`primaite.simulator.network.har
 
 .. code-block:: python
 
-    class Node(SimComponent):
+    class Node(SimComponent, ABC):
         ...
-        def _init_request_manager(self):
+        def _init_request_manager(self) -> RequestManager:
             ...
-            # a regular action which is processed by the Node itself
-            request_manager.add_request("turn_on", RequestType(func=lambda request, context: self.turn_on()))
-
-            # if the Node receives a request where the first word is 'service', it will use a dummy manager
-            # called self._service_request_manager to pass on the request to the relevant service. This dummy
-            # manager is simply here to map the service name that that service's own action manager. This is
-            # done because the next string after "service" is always the name of that service, so we need an
-            # RequestManager to pop that string before sending it onto the relevant service's RequestManager.
+            # since there are potentially many services, create an request manager that can map service name
             self._service_request_manager = RequestManager()
-            request_manager.add_request("service", RequestType(func=self._service_request_manager))
-            ...
+            rm.add_request("service", RequestType(func=self._service_request_manager, validator=_node_is_on))
+            self._nic_request_manager = RequestManager()
+            rm.add_request("network_interface", RequestType(func=self._nic_request_manager, validator=_node_is_on))
+
+            rm.add_request("file_system", RequestType(func=self.file_system._request_manager, validator=_node_is_on))
 
-        def install_service(self, service):
-            self.services[service.name] = service
-            ...
-            # Here, the service name is registered to allow passing actions between the node and the service.
-            self._service_request_manager.add_request(service.name, RequestType(func=service._request_manager))
 
 This process is repeated until the request word corresponds to a callable function rather than another ``RequestManager`` .
 
@@ -140,3 +142,8 @@ The :py:class:`primaite.interface.request.RequestResponse<RequestResponse>` carr
 For instance, the ``execute`` action on a :py:class:`primaite.simulator.system.applications.web_browser.WebBrowser<WebBrowser>` calls the ``get_webpage()`` method. ``get_webpage()`` returns a True if the webpage was successfully retrieved, and False if unsuccessful for any reason, such as being blocked by an ACL, or if the database server is unresponsive. The boolean returned from ``get_webpage()`` is used to create the request response with ``from_bool()``.
 
 Just as the requests themselves were passed from owner to component, the request response is bubbled back up from component to owner until it arrives at the game layer.
+
+Example notebooks
+-----------------
+Further examples of the request system and be found in ``Requests-and-Responses.ipynb``
+and ``Terminal-Processing.ipynb`` notebooks.

docs/source/rewards.rst

@@ -0,0 +1,128 @@
+.. only:: comment
+
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+
+.. _Rewards:
+
+Rewards
+#######
+
+Rewards in PrimAITE are based on a system of individual components that react to events in the simulation. An agent's reward function is calculated as the weighted sum of several reward components.
+
+Some rewards, such as the ``green-admin-database-unreachable-penalty``, can be marked as 'sticky' in their configuration. Setting this to ``True`` will mean that they continue to output the same value after an event until another event of that type.
+In the instance of the ``green-admin-database-unreachable-penalty``, the database admin reward will stay negative until the next successful database request is made, even if the database admin agents do nothing and the database returns a good state.
+
+Components
+**********
+The following API pages describe the use of each reward component and the possible configuration options. An example of configuring each via yaml is also provided.
+
+:py:class:`primaite.game.agent.rewards.DummyReward`
+
+.. code-block:: yaml
+
+    agents:
+      - ref: agent_name
+        # ...
+        reward_function:
+          reward_components:
+          - type: dummy
+            weight: 1.0
+
+
+:py:class:`primaite.game.agent.rewards.DatabaseFileIntegrity`
+
+.. code-block:: yaml
+
+    agents:
+      - ref: agent_name
+        # ...
+        reward_function:
+          reward_components:
+          - type: database-file-integrity
+            weight: 1.0
+            options:
+              node_hostname: server_1
+              folder_name: database
+              file_name: database.db
+
+
+:py:class:`primaite.game.agent.rewards.WebServer404Penalty`
+
+.. code-block:: yaml
+
+    agents:
+      - ref: agent_name
+        # ...
+        reward_function:
+          reward_components:
+          - type: web-server-404-penalty
+            node_hostname: web_server
+            weight: 1.0
+            options:
+              service_name: WebService
+              sticky: false
+
+
+:py:class:`primaite.game.agent.rewards.WebpageUnavailablePenalty`
+
+.. code-block:: yaml
+
+    agents:
+      - ref: agent_name
+        # ...
+        reward_function:
+          reward_components:
+          - type: webpage-unavailable-penalty
+            node_hostname: computer_1
+            weight: 1.0
+            options:
+              sticky: false
+
+
+:py:class:`primaite.game.agent.rewards.GreenAdminDatabaseUnreachablePenalty`
+
+.. code-block:: yaml
+
+    agents:
+      - ref: agent_name
+        # ...
+        reward_function:
+          reward_components:
+          - type: green-admin-database-unreachable-penalty
+            weight: 1.0
+            options:
+              node_hostname: admin_pc_1
+              sticky: false
+
+
+:py:class:`primaite.game.agent.rewards.SharedReward`
+
+.. code-block:: yaml
+
+    agents:
+      - ref: scripted_agent
+        # ...
+      - ref: agent_name
+        # ...
+        reward_function:
+          reward_components:
+          - type: shared-reward
+            weight: 1.0
+            options:
+              agent_name: scripted_agent
+
+
+:py:class:`primaite.game.agent.rewards.ActionPenalty`
+
+.. code-block:: yaml
+
+    agents:
+      - ref: agent_name
+        # ...
+        reward_function:
+          reward_components:
+          - type: action-penalty
+            weight: 1.0
+            options:
+                action_penalty: -0.3
+                do_nothing_penalty: 0.0

docs/source/simulation.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 
 Simulation

docs/source/simulation_components/network/airspace.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 .. _airspace:
 

docs/source/simulation_components/network/base_hardware.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 #############
 Base Hardware
@@ -21,6 +21,9 @@ The key elements defined in ``base.py`` are:
 
 ``Node``
 ========
+
+.. _node_description:
+
 The Node class stands as a central component in ``base.py``, acting as the superclass for all network nodes within a
 PrimAITE simulation.
 
@@ -42,7 +45,7 @@ Example code where a node is turned on:
     from primaite.simulator.network.hardware.base import Node
     from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState
 
-    node = Node(hostname="pc_a")
+    node = Node(config={"hostname":"pc_a"})
 
     assert node.operating_state is NodeOperatingState.OFF # By default, node is instantiated in an OFF state
 
@@ -65,7 +68,7 @@ If the node needs to be instantiated in an on state:
     from primaite.simulator.network.hardware.base import Node
     from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState
 
-    node = Node(hostname="pc_a", operating_state=NodeOperatingState.ON)
+    node = Node(config={"hostname":"pc_a", "operating_state":NodeOperatingState.ON})
 
     assert node.operating_state is NodeOperatingState.ON  # node is in ON state
 
@@ -76,7 +79,7 @@ Setting ``start_up_duration`` and/or ``shut_down_duration`` to ``0`` will allow
     from primaite.simulator.network.hardware.base import Node
     from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState
 
-    node = Node(hostname="pc_a", start_up_duration=0, shut_down_duration=0)
+    node = Node(config={"hostname":"pc_a", "start_up_duration":0, "shut_down_duration":0})
 
     assert node.operating_state is NodeOperatingState.OFF  # node is in OFF state
 
@@ -97,8 +100,8 @@ Node Behaviours/Functions
 - **receive_frame()**: Handles the processing of incoming network frames.
 - **apply_timestep()**: Advances the state of the node according to the simulation timestep.
 - **power_on()**: Initiates the node, enabling all connected Network Interfaces and starting all Services and
-  Applications, taking into account the `start_up_duration`.
-- **power_off()**: Stops the node's operations, adhering to the `shut_down_duration`.
+  Applications, taking into account the ``start_up_duration``.
+- **power_off()**: Stops the node's operations, adhering to the ``shut_down_duration``.
 - **ping()**: Sends ICMP echo requests to a specified IP address to test connectivity.
 - **has_enabled_network_interface()**: Checks if the node has any network interfaces enabled, facilitating network
   communication.
@@ -109,3 +112,207 @@ Node Behaviours/Functions
 The Node class handles installation of system software, network connectivity, frame processing, system logging, and
 power states. It establishes baseline functionality while allowing subclassing to model specific node types like hosts,
 routers, firewalls etc. The flexible architecture enables composing complex network topologies.
+
+User, UserManager, and UserSessionManager
+=========================================
+
+The ``base.py`` module also includes essential classes for managing users and their sessions within the PrimAITE
+simulation. These are the ``User``, ``UserManager``, and ``UserSessionManager`` classes. The base ``Node`` class comes
+with ``UserManager``, and ``UserSessionManager`` classes pre-installed.
+
+User Class
+----------
+
+The ``User`` class represents a user in the system. It includes attributes such as ``username``, ``password``,
+``disabled``, and ``is_admin`` to define the user's credentials and status.
+
+Example Usage
+^^^^^^^^^^^^^
+
+Creating a user:
+    .. code-block:: python
+
+        user = User(username="john_doe", password="12345")
+
+UserManager Class
+-----------------
+
+The ``UserManager`` class handles user management tasks such as creating users, authenticating them, changing passwords,
+and enabling or disabling user accounts. It maintains a dictionary of users and provides methods to manage them
+effectively.
+
+Example Usage
+^^^^^^^^^^^^^
+
+Creating a ``UserManager`` instance and adding a user:
+    .. code-block:: python
+
+        user_manager = UserManager()
+        user_manager.add_user(username="john_doe", password="12345")
+
+Authenticating a user:
+    .. code-block:: python
+
+        user = user_manager.authenticate_user(username="john_doe", password="12345")
+
+UserSessionManager Class
+------------------------
+
+The ``UserSessionManager`` class manages user sessions, including local and remote sessions. It handles session creation,
+timeouts, and provides methods for logging users in and out.
+
+Example Usage
+^^^^^^^^^^^^^
+
+Creating a ``UserSessionManager`` instance and logging a user in locally:
+    .. code-block:: python
+
+        session_manager = UserSessionManager()
+        session_id = session_manager.local_login(username="john_doe", password="12345")
+
+Logging a user out:
+    .. code-block:: python
+
+        session_manager.local_logout()
+
+Practical Examples
+------------------
+
+Below are unit tests which act as practical examples illustrating how to use the ``User``, ``UserManager``, and
+``UserSessionManager`` classes within the context of a client-server network simulation.
+
+Setting up a Client-Server Network
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: python
+
+    from typing import Tuple
+    from uuid import uuid4
+
+    import pytest
+
+    from primaite.simulator.network.container import Network
+    from primaite.simulator.network.hardware.nodes.host.computer import Computer
+    from primaite.simulator.network.hardware.nodes.host.server import Server
+
+    @pytest.fixture(scope="function")
+    def client_server_network() -> Tuple[Computer, Server, Network]:
+        network = Network()
+
+        client = Computer(config={
+            "hostname":"client",
+            "ip_address":"192.168.1.2",
+            "subnet_mask":"255.255.255.0",
+            "default_gateway":"192.168.1.1",
+            "start_up_duration":0,
+            }
+        )
+        client.power_on()
+
+        server = Server(config = {
+            "hostname":"server",
+            "ip_address":"192.168.1.3",
+            "subnet_mask":"255.255.255.0",
+            "default_gateway":"192.168.1.1",
+            "start_up_duration":0,
+            }
+        )
+        server.power_on()
+
+        network.connect(client.network_interface[1], server.network_interface[1])
+
+        return client, server, network
+
+Local Login Success
+^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: python
+
+    def test_local_login_success(client_server_network):
+        client, server, network = client_server_network
+
+        assert not client.user_session_manager.local_user_logged_in
+
+        client.user_session_manager.local_login(username="admin", password="admin")
+
+        assert client.user_session_manager.local_user_logged_in
+
+Local Login Failure
+^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: python
+
+    def test_local_login_failure(client_server_network):
+        client, server, network = client_server_network
+
+        assert not client.user_session_manager.local_user_logged_in
+
+        client.user_session_manager.local_login(username="jane.doe", password="12345")
+
+        assert not client.user_session_manager.local_user_logged_in
+
+Adding a New User and Successful Local Login
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: python
+
+    def test_new_user_local_login_success(client_server_network):
+        client, server, network = client_server_network
+
+        assert not client.user_session_manager.local_user_logged_in
+
+        client.user_manager.add_user(username="jane.doe", password="12345")
+
+        client.user_session_manager.local_login(username="jane.doe", password="12345")
+
+        assert client.user_session_manager.local_user_logged_in
+
+Clearing Previous Login on New Local Login
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: python
+
+    def test_new_local_login_clears_previous_login(client_server_network):
+        client, server, network = client_server_network
+
+        assert not client.user_session_manager.local_user_logged_in
+
+        current_session_id = client.user_session_manager.local_login(username="admin", password="admin")
+
+        assert client.user_session_manager.local_user_logged_in
+
+        assert client.user_session_manager.local_session.user.username == "admin"
+
+        client.user_manager.add_user(username="jane.doe", password="12345")
+
+        new_session_id = client.user_session_manager.local_login(username="jane.doe", password="12345")
+
+        assert client.user_session_manager.local_user_logged_in
+
+        assert client.user_session_manager.local_session.user.username == "jane.doe"
+
+        assert new_session_id != current_session_id
+
+Persistent Login for the Same User
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: python
+
+    def test_new_local_login_attempt_same_uses_persists(client_server_network):
+        client, server, network = client_server_network
+
+        assert not client.user_session_manager.local_user_logged_in
+
+        current_session_id = client.user_session_manager.local_login(username="admin", password="admin")
+
+        assert client.user_session_manager.local_user_logged_in
+
+        assert client.user_session_manager.local_session.user.username == "admin"
+
+        new_session_id = client.user_session_manager.local_login(username="admin", password="admin")
+
+        assert client.user_session_manager.local_user_logged_in
+
+        assert client.user_session_manager.local_session.user.username == "admin"
+
+        assert new_session_id == current_session_id

docs/source/simulation_components/network/network.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 .. _network:
 
@@ -48,7 +48,7 @@ we'll use the following Network that has a client, server, two switches, and a r
 
 .. code-block:: python
 
-    router_1 = Router(hostname="router_1", num_ports=3)
+    router_1 = Router(config={"hostname":"router_1", "num_ports":3})
     router_1.power_on()
     router_1.configure_port(port=1, ip_address="192.168.1.1", subnet_mask="255.255.255.0")
     router_1.configure_port(port=2, ip_address="192.168.2.1", subnet_mask="255.255.255.0")
@@ -57,9 +57,9 @@ we'll use the following Network that has a client, server, two switches, and a r
 
 .. code-block:: python
 
-    switch_1 = Switch(hostname="switch_1", num_ports=6)
+    switch_1 = Switch(config={"hostname":"switch_1", "num_ports":6})
     switch_1.power_on()
-    switch_2 = Switch(hostname="switch_2", num_ports=6)
+    switch_2 = Switch(config={"hostname":"switch_2", "num_ports":6})
     switch_2.power_on()
 
 5. Connect the Switches to the Router
@@ -75,18 +75,20 @@ we'll use the following Network that has a client, server, two switches, and a r
 
 .. code-block:: python
 
-    client_1 = Computer(
-        hostname="client_1",
-        ip_address="192.168.2.2",
-        subnet_mask="255.255.255.0",
-        default_gateway="192.168.2.1"
+    client_1 = Computer(config = {
+        "hostname":"client_1",
+        "ip_address":"192.168.2.2",
+        "subnet_mask":"255.255.255.0",
+        "default_gateway":"192.168.2.1",
+        }
     )
     client_1.power_on()
-    server_1 = Server(
-        hostname="server_1",
-        ip_address="192.168.1.2",
-        subnet_mask="255.255.255.0",
-        default_gateway="192.168.1.1"
+    server_1 = Server(config= {
+        "hostname":"server_1",
+        "ip_address":"192.168.1.2",
+        "subnet_mask":"255.255.255.0",
+        "default_gateway":"192.168.1.1",
+        }
     )
     server_1.power_on()
 
@@ -97,19 +99,19 @@ we'll use the following Network that has a client, server, two switches, and a r
     network.connect(endpoint_a=switch_2.network_interface[1], endpoint_b=client_1.network_interface[1])
     network.connect(endpoint_a=switch_1.network_interface[1], endpoint_b=server_1.network_interface[1])
 
-8. Add ACL rules on the Router to allow ARP and ICMP traffic.
+8. Add an ACL rule on the Router to allow ICMP traffic.
 
 .. code-block:: python
 
     router_1.acl.add_rule(
         action=ACLAction.PERMIT,
-        src_port=Port.ARP,
-        dst_port=Port.ARP,
+        src_port=PORT_LOOKUP["ARP"],
+        dst_port=PORT_LOOKUP["ARP"],
         position=22
     )
 
     router_1.acl.add_rule(
         action=ACLAction.PERMIT,
-        protocol=IPProtocol.ICMP,
+        protocol=PROTOCOL_LOOKUP["ICMP"],
         position=23
     )

docs/source/simulation_components/network/network_interfaces.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 #################################
 Network Interface Hierarchy Model

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

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 ########
 Firewall
@@ -156,8 +156,8 @@ To prevent all external traffic from accessing the internal network, with except
    # Exception rule to allow HTTP traffic from external to internal network
    firewall.internal_inbound_acl.add_rule(
        action=ACLAction.PERMIT,
-       protocol=IPProtocol.TCP,
-       dst_port=Port.HTTP,
+       protocol=PROTOCOL_LOOKUP["TCP"],
+       dst_port=PORT_LOOKUP["HTTP"],
        dst_ip_address="192.168.1.0",
        dst_wildcard_mask="0.0.0.255",
        position=2
@@ -172,16 +172,16 @@ To enable external traffic to access specific services hosted within the DMZ:
    # Allow HTTP and HTTPS traffic to the DMZ
    firewall.dmz_inbound_acl.add_rule(
        action=ACLAction.PERMIT,
-       protocol=IPProtocol.TCP,
-       dst_port=Port.HTTP,
+       protocol=PROTOCOL_LOOKUP["TCP"],
+       dst_port=PORT_LOOKUP["HTTP"],
        dst_ip_address="172.16.0.0",
        dst_wildcard_mask="0.0.0.255",
        position=3
    )
    firewall.dmz_inbound_acl.add_rule(
        action=ACLAction.PERMIT,
-       protocol=IPProtocol.TCP,
-       dst_port=Port.HTTPS,
+       protocol=PROTOCOL_LOOKUP["TCP"],
+       dst_port=PORT_LOOKUP["HTTPS"],
        dst_ip_address="172.16.0.0",
        dst_wildcard_mask="0.0.0.255",
        position=4
@@ -196,9 +196,9 @@ To permit SSH access from a designated external IP to a specific server within t
    # Allow SSH from a specific external IP to an internal server
    firewall.internal_inbound_acl.add_rule(
        action=ACLAction.PERMIT,
-       protocol=IPProtocol.TCP,
+       protocol=PROTOCOL_LOOKUP["TCP"],
        src_ip_address="10.0.0.2",
-       dst_port=Port.SSH,
+       dst_port=PORT_LOOKUP["SSH"],
        dst_ip_address="192.168.1.10",
        position=5
    )
@@ -212,9 +212,9 @@ To limit database server access to selected external IP addresses:
    # Allow PostgreSQL traffic from an authorized external IP to the internal DB server
    firewall.internal_inbound_acl.add_rule(
        action=ACLAction.PERMIT,
-       protocol=IPProtocol.TCP,
+       protocol=PROTOCOL_LOOKUP["TCP"],
        src_ip_address="10.0.0.3",
-       dst_port=Port.POSTGRES_SERVER,
+       dst_port=PORT_LOOKUP["POSTGRES_SERVER"],
        dst_ip_address="192.168.1.20",
        position=6
    )
@@ -222,8 +222,8 @@ To limit database server access to selected external IP addresses:
    # Deny all other PostgreSQL traffic from external sources
    firewall.internal_inbound_acl.add_rule(
        action=ACLAction.DENY,
-       protocol=IPProtocol.TCP,
-       dst_port=Port.POSTGRES_SERVER,
+       protocol=PROTOCOL_LOOKUP["TCP"],
+       dst_port=PORT_LOOKUP["POSTGRES_SERVER"],
        dst_ip_address="192.168.1.0",
        dst_wildcard_mask="0.0.0.255",
        position=7
@@ -247,15 +247,15 @@ To authorize HTTP/HTTPS access to a DMZ-hosted web server, excluding known malic
    # Allow HTTP/HTTPS traffic to the DMZ web server
    firewall.dmz_inbound_acl.add_rule(
        action=ACLAction.PERMIT,
-       protocol=IPProtocol.TCP,
-       dst_port=Port.HTTP,
+       protocol=PROTOCOL_LOOKUP["TCP"],
+       dst_port=PORT_LOOKUP["HTTP"],
        dst_ip_address="172.16.0.2",
        position=9
    )
    firewall.dmz_inbound_acl.add_rule(
        action=ACLAction.PERMIT,
-       protocol=IPProtocol.TCP,
-       dst_port=Port.HTTPS,
+       protocol=PROTOCOL_LOOKUP["TCP"],
+       dst_port=PORT_LOOKUP["HTTPS"],
        dst_ip_address="172.16.0.2",
        position=10
    )
@@ -269,9 +269,9 @@ To facilitate restricted access from the internal network to DMZ-hosted services
    # Permit specific internal application server HTTPS access to a DMZ-hosted API
    firewall.internal_outbound_acl.add_rule(
        action=ACLAction.PERMIT,
-       protocol=IPProtocol.TCP,
+       protocol=PROTOCOL_LOOKUP["TCP"],
        src_ip_address="192.168.1.30",  # Internal application server IP
-       dst_port=Port.HTTPS,
+       dst_port=PORT_LOOKUP["HTTPS"],
        dst_ip_address="172.16.0.3",  # DMZ API server IP
        position=11
    )
@@ -289,9 +289,9 @@ To facilitate restricted access from the internal network to DMZ-hosted services
    # Corresponding rule in DMZ inbound ACL to allow the traffic from the specific internal server
    firewall.dmz_inbound_acl.add_rule(
        action=ACLAction.PERMIT,
-       protocol=IPProtocol.TCP,
+       protocol=PROTOCOL_LOOKUP["TCP"],
        src_ip_address="192.168.1.30",  # Ensuring this specific source is allowed
-       dst_port=Port.HTTPS,
+       dst_port=PORT_LOOKUP["HTTPS"],
        dst_ip_address="172.16.0.3",  # DMZ API server IP
        position=13
    )
@@ -301,7 +301,7 @@ To facilitate restricted access from the internal network to DMZ-hosted services
        action=ACLAction.DENY,
        src_ip_address="192.168.1.0",
        src_wildcard_mask="0.0.0.255",
-       dst_port=Port.HTTPS,
+       dst_port=PORT_LOOKUP["HTTPS"],
        dst_ip_address="172.16.0.3",  # DMZ API server IP
        position=14
    )
@@ -315,8 +315,8 @@ To block all SSH access attempts from the external network:
    # Deny all SSH traffic from any external source
    firewall.external_inbound_acl.add_rule(
        action=ACLAction.DENY,
-       protocol=IPProtocol.TCP,
-       dst_port=Port.SSH,
+       protocol=PROTOCOL_LOOKUP["TCP"],
+       dst_port=PORT_LOOKUP["SSH"],
        position=1
    )
 
@@ -329,8 +329,8 @@ To allow the internal network to initiate HTTP connections to the external netwo
    # Permit outgoing HTTP traffic from the internal network to any external destination
    firewall.external_outbound_acl.add_rule(
        action=ACLAction.PERMIT,
-       protocol=IPProtocol.TCP,
-       dst_port=Port.HTTP,
+       protocol=PROTOCOL_LOOKUP["TCP"],
+       dst_port=PORT_LOOKUP["HTTP"],
        position=2
    )
 

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

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 
 #########
@@ -49,3 +49,5 @@ fundamental network operations:
 5. **NTP (Network Time Protocol) Client:** Synchronises the host's clock with network time servers.
 
 6. **Web Browser:** A simulated application that allows the host to request and display web content.
+
+7. **Terminal:** A simulated service that allows the host to connect to remote hosts and execute commands.

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

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 ############
 Network Node

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

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 ######
 Router

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

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 ######
 Switch

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

@@ -1,9 +1,9 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 ######
-Router
+Wireless Router
 ######
 
 The ``WirelessRouter`` class extends the functionality of the standard ``Router`` class within PrimAITE,
@@ -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="WIFI_2_4",
     )
 
 
@@ -64,7 +64,7 @@ other wireless devices within the same frequency band.
 Example Scenario
 ----------------
 
-This example sets up a network with two PCs (PC A and PC B), each connected to their own `WirelessRouter`
+This example sets up a network with two PCs (PC A and PC B), each connected to their own ``WirelessRouter``
 (Router 1 and Router 2). These routers are then wirelessly connected to each other, enabling communication between the
 PCs through the routers over the airspace. Access Control Lists (ACLs) are configured on the routers to permit ARP and
 ICMP traffic, ensuring basic network connectivity and ping functionality.
@@ -102,8 +102,8 @@ ICMP traffic, ensuring basic network connectivity and ping functionality.
     network.connect(pc_a.network_interface[1], router_1.router_interface)
 
     # Configure Router 1 ACLs
-    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, src_port=PORT_LOOKUP["ARP"], dst_port=PORT_LOOKUP["ARP"], position=22)
+    router_1.acl.add_rule(action=ACLAction.PERMIT, protocol=PROTOCOL_LOOKUP["ICMP"], position=23)
 
     # Configure PC B
     pc_b = Computer(
@@ -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="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="WIFI_2_4",
     )
 
     # Configure routes for inter-router communication
@@ -160,7 +160,7 @@ network segments.
 Viewing Wireless Network Configuration
 --------------------------------------
 
-The `AirSpace.show()` function is an invaluable tool for inspecting the current wireless network configuration within
+The :py:meth:`AirSpace.show() <primaite.simulator.network.airspace.AirSpace.show()>` function is an invaluable tool for inspecting the current wireless network configuration within
 the PrimAITE environment. It presents a table summarising all wireless interfaces, including routers and access points,
 that are active within the airspace. The table outlines each device's connected node name, MAC address, IP address,
 subnet mask, operating frequency, and status, providing a comprehensive view of the wireless network topology.
@@ -168,7 +168,7 @@ subnet mask, operating frequency, and status, providing a comprehensive view of
 Example Output
 ^^^^^^^^^^^^^^^
 
-Below is an example output of the `AirSpace.show()` function, demonstrating the visibility it provides into the
+Below is an example output of the :py:meth:`AirSpace.show() <primaite.simulator.network.airspace.AirSpace.show()>` function, demonstrating the visibility it provides into the
 wireless network:
 
 .. code-block:: none
@@ -182,10 +182,10 @@ wireless network:
 
 This table aids in verifying that wireless devices are correctly configured and operational. It also helps in
 diagnosing connectivity issues by ensuring that devices are on the correct frequency and have the appropriate network
-settings. The `Status` column, indicating whether a device is enabled or disabled, further assists in troubleshooting
+settings. The ``Status`` column, indicating whether a device is enabled or disabled, further assists in troubleshooting
 by quickly identifying any devices that are not actively participating in the network.
 
-Utilising the `AirSpace.show()` function is particularly beneficial in complex network simulations where multiple
+Utilising the :py:meth:`AirSpace.show() <primaite.simulator.network.airspace.AirSpace.show()>` function is particularly beneficial in complex network simulations where multiple
 wireless devices are in use. It provides a snapshot of the wireless landscape, facilitating the understanding of how
 devices interact within the network and ensuring that configurations are aligned with the intended network architecture.
 

docs/source/simulation_components/network/transport_to_data_link_layer.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
 
 Transport Layer to Data Link Layer
 ==================================
@@ -14,9 +14,11 @@ Transport Layer (Layer 4)
 **UDPHeader:** Represents a UDP header for the transport layer of a Network Frame. It includes source and destination
 ports. UDP (User Datagram Protocol) is a connectionless and unreliable transport protocol used for data transmission.
 
-**TCPFlags:** Enum representing TCP control flags used in a TCP connection, such as SYN, ACK, FIN, and RST. TCP
-(Transmission Control Protocol) is a connection-oriented and reliable transport protocol used for establishing and
-maintaining data streams.
+..
+    **TCPFlags:** Enum representing TCP control flags used in a TCP connection, such as SYN, ACK, FIN, and RST. TCP
+    (Transmission Control Protocol) is a connection-oriented and reliable transport protocol used for establishing and
+    maintaining data streams.
+.. not currently used
 
 **TCPHeader:** Represents a TCP header for the transport layer of a Network Frame. It includes source and destination
 ports and TCP flags. This header is used for establishing and managing TCP connections.
@@ -104,7 +106,7 @@ address of 'aa:bb:cc:dd:ee:ff' to port 8080 on the host 10.0.0.10 which has a NI
     ip_packet = IPPacket(
         src_ip_address="192.168.0.100",
         dst_ip_address="10.0.0.10",
-        protocol=IPProtocol.TCP
+        protocol=PROTOCOL_LOOKUP["TCP"]
     )
     # Data Link Layer
     ethernet_header = EthernetHeader(

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

@@ -0,0 +1,307 @@
+.. only:: comment
+
+    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+
+.. _C2_Suite:
+
+Command and Control Application Suite
+#####################################
+
+Comprising of two applications, the Command and Control (C2) suite intends to introduce
+malicious network architecture and further the realism of red agents within PrimAITE.
+
+Overview:
+=========
+
+These two new classes give red agents a cyber realistic way of leveraging the capabilities of the ``Terminal`` application whilst introducing more opportunities for the blue agent(s) to notice and subvert a red agent during an episode.
+
+For a more in-depth look at the command and control applications then please refer to the ``C2-E2E-Notebook``.
+
+``C2 Server``
+"""""""""""""
+
+The C2 Server application is intended to represent the malicious infrastructure already under the control of an adversary.
+
+The C2 Server is configured to listen and await ``keep alive`` traffic from a C2 beacon. Once received the C2 Server is able to send and receive C2 commands.
+
+Currently, the C2 Server offers four commands:
+
++---------------------+---------------------------------------------------------------------------+
+|C2 Command           | Meaning                                                                   |
++=====================+===========================================================================+
+|RANSOMWARE_CONFIGURE | Configures an installed ransomware script based on the passed parameters. |
++---------------------+---------------------------------------------------------------------------+
+|RANSOMWARE_LAUNCH    | Launches the installed ransomware script.                                 |
++---------------------+---------------------------------------------------------------------------+
+|DATA_EXFILTRATION    | Copies a target file from a remote node to the C2 Beacon & Server via FTP |
++---------------------+---------------------------------------------------------------------------+
+|TERMINAL             | Executes a command via the terminal installed on the C2 Beacons Host.     |
++---------------------+---------------------------------------------------------------------------+
+
+
+It's important to note that in order to keep PrimAITE realistic from a cyber perspective,
+the C2 Server application should never be visible or actionable upon directly by the blue agent.
+
+This is because in the real world, C2 servers are hosted on ephemeral public domains that would not be accessible by private network blue agent.
+Therefore granting blue agent(s) the ability to perform counter measures directly against the application would be unrealistic.
+
+It is more accurate to see the host that the C2 Beacon is installed on as being able to route to the C2 Server (Internet Access).
+
+``C2 Beacon``
+"""""""""""""
+
+The C2 Beacon application is intended to represent malware that is used to establish and maintain contact to a C2 Server within a compromised network.
+
+A C2 Beacon will need to be first configured with the C2 Server IP Address which can be done via the ``configure`` method.
+
+Once installed and configured; the C2 beacon can establish connection with the C2 Server via executing the application.
+
+This will send an initial ``keep alive`` to the given C2 Server (The C2 Server IPv4Address must be given upon C2 Beacon configuration).
+Which is then resolved and responded by another ``Keep Alive`` by the C2 server back to the C2 beacon to confirm connection.
+
+The C2 Beacon will send out periodic keep alive based on its configuration parameters to configure it's active connection with the C2 server.
+
+It's recommended that a C2 Beacon is installed and configured mid episode by a Red Agent for a more cyber realistic simulation.
+
+Usage
+=====
+
+As mentioned, the C2 Suite is intended to grant Red Agents further flexibility whilst also expanding a blue agent's observation space.
+
+Adding to this, the following behaviour of the C2 beacon can be configured by users for increased domain randomisation:
+
++---------------------+---------------------------------------------------------------------------+
+|Configuration Option | Option Meaning                                                            |
++=====================+===========================================================================+
+|c2_server_ip_address | The IP Address of the C2 Server. (The C2 Server must be running)          |
++---------------------+---------------------------------------------------------------------------+
+|keep_alive_frequency | How often should the C2 Beacon confirm it's connection in timesteps.      |
++---------------------+---------------------------------------------------------------------------+
+|masquerade_protocol  | What protocol should the C2 traffic masquerade as? (TCP opr UDP)          |
++---------------------+---------------------------------------------------------------------------+
+|masquerade_port      | What port should the C2 traffic use? (HTTP, FTP, or DNS)                  |
++---------------------+---------------------------------------------------------------------------+
+
+
+Implementation
+==============
+
+Both applications inherit from an abstract C2 which handles the keep alive functionality and main logic.
+However, each host implements it's own receive methods.
+
+- The ``C2 Beacon`` is responsible for the following logic:
+    - Establishes and confirms connection to the C2 Server via sending ``C2Payload.KEEP_ALIVE``.
+    - Receives and executes C2 Commands given by the C2 Server via ``C2Payload.INPUT``.
+    - Returns the RequestResponse of the C2 Commands executed back the C2 Server via ``C2Payload.OUTPUT``.
+
+- The ``C2 Server`` is responsible for the following logic:
+    - Listens and resolves connection to a C2 Beacon via responding to ``C2Payload.KEEP_ALIVE``.
+    - Sends C2 Commands to the C2 Beacon via ``C2Payload.INPUT``.
+    - Receives the RequestResponse of the C2 Commands executed by C2 Beacon via ``C2Payload.OUTPUT``.
+
+The sequence diagram below clarifies the functionality of both applications:
+
+.. image:: ../../../../_static/c2_sequence.png
+    :width: 1000
+    :align: center
+
+
+For further details and more in-depth examples please refer to the ``Command-&-Control notebook``
+
+Examples
+========
+
+Python
+""""""
+.. code-block:: python
+
+    # Network Setup
+    network = Network()
+
+
+    switch = Switch(config=Switch.ConfigSchema(hostname="switch", start_up_duration=0, num_ports=4))
+    switch.power_on()
+
+    node_a = Computer(config=Computer.ConfigSchema(hostname="node_a", ip_address="192.168.0.10", subnet_mask="255.255.255.0", start_up_duration=0))
+    node_a.power_on()
+    network.connect(node_a.network_interface[1], switch.network_interface[1])
+
+    node_b = Computer(config=Computer.ConfigSchema(hostname="node_b", ip_address="192.168.0.11", subnet_mask="255.255.255.0", start_up_duration=0))
+    node_b.power_on()
+
+    network.connect(node_b.network_interface[1], switch.network_interface[2])
+
+    node_c = Computer(config=Computer.ConfigSchema(hostname="node_c", ip_address="192.168.0.12", subnet_mask="255.255.255.0", start_up_duration=0))
+    node_c.power_on()
+    network.connect(node_c.network_interface[1], switch.network_interface[3])
+
+    node_c.software_manager.install(software_class=DatabaseService)
+    node_b.software_manager.install(software_class=DatabaseClient)
+    node_b.software_manager.install(software_class=RansomwareScript)
+    node_b.software_manager.install(software_class=C2Beacon)
+    node_a.software_manager.install(software_class=C2Server)
+
+    # C2 Application objects
+
+    c2_server_host: Computer = network.get_node_by_hostname("node_a")
+    c2_beacon_host: Computer = network.get_node_by_hostname("node_b")
+
+    c2_server: C2Server = c2_server_host.software_manager.software["c2-server"]
+    c2_beacon: C2Beacon = c2_beacon_host.software_manager.software["c2-beacon"]
+
+    # Configuring the C2 Beacon
+    c2_beacon.configure(c2_server_ip_address="192.168.0.10", keep_alive_frequency=5)
+
+    # Launching the C2 Server (Needs to be running in order to listen for connections)
+    c2_server.run()
+
+    # Establishing connection
+    c2_beacon.establish()
+
+    # Example command: Creating a file
+
+    file_create_command = {
+        "commands": [
+            ["file_system", "create", "folder", "test_folder"],
+            ["file_system", "create", "file", "test_folder", "example_file", "True"],
+        ],
+        "username": "admin",
+        "password": "admin",
+        "ip_address": None,
+    }
+
+    c2_server.send_command(C2Command.TERMINAL, command_options=file_create_command)
+
+    # Example command: Installing and configuring Ransomware:
+
+    ransomware_installation_command = { "commands": [
+            ["software_manager","application","install","ransomware-script"],
+        ],
+        "username": "admin",
+        "password": "admin",
+        "ip_address": None,
+    }
+    c2_server.send_command(given_command=C2Command.TERMINAL, command_options=ransomware_installation_command)
+
+    ransomware_config = {"server_ip_address": "192.168.0.12"}
+
+    c2_server.send_command(given_command=C2Command.RANSOMWARE_CONFIGURE, command_options=ransomware_config)
+
+    c2_beacon_host.software_manager.show()
+
+    # Example command: File Exfiltration
+
+    data_exfil_options = {
+        "username": "admin",
+        "password": "admin",
+        "ip_address": None,
+        "target_ip_address": "192.168.0.12",
+        "target_file_name": "database.db",
+        "target_folder_name": "database",
+    }
+
+    c2_server.send_command(given_command=C2Command.DATA_EXFILTRATION, command_options=data_exfil_options)
+
+    # Example command: Launching Ransomware
+
+    c2_server.send_command(given_command=C2Command.RANSOMWARE_LAUNCH, command_options={})
+
+
+
+Via Configuration
+"""""""""""""""""
+
+.. code-block:: yaml
+
+    simulation:
+        network:
+            nodes:
+                - ref: example_computer_1
+                hostname: computer_a
+                type: computer
+                ...
+                applications:
+                    type: c2-server
+            ...
+                hostname: computer_b
+                type: computer
+                ...
+                # A C2 Beacon will not automatically connection to a C2 Server.
+                # Either an agent must use application_execute.
+                # Or a if using the simulation layer - .establish().
+                applications:
+                    type: c2-beacon
+                    options:
+                        c2_server_ip_address: ...
+                        keep_alive_frequency: 5
+                        masquerade_protocol: tcp
+                        masquerade_port: http
+                        listen_on_ports:
+                            - 80
+                            - 53
+                            - 21
+
+
+
+C2 Beacon Configuration
+=======================
+
+``c2_server_ip_address``
+""""""""""""""""""""""""
+
+IP address of the ``C2Server`` that the C2 Beacon will use to establish connection.
+
+This must be a valid octet i.e. in the range of ``0.0.0.0`` and ``255.255.255.255``.
+
+
+``Keep Alive Frequency``
+""""""""""""""""""""""""
+
+How often should the C2 Beacon confirm it's connection in timesteps.
+
+For example, if the keep alive Frequency is set to one then every single timestep
+the C2 connection will be confirmed.
+
+It's worth noting that this may be a useful option when investigating
+network blue agent observation space.
+
+This must be a valid integer i.e ``10``. Defaults to ``5``.
+
+
+``Masquerade Protocol``
+"""""""""""""""""""""""
+
+The protocol that the C2 Beacon will use to communicate to the C2 Server with.
+
+Currently only ``TCP`` and ``UDP`` are valid masquerade protocol options.
+
+It's worth noting that this may be a useful option to bypass ACL rules.
+
+This must be a string i.e *UDP*. Defaults to ``TCP``.
+
+``Masquerade Port``
+"""""""""""""""""""
+
+What port that the C2 Beacon will use to communicate to the C2 Server with.
+
+Currently only ``FTP``, ``HTTP`` and ``DNS`` are valid masquerade port options.
+
+It's worth noting that this may be a useful option to bypass ACL rules.
+
+This must be a string i.e ``DNS``. Defaults to ``HTTP``.
+
+``Common Attributes``
+^^^^^^^^^^^^^^^^^^^^^
+
+See :ref:`Common Configuration`
+
+
+C2 Server Configuration
+=======================
+
+*The C2 Server does not currently offer any unique configuration options and will configure itself to match the C2 beacon's network behaviour.*
+
+``Common Attributes``
+^^^^^^^^^^^^^^^^^^^^^
+
+See :ref:`Common Configuration`