[skip ci]

Implements the following changes:

**Moving some of the text from index.html into about.html (reduces repeated text**)

Index.html (home)
	i.	Overview
	ii.	Features (the ones we have listed currently in v3.2.0)
About.html
	i.	Architecture
	ii.	Training & Evaluation Capability
	iii.	What is PrimAITE built with
	iv.	Getting started with PrimAITE

**Adds deepdiff and sb3_contrib to the dependencies list**

![image.png](https://dev.azure.com/ma-dev-uk/b50a61ee-86c4-48bc-9a0b-a67645ba12ee/_apis/git/repositories/2825053e-bd3b-45b2-8680-1281809eefa2/pullRequests/472/attachments/image.png)

**NMAP headers were inconsistent with other documentation. **

This may be an issue with the other documentation rather than NMAP however refactoring every header could cause a lot more headache.

![image (2).png](https://dev.azure.com/ma-dev-uk/b50a61ee-86c4-48bc-9a0b-a67645ba12ee/_apis/git/repositories/2825053e-bd3b-45b2-8680-1281809eefa2/pullRequests/472/attachments/image%20%282%29.png)

**General Improvements**

Small link fixes

changing up python outdated python information

adding the common.config to .rst documents that didnt have them previously.

Related work items: #2734

.azure/azure-build-deploy-docs-pipeline.yml

@@ -30,7 +30,7 @@ jobs:
     displayName: 'Install PrimAITE for docs autosummary'
 
   - script: |
-      apt-get install pandoc
+      sudo apt-get install pandoc
     displayName: 'Install Pandoc'
 
   - script: |

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

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

.github/workflows/build-sphinx.yml

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

.github/workflows/python-package.yml

@@ -5,13 +5,11 @@ on:
     branches:
       - main
       - dev
-      - dev-gui
       - 'release/**'
   pull_request:
     branches:
       - main
       - dev
-      - dev-gui
       - 'release/**'
 jobs:
   build:
@@ -19,7 +17,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10"]
+        python-version: ["3.9", "3.10", "3.11"]
 
     steps:
       - uses: actions/checkout@v3
@@ -54,13 +52,6 @@ jobs:
         run: |
           primaite setup
 
-      - name: Lint with flake8
-        run: |
-          # stop the build if there are Python syntax errors or undefined names
-          flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
-          # exit-zero treats all errors as warnings.
-          flake8 . --count --exit-zero --max-complexity=10 --max-line-length=120 --statistics
-
       - name: Run tests
         run: |
           pytest tests/

.gitignore

@@ -54,6 +54,7 @@ cover/
 tests/assets/**/*.png
 tests/assets/**/tensorboard_logs/
 tests/assets/**/checkpoints/
+notebook-tests/*.xml
 
 # Translations
 *.mo
@@ -148,7 +149,7 @@ cython_debug/
 
 # IDE
 .idea/
-docs/source/primaite-dependencies.rst
+
 .vscode/
 
 # outputs

.pre-commit-config.yaml

@@ -1,9 +1,17 @@
 repos:
+  - repo: local
+    hooks:
+      - id: ensure-copyright-clause
+        name: ensure copyright clause
+        entry: python copyright_clause_pre_commit_hook.py
+        language: python
   - repo: http://github.com/pre-commit/pre-commit-hooks
     rev: v4.4.0
     hooks:
       - id: check-yaml
-        exclude: scenario_with_placeholders/
+        exclude: |
+          | scenario_with_placeholders/
+          | mini_scenario_with_simulation_variation/
       - id: end-of-file-fixer
       - id: trailing-whitespace
       - id: check-added-large-files

CHANGELOG.md

@@ -2,239 +2,175 @@
 
 All notable changes to this project will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## 3.0.0b9
-- Removed deprecated `PrimaiteSession` class.
-- Added ability to set log levels via configuration.
-- Upgraded pydantic to version 2.7.0
-- Upgraded Ray to version >= 2.9
-- Added ipywidgets to the dependencies
-- Added ability to define scenarios that change depending on the episode number.
-- Standardised Environment API by renaming the config parameter of `PrimaiteGymEnv` from `game_config` to `env_config`
-- Database Connection ID's are now created/issued by DatabaseService and not DatabaseClient
-- Updated DatabaseClient so that it can now have a single native DatabaseClientConnection along with a collection of DatabaseClientConnection's.
-- Implemented the uninstall functionality for DatabaseClient so that all connections are terminated at the DatabaseService.
-- Added the ability for a DatabaseService to terminate a connection.
-- Added active_connection to DatabaseClientConnection so that if the connection is terminated active_connection is set to False and the object can no longer be used.
-- Added additional show functions to enable connection inspection.
-- Updates to agent logging, to include the reward both per step and per episode.
-- Introduced Developer CLI tools to assist with developing/debugging PrimAITE
-  - Can be enabled via `primaite dev-mode enable`
-  - Activating dev-mode will change the location where the sessions will be output - by default will output where the PrimAITE repository is located
-- Refactored all air-space usage to that a new instance of AirSpace is created for each instance of Network. This 1:1 relationship between network and airspace will allow parallelization.
-- Added notebook to demonstrate use of SubprocVecEnv from SB3 to vectorise environments to speed up training.
-
-
-
-## [Unreleased]
-- Made requests fail to reach their target if the node is off
-- Added responses to requests
-- Made environment reset completely recreate the game object.
-- Changed the red agent in the data manipulation scenario to randomly choose client 1 or client 2 to start its attack.
-- Changed the data manipulation scenario to include a second green agent on client 1.
-- Refactored actions and observations to be configurable via object name, instead of UUID.
-- Made database patch correctly take 2 timesteps instead of being immediate
-- Made database patch only possible when the software is compromised or good, it's no longer possible when the software is OFF or RESETTING
-- Added a notebook which explains Data manipulation scenario, demonstrates the attack, and shows off blue agent's action space, observation space, and reward function.
-- Made packet capture and system logging optional (off by default). To turn on, change the io_settings.save_pcap_logs and io_settings.save_sys_logs settings in the config.
-- Made observation space flattening optional (on by default). To turn off for an agent, change the `agent_settings.flatten_obs` setting in the config.
-- Added support for SQL INSERT command.
-- Added ability to log each agent's action choices in each step to a JSON file.
-- Removal of Link bandwidth hardcoding. This can now be configured via the network configuraiton yaml. Will default to 100 if not present.
-
-### Bug Fixes
-
-- ACL rules were not resetting on episode reset.
-- ACLs were not showing up correctly in the observation space.
-- Blue agent's ACL actions were being applied against the wrong IP addresses
-- Deleted files and folders did not reset correctly on episode reset.
-- Service health status was using the actual health state instead of the visible health state
-- Database file health status was using the incorrect value for negative rewards
-- Preventing file actions from reaching their intended file
-- The data manipulation attack was triggered at episode start.
-- FTP STOR stored an additional copy on the client machine's filesystem
-- The red agent acted to early
-- Order of service health state
-- Starting a node didn't start the services on it
-- Fixed an issue where the services were still able to run even though the node the service is installed on is turned off
-- The use of NODE_FILE_CHECKHASH and NODE_FOLDER_CHECKHASH in the current release is marked as 'Not Implemented'.
 
+## [3.2.0] - 2024-07-18
 
 ### Added
-- Network Hardware - Added base hardware module with NIC, SwitchPort, Node, and Link. Nodes have
-fundamental services like ARP, ICMP, and PCAP running them by default.
-- Network Transmission - Modelled OSI Model layers 1 through to 5 with various classes for creating network frames and
-transmitting them from a Service/Application, down through the layers, over the wire, and back up through the layers to
-a Service/Application another machine.
-- Introduced `Router` and `Switch` classes to manage networking routes more effectively.
-  - Added `ACLRule` and `RouteTableEntry` classes as part of the `Router`.
-- New `.show()` methods in all network component classes to inspect the state in either plain text or markdown formats.
-- Added `Computer` and `Server` class to better differentiate types of network nodes.
-- Integrated a new Use Case 2 network into the system.
-- New unit tests to verify routing between different subnets using `.ping()`.
-- system - Added the core structure of Application, Services, and Components. Also added a SoftwareManager and
-SessionManager.
-- Permission System - each action can define criteria that will be used to permit or deny agent actions.
-- File System - ability to emulate a node's file system during a simulation
-- Example notebooks - There are 5 jupyter notebook which walk through using PrimAITE
-  1. Training a Stable Baselines 3 agent
-  2. Training a single agent system using Ray RLLib
-  3. Training a multi-agent system Ray RLLib
-  4. Data manipulation end to end demonstration
-  5. Data manipulation scenario with customised red agents
-- Database:
-  - `DatabaseClient` and `DatabaseService` created to allow emulation of database actions
-  - Ability for `DatabaseService` to backup its data to another server via FTP and restore data from backup
-- Red Agent Services:
-  - Data Manipulator Bot - A red agent service which sends a payload to a target machine. (By default this payload is a SQL query that breaks a database). The attack runs in stages with a random, configurable probability of succeeding.
-  - `DataManipulationAgent` runs the Data Manipulator Bot according to a configured start step, frequency and variance.
-- DNS Services: `DNSClient` and `DNSServer`
-- FTP Services: `FTPClient` and `FTPServer`
-- HTTP Services: `WebBrowser` to simulate a web client and `WebServer`
-- NTP Services: `NTPClient` and `NTPServer`
-- **RouterNIC Class**: Introduced a new class `RouterNIC`, extending the standard `NIC` functionality. This class is specifically designed for router operations, optimizing the processing and routing of network traffic.
-  - **Custom Layer-3 Processing**: The `RouterNIC` class includes custom handling for network frames, bypassing standard Node NIC's Layer 3 broadcast/unicast checks. This allows for more efficient routing behavior in network scenarios where router-specific frame processing is required.
-  - **Enhanced Frame Reception**: The `receive_frame` method in `RouterNIC` is tailored to handle frames based on Layer 2 (Ethernet) checks, focusing on MAC address-based routing and broadcast frame acceptance.
-- **Subnet-Wide Broadcasting for Services and Applications**: Implemented the ability for services and applications to conduct broadcasts across an entire IPv4 subnet within the network simulation framework.
-- Introduced the `NetworkInterface` abstract class to provide a common interface for all network interfaces. Subclasses are divided into two main categories: `WiredNetworkInterface` and `WirelessNetworkInterface`, each serving as an abstract base class (ABC) for more specific interface types. Under `WiredNetworkInterface`, the subclasses `NIC` and `SwitchPort` were added. For wireless interfaces, `WirelessNIC` and `WirelessAccessPoint` are the subclasses under `WirelessNetworkInterface`.
-- Added `Layer3Interface` as an abstract base class for networking functionalities at layer 3, including IP addressing and routing capabilities. This class is inherited by `NIC`, `WirelessNIC`, and `WirelessAccessPoint` to provide them with layer 3 capabilities, facilitating their role in both wired and wireless networking contexts with IP-based communication.
-- Created the `ARP` and `ICMP` service classes to handle Address Resolution Protocol operations and Internet Control Message Protocol messages, respectively, with `RouterARP` and `RouterICMP` for router-specific implementations.
-- Created `HostNode` as a subclass of `Node`, extending its functionality with host-specific services and applications. This class is designed to represent end-user devices like computers or servers that can initiate and respond to network communications.
-- Introduced a new `IPV4Address` type in the Pydantic model for enhanced validation and auto-conversion of IPv4 addresses from strings using an `ipv4_validator`.
-- Comprehensive documentation for the Node and its network interfaces, detailing the operational workflow from frame reception to application-level processing.
-- Detailed descriptions of the Session Manager and Software Manager functionalities, including their roles in managing sessions, software services, and applications within the simulation.
-- Documentation for the Packet Capture (PCAP) service and SysLog functionality, highlighting their importance in logging network frames and system events, respectively.
-- Expanded documentation on network devices such as Routers, Switches, Computers, and Switch Nodes, explaining their specific processing logic and protocol support.
-- **Firewall Node**: Introduced the `Firewall` class extending the functionality of the existing `Router` class. The `Firewall` class incorporates advanced features to scrutinize, direct, and filter traffic between various network zones, guided by predefined security rules and policies. Key functionalities include:
-    - Access Control Lists (ACLs) for traffic filtering based on IP addresses, protocols, and port numbers.
-    - Network zone segmentation for managing traffic across external, internal, and DMZ (De-Militarized Zone) networks.
-    - Interface configuration to establish connectivity and define network parameters for external, internal, and DMZ interfaces.
-    - Protocol and service management to oversee traffic and enforce security policies.
-    - Dynamic traffic processing and filtering to ensure network security and integrity.
-- `AirSpace` class to simulate wireless communications, managing wireless interfaces and facilitating the transmission of frames within specified frequencies.
-- `AirSpaceFrequency` enum for defining standard wireless frequencies, including 2.4 GHz and 5 GHz bands, to support realistic wireless network simulations.
-- `WirelessRouter` class, extending the `Router` class, to incorporate wireless networking capabilities alongside traditional wired connections. This class allows the configuration of wireless access points with specific IP settings and operating frequencies.
-- Documentation Updates:
-    - Examples include how to set up PrimAITE session via config
-    - Examples include how to create nodes and install software via config
-    - Examples include how to set up PrimAITE session via Python
-    - Examples include how to create nodes and install software via Python
-    - Added missing ``DoSBot`` documentation page
-    - Added diagrams where needed to make understanding some things easier
-    - Templated parts of the documentation to prevent unnecessary repetition and for easier maintaining of documentation
-    - Separated documentation pages of some items i.e. client and server software were on the same pages - which may make things confusing
-    - Configuration section at the bottom of the software pages specifying the configuration options available (and which ones are optional)
-- Ability to add ``Firewall`` node via config
-- Ability to add ``Router`` routes via config
-- Ability to add ``Router``/``Firewall`` ``ACLRule`` via config
-- NMNE capturing capabilities to `NetworkInterface` class for detecting and logging Malicious Network Events.
-- New `nmne_config` settings in the simulation configuration to enable NMNE capturing and specify keywords such as "DELETE".
-- Router-specific SessionManager Implementation: Introduced a specialized version of the SessionManager tailored for router operations. This enhancement enables the SessionManager to determine the routing path by consulting the route table.
+-   Action penalty is a reward component that applies a negative reward for doing any action other than DONOTHING
+-   Application configuration actions for RansomwareScript, DatabaseClient, and DoSBot applications
+-   Ability to configure how long it takes to apply the service fix action
+-   Terminal service using SSH
+-   Airspaces now track the amount of data being transmitted, viewable using the `show_bandwidth_load` method
+-   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
-- Integrated the RouteTable into the Routers frame processing.
-- Frames are now dropped when their TTL reaches 0
-- **NIC Functionality Update**: Updated the Network Interface Card (`NIC`) functionality to support Layer 3 (L3) broadcasts.
-  - **Layer 3 Broadcast Handling**: Enhanced the existing `NIC` classes to correctly process and handle Layer 3 broadcasts. This update allows devices using standard NICs to effectively participate in network activities that involve L3 broadcasting.
-  - **Improved Frame Reception Logic**: The `receive_frame` method of the `NIC` class has been updated to include additional checks and handling for L3 broadcasts, ensuring proper frame processing in a wider range of network scenarios.
-- Standardised the way network interfaces are accessed across all `Node` subclasses (`HostNode`, `Router`, `Switch`) by maintaining a comprehensive `network_interface` attribute. This attribute captures all network interfaces by their port number, streamlining the management and interaction with network interfaces across different types of nodes.
-- Refactored all tests to utilise new `Node` subclasses (`Computer`, `Server`, `Router`, `Switch`) instead of creating generic `Node` instances and manually adding network interfaces. This change aligns test setups more closely with the intended use cases and hierarchies within the network simulation framework.
-- Updated all tests to employ the `Network()` class for managing nodes and their connections, ensuring a consistent and structured approach to setting up network topologies in testing scenarios.
-- **ACLRule Wildcard Masking**: Updated the `ACLRule` class to support IP ranges using wildcard masking. This enhancement allows for more flexible and granular control over traffic filtering, enabling the specification of broader or more specific IP address ranges in ACL rules.
-- Updated `NetworkInterface` documentation to reflect the new NMNE capturing features and how to use them.
-- Integration of NMNE capturing functionality within the `NICObservation` class.
-- Changed blue action set to enable applying node scan, reset, start, and shutdown to every host in data manipulation scenario
-
-### Removed
-- Removed legacy simulation modules: `acl`, `common`, `environment`, `links`, `nodes`, `pol`
-- Removed legacy training modules
-- Removed tests for legacy code
+-   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
+-   Application install no longer accepts an `ip_address` parameter
+-   Application install action can now be used on all applications
+-   Actions have additional logic for checking validity
+-   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
 
 ### Fixed
-- Addressed network transmission issues that previously allowed ARP requests to be incorrectly routed and repeated across different subnets. This fix ensures ARP requests are correctly managed and confined to their appropriate network segments.
-- Resolved problems in `Node` and its subclasses where the default gateway configuration was not properly utilized for communications across different subnets. This correction ensures that nodes effectively use their configured default gateways for outbound communications to other network segments, thereby enhancing the network's routing functionality and reliability.
-- Network Interface Port name/num being set properly for sys log and PCAP output.
+-   Links and airspaces can no longer transmit data if this would exceed their bandwidth
+
+
+## [3.1.0] - 2024-06-25
+
+### Added
+-   Observations for traffic amounts on host network interfaces
+-   NMAP application network discovery, including ping scan and port scan
+-   NMAP actions
+-   Automated adding copyright notices to source files
+-   More file types
+-   `show` method to files
+-   `model_dump` methods to network enums to enable better logging
+
+### Changed
+-   Updated file system actions to stop failures when creating duplicate files
+-   Improved parsing of ACL add rule actions to make some parameters optional
+
+### Fixed
+-   Fixed database client uninstall failing due to persistent connections
+-   Fixed packet storm when pinging broadcast addresses
+
+
+## [3.0.0] - 2024-06-10
+
+### Added
+-   New simulation module
+-   Multi agent reinforcement learning support
+-   File system class to manage files and folders
+-   Software for nodes that can have its own behaviour
+-   Software classes to model FTP, Postgres databases, web traffic, NTP
+-   Much more detailed network simulation including packets, links, and network interfaces
+-   More node types: host, computer, server, router, switch, wireless router, and firewalls
+-   Network Hardware - NIC, SwitchPort, Node, and Link. Nodes have fundamental services like ARP, ICMP, and PCAP running them by default.
+-   Malicious network event detection
+-   New `game` module for managing agents
+-   ACL rule wildcard masking
+-   Network broadcasting
+-   Wireless transmission
+-   More detailed documentation
+-   Example jupyter notebooks to demonstrate new functionality
+-   More reward components
+-   Packet capture logs
+-   Node system logs
+-   Per-step full simulation state log
+-   Attack randomisation with respect to timing and attack source
+-   Ability to set log level via CLI
+-   Ability to vary the YAML configuration per-episode
+-   Developer CLI tools for enhanced debugging (with `primaite dev-mode enable`)
+-   `show` function to many simulation objects to inspect their current state
+
+### Changed
+-   Decoupled the environment from the simulation by adding the `game` interface layer
+-   Made agents share a common base class
+-   Added more actions
+-   Made all agents use CAOS actions, including red and green agents
+-   Reworked YAML configuration file schema
+-   Reworked the reward system to be component-based
+-   Changed agent logs to create a JSON output instead of CSV with more detailed action information
+-   Made observation space flattening optional
+-   Made all logging optional
+-   Agent actions now provide responses with a success code
+
+### Removed
+-   Legacy simulation modules
+-   Legacy training modules
+-   Tests for legacy code
+-   Hardcoded IERs and PoL, traffic generation is now handled by agents and software
+-   Inbuilt agent training scripts
+
 
 ## [2.0.0] - 2023-07-26
 
 ### Added
-- Command Line Interface (CLI) for easy access and streamlined usage of PrimAITE.
-- Application Directories to enable PrimAITE as a Python package with predefined directories for storage.
-- Support for Ray Rllib, allowing training of PPO and A2C agents using Stable Baselines3 and Ray RLlib.
-- Random Red Agent to train the blue agent against, with options for randomised Red Agent `POL` and `IER`.
-- Repeatability of sessions through seed settings, and deterministic or stochastic evaluation options.
-- Session loading to revisit previously run sessions for SB3 Agents.
-- Agent Session Classes (`AgentSessionABC` and `HardCodedAgentSessionABC`) to standardise agent training with a common interface.
-- Standardised Session Output in a structured format in the user's app sessions directory, providing four types of outputs:
-  1. Session Metadata
-  2. Results
-  3. Diagrams
-  4. Saved agents (training checkpoints and a final trained agent).
-- Configurable Observation Space managed by the `ObservationHandler` class for a more flexible observation space setup.
-- Benchmarking of PrimAITE performance, showcasing session and step durations for reference.
-- Documentation overhaul, including automatic API and test documentation with recursive Sphinx auto-summary, using the Furo theme for responsive light/dark theme, and enhanced navigation with `sphinx-code-tabs` and `sphinx-copybutton`.
+-   Command Line Interface (CLI) for easy access and streamlined usage of PrimAITE.
+-   Application Directories to enable PrimAITE as a Python package with predefined directories for storage.
+-   Support for Ray Rllib, allowing training of PPO and A2C agents using Stable Baselines3 and Ray RLlib.
+-   Random Red Agent to train the blue agent against, with options for randomised Red Agent `POL` and `IER`.
+-   Repeatability of sessions through seed settings, and deterministic or stochastic evaluation options.
+-   Session loading to revisit previously run sessions for SB3 Agents.
+-   Agent Session Classes (`AgentSessionABC` and `HardCodedAgentSessionABC`) to standardise agent training with a common interface.
+-   Standardised Session Output in a structured format in the user's app sessions directory, providing four types of outputs: Session Metadata, Results, Diagrams, Trained agents.
+-   Configurable Observation Space managed by the `ObservationHandler` class for a more flexible observation space setup.
+-   Benchmarking of PrimAITE performance, showcasing session and step durations for reference.
+-   Documentation overhaul, including automatic API and test documentation with recursive Sphinx auto-summary, using the Furo theme for responsive light/dark theme, and enhanced navigation with `sphinx-code-tabs` and `sphinx-copybutton`.
 
 ### Changed
-- Action Space updated to discrete spaces, introducing a new `ANY` action space option for combined `NODE` and `ACL` actions.
-- Improved `Node` attribute naming convention for consistency, now adhering to `Pascal Case`.
-- Package Structure has been refactored for better build, distribution, and installation, with all source code now in the `src/` directory, and the `PRIMAITE` Python package renamed to `primaite` to adhere to PEP-8 Package & Module Names.
-- Docs and Tests now sit outside the `src/` directory.
-- Non-python files (example config files, Jupyter notebooks, etc.) now sit inside a `*/_package_data/` directory in their respective sub-packages.
-- All dependencies are now defined in the `pyproject.toml` file.
-- Introduced individual configuration for the number of episodes and time steps for training and evaluation sessions, with separate config values for each.
-- Decoupled the lay down config file from the training config, allowing more flexibility in configuration management.
-- Updated `Transactions` to only report pre-action observation, improving the CSV header and providing more human-readable descriptions for columns relating to observations.
-- Changes to `AccessControlList`, where the `acl` dictionary is now a list to accommodate changes to ACL action space and positioning of `ACLRules` inside the list to signal their level of priority.
+-   Action Space updated to discrete spaces, introducing a new `ANY` action space option for combined `NODE` and `ACL` actions.
+-   Improved `Node` attribute naming convention for consistency, now adhering to `Pascal Case`.
+-   Package Structure has been refactored for better build, distribution, and installation, with all source code now in the `src/` directory, and the `PRIMAITE` Python package renamed to `primaite` to adhere to PEP-8 Package & Module Names.
+-   Docs and Tests now sit outside the `src/` directory.
+-   Non-python files (example config files, Jupyter notebooks, etc.) now sit inside a `*/_package_data/` directory in their respective sub-packages.
+-   All dependencies are now defined in the `pyproject.toml` file.
+-   Introduced individual configuration for the number of episodes and time steps for training and evaluation sessions, with separate config values for each.
+-   Decoupled the lay down config file from the training config, allowing more flexibility in configuration management.
+-   Updated `Transactions` to only report pre-action observation, improving the CSV header and providing more human-readable descriptions for columns relating to observations.
+-   Changes to `AccessControlList`, where the `acl` dictionary is now a list to accommodate changes to ACL action space and positioning of `ACLRules` inside the list to signal their level of priority.
 
 
 ### Fixed
-- Various bug fixes, including Green IERs separation, correct clearing of links in the reference environment, and proper reward calculation.
-- Logic to check if a node is OFF before executing actions on the node by the blue agent, preventing erroneous state changes.
-- Improved functionality of Resetting a Node, adding "SHUTTING DOWN" and "BOOTING" operating states for more reliable reset commands.
-- Corrected the order of actions in the `Primaite` env to ensure the blue agent uses the current state for decision-making.
+-   Various bug fixes, including Green IERs separation, correct clearing of links in the reference environment, and proper reward calculation.
+-   Logic to check if a node is OFF before executing actions on the node by the blue agent, preventing erroneous state changes.
+-   Improved functionality of Resetting a Node, adding "SHUTTING DOWN" and "BOOTING" operating states for more reliable reset commands.
+-   Corrected the order of actions in the `Primaite` env to ensure the blue agent uses the current state for decision-making.
+
 
 ## [1.1.1] - 2023-06-27
 
-### Bug Fixes
-* Fixed bug whereby 'reference' environment links reach bandwidth capacity and are never cleared due to green & red IERs being applied to them. This bug had a knock-on effect that meant IERs were being blocked based on the full capacity of links on the reference environment which was not correct; they should only be based on the link capacity of the 'live' environment. This fix has been addressed by:
-  * Implementing a reference copy of all green IERs (`self.green_iers_reference`).
-  * Clearing the traffic on reference IERs at the same time as the live IERs.
-  * Passing the `green_iers_reference` to the `apply_iers` function at the reference stage.
-  * Passing the `green_iers_reference` as an additional argument to `calculate_reward_function`.
-  * Updating the green IERs section of the `calculate_reward_function` to now take into account both the green reference IERs and live IERs. The `green_ier_blocked` reward is only applied if the IER is blocked in the live environment but is running in the reference environment.
-  * Re-ordering the actions taken as part of the step function to ensure the blue action happens first before other changes.
-  * Removing the unnecessary "Reapply PoL and IERs" action from the step function.
-  * Moving the deep-copy of nodes and links to below the "Implement blue action" stage of the step function.
+### Fixed
+-   Fixed bug whereby 'reference' environment links reach bandwidth capacity and are never cleared due to green & red IERs being applied to them. This bug had a knock-on effect that meant IERs were being blocked based on the full capacity of links on the reference environment which was not correct; they should only be based on the link capacity of the 'live' environment. This fix has been addressed by:
+    -   Implementing a reference copy of all green IERs (`self.green_iers_reference`).
+    -   Clearing the traffic on reference IERs at the same time as the live IERs.
+    -   Passing the `green_iers_reference` to the `apply_iers` function at the reference stage.
+    -   Passing the `green_iers_reference` as an additional argument to `calculate_reward_function`.
+    -   Updating the green IERs section of the `calculate_reward_function` to now take into account both the green reference IERs and live IERs. The `green_ier_blocked` reward is only applied if the IER is blocked in the live environment but is running in the reference environment.
+    -   Re-ordering the actions taken as part of the step function to ensure the blue action happens first before other changes.
+    -   Removing the unnecessary "Reapply PoL and IERs" action from the step function.
+    -   Moving the deep-copy of nodes and links to below the "Implement blue action" stage of the step function.
+
 
 ## [1.1.0] - 2023-03-13
 
 ### Added
-* The user can now initiate either a TRAINING session or an EVALUATION (test) session with the Stable Baselines 3 (SB3) agents via the config_main.yaml file. During evaluation/testing, the agent policy will be fixed (no longer learning) and subjected to the SB3 `evaluate_policy()` function.
-* The user can choose whether a saved agent is loaded into the session (with reference to a URL) via the `config_main.yaml` file. They specify a Boolean true/false indicating whether a saved agent should be loaded, and specify the URL and file name.
-* Active and Service nodes now possess a new "File System State" attribute. This attribute is permitted to have the states GOOD, CORRUPT, DESTROYED, REPAIRING, and RESTORING. This new feature affects the following components:
-  * Blue agent observation space;
-  * Blue agent action space;
-  * Reward function;
-  * Node pattern-of-life.
-* The Red Agent node pattern-of-life has been enhanced so that node PoL is triggered by an 'initiator'. The initiator is either DIRECT (state change is applied to the node without any conditions), IER (state change is applied to the node based on IER entry condition), or SERVICE (state change is applied to the node based on a service state condition on the same node or a different node within the network).
-* New default config named "config_5_DATA_MANIPULATION.yaml" and associated Training Use Case Profile.
-* NodeStateInstruction has been split into `NodeStateInstructionGreen` and `NodeStateInstructionRed` to reflect the changes within the red agent pattern-of-life capability.
-* The reward function has been enhanced so that node attribute states of resetting, patching, repairing, and restarting contribute to the overall reward value.
-* The User Guide has been updated to reflect all the above changes.
+-   The user can now initiate either a TRAINING session or an EVALUATION (test) session with the Stable Baselines 3 (SB3) agents via the config_main.yaml file. During evaluation/testing, the agent policy will be fixed (no longer learning) and subjected to the SB3 `evaluate_policy()` function.
+-   The user can choose whether a saved agent is loaded into the session (with reference to a URL) via the `config_main.yaml` file. They specify a Boolean true/false indicating whether a saved agent should be loaded, and specify the URL and file name.
+-   Active and Service nodes now possess a new "File System State" attribute. This attribute is permitted to have the states GOOD, CORRUPT, DESTROYED, REPAIRING, and RESTORING. This new feature affects the following components:
+    -   Blue agent observation space;
+    -   Blue agent action space;
+    -   Reward function;
+    -   Node pattern-of-life.
+-   The Red Agent node pattern-of-life has been enhanced so that node PoL is triggered by an 'initiator'. The initiator is either DIRECT (state change is applied to the node without any conditions), IER (state change is applied to the node based on IER entry condition), or SERVICE (state change is applied to the node based on a service state condition on the same node or a different node within the network).
+-   New default config named "config_5_DATA_MANIPULATION.yaml" and associated Training Use Case Profile.
+-   NodeStateInstruction has been split into `NodeStateInstructionGreen` and `NodeStateInstructionRed` to reflect the changes within the red agent pattern-of-life capability.
+-   The reward function has been enhanced so that node attribute states of resetting, patching, repairing, and restarting contribute to the overall reward value.
+-   The User Guide has been updated to reflect all the above changes.
 
 ### Changed
-* "config_1_DDOS_BASIC.yaml" modified to make it more simplistic to aid evaluation testing.
-* "config_2_DDOS_BASIC.yaml" updated to reflect the addition of the File System State and the Red Agent node pattern-of-life enhancement.
-* "config_3_DOS_VERY_BASIC.yaml" updated to reflect the addition of the File System State and the Red Agent node pattern-of-life enhancement.
-* "config_UNIT_TEST.yaml" is a copy of the new "config_5_DATA_MANIPULATION.yaml" file.
-* Updates to Transactions.
+-   "config_1_DDOS_BASIC.yaml" modified to make it more simplistic to aid evaluation testing.
+-   "config_2_DDOS_BASIC.yaml" updated to reflect the addition of the File System State and the Red Agent node pattern-of-life enhancement.
+-   "config_3_DOS_VERY_BASIC.yaml" updated to reflect the addition of the File System State and the Red Agent node pattern-of-life enhancement.
+-   "config_UNIT_TEST.yaml" is a copy of the new "config_5_DATA_MANIPULATION.yaml" file.
+-   Updates to Transactions.
 
 ### Fixed
-* Fixed "config_2_DDOS_BASIC.yaml" by adding another ACL rule to allow traffic to flow from Node 9 to Node 3. Previously, there was no rule, so one of the green IERs could not flow by default.
-
-
-
-[unreleased]: https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE/compare/v2.0.0...HEAD
-[2.0.0]: https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE/releases/tag/v2.0.0
+-   Fixed "config_2_DDOS_BASIC.yaml" by adding another ACL rule to allow traffic to flow from Node 9 to Node 3. Previously, there was no rule, so one of the green IERs could not flow by default.

CONTRIBUTING.md

@@ -4,20 +4,17 @@
 ### **Did you find a bug?**
 
 
-* **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**
+* **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**
 
 
 ### **Do you have a solution to fix the bug?**
 
-* [Fork the repository](https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE/fork).
+* [Fork the repository](https://github.com/{todo:fill in URL}/PrimAITE/fork).
 * Install the pre-commit hook with `pre-commit install`.
 * Implement the bug fix.
-* Update documentation where applicable.
-* Update the **UNRELEASED** section of the [CHANGELOG.md](CHANGELOG.md) file
-* Write a suitable test/tests.
-* 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.
+* 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.
 
 ### **Did you fix whitespace, format code, or make a purely cosmetic patch?**
 
@@ -25,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/Autonomous-Resilient-Cyber-Defence/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/{todo:fill in URL}/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

@@ -1,21 +1,27 @@
-MIT License
+MIT License License
 
-Copyright (c) 2023 - 2025 Defence Science and Technology Laboratory UK (https://dstl.gov.uk)
+MIT License Conditions
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
+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
-in the Software without restriction, including without limitation the rights
+request to the QQ or FNC mailbox):
+
 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:
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+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 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
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+
+The material is supplied in confidence to QQ / FNC and their subcontractors under SERAPIS, and is issued to inform only those
 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.
+

README.md

@@ -33,7 +33,7 @@ Currently, the PrimAITE wheel can only be installed from GitHub. This may change
 #### Windows (PowerShell)
 
 **Prerequisites:**
-* Manual install of Python >= 3.8 < 3.12
+* Manual install of Python >= 3.9 < 3.12
 
 **Install:**
 
@@ -43,7 +43,7 @@ cd ~\primaite
 python3 -m venv .venv
 attrib +h .venv /s /d # Hides the .venv directory
 .\.venv\Scripts\activate
-pip install primaite-3.0.0-py3-none-any.whl[rl]
+pip install primaite-{VERSION}-py3-none-any.whl[rl]
 primaite setup
 ```
 
@@ -66,7 +66,7 @@ mkdir ~/primaite
 cd ~/primaite
 python3 -m venv .venv
 source .venv/bin/activate
-pip install primaite-3.0.0-py3-none-any.whl[rl]
+pip install primaite-{VERSION}-py3-none-any.whl[rl]
 primaite setup
 ```
 
@@ -77,7 +77,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:Autonomous-Resilient-Cyber-Defence/PrimAITE.git
+git clone git@github.com:{todo:fill in URL}/PrimAITE.git
 ```
 
 #### 2. CD into the repo directory

_config.yml

@@ -0,0 +1,3 @@
+# Used by nbmake to change build pipeline notebook timeout
+execute:
+  timeout: 600

benchmark/report.py

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

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

@@ -1006,4 +1006,4 @@
         "999": 112.49999999999994,
         "1000": 115.2500000000002
     }
-}
+}

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

@@ -1006,4 +1006,4 @@
         "999": 103.49999999999994,
         "1000": 117.9500000000001
     }
-}
+}

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

@@ -1006,4 +1006,4 @@
         "999": 112.00000000000017,
         "1000": 106.10000000000002
     }
-}
+}

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

@@ -1006,4 +1006,4 @@
         "999": 100.75000000000009,
         "1000": 110.70000000000007
     }
-}
+}

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

@@ -1006,4 +1006,4 @@
         "999": 110.6500000000001,
         "1000": 113.10000000000015
     }
-}
+}

benchmark/results/v3/v3.0.0/v3.0.0_benchmark_metadata.json

@@ -7433,4 +7433,4 @@
             }
         }
     }
-}
+}

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

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

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

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

copyright_clause_pre_commit_hook.py

@@ -0,0 +1,154 @@
+# -*- coding: utf-8 -*-
+import datetime
+import sys
+from pathlib import Path
+
+# Constants
+CURRENT_YEAR = datetime.date.today().year
+COPYRIGHT_PY_STR = f"# © Crown-owned copyright {CURRENT_YEAR}, Defence Science and Technology Laboratory UK"
+COPYRIGHT_RST_LINES = [
+    ".. only:: comment",
+    "",
+    f"    © Crown-owned copyright {CURRENT_YEAR}, Defence Science and Technology Laboratory UK",
+]
+PATHS = {Path("./src"), Path("./tests"), Path("./docs"), Path("./benchmark")}
+EXTENSIONS = {".py", ".rst"}
+
+
+def _is_copyright_line(line: str) -> bool:
+    """
+    Check if a line is a copyright line.
+
+    :param line: The line to check.
+    :return: True if the line is a copyright line, False otherwise.
+    """
+    return line.startswith("#") and "copyright" in line.lower()
+
+
+def _is_rst_copyright_lines(lines: list) -> bool:
+    """
+    Check if the lines match the RST copyright format.
+
+    :param lines: The lines to check.
+    :return: True if the lines match the RST copyright format, False otherwise.
+    """
+    return len(lines) >= 3 and lines[0] == ".. only:: comment" and "copyright" in lines[2].lower()
+
+
+def process_py_file(file_path: Path) -> bool:
+    """
+    Process a Python file to check and add/update the copyright clause.
+
+    :param file_path: The path to the file to check and update.
+    :return: True if the file was modified, False otherwise.
+    """
+    modified = False
+    try:
+        content = file_path.read_text(encoding="utf-8")
+        lines = content.splitlines(keepends=True)  # Keep line endings
+
+        if lines and _is_copyright_line(lines[0]):
+            if lines[0].strip() != COPYRIGHT_PY_STR:
+                lines[0] = COPYRIGHT_PY_STR + "\n"
+                modified = True
+                print(f"Updated copyright clause in {file_path}")
+        else:
+            lines.insert(0, COPYRIGHT_PY_STR + "\n")
+            modified = True
+            print(f"Added copyright clause to {file_path}")
+
+        if modified:
+            file_path.write_text("".join(lines), encoding="utf-8")
+    except Exception as e:
+        print(f"Failed to process {file_path}: {e}")
+        return False
+
+    return modified
+
+
+def process_rst_file(file_path: Path) -> bool:
+    """
+    Process an RST file to check and add/update the copyright clause.
+
+    :param file_path: The path to the file to check and update.
+    :return: True if the file was modified, False otherwise.
+    """
+    modified = False
+    try:
+        content = file_path.read_text(encoding="utf-8")
+        lines = content.splitlines(keepends=True)  # Keep line endings
+
+        existing_block = any(".. only:: comment" in line for line in lines)
+
+        if existing_block:
+            # Check if the block is correct
+            for i, line in enumerate(lines):
+                if line.strip() == ".. only:: comment":
+                    if lines[i : i + 3] != [
+                        COPYRIGHT_RST_LINES[0] + "\n",
+                        COPYRIGHT_RST_LINES[1] + "\n",
+                        COPYRIGHT_RST_LINES[2] + "\n",
+                    ]:
+                        # Update the incorrect block
+                        lines[i : i + 3] = [
+                            COPYRIGHT_RST_LINES[0] + "\n",
+                            COPYRIGHT_RST_LINES[1] + "\n",
+                            COPYRIGHT_RST_LINES[2] + "\n",
+                        ]
+                        modified = True
+                        print(f"Updated copyright clause in {file_path}")
+                    break
+        else:
+            # Insert new copyright block
+            lines = [line + "\n" for line in COPYRIGHT_RST_LINES] + ["\n"] + lines
+            modified = True
+            print(f"Added copyright clause to {file_path}")
+
+        if modified:
+            file_path.write_text("".join(lines), encoding="utf-8")
+    except Exception as e:
+        print(f"Failed to process {file_path}: {e}")
+        return False
+
+    return modified
+
+
+def process_file(file_path: Path) -> bool:
+    """
+    Check if a file has the correct copyright clause and add or update it if necessary.
+
+    :param file_path: The path to the file to check and update.
+    :return: True if the file was modified, False otherwise.
+    """
+    if file_path.suffix == ".py":
+        return process_py_file(file_path)
+    elif file_path.suffix == ".rst":
+        return process_rst_file(file_path)
+    return False
+
+
+def main() -> int:
+    """
+    Main function to walk through the root directories, check files, and update the copyright clause.
+
+    :return: 1 if any file was modified, 0 otherwise.
+    """
+    files_checked = 0
+    files_modified = 0
+    any_file_modified = False
+    for path in PATHS:
+        for file_path in path.rglob("*"):
+            if file_path.suffix in EXTENSIONS:
+                files_checked += 1
+                if process_file(file_path):
+                    files_modified += 1
+                    any_file_modified = True
+
+    if any_file_modified:
+        print(f"Files Checked: {files_checked}. Files Modified: {files_modified}")
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

docs/Makefile

@@ -1,3 +1,4 @@
+# © Crown-owned copyright 2024, 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.

docs/_templates/custom-class-template.rst

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

docs/_templates/custom-module-template.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2024, 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 2023, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2024, 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,3 +1,4 @@
+# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
 #!/bin/bash
 set -x
 
@@ -42,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://Autonomous-Resilient-Cyber-Defence.github.io/PrimAITE/,
+This branch is simply a cache for the website served from https://{todo:fill in URL}.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 2023, Defence Science and Technology Laboratory UK
+# © Crown-owned copyright 2024, 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:
@@ -147,7 +147,7 @@ def copy_notebooks_to_docs() -> Any:
     This allows developers to create new notebooks without having to worry about updating documentation when
     a new notebook is included within PrimAITE.
     """
-    notebook_asset_types = [".ipynb", ".png"]
+    notebook_asset_types = [".ipynb", ".png", ".svg"]
     notebook_directories = []
 
     # find paths where notebooks are contained

docs/index.rst

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

docs/make.bat

@@ -1,4 +1,5 @@
 @ECHO OFF
+REM  © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
 
 setlocal EnableDelayedExpansion
 

docs/source/about.rst

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

docs/source/action_masking.rst

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

docs/source/configuration/agents.rst

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

docs/source/configuration/game.rst

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

docs/source/configuration/io_settings.rst

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

docs/source/configuration/simulation.rst

@@ -1,13 +1,13 @@
 .. only:: comment
 
-    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2024, 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.
 
-At the top level of the network are ``nodes`` and ``links``.
+At the top level of the network are ``nodes``, ``links`` and ``airspace``.
 
 e.g.
 
@@ -19,6 +19,9 @@ e.g.
             ...
             links:
             ...
+            airspace:
+            ...
+
 
 ``nodes``
 ---------
@@ -101,3 +104,27 @@ This accepts an integer value e.g. if port 1 is to be connected, the configurati
 ``bandwidth``
 
 This is an integer value specifying the allowed bandwidth across the connection. Units are in Mbps.
+
+``airspace``
+------------
+
+This section configures settings specific to the wireless network's virtual airspace.
+
+``frequency_max_capacity_mbps``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This setting allows the user to override the default maximum bandwidth capacity set for each frequency. The key should
+be the AirSpaceFrequency name and the value be the desired maximum bandwidth capacity in mbps (megabits per second) for
+a single timestep.
+
+The below example would permit 123.45 megabits to be transmit across the WiFi 2.4 GHz frequency in a single timestep.
+Setting a frequencies max capacity to 0.0 blocks that frequency on the airspace.
+
+.. code-block:: yaml
+
+    simulation:
+      network:
+        airspace:
+          frequency_max_capacity_mbps:
+            WIFI_2_4: 123.45
+            WIFI_5: 0.0

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

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2024, 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 2023, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2024, 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 2023, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
 
 .. _common_network_node_attributes:
 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

docs/source/customising_scenarios.rst

@@ -1,3 +1,7 @@
+.. only:: comment
+
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+
 Customising Agents
 ******************
 

docs/source/developer_tools.rst

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

docs/source/environment.rst

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

docs/source/example_notebooks.rst

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

docs/source/game_layer.rst

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

docs/source/getting_started.rst

@@ -113,7 +113,7 @@ For example:
 
 .. code-block:: bash
 
-    git clone https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE
+    git clone https://github.com/{todo:fill in URL}/PrimAITE
     cd primaite
 
 2. Create and activate your Python virtual environment (venv)

docs/source/notebooks/executed_notebooks.rst

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

docs/source/primaite-dependencies.rst

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

docs/source/request_system.rst

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

docs/source/simulation.rst

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

docs/source/simulation_components/network/airspace.rst

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

docs/source/simulation_components/network/base_hardware.rst

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

docs/source/simulation_components/network/network.rst

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

docs/source/simulation_components/network/network_interfaces.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2024, 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 2023, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
 
 ########
 Firewall

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

@@ -1,3 +1,7 @@
+.. only:: comment
+
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+
 
 #########
 Host Node

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

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2024, 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 2023, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
 
 ######
 Router

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

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

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

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

docs/source/simulation_components/network/transport_to_data_link_layer.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
 
 Transport Layer to Data Link Layer
 ==================================

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

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

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

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

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

@@ -1,13 +1,16 @@
 .. only:: comment
 
-    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
 
 .. _DoSBot:
 
 DoSBot
 ######
 
-The ``DoSBot`` is an implementation of a Denial of Service attack within the PrimAITE simulation. This specifically simulates a `Slow Loris attack <https://en.wikipedia.org/wiki/Slowloris_(computer_security)>`.
+The ``DoSBot`` is an implementation of a Denial of Service attack within the PrimAITE simulation.
+This specifically simulates a `Slow Loris attack`_.
+
+.. _Slow Loris Attack: https://en.wikipedia.org/wiki/Slowloris_(computer_security)
 
 Key features
 ============

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

@@ -0,0 +1,355 @@
+.. only:: comment
+
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+
+.. _NMAP:
+
+NMAP
+####
+
+Overview
+========
+
+The NMAP application is used to simulate network scanning activities. NMAP is a powerful tool that helps in discovering
+hosts and services on a network. It provides functionalities such as ping scans to discover active hosts and port scans
+to detect open ports on those hosts.
+
+The NMAP application is essential for network administrators and security professionals to map out a network's
+structure, identify active devices, and find potential vulnerabilities by discovering open ports and running services.
+However, it is also a tool frequently used by attackers during the reconnaissance stage of a cyber attack to gather
+information about the target network.
+
+Scan Type
+=========
+
+Ping Scan
+^^^^^^^^^
+
+A ping scan is used to identify which hosts on a network are active and reachable. This is achieved by sending ICMP
+Echo Request packets (ping) to the target IP addresses. If a host responds with an ICMP Echo Reply, it is considered
+active. Ping scans are useful for quickly mapping out live hosts in a network.
+
+Port Scan
+^^^^^^^^^
+
+A port scan is used to detect open ports on a target host or range of hosts. Open ports can indicate running services
+that might be exploitable or require securing. Port scans help in understanding the services available on a network and
+identifying potential entry points for attacks. There are three types of port scans based on the scope:
+
+- **Horizontal Port Scan**: This scan targets a specific port across a range of IP addresses. It helps in identifying
+  which hosts have a particular service running.
+
+- **Vertical Port Scan**: This scan targets multiple ports on a single IP address. It provides detailed information
+  about the services running on a specific host.
+
+- **Box Scan**: This combines both horizontal and vertical scans, targeting multiple ports across multiple IP addresses.
+  It gives a comprehensive view of the network's service landscape.
+
+Example Usage
+^^^^^^^^^^^^^
+
+The network we use for these examples is defined below:
+
+.. code-block:: python
+
+    from ipaddress import IPv4Network
+
+    from primaite.simulator.network.container import Network
+    from primaite.simulator.network.hardware.nodes.host.computer import Computer
+    from primaite.simulator.network.hardware.nodes.network.router import Router
+    from primaite.simulator.network.hardware.nodes.network.switch import Switch
+    from primaite.simulator.system.applications.nmap import NMAP
+    from primaite.simulator.system.services.database.database_service import DatabaseService
+
+    # Initialize the network
+    network = Network()
+
+    # Set up the router
+    router = Router(hostname="router", start_up_duration=0)
+    router.power_on()
+    router.configure_port(port=1, ip_address="192.168.1.1", subnet_mask="255.255.255.0")
+
+    # Set up PC 1
+    pc_1 = Computer(
+        hostname="pc_1",
+        ip_address="192.168.1.11",
+        subnet_mask="255.255.255.0",
+        default_gateway="192.168.1.1",
+        start_up_duration=0
+    )
+    pc_1.power_on()
+
+    # Set up PC 2
+    pc_2 = Computer(
+        hostname="pc_2",
+        ip_address="192.168.1.12",
+        subnet_mask="255.255.255.0",
+        default_gateway="192.168.1.1",
+        start_up_duration=0
+    )
+    pc_2.power_on()
+    pc_2.software_manager.install(DatabaseService)
+    pc_2.software_manager.software["DatabaseService"].start() # start the postgres server
+
+    # Set up PC 3
+    pc_3 = Computer(
+        hostname="pc_3",
+        ip_address="192.168.1.13",
+        subnet_mask="255.255.255.0",
+        default_gateway="192.168.1.1",
+        start_up_duration=0
+    )
+    # Don't power on PC 3
+
+    # Set up the switch
+    switch = Switch(hostname="switch", start_up_duration=0)
+    switch.power_on()
+
+    # Connect devices
+    network.connect(router.network_interface[1], switch.network_interface[24])
+    network.connect(switch.network_interface[1], pc_1.network_interface[1])
+    network.connect(switch.network_interface[2], pc_2.network_interface[1])
+    network.connect(switch.network_interface[3], pc_3.network_interface[1])
+
+
+    pc_1_nmap: NMAP = pc_1.software_manager.software["NMAP"]
+
+
+Ping Scan
+^^^^^^^^^
+
+Perform a ping scan to find active hosts in the `192.168.1.0/24` subnet:
+
+.. code-block:: python
+   :caption: Ping Scan Code
+
+    active_hosts = pc_1_nmap.ping_scan(target_ip_address=IPv4Network("192.168.1.0/24"))
+
+.. code-block:: python
+   :caption: Ping Scan Return Value
+
+    [
+        IPv4Address('192.168.1.11'),
+        IPv4Address('192.168.1.12'),
+        IPv4Address('192.168.1.1')
+    ]
+
+.. code-block:: text
+   :caption: Ping Scan Output
+
+    +-------------------------+
+    |   pc_1 NMAP Ping Scan   |
+    +--------------+----------+
+    | IP Address   | Can Ping |
+    +--------------+----------+
+    | 192.168.1.1  | True     |
+    | 192.168.1.11 | True     |
+    | 192.168.1.12 | True     |
+    +--------------+----------+
+
+Horizontal Port Scan
+^^^^^^^^^^^^^^^^^^^^
+
+Perform a horizontal port scan on port 5432 across multiple IP addresses:
+
+.. code-block:: python
+   :caption: Horizontal Port Scan Code
+
+    horizontal_scan_results = pc_1_nmap.port_scan(
+        target_ip_address=[IPv4Address("192.168.1.12"), IPv4Address("192.168.1.13")],
+        target_port=Port(5432 )
+    )
+
+.. code-block:: python
+   :caption: Horizontal Port Scan Return Value
+
+   {
+      IPv4Address('192.168.1.12'): {
+         <IPProtocol.TCP: 'tcp'>: [
+            <Port.POSTGRES_SERVER: 5432>
+         ]
+      }
+   }
+
+.. code-block:: text
+   :caption: Horizontal Port Scan Output
+
+   +--------------------------------------------------+
+   |         pc_1 NMAP Port Scan (Horizontal)         |
+   +--------------+------+-----------------+----------+
+   | IP Address   | Port | Name            | Protocol |
+   +--------------+------+-----------------+----------+
+   | 192.168.1.12 | 5432 | POSTGRES_SERVER | TCP      |
+   +--------------+------+-----------------+----------+
+
+Vertical Post Scan
+^^^^^^^^^^^^^^^^^^
+
+Perform a vertical port scan on multiple ports on a single IP address:
+
+.. code-block:: python
+   :caption: Vertical Port Scan Code
+
+   vertical_scan_results = pc_1_nmap.port_scan(
+       target_ip_address=[IPv4Address("192.168.1.12")],
+       target_port=[Port(21), Port(22), Port(80), Port(443)]
+   )
+
+.. code-block:: python
+   :caption: Vertical Port Scan Return Value
+
+   {
+      IPv4Address('192.168.1.12'): {
+         <IPProtocol.TCP: 'tcp'>: [
+            <Port.FTP: 21>,
+            <Port.HTTP: 80>
+         ]
+      }
+   }
+
+.. code-block:: text
+   :caption: Vertical Port Scan Output
+
+   +---------------------------------------+
+   |     pc_1 NMAP Port Scan (Vertical)    |
+   +--------------+------+------+----------+
+   | IP Address   | Port | Name | Protocol |
+   +--------------+------+------+----------+
+   | 192.168.1.12 | 21   | FTP  | TCP      |
+   | 192.168.1.12 | 80   | HTTP | TCP      |
+   +--------------+------+------+----------+
+
+Box Scan
+^^^^^^^^
+
+Perform a box scan on multiple ports across multiple IP addresses:
+
+.. code-block:: python
+   :caption: Box Port Scan Code
+
+   # Power PC 3 on before performing the box scan
+   pc_3.power_on()
+
+
+   box_scan_results = pc_1_nmap.port_scan(
+       target_ip_address=[IPv4Address("192.168.1.12"), IPv4Address("192.168.1.13")],
+       target_port=[Port(21), Port(22), Port(80), Port(443)]
+   )
+
+.. code-block:: python
+   :caption: Box Port Scan Return Value
+
+   {
+      IPv4Address('192.168.1.13'): {
+         <IPProtocol.TCP: 'tcp'>: [
+            <Port.FTP: 21>,
+            <Port.HTTP: 80>
+         ]
+      },
+      IPv4Address('192.168.1.12'): {
+         <IPProtocol.TCP: 'tcp'>: [
+            <Port.FTP: 21>,
+            <Port.HTTP: 80>
+         ]
+      }
+   }
+
+.. code-block:: text
+   :caption: Box Port Scan Output
+
+   +---------------------------------------+
+   |       pc_1 NMAP Port Scan (Box)       |
+   +--------------+------+------+----------+
+   | IP Address   | Port | Name | Protocol |
+   +--------------+------+------+----------+
+   | 192.168.1.12 | 21   | FTP  | TCP      |
+   | 192.168.1.12 | 80   | HTTP | TCP      |
+   | 192.168.1.13 | 21   | FTP  | TCP      |
+   | 192.168.1.13 | 80   | HTTP | TCP      |
+   +--------------+------+------+----------+
+
+Full Box Scan
+^^^^^^^^^^^^^
+
+Perform a full box scan on all ports, over both TCP and UDP, on a whole subnet:
+
+.. code-block:: python
+   :caption: Box Port Scan Code
+
+   # Power PC 3 on before performing the full box scan
+   pc_3.power_on()
+
+
+   full_box_scan_results = pc_1_nmap.port_scan(
+       target_ip_address=IPv4Network("192.168.1.0/24"),
+   )
+
+.. code-block:: python
+   :caption: Box Port Scan Return Value
+
+   {
+      IPv4Address('192.168.1.11'): {
+         <IPProtocol.UDP: 'udp'>: [
+            <Port.ARP: 219>
+         ]
+      },
+      IPv4Address('192.168.1.1'): {
+         <IPProtocol.UDP: 'udp'>: [
+            <Port.ARP: 219>
+         ]
+      },
+      IPv4Address('192.168.1.12'): {
+         <IPProtocol.TCP: 'tcp'>: [
+            <Port.HTTP: 80>,
+            <Port.DNS: 53>,
+            <Port.POSTGRES_SERVER: 5432>,
+            <Port.FTP: 21>
+         ],
+         <IPProtocol.UDP: 'udp'>: [
+            <Port.NTP: 123>,
+            <Port.ARP: 219>
+         ]
+      },
+      IPv4Address('192.168.1.13'): {
+         <IPProtocol.TCP: 'tcp'>: [
+            <Port.HTTP: 80>,
+            <Port.DNS: 53>,
+            <Port.FTP: 21>
+         ],
+         <IPProtocol.UDP: 'udp'>: [
+            <Port.NTP: 123>,
+            <Port.ARP: 219>
+         ]
+      }
+   }
+
+.. code-block:: text
+   :caption: Box Port Scan Output
+
+   +--------------------------------------------------+
+   |          pc_1 NMAP Port Scan (Box)               |
+   +--------------+------+-----------------+----------+
+   | IP Address   | Port | Name            | Protocol |
+   +--------------+------+-----------------+----------+
+   | 192.168.1.1  | 219  | ARP             | UDP      |
+   | 192.168.1.11 | 219  | ARP             | UDP      |
+   | 192.168.1.12 | 21   | FTP             | TCP      |
+   | 192.168.1.12 | 53   | DNS             | TCP      |
+   | 192.168.1.12 | 80   | HTTP            | TCP      |
+   | 192.168.1.12 | 123  | NTP             | UDP      |
+   | 192.168.1.12 | 219  | ARP             | UDP      |
+   | 192.168.1.12 | 5432 | POSTGRES_SERVER | TCP      |
+   | 192.168.1.13 | 21   | FTP             | TCP      |
+   | 192.168.1.13 | 53   | DNS             | TCP      |
+   | 192.168.1.13 | 80   | HTTP            | TCP      |
+   | 192.168.1.13 | 123  | NTP             | UDP      |
+   | 192.168.1.13 | 219  | ARP             | UDP      |
+   +--------------+------+-----------------+----------+
+
+Configuration
+=============
+
+.. include:: ../common/common_configuration.rst
+
+.. |SOFTWARE_NAME| replace:: NMAP
+.. |SOFTWARE_NAME_BACKTICK| replace:: ``NMAP``

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

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

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

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
 
 .. _WebBrowser:
 
@@ -23,7 +23,7 @@ Usage
 =====
 
 - Install on a Node via the ``SoftwareManager`` to start the ``WebBrowser``.
-- Service runs on HTTP port 80 by default. (TODO: HTTPS)
+- Service runs on HTTP port 80 by default.
 - Execute sending an HTTP GET request with ``get_webpage``
 
 Implementation

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

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
 
 ``ref``
 =======
@@ -16,3 +16,12 @@ The type of software that should be added. To add |SOFTWARE_NAME| this must be |
 ===========
 
 The configuration options are the attributes that fall under the options for an application.
+
+
+
+``fix_duration``
+""""""""""""""""
+
+Optional. Default value is ``2``.
+
+The number of timesteps the |SOFTWARE_NAME| will remain in a ``FIXING`` state before going into a ``GOOD`` state.

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

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
 
 .. _Database Payload List:
 

docs/source/simulation_components/system/internal_frame_processing.rst

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

docs/source/simulation_components/system/list_of_applications.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
 
 .. toctree::
     :maxdepth: 1
@@ -8,7 +8,7 @@
 
     applications/*
 
-More info :py:mod:`primaite.game.game.APPLICATION_TYPES_MAPPING`
+More info :py:mod:`primaite.simulator.system.applications.application.Application`
 
 .. include:: list_of_system_applications.rst
 

docs/source/simulation_components/system/list_of_services.rst

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

docs/source/simulation_components/system/list_of_system_applications.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
 
 ``system applications``
 """""""""""""""""""""""

docs/source/simulation_components/system/list_of_system_services.rst

@@ -1,6 +1,6 @@
 .. only:: comment
 
-    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
 
 ``system services``
 """""""""""""""""""