Merged PR 478: merged 3.0.0 into main for git history alignment

merged 3.0.0 into main for git history alignment

Related work items: #2457, #2472, #2536, #2552, #2560, #2561, #2563, #2570, #2588, #2606, #2626, #2628, #2637, #2639

.azure/azure-benchmark-pipeline.yaml

@@ -0,0 +1,108 @@
+trigger:
+- release/*
+
+schedules:
+- cron: "0 2 * * 1-5"  # Run at 2 AM every weekday
+  displayName: "Weekday Schedule"
+  branches:
+    include:
+    - 'refs/heads/dev'
+variables:
+  VERSION: ''
+  MAJOR_VERSION: ''
+
+jobs:
+- job: PrimAITE_Benchmark
+  timeoutInMinutes: 360 # 6-hour maximum
+  pool:
+    name: 'Imaginary Yak Pool'
+  workspace:
+    clean: all
+
+  steps:
+  - checkout: self
+    persistCredentials: true
+
+  - script: |
+      python3.10 -m venv venv
+    displayName: 'Create venv'
+
+  - script: |
+      VERSION=$(cat src/primaite/VERSION | tr -d '\n')
+      if [[ "$(Build.SourceBranch)" == "refs/heads/dev" ]]; then
+        DATE=$(date +%Y%m%d)
+        echo "${VERSION}+dev.${DATE}" > src/primaite/VERSION
+      fi
+    displayName: 'Update VERSION file for Dev Benchmark'
+
+  - script: |
+      VERSION=$(cat src/primaite/VERSION | tr -d '\n')
+      MAJOR_VERSION=$(echo $VERSION | cut -d. -f1)
+      echo "##vso[task.setvariable variable=VERSION]$VERSION"
+      echo "##vso[task.setvariable variable=MAJOR_VERSION]$MAJOR_VERSION"
+    displayName: 'Set Version Variables'
+
+  - script: |
+      source venv/bin/activate
+      pip install --upgrade pip
+      pip install -e .[dev,rl]
+      primaite setup
+    displayName: 'Install Dependencies'
+
+  - script: |
+      set -e
+      source venv/bin/activate
+      cd benchmark
+      python primaite_benchmark.py
+      cd ..
+    displayName: 'Run Benchmarking Script'
+
+  - script: |
+      tar czf primaite_v$(VERSION)_benchmark.tar.gz benchmark/results/v$(MAJOR_VERSION)/v$(VERSION)
+    displayName: 'Prepare Artifacts for Publishing'
+
+  - task: PublishPipelineArtifact@1
+    inputs:
+      targetPath: primaite_v$(VERSION)_benchmark.tar.gz
+      artifactName: 'benchmark-zip-output'
+      publishLocation: 'pipeline'
+    displayName: 'Publish Benchmark Output zip as Artifact'
+
+  - script: |
+      git config --global user.email "oss@dstl.gov.uk"
+      git config --global user.name "Defence Science and Technology Laboratory UK"
+    workingDirectory: $(System.DefaultWorkingDirectory)
+    displayName: 'Configure Git'
+    condition: and(succeeded(), startsWith(variables['Build.SourceBranch'], 'refs/heads/release'))
+
+  - script: |
+      echo "Fetching all branches..."
+      git fetch --all --prune
+
+      echo "Stashing files..."
+      git stash push -u
+
+      echo "Resolving branch name..."
+      # Extracting just the branch name from the full ref path
+      branch_name=$(echo "$(Build.SourceBranch)" | sed 's|refs/heads/||')
+      echo "Branch Name: $branch_name"
+
+      echo "Checking out branch $branch_name..."
+      git checkout $branch_name
+
+      echo "Popping stash..."
+      git stash pop
+
+      echo "Adding benchmark results..."
+      git add benchmark/results/v$(MAJOR_VERSION)/v$(VERSION)/*
+
+      echo "Committing changes..."
+      git commit -m "Automated benchmark output commit for version $(VERSION) [skip ci]"
+
+      echo "Pushing to remote..."
+      git push origin $branch_name
+    displayName: 'Commit and Push Benchmark Results'
+    workingDirectory: $(System.DefaultWorkingDirectory)
+    env:
+      GIT_CREDENTIALS: $(System.AccessToken)
+    condition: and(succeeded(), startsWith(variables['Build.SourceBranch'], 'refs/heads/release'))

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

@@ -26,8 +26,12 @@ jobs:
     displayName: 'Install build dependencies'
 
   - script: |
-      pip install -e .[dev]
-    displayName: 'Install Yawning-Titan for docs autosummary'
+      pip install -e .[dev,rl]
+    displayName: 'Install PrimAITE for docs autosummary'
+
+  - script: |
+      apt-get install pandoc
+    displayName: 'Install Pandoc'
 
   - script: |
       primaite setup

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

@@ -6,45 +6,55 @@ trigger:
 - bugfix/*
 - release/*
 
+pr:
+  autoCancel: true
+  drafts: false
 parameters:
   # https://stackoverflow.com/a/70046417
   - name: matrix
     type: object
     default:
-    - job_name: 'UbuntuPython38'
-      py: '3.8'
-      img: 'ubuntu-latest'
-      every_time: false
-    - job_name: 'UbuntuPython310'
-      py: '3.10'
+    # - job_name: 'UbuntuPython38'
+    #   py: '3.8'
+    #   img: 'ubuntu-latest'
+    #   every_time: false
+    #   publish_coverage: false
+    - job_name: 'UbuntuPython311'
+      py: '3.11'
       img: 'ubuntu-latest'
       every_time: true
-    - job_name: 'WindowsPython38'
-      py: '3.8'
+      publish_coverage: true
+    # - job_name: 'WindowsPython38'
+    #   py: '3.8'
+    #   img: 'windows-latest'
+    #   every_time: false
+    #   publish_coverage: false
+    - job_name: 'WindowsPython311'
+      py: '3.11'
       img: 'windows-latest'
       every_time: false
-    - job_name: 'WindowsPython310'
-      py: '3.10'
-      img: 'windows-latest'
-      every_time: false
-    - job_name: 'MacOSPython38'
-      py: '3.8'
-      img: 'macOS-latest'
-      every_time: false
-    - job_name: 'MacOSPython310'
-      py: '3.10'
+      publish_coverage: false
+    # - job_name: 'MacOSPython38'
+    #   py: '3.8'
+    #   img: 'macOS-latest'
+    #   every_time: false
+    #   publish_coverage: false
+    - job_name: 'MacOSPython311'
+      py: '3.11'
       img: 'macOS-latest'
       every_time: false
+      publish_coverage: false
 
 stages:
   - stage: Test
     jobs:
     - ${{ each item in parameters.matrix }}:
       - job: ${{ item.job_name }}
+        timeoutInMinutes: 90
+        cancelTimeoutInMinutes: 1
         pool:
           vmImage: ${{ item.img }}
-
-        condition: or( eq(variables['Build.Reason'], 'PullRequest'), ${{ item.every_time }} )
+        condition: and(succeeded(), or( eq(variables['Build.Reason'], 'PullRequest'), ${{ item.every_time }} ))
 
         steps:
           - task: UsePythonVersion@0
@@ -72,12 +82,12 @@ stages:
 
           - script: |
               PRIMAITE_WHEEL=$(ls ./dist/primaite*.whl)
-              python -m pip install $PRIMAITE_WHEEL[dev]
+              python -m pip install $PRIMAITE_WHEEL[dev,rl]
             displayName: 'Install PrimAITE'
             condition: or(eq( variables['Agent.OS'], 'Linux' ), eq( variables['Agent.OS'], 'Darwin' ))
 
           - script: |
-              forfiles /p dist\ /m *.whl /c "cmd /c python -m pip install @file[dev]"
+              forfiles /p dist\ /m *.whl /c "cmd /c python -m pip install @file[dev,rl]"
             displayName: 'Install PrimAITE'
             condition: eq( variables['Agent.OS'], 'Windows_NT' )
 
@@ -85,6 +95,34 @@ stages:
               primaite setup
             displayName: 'Perform PrimAITE Setup'
 
+          - task: UseDotNet@2
+            displayName: 'Install dotnet dependencies'
+            inputs:
+              packageType: 'sdk'
+              version: '2.1.x'
+
           - script: |
-              pytest -n 4
-            displayName: 'Run tests'
+              coverage run -m --source=primaite pytest -v -o junit_family=xunit2 --junitxml=junit/test-results.xml --cov-fail-under=80
+              coverage xml -o coverage.xml -i
+              coverage html -d htmlcov -i
+            displayName: 'Run tests and code coverage'
+
+          - task: PublishTestResults@2
+            condition: succeededOrFailed()
+            inputs:
+              testRunner: JUnit
+              testResultsFiles: 'junit/**.xml'
+              testRunTitle: 'Publish test results'
+              failTaskOnFailedTests: true
+
+          - publish: $(System.DefaultWorkingDirectory)/htmlcov/
+            # publish the html report - so we can debug the coverage if needed
+            condition: ${{ item.publish_coverage }} # should only be run once
+            artifact: coverage_report
+
+          - task: PublishCodeCoverageResults@2
+            # publish the code coverage so it can be viewed in the run coverage page
+            condition: ${{ item.publish_coverage }} # should only be run once
+            inputs:
+              codeCoverageTool: Cobertura
+              summaryFileLocation: '$(System.DefaultWorkingDirectory)/**/coverage.xml'

.azuredevops/pull_request_template.md

@@ -5,8 +5,12 @@
 *How have you tested this (if applicable)?*
 
 ## Checklist
-- [ ] This PR is linked to a **work item**
-- [ ] I have performed **self-review** of the code
-- [ ] I have written **tests** for any new functionality added with this PR
-- [ ] I have updated the **documentation** if this PR changes or adds functionality
-- [ ] I have run **pre-commit** checks for code style
+- [ ] PR is linked to a **work item**
+- [ ] **acceptance criteria** of linked ticket are met
+- [ ] performed **self-review** of the code
+- [ ] written **tests** for any new functionality added with this PR
+- [ ] updated the **documentation** if this PR changes or adds functionality
+- [ ] written/updated **design docs** if this PR implements new functionality
+- [ ] updated the **change log**
+- [ ] ran **pre-commit** checks for code style
+- [ ] attended to any **TO-DOs** left in the code

.flake8

@@ -9,5 +9,12 @@ extend-ignore =
     E712
     D401
     F811
+    ANN002
+    ANN003
+    ANN101
+    ANN102
 exclude =
     docs/source/*
+    tests/*
+suppress-none-returning=True
+suppress-dummy-args=True

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,41 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: "[BUG] - <bug title goes here>"
+labels: bug
+assignees: ''
+
+---
+
+### Describe the bug:
+
+A clear and concise description of what the bug is.
+
+### To Reproduce:
+
+Steps to reproduce the behaviour:
+
+1. Import '...'
+2. Instantiate '....'
+3. Pass to '....'
+4. Run '....'
+5. See error
+
+### Expected behaviour
+
+A clear and concise description of what you expected to happen.
+
+### Screenshots/Outputs
+
+If applicable, add screenshots to help explain your problem.
+
+### Environment (please complete the following information)
+
+ - **OS:** [e.g. Ubuntu 22.04]
+ - **Python:** [e.g. 3.10.11]
+ - **PrimAITE Version:** [e.g. v2.0.0]
+ - **Software:** [e.g. cli, Jupyter, PyCharm, VSCode etc.]
+
+### Additional context
+
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,24 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: "[REQUEST] - <request title goes here>"
+labels: feature_request
+assignees: ''
+
+---
+
+### Is your feature request related to a problem?
+
+If so, please give a concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+### Describe the solution you'd like:
+
+A clear and concise description of what you want to happen.
+
+### Describe alternatives you've considered:
+
+A clear and concise description of any alternative solutions or features you've considered.
+
+### Additional context:
+
+Add any other context or screenshots about the feature request here.

.github/workflows/build-sphinx.yml

@@ -0,0 +1,60 @@
+name: build-sphinx-to-github-pages
+
+env:
+  GITHUB_ACTOR: Autonomous-Resilient-Cyber-Defence
+  GITHUB_REPOSITORY: Autonomous-Resilient-Cyber-Defence/PrimAITE
+  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN}}
+
+on:
+  push:
+    branches: [main]
+
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10"]
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install python dev
+        run: |
+          set -x
+          sudo apt-get update
+          sudo add-apt-repository ppa:deadsnakes/ppa -y
+          sudo apt install python${{ matrix.python-version}}-dev -y
+
+      - name: Install Git
+        run: |
+          set -x
+          sudo apt-get install -y git
+        shell: bash
+
+      - name: Set pip, wheel, setuptools versions
+        run: |
+          python -m pip install --upgrade pip==23.0.1
+          pip install wheel==0.38.4 --upgrade
+          pip install setuptools==66 --upgrade
+          pip install build
+
+      - name: Install PrimAITE for docs autosummary
+        run: |
+          set -x
+          python -m pip install -e .[dev,rl]
+
+      - name: Run build script for Sphinx pages
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+        run: |
+          set -x
+          bash $PWD/docs/build-sphinx-docs-to-github-pages.sh

.github/workflows/python-package.yml

@@ -0,0 +1,66 @@
+name: Python package
+
+on:
+  push:
+    branches:
+      - main
+      - dev
+      - dev-gui
+      - 'release/**'
+  pull_request:
+    branches:
+      - main
+      - dev
+      - dev-gui
+      - 'release/**'
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10"]
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install python dev
+        run: |
+          sudo apt update
+          sudo add-apt-repository ppa:deadsnakes/ppa -y
+          sudo apt install python${{ matrix.python-version}}-dev -y
+
+      - name: Install Build Dependencies
+        run: |
+          python -m pip install --upgrade pip==23.0.1
+          pip install wheel==0.38.4 --upgrade
+          pip install setuptools==66 --upgrade
+          pip install build
+
+      - name: Build PrimAITE
+        run: |
+          python -m build
+
+      - name: Install PrimAITE
+        run: |
+          PRIMAITE_WHEEL=$(ls ./dist/primaite*.whl)
+          python -m pip install $PRIMAITE_WHEEL[dev,rl]
+
+      - name: Perform PrimAITE Setup
+        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

@@ -37,6 +37,7 @@ pip-log.txt
 pip-delete-this-directory.txt
 
 # Unit test / coverage reports
+junit/
 htmlcov/
 .tox/
 .nox/
@@ -81,6 +82,10 @@ target/
 
 # Jupyter Notebook
 .ipynb_checkpoints
+PPO_UC2/
+# ignore everything but the executed notebooks rst in the docs/source/notebooks directory
+!docs/source/notebooks/executed_notebooks.rst
+docs/source/notebooks/**/*
 
 # IPython
 profile_default/
@@ -144,9 +149,22 @@ cython_debug/
 # IDE
 .idea/
 docs/source/primaite-dependencies.rst
+.vscode/
 
 # outputs
 src/primaite/outputs/
+simulation_output/
+sessions/
+PrimAITE-PPO-example-agent.zip
 
 # benchmark session outputs
 benchmark/output
+# src/primaite/notebooks/scratch.ipynb
+src/primaite/notebooks/scratch.py
+sandbox.py
+sandbox/
+sandbox.ipynb
+
+# benchmarking
+**/benchmark/sessions/
+**/benchmark/output/

.pre-commit-config.yaml

@@ -3,10 +3,11 @@ repos:
     rev: v4.4.0
     hooks:
       - id: check-yaml
+        exclude: scenario_with_placeholders/
       - id: end-of-file-fixer
       - id: trailing-whitespace
       - id: check-added-large-files
-        args: ['--maxkb=1000']
+        args: ['--maxkb=5000']
       - id: mixed-line-ending
       - id: requirements-txt-fixer
   - repo: http://github.com/psf/black
@@ -27,3 +28,8 @@ repos:
       - id: flake8
         additional_dependencies:
           - flake8-docstrings
+          - flake8-annotations
+  - repo: https://github.com/kynan/nbstripout
+    rev: 0.7.1
+    hooks:
+      - id: nbstripout

CHANGELOG.md

@@ -5,7 +5,157 @@ 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/),
 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'.
+
+
+### 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.
+
+### 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
+
+### 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.
 
 ## [2.0.0] - 2023-07-26
 

CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# How to contribute to PrimAITE?
+
+
+### **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**
+
+
+### **Do you have a solution to fix the bug?**
+
+* [Fork the repository](https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE/fork).
+* Install the pre-commit hook with `pre-commit install`.
+* Implement the bug fix.
+* 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.
+
+### **Did you fix whitespace, format code, or make a purely cosmetic patch?**
+
+Changes that are cosmetic in nature and do not add anything substantial to the stability, functionality, or testability of PrimAITE will generally not be accepted.
+
+### **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).
+* 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?**
+
+Ask any question about how to use PrimAITE in our discussions section.
+
+### **Do you want to contribute to the PrimAITE documentation?**
+
+Please follow the "Do you intend to add a new feature or change an existing one?" section above and tag your feature request issue and pull request with the documentation tag.
+
+Thank you from the PrimAITE dev team! 🙌

MANIFEST.in

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

README.md

@@ -1,50 +1,161 @@
 # PrimAITE
 
+![image](./PrimAITE_logo_transparent.png)
+
+The ARCD Primary-level AI Training Environment (**PrimAITE**) provides an effective simulation capability for the purposes of training and evaluating AI in a cyber-defensive role. It incorporates the functionality required of a primary-level ARCD environment, which includes:
+
+- The ability to model a relevant platform / system context;
+
+- The ability to model key characteristics of a platform / system by representing connections, IP addresses, ports, traffic loading, operating systems and services;
+
+- Operates at machine-speed to enable fast training cycles.
+
+PrimAITE presents the following features:
+
+- Highly configurable (via YAML files) to provide the means to model a variety of platform / system laydowns and adversarial attack scenarios;
+
+- A Reinforcement Learning (RL) reward function based on (a) the ability to counter the specific modelled adversarial cyber-attack, and (b) the ability to ensure success;
+
+- Provision of logging to support AI evaluation and metrics gathering;
+
+- Realistic network traffic simulation, including address and sending packets via internet protocols like TCP, UDP, ICMP, and others
+
+- Routers with traffic routing and firewall capabilities
+
+- Support for multiple agents, each having their own customisable observation space, action space, and reward function definition, and either deterministic or RL-directed behaviour
+
 ## Getting Started with PrimAITE
 
-### Pre-Requisites
-
-In order to get **PrimAITE** installed, you will need to have the following installed:
-
-- `python3.8+`
-- `python3-pip`
-- `virtualenv`
-
+### 💫 Installation
 **PrimAITE** is designed to be OS-agnostic, and thus should work on most variations/distros of Linux, Windows, and MacOS.
+Currently, the PrimAITE wheel can only be installed from GitHub. This may change in the future with release to PyPi.
 
-### Installation from source
-#### 1. Navigate to the PrimAITE folder and create a new python virtual environment (venv)
+#### Windows (PowerShell)
 
-```unix
-python3 -m venv <name_of_venv>
+**Prerequisites:**
+* Manual install of Python >= 3.8 < 3.12
+
+**Install:**
+
+``` powershell
+mkdir ~\primaite
+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]
+primaite setup
 ```
 
-#### 2. Activate the venv
+
+#### Unix
+
+**Prerequisites:**
+* Manual install of Python >= 3.8 < 3.12
+
+``` bash
+sudo add-apt-repository ppa:deadsnakes/ppa
+sudo apt install python3.10
+sudo apt-get install python3-pip
+sudo apt-get install python3-venv
+```
+**Install:**
+
+``` bash
+mkdir ~/primaite
+cd ~/primaite
+python3 -m venv .venv
+source .venv/bin/activate
+pip install primaite-3.0.0-py3-none-any.whl[rl]
+primaite setup
+```
+
+
+
+### Developer Install from Source
+To make your own changes to PrimAITE, perform the install from source (developer install)
+
+#### 1. Clone the PrimAITE repository
+``` unix
+git clone git@github.com:Autonomous-Resilient-Cyber-Defence/PrimAITE.git
+```
+
+#### 2. CD into the repo directory
+``` unix
+cd PrimAITE
+```
+#### 3. Create a new python virtual environment (venv)
+
+```unix
+python3 -m venv venv
+```
+
+#### 4. Activate the venv
 
 ##### Unix
 ```bash
-source <name_of_venv>/bin/activate
+source venv/bin/activate
 ```
 
-##### Windows
+##### Windows (Powershell)
 ```powershell
-.\<name_of_venv>\Scripts\activate
+.\venv\Scripts\activate
 ```
 
-#### 3. Install `primaite` into the venv along with all of it's dependencies
+#### 5. Install `primaite` with the dev extra into the venv along with all of it's dependencies
 
 ```bash
-python3 -m pip install -e .
+python3 -m pip install -e .[dev,rl]
 ```
 
-### Development Installation
-To install the development dependencies, postfix the command in step 3 above with the `[dev]` extra. Example:
+#### 6. Perform the PrimAITE setup:
 
 ```bash
-python3 -m pip install -e .[dev]
+primaite setup
 ```
 
-## Building documentation
+#### Note
+*It is possible to install PrimAITE without Ray RLLib, StableBaselines3, or any deep learning libraries by omitting the `rl` flag in the pip install command.*
+
+### Running PrimAITE
+
+Use the provided jupyter notebooks as a starting point to try running PrimAITE. They are automatically copied to your PrimAITE notebook folder when you run `primaite setup`.
+
+#### 1. Activate the virtual environment
+
+##### Windows (Powershell)
+```powershell
+.\venv\Scripts\activate
+```
+
+##### Unix
+```bash
+source venv/bin/activate
+```
+
+#### 2. Open jupyter notebook
+
+```bash
+python -m jupyter notebook
+```
+Then, click the URL provided by the jupyter command to open the jupyter application in your browser. You can also open notebooks in your IDE if supported.
+
+## 📚 Documentation
+
+### Pre requisites
+
+Building the documentation requires the installation of Pandoc
+
+##### Unix
+```bash
+sudo apt-get install pandoc
+```
+
+##### Other operating systems
+Follow the steps in https://pandoc.org/installing.html
+
+### Building the documentation
+
 The PrimAITE documentation can be built with the following commands:
 
 ##### Unix
@@ -53,12 +164,12 @@ cd docs
 make html
 ```
 
-##### Windows
+##### Windows (Powershell)
 ```powershell
 cd docs
 .\make.bat html
 ```
 
-This will build the documentation as a collection of HTML files which uses the Read The Docs sphinx theme. Other build
-options are available but may require additional dependencies such as LaTeX and PDF. Please refer to the Sphinx documentation
-for your specific output requirements.
+
+## Example notebooks
+Check out the example notebooks to learn more about how PrimAITE works and how you can use it to train agents. They are automatically copied to your primaite installation directory when you run `primaite setup`.

benchmark/benchmark.py

@@ -0,0 +1,22 @@
+# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+from typing import Any, Dict, Optional, Tuple
+
+from gymnasium.core import ObsType
+
+from primaite.session.environment import PrimaiteGymEnv
+
+
+class BenchmarkPrimaiteGymEnv(PrimaiteGymEnv):
+    """
+    Class that extends the PrimaiteGymEnv.
+
+    The reset method is extended so that the average rewards per episode are recorded.
+    """
+
+    total_time_steps: int = 0
+
+    def reset(self, seed: Optional[int] = None) -> Tuple[ObsType, Dict[str, Any]]:
+        """Overrides the PrimAITEGymEnv reset so that the total timesteps is saved."""
+        self.total_time_steps += self.game.step_counter
+
+        return super().reset(seed=seed)

benchmark/primaite_benchmark.py

@@ -1,206 +1,93 @@
-# © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
 import json
-import platform
 import shutil
-import sys
 from datetime import datetime
 from pathlib import Path
-from typing import Any, Dict, Final, Optional, Tuple, Union
-from unittest.mock import patch
+from typing import Any, Dict, Final, Tuple
 
-import GPUtil
-import plotly.graph_objects as go
-import polars as pl
-import psutil
-import yaml
-from plotly.graph_objs import Figure
-from pylatex import Command, Document
-from pylatex import Figure as LatexFigure
-from pylatex import Section, Subsection, Tabular
-from pylatex.utils import bold
+from report import build_benchmark_md_report
+from stable_baselines3 import PPO
 
 import primaite
-from primaite.config.lay_down_config import data_manipulation_config_path
-from primaite.data_viz.session_plots import get_plotly_config
-from primaite.environment.primaite_env import Primaite
-from primaite.primaite_session import PrimaiteSession
+from benchmark import BenchmarkPrimaiteGymEnv
+from primaite.config.load import data_manipulation_config_path
 
 _LOGGER = primaite.getLogger(__name__)
 
+_MAJOR_V = primaite.__version__.split(".")[0]
+
 _BENCHMARK_ROOT = Path(__file__).parent
-_RESULTS_ROOT: Final[Path] = _BENCHMARK_ROOT / "results"
-_RESULTS_ROOT.mkdir(exist_ok=True, parents=True)
+_RESULTS_ROOT: Final[Path] = _BENCHMARK_ROOT / "results" / f"v{_MAJOR_V}"
+_VERSION_ROOT: Final[Path] = _RESULTS_ROOT / f"v{primaite.__version__}"
+_SESSION_METADATA_ROOT: Final[Path] = _VERSION_ROOT / "session_metadata"
 
-_OUTPUT_ROOT: Final[Path] = _BENCHMARK_ROOT / "output"
-# Clear and recreate the output directory
-if _OUTPUT_ROOT.exists():
-    shutil.rmtree(_OUTPUT_ROOT)
-_OUTPUT_ROOT.mkdir()
-
-_TRAINING_CONFIG_PATH = _BENCHMARK_ROOT / "config" / "benchmark_training_config.yaml"
-_LAY_DOWN_CONFIG_PATH = data_manipulation_config_path()
+_SESSION_METADATA_ROOT.mkdir(parents=True, exist_ok=True)
 
 
-def get_size(size_bytes: int):
-    """
-    Scale bytes to its proper format.
+class BenchmarkSession:
+    """Benchmark Session class."""
 
-    e.g:
-        1253656 => '1.20MB'
-        1253656678 => '1.17GB'
+    gym_env: BenchmarkPrimaiteGymEnv
+    """Gym environment used by the session to train."""
 
-    :
-    """
-    factor = 1024
-    for unit in ["", "K", "M", "G", "T", "P"]:
-        if size_bytes < factor:
-            return f"{size_bytes:.2f}{unit}B"
-        size_bytes /= factor
+    num_episodes: int
+    """Number of episodes to run the training session."""
 
+    episode_len: int
+    """The number of steps per episode."""
 
-def _get_system_info() -> Dict:
-    """Builds and returns a dict containing system info."""
-    uname = platform.uname()
-    cpu_freq = psutil.cpu_freq()
-    virtual_mem = psutil.virtual_memory()
-    swap_mem = psutil.swap_memory()
-    gpus = GPUtil.getGPUs()
-    return {
-        "System": {
-            "OS": uname.system,
-            "OS Version": uname.version,
-            "Machine": uname.machine,
-            "Processor": uname.processor,
-        },
-        "CPU": {
-            "Physical Cores": psutil.cpu_count(logical=False),
-            "Total Cores": psutil.cpu_count(logical=True),
-            "Max Frequency": f"{cpu_freq.max:.2f}Mhz",
-        },
-        "Memory": {"Total": get_size(virtual_mem.total), "Swap Total": get_size(swap_mem.total)},
-        "GPU": [{"Name": gpu.name, "Total Memory": f"{gpu.memoryTotal}MB"} for gpu in gpus],
-    }
+    total_steps: int
+    """Number of steps to run the training session."""
 
+    batch_size: int
+    """Number of steps for each episode."""
 
-def _build_benchmark_latex_report(
-    benchmark_metadata_dict: Dict, this_version_plot_path: Path, all_version_plot_path: Path
-):
-    geometry_options = {"tmargin": "2.5cm", "rmargin": "2.5cm", "bmargin": "2.5cm", "lmargin": "2.5cm"}
-    data = benchmark_metadata_dict
-    primaite_version = data["primaite_version"]
+    learning_rate: float
+    """Learning rate for the model."""
 
-    # Create a new document
-    doc = Document("report", geometry_options=geometry_options)
-    # Title
-    doc.preamble.append(Command("title", f"PrimAITE {primaite_version} Learning Benchmark"))
-    doc.preamble.append(Command("author", "PrimAITE Dev Team"))
-    doc.preamble.append(Command("date", datetime.now().date()))
-    doc.append(Command("maketitle"))
+    start_time: datetime
+    """Start time for the session."""
 
-    sessions = data["total_sessions"]
-    episodes = data["training_config"]["num_train_episodes"]
-    steps = data["training_config"]["num_train_steps"]
-
-    # Body
-    with doc.create(Section("Introduction")):
-        doc.append(
-            f"PrimAITE v{primaite_version} was benchmarked automatically upon release. Learning rate metrics "
-            f"were captured to be referenced during system-level testing and user acceptance testing (UAT)."
-        )
-        doc.append(
-            f"\nThe benchmarking process consists of running {sessions} training session using the same "
-            f"training and lay down config files. Each session trains an agent for {episodes} episodes, "
-            f"with each episode consisting of {steps} steps."
-        )
-        doc.append(
-            f"\nThe mean reward per episode from each session is captured. This is then used to calculate a "
-            f"combined average reward per episode from the {sessions} individual sessions for smoothing. "
-            f"Finally, a 25-widow rolling average of the combined average reward per session is calculated for "
-            f"further smoothing."
-        )
-
-    with doc.create(Section("System Information")):
-        with doc.create(Subsection("Python")):
-            with doc.create(Tabular("|l|l|")) as table:
-                table.add_hline()
-                table.add_row((bold("Version"), sys.version))
-                table.add_hline()
-        for section, section_data in data["system_info"].items():
-            if section_data:
-                with doc.create(Subsection(section)):
-                    if isinstance(section_data, dict):
-                        with doc.create(Tabular("|l|l|")) as table:
-                            table.add_hline()
-                            for key, value in section_data.items():
-                                table.add_row((bold(key), value))
-                                table.add_hline()
-                    elif isinstance(section_data, list):
-                        headers = section_data[0].keys()
-                        tabs_str = "|".join(["l" for _ in range(len(headers))])
-                        tabs_str = f"|{tabs_str}|"
-                        with doc.create(Tabular(tabs_str)) as table:
-                            table.add_hline()
-                            table.add_row([bold(h) for h in headers])
-                            table.add_hline()
-                            for item in section_data:
-                                table.add_row(item.values())
-                                table.add_hline()
-
-    headers_map = {
-        "total_sessions": "Total Sessions",
-        "total_episodes": "Total Episodes",
-        "total_time_steps": "Total Steps",
-        "av_s_per_session": "Av Session Duration (s)",
-        "av_s_per_step": "Av Step Duration (s)",
-        "av_s_per_100_steps_10_nodes": "Av Duration per 100 Steps per 10 Nodes (s)",
-    }
-    with doc.create(Section("Stats")):
-        with doc.create(Subsection("Benchmark Results")):
-            with doc.create(Tabular("|l|l|")) as table:
-                table.add_hline()
-                for section, header in headers_map.items():
-                    if section.startswith("av_"):
-                        table.add_row((bold(header), f"{data[section]:.4f}"))
-                    else:
-                        table.add_row((bold(header), data[section]))
-                    table.add_hline()
-
-    with doc.create(Section("Graphs")):
-        with doc.create(Subsection(f"PrimAITE {primaite_version} Learning Benchmark Plot")):
-            with doc.create(LatexFigure(position="h!")) as pic:
-                pic.add_image(str(this_version_plot_path))
-                pic.add_caption(f"PrimAITE {primaite_version} Learning Benchmark Plot")
-
-        with doc.create(Subsection("PrimAITE All Versions Learning Benchmark Plot")):
-            with doc.create(LatexFigure(position="h!")) as pic:
-                pic.add_image(str(all_version_plot_path))
-                pic.add_caption("PrimAITE All Versions Learning Benchmark Plot")
-
-    doc.generate_pdf(str(this_version_plot_path).replace(".png", ""), clean_tex=True)
-
-
-class BenchmarkPrimaiteSession(PrimaiteSession):
-    """A benchmarking primaite session."""
+    end_time: datetime
+    """End time for the session."""
 
     def __init__(
         self,
-        training_config_path: Union[str, Path],
-        lay_down_config_path: Union[str, Path],
+        gym_env: BenchmarkPrimaiteGymEnv,
+        episode_len: int,
+        num_episodes: int,
+        n_steps: int,
+        batch_size: int,
+        learning_rate: float,
     ):
-        super().__init__(training_config_path, lay_down_config_path)
-        self.setup()
+        """Initialise the BenchmarkSession."""
+        self.gym_env = gym_env
+        self.episode_len = episode_len
+        self.n_steps = n_steps
+        self.num_episodes = num_episodes
+        self.total_steps = self.num_episodes * self.episode_len
+        self.batch_size = batch_size
+        self.learning_rate = learning_rate
 
-    @property
-    def env(self) -> Primaite:
-        """Direct access to the env for ease of testing."""
-        return self._agent_session._env  # noqa
+    def train(self):
+        """Run the training session."""
+        # start timer for session
+        self.start_time = datetime.now()
+        model = PPO(
+            policy="MlpPolicy",
+            env=self.gym_env,
+            learning_rate=self.learning_rate,
+            n_steps=self.n_steps,
+            batch_size=self.batch_size,
+            verbose=0,
+            tensorboard_log="./PPO_UC2/",
+        )
+        model.learn(total_timesteps=self.total_steps)
 
-    def __enter__(self):
-        return self
+        # end timer for session
+        self.end_time = datetime.now()
 
-    def __exit__(self, type, value, tb):
-        shutil.rmtree(self.session_path)
-        _LOGGER.debug(f"Deleted benchmark session directory: {self.session_path}")
+        self.session_metadata = self.generate_learn_metadata_dict()
 
     def _learn_benchmark_durations(self) -> Tuple[float, float, float]:
         """
@@ -214,235 +101,99 @@ class BenchmarkPrimaiteSession(PrimaiteSession):
         :return: The learning benchmark durations as a Tuple of three floats:
             Tuple[total_s, s_per_step, s_per_100_steps_10_nodes].
         """
-        data = self.metadata_file_as_dict()
-        start_dt = datetime.fromisoformat(data["start_datetime"])
-        end_dt = datetime.fromisoformat(data["end_datetime"])
-        delta = end_dt - start_dt
+        delta = self.end_time - self.start_time
         total_s = delta.total_seconds()
 
-        total_steps = data["learning"]["total_time_steps"]
+        total_steps = self.batch_size * self.num_episodes
         s_per_step = total_s / total_steps
 
-        num_nodes = self.env.num_nodes
+        num_nodes = len(self.gym_env.game.simulation.network.nodes)
         num_intervals = total_steps / 100
         av_interval_time = total_s / num_intervals
         s_per_100_steps_10_nodes = av_interval_time / (num_nodes / 10)
 
         return total_s, s_per_step, s_per_100_steps_10_nodes
 
-    def learn_metadata_dict(self) -> Dict[str, Any]:
+    def generate_learn_metadata_dict(self) -> Dict[str, Any]:
         """Metadata specific to the learning session."""
         total_s, s_per_step, s_per_100_steps_10_nodes = self._learn_benchmark_durations()
+        self.gym_env.total_reward_per_episode.pop(0)  # remove episode 0
         return {
-            "total_episodes": self.env.actual_episode_count,
-            "total_time_steps": self.env.total_step_count,
+            "total_episodes": self.gym_env.episode_counter,
+            "total_time_steps": self.gym_env.total_time_steps,
             "total_s": total_s,
             "s_per_step": s_per_step,
             "s_per_100_steps_10_nodes": s_per_100_steps_10_nodes,
-            "av_reward_per_episode": self.learn_av_reward_per_episode_dict(),
+            "total_reward_per_episode": self.gym_env.total_reward_per_episode,
         }
 
 
-def _get_benchmark_session_path(session_timestamp: datetime) -> Path:
-    return _OUTPUT_ROOT / session_timestamp.strftime("%Y-%m-%d_%H-%M-%S")
-
-
-def _get_benchmark_primaite_session() -> BenchmarkPrimaiteSession:
-    with patch("primaite.agents.agent_abc.get_session_path", _get_benchmark_session_path) as mck:
-        mck.session_timestamp = datetime.now()
-        return BenchmarkPrimaiteSession(_TRAINING_CONFIG_PATH, _LAY_DOWN_CONFIG_PATH)
-
-
-def _build_benchmark_results_dict(start_datetime: datetime, metadata_dict: Dict) -> dict:
-    n = len(metadata_dict)
-    with open(_TRAINING_CONFIG_PATH, "r") as file:
-        training_config_dict = yaml.safe_load(file)
-    with open(_LAY_DOWN_CONFIG_PATH, "r") as file:
-        lay_down_config_dict = yaml.safe_load(file)
-    averaged_data = {
-        "start_timestamp": start_datetime.isoformat(),
-        "end_datetime": datetime.now().isoformat(),
-        "primaite_version": primaite.__version__,
-        "system_info": _get_system_info(),
-        "total_sessions": n,
-        "total_episodes": sum(d["total_episodes"] for d in metadata_dict.values()),
-        "total_time_steps": sum(d["total_time_steps"] for d in metadata_dict.values()),
-        "av_s_per_session": sum(d["total_s"] for d in metadata_dict.values()) / n,
-        "av_s_per_step": sum(d["s_per_step"] for d in metadata_dict.values()) / n,
-        "av_s_per_100_steps_10_nodes": sum(d["s_per_100_steps_10_nodes"] for d in metadata_dict.values()) / n,
-        "combined_av_reward_per_episode": {},
-        "session_av_reward_per_episode": {k: v["av_reward_per_episode"] for k, v in metadata_dict.items()},
-        "training_config": training_config_dict,
-        "lay_down_config": lay_down_config_dict,
-    }
-
-    episodes = metadata_dict[1]["av_reward_per_episode"].keys()
-
-    for episode in episodes:
-        combined_av_reward = sum(metadata_dict[k]["av_reward_per_episode"][episode] for k in metadata_dict.keys()) / n
-        averaged_data["combined_av_reward_per_episode"][episode] = combined_av_reward
-
-    return averaged_data
-
-
-def _get_df_from_episode_av_reward_dict(data: Dict):
-    data: Dict = {"episode": data.keys(), "av_reward": data.values()}
-
-    return (
-        pl.from_dict(data)
-        .with_columns(rolling_mean=pl.col("av_reward").rolling_mean(window_size=25))
-        .rename({"rolling_mean": "rolling_av_reward"})
-    )
-
-
-def _plot_benchmark_metadata(
-    benchmark_metadata_dict: Dict,
-    title: Optional[str] = None,
-    subtitle: Optional[str] = None,
-) -> Figure:
-    if title:
-        if subtitle:
-            title = f"{title} <br>{subtitle}</sup>"
-    else:
-        if subtitle:
-            title = subtitle
-
-    config = get_plotly_config()
-    layout = go.Layout(
-        autosize=config["size"]["auto_size"],
-        width=config["size"]["width"],
-        height=config["size"]["height"],
-    )
-    # Create the line graph with a colored line
-    fig = go.Figure(layout=layout)
-    fig.update_layout(template=config["template"])
-
-    for session, av_reward_dict in benchmark_metadata_dict["session_av_reward_per_episode"].items():
-        df = _get_df_from_episode_av_reward_dict(av_reward_dict)
-        fig.add_trace(
-            go.Scatter(
-                x=df["episode"],
-                y=df["av_reward"],
-                mode="lines",
-                name=f"Session {session}",
-                opacity=0.25,
-                line={"color": "#a6a6a6"},
-            )
-        )
-
-    df = _get_df_from_episode_av_reward_dict(benchmark_metadata_dict["combined_av_reward_per_episode"])
-    fig.add_trace(
-        go.Scatter(
-            x=df["episode"], y=df["av_reward"], mode="lines", name="Combined Session Av", line={"color": "#FF0000"}
-        )
-    )
-
-    fig.add_trace(
-        go.Scatter(
-            x=df["episode"],
-            y=df["rolling_av_reward"],
-            mode="lines",
-            name="Rolling Av (Combined Session Av)",
-            line={"color": "#4CBB17"},
-        )
-    )
-
-    # Set the layout of the graph
-    fig.update_layout(
-        xaxis={
-            "title": "Episode",
-            "type": "linear",
-        },
-        yaxis={"title": "Average Reward"},
-        title=title,
-    )
-
-    return fig
-
-
-def _plot_all_benchmarks_combined_session_av():
+def _get_benchmark_primaite_environment() -> BenchmarkPrimaiteGymEnv:
     """
-    Plot the Benchmark results for each released version of PrimAITE.
+    Create an instance of the BenchmarkPrimaiteGymEnv.
 
-    Does this by iterating over the ``benchmark/results`` directory and
-    extracting the benchmark metadata json for each version that has been
-    benchmarked. The combined_av_reward_per_episode is extracted from each,
-    converted into a polars dataframe, and plotted as a scatter line in plotly.
+    This environment will be used to train the agents on.
     """
-    title = "PrimAITE Versions Learning Benchmark"
-    subtitle = "Rolling Av (Combined Session Av)"
-    if title:
-        if subtitle:
-            title = f"{title} <br>{subtitle}</sup>"
-    else:
-        if subtitle:
-            title = subtitle
-    config = get_plotly_config()
-    layout = go.Layout(
-        autosize=config["size"]["auto_size"],
-        width=config["size"]["width"],
-        height=config["size"]["height"],
-    )
-    # Create the line graph with a colored line
-    fig = go.Figure(layout=layout)
-    fig.update_layout(template=config["template"])
-
-    for dir in _RESULTS_ROOT.iterdir():
-        if dir.is_dir():
-            metadata_file = dir / f"{dir.name}_benchmark_metadata.json"
-            with open(metadata_file, "r") as file:
-                metadata_dict = json.load(file)
-            df = _get_df_from_episode_av_reward_dict(metadata_dict["combined_av_reward_per_episode"])
-
-            fig.add_trace(go.Scatter(x=df["episode"], y=df["rolling_av_reward"], mode="lines", name=dir.name))
-
-    # Set the layout of the graph
-    fig.update_layout(
-        xaxis={
-            "title": "Episode",
-            "type": "linear",
-        },
-        yaxis={"title": "Average Reward"},
-        title=title,
-    )
-    fig["data"][0]["showlegend"] = True
-
-    return fig
+    env = BenchmarkPrimaiteGymEnv(env_config=data_manipulation_config_path())
+    return env
 
 
-def run():
+def _prepare_session_directory():
+    """Prepare the session directory so that it is easier to clean up after the benchmarking is done."""
+    # override session path
+    session_path = _BENCHMARK_ROOT / "sessions"
+
+    if session_path.is_dir():
+        shutil.rmtree(session_path)
+
+    primaite.PRIMAITE_PATHS.user_sessions_path = session_path
+    primaite.PRIMAITE_PATHS.user_sessions_path.mkdir(exist_ok=True, parents=True)
+
+
+def run(
+    number_of_sessions: int = 5,
+    num_episodes: int = 1000,
+    episode_len: int = 128,
+    n_steps: int = 1280,
+    batch_size: int = 32,
+    learning_rate: float = 3e-4,
+) -> None:
     """Run the PrimAITE benchmark."""
-    start_datetime = datetime.now()
-    av_reward_per_episode_dicts = {}
-    for i in range(1, 11):
+    benchmark_start_time = datetime.now()
+
+    session_metadata_dict = {}
+
+    _prepare_session_directory()
+
+    # run training
+    for i in range(1, number_of_sessions + 1):
         print(f"Starting Benchmark Session: {i}")
-        with _get_benchmark_primaite_session() as session:
-            session.learn()
-            av_reward_per_episode_dicts[i] = session.learn_metadata_dict()
 
-    benchmark_metadata = _build_benchmark_results_dict(
-        start_datetime=start_datetime, metadata_dict=av_reward_per_episode_dicts
+        with _get_benchmark_primaite_environment() as gym_env:
+            session = BenchmarkSession(
+                gym_env=gym_env,
+                num_episodes=num_episodes,
+                n_steps=n_steps,
+                episode_len=episode_len,
+                batch_size=batch_size,
+                learning_rate=learning_rate,
             )
-    v_str = f"v{primaite.__version__}"
+            session.train()
 
-    version_result_dir = _RESULTS_ROOT / v_str
-    if version_result_dir.exists():
-        shutil.rmtree(version_result_dir)
-    version_result_dir.mkdir(exist_ok=True, parents=True)
+            # Dump the session metadata so that we're not holding it in memory as it's large
+            with open(_SESSION_METADATA_ROOT / f"{i}.json", "w") as file:
+                json.dump(session.session_metadata, file, indent=4)
 
-    with open(version_result_dir / f"{v_str}_benchmark_metadata.json", "w") as file:
-        json.dump(benchmark_metadata, file, indent=4)
-    title = f"PrimAITE v{primaite.__version__.strip()} Learning Benchmark"
-    fig = _plot_benchmark_metadata(benchmark_metadata, title=title)
-    this_version_plot_path = version_result_dir / f"{title}.png"
-    fig.write_image(this_version_plot_path)
-
-    fig = _plot_all_benchmarks_combined_session_av()
-
-    all_version_plot_path = _RESULTS_ROOT / "PrimAITE Versions Learning Benchmark.png"
-    fig.write_image(all_version_plot_path)
-
-    _build_benchmark_latex_report(benchmark_metadata, this_version_plot_path, all_version_plot_path)
+    for i in range(1, number_of_sessions + 1):
+        with open(_SESSION_METADATA_ROOT / f"{i}.json", "r") as file:
+            session_metadata_dict[i] = json.load(file)
+    # generate report
+    build_benchmark_md_report(
+        benchmark_start_time=benchmark_start_time,
+        session_metadata=session_metadata_dict,
+        config_path=data_manipulation_config_path(),
+        results_root_path=_RESULTS_ROOT,
+    )
 
 
 if __name__ == "__main__":

benchmark/report.py

@@ -0,0 +1,426 @@
+# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, Optional
+
+import plotly.graph_objects as go
+import polars as pl
+import yaml
+from plotly.graph_objs import Figure
+from utils import _get_system_info
+
+import primaite
+
+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",
+}
+
+
+def _build_benchmark_results_dict(start_datetime: datetime, metadata_dict: Dict, config: Dict) -> dict:
+    """
+    Constructs a dictionary aggregating benchmark results from multiple sessions.
+
+    :param start_datetime: The datetime when the benchmarking started.
+    :param metadata_dict: Dictionary containing metadata for each session.
+    :param config: Configuration settings used during the benchmarking.
+    :return: A dictionary containing aggregated data and metadata from the benchmarking sessions.
+    """
+    num_sessions = len(metadata_dict)  # number of sessions
+
+    averaged_data = {
+        "start_timestamp": start_datetime.isoformat(),
+        "end_datetime": datetime.now().isoformat(),
+        "primaite_version": primaite.__version__,
+        "system_info": _get_system_info(),
+        "total_sessions": num_sessions,
+        "total_episodes": sum(d["total_episodes"] for d in metadata_dict.values()),
+        "total_time_steps": sum(d["total_time_steps"] for d in metadata_dict.values()),
+        "av_s_per_session": sum(d["total_s"] for d in metadata_dict.values()) / num_sessions,
+        "av_s_per_step": sum(d["s_per_step"] for d in metadata_dict.values()) / num_sessions,
+        "av_s_per_100_steps_10_nodes": sum(d["s_per_100_steps_10_nodes"] for d in metadata_dict.values())
+        / num_sessions,
+        "combined_total_reward_per_episode": {},
+        "session_total_reward_per_episode": {k: v["total_reward_per_episode"] for k, v in metadata_dict.items()},
+        "config": config,
+    }
+
+    # find the average of each episode across all sessions
+    episodes = metadata_dict[1]["total_reward_per_episode"].keys()
+
+    for episode in episodes:
+        combined_av_reward = (
+            sum(metadata_dict[k]["total_reward_per_episode"][episode] for k in metadata_dict.keys()) / num_sessions
+        )
+        averaged_data["combined_total_reward_per_episode"][episode] = combined_av_reward
+
+    return averaged_data
+
+
+def _get_df_from_episode_av_reward_dict(data: Dict) -> pl.DataFrame:
+    """
+    Converts a dictionary of episode average rewards into a Polars DataFrame.
+
+    :param data: Dictionary with episodes as keys and average rewards as values.
+    :return: Polars DataFrame with episodes and average rewards, including a rolling average.
+    """
+    data: Dict = {"episode": data.keys(), "av_reward": data.values()}
+
+    return (
+        pl.from_dict(data)
+        .with_columns(rolling_mean=pl.col("av_reward").rolling_mean(window_size=25))
+        .rename({"rolling_mean": "rolling_av_reward"})
+    )
+
+
+def _plot_benchmark_metadata(
+    benchmark_metadata_dict: Dict,
+    title: Optional[str] = None,
+    subtitle: Optional[str] = None,
+) -> Figure:
+    """
+    Plots benchmark metadata as a line graph using Plotly.
+
+    :param benchmark_metadata_dict: Dictionary containing the total reward per episode and session.
+    :param title: Optional title for the graph.
+    :param subtitle: Optional subtitle for the graph.
+    :return: Plotly figure object representing the benchmark metadata plot.
+    """
+    if title:
+        if subtitle:
+            title = f"{title} <br>{subtitle}</sup>"
+    else:
+        if subtitle:
+            title = subtitle
+
+    layout = go.Layout(
+        autosize=PLOT_CONFIG["size"]["auto_size"],
+        width=PLOT_CONFIG["size"]["width"],
+        height=PLOT_CONFIG["size"]["height"],
+    )
+    # Create the line graph with a colored line
+    fig = go.Figure(layout=layout)
+    fig.update_layout(template=PLOT_CONFIG["template"])
+
+    for session, av_reward_dict in benchmark_metadata_dict["session_total_reward_per_episode"].items():
+        df = _get_df_from_episode_av_reward_dict(av_reward_dict)
+        fig.add_trace(
+            go.Scatter(
+                x=df["episode"],
+                y=df["av_reward"],
+                mode="lines",
+                name=f"Session {session}",
+                opacity=0.25,
+                line={"color": "#a6a6a6"},
+            )
+        )
+
+    df = _get_df_from_episode_av_reward_dict(benchmark_metadata_dict["combined_total_reward_per_episode"])
+    fig.add_trace(
+        go.Scatter(
+            x=df["episode"], y=df["av_reward"], mode="lines", name="Combined Session Av", line={"color": "#FF0000"}
+        )
+    )
+
+    fig.add_trace(
+        go.Scatter(
+            x=df["episode"],
+            y=df["rolling_av_reward"],
+            mode="lines",
+            name="Rolling Av (Combined Session Av)",
+            line={"color": "#4CBB17"},
+        )
+    )
+
+    # Set the layout of the graph
+    fig.update_layout(
+        xaxis={
+            "title": "Episode",
+            "type": "linear",
+        },
+        yaxis={"title": "Total Reward"},
+        title=title,
+    )
+
+    return fig
+
+
+def _plot_all_benchmarks_combined_session_av(results_directory: Path) -> Figure:
+    """
+    Plot the Benchmark results for each released version of PrimAITE.
+
+    Does this by iterating over the ``benchmark/results`` directory and
+    extracting the benchmark metadata json for each version that has been
+    benchmarked. The combined_total_reward_per_episode is extracted from each,
+    converted into a polars dataframe, and plotted as a scatter line in plotly.
+    """
+    major_v = primaite.__version__.split(".")[0]
+    title = f"Learning Benchmark of Minor and Bugfix Releases for Major Version {major_v}"
+    subtitle = "Rolling Av (Combined Session Av)"
+    if title:
+        if subtitle:
+            title = f"{title} <br>{subtitle}</sup>"
+    else:
+        if subtitle:
+            title = subtitle
+    layout = go.Layout(
+        autosize=PLOT_CONFIG["size"]["auto_size"],
+        width=PLOT_CONFIG["size"]["width"],
+        height=PLOT_CONFIG["size"]["height"],
+    )
+    # Create the line graph with a colored line
+    fig = go.Figure(layout=layout)
+    fig.update_layout(template=PLOT_CONFIG["template"])
+
+    for dir in results_directory.iterdir():
+        if dir.is_dir():
+            metadata_file = dir / f"{dir.name}_benchmark_metadata.json"
+            with open(metadata_file, "r") as file:
+                metadata_dict = json.load(file)
+            df = _get_df_from_episode_av_reward_dict(metadata_dict["combined_total_reward_per_episode"])
+
+            fig.add_trace(go.Scatter(x=df["episode"], y=df["rolling_av_reward"], mode="lines", name=dir.name))
+
+    # Set the layout of the graph
+    fig.update_layout(
+        xaxis={
+            "title": "Episode",
+            "type": "linear",
+        },
+        yaxis={"title": "Total Reward"},
+        title=title,
+    )
+    fig["data"][0]["showlegend"] = True
+
+    return fig
+
+
+def _get_performance_benchmark_for_all_version_dict(results_directory: Path) -> Dict[str, float]:
+    """
+    Gathers performance benchmarks for all versions of the software stored in a specified directory.
+
+    This function iterates through each directory within the specified results directory,
+    extracts the av_s_per_100_steps_10_nodes from the benchmark_metadata.json files, and aggregates it into a
+    dictionary.
+
+    :param results_directory: The directory containing subdirectories for each version's benchmark data.
+    :return: A dictionary with version numbers as keys and their corresponding average performance benchmark
+        (average time per 100 steps on 10 nodes) as values.
+    """
+    performance_benchmark_dict = {}
+    for dir in results_directory.iterdir():
+        if dir.is_dir():
+            metadata_file = dir / f"{dir.name}_benchmark_metadata.json"
+            with open(metadata_file, "r") as file:
+                metadata_dict = json.load(file)
+                version = metadata_dict["primaite_version"]
+                performance_benchmark_dict[version] = metadata_dict["av_s_per_100_steps_10_nodes"]
+    return performance_benchmark_dict
+
+
+def _plot_av_s_per_100_steps_10_nodes(
+    version_times_dict: Dict[str, float],
+) -> Figure:
+    """
+    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.
+
+    :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.
+    """
+    major_v = primaite.__version__.split(".")[0]
+    title = f"Performance of Minor and Bugfix Releases for Major Version {major_v}"
+    subtitle = (
+        f"Average Training Time per 100 Steps on 10 Nodes "
+        f"(target: <= {PLOT_CONFIG['av_s_per_100_steps_10_nodes_benchmark_threshold']} seconds)"
+    )
+    title = f"{title} <br><sub>{subtitle}</sub>"
+
+    layout = go.Layout(
+        autosize=PLOT_CONFIG["size"]["auto_size"],
+        width=PLOT_CONFIG["size"]["width"],
+        height=PLOT_CONFIG["size"]["height"],
+    )
+    fig = go.Figure(layout=layout)
+    fig.update_layout(template=PLOT_CONFIG["template"])
+
+    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
+
+    fig.add_trace(
+        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)",
+        yaxis=dict(range=[0, max_y_axis_value]),
+        title=title,
+    )
+
+    return fig
+
+
+def build_benchmark_md_report(
+    benchmark_start_time: datetime, session_metadata: Dict, config_path: Path, results_root_path: Path
+) -> None:
+    """
+    Generates a Markdown report for a benchmarking session, documenting performance metrics and graphs.
+
+    This function orchestrates the creation of several graphs depicting various performance benchmarks and aggregates
+    them into a markdown document that includes comprehensive system and benchmark information.
+
+    :param benchmark_start_time: The datetime object representing when the benchmarking process was initiated.
+    :param session_metadata: A dictionary containing metadata for each benchmarking session.
+    :param config_path: A pathlib.Path object pointing to the configuration file used for the benchmark sessions.
+    :param results_root_path: A pathlib.Path object pointing to the directory where the results and graphs should be
+        saved.
+    """
+    # generate report folder
+    v_str = f"v{primaite.__version__}"
+
+    version_result_dir = results_root_path / v_str
+    version_result_dir.mkdir(exist_ok=True, parents=True)
+
+    # load the config file as dict
+    with open(config_path, "r") as f:
+        cfg_data = yaml.safe_load(f)
+
+    # generate the benchmark metadata dict
+    benchmark_metadata_dict = _build_benchmark_results_dict(
+        start_datetime=benchmark_start_time, metadata_dict=session_metadata, config=cfg_data
+    )
+    major_v = primaite.__version__.split(".")[0]
+    with open(version_result_dir / f"{v_str}_benchmark_metadata.json", "w") as file:
+        json.dump(benchmark_metadata_dict, file, indent=4)
+    title = f"PrimAITE v{primaite.__version__.strip()} Learning Benchmark"
+    fig = _plot_benchmark_metadata(benchmark_metadata_dict, title=title)
+    this_version_plot_path = version_result_dir / f"{title}.png"
+    fig.write_image(this_version_plot_path)
+
+    fig = _plot_all_benchmarks_combined_session_av(results_directory=results_root_path)
+
+    filename = f"PrimAITE Learning Benchmark of Minor and Bugfix Releases for Major Version {major_v}.png"
+
+    all_version_plot_path = version_result_dir / filename
+    fig.write_image(all_version_plot_path)
+
+    performance_benchmark_dict = _get_performance_benchmark_for_all_version_dict(results_directory=results_root_path)
+    fig = _plot_av_s_per_100_steps_10_nodes(performance_benchmark_dict)
+    filename = f"PrimAITE Performance of Minor and Bugfix Releases for Major Version {major_v}.png"
+    performance_benchmark_plot_path = version_result_dir / filename
+    fig.write_image(performance_benchmark_plot_path)
+
+    data = benchmark_metadata_dict
+    primaite_version = data["primaite_version"]
+
+    with open(version_result_dir / f"PrimAITE v{primaite_version} Benchmark Report.md", "w") as file:
+        # Title
+        file.write(f"# PrimAITE v{primaite_version} Learning Benchmark\n")
+        file.write("## PrimAITE Dev Team\n")
+        file.write(f"### {datetime.now().date()}\n")
+        file.write("\n---\n")
+
+        sessions = data["total_sessions"]
+        episodes = session_metadata[1]["total_episodes"] - 1
+        steps = data["config"]["game"]["max_episode_length"]
+
+        # Body
+        file.write("## 1 Introduction\n")
+        file.write(
+            f"PrimAITE v{primaite_version} was benchmarked automatically upon release. Learning rate metrics "
+            f"were captured to be referenced during system-level testing and user acceptance testing (UAT).\n"
+        )
+        file.write(
+            f"The benchmarking process consists of running {sessions} training session using the same "
+            f"config file. Each session trains an agent for {episodes} episodes, "
+            f"with each episode consisting of {steps} steps.\n"
+        )
+        file.write(
+            f"The total reward per episode from each session is captured. This is then used to calculate an "
+            f"caverage total reward per episode from the {sessions} individual sessions for smoothing. "
+            f"Finally, a 25-widow rolling average of the average total reward per session is calculated for "
+            f"further smoothing.\n"
+        )
+
+        file.write("## 2 System Information\n")
+        i = 1
+        file.write(f"### 2.{i} Python\n")
+        file.write(f"**Version:** {sys.version}\n")
+
+        for section, section_data in data["system_info"].items():
+            i += 1
+            if section_data:
+                file.write(f"### 2.{i} {section}\n")
+                if isinstance(section_data, dict):
+                    for key, value in section_data.items():
+                        file.write(f"- **{key}:** {value}\n")
+
+        headers_map = {
+            "total_sessions": "Total Sessions",
+            "total_episodes": "Total Episodes",
+            "total_time_steps": "Total Steps",
+            "av_s_per_session": "Av Session Duration (s)",
+            "av_s_per_step": "Av Step Duration (s)",
+            "av_s_per_100_steps_10_nodes": "Av Duration per 100 Steps per 10 Nodes (s)",
+        }
+
+        file.write("## 3 Stats\n")
+        for section, header in headers_map.items():
+            if section.startswith("av_"):
+                file.write(f"- **{header}:** {data[section]:.4f}\n")
+            else:
+                file.write(f"- **{header}:** {data[section]}\n")
+
+        file.write("## 4 Graphs\n")
+
+        file.write(f"### 4.1 v{primaite_version} Learning Benchmark Plot\n")
+        file.write(f"![PrimAITE {primaite_version} Learning Benchmark Plot]({this_version_plot_path.name})\n")
+
+        file.write(f"### 4.2 Learning Benchmark of Minor and Bugfix Releases for Major Version {major_v}\n")
+        file.write(
+            f"![Learning Benchmark of Minor and Bugfix Releases for Major Version {major_v}]"
+            f"({all_version_plot_path.name})\n"
+        )
+
+        file.write(f"### 4.3 Performance of Minor and Bugfix Releases for Major Version {major_v}\n")
+        file.write(
+            f"![Performance of Minor and Bugfix Releases for Major Version {major_v}]"
+            f"({performance_benchmark_plot_path.name})\n"
+        )

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

@@ -0,0 +1,38 @@
+# PrimAITE v3.0.0 Learning Benchmark
+## PrimAITE Dev Team
+### 2024-07-20
+
+---
+## 1 Introduction
+PrimAITE v3.0.0 was benchmarked automatically upon release. Learning rate metrics were captured to be referenced during system-level testing and user acceptance testing (UAT).
+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):** 1452.5910
+- **Av Step Duration (s):** 0.0454
+- **Av Duration per 100 Steps per 10 Nodes (s):** 4.5393
+## 4 Graphs
+### 4.1 v3.0.0 Learning Benchmark Plot
+![PrimAITE 3.0.0 Learning Benchmark Plot](PrimAITE v3.0.0 Learning Benchmark.png)
+### 4.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/utils.py

@@ -0,0 +1,47 @@
+# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+import platform
+from typing import Dict
+
+import psutil
+from GPUtil import GPUtil
+
+
+def get_size(size_bytes: int) -> str:
+    """
+    Scale bytes to its proper format.
+
+    e.g:
+        1253656 => '1.20MB'
+        1253656678 => '1.17GB'
+
+    :
+    """
+    factor = 1024
+    for unit in ["", "K", "M", "G", "T", "P"]:
+        if size_bytes < factor:
+            return f"{size_bytes:.2f}{unit}B"
+        size_bytes /= factor
+
+
+def _get_system_info() -> Dict:
+    """Builds and returns a dict containing system info."""
+    uname = platform.uname()
+    cpu_freq = psutil.cpu_freq()
+    virtual_mem = psutil.virtual_memory()
+    swap_mem = psutil.swap_memory()
+    gpus = GPUtil.getGPUs()
+    return {
+        "System": {
+            "OS": uname.system,
+            "OS Version": uname.version,
+            "Machine": uname.machine,
+            "Processor": uname.processor,
+        },
+        "CPU": {
+            "Physical Cores": psutil.cpu_count(logical=False),
+            "Total Cores": psutil.cpu_count(logical=True),
+            "Max Frequency": f"{cpu_freq.max:.2f}Mhz",
+        },
+        "Memory": {"Total": get_size(virtual_mem.total), "Swap Total": get_size(swap_mem.total)},
+        "GPU": [{"Name": gpu.name, "Total Memory": f"{gpu.memoryTotal}MB"} for gpu in gpus],
+    }

diagram/classes.puml

@@ -48,7 +48,7 @@ class "ActiveNode" as primaite.nodes.active_node.ActiveNode {
   file_system_state_actual : GOOD
   file_system_state_observed : REPAIRING, RESTORING, GOOD
   ip_address : str
-  patching_count : int
+  fixing_count : int
   software_state
   software_state : GOOD
   set_file_system_state(file_system_state: FileSystemState) -> None
@@ -353,10 +353,10 @@ class "SB3Agent" as primaite.agents.sb3.SB3Agent {
 }
 class "Service" as primaite.common.service.Service {
   name : str
-  patching_count : int
+  fixing_count : int
   port : str
   software_state : GOOD
-  reduce_patching_count() -> None
+  reduce_fixing_count() -> None
 }
 class "ServiceNode" as primaite.nodes.service_node.ServiceNode {
   services : Dict[str, Service]
@@ -455,7 +455,7 @@ class "TrainingConfig" as primaite.config.training_config.TrainingConfig {
   sb3_output_verbose_level
   scanning : float
   seed : Optional[int]
-  service_patching_duration : int
+  service_fixing_duration : int
   session_type
   time_delay : int
   from_dict(config_dict: Dict[str, Any]) -> TrainingConfig

docs/Makefile

@@ -6,7 +6,7 @@ SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
 
-AUTOSUMMARY="source\_autosummary"
+AUTOSUMMARY="source/_autosummary"
 
 # Remove command is different depending on OS
 ifdef OS
@@ -29,6 +29,5 @@ clean:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile | clean
-	pip-licenses --format=rst --with-urls --output-file=source/primaite-dependencies.rst
 
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/api.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 .. only:: comment
 
     © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
@@ -17,4 +19,3 @@
    :recursive:
 
    primaite
-   tests

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

@@ -0,0 +1,67 @@
+#!/bin/bash
+set -x
+
+apt-get update
+apt-get -y install git rsync python3-sphinx
+
+pwd ls -lah
+export SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct)
+
+##############
+# BUILD DOCS #
+##############
+
+cd docs
+# Python Sphinx, configured with source/conf.py
+# See https://www.sphinx-doc.org/
+make clean
+make html
+
+cd ..
+#######################
+# Update GitHub Pages #
+#######################
+
+git config --global user.name "${GITHUB_ACTOR}"
+git config --global user.email "${GITHUB_ACTOR}@users.noreply.github.com"
+
+docroot=`mktemp -d`
+
+rsync -av $PWD/docs/_build/html/ "${docroot}/"
+
+pushd "${docroot}"
+
+git init
+git remote add deploy "https://token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
+git checkout -b sphinx-docs-github-pages
+
+# Adds .nojekyll file to the root to signal to GitHub that
+# directories that start with an underscore (_) can remain
+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/,
+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:
+ * https://www.docslikecode.com/articles/github-pages-python-sphinx/
+ * https://tech.michaelaltfield.net/2020/07/18/sphinx-rtd-github-pages-1
+ * https://github.com/annegentle/create-demo
+EOF
+
+# Copy the resulting html pages built from Sphinx to the sphinx-docs-github-pages branch
+git add .
+
+# Make a commit with changes and any new files
+msg="Updating Docs for commit ${GITHUB_SHA} made on `date -d"@${SOURCE_DATE_EPOCH}" --iso-8601=seconds` from ${GITHUB_REF} by ${GITHUB_ACTOR}"
+git commit -am "${msg}"
+
+# overwrite the contents of the sphinx-docs-github-pages branch on our github.com repo
+git push deploy sphinx-docs-github-pages --force
+
+popd # return to main repo sandbox root
+
+# exit cleanly
+exit 0

docs/conf.py

@@ -9,13 +9,15 @@ import datetime
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 import os
+import shutil
 import sys
+from pathlib import Path
+from typing import Any, List, Optional
 
 import furo  # noqa
 
 sys.path.insert(0, os.path.abspath("../"))
 
-
 # -- Project information -----------------------------------------------------
 year = datetime.datetime.now().year
 project = "PrimAITE"
@@ -28,6 +30,11 @@ with open("../src/primaite/VERSION", "r") as file:
 # The full version, including alpha/beta/rc tags
 release = version
 
+# set global variables
+rst_prolog = f"""
+.. |VERSION| replace::  {release}
+"""
+
 html_title = f"{project} v{release} docs"
 
 # -- General configuration ---------------------------------------------------
@@ -43,16 +50,136 @@ extensions = [
     "sphinx.ext.viewcode",  # Add a link to the Python source code for classes, functions etc.
     "sphinx.ext.todo",
     "sphinx_copybutton",  # Adds a copy button to code blocks
-    "sphinx_code_tabs",  # Enables tabbed code blocks
+    "nbsphinx",
 ]
 
-
 templates_path = ["_templates"]
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
-
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+]
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "furo"
 html_static_path = ["_static"]
+html_theme_options = {"globaltoc_collapse": True, "globaltoc_maxdepth": 2}
+html_copy_source = False
+nbsphinx_allow_errors = False  # set to True to take shortcuts
+html_scaled_image_link = False
+
+# make some stuff easier to read
+nbsphinx_prolog = """
+.. raw:: html
+
+    <style>
+        .stderr {
+            color: #000 !important
+        }
+    </style>
+"""
+
+
+def replace_token(app: Any, docname: Any, source: Any):
+    """Replaces a token from the list of tokens."""
+    result = source[0]
+    for key in app.config.tokens:
+        result = result.replace(key, app.config.tokens[key])
+    source[0] = result
+
+
+tokens = {
+    "{VERSION}": release,
+}  # Token VERSION is replaced by the value of the PrimAITE version in the version file
+"""Dict containing the tokens that need to be replaced in documentation."""
+
+
+def notebook_assets(ignored_files: Optional[List[str]] = [], include_file_types: Optional[List[str]] = []) -> Any:
+    """
+    Creates a function to be used with `shutil.copytree`'s `ignore` parameter.
+
+    :param ignored_files: A list of specific file names to ignore. If a file in the directory matches one of these
+    names, it will be excluded from the copy process.
+    :type ignored_files: Optional[List[str]]
+    :param include_file_types: A list of file extensions to include in the copy process. Files that do not match these
+    extensions will be excluded. If this list is empty, all files will be excluded, effectively copying only
+    directories.
+    :type include_file_types: Optional[List[str]]
+    """
+
+    def ignore_items(directory: List[str], contents: List[str]) -> List[str]:
+        """
+        Determines which files and directories should be ignored during the copy process.
+
+        :param directory: The directory being copied.
+        :type directory: str
+        :param contents: A list of contents in the directory.
+        :type contents: List[str]
+        :return: A list of items to exclude from the copy process.
+        :rtype: List[str]
+        """
+        exclude_items = []
+
+        for item in contents:
+            if item in ignored_files:
+                exclude_items.append(item)
+                continue
+
+            if len(include_file_types) > 0:
+                if not any(item.lower().endswith(ext.lower()) for ext in include_file_types) and os.path.isdir(item):
+                    exclude_items.append(item)
+            else:
+                # if we dont specify which files to include, exclude everything
+                exclude_items.append(item)
+
+        # exclude files but not directories
+        return [path for path in exclude_items if not (Path(directory) / path).is_dir()]
+
+    return ignore_items
+
+
+def copy_notebooks_to_docs() -> Any:
+    """
+    Incredibly over-engineered method that copies the notebooks and its assets to a directory within the docs directory.
+
+    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_directories = []
+
+    # find paths where notebooks are contained
+    for notebook in Path("../src/primaite").rglob("*.ipynb"):
+        # add parent path to notebook directory if not already added
+        if notebook.parent not in notebook_directories:
+            notebook_directories.append(notebook.parent)
+
+    # go through the notebook directories and copy the notebooks and extra assets
+    for notebook_parent in notebook_directories:
+        shutil.copytree(
+            src=notebook_parent,
+            dst=Path("source") / "notebooks" / notebook_parent.name,
+            ignore=notebook_assets(include_file_types=notebook_asset_types),
+            dirs_exist_ok=True,
+        )
+
+
+def suppress_log_output():
+    """Sets the log level while building the documentation."""
+    from primaite import _FILE_HANDLER, _LOGGER, _STREAM_HANDLER
+
+    log_level = "WARN"
+
+    _LOGGER.setLevel(log_level)
+    _STREAM_HANDLER.setLevel(log_level)
+    _FILE_HANDLER.setLevel(log_level)
+
+
+def setup(app: Any):
+    """Custom setup for sphinx."""
+    suppress_log_output()
+    copy_notebooks_to_docs()
+    app.add_config_value("tokens", {}, True)
+    app.connect("source-read", replace_token)

docs/index.rst

@@ -1,27 +1,94 @@
 .. only:: comment
 
-    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
 
 Welcome to PrimAITE's documentation
 ====================================
 
 What is PrimAITE?
-------------------------
+-----------------
 
-PrimAITE (Primary-level AI Training Environment) is a simulation environment for training AI under the ARCD programme. It incorporates the functionality required of a Primary-level environment, as specified in the Dstl ARCD Training Environment Matrix document:
+Overview
+^^^^^^^^
 
-* The ability to model a relevant platform / system context;
-* The ability to model key characteristics of a platform / system by representing connections, IP addresses, ports, traffic loading, operating systems, file system, services and processes;
-* Operates at machine-speed to enable fast training cycles.
+The ARCD Primary-level AI Training Environment (**PrimAITE**) provides an effective simulation capability for training and evaluating AI in a cyber-defensive role. It incorporates the functionality required of a primary-level  ARCD environment:
 
-PrimAITE aims to evolve into an ARCD environment that could be used as the follow-on from Reception level approaches (e.g. YAWNING TITAN), and help bridge the Sim-to-Real gap into Secondary level environments (e.g. IMAGINARY YAK).
+- The ability to model a relevant system context;
+- Modelling an adversarial agent that the defensive agent can be trained and evaluated against;
+- The ability to model key characteristics of a system by representing hosts, servers, network devices, IP addresses, ports, operating systems, folders / files, applications, services and links;
+- Modelling background (green) pattern-of-life;
+- Operates at machine-speed to enable fast training cycles via Reinforcement Learning (RL).
 
-This is similar to the approach taken by FVEY international partners (e.g. AUS CyBORG, US NSA FARLAND and CAN CyGil). These environments are referenced by the Dstl ARCD Agent Training Environments Knowledge Transfer document (TR141342).
+Features
+^^^^^^^^
+
+PrimAITE incorporates the following features:
+
+- Architected with a separate Simulation layer and Game layer. This separation of concerns defines a clear path towards transfer learning with environments of differing fidelity;
+- Ability to reconfigure an RL reward function based on (a) the ability to counter the modelled adversarial cyber-attack, and (b) the ability to ensure success for green agents;
+- Access Control List (ACL) functions for network devices (routers and firewalls), following standard ACL rule format (e.g., DENY / ALLOW, source / destination IP addresses, protocol and port);
+- Application of traffic to the links of the system laydown adheres to the ACL rulesets and routing tables contained within each network device;
+- Provides RL environments adherent to the Farama Foundation Gymnasium (Previously OpenAI Gym) API, allowing integration with any compliant RL Agent frameworks;
+- Provides RL environments adherent to Ray RLlib environment specifications for single-agent and multi-agent scenarios;
+- Assessed for compatibility with Stable-Baselines3 (SB3), Ray RLlib, and bespoke agents;
+- Persona-based adversarial (Red) agent behaviour; several out-the-box personas are provided, and more can be developed to suit the needs of the task. Stochastic variations in Red agent behaviour are also included as required;
+- A robust system logging tool, automatically enabled at the node level and featuring various log levels and terminal output options, enables PrimAITE users to conduct in-depth network simulations;
+- 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;
+- 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
---------------------------------------
+---------------------------
 
-* `OpenAI's Gym <https://gym.openai.com/>`_ is used as the basis for AI blue agent interaction with the PrimAITE environment
+* `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
@@ -31,35 +98,45 @@ What is PrimAITE built with
 * `Plotly <https://github.com/plotly/plotly.py>`_ is used for building high level charts
 
 
-Where next?
-------------
+Getting Started with PrimAITE
+-----------------------------
 
 Head over to the :ref:`getting-started` page to install and setup PrimAITE!
 
 .. toctree::
    :maxdepth: 8
-   :caption: Contents:
+   :caption: About PrimAITE:
+   :hidden:
+
+   source/about
+   source/dependencies
+   source/glossary
+
+.. toctree::
+   :caption: Usage:
    :hidden:
 
    source/getting_started
-   source/about
+   source/simulation
+   source/game_layer
    source/config
-   source/primaite_session
-   source/custom_agent
-   PrimAITE API <source/_autosummary/primaite>
-   PrimAITE Tests <source/_autosummary/tests>
-   source/dependencies
-   source/glossary
-   source/migration_1.2_-_2.0
-
-
-.. TODO: Add project links once public repo has been created
+   source/environment
+   source/customising_scenarios
+   source/varying_config_files
 
 .. toctree::
-   :caption: Project Links:
+   :caption: Notebooks:
    :hidden:
 
-   Code <https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE>
-   Issues <https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE/issues>
-   Pull Requests <https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE/pulls>
-   Discussions <https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE/discussions>
+   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

@@ -36,11 +36,6 @@ IF EXIST %AUTOSUMMARYDIR% (
     RMDIR %AUTOSUMMARYDIR% /s /q
 )
 
-REM print the YT licenses
-set LICENSEBUILD=pip-licenses --format=rst --with-urls
-set DEPS="%cd%\source\primaite-dependencies.rst"
-
-%LICENSEBUILD% --output-file=%DEPS%
 
 %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 goto end

docs/source/about.rst

@@ -1,73 +1,64 @@
 .. only:: comment
 
-    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
 
 .. _about:
 
 About PrimAITE
 ==============
 
+PrimAITE is a simulation environment for training agents to protect a computer network from cyber attacks.
+
 Features
 ********
 
 PrimAITE provides the following features:
 
-* A flexible network / system laydown based on the Python networkx framework
-* Nodes and links (edges) host Python classes in order to present attributes and methods (and hence, a more representative model of a platform / system)
-* A 'green agent' Information Exchange Requirement (IER) function allows the representation of traffic (protocols and loading) on any / all links. Application of IERs is based on the status of node operating systems and services
-* A 'green agent' node Pattern-of-Life (PoL) function allows the representation of core behaviours on nodes (e.g. changing the Hardware state, Software State, Service state, or File System state)
-* An Access Control List (ACL) function, mimicking the behaviour of a network firewall, is applied across the model, following standard ACL rule format (e.g. DENY/ALLOW, source IP, destination IP, protocol and port). Application of IERs adheres to any ACL restrictions
-* Presents an OpenAI Gym interface to the environment, allowing integration with any OpenAI Gym compliant defensive agents
-* Red agent activity based on 'red' IERs and 'red' PoL
-* Defined reward function for use with RL agents (based on nodes status, and green / red IER success)
-* Fully configurable (network / system laydown, IERs, node PoL, ACL, episode step period, episode max steps) and repeatable to suit the training requirements of agents. Therefore, not bound to a representation of any particular platform, system or technology
-* Full capture of discrete metrics relating to agent training (full system state, agent actions taken, average reward)
-* Networkx provides laydown visualisation capability
+* 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.
 
+
+Structure
+*********
+
+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.
+
+
+..
   Architecture - Nodes and Links
   ******************************
-
   **Nodes**
-
   An inheritance model has been adopted in order to model nodes. All nodes have the following base attributes (Class: Node):
-
   * ID
   * Name
   * Type (e.g. computer, switch, RTU - enumeration)
   * Priority (P1, P2, P3, P4 or P5 - enumeration)
   * Hardware State (ON, OFF, RESETTING, SHUTTING_DOWN, BOOTING - enumeration)
-
   Active Nodes also have the following attributes (Class: Active Node):
-
   * IP Address
-* Software State (GOOD, PATCHING, COMPROMISED - enumeration)
+  * Software State (GOOD, FIXING, COMPROMISED - enumeration)
   * File System State (GOOD, CORRUPT, DESTROYED, REPAIRING, RESTORING - enumeration)
-
   Service Nodes also have the following attributes (Class: Service Node):
-
   * List of Services (where service is composed of service name and port). There is no theoretical limit on the number of services that can be modelled. Services and protocols are currently intrinsically linked (i.e. a service is an application on a node transmitting traffic of this protocol type)
-* Service state (GOOD, PATCHING, COMPROMISED, OVERWHELMED - enumeration)
-
+  * Service state (GOOD, FIXING, COMPROMISED, OVERWHELMED - enumeration)
   Passive Nodes are currently not used (but may be employed for non IP-based components such as machinery actuators in future releases).
-
   **Links**
-
   Links are modelled both as network edges (networkx) and as Python classes, in order to extend their functionality. Links include the following attributes:
-
   * ID
   * Name
   * Bandwidth (bits/s)
   * Source node ID
   * Destination node ID
   * Protocol list (containing the loading of protocols currently running on the link)
-
   When the simulation runs, IERs are applied to the links in order to model traffic loading, individually assigned to each protocol. This allows green (background) and red agent behaviour to be modelled, and defensive agents to identify suspicious traffic patterns at a protocol / traffic loading level of fidelity.
-
   Information Exchange Requirements (IERs)
   ****************************************
-
   PrimAITE adopts the concept of Information Exchange Requirements (IERs) to model both green agent (background) and red agent (adversary) behaviour. IERs are used to initiate modelling of traffic loading on the network, and have the following attributes:
-
   * ID
   * Start step (i.e. which step in the training episode should the IER start)
   * End step (i.e. which step in the training episode should the IER end)
@@ -77,92 +68,61 @@ PrimAITE adopts the concept of Information Exchange Requirements (IERs) to model
   * Protocol
   * Port
   * Running status (i.e. on / off)
-
   The application of green agent IERs between a source and destination follows a number of rules. Specifically:
-
   1. Does the current simulation time step fall between IER start and end step
-2. Is the source node operational (both physically and at an O/S level), and is the service (protocol / port) associated with the IER (a) present on this node, and (b) in an operational state (i.e. not PATCHING)
-3. Is the destination node operational (both physically and at an O/S level), and is the service (protocol / port) associated with the IER (a) present on this node, and (b) in an operational state (i.e. not PATCHING)
+  2. Is the source node operational (both physically and at an O/S level), and is the service (protocol / port) associated with the IER (a) present on this node, and (b) in an operational state (i.e. not FIXING)
+  3. Is the destination node operational (both physically and at an O/S level), and is the service (protocol / port) associated with the IER (a) present on this node, and (b) in an operational state (i.e. not FIXING)
   4. Are there any Access Control List rules in place that prevent the application of this IER
   5. Are all switches in the (OSPF) path between source and destination operational (both physically and at an O/S level)
-
   For red agent IERs, the application of IERs between a source and destination follows a number of subtly different rules. Specifically:
-
   1. Does the current simulation time step fall between IER start and end step
   2. Is the source node operational, and is the service (protocol / port) associated with the IER (a) present on that node and (b) already in a compromised state
   3. Is the destination node operational, and is the service (protocol / port) associated with the IER present on that node
   4. Are there any Access Control List rules in place that prevent the application of this IER
   5. Are all switches in the (OSPF) path between source and destination operational (both physically and at an O/S level)
-
   Assuming the rules pass, the IER is applied to all relevant links (based on use of OSPF) between source and destination.
-
   Node Pattern-of-Life
   ********************
-
   Every node can be impacted (i.e. have a status change applied to it) by either green agent pattern-of-life or red agent pattern-of-life. This is distinct from IERs, and allows for attacks (and defence) to be modelled purely within the confines of a node.
-
   The status changes that can be made to a node are as follows:
-
   * All Nodes:
-
     * Hardware State:
-
         * ON
         * OFF
         * RESETTING - when a status of resetting is entered, the node will automatically exit this state after a number of steps (as defined by the nodeResetDuration configuration item) after which it returns to an ON state
         * BOOTING
         * SHUTTING_DOWN
-
   * Active Nodes and Service Nodes:
-
     * Software State:
-
         * GOOD
-      * PATCHING - when a status of patching is entered, the node will automatically exit this state after a number of steps (as defined by the osPatchingDuration configuration item) after which it returns to a GOOD state
+        * FIXING - when a status of FIXING is entered, the node will automatically exit this state after a number of steps (as defined by the osFIXINGDuration configuration item) after which it returns to a GOOD state
         * COMPROMISED
-
     * File System State:
-
         * GOOD
         * CORRUPT (can be resolved by repair or restore)
         * DESTROYED (can be resolved by restore only)
         * REPAIRING - when a status of repairing is entered, the node will automatically exit this state after a number of steps (as defined by the fileSystemRepairingLimit configuration item) after which it returns to a GOOD state
         * RESTORING - when a status of repairing is entered, the node will automatically exit this state after a number of steps (as defined by the fileSystemRestoringLimit configuration item) after which it returns to a GOOD state
-
   * Service Nodes only:
-
     * Service State (for any associated service):
-
         * GOOD
-      * PATCHING - when a status of patching is entered, the service will automatically exit this state after a number of steps (as defined by the servicePatchingDuration configuration item) after which it returns to a GOOD state
+        * FIXING - when a status of FIXING is entered, the service will automatically exit this state after a number of steps (as defined by the serviceFIXINGDuration configuration item) after which it returns to a GOOD state
         * COMPROMISED
         * OVERWHELMED
-
   Red agent pattern-of-life has an additional feature not found in the green pattern-of-life. This is the ability to influence the state of the attributes of a node via a number of different conditions:
-
     * DIRECT:
-
     The pattern-of-life described by the configuration file item will be applied regardless of any other conditions in the network. This is particularly useful for direct red agent entry into the network.
-
     * IER:
-
     The pattern-of-life described by the configuration file item will be applied to the service on the node, only if there is an IER of the same protocol / service type incoming at the specified timestep.
-
     * SERVICE:
-
     The pattern-of-life described by the configuration file item will be applied to the node based on the state of a service. The service can either be on the same node, or a different node within the network.
-
   Access Control List modelling
   *****************************
-
   An Access Control List (ACL) is modelled to provide the means to manage traffic flows in the system. This will allow defensive agents the means to turn on / off rules, or potentially create new rules, to counter an attack.
-
   The ACL follows a standard network firewall format. For example:
-
   .. list-table:: ACL example
     :widths: 25 25 25 25 25
     :header-rows: 1
-
     * - Permission
       - Source IP
       - Dest IP
@@ -183,25 +143,18 @@ The ACL follows a standard network firewall format. For example:
       - 192.168.1.5
       - ANY
       - ANY
-
   All ACL rules are considered when applying an IER. Logic follows the order of rules, so a DENY or ALLOW for the same parameters will override an earlier entry.
-
   Observation Spaces
   ******************
   The observation space provides the blue agent with information about the current status of nodes and links.
-
-PrimAITE builds on top of Gym Spaces to create an observation space that is easily configurable for users. It's made up of components which are managed by the :py:class:`primaite.environment.observations.ObservationsHandler`. Each training scenario can define its own observation space, and the user can choose which information to inlude, and how it should be formatted.
-
+  PrimAITE builds on top of Gymnasium Spaces to create an observation space that is easily configurable for users. It's made up of components which are managed by the :py:class:`primaite.environment.observations.ObservationsHandler`. Each training scenario can define its own observation space, and the user can choose which information to inlude, and how it should be formatted.
   NodeLinkTable component
   -----------------------
   For example, the :py:class:`primaite.environment.observations.NodeLinkTable` component represents the status of nodes and links as a ``gym.spaces.Box`` with an example format shown below:
-
   An example observation space is provided below:
-
   .. list-table:: Observation Space example
     :widths: 25 25 25 25 25 25 25
     :header-rows: 1
-
     * -
       - ID
       - Hardware State
@@ -251,26 +204,19 @@ An example observation space is provided below:
       - 0
       - 5000
       - 0
-
   For the nodes, the following values are represented:
-
   .. code-block::
-
     [
       ID
       Hardware State            (1=ON,   2=OFF,  3=RESETTING,  4=SHUTTING_DOWN, 5=BOOTING)
       Operating System State    (0=none, 1=GOOD, 2=PATCHING,   3=COMPROMISED)
       File System State         (0=none, 1=GOOD, 2=CORRUPT,    3=DESTROYED,  4=REPAIRING, 5=RESTORING)
-    Service1/Protocol1 state  (0=none, 1=GOOD, 2=PATCHING,   3=COMPROMISED)
-    Service2/Protocol2 state  (0=none, 1=GOOD, 2=PATCHING,   3=COMPROMISED)
+      Service1/Protocol1 state  (0=none, 1=GOOD, 2=FIXING,   3=COMPROMISED)
+      Service2/Protocol2 state  (0=none, 1=GOOD, 2=FIXING,   3=COMPROMISED)
     ]
-
   (Note that each service available in the network is provided as a column, although not all nodes may utilise all services)
-
   For the links, the following statuses are represented:
-
   .. code-block::
-
     [
       ID
       Hardware State            (0=not applicable)
@@ -279,136 +225,93 @@ For the links, the following statuses are represented:
       Service1/Protocol1 state  (Traffic load from this protocol on this link)
       Service2/Protocol2 state  (Traffic load from this protocol on this link)
     ]
-
   NodeStatus component
   ----------------------
   This is a MultiDiscrete observation space that can be though of as a one-dimensional vector of discrete states.
   The example above would have the following structure:
-
   .. code-block::
-
     [
       node1_info
       node2_info
       node3_info
     ]
-
   Each ``node_info`` contains the following:
-
   .. code-block::
-
     [
       hardware_state    (0=none, 1=ON,   2=OFF,      3=RESETTING, 4=SHUTTING_DOWN, 5=BOOTING)
       software_state    (0=none, 1=GOOD, 2=PATCHING, 3=COMPROMISED)
       file_system_state (0=none, 1=GOOD, 2=CORRUPT,  3=DESTROYED, 4=REPAIRING, 5=RESTORING)
-    service1_state    (0=none, 1=GOOD, 2=PATCHING, 3=COMPROMISED)
-    service2_state    (0=none, 1=GOOD, 2=PATCHING, 3=COMPROMISED)
+      service1_state    (0=none, 1=GOOD, 2=FIXING, 3=COMPROMISED)
+      service2_state    (0=none, 1=GOOD, 2=FIXING, 3=COMPROMISED)
     ]
-
   In a network with three nodes and two services, the full observation space would have 15 elements. It can be written with ``gym`` notation to indicate the number of discrete options for each of the elements of the observation space. For example:
-
   .. code-block::
-
     gym.spaces.MultiDiscrete([4,5,6,4,4,4,5,6,4,4,4,5,6,4,4])
-
   .. note::
     NodeStatus observation component provides information only about nodes. Links are not considered.
-
   LinkTrafficLevels
   -----------------
   This component is a MultiDiscrete space showing the traffic flow levels on the links in the network, after applying a threshold to convert it from a continuous to a discrete value.
   There are two configurable parameters:
   * ``quantisation_levels`` determines how many discrete bins to use for converting the continuous traffic value to discrete (default is 5).
   * ``combine_service_traffic`` determines whether to separately output traffic use for each network protocol or whether to combine them into an overall value for the link. (default is ``True``)
-
   For example, with default parameters and a network with three links, the structure of this component would be:
-
   .. code-block::
-
     [
       link1_status
       link2_status
       link3_status
     ]
-
   Each ``link_status`` is a number from 0-4 representing the network load in relation to bandwidth.
-
   .. code-block::
-
     0 = No traffic (0%)
     1 = low traffic (1%-33%)
     2 = medium traffic (33%-66%)
     3 = high traffic (66%-99%)
     4 = max traffic/ overwhelmed (100%)
-
   Using ``gym`` notation, the shape of the obs space is: ``gym.spaces.MultiDiscrete([5,5,5])``.
-
-
   Action Spaces
   **************
-
   The action space available to the blue agent comes in two types:
-
   1. Node-based
   2. Access Control List
   3. Any (Agent can take both node-based and ACL-based actions)
-
   The choice of action space used during a training session is determined in the config_[name].yaml file.
-
   **Node-Based**
-
-The agent is able to influence the status of nodes by switching them off, resetting, or patching operating systems and services. In this instance, the action space is an OpenAI Gym spaces.Discrete type, as follows:
-
+  The agent is able to influence the status of nodes by switching them off, resetting, or FIXING operating systems and services. In this instance, the action space is a Gymnasium spaces.Discrete type, as follows:
   * Dictionary item {... ,1: [x1, x2, x3,x4] ...}
     The placeholders inside the list under the key '1' mean the following:
-
       * [0, num nodes] - Node ID (0 = nothing, node ID)
       * [0, 4] - What property it's acting on (0 = nothing, 1 = state, 2 = SoftwareState, 3 = service state, 4 = file system state)
       * [0, 3] - Action on property (0 = nothing, 1 = on / scan, 2 = off / repair, 3 = reset / patch / restore)
       * [0, num services] - Resolves to service ID (0 = nothing, resolves to service)
-
   **Access Control List**
-
-The blue agent is able to influence the configuration of the Access Control List rule set (which implements a system-wide firewall). In this instance, the action space is an OpenAI spaces.Discrete type, as follows:
-
+  The blue agent is able to influence the configuration of the Access Control List rule set (which implements a system-wide firewall). In this instance, the action space is an Gymnasium spaces.Discrete type, as follows:
     * Dictionary item {... ,1: [x1, x2, x3, x4, x5, x6] ...}
     The placeholders inside the list under the key '1' mean the following:
-
       * [0, 2] - Action (0 = do nothing, 1 = create rule, 2 = delete rule)
       * [0, 1] - Permission (0 = DENY, 1 = ALLOW)
       * [0, num nodes] - Source IP (0 = any, then 1 -> x resolving to IP addresses)
       * [0, num nodes] - Dest IP (0 = any, then 1 -> x resolving to IP addresses)
       * [0, num services] - Protocol (0 = any, then 1 -> x resolving to protocol)
       * [0, num ports] - Port (0 = any, then 1 -> x resolving to port)
-
   **ANY**
   The agent is able to carry out both **Node-Based** and **Access Control List** operations.
-
   This means the dictionary will contain key-value pairs in the format of BOTH Node-Based and Access Control List as seen above.
-
   Rewards
   *******
-
   A reward value is presented back to the blue agent on the conclusion of every step. The reward value is calculated via two methods which combine to give the total value:
-
   1. Node and service status
   2. IER status
-
   **Node and service status**
-
   On every step, the status of each node is compared against both a reference environment (simulating the situation if the red and blue agents had not impacted the environment)
   and the before and after state of the environment. If the comparison against the reference environment shows no difference, then the score provided is "AllOK". If there is a
   difference with respect to the reference environment, the before and after states are compared, and a score determined. See :ref:`config` for details of reward values.
-
   **IER status**
-
   On every step, the full IER set is examined to determine whether green and red agent IERs are being permitted to run. Any red agent IERs running incur a penalty; any green agent
   IERs not permitted to run also incur a penalty. See :ref:`config` for details of reward values.
-
   Future Enhancements
   *******************
-
   The PrimAITE project has an ambition to include the following enhancements in future releases:
-
   * Integration with a suitable standardised framework to allow multi-agent integration
   * Integration with external threat emulation tools, either using off-line data, or integrating at runtime

docs/source/config.rst

@@ -1,489 +1,41 @@
 .. only:: comment
 
-    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
 
-.. _config:
+PrimAITE |VERSION| Configuration
+********************************
 
-The Config Files Explained
-==========================
+PrimAITE uses YAML configuration files to define everything needed to create the training environment for RL agents, including the network, the scripted agents, and the RL agent's action space, observation space, and reward function.
 
-PrimAITE uses two configuration files for its operation:
-
-* **The Training Config**
-
-    Used to define the top-level settings of the PrimAITE environment, the reward values, and the session that is to be run.
-
-* **The Lay Down Config**
-
-    Used to define the low-level settings of a session, including the network laydown, green / red agent information exchange requirements (IERSs) and Access Control Rules.
-
-Training Config:
-*******************
-
-The Training Config file consists of the following attributes:
-
-**Generic Config Values**
-
-
-* **agent_framework** [enum]
-
-    This identifies the agent framework to be used to instantiate the agent algorithm. Select from one of the following:
-
-    * NONE - Where a user developed agent is to be used
-    * SB3 - Stable Baselines3
-    * RLLIB - Ray RLlib.
-
-* **agent_identifier**
-
-    This identifies the agent to use for the session. Select from one of the following:
-
-    * A2C - Advantage Actor Critic
-    * PPO - Proximal Policy Optimization
-    * HARDCODED - A custom built deterministic agent
-    * RANDOM - A Stochastic random agent
-
-
-* **random_red_agent** [bool]
-
-    Determines if the session should be run with a random red agent
-
-* **action_type** [enum]
-
-    Determines whether a NODE, ACL, or ANY (combined NODE & ACL) action space format is adopted for the session
-
-
-* **OBSERVATION_SPACE** [dict]
-
-    Allows for user to configure observation space by combining one or more observation components. List of available
-    components is in :py:mod:`primaite.environment.observations`.
-
-    The observation space config item should have a ``components`` key which is a list of components. Each component
-    config must have a ``name`` key, and can optionally have an ``options`` key. The ``options`` are passed to the
-    component while it is being initialised.
-
-    This example illustrates the correct format for the observation space config item
+Example Configuration Hierarchy
+###############################
+The top level configuration items in a configuration file is as follows
 
 .. code-block:: yaml
 
-        observation_space:
-        components:
-          - name: NODE_LINK_TABLE
-          - name: NODE_STATUSES
-          - name: LINK_TRAFFIC_LEVELS
-          - name: ACCESS_CONTROL_LIST
-            options:
-              combine_service_traffic : False
-              quantisation_levels: 99
+    io_settings:
+    ...
+    game:
+    ...
+    agents:
+    ...
+    simulation:
+    ...
 
+These are expanded upon in the Configurable items section below
 
-    Currently available components are:
+Configurable items
+##################
 
-      * :py:mod:`NODE_LINK_TABLE<primaite.environment.observations.NodeLinkTable>` this does not accept any additional options
-      * :py:mod:`NODE_STATUSES<primaite.environment.observations.NodeStatuses>`, this does not accept any additional options
-      * :py:mod:`ACCESS_CONTROL_LIST<primaite.environment.observations.AccessControlList>`, this does not accept additional options
-      * :py:mod:`LINK_TRAFFIC_LEVELS<primaite.environment.observations.LinkTrafficLevels>`, this accepts the following options:
+.. toctree::
+   :maxdepth: 1
 
-        * ``combine_service_traffic`` - whether to consider bandwidth use separately for each network protocol or combine them into a single bandwidth reading (boolean)
-        * ``quantisation_levels`` - how many discrete bandwidth usage levels to use for encoding. This can be an integer equal to or greater than 3.
+   configuration/io_settings.rst
+   configuration/game.rst
+   configuration/agents.rst
+   configuration/simulation.rst
 
-    The other configurable item is ``flatten`` which is false by default. When set to true, the observation space is flattened (turned into a 1-D vector). You should use this if your RL agent does not natively support observation space types like ``gym.Spaces.Tuple``.
+Varying The Configuration Each Episode
+######################################
 
-* **num_train_episodes** [int]
-
-    This defines the number of episodes that the agent will train for.
-
-
-* **num_train_steps** [int]
-
-    Determines the number of steps to run in each episode of the training session.
-
-
-* **num_eval_episodes** [int]
-
-    This defines the number of episodes that the agent will be evaluated over.
-
-
-* **num_eval_steps** [int]
-
-    Determines the number of steps to run in each episode of the evaluation session.
-
-
-* **time_delay** [int]
-
-    The time delay (in milliseconds) to take between each step when running a GENERIC agent session
-
-
-* **session_type** [text]
-
-    Type of session to be run (TRAINING, EVALUATION, or BOTH)
-
-* **load_agent** [bool]
-
-    Determine whether to load an agent from file
-
-* **agent_load_file** [text]
-
-    File path and file name of agent if you're loading one in
-
-* **observation_space_high_value** [int]
-
-    The high value to use for values in the observation space. This is set to 1000000000 by default, and should not need changing in most cases
-
-* **implicit_acl_rule** [str]
-
-    Determines which Explicit rule the ACL list has - two options are: DENY or ALLOW.
-
-* **max_number_acl_rules** [int]
-
-    Sets a limit on how many ACL rules there can be in the ACL list throughout the training session.
-
-**Reward-Based Config Values**
-
-Rewards are calculated based on the difference between the current state and reference state (the 'should be' state) of the environment.
-
-* **Generic [all_ok]** [float]
-
-    The score to give when the current situation (for a given component) is no different from that expected in the baseline (i.e. as though no blue or red agent actions had been undertaken)
-
-* **Node Hardware State [off_should_be_on]** [float]
-
-    The score to give when the node should be on, but is off
-
-* **Node Hardware State [off_should_be_resetting]** [float]
-
-    The score to give when the node should be resetting, but is off
-
-* **Node Hardware State [on_should_be_off]** [float]
-
-    The score to give when the node should be off, but is on
-
-* **Node Hardware State [on_should_be_resetting]** [float]
-
-    The score to give when the node should be resetting, but is on
-
-* **Node Hardware State [resetting_should_be_on]** [float]
-
-    The score to give when the node should be on, but is resetting
-
-* **Node Hardware State [resetting_should_be_off]** [float]
-
-    The score to give when the node should be off, but is resetting
-
-* **Node Hardware State [resetting]** [float]
-
-    The score to give when the node is resetting
-
-* **Node Operating System or Service State [good_should_be_patching]** [float]
-
-    The score to give when the state should be patching, but is good
-
-* **Node Operating System or Service State [good_should_be_compromised]** [float]
-
-    The score to give when the state should be compromised, but is good
-
-* **Node Operating System or Service State [good_should_be_overwhelmed]** [float]
-
-    The score to give when the state should be overwhelmed, but is good
-
-* **Node Operating System or Service State [patching_should_be_good]** [float]
-
-    The score to give when the state should be good, but is patching
-
-* **Node Operating System or Service State [patching_should_be_compromised]** [float]
-
-    The score to give when the state should be compromised, but is patching
-
-* **Node Operating System or Service State [patching_should_be_overwhelmed]** [float]
-
-    The score to give when the state should be overwhelmed, but is patching
-
-* **Node Operating System or Service State [patching]** [float]
-
-    The score to give when the state is patching
-
-* **Node Operating System or Service State [compromised_should_be_good]** [float]
-
-    The score to give when the state should be good, but is compromised
-
-* **Node Operating System or Service State [compromised_should_be_patching]** [float]
-
-    The score to give when the state should be patching, but is compromised
-
-* **Node Operating System or Service State [compromised_should_be_overwhelmed]** [float]
-
-    The score to give when the state should be overwhelmed, but is compromised
-
-* **Node Operating System or Service State [compromised]** [float]
-
-    The score to give when the state is compromised
-
-* **Node Operating System or Service State [overwhelmed_should_be_good]** [float]
-
-    The score to give when the state should be good, but is overwhelmed
-
-* **Node Operating System or Service State [overwhelmed_should_be_patching]** [float]
-
-    The score to give when the state should be patching, but is overwhelmed
-
-* **Node Operating System or Service State [overwhelmed_should_be_compromised]** [float]
-
-    The score to give when the state should be compromised, but is overwhelmed
-
-* **Node Operating System or Service State [overwhelmed]** [float]
-
-    The score to give when the state is overwhelmed
-
-* **Node File System State [good_should_be_repairing]** [float]
-
-    The score to give when the state should be repairing, but is good
-
-* **Node File System State [good_should_be_restoring]** [float]
-
-    The score to give when the state should be restoring, but is good
-
-* **Node File System State [good_should_be_corrupt]** [float]
-
-    The score to give when the state should be corrupt, but is good
-
-* **Node File System State [good_should_be_destroyed]** [float]
-
-    The score to give when the state should be destroyed, but is good
-
-* **Node File System State [repairing_should_be_good]** [float]
-
-    The score to give when the state should be good, but is repairing
-
-* **Node File System State [repairing_should_be_restoring]** [float]
-
-    The score to give when the state should be restoring, but is repairing
-
-* **Node File System State [repairing_should_be_corrupt]** [float]
-
-    The score to give when the state should be corrupt, but is repairing
-
-* **Node File System State [repairing_should_be_destroyed]** [float]
-
-    The score to give when the state should be destroyed, but is repairing
-
-* **Node File System State [repairing]** [float]
-
-    The score to give when the state is repairing
-
-* **Node File System State [restoring_should_be_good]** [float]
-
-    The score to give when the state should be good, but is restoring
-
-* **Node File System State [restoring_should_be_repairing]** [float]
-
-    The score to give when the state should be repairing, but is restoring
-
-* **Node File System State [restoring_should_be_corrupt]** [float]
-
-    The score to give when the state should be corrupt, but is restoring
-
-* **Node File System State [restoring_should_be_destroyed]** [float]
-
-    The score to give when the state should be destroyed, but is restoring
-
-* **Node File System State [restoring]** [float]
-
-    The score to give when the state is restoring
-
-* **Node File System State [corrupt_should_be_good]** [float]
-
-    The score to give when the state should be good, but is corrupt
-
-* **Node File System State [corrupt_should_be_repairing]** [float]
-
-    The score to give when the state should be repairing, but is corrupt
-
-* **Node File System State [corrupt_should_be_restoring]** [float]
-
-    The score to give when the state should be restoring, but is corrupt
-
-* **Node File System State [corrupt_should_be_destroyed]** [float]
-
-    The score to give when the state should be destroyed, but is corrupt
-
-* **Node File System State [corrupt]** [float]
-
-    The score to give when the state is corrupt
-
-* **Node File System State [destroyed_should_be_good]** [float]
-
-    The score to give when the state should be good, but is destroyed
-
-* **Node File System State [destroyed_should_be_repairing]** [float]
-
-    The score to give when the state should be repairing, but is destroyed
-
-* **Node File System State [destroyed_should_be_restoring]** [float]
-
-    The score to give when the state should be restoring, but is destroyed
-
-* **Node File System State [destroyed_should_be_corrupt]** [float]
-
-    The score to give when the state should be corrupt, but is destroyed
-
-* **Node File System State [destroyed]** [float]
-
-    The score to give when the state is destroyed
-
-* **Node File System State [scanning]** [float]
-
-    The score to give when the state is scanning
-
-* **IER Status [red_ier_running]** [float]
-
-    The score to give when a red agent IER is permitted to run
-
-* **IER Status [green_ier_blocked]** [float]
-
-    The score to give when a green agent IER is prevented from running
-
-**Patching / Reset Durations**
-
-* **os_patching_duration** [int]
-
-    The number of steps to take when patching an Operating System
-
-* **node_reset_duration** [int]
-
-    The number of steps to take when resetting a node's hardware state
-
-* **service_patching_duration** [int]
-
-    The number of steps to take when patching a service
-
-* **file_system_repairing_limit** [int]:
-
-    The number of steps to take when repairing the file system
-
-* **file_system_restoring_limit** [int]
-
-    The number of steps to take when restoring the file system
-
-* **file_system_scanning_limit** [int]
-
-    The number of steps to take when scanning the file system
-
-* **deterministic** [bool]
-
-   Set to true if the agent evaluation should be deterministic. Default is ``False``
-
-* **seed** [int]
-
-   Seed used in the randomisation in agent training. Default is ``None``
-
-The Lay Down Config
-*******************
-
-The lay down config file consists of the following attributes:
-
-
-* **itemType: STEPS** [int]
-
-* **item_type: PORTS** [int]
-
-    Provides a list of ports modelled in this session
-
-* **item_type: SERVICES** [freetext]
-
-    Provides a list of services modelled in this session
-
-* **item_type: NODE**
-
-    Defines a node included in the system laydown being simulated. It should consist of the following attributes:
-
-     * **id** [int]: Unique ID for this YAML item
-     * **name** [freetext]: Human-readable name of the component
-     * **node_class** [enum]: Relates to the base type of the node. Can be SERVICE, ACTIVE or PASSIVE. PASSIVE nodes do not have an operating system or services. ACTIVE nodes have an operating system, but no services. SERVICE nodes have both an operating system and one or more services
-     * **node_type** [enum]: Relates to the component type. Can be one of CCTV, SWITCH, COMPUTER, LINK, MONITOR, PRINTER, LOP, RTU, ACTUATOR or SERVER
-     * **priority** [enum]: Provides a priority for each node. Can be one of P1, P2, P3, P4 or P5 (which P1 being the highest)
-     * **hardware_state** [enum]: The initial hardware state of the node. Can be one of ON, OFF or RESETTING
-     * **ip_address** [IP address]: The IP address of the component in format xxx.xxx.xxx.xxx
-     * **software_state** [enum]: The intial state of the node operating system. Can be GOOD, PATCHING or COMPROMISED
-     * **file_system_state** [enum]: The initial state of the node file system. Can be GOOD, CORRUPT, DESTROYED, REPAIRING or RESTORING
-     * **services**: For each service associated with the node:
-
-        * **name** [freetext]: Free-text name of the service, but must match one of the services defined for the system in the services list
-        * **port** [int]: Integer value of the port related to this service, but must match one of the ports defined for the system in the ports list
-        * **state** [enum]: The initial state of the service. Can be one of GOOD, PATCHING, COMPROMISED or OVERWHELMED
-
-* **item_type: LINK**
-
-    Defines a link included in the system laydown being simulated. It should consist of the following attributes:
-
-     * **id** [int]: Unique ID for this YAML item
-     * **name** [freetext]: Human-readable name of the component
-     * **bandwidth** [int]: The bandwidth (in bits/s) of the link
-     * **source** [int]: The ID of the source node
-     * **destination** [int]: The ID of the destination node
-
-* **item_type: GREEN_IER**
-
-    Defines a green agent Information Exchange Requirement (IER). It should consist of:
-
-     * **id** [int]: Unique ID for this YAML item
-     * **start_step** [int]: The start step (in the episode) for this IER to begin
-     * **end_step** [int]: The end step (in the episode) for this IER to finish
-     * **load** [int]: The load (in bits/s) for this IER to apply to links
-     * **protocol** [freetext]: The protocol to apply to the links. This must match a value in the services list
-     * **port** [int]: The port that the protocol is running on. This must match a value in the ports list
-     * **source** [int]: The ID of the source node
-     * **destination** [int]: The ID of the destination node
-     * **mission_criticality** [enum]: The mission criticality of this IER (with 5 being highest, 1 lowest)
-
-* **item_type: RED_IER**
-
-    Defines a red agent Information Exchange Requirement (IER). It should consist of:
-
-     * **id** [int]: Unique ID for this YAML item
-     * **start_step** [int]: The start step (in the episode) for this IER to begin
-     * **end_step** [int]: The end step (in the episode) for this IER to finish
-     * **load** [int]: The load (in bits/s) for this IER to apply to links
-     * **protocol** [freetext]: The protocol to apply to the links. This must match a value in the services list
-     * **port** [int]: The port that the protocol is running on. This must match a value in the ports list
-     * **source** [int]: The ID of the source node
-     * **destination** [int]: The ID of the destination node
-     * **mission_criticality** [enum]: Not currently used. Default to 0
-
-* **item_type: GREEN_POL**
-
-    Defines a green agent pattern-of-life instruction. It should consist of:
-
-      * **id** [int]: Unique ID for this YAML item
-      * **start_step** [int]: The start step (in the episode) for this PoL to begin
-      * **end_step** [int]: Not currently used. Default to same as start step
-      * **nodeId** [int]: The ID of the node to apply the PoL to
-      * **type** [enum]: The type of PoL to apply. Can be one of OPERATING, OS or SERVICE
-      * **protocol** [freetext]: The protocol to be affected if SERVICE type is chosen. Must match a value in the services list
-      * **state** [enuum]: The state to apply to the node (which represents the PoL change). Can be one of ON, OFF or RESETTING (for node state) or GOOD, PATCHING or COMPROMISED (for Software State) or GOOD, PATCHING, COMPROMISED or OVERWHELMED (for service state)
-
-* **item_type: RED_POL**
-
-    Defines a red agent pattern-of-life instruction. It should consist of:
-
-      * **id** [int]: Unique ID for this YAML item
-      * **start_step** [int]: The start step (in the episode) for this PoL to begin
-      * **end_step** [int]: Not currently used. Default to same as start step
-      * **targetNodeId** [int]: The ID of the node to apply the PoL to
-      * **initiator** [enum]: What initiates the PoL. Can be DIRECT, IER or SERVICE
-      * **type** [enum]: The type of PoL to apply. Can be one of OPERATING, OS or SERVICE
-      * **protocol** [freetext]: The protocol to be affected if SERVICE type is chosen. Must match a value in the services list
-      * **state** [enum]: The state to apply to the node (which represents the PoL change). Can be one of ON, OFF or RESETTING (for node state) or GOOD, PATCHING or COMPROMISED (for Software State) or GOOD, PATCHING, COMPROMISED or OVERWHELMED (for service state) or GOOD, CORRUPT, DESTROYED, REPAIRING or RESTORING (for file system state)
-      * **sourceNodeId** [int] The ID of the source node containing the service to check (used for SERVICE initiator)
-      * **sourceNodeService** [freetext]: The service on the source node to check (used for SERVICE initiator). Must match a value in the services list for this node
-      * **sourceNodeServiceState** [enum]: The state of the source node service to check (used for SERVICE initiator). Can be one of GOOD, PATCHING, COMPROMISED or OVERWHELMED
-
-* **item_type: ACL_RULE**
-
-    Defines an initial Access Control List (ACL) rule. It should consist of:
-
-      * **id** [int]: Unique ID for this YAML item
-      * **permission** [enum]: Defines either an allow or deny rule. Value must be either DENY or ALLOW
-      * **source** [IP address]: Defines the source IP address for the rule in xxx.xxx.xxx.xxx format
-      * **destination** [IP address]: Defines the destination IP address for the rule in xxx.xxx.xxx.xxx format
-      * **protocol** [freetext]: Defines the protocol for the rule. Must match a value in the services list
-      * **port** [int]: Defines the port for the rule. Must match a value in the ports list
-      * **position** [int]: Defines where to place the ACL rule in the list. Lower index or (higher up in the list) means they are checked first. Index starts at 0 (Python indexes).
+PrimAITE allows for the configuration to be varied each episode. This is done by specifying a configuration folder instead of a single file. A full explanation is provided in the notebook `Using-Episode-Schedules.ipynb`. Please find the notebook in the user notebooks directory.

docs/source/configuration/agents.rst

@@ -0,0 +1,174 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+
+``agents``
+==========
+Agents can be scripted (deterministic and stochastic), or controlled by a reinforcement learning algorithm. Not to be confused with an RL agent, the term agent here is used to refer to an entity that sends requests to the simulated network. In this part of the config, each agent's action space, observation space, and reward function can be defined. All three are defined in a modular way.
+
+``agents`` hierarchy
+--------------------
+
+.. code-block:: yaml
+
+    agents:
+        - ref: red_agent_example
+            ...
+        - ref: blue_agent_example
+            ...
+        - ref: green_agent_example
+            team: GREEN
+            type: ProbabilisticAgent
+            observation_space:
+                type: UC2GreenObservation
+            action_space:
+                action_list:
+                - type: DONOTHING
+                - type: NODE_APPLICATION_EXECUTE
+            options:
+                nodes:
+                - node_name: client_2
+                  applications:
+                    - application_name: WebBrowser
+                max_folders_per_node: 1
+                max_files_per_folder: 1
+                max_services_per_node: 1
+                max_applications_per_node: 1
+
+            reward_function:
+                reward_components:
+                - type: DUMMY
+
+            agent_settings:
+                start_settings:
+                    start_step: 5
+                    frequency: 4
+            variance: 3
+            flatten_obs: False
+
+``ref``
+-------
+The reference to be used for the given agent.
+
+``team``
+--------
+Specifies if the agent is malicious (``RED``), benign (``GREEN``), or defensive (``BLUE``). Currently this value is not used for anything other than for human readability in the configuration file.
+
+``type``
+--------
+Specifies which class should be used for the agent. ``ProxyAgent`` is used for agents that receive instructions from an RL algorithm. Scripted agents like ``RedDatabaseCorruptingAgent`` and ``ProbabilisticAgent`` generate their own behaviour.
+
+Available agent types:
+
+- ``ProbabilisticAgent``
+- ``ProxyAgent``
+- ``RedDatabaseCorruptingAgent``
+
+``observation_space``
+---------------------
+Defines the observation space of the agent.
+
+``type``
+^^^^^^^^
+
+selects which python class from the :py:mod:`primaite.game.agent.observation` module is used for the overall observation structure.
+
+``options``
+^^^^^^^^^^^
+
+Allows configuration of the chosen observation type. These are optional.
+
+    * ``num_services_per_node``, ``num_folders_per_node``, ``num_files_per_folder``, ``num_nics_per_node`` all define the shape of the observation space. The size and shape of the obs space must remain constant, but the number of files, folders, ACL rules, and other components can change within an episode. Therefore padding is performed and these options set the size of the obs space.
+    * ``nodes``: list of nodes that will be present in this agent's observation space. The ``node_ref`` relates to the human-readable unique reference defined later in the ``simulation`` part of the config. Each node can also be configured with services, and files that should be monitored.
+    * ``links``: list of links that will be present in this agent's observation space. The ``link_ref`` relates to the human-readable unique reference defined later in the ``simulation`` part of the config.
+    * ``acl``: configure how the agent reads the access control list on the router in the simulation. ``router_node_ref`` is for selecting which router's ACL table should be used. ``ip_list`` sets the encoding of ip addresses as integers within the observation space.
+
+For more information see :py:mod:`primaite.game.agent.observations`
+
+``action_space``
+----------------
+
+The action space is configured to be made up of individual action types. Once configured, the agent can select an action type and some optional action parameters at every step. For example: The ``NODE_SERVICE_SCAN`` action takes the parameters ``node_id`` and ``service_id``.
+
+``action_list``
+^^^^^^^^^^^^^^^
+
+A list of action modules. The options are listed in the :py:mod:`primaite.game.agent.actions.ActionManager.act_class_identifiers` module.
+
+``action_map``
+^^^^^^^^^^^^^^
+
+Restricts the possible combinations of action type / action parameter values to reduce the overall size of the action space. By default, every possible combination of actions and parameters will be assigned an integer for the agent's ``MultiDiscrete`` action space. Instead, the ``action_map`` allows you to list the actions corresponding to each integer in the ``MultiDiscrete`` space.
+
+This is Optional.
+
+``options``
+^^^^^^^^^^^
+
+Options that apply to all action components. These are optional.
+
+    * ``nodes``: list the nodes that the agent can act on, the order of this list defines the mapping between nodes and ``node_id`` integers.
+    * ``max_folders_per_node``, ``max_files_per_folder``, ``max_services_per_node``, ``max_nics_per_node``, ``max_acl_rules`` all are used to define the size of the action space.
+
+For more information see :py:mod:`primaite.game.agent.actions`
+
+``reward_function``
+-------------------
+
+Similar to action space, this is defined as a list of components from the :py:mod:`primaite.game.agent.rewards` module.
+
+``reward_components``
+^^^^^^^^^^^^^^^^^^^^^
+
+A list of reward types from :py:mod:`primaite.game.agent.rewards.RewardFunction.rew_class_identifiers`
+
+e.g.
+
+.. code-block:: yaml
+
+    reward_components:
+        - type: DUMMY
+        - type: DATABASE_FILE_INTEGRITY
+
+
+``agent_settings``
+------------------
+
+Settings passed to the agent during initialisation. Determines how the agent will behave during training.
+
+e.g.
+
+.. code-block:: yaml
+
+    agent_settings:
+        start_settings:
+            start_step: 25
+            frequency: 20
+            variance: 5
+
+``start_step``
+^^^^^^^^^^^^^^
+
+Optional. Default value is ``5``.
+
+The timestep where the agent begins performing actions.
+
+``frequency``
+^^^^^^^^^^^^^
+
+Optional. Default value is ``5``.
+
+The number of timesteps the agent will wait before performing another action.
+
+``variance``
+^^^^^^^^^^^^
+
+Optional. Default value is ``0``.
+
+The amount of timesteps that the frequency can randomly change.
+
+``flatten_obs``
+---------------
+
+If ``True``, gymnasium flattening will be performed on the observation space before sending to the agent. Set this to ``True`` if your agent does not support nested observation spaces.

docs/source/configuration/game.rst

@@ -0,0 +1,56 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+
+``game``
+========
+This section defines high-level settings that apply across the game, currently it's used to help shape the action and observation spaces by restricting which ports and internet protocols should be considered. Here, users can also set the maximum number of steps in an episode.
+
+``game`` hierarchy
+------------------
+
+.. code-block:: yaml
+
+    game:
+        max_episode_length: 256
+        ports:
+            - ARP
+            - DNS
+            - HTTP
+            - POSTGRES_SERVER
+        protocols:
+            - ICMP
+            - TCP
+            - UDP
+        thresholds:
+            nmne:
+                high: 10
+                medium: 5
+                low: 0
+
+``max_episode_length``
+----------------------
+
+Optional. Default value is ``256``.
+
+The maximum number of episodes a Reinforcement Learning agent(s) can be trained for.
+
+``ports``
+---------
+
+A list of ports that the Reinforcement Learning agent(s) are able to see in the observation space.
+
+See :ref:`List of Ports <List of Ports>` for a list of ports.
+
+``protocols``
+-------------
+
+A list of protocols that the Reinforcement Learning agent(s) are able to see in the observation space.
+
+See :ref:`List of IPProtocols <List of IPProtocols>` for a list of protocols.
+
+``thresholds``
+--------------
+
+These are used to determine the thresholds of high, medium and low categories for counted observation occurrences.

docs/source/configuration/io_settings.rst

@@ -0,0 +1,90 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+
+``io_settings``
+===============
+This section configures how PrimAITE saves data during simulation and training.
+
+``io_settings`` hierarchy
+-------------------------
+
+.. code-block:: yaml
+
+    io_settings:
+        # save_logs: True
+        save_agent_actions: True
+        save_step_metadata: False
+        save_pcap_logs: False
+        save_sys_logs: False
+        write_sys_log_to_terminal: False
+        sys_log_level: WARNING
+
+
+``save_logs``
+-------------
+
+*currently unused*.
+
+``save_agent_actions``
+----------------------
+
+Optional. Default value is ``True``.
+
+If ``True``, this will create a JSON file each episode detailing every agent's action in each step of that episode, formatted according to the CAOS format. This includes scripted, RL, and red agents.
+
+``save_step_metadata``
+----------------------
+
+Optional. Default value is ``False``.
+
+If ``True``, The RL agent(s) actions, environment states and other data will be saved at every single step.
+
+
+``save_pcap_logs``
+------------------
+
+Optional. Default value is ``False``.
+
+If ``True``, then the pcap files which contain all network traffic during the simulation will be saved.
+
+
+``save_sys_logs``
+-----------------
+
+Optional. Default value is ``False``.
+
+If ``True``, then the log files which contain all node actions during the simulation will be saved.
+
+
+``write_sys_log_to_terminal``
+-----------------------------
+
+Optional. Default value is ``False``.
+
+If ``True``, PrimAITE will print sys log to the terminal.
+
+
+``sys_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.
+
+``save_sys_logs`` or ``write_sys_log_to_terminal`` has to be set to ``True`` for this setting to be used.
+
+Available options are:
+
+- ``DEBUG``: Debug level items and the items below
+- ``INFO``: Info level items and the items below
+- ``WARNING``: Warning level items and the items below
+- ``ERROR``: Error level items and the items below
+- ``CRITICAL``: Only critical level logs
+
+See also |logging_levels|
+
+.. |logging_levels| raw:: html
+
+    <a href="https://docs.python.org/3/library/logging.html#logging-levels" target="blank">Python logging levels</a>

docs/source/configuration/simulation.rst

@@ -0,0 +1,103 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, 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``.
+
+e.g.
+
+.. code-block:: yaml
+
+    simulation:
+        network:
+            nodes:
+            ...
+            links:
+            ...
+
+``nodes``
+---------
+
+This is where the list of nodes are defined. Some items will differ according to the node type, however, there will be common items such as a node's reference (which is used by the agent), the node's ``type`` and ``hostname``
+
+To see the configuration for these nodes, refer to the following:
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    simulation/nodes/computer
+    simulation/nodes/firewall
+    simulation/nodes/router
+    simulation/nodes/server
+    simulation/nodes/switch
+    simulation/nodes/wireless_router
+    simulation/nodes/network_examples
+
+``links``
+---------
+
+This is where the links between the nodes are formed.
+
+e.g.
+
+In order to recreate the network below, we will need to create 2 links:
+
+- a link from computer_1 to the switch
+- a link from computer_2 to the switch
+
+.. image:: ../../_static/switched_p2p_network.png
+    :width: 500
+    :align: center
+
+this results in:
+
+.. code-block:: yaml
+
+    links:
+        - endpoint_a_hostname: computer_1
+        endpoint_a_port: 1 # port 1 on computer_1
+        endpoint_b_hostname: switch
+        endpoint_b_port: 1 # port 1 on switch
+        bandwidth: 100
+        - endpoint_a_hostname: computer_2
+        endpoint_a_port: 1 # port 1 on computer_2
+        endpoint_b_hostname: switch
+        endpoint_b_port: 2 # port 2 on switch
+        bandwidth: 100
+
+``ref``
+^^^^^^^
+
+The human readable name for the link. Not used in code, however is useful for a human to understand what the link is for.
+
+``endpoint_a_hostname``
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``hostname`` of the node which must be connected.
+
+``endpoint_a_port``
+^^^^^^^^^^^^^^^^^^^
+
+The port on ``endpoint_a_hostname`` which is to be connected to ``endpoint_b_port``.
+This accepts an integer value e.g. if port 1 is to be connected, the configuration should be ``endpoint_a_port: 1``
+
+``endpoint_b_hostname``
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``hostname`` of the node which must be connected.
+
+``endpoint_b_port``
+^^^^^^^^^^^^^^^^^^^
+
+The port on ``endpoint_b_hostname`` which is to be connected to ``endpoint_a_port``.
+This accepts an integer value e.g. if port 1 is to be connected, the configuration should be ``endpoint_b_port: 1``
+
+``bandwidth``
+
+This is an integer value specifying the allowed bandwidth across the connection. Units are in Mbps.

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

@@ -0,0 +1,35 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+.. _Node Attributes:
+
+Common Attributes
+#################
+
+Node Attributes
+===============
+
+Attributes that are shared by all nodes.
+
+.. include:: common_node_attributes.rst
+
+.. _Network Node Attributes:
+
+Network Node Attributes
+=======================
+
+Attributes that are shared by nodes that inherit from :py:mod:`primaite.simulator.network.hardware.nodes.network.network_node.NetworkNode`
+
+.. include:: common_host_node_attributes.rst
+
+.. _Host Node Attributes:
+
+Host Node Attributes
+====================
+
+Attributes that are shared by nodes that inherit from :py:mod:`primaite.simulator.network.hardware.nodes.host.host_node.HostNode`
+
+.. include:: common_host_node_attributes.rst
+
+.. |NODE| replace:: node

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

@@ -0,0 +1,26 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+.. _common_host_node_attributes:
+
+``ip_address``
+--------------
+
+The IP address of the |NODE| in the network.
+
+``subnet_mask``
+---------------
+
+Optional. Default value is ``255.255.255.0``.
+
+The subnet mask for the |NODE| to use.
+
+``default_gateway``
+-------------------
+
+The IP address that the |NODE| will use as the default gateway. Typically, this is the IP address of the closest router that the |NODE| is connected to.
+
+.. include:: ../software/applications.rst
+
+.. include:: ../software/services.rst

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

@@ -0,0 +1,51 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+.. _common_network_node_attributes:
+
+``routes``
+----------
+
+A list of routes which tells the |NODE| where to forward the packet to depending on the target IP address.
+
+e.g.
+
+.. code-block:: yaml
+
+    nodes:
+        - ref: node
+        ...
+        routes:
+            - address: 192.168.0.10
+            subnet_mask: 255.255.255.0
+            next_hop_ip_address: 192.168.1.1
+            metric: 0
+
+``address``
+"""""""""""
+
+The target IP address for the route. If the packet destination IP address matches this, the |NODE| will route the packet according to the ``next_hop_ip_address``.
+
+This must be a valid octet i.e. in the range of ``0.0.0.0`` and ``255.255.255.255``.
+
+``subnet_mask``
+"""""""""""""""
+
+Optional. Default value is ``255.255.255.0``.
+
+The subnet mask setting for the route.
+
+``next_hop_ip_address``
+"""""""""""""""""""""""
+
+The IP address of the next hop IP address that the packet will follow if the address matches the packet's destination IP address.
+
+This must be a valid octet i.e. in the range of ``0.0.0.0`` and ``255.255.255.255``.
+
+``metric``
+""""""""""
+
+Optional. Default value is ``0``. This value accepts floats.
+
+The cost or distance of a route. The higher the value, the more cost or distance is attributed to the route.

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

@@ -0,0 +1,55 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+.. _common_node_attributes:
+
+``ref``
+-------
+
+Human readable name used as reference for the |NODE|. Not used in code.
+
+``hostname``
+------------
+
+The hostname of the |NODE|. This will be used to reference the |NODE|.
+
+``operating_state``
+-------------------
+
+The initial operating state of the node.
+
+Optional. Default value is ``ON``.
+
+Options available are:
+
+- ``ON``
+- ``OFF``
+- ``BOOTING``
+- ``SHUTTING_DOWN``
+
+Note that YAML may assume non quoted ``ON`` and ``OFF`` as ``True`` and ``False`` respectively. To prevent this, use ``"ON"`` or ``"OFF"``
+
+See :py:mod:`primaite.simulator.network.hardware.node_operating_state.NodeOperatingState`
+
+
+``dns_server``
+--------------
+
+Optional. Default value is ``None``.
+
+The IP address of the node which holds an instance of the :ref:`DNSServer`. Some applications may use a domain name e.g. the :ref:`WebBrowser`
+
+``start_up_duration``
+---------------------
+
+Optional. Default value is ``3``.
+
+The number of time steps required to occur in order for the node to cycle from ``OFF`` to ``BOOTING_UP`` and then finally ``ON``.
+
+``shut_down_duration``
+----------------------
+
+Optional. Default value is ``3``.
+
+The number of time steps required to occur in order for the node to cycle from ``ON`` to ``SHUTTING_DOWN`` and then finally ``OFF``.

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

@@ -0,0 +1,18 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+``type``
+--------
+
+The type of node to add.
+
+Available options are:
+
+- ``computer``
+- ``firewall``
+- ``router``
+- ``server``
+- ``switch``
+
+To create a |NODE|, type must be |NODE_TYPE|.

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

@@ -0,0 +1,41 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+.. _computer_configuration:
+
+``computer``
+============
+
+A basic representation of a computer within the simulation.
+
+See :py:mod:`primaite.simulator.network.hardware.nodes.host.computer.Computer`
+
+example computer
+----------------
+
+.. code-block:: yaml
+
+    simulation:
+        network:
+            nodes:
+                - ref: client_1
+                hostname: client_1
+                type: computer
+                ip_address: 192.168.0.10
+                subnet_mask: 255.255.255.0
+                default_gateway: 192.168.0.1
+                dns_server: 192.168.1.10
+                applications:
+                    ...
+                services:
+                    ...
+
+.. include:: common/common_node_attributes.rst
+
+.. include:: common/node_type_list.rst
+
+.. include:: common/common_host_node_attributes.rst
+
+.. |NODE| replace:: computer
+.. |NODE_TYPE| replace:: ``computer``

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

@@ -0,0 +1,300 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+.. _firewall_configuration:
+
+``firewall``
+============
+
+A basic representation of a network firewall within the simulation.
+
+The firewall is similar to how :ref:`Router <router_configuration>` works, with the difference being how firewall has specific ACL rules for inbound and outbound traffic as well as firewall being limited to 3 ports.
+
+See :py:mod:`primaite.simulator.network.hardware.nodes.network.firewall.Firewall`
+
+example firewall
+----------------
+
+.. code-block:: yaml
+
+    simulation:
+        network:
+            nodes:
+                - ref: firewall
+                    hostname: firewall
+                    type: firewall
+                    start_up_duration: 0
+                    shut_down_duration: 0
+                    ports:
+                        external_port: # port 1
+                            ip_address: 192.168.20.1
+                            subnet_mask: 255.255.255.0
+                        internal_port: # port 2
+                            ip_address: 192.168.1.2
+                            subnet_mask: 255.255.255.0
+                        dmz_port: # port 3
+                            ip_address: 192.168.10.1
+                            subnet_mask: 255.255.255.0
+                    acl:
+                        internal_inbound_acl:
+                            ...
+                        internal_outbound_acl:
+                            ...
+                        dmz_inbound_acl:
+                            ...
+                        dmz_outbound_acl:
+                            ...
+                        external_inbound_acl:
+                            ...
+                        external_outbound_acl:
+                            ...
+                    routes:
+                        ...
+
+.. include:: common/common_node_attributes.rst
+
+.. include:: common/node_type_list.rst
+
+``ports``
+---------
+
+The firewall node only has 3 ports. These specifically are:
+
+- ``external_port`` (port 1)
+- ``internal_port`` (port 2)
+- ``dmz_port`` (port 3) (can be optional)
+
+The ports should be defined with an ip address and subnet mask e.g.
+
+.. code-block:: yaml
+
+    nodes:
+        - ref: firewall
+        ...
+        ports:
+            external_port: # port 1
+                ip_address: 192.168.20.1
+                subnet_mask: 255.255.255.0
+            internal_port: # port 2
+                ip_address: 192.168.1.2
+                subnet_mask: 255.255.255.0
+            dmz_port: # port 3
+                ip_address: 192.168.10.1
+                subnet_mask: 255.255.255.0
+
+``ip_address``
+""""""""""""""
+
+The IP address for the given port. This must be a valid octet i.e. in the range of ``0.0.0.0`` and ``255.255.255.255``.
+
+``subnet_mask``
+"""""""""""""""
+
+Optional. Default value is ``255.255.255.0``.
+
+The subnet mask setting for the port.
+
+``acl``
+-------
+
+There are 6 ACLs that can be defined for a firewall
+
+- ``internal_inbound_acl`` for traffic going towards the internal network
+- ``internal_outbound_acl`` for traffic coming from the internal network
+- ``dmz_inbound_acl`` for traffic going towards the dmz network
+- ``dmz_outbound_acl`` for traffic coming from the dmz network
+- ``external_inbound_acl`` for traffic coming from the external network
+- ``external_outbound_acl`` for traffic going towards the external network
+
+.. image:: ../../../../_static/firewall_acl.png
+    :width: 500
+    :align: center
+
+By default, ``external_inbound_acl`` and ``external_outbound_acl`` will permit any traffic through.
+
+``internal_inbound_acl``, ``internal_outbound_acl``, ``dmz_inbound_acl`` and ``dmz_outbound_acl`` will deny any traffic by default, so must be configured to allow defined ``src_port`` and ``dst_port`` or ``protocol``.
+
+See :py:mod:`primaite.simulator.network.hardware.nodes.network.router.AccessControlList`
+
+See :ref:`List of Ports <List of Ports>` for a list of ports.
+
+``internal_inbound_acl``
+""""""""""""""""""""""""
+
+ACL rules for packets that have a destination IP address in what is considered the internal network.
+
+example:
+
+.. code-block:: yaml
+
+    nodes:
+        - ref: firewall
+        ...
+        acl:
+            internal_inbound_acl:
+                21: # position 21 on ACL list
+                    action: PERMIT  # allow packets that
+                    src_port: POSTGRES_SERVER   # are emitted from the POSTGRES_SERVER port
+                    dst_port: POSTGRES_SERVER   # are going towards an POSTGRES_SERVER port
+                22: # position 22 on ACL list
+                    action: PERMIT  # allow packets that
+                    src_port: ARP   # are emitted from the ARP port
+                    dst_port: ARP   # are going towards an ARP port
+                23: # position 23 on ACL list
+                    action: PERMIT  # allow packets that
+                    protocol: ICMP  # are ICMP
+
+``internal_outbound_acl``
+"""""""""""""""""""""""""
+
+ACL rules for packets that have a source IP address in what is considered the internal network and is going towards the DMZ network or the external network.
+
+example:
+
+.. code-block:: yaml
+
+    nodes:
+        - ref: firewall
+        ...
+        acl:
+            internal_outbound_acl:
+                21: # position 21 on ACL list
+                    action: PERMIT  # allow packets that
+                    src_port: POSTGRES_SERVER   # are emitted from the POSTGRES_SERVER port
+                    dst_port: POSTGRES_SERVER   # are going towards an POSTGRES_SERVER port
+                22: # position 22 on ACL list
+                    action: PERMIT  # allow packets that
+                    src_port: ARP   # are emitted from the ARP port
+                    dst_port: ARP   # are going towards an ARP port
+                23: # position 23 on ACL list
+                    action: PERMIT  # allow packets that
+                    protocol: ICMP  # are ICMP
+
+
+``dmz_inbound_acl``
+"""""""""""""""""""
+
+ACL rules for packets that have a destination IP address in what is considered the DMZ network.
+
+example:
+
+.. code-block:: yaml
+
+    nodes:
+        - ref: firewall
+        ...
+        acl:
+            dmz_inbound_acl:
+                19: # position 19 on ACL list
+                    action: PERMIT  # allow packets that
+                    src_port: POSTGRES_SERVER   # are emitted from the POSTGRES_SERVER port
+                    dst_port: POSTGRES_SERVER   # are going towards an POSTGRES_SERVER port
+                20: # position 20 on ACL list
+                    action: PERMIT  # allow packets that
+                    src_port: HTTP   # are emitted from the HTTP port
+                    dst_port: HTTP   # are going towards an HTTP port
+                21: # position 21 on ACL list
+                    action: PERMIT  # allow packets that
+                    src_port: HTTPS   # are emitted from the HTTPS port
+                    dst_port: HTTPS   # are going towards an HTTPS port
+                22: # position 22 on ACL list
+                    action: PERMIT  # allow packets that
+                    src_port: ARP   # are emitted from the ARP port
+                    dst_port: ARP   # are going towards an ARP port
+                23: # position 23 on ACL list
+                    action: PERMIT  # allow packets that
+                    protocol: ICMP  # are ICMP
+
+``dmz_outbound_acl``
+""""""""""""""""""""
+
+ACL rules for packets that have a source IP address in what is considered the DMZ network and is going towards the internal network or the external network.
+
+example:
+
+.. code-block:: yaml
+
+    nodes:
+        - ref: firewall
+        ...
+        acl:
+            dmz_outbound_acl:
+                19: # position 19 on ACL list
+                    action: PERMIT  # allow packets that
+                    src_port: POSTGRES_SERVER   # are emitted from the POSTGRES_SERVER port
+                    dst_port: POSTGRES_SERVER   # are going towards an POSTGRES_SERVER port
+                20: # position 20 on ACL list
+                    action: PERMIT  # allow packets that
+                    src_port: HTTP   # are emitted from the HTTP port
+                    dst_port: HTTP   # are going towards an HTTP port
+                21: # position 21 on ACL list
+                    action: PERMIT  # allow packets that
+                    src_port: HTTPS   # are emitted from the HTTPS port
+                    dst_port: HTTPS   # are going towards an HTTPS port
+                22: # position 22 on ACL list
+                    action: PERMIT  # allow packets that
+                    src_port: ARP   # are emitted from the ARP port
+                    dst_port: ARP   # are going towards an ARP port
+                23: # position 23 on ACL list
+                    action: PERMIT  # allow packets that
+                    protocol: ICMP  # are ICMP
+
+
+
+``external_inbound_acl``
+""""""""""""""""""""""""
+
+Optional. By default, this will allow any traffic through.
+
+ACL rules for packets that have a destination IP address in what is considered the external network.
+
+example:
+
+.. code-block:: yaml
+
+    nodes:
+        - ref: firewall
+        ...
+        acl:
+            external_inbound_acl:
+                21: # position 19 on ACL list
+                    action: DENY  # deny packets that
+                    src_port: POSTGRES_SERVER   # are emitted from the POSTGRES_SERVER port
+                    dst_port: POSTGRES_SERVER   # are going towards an POSTGRES_SERVER port
+                22: # position 22 on ACL list
+                    action: PERMIT  # allow packets that
+                    src_port: ARP   # are emitted from the ARP port
+                    dst_port: ARP   # are going towards an ARP port
+                23: # position 23 on ACL list
+                    action: PERMIT  # allow packets that
+                    protocol: ICMP  # are ICMP
+
+``external_outbound_acl``
+"""""""""""""""""""""""""
+
+Optional. By default, this will allow any traffic through.
+
+ACL rules for packets that have a source IP address in what is considered the external network and is going towards the DMZ network or the internal network.
+
+example:
+
+.. code-block:: yaml
+
+    nodes:
+        - ref: firewall
+        ...
+        acl:
+            external_outbound_acl:
+                22: # position 22 on ACL list
+                    action: PERMIT  # allow packets that
+                    src_port: ARP   # are emitted from the ARP port
+                    dst_port: ARP   # are going towards an ARP port
+                23: # position 23 on ACL list
+                    action: PERMIT  # allow packets that
+                    protocol: ICMP  # are ICMP
+
+.. include:: common/common_network_node_attributes.rst
+
+.. |NODE| replace:: firewall
+.. |NODE_TYPE| replace:: ``firewall``

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

@@ -0,0 +1,127 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+.. _router_configuration:
+
+``router``
+==========
+
+A basic representation of a network router within the simulation.
+
+See :py:mod:`primaite.simulator.network.hardware.nodes.network.router.Router`
+
+example router
+--------------
+
+.. code-block:: yaml
+
+    simulation:
+        network:
+            nodes:
+                - ref: router_1
+                hostname: router_1
+                type: router
+                num_ports: 5
+                ports:
+                    ...
+                acl:
+                    ...
+
+.. include:: common/common_node_attributes.rst
+
+.. include:: common/node_type_list.rst
+
+``num_ports``
+-------------
+
+Optional. Default value is ``5``.
+
+The number of ports the router will have.
+
+``ports``
+---------
+
+Sets up the router's ports with an IP address and a subnet mask.
+
+Example of setting ports for a router with 2 ports:
+
+.. code-block:: yaml
+
+    nodes:
+        - ref: router_1
+        ...
+        ports:
+            1:
+                ip_address: 192.168.1.1
+                subnet_mask: 255.255.255.0
+            2:
+                ip_address: 192.168.10.1
+                subnet_mask: 255.255.255.0
+
+``ip_address``
+""""""""""""""
+
+The IP address for the given port. This must be a valid octet i.e. in the range of ``0.0.0.0`` and ``255.255.255.255``.
+
+``subnet_mask``
+"""""""""""""""
+
+Optional. Default value is ``255.255.255.0``.
+
+The subnet mask setting for the port.
+
+``acl``
+-------
+
+Sets up the ACL rules for the router.
+
+e.g.
+
+.. code-block:: yaml
+
+    nodes:
+        - ref: router_1
+        ...
+        acl:
+            1:
+                action: PERMIT
+                src_port: ARP
+                dst_port: ARP
+            2:
+                action: PERMIT
+                protocol: ICMP
+
+See :py:mod:`primaite.simulator.network.hardware.nodes.network.router.AccessControlList`
+
+See :ref:`List of Ports <List of Ports>` for a list of ports.
+
+``action``
+""""""""""
+
+Available options are
+
+- ``PERMIT`` : Allows the specified ``protocol`` or ``src_port`` and ``dst_port`` pairs
+- ``DENY`` : Blocks the specified ``protocol`` or ``src_port`` and ``dst_port`` pairs
+
+``src_port``
+""""""""""""
+
+Is used alongside ``dst_port``. Specifies the port where a packet originates. Used by the ACL Rule to determine if a packet with a specific source port is allowed to pass through the network node.
+
+``dst_port``
+""""""""""""
+
+Is used alongside ``src_port``. Specifies the port where a packet is destined to arrive. Used by the ACL Rule to determine if a packet with a specific destination port is allowed to pass through the network node.
+
+``protocol``
+""""""""""""
+
+Specifies which protocols are allowed by the ACL Rule to pass through the network node.
+
+See :ref:`List of IPProtocols <List of IPProtocols>` for a list of protocols.
+
+.. include:: common/common_network_node_attributes.rst
+
+.. |NODE| replace:: router
+.. |NODE_TYPE| replace:: ``router``

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

@@ -0,0 +1,41 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+.. _server_configuration:
+
+``server``
+==========
+
+A basic representation of a server within the simulation.
+
+See :py:mod:`primaite.simulator.network.hardware.nodes.host.server.Server`
+
+example server
+--------------
+
+.. code-block:: yaml
+
+    simulation:
+        network:
+            nodes:
+                - ref: server_1
+                hostname: server_1
+                type: server
+                ip_address: 192.168.10.10
+                subnet_mask: 255.255.255.0
+                default_gateway: 192.168.10.1
+                dns_server: 192.168.1.10
+                applications:
+                    ...
+                services:
+                    ...
+
+.. include:: common/common_node_attributes.rst
+
+.. include:: common/node_type_list.rst
+
+.. include:: common/common_host_node_attributes.rst
+
+.. |NODE| replace:: server
+.. |NODE_TYPE| replace:: ``server``

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

@@ -0,0 +1,39 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+.. _switch_configuration:
+
+``switch``
+==========
+
+A basic representation of a network switch within the simulation.
+
+See :py:mod:`primaite.simulator.network.hardware.nodes.network.switch.Switch`
+
+example switch
+--------------
+
+.. code-block:: yaml
+
+    simulation:
+        network:
+            nodes:
+                - ref: switch_1
+                hostname: switch_1
+                type: switch
+                num_ports: 8
+
+.. include:: common/common_node_attributes.rst
+
+.. include:: common/node_type_list.rst
+
+``num_ports``
+-------------
+
+Optional. Default value is ``8``.
+
+The number of ports the switch will have.
+
+.. |NODE| replace:: switch
+.. |NODE_TYPE| replace:: ``switch``

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

@@ -0,0 +1,25 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+``applications``
+----------------
+
+List of available applications that can be installed on a |NODE| can be found in :ref:`List of Applications <List of Applications>`
+
+application in configuration
+""""""""""""""""""""""""""""
+
+Applications takes a list of applications as shown in the example below.
+
+.. code-block:: yaml
+
+    - ref: client_1
+    hostname: client_1
+    type: computer
+    ...
+    applications:
+        - ref: example_application
+        type: example_application_type
+        options:
+            # this section is different for each application

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

@@ -0,0 +1,25 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+``services``
+------------
+
+List of available services that can be installed on a |NODE| can be found in :ref:`List of Services <List of Services>`
+
+services in configuration
+"""""""""""""""""""""""""
+
+Services takes a list of services as shown in the example below.
+
+.. code-block:: yaml
+
+    - ref: client_1
+    hostname: client_1
+    type: computer
+    ...
+    applications:
+        - ref: example_service
+        type: example_service_type
+        options:
+            # this section is different for each service

docs/source/custom_agent.rst

@@ -1,142 +0,0 @@
-.. only:: comment
-
-    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
-
-Custom Agents
-=============
-
-
-Integrating a user defined blue agent
-*************************************
-
-.. note::
-
-    If you are planning to implement custom RL agents into PrimAITE, you must use the project as a repository. If you install PrimAITE as a python package from wheel, custom agents are not supported.
-
-PrimAITE has integration with Ray RLLib and StableBaselines3 agents. All agents interface with PrimAITE through an :py:class:`primaite.agents.agent.AgentSessionABC<Agent Session>` which provides Input/Output of agent savefiles, as well as capturing and plotting performance metrics during training and evaluation. If you wish to integrate a custom blue agent, it is recommended to create a subclass of the :py:class:`primaite.agents.agent.AgentSessionABC` and implement the ``__init__()``, ``_setup()``,  ``_save_checkpoint()``, ``learn()``, ``evaluate()``, ``_get_latest_checkpoint``, ``load()``, and ``save()`` methods.
-
-Below is a barebones example of a custom agent implementation:
-
-.. code:: python
-
-    # src/primaite/agents/my_custom_agent.py
-
-    from primaite.agents.agent import AgentSessionABC
-    from primaite.common.enums import AgentFramework, AgentIdentifier
-
-    class CustomAgent(AgentSessionABC):
-        def __init__(self, training_config_path, lay_down_config_path):
-            super().__init__(training_config_path, lay_down_config_path)
-            assert self._training_config.agent_framework == AgentFramework.CUSTOM
-            assert self._training_config.agent_identifier == AgentIdentifier.MY_AGENT
-            self._setup()
-
-        def _setup(self):
-            super()._setup()
-            self._env = Primaite(
-                training_config_path=self._training_config_path,
-                lay_down_config_path=self._lay_down_config_path,
-                session_path=self.session_path,
-                timestamp_str=self.timestamp_str,
-        )
-            self._agent = ... # your code to setup agent
-
-        def _save_checkpoint(self):
-            checkpoint_num = self._training_config.checkpoint_every_n_episodes
-            episode_count = self._env.episode_count
-            save_checkpoint = False
-            if checkpoint_num:
-                save_checkpoint = episode_count % checkpoint_num == 0
-            # saves checkpoint if the episode count is not 0 and save_checkpoint flag was set to true
-            if episode_count and save_checkpoint:
-                ...
-                # your code to save checkpoint goes here.
-                # The path should start with self.checkpoints_path and include the episode number.
-
-        def learn(self):
-            ...
-            # call your agent's learning function here.
-
-            super().learn() # this will finalise learning and output session metadata
-            self.save()
-
-        def evaluate(self):
-            ...
-            # call your agent's evaluation function here.
-
-            self._env.close()
-            super().evaluate()
-
-        def _get_latest_checkpoint(self):
-            ...
-            # Load an agent from file.
-
-        @classmethod
-        def load(cls, path):
-            ...
-            # Create a CustomAgent object which loads model weights from file.
-
-        def save(self):
-            ...
-            # Call your agent's function that saves it to a file
-
-
-You will also need to modify :py:class:`primaite.primaite_session.PrimaiteSession<PrimaiteSession>` and :py:mod:`primaite.common.enums` to capture your new agent identifiers.
-
-.. code-block:: python
-    :emphasize-lines: 17, 18
-
-    # src/primaite/common/enums.py
-
-    class AgentIdentifier(Enum):
-        """The Red Agent algo/class."""
-        A2C = 1
-        "Advantage Actor Critic"
-        PPO = 2
-        "Proximal Policy Optimization"
-        HARDCODED = 3
-        "The Hardcoded agents"
-        DO_NOTHING = 4
-        "The DoNothing agents"
-        RANDOM = 5
-        "The RandomAgent"
-        DUMMY = 6
-        "The DummyAgent"
-        CUSTOM_AGENT = 7
-        "Your custom agent"
-
-.. code-block:: python
-    :emphasize-lines: 3, 11, 12
-
-    # src/primaite_session.py
-
-    from primaite.agents.my_custom_agent import CustomAgent
-
-    # ...
-
-        def setup(self):
-        """Performs the session setup."""
-        if self._training_config.agent_framework == AgentFramework.CUSTOM:
-            _LOGGER.debug(f"PrimaiteSession Setup: Agent Framework = {AgentFramework.CUSTOM}")
-            if self._training_config.agent_identifier == AgentIdentifier.CUSTOM_AGENT:
-                self._agent_session = CustomAgent(self._training_config_path, self._lay_down_config_path)
-            if self._training_config.agent_identifier == AgentIdentifier.HARDCODED:
-                _LOGGER.debug(f"PrimaiteSession Setup: Agent Identifier =" f" {AgentIdentifier.HARDCODED}")
-                if self._training_config.action_type == ActionType.NODE:
-                    # Deterministic Hardcoded Agent with Node Action Space
-                    self._agent_session = HardCodedNodeAgent(self._training_config_path, self._lay_down_config_path)
-
-Finally, specify your agent in your training config.
-
-.. code-block:: yaml
-
-    # ~/primaite/2.0.0/config/path/to/your/config_main.yaml
-
-    # Training Config File
-
-    agent_framework: CUSTOM
-    agent_identifier: CUSTOM_AGENT
-    random_red_agent: False
-    # ...
-
-Now you can :ref:`run a primaite session<run a primaite session>` with your custom agent by passing in the custom ``config_main``.

docs/source/customising_scenarios.rst

@@ -0,0 +1,4 @@
+Customising Agents
+******************
+
+For an example of how to customise red agent behaviour in the Data Manipulation scenario, please refer to the notebook ``Data-Manipulation-Customising-Red-Agent.ipynb``.

docs/source/dependencies.rst

@@ -1,10 +1,12 @@
 .. only:: comment
 
-    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
 
 .. role::  raw-html(raw)
     :format: html
 
+.. _Dependencies:
+
 Dependencies
 ============
 

docs/source/developer_tools.rst

@@ -0,0 +1,210 @@
+.. only:: comment
+
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+
+.. _Developer Tools:
+
+Developer Tools
+***************
+
+PrimAITE includes developer CLI tools that are intended to be used by developers.
+
+dev-mode
+========
+
+The dev-mode contains configuration which override any of the config files during runtime.
+
+This is intended to make debugging easier by removing the need to find the relevant configuration file/settings.
+
+Enabling dev-mode
+-----------------
+
+The PrimAITE dev-mode can be enabled via the use of
+
+.. code-block::
+
+    primaite dev-mode enable
+
+Disabling dev-mode
+------------------
+
+The PrimAITE dev-mode can be disabled via the use of
+
+.. code-block::
+
+    primaite dev-mode disable
+
+Show current mode
+-----------------
+
+To show if the dev-mode is enabled or not, use
+The PrimAITE dev-mode can be disabled via the use of
+
+.. code-block::
+
+    primaite dev-mode show
+
+dev-mode configuration
+======================
+
+The following configures some specific items that the dev-mode overrides, if enabled.
+
+`--sys-log-level` or `-level`
+----------------------------
+
+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]
+
+.. code-block::
+
+    primaite dev-mode config -level INFO
+
+or
+
+.. code-block::
+
+    primaite dev-mode config --sys-log-level INFO
+
+`--output-sys-logs` or `-sys`
+-----------------------------
+
+The outputting 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
+
+.. code-block::
+
+    primaite dev-mode config --output-sys-logs
+
+or
+
+.. code-block::
+
+    primaite dev-mode config -sys
+
+Disabling system logs
+"""""""""""""""""""""
+
+To disable outputting of system logs
+
+.. code-block::
+
+    primaite dev-mode config --no-sys-logs
+
+or
+
+.. code-block::
+
+    primaite dev-mode config -nsys
+
+`--output-pcap-logs` or `-pcap`
+-------------------------------
+
+The outputting 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
+
+.. code-block::
+
+    primaite dev-mode config --output-pcap-logs
+
+or
+
+.. code-block::
+
+    primaite dev-mode config -pcap
+
+Disabling PCAP logs
+"""""""""""""""""""
+
+To disable outputting of packet capture logs
+
+.. code-block::
+
+    primaite dev-mode config --no-pcap-logs
+
+or
+
+.. code-block::
+
+    primaite dev-mode config -npcap
+
+`--output-to-terminal` or `-t`
+------------------------------
+
+The outputting 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
+
+.. code-block::
+
+    primaite dev-mode config --output-to-terminal
+
+or
+
+.. code-block::
+
+    primaite dev-mode config -t
+
+Disabling system log output to terminal
+"""""""""""""""""""""""""""""""""""""""
+
+To disable outputting of system logs to terminal
+
+.. code-block::
+
+    primaite dev-mode config --no-terminal
+
+or
+
+.. code-block::
+
+    primaite dev-mode config -nt
+
+path
+----
+
+PrimAITE dev-mode can override where sessions are output.
+
+By default, PrimAITE will output the sessions in USER_HOME/primaite/sessions
+
+With dev-mode enabled, by default, this will be changed to PRIMAITE_REPOSITORY_ROOT/sessions
+
+However, providing a path will let dev-mode output sessions to the given path e.g.
+
+.. code-block:: bash
+    :caption: Unix
+
+    primaite dev-mode config path ~/output/path
+
+.. code-block:: powershell
+    :caption: Windows (Powershell)
+
+    primaite dev-mode config path ~\output\path
+
+default path
+""""""""""""
+
+To reset the path to use the PRIMAITE_REPOSITORY_ROOT/sessions, run the command
+
+.. code-block::
+
+    primaite dev-mode config path --default

docs/source/environment.rst

@@ -0,0 +1,10 @@
+RL Environments
+***************
+
+RL environments are the objects that directly interface with RL libraries such as Stable-Baselines3 and Ray RLLib. The PrimAITE simulation is exposed via three different environment APIs:
+
+* Gymnasium API - this is the standard interface that works with many RL libraries like SB3, Ray, Tianshou, etc.  ``PrimaiteGymEnv`` adheres to the `Official Gymnasium documentation <https://gymnasium.farama.org/api/env/>`_.
+* Ray Single agent API - For training a single Ray RLLib agent
+* Ray MARL API - For training multi-agent systems with Ray RLLib. ``PrimaiteRayMARLEnv`` adheres to the `Official Ray documentation <https://docs.ray.io/en/latest/rllib/package_ref/env/multi_agent_env.html>`_.
+
+There are Jupyter notebooks which demonstrate integration with each of these three environments. They are located in ``~/primaite/<VERSION>/notebooks/example_notebooks``.

docs/source/example_notebooks.rst

@@ -0,0 +1,82 @@
+.. only:: comment
+
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+
+Example Jupyter Notebooks
+=========================
+
+Executed Notebooks
+------------------
+
+There are a few example notebooks included which help with the understanding of PrimAITE's capabilities.
+
+The PrimAITE documentation includes a pre executed example of notebooks. See :ref:`Executed Notebooks`.
+
+In order to run the notebooks interactively, :ref:`install PrimAITE <getting-started>` and follow these steps:
+
+Running Jupyter Notebooks
+-------------------------
+
+1. Navigate to the PrimAITE directory
+
+.. code-block:: bash
+    :caption: Unix
+
+    cd ~/primaite/{VERSION}
+
+.. code-block:: powershell
+    :caption: Windows (Powershell)
+
+    cd ~\primaite\{VERSION}
+
+2. Run jupyter notebook (the python environment to which you installed PrimAITE must be active)
+
+.. code-block:: bash
+    :caption: Unix
+
+    jupyter notebook
+
+.. code-block:: powershell
+    :caption: Windows (Powershell)
+
+    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.
+
+
+Running Jupyter Notebooks via VSCode
+------------------------------------
+
+It is also possible to view the Jupyter notebooks within VSCode.
+
+The best place to start is by opening a notebook file (.ipynb) in VSCode. If using VSCode to view a notebook for the first time, follow the steps below.
+
+Installing extensions
+"""""""""""""""""""""
+
+VSCode may need some extensions to be installed if not already done.
+To do this, press the "Select Kernel" button on the top right.
+
+This should open a dialog which has the option to install python and jupyter extensions.
+
+.. image:: ../../_static/notebooks/install_extensions.png
+    :width: 700
+    :align: center
+    :alt: ::    The top dialog option that appears will automatically install the extensions
+
+The following extensions should now be installed
+
+.. image:: ../../_static/notebooks/extensions.png
+    :width: 300
+    :align: center
+
+VSCode will then ask for a Python environment version to use. PrimAITE is compatible with Python versions 3.8 - 3.11
+
+You should now be able to interact with the notebook.

docs/source/game_layer.rst

@@ -0,0 +1,87 @@
+PrimAITE Game layer
+*******************
+
+The Primaite codebase consists of two main modules:
+
+* ``simulator``: The simulation logic including the network topology, the network state, and behaviour of various hardware and software classes.
+* ``game``: The agent-training infrastructure which helps reinforcement learning agents interface with the simulation. This includes the observation, action, and rewards, for RL agents, but also scripted deterministic agents. The game layer orchestrates all the interactions between modules.
+
+The simulator and game layer communicate using the PrimAITE State API and the PrimAITE Request API.
+
+The game layer is responsible for managing agents and getting them to interface with the simulator correctly. It consists of several components:
+
+
+Agents
+======
+
+All agents inherit from the :py:class:`primaite.game.agent.interface.AbstractAgent` class, which mandates that they have an ObservationManager, ActionManager, and RewardManager. The agent behaviour depends on the type of agent, but there are two main types:
+
+* RL agents action during each step is decided by an appropriate RL algorithm. The agent within PrimAITE just acts to format and forward actions decided by an RL policy.
+* Deterministic agents perform all of their decision making within the PrimAITE game layer. They typically have a scripted policy which always performs the same action or a rule-based policy which performs actions based on the current state of the simulation. They can have a stochastic element, and their seed is settable.
+
+
+Observations
+============
+
+An agent's observations are managed by the ``ObservationManager`` class. It generates observations based on the current simulation state dictionary. It also provides the observation space during initial setup. The data is formatted so it's compatible with ``Gymnasium.spaces``. Observation spaces are composed of one or more components which are defined by the ``AbstractObservation`` base class.
+
+Actions
+=======
+
+An agent's actions are managed by the ``ActionManager``. It converts actions selected by agents (which are typically integers chosen from a ``gymnasium.spaces.Discrete`` space) into simulation-friendly requests. It also provides the action space during initial setup. Action spaces are composed of one or more components which are defined by the ``AbstractAction`` base class.
+
+Rewards
+=======
+
+An agent's reward function is managed by the ``RewardManager``. It calculates rewards based on the simulation state (in a way similar to observations). Rewards can be defined as a weighted sum of small reward components. For example, an agents reward can be based on the uptime of a database service plus the loss rate of packets between clients and a web server.
+
+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`.
+
+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:
+
+        # 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
+
+        # 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
+
+blue_agent:
+    # actions, observations, and agent settings go here
+    reward_function:
+      reward_components:
+
+        # When the database file is in a good state, blue's reward is 0.4, when it's in a corrupted state the reward is -0.4
+        - type: DATABASE_FILE_INTEGRITY
+          weight: 0.40
+          options:
+            node_hostname: database_server
+            folder_name: database
+            file_name: database.db
+
+        # The green's reward is added onto the blue's reward.
+        - type: SHARED_REWARD
+          weight: 1.0
+          options:
+            agent_name: client_2_green_user
+
+```
+
+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

@@ -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
 
 .. _getting-started:
 
@@ -11,12 +11,10 @@ Getting Started
 
 Pre-Requisites
 
-In order to get **PrimAITE** installed, you will need to have a python version between 3.8 and 3.10 installed. If you don't already have it, this is how to install it:
+In order to get **PrimAITE** installed, you will need Python, venv, and pip. If you don't already have them, this is how to install it:
 
 
-.. tabs:: lang
-
-    .. code-tab:: bash
+.. code-block:: bash
     :caption: Unix
 
     sudo add-apt-repository ppa:deadsnakes/ppa
@@ -24,86 +22,81 @@ In order to get **PrimAITE** installed, you will need to have a python version b
     sudo apt-get install python3-pip
     sudo apt-get install python3-venv
 
-    .. code-tab:: text
+
+.. code-block:: text
     :caption: Windows (Powershell)
 
     - Manual install from: https://www.python.org/downloads/release/python-31011/
 
 **PrimAITE** is designed to be OS-agnostic, and thus should work on most variations/distros of Linux, Windows, and MacOS.
 
+Installing PrimAITE has been tested with all supported python versions, venv 20.24.1, and pip 23.
+
 Install PrimAITE
 ****************
 
-1. Create a primaite directory in your home directory:
+1. Create a directory for your PrimAITE project:
 
-.. tabs:: lang
-
-    .. code-tab:: bash
+.. code-block:: bash
     :caption: Unix
 
-        mkdir ~/primaite/2.0.0
+    mkdir -p ~/primaite/{VERSION}
 
-    .. code-tab:: powershell
+.. code-block:: powershell
     :caption: Windows (Powershell)
 
-        mkdir ~\primaite\2.0.0
+    mkdir ~\primaite\{VERSION}
+
 
 2. Navigate to the primaite directory and create a new python virtual environment (venv)
 
-.. tabs:: lang
-
-    .. code-tab:: bash
+.. code-block:: bash
     :caption: Unix
 
-        cd ~/primaite/2.0.0
+    cd ~/primaite/{VERSION}
     python3 -m venv .venv
 
-    .. code-tab:: powershell
+.. code-block:: powershell
     :caption: Windows (Powershell)
 
-        cd ~\primaite\2.0.0
+        cd ~\primaite\{VERSION}
         python3 -m venv .venv
         attrib +h .venv /s /d # Hides the .venv directory
 
+
 3. Activate the venv
 
-.. tabs:: lang
-
-    .. code-tab:: bash
+.. code-block:: bash
     :caption: Unix
 
     source .venv/bin/activate
 
-    .. code-tab:: powershell
+.. code-block:: powershell
     :caption: Windows (Powershell)
 
     .\.venv\Scripts\activate
 
 
-4. Install PrimAITE using pip from PyPi
+4. Install PrimAITE from your saved wheel file
 
-.. tabs:: lang
-
-    .. code-tab:: bash
+.. code-block:: bash
     :caption: Unix
 
-        pip install primaite
+    pip install path/to/your/primaite.whl[rl]
 
-    .. code-tab:: powershell
+.. code-block:: powershell
     :caption: Windows (Powershell)
 
-        pip install primaite
+    pip install path\to\your\primaite.whl
 
 5. Perform the PrimAITE setup
 
-.. tabs:: lang
-
-    .. code-tab:: bash
+.. code-block:: bash
     :caption: Unix
 
     primaite setup
 
-    .. code-tab:: powershell
+.. code-block:: powershell
     :caption: Windows (Powershell)
 
         primaite setup
@@ -114,42 +107,67 @@ Clone & Install PrimAITE for Development
 To be able to extend PrimAITE further, or to build wheels manually before install, clone the repository to a location
 of your choice:
 
-.. TODO:: Add repo path once we know what it is
+1. Clone the repository.
+
+For example:
 
 .. code-block:: bash
 
-    git clone <repo path>
+    git clone https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE
     cd primaite
 
-Create and activate your Python virtual environment (venv)
+2. Create and activate your Python virtual environment (venv)
 
-.. tabs:: lang
-
-    .. code-tab:: bash
+.. code-block:: bash
     :caption: Unix
 
     python3 -m venv venv
     source venv/bin/activate
 
-    .. code-tab:: powershell
+.. code-block:: powershell
     :caption: Windows (Powershell)
 
     python3 -m venv venv
     .\venv\Scripts\activate
 
-Install PrimAITE with the dev extra
+3. Install PrimAITE with the dev extra
 
-.. tabs:: lang
-
-    .. code-tab:: bash
+.. code-block:: bash
     :caption: Unix
 
-        pip install -e .[dev]
+    pip install -e .[dev,rl]
 
-    .. code-tab:: powershell
+.. code-block:: powershell
     :caption: Windows (Powershell)
 
-        pip install -e .[dev]
-
+    pip install -e .[dev,rl]
 
 To view the complete list of packages installed during PrimAITE installation, go to the dependencies page (:ref:`Dependencies`).
+
+4. Set PrimAITE to run on development mode
+
+Running step 3 should have installed PrimAITE, verify this by running
+
+.. code-block:: bash
+    :caption: Unix
+
+    primaite setup
+
+.. code-block:: powershell
+    :caption: Windows (Powershell)
+
+    primaite setup
+
+To set PrimAITE to run in development mode:
+
+.. code-block:: bash
+    :caption: Unix
+
+    primaite dev-mode enable
+
+.. code-block:: powershell
+    :caption: Windows (Powershell)
+
+    primaite dev-mode enable
+
+More information about :ref:`Developer Tools`

docs/source/glossary.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
 
 Glossary
 =============
@@ -38,14 +38,11 @@ Glossary
     Blue Agent
         A defensive agent that protects the network from Red Agent attacks to minimise disruption to green agents and protect data.
 
-    Information Exchange Requirement (IER)
-        Simulates network traffic by sending data from one network node to another via links for a specified amount of time. IERs can be part of green agent behaviour or red agent behaviour. PrimAITE can be configured to apply a penalty for green agents' IERs being blocked and a reward for red agents' IERs being blocked.
-
     Pattern-of-Life (PoL)
         PoLs allow agents to change the current hardware, OS, file system, or service statuses of nodes during the course of an episode. For example, a green agent may restart a server node to represent scheduled maintainance. A red agent's Pattern-of-Life can be used to attack nodes by changing their states to CORRUPTED or COMPROMISED.
 
     Reward
-        The reward is a single number used by the blue agent to understand whether it's performing well or poorly. RL agents change their behaviour in an attempt to increase the expected reward each episode. The reward is generated based on the current states of the environment / :term:`reference environment` and is impacted positively by things like green IERS running successfully and negatively by things like nodes being compromised.
+        The reward is a single number used by the blue agent to understand whether it's performing well or poorly. RL agents change their behaviour in an attempt to increase the expected reward each episode. The reward is generated based on the current states of the environment and is impacted positively by things like green PoL running successfully and negatively by things like nodes being compromised.
 
     Observation
         An observation is a representation of the current state of the environment that is given to the learning agent so it can decide on which action to perform. If the environment is 'fully observable', the observation contains information about every possible aspect of the environment. More commonly, the environment is 'partially observable' which means the learning agent has to make decisions without knowing every detail of the current environment state.
@@ -65,17 +62,11 @@ Glossary
     Episode
         When an episode starts, the network simulation is reset to an initial state. The agents take actions on each step of the episode until it reaches a terminal state, which usually happens after a predetermined number of steps. After the terminal state is reached, a new episode starts and the RL agent has another opportunity to protect the network.
 
-    Reference environment
-        While the network simulation is unfolding, a parallel simulation takes place which is identical to the main one except that blue and red agent actions are not applied. This reference environment essentially shows what would be happening to the network if there had been no cyberattack or defense. The reference environment is used to calculate rewards.
-
-    Transaction
-        PrimAITE records the decisions of the learning agent by saving its observation, action, and reward at every time step. During each session, this data is saved to disk to allow for full inspection.
-
     Laydown
         The laydown is a file which defines the training scenario. It contains the network topology, firewall rules, services, protocols, and details about green and red agent behaviours.
 
-    Gym
-        PrimAITE uses the Gym reinforcement learning framework API to create a training environment and interface with RL agents. Gym defines a common way of creating observations, actions, and rewards.
+    Gymnasium
+        PrimAITE uses the Gymnasium reinforcement learning framework API to create a training environment and interface with RL agents. Gymnasium defines a common way of creating observations, actions, and rewards.
 
     User app home
-        PrimAITE supports upgrading software version while retaining user data. The user data directory is where configs, notebooks, and results are stored, this location is `~/primaite<version>` on linux/darwin and `C:\Users\<username>\primaite\<version>` on Windows.
+        PrimAITE supports upgrading software version while retaining user data. The user data directory is where configs, notebooks, and results are stored, this location is `~/primaite<version>/` on linux/darwin and `C:\\Users\\<username>\\primaite<version>` on Windows.

docs/source/migration_1.2_-_2.0.rst

@@ -1,57 +0,0 @@
-.. only:: comment
-
-    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
-
-v1.2 to v2.0 Migration guide
-============================
-
-**1. Installing PrimAITE**
-
-    Like before, you can install primaite from the repository by running ``pip install -e .``. But, there is now an additional setup step which does several things, like setting up user directories, copy default configs and notebooks, etc. Once you have installed PrimAITE to your virtual environment, run this command to finalise setup.
-
-    .. code-block:: bash
-
-        primaite setup
-
-**2. Running a training session**
-
-    In version 1.2 of PrimAITE, the main entry point for training or evaluating agents was the ``src/primaite/main.py`` file. v2.0.0 introduced managed 'sessions' which are responsible for reading configuration files, performing training, and writing outputs.
-
-    ``main.py`` file still runs a training session but it now uses the new `PrimaiteSession`, and it now requires you to provide the path to your config files.
-
-    .. code-block:: bash
-
-        python src/primaite/main.py --tc path/to/training-config.yaml --ldc path/to/laydown-config.yaml
-
-    Alternatively, the session can be invoked via the commandline by running:
-
-    .. code-block:: bash
-
-        primaite session --tc path/to/training-config.yaml --ldc path/to/laydown-config.yaml
-
-**3. Location of configs**
-
-    In version 1.2, training configs and laydown configs were all stored in the project repository under ``src/primaite/config``. Version 2.0.0 introduced user data directories, and now when you install and setup PrimAITE, config files are stored in your user data location. On Linux/OSX, this is stored in ``~/primaite/2.0.0/config``. On Windows, this is stored in ``C:\Users\<your username>\primaite\configs``. Upon first setup, the configs folder is populated with some default yaml files. It is recommended that you store all your custom configuration files here.
-
-**4. Contents of configs**
-
-    Some things that were previously part of the laydown config are now part of the traning config.
-
-        * Actions
-
-    If you have custom configs which use these, you will need to adapt them by moving the configuration from the laydown config to the training config.
-
-    Also, there are new configurable items in the training config:
-
-        * Observations
-        * Agent framework
-        * Agent
-        * Deep learning framework
-        * random red agents
-        * seed
-        * deterministic
-        * hard coded agent view
-
-    Each of these items have default values which are designed so that PrimAITE has the same behaviour as it did in 1.2.0, so you do not have to specify them.
-
-    ACL Rules in laydown configs have a new required parameter: ``position``. The lower the position, the higher up in the ACL table the rule will placed. If you have custom laydowns, you will need to go through them and add a position to each ACL_RULE.

docs/source/notebooks/executed_notebooks.rst

@@ -0,0 +1,16 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+.. _Executed Notebooks:
+
+Executed Jupyter Notebooks
+==========================
+
+Below is a list of available pre-executed notebooks.
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    **/*

docs/source/primaite-dependencies.rst

@@ -0,0 +1,37 @@
++-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+----------------------------------------------+
+| 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            |
++-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+----------------------------------------------+

docs/source/primaite_session.rst

@@ -1,182 +0,0 @@
-.. only:: comment
-
-    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
-
-.. _run a primaite session:
-
-Run a PrimAITE Session
-======================
-
-Run
----
-
-A PrimAITE session can be ran either with the ``primaite session`` command from the cli
-(See :func:`primaite.cli.session`), or by calling :func:`primaite.main.run` from a Python terminal or Jupyter Notebook.
-Both the ``primaite session`` and :func:`primaite.main.run` take a training config and a lay down config as parameters.
-
-
-.. tabs::
-
-    .. code-tab:: bash
-        :caption: Unix CLI
-
-        cd ~/primaite/2.0.0
-        source ./.venv/bin/activate
-        primaite session --tc ./config/my_training_config.yaml --ldc ./config/my_lay_down_config.yaml
-
-    .. code-tab:: powershell
-        :caption: Powershell CLI
-
-        cd ~\primaite\2.0.0
-        .\.venv\Scripts\activate
-        primaite session --tc .\config\my_training_config.yaml --ldc .\config\my_lay_down_config.yaml
-
-
-    .. code-tab:: python
-        :caption: Python
-
-        from primaite.main import run
-
-        training_config = <path to training config yaml file>
-        lay_down_config = <path to lay down config yaml file>
-        run(training_config, lay_down_config)
-
-When a session is ran, a session output sub-directory is created in the users app sessions directory (``~/primaite/2.0.0/sessions``).
-The sub-directory is formatted as such: ``~/primaite/2.0.0/sessions/<yyyy-mm-dd>/<yyyy-mm-dd>_<hh-mm-dd>/``
-
-For example, when running a session at 17:30:00 on 31st January 2023, the session will output to:
-``~/primaite/2.0.0/sessions/2023-01-31/2023-01-31_17-30-00/``.
-
-``primaite session`` can be ran in the terminal/command prompt without arguments. It will use the default configs in the directory ``primaite/config/example_config``.
-
-
-Outputs
--------
-
-PrimAITE produces four types of outputs:
-
-* Session Metadata
-* Results
-* Diagrams
-* Saved agents (training checkpoints and a final trained agent)
-
-
-**Session Metadata**
-
-PrimAITE creates a ``session_metadata.json`` file that contains the following metadata:
-
-    * **uuid** - The UUID assigned to the session upon instantiation.
-    * **start_datetime** - The date & time the session started in iso format.
-    * **end_datetime** - The date & time the session ended in iso format.
-    * **learning**
-        * **total_episodes** - The total number of training episodes completed.
-        * **total_time_steps** - The total number of training time steps completed.
-    * **evaluation**
-        * **total_episodes** - The total number of evaluation episodes completed.
-        * **total_time_steps** - The total number of evaluation time steps completed.
-    * **env**
-        * **training_config**
-            * **All training config items**
-        * **lay_down_config**
-            * **All lay down config items**
-
-
-**Results**
-
-PrimAITE automatically creates two sets of results from each learning and evaluation session:
-
-* Average reward per episode - a csv file listing the average reward for each episode of the session. This provides, for example, an indication of the change over a training session of the reward value
-* All transactions - a csv file listing the following values for every step of every episode:
-
-    * Timestamp
-    * Episode number
-    * Step number
-    * Reward value
-    * Action taken (as presented by the blue agent on this step). Individual elements of the action space are presented in the format AS_X
-    * Initial observation space (what the blue agent observed when it decided its action)
-
-**Diagrams**
-
-* For each session, PrimAITE automatically creates a visualisation of the system / network lay down configuration.
-* For each learning and evaluation task within the session, PrimAITE automatically plots the average reward per episode using PlotLY and saves it to the learning or evaluation subdirectory in the session directory.
-
-**Saved agents**
-
-For each training session, assuming the agent being trained implements the *save()* function and this function is called by the code, PrimAITE automatically saves the agent state.
-
-**Example Session Directory Structure**
-
-.. code-block:: text
-
-    ~/
-    └── primaite/
-        └── 2.0.0/
-            └── sessions/
-                └── 2023-07-18/
-                    └── 2023-07-18_11-06-04/
-                        ├── evaluation/
-                        │   ├── all_transactions_2023-07-18_11-06-04.csv
-                        │   ├── average_reward_per_episode_2023-07-18_11-06-04.csv
-                        │   └── average_reward_per_episode_2023-07-18_11-06-04.png
-                        ├── learning/
-                        │   ├── all_transactions_2023-07-18_11-06-04.csv
-                        │   ├── average_reward_per_episode_2023-07-18_11-06-04.csv
-                        │   ├── average_reward_per_episode_2023-07-18_11-06-04.png
-                        │   ├── checkpoints/
-                        │   │   └── sb3ppo_10.zip
-                        │   ├── SB3_PPO.zip
-                        │   └── tensorboard_logs/
-                        │       ├── PPO_1/
-                        │       │   └── events.out.tfevents.1689674765.METD-9PMRFB3.42960.0
-                        │       ├── PPO_2/
-                        │       │   └── events.out.tfevents.1689674766.METD-9PMRFB3.42960.1
-                        │       ├── PPO_3/
-                        │       │   └── events.out.tfevents.1689674766.METD-9PMRFB3.42960.2
-                        │       ├── PPO_4/
-                        │       │   └── events.out.tfevents.1689674767.METD-9PMRFB3.42960.3
-                        │       ├── PPO_5/
-                        │       │   └── events.out.tfevents.1689674767.METD-9PMRFB3.42960.4
-                        │       ├── PPO_6/
-                        │       │   └── events.out.tfevents.1689674768.METD-9PMRFB3.42960.5
-                        │       ├── PPO_7/
-                        │       │   └── events.out.tfevents.1689674768.METD-9PMRFB3.42960.6
-                        │       ├── PPO_8/
-                        │       │   └── events.out.tfevents.1689674769.METD-9PMRFB3.42960.7
-                        │       ├── PPO_9/
-                        │       │   └── events.out.tfevents.1689674770.METD-9PMRFB3.42960.8
-                        │       └── PPO_10/
-                        │           └── events.out.tfevents.1689674770.METD-9PMRFB3.42960.9
-                        ├── network_2023-07-18_11-06-04.png
-                        └── session_metadata.json
-
-Loading a session
------------------
-
-A previous session can be loaded by providing the **directory** of the previous session to either the ``primaite session`` command from the cli
-(See :func:`primaite.cli.session`), or by calling :func:`primaite.main.run` with session_path.
-
-.. tabs::
-
-    .. code-tab:: bash
-        :caption: Unix CLI
-
-        cd ~/primaite/2.0.0
-        source ./.venv/bin/activate
-        primaite session --load "path/to/session"
-
-    .. code-tab:: bash
-        :caption: Powershell CLI
-
-        cd ~\primaite\2.0.0
-        .\.venv\Scripts\activate
-        primaite session --load "path\to\session"
-
-
-    .. code-tab:: python
-        :caption: Python
-
-        from primaite.main import run
-
-        run(session_path=<previous session directory>)
-
-When PrimAITE runs a loaded session, PrimAITE will output in the provided session directory

docs/source/request_system.rst

@@ -0,0 +1,136 @@
+.. only:: comment
+
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+
+Request System
+**************
+
+``SimComponent`` objects in the simulation are decoupled from the agent training logic. However, they still need a managed means of accepting requests to perform actions. For this, they use ``RequestManager`` and ``RequestType``.
+
+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:
+
+    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.
+
+    ``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
+
+    ``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:
+
+    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`` detail
+    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:
+
+    * **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.
+
+    * **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
+
+Technical Detail
+================
+
+This system was achieved by implementing two classes, :py:class:`primaite.simulator.core.RequestType`, and :py:class:`primaite.simulator.core.RequestManager`.
+
+``RequestType``
+---------------
+
+The ``RequestType`` object stores a reference to a method that executes the request, for example a node could have a request type that stores a reference to ``self.turn_on()``. Technically, this can be any callable that accepts `request, context` as it's parameters. In practice, this is often defined using ``lambda`` functions within a component's ``self._init_request_manager()`` method. Optionally, the ``RequestType`` object can also hold a validator that will permit/deny the request depending on context.
+
+``RequestManager``
+------------------
+
+The ``RequestManager`` object stores a mapping between strings and request types. It is responsible for processing the request and passing it down the ownership tree. Technically, the ``RequestManager`` is itself a callable that accepts `request, context` tuple, and so it can be chained with other request managers.
+
+A simple example without chaining can be seen in the :py:class:`primaite.simulator.file_system.file_system.File` class.
+
+.. code-block:: python
+
+    class File(FileSystemItemABC):
+        ...
+        def _init_request_manager(self):
+            ...
+            request_manager.add_request("scan", RequestType(func=lambda request, context: RequestResponse.from_bool(self.scan())))
+            request_manager.add_request("repair", RequestType(func=lambda request, context: RequestResponse.from_bool(self.repair())))
+            request_manager.add_request("restore", RequestType(func=lambda request, context: RequestResponse.from_bool(self.restore())))
+
+*ellipses (``...``) used to omit code impertinent to this explanation*
+
+Chaining RequestManagers
+------------------------
+
+A request function needs to be a callable that accepts ``request, context`` as parameters. Since the request manager resolves requests by invoking it with ``request, context`` as parameter, it is possible to use a ``RequestManager`` as a ``RequestType``.
+
+When a RequestManager accepts a request, it pops the first element and uses it to decide where it should send the remaining request. This is how PrimAITE traverses the ownership tree. If the ``RequestType`` has another ``RequestManager`` as its function, the request will be routed again. Each time the request is passed to a new request manager, the first element is popped.
+
+An example of how this works is in the :py:class:`primaite.simulator.network.hardware.base.Node` class.
+
+.. code-block:: python
+
+    class Node(SimComponent):
+        ...
+        def _init_request_manager(self):
+            ...
+            # a regular action which is processed by the Node itself
+            request_manager.add_request("turn_on", RequestType(func=lambda request, context: self.turn_on()))
+
+            # if the Node receives a request where the first word is 'service', it will use a dummy manager
+            # called self._service_request_manager to pass on the request to the relevant service. This dummy
+            # manager is simply here to map the service name that that service's own action manager. This is
+            # done because the next string after "service" is always the name of that service, so we need an
+            # RequestManager to pop that string before sending it onto the relevant service's RequestManager.
+            self._service_request_manager = RequestManager()
+            request_manager.add_request("service", RequestType(func=self._service_request_manager))
+            ...
+
+        def install_service(self, service):
+            self.services[service.name] = service
+            ...
+            # Here, the service name is registered to allow passing actions between the node and the service.
+            self._service_request_manager.add_request(service.name, RequestType(func=service._request_manager))
+
+This process is repeated until the request word corresponds to a callable function rather than another ``RequestManager`` .
+
+Request Validation
+------------------
+
+There are times when a request should be rejected. For instance, if an agent attempts to run an application on a node that is currently off. For this purpose, requests are filtered by an object called a validator. :py:class:`primaite.simulator.core.RequestPermissionValidator` is a basic class whose ``__call__()`` method returns ``True`` if the request should be permitted or ``False`` if it cannot be permitted. For example, the Node class has a validator called :py:class:`primaite.simulator.network.hardware.base.Node._NodeIsOnValidator<_NodeIsOnValidator>` which allows requests only when the operating status of the node is ``ON``.
+
+Requests that are specified without a validator automatically get assigned an ``AllowAllValidator`` which allows requests no matter what.
+
+Request Response
+----------------
+
+The :py:class:`primaite.interface.request.RequestResponse<RequestResponse>` carries response data between the simulator and the game layer. The ``status`` field reports on the success or failure, and the ``data`` field is for any additional data. The most common way that this class is used is by the ``from_bool`` method. This way, given a True or False, a successful or failed request response is generated, respectively (with an empty data field).
+
+For instance, the ``execute`` action on a :py:class:`primaite.simulator.system.applications.web_browser.WebBrowser<WebBrowser>` calls the ``get_webpage()`` method. ``get_webpage()`` returns a True if the webpage was successfully retrieved, and False if unsuccessful for any reason, such as being blocked by an ACL, or if the database server is unresponsive. The boolean returned from ``get_webpage()`` is used to create the request response with ``from_bool()``.
+
+Just as the requests themselves were passed from owner to component, the request response is bubbled back up from component to owner until it arrives at the game layer.

docs/source/simulation.rst

@@ -0,0 +1,34 @@
+.. only:: comment
+
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+
+
+Simulation
+==========
+
+
+
+
+Contents
+########
+
+.. toctree::
+   :maxdepth: 8
+
+   simulation_structure
+   simulation_components/network/base_hardware
+   simulation_components/network/network_interfaces
+   simulation_components/network/transport_to_data_link_layer
+   simulation_components/network/nodes/host_node
+   simulation_components/network/nodes/network_node
+   simulation_components/network/nodes/router
+   simulation_components/network/nodes/switch
+   simulation_components/network/nodes/wireless_router
+   simulation_components/network/nodes/firewall
+   simulation_components/network/switch
+   simulation_components/network/network
+   simulation_components/system/internal_frame_processing
+   simulation_components/system/sys_log
+   simulation_components/system/pcap
+   simulation_components/system/session_and_software_manager
+   simulation_components/system/software

docs/source/simulation_components/network/base_hardware.rst

@@ -0,0 +1,111 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+#############
+Base Hardware
+#############
+
+The ``base.py`` module in ``primaite.simulator.network.hardware`` provides foundational components, interfaces, and classes for
+modeling network hardware within PrimAITE simulations. It establishes core building blocks and abstractions that more
+complex, specialized hardware components inherit from and build upon.
+
+The key elements defined in ``base.py`` are:
+
+``NetworkInterface``
+====================
+
+- Abstract base class for network interfaces like NICs. Defines common attributes like MAC address, speed, MTU.
+- Requires subclasses to implement ``enable()``, ``disable()``, ``send_frame()`` and ``receive_frame()``.
+- Provides basic state description and request handling capabilities.
+
+``Node``
+========
+The Node class stands as a central component in ``base.py``, acting as the superclass for all network nodes within a
+PrimAITE simulation.
+
+Node Attributes
+---------------
+
+See :ref:`Node Attributes`
+
+.. _Node Start up and Shut down:
+
+Node Start up and Shut down
+---------------------------
+Nodes are powered on and off over multiple timesteps. By default, the node ``start_up_duration`` and ``shut_down_duration`` is 3 timesteps.
+
+Example code where a node is turned on:
+
+.. code-block:: python
+
+    from primaite.simulator.network.hardware.base import Node
+    from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState
+
+    node = Node(hostname="pc_a")
+
+    assert node.operating_state is NodeOperatingState.OFF # By default, node is instantiated in an OFF state
+
+    node.power_on() # power on the node
+
+    assert node.operating_state is NodeOperatingState.BOOTING # node is booting up
+
+    for i in range(node.start_up_duration + 1):
+        # apply timestep until the node start up duration
+        node.apply_timestep(timestep=i)
+
+    assert node.operating_state is NodeOperatingState.ON # node is in ON state
+
+
+If the node needs to be instantiated in an on state:
+
+
+.. code-block:: python
+
+    from primaite.simulator.network.hardware.base import Node
+    from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState
+
+    node = Node(hostname="pc_a", operating_state=NodeOperatingState.ON)
+
+    assert node.operating_state is NodeOperatingState.ON  # node is in ON state
+
+Setting ``start_up_duration`` and/or ``shut_down_duration`` to ``0`` will allow for the ``power_on`` and ``power_off`` methods to be completed instantly without applying timesteps:
+
+.. code-block:: python
+
+    from primaite.simulator.network.hardware.base import Node
+    from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState
+
+    node = Node(hostname="pc_a", start_up_duration=0, shut_down_duration=0)
+
+    assert node.operating_state is NodeOperatingState.OFF  # node is in OFF state
+
+    node.power_on()
+
+    assert node.operating_state is NodeOperatingState.ON  # node is in ON state
+
+    node.power_off()
+
+    assert node.operating_state is NodeOperatingState.OFF  # node is in OFF state
+
+Node Behaviours/Functions
+-------------------------
+
+
+- **connect_nic()**: Connects a ``NetworkInterface`` to the node for network communication.
+- **disconnect_nic()**: Removes a ``NetworkInterface`` from the node.
+- **receive_frame()**: Handles the processing of incoming network frames.
+- **apply_timestep()**: Advances the state of the node according to the simulation timestep.
+- **power_on()**: Initiates the node, enabling all connected Network Interfaces and starting all Services and
+  Applications, taking into account the `start_up_duration`.
+- **power_off()**: Stops the node's operations, adhering to the `shut_down_duration`.
+- **ping()**: Sends ICMP echo requests to a specified IP address to test connectivity.
+- **has_enabled_network_interface()**: Checks if the node has any network interfaces enabled, facilitating network
+  communication.
+- **show()**: Provides a summary of the node's current state, including network interfaces, operational status, and
+  other key attributes.
+
+
+The Node class handles installation of system software, network connectivity, frame processing, system logging, and
+power states. It establishes baseline functionality while allowing subclassing to model specific node types like hosts,
+routers, firewalls etc. The flexible architecture enables composing complex network topologies.

docs/source/simulation_components/network/network.rst

@@ -0,0 +1,115 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+.. _network:
+
+Network
+=======
+
+The ``Network`` class serves as the backbone of the simulation. It offers a framework to manage various network
+components such as routers, switches, servers, and clients. This document provides a detailed explanation of how to
+effectively use the ``Network`` class.
+
+Example Usage
+-------------
+
+Below demonstrates how to use the Router node to connect Nodes, and block traffic using ACLs. For this demonstration,
+we'll use the following Network that has a client, server, two switches, and a router.
+
+.. code-block:: text
+
+    +------------+      +------------+      +------------+      +------------+      +------------+
+    |            |      |            |      |            |      |            |      |            |
+    |  client_1  +------+  switch_2  +------+  router_1  +------+  switch_1  +------+  server_1  |
+    |            |      |            |      |            |      |            |      |            |
+    +------------+      +------------+      +------------+      +------------+      +------------+
+
+1. Relevant imports
+
+.. code-block:: python
+
+    from primaite.simulator.network.container import Network
+    from primaite.simulator.network.hardware.base import NetworkInterface
+    from primaite.simulator.network.hardware.nodes.host.computer import Computer
+    from primaite.simulator.network.hardware.nodes.network.router import Router, ACLAction
+    from primaite.simulator.network.hardware.nodes.host.server import Server
+    from primaite.simulator.network.hardware.nodes.network.switch import Switch
+    from primaite.simulator.network.transmission.network_layer import IPProtocol
+    from primaite.simulator.network.transmission.transport_layer import Port
+
+2. Create the Network
+
+.. code-block:: python
+
+    network = Network()
+
+3. Create and configure the Router
+
+.. code-block:: python
+
+    router_1 = Router(hostname="router_1", num_ports=3)
+    router_1.power_on()
+    router_1.configure_port(port=1, ip_address="192.168.1.1", subnet_mask="255.255.255.0")
+    router_1.configure_port(port=2, ip_address="192.168.2.1", subnet_mask="255.255.255.0")
+
+4. Create and configure the two Switches
+
+.. code-block:: python
+
+    switch_1 = Switch(hostname="switch_1", num_ports=6)
+    switch_1.power_on()
+    switch_2 = Switch(hostname="switch_2", num_ports=6)
+    switch_2.power_on()
+
+5. Connect the Switches to the Router
+
+.. code-block:: python
+
+    network.connect(endpoint_a=router_1.network_interfaces[1], endpoint_b=switch_1.network_interface[6])
+    router_1.enable_port(1)
+    network.connect(endpoint_a=router_1.network_interfaces[2], endpoint_b=switch_2.network_interface[6])
+    router_1.enable_port(2)
+
+6. Create the Client and Server nodes.
+
+.. code-block:: python
+
+    client_1 = Computer(
+        hostname="client_1",
+        ip_address="192.168.2.2",
+        subnet_mask="255.255.255.0",
+        default_gateway="192.168.2.1"
+    )
+    client_1.power_on()
+    server_1 = Server(
+        hostname="server_1",
+        ip_address="192.168.1.2",
+        subnet_mask="255.255.255.0",
+        default_gateway="192.168.1.1"
+    )
+    server_1.power_on()
+
+7. Connect the Client and Server to the relevant Switch
+
+.. code-block:: python
+
+    network.connect(endpoint_a=switch_2.network_interface[1], endpoint_b=client_1.network_interface[1])
+    network.connect(endpoint_a=switch_1.network_interface[1], endpoint_b=server_1.network_interface[1])
+
+8. Add ACL rules on the Router to allow ARP and ICMP traffic.
+
+.. code-block:: python
+
+    router_1.acl.add_rule(
+        action=ACLAction.PERMIT,
+        src_port=Port.ARP,
+        dst_port=Port.ARP,
+        position=22
+    )
+
+    router_1.acl.add_rule(
+        action=ACLAction.PERMIT,
+        protocol=IPProtocol.ICMP,
+        position=23
+    )

docs/source/simulation_components/network/network_interfaces.rst

@@ -0,0 +1,125 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+#################################
+Network Interface Hierarchy Model
+#################################
+
+The network interface hierarchy model is designed to represent the various types of network interfaces and their
+functionalities within a networking system. This model is organised into five distinct layers, each serving a specific
+purpose in the abstraction, implementation, and utilisation of network interfaces. This hierarchical structure
+facilitates modular development, enhances maintainability, and supports scalability by clearly separating concerns and
+allowing for focused enhancements within each layer.
+
+.. image:: primaite_network_interface_model.png
+    :width: 500
+    :align: center
+
+Layer Descriptions
+==================
+
+#. **Base Layer**
+
+   * **Purpose:** Serves as the foundation of the hierarchy, defining the most abstract properties and behaviours common
+     to all network interfaces.
+   * **Content:** Contains the NetworkInterface class, which abstracts basic functionalities such as enabling/disabling
+     the interface, sending, and receiving frames.
+   * **Significance:** Ensures that core functionalities are universally available across all types of network
+     interfaces, promoting code reuse and consistency.
+
+#. **Connection Type Layer**
+
+   * **Purpose:** Differentiates network interfaces based on their physical connection type: wired or wireless.
+   * **Content:** Includes ``WiredNetworkInterface`` and ``WirelessNetworkInterface`` classes, each tailoring the base
+     functionalities to specific mediums.
+   * **Significance:** Allows the development of medium-specific features (e.g., handling point-to-point links in
+     wired devices) while maintaining a clear separation from IP-related functionalities.
+
+#. **IP Layer**
+
+   * **Purpose:** Introduces Internet Protocol (IP) capabilities to network interfaces, enabling IP-based networking.
+   * **Content:** Includes ``IPWiredNetworkInterface`` and ``IPWirelessNetworkInterface`` classes, extending connection
+     type-specific classes with IP functionalities.
+   * **Significance:** Facilitates the implementation of IP address assignment, subnetting, and other Layer 3
+     networking features, crucial for modern networking applications.
+
+#. **Interface Layer**
+
+   * **Purpose:** Defines concrete implementations of network interfaces for specific devices or roles within a network.
+   * **Content:** Includes ``NIC``, ``RouterInterface``, ``SwitchPort``, ``WirelessNIC``, and ``WirelessAccessPoint``
+     classes, each  designed for a particular networking function or device.
+   * **Significance:** This layer allows developers to directly utilise or extend pre-built interfaces tailored to
+     specific networking tasks, enhancing development efficiency and clarity.
+
+#. **Device Layer**
+
+   * **Purpose:** Maps the concrete interface implementations to their respective devices within a network,
+     illustrating practical usage scenarios.
+   * **Content:** Conceptually groups devices such as ``Computer``, ``Server``, ``Switch``, ``Router``, and ``Firewall``
+     with the interfaces they utilise (e.g., ``Computer`` might use ``NIC`` or ``WirelessNIC``).
+   * **Significance:** Provides a clear understanding of how various network interfaces are applied in real-world
+     devices, aiding in system design and architecture planning.
+
+
+Network Interface Classes
+=========================
+
+**NetworkInterface (Base Layer)**
+
+- Abstract base class defining core interface properties like MAC address, speed, MTU.
+- Requires subclasses implement key methods like send/receive frames, enable/disable interface.
+- Establishes universal network interface capabilities.
+- Malicious Network Events Monitoring:
+
+   * Enhances network interfaces with the capability to monitor and capture Malicious Network Events (MNEs) based on predefined criteria such as specific keywords or traffic patterns.
+   * Integrates Number of Malicious Network Events (NMNE) detection functionalities, leveraging configurable settings like ``capture_nmne``, `nmne_capture_keywords``, and observation mechanisms such as ``NICObservation`` to classify and record network anomalies.
+   * Offers an additional layer of security and data analysis, crucial for identifying and mitigating malicious activities within the network infrastructure. Provides vital information for network security analysis and reinforcement learning algorithms.
+
+**WiredNetworkInterface (Connection Type Layer)**
+
+- Extends NetworkInterface for wired connection interfaces.
+- Adds notions of physical/logical connectivity and link management.
+- Mandates subclasses implement wired-specific methods.
+
+**WirelessNetworkInterface (Connection Type Layer)**
+
+- Extends NetworkInterface for wireless interfaces.
+- Encapsulates wireless-specific behaviours like signal strength handling.
+- Requires wireless-specific methods in subclasses.
+
+**Layer3Interface (IP Layer)**
+
+- Introduces IP addressing abilities with ip_address and subnet_mask.
+- Validates address configuration.
+- Enables participation in IP networking.
+
+**IPWiredNetworkInterface (IP Layer)**
+
+- Merges Layer3Interface and WiredNetworkInterface.
+- Defines wired interfaces with IP capabilities.
+- Meant to be extended, doesn't implement methods.
+
+**IPWirelessNetworkInterface (IP Layer)**
+
+- Combines Layer3Interface and WirelessNetworkInterface.
+- Represents wireless interfaces with IP capabilities.
+- Intended to be extended and specialised.
+
+**NIC (Interface Layer)**
+
+- Concrete wired NIC implementation combining IPWiredNetworkInterface and Layer3Interface.
+- Provides network connectivity for host nodes.
+- Manages MAC and IP addressing, frame processing.
+
+**WirelessNIC (Interface Layer)**
+
+- Concrete wireless NIC implementation combining IPWirelessNetworkInterface and Layer3Interface.
+- Delivers wireless connectivity with IP for hosts.
+- Handles wireless transmission/reception.
+
+**WirelessAccessPoint (Interface Layer)**
+
+- Concrete wireless access point implementation using IPWirelessNetworkInterface and Layer3Interface.
+- Bridges wireless and wired networks.
+- Manages wireless network.

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

@@ -0,0 +1,432 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+########
+Firewall
+########
+
+The ``firewall.py`` module is a cornerstone in network security within the PrimAITE simulation, designed to simulate
+the functionalities of a firewall in monitoring, controlling, and securing network traffic.
+
+Firewall Class
+--------------
+
+The ``Firewall`` class extends the ``Router`` class, incorporating advanced capabilities to scrutinise, direct,
+and filter traffic between various network zones, guided by predefined security rules and policies.
+
+Key Features
+============
+
+
+- **Access Control Lists (ACLs):** Employs ACLs to establish security rules for permitting or denying traffic
+  based on IP addresses, protocols, and port numbers, offering detailed oversight of network traffic.
+- **Network Zone Segmentation:** Facilitates network division into distinct zones, including internal, external,
+  and DMZ (De-Militarized Zone), each governed by specific inbound and outbound traffic rules.
+- **Interface Configuration:** Enables the configuration of network interfaces for connectivity to external,
+  internal, and DMZ networks, including setting up IP addressing and subnetting.
+- **Protocol and Service Management:** Oversees and filters traffic across different protocols and services,
+  enforcing adherence to established security policies.
+- **Dynamic Traffic Processing:** Actively processes incoming and outgoing traffic via relevant ACLs, determining
+  whether to forward or block based on the evaluation of rules.
+- **Logging and Diagnostics:** Integrates with ``SysLog`` for detailed logging of firewall actions, supporting
+  security monitoring and incident investigation.
+
+Operations
+==========
+
+- **Rule Definition and Management:** Permits the creation and administration of ACL rules for precise traffic
+  control, enabling the firewall to serve as an effective guard against unauthorised access.
+- **Traffic Forwarding and Filtering:** Assesses network frames against ACL rules to allow or block traffic,
+  forwarding permitted traffic towards its destination whilst obstructing malicious or unauthorised requests.
+- **Interface and Zone Configuration:** Provides mechanisms for configuring and managing network interfaces,
+  aligning with logical network architecture and security zoning requisites.
+
+Configuring Interfaces
+======================
+
+To set up firewall interfaces, allocate IP addresses and subnet masks to the external, internal, and DMZ interfaces
+using the respective configuration methods:
+
+.. code-block:: python
+
+   firewall.configure_external_port(ip_address="10.0.0.1", subnet_mask="255.255.255.0")
+   firewall.configure_internal_port(ip_address="192.168.1.1", subnet_mask="255.255.255.0")
+   firewall.configure_dmz_port(ip_address="172.16.0.1", subnet_mask="255.255.255.0")
+
+
+Firewall ACLs
+=============
+
+In the PrimAITE network simulation, six Access Control Lists (ACLs) are crucial for delineating and enforcing
+comprehensive network security measures. These ACLs, designated as internal inbound, internal outbound, DMZ inbound,
+DMZ outbound, external inbound, and external outbound, each serve a specific role in orchestrating the flow of data
+through the network. They allow for meticulous control of traffic entering, exiting, and moving within the network,
+ensuring robust protection against unauthorised access and potential cyber threats. By leveraging these ACLs both
+individually and collectively, users can simulate a multi-layered security architecture.
+
+Internal Inbound ACL
+^^^^^^^^^^^^^^^^^^^^
+
+This ACL controls incoming traffic from the external network and DMZ to the internal network. It's crucial for
+preventing unauthorised access to internal resources. By filtering incoming requests, it ensures that only legitimate
+and necessary traffic can enter the internal network, protecting sensitive data and systems.
+
+Internal Outbound ACL
+^^^^^^^^^^^^^^^^^^^^^
+
+The internal outbound ACL manages traffic leaving the internal network to the external network or DMZ. It can restrict
+internal users or systems from accessing potentially harmful external sites or services, mitigate data exfiltration
+risks.
+
+DMZ Inbound ACL
+^^^^^^^^^^^^^^^
+
+This ACL regulates access to services hosted in the DMZ from the external network and internal network. Since the DMZ
+hosts public-facing services like web and email servers, the DMZ inbound ACL is pivotal in allowing necessary access
+while blocking malicious or unauthorised attempts, thus serving as a first line of defence.
+
+DMZ Outbound ACL
+^^^^^^^^^^^^^^^^
+
+The ACL controls traffic from DMZ to the external network and internal network. It's used to restrict the DMZ services
+from initiating unauthorised connections, which is essential for preventing compromised DMZ services from being used
+as launchpads for attacks or data exfiltration.
+
+External Inbound ACL
+^^^^^^^^^^^^^^^^^^^^
+
+This ACL filters all incoming traffic from the external network towards the internal network or DMZ. It's instrumental
+in blocking unwanted or potentially harmful external traffic, ensuring that only traffic conforming to the security
+policies is allowed into the network. **This ACL should only be used when the rule applies to both internal and DMZ
+networks.**
+
+External Outbound ACL
+^^^^^^^^^^^^^^^^^^^^^
+
+This ACL governs traffic leaving the internal network or DMZ to the external network. It plays a critical role in data
+loss prevention (DLP) by restricting the types of data and services that internal users and systems can access or
+interact with on external networks. **This ACL should only be used when the rule applies to both internal and DMZ
+networks.**
+
+Using ACLs Together
+^^^^^^^^^^^^^^^^^^^
+
+When these ACLs are used in concert, they create a robust security matrix that controls traffic flow in all directions:
+into the internal network, out of the internal network, into the DMZ, out of the DMZ, and between these networks and
+the external world. For example, while the external inbound ACL might block all incoming SSH requests to protect both
+the internal network and DMZ, the internal outbound ACL could allow SSH access to specific external servers for
+management purposes. Simultaneously, the DMZ inbound ACL might permit HTTP and HTTPS traffic to specific servers to
+provide access to web services while the DMZ outbound ACL ensures these servers cannot make unauthorised outbound
+connections.
+
+By effectively configuring and managing these ACLs, users can establish and experiment with detailed security policies
+that are finely tuned to their simulated network's unique requirements and threat models, achieving granular oversight
+over traffic flows. This not only enables secure simulated interactions and data exchanges within PrimAITE environments
+but also fortifies the virtual network against unauthorised access and cyber threats, mirroring real-world network
+security practices.
+
+
+ACL Configuration Examples
+==========================
+
+The subsequent examples provide detailed illustrations on configuring ACL rules within PrimAITE's firewall setup,
+addressing various scenarios that encompass external attempts to access resources not only within the internal network
+but also within the DMZ. These examples reflect the firewall's specific port configurations and showcase the
+versatility and control that ACLs offer in managing network traffic, ensuring that security policies are precisely
+enforced. Each example highlights different aspects of ACL usage, from basic traffic filtering to more complex
+scenarios involving specific service access and protection against external threats.
+
+**Blocking External Traffic to Internal Network**
+
+To prevent all external traffic from accessing the internal network, with exceptions for approved services:
+
+.. code-block:: python
+
+   # Default rule to deny all external traffic to the internal network
+   firewall.internal_inbound_acl.add_rule(
+       action=ACLAction.DENY,
+       src_ip_address="0.0.0.0",
+       src_wildcard_mask="255.255.255.255",
+       dst_ip_address="192.168.1.0",
+       dst_wildcard_mask="0.0.0.255",
+       position=1
+   )
+
+   # Exception rule to allow HTTP traffic from external to internal network
+   firewall.internal_inbound_acl.add_rule(
+       action=ACLAction.PERMIT,
+       protocol=IPProtocol.TCP,
+       dst_port=Port.HTTP,
+       dst_ip_address="192.168.1.0",
+       dst_wildcard_mask="0.0.0.255",
+       position=2
+   )
+
+**Allowing External Access to Specific Services in DMZ**
+
+To enable external traffic to access specific services hosted within the DMZ:
+
+.. code-block:: python
+
+   # Allow HTTP and HTTPS traffic to the DMZ
+   firewall.dmz_inbound_acl.add_rule(
+       action=ACLAction.PERMIT,
+       protocol=IPProtocol.TCP,
+       dst_port=Port.HTTP,
+       dst_ip_address="172.16.0.0",
+       dst_wildcard_mask="0.0.0.255",
+       position=3
+   )
+   firewall.dmz_inbound_acl.add_rule(
+       action=ACLAction.PERMIT,
+       protocol=IPProtocol.TCP,
+       dst_port=Port.HTTPS,
+       dst_ip_address="172.16.0.0",
+       dst_wildcard_mask="0.0.0.255",
+       position=4
+   )
+
+**Edge Case - Permitting External SSH Access to a Specific Internal Server**
+
+To permit SSH access from a designated external IP to a specific server within the internal network:
+
+.. code-block:: python
+
+   # Allow SSH from a specific external IP to an internal server
+   firewall.internal_inbound_acl.add_rule(
+       action=ACLAction.PERMIT,
+       protocol=IPProtocol.TCP,
+       src_ip_address="10.0.0.2",
+       dst_port=Port.SSH,
+       dst_ip_address="192.168.1.10",
+       position=5
+   )
+
+**Restricting Access to Internal Database Server**
+
+To limit database server access to selected external IP addresses:
+
+.. code-block:: python
+
+   # Allow PostgreSQL traffic from an authorized external IP to the internal DB server
+   firewall.internal_inbound_acl.add_rule(
+       action=ACLAction.PERMIT,
+       protocol=IPProtocol.TCP,
+       src_ip_address="10.0.0.3",
+       dst_port=Port.POSTGRES_SERVER,
+       dst_ip_address="192.168.1.20",
+       position=6
+   )
+
+   # Deny all other PostgreSQL traffic from external sources
+   firewall.internal_inbound_acl.add_rule(
+       action=ACLAction.DENY,
+       protocol=IPProtocol.TCP,
+       dst_port=Port.POSTGRES_SERVER,
+       dst_ip_address="192.168.1.0",
+       dst_wildcard_mask="0.0.0.255",
+       position=7
+   )
+
+**Permitting DMZ Web Server Access while Blocking Specific Threats**
+
+To authorize HTTP/HTTPS access to a DMZ-hosted web server, excluding known malicious IPs:
+
+.. code-block:: python
+
+   # Deny access from a known malicious IP to any DMZ service
+   firewall.dmz_inbound_acl.add_rule(
+       action=ACLAction.DENY,
+       src_ip_address="10.0.0.4",
+       dst_ip_address="172.16.0.0",
+       dst_wildcard_mask="0.0.0.255",
+       position=8
+   )
+
+   # Allow HTTP/HTTPS traffic to the DMZ web server
+   firewall.dmz_inbound_acl.add_rule(
+       action=ACLAction.PERMIT,
+       protocol=IPProtocol.TCP,
+       dst_port=Port.HTTP,
+       dst_ip_address="172.16.0.2",
+       position=9
+   )
+   firewall.dmz_inbound_acl.add_rule(
+       action=ACLAction.PERMIT,
+       protocol=IPProtocol.TCP,
+       dst_port=Port.HTTPS,
+       dst_ip_address="172.16.0.2",
+       position=10
+   )
+
+**Enabling Internal to DMZ Restricted Access**
+
+To facilitate restricted access from the internal network to DMZ-hosted services:
+
+.. code-block:: python
+
+   # Permit specific internal application server HTTPS access to a DMZ-hosted API
+   firewall.internal_outbound_acl.add_rule(
+       action=ACLAction.PERMIT,
+       protocol=IPProtocol.TCP,
+       src_ip_address="192.168.1.30",  # Internal application server IP
+       dst_port=Port.HTTPS,
+       dst_ip_address="172.16.0.3",  # DMZ API server IP
+       position=11
+   )
+
+   # Deny all other traffic from the internal network to the DMZ
+   firewall.internal_outbound_acl.add_rule(
+       action=ACLAction.DENY,
+       src_ip_address="192.168.1.0",
+       src_wildcard_mask="0.0.0.255",
+       dst_ip_address="172.16.0.0",
+       dst_wildcard_mask="0.0.0.255",
+       position=12
+   )
+
+   # Corresponding rule in DMZ inbound ACL to allow the traffic from the specific internal server
+   firewall.dmz_inbound_acl.add_rule(
+       action=ACLAction.PERMIT,
+       protocol=IPProtocol.TCP,
+       src_ip_address="192.168.1.30",  # Ensuring this specific source is allowed
+       dst_port=Port.HTTPS,
+       dst_ip_address="172.16.0.3",  # DMZ API server IP
+       position=13
+   )
+
+   # Deny all other internal traffic to the specific DMZ API server
+   firewall.dmz_inbound_acl.add_rule(
+       action=ACLAction.DENY,
+       src_ip_address="192.168.1.0",
+       src_wildcard_mask="0.0.0.255",
+       dst_port=Port.HTTPS,
+       dst_ip_address="172.16.0.3",  # DMZ API server IP
+       position=14
+   )
+
+**Blocking Unwanted External Access**
+
+To block all SSH access attempts from the external network:
+
+.. code-block:: python
+
+   # Deny all SSH traffic from any external source
+   firewall.external_inbound_acl.add_rule(
+       action=ACLAction.DENY,
+       protocol=IPProtocol.TCP,
+       dst_port=Port.SSH,
+       position=1
+   )
+
+**Allowing Specific External Communication**
+
+To allow the internal network to initiate HTTP connections to the external network:
+
+.. code-block:: python
+
+   # Permit outgoing HTTP traffic from the internal network to any external destination
+   firewall.external_outbound_acl.add_rule(
+       action=ACLAction.PERMIT,
+       protocol=IPProtocol.TCP,
+       dst_port=Port.HTTP,
+       position=2
+   )
+
+
+The examples above demonstrate the versatility and power of ACLs in crafting nuanced security policies. By combining
+rules that specify permitted and denied traffic, both broadly and narrowly defined, administrators can construct
+a firewall policy that safeguards network resources while ensuring necessary access is maintained.
+
+Show Rules Function
+===================
+
+The show_rules function in the Firewall class displays the configurations of Access Control Lists (ACLs) within a
+network firewall. It presents a comprehensive table detailing the rules that govern the filtering and management of
+network traffic.
+
+**Functionality:**
+
+This function showcases each rule in an ACL, outlining its:
+
+- **Index**: The rule's position within the ACL.
+- **Action**: Specifies whether to permit or deny matching traffic.
+- **Protocol**: The network protocol to which the rule applies.
+- **Src IP and Dst IP**: Source and destination IP addresses.
+- **Src Wildcard and Dst** Wildcard: Wildcard masks for source and destination IP ranges.
+- **Src Port and Dst Port**: Source and destination ports.
+- **Matched**: The number of times the rule has been matched by traffic.
+
+Example Output:
+
+.. code-block:: text
+
+    +---------------------------------------------------------------------------------------------------------------+
+    |                               firewall_1 - External Inbound Access Control List                               |
+    +-------+--------+----------+--------+--------------+-----------+--------+--------------+-----------+-----------+
+    | Index | Action | Protocol | Src IP | Src Wildcard | Src Port  | Dst IP | Dst Wildcard | Dst Port  | Matched   |
+    +-------+--------+----------+--------+--------------+-----------+--------+--------------+-----------+-----------+
+    | 22    | PERMIT | ANY      | ANY    | ANY          | 219 (ARP) | ANY    | ANY          | 219 (ARP) | 1         |
+    | 23    | PERMIT | ICMP     | ANY    | ANY          | ANY       | ANY    | ANY          | ANY       | 0         |
+    | 24    | PERMIT | ANY      | ANY    | ANY          | ANY       | ANY    | ANY          | ANY       | 2         |
+    +-------+--------+----------+--------+--------------+-----------+--------+--------------+-----------+-----------+
+
+    +---------------------------------------------------------------------------------------------------------------+
+    |                               firewall_1 - External Outbound Access Control List                              |
+    +-------+--------+----------+--------+--------------+-----------+--------+--------------+-----------+-----------+
+    | Index | Action | Protocol | Src IP | Src Wildcard | Src Port  | Dst IP | Dst Wildcard | Dst Port  | Matched   |
+    +-------+--------+----------+--------+--------------+-----------+--------+--------------+-----------+-----------+
+    | 22    | PERMIT | ANY      | ANY    | ANY          | 219 (ARP) | ANY    | ANY          | 219 (ARP) | 0         |
+    | 23    | PERMIT | ICMP     | ANY    | ANY          | ANY       | ANY    | ANY          | ANY       | 0         |
+    | 24    | PERMIT | ANY      | ANY    | ANY          | ANY       | ANY    | ANY          | ANY       | 2         |
+    +-------+--------+----------+--------+--------------+-----------+--------+--------------+-----------+-----------+
+
+    +---------------------------------------------------------------------------------------------------------------+
+    |                               firewall_1 - Internal Inbound Access Control List                               |
+    +-------+--------+----------+--------+--------------+-----------+--------+--------------+-----------+-----------+
+    | Index | Action | Protocol | Src IP | Src Wildcard | Src Port  | Dst IP | Dst Wildcard | Dst Port  | Matched   |
+    +-------+--------+----------+--------+--------------+-----------+--------+--------------+-----------+-----------+
+    | 1     | PERMIT | ANY      | ANY    | ANY          | 123 (NTP) | ANY    | ANY          | 123 (NTP) | 1         |
+    | 22    | PERMIT | ANY      | ANY    | ANY          | 219 (ARP) | ANY    | ANY          | 219 (ARP) | 0         |
+    | 23    | PERMIT | ICMP     | ANY    | ANY          | ANY       | ANY    | ANY          | ANY       | 0         |
+    | 24    | DENY   | ANY      | ANY    | ANY          | ANY       | ANY    | ANY          | ANY       | 0         |
+    +-------+--------+----------+--------+--------------+-----------+--------+--------------+-----------+-----------+
+
+    +---------------------------------------------------------------------------------------------------------------+
+    |                               firewall_1 - Internal Outbound Access Control List                              |
+    +-------+--------+----------+--------+--------------+-----------+--------+--------------+-----------+-----------+
+    | Index | Action | Protocol | Src IP | Src Wildcard | Src Port  | Dst IP | Dst Wildcard | Dst Port  | Matched   |
+    +-------+--------+----------+--------+--------------+-----------+--------+--------------+-----------+-----------+
+    | 1     | PERMIT | ANY      | ANY    | ANY          | 123 (NTP) | ANY    | ANY          | 123 (NTP) | 1         |
+    | 22    | PERMIT | ANY      | ANY    | ANY          | 219 (ARP) | ANY    | ANY          | 219 (ARP) | 1         |
+    | 23    | PERMIT | ICMP     | ANY    | ANY          | ANY       | ANY    | ANY          | ANY       | 0         |
+    | 24    | DENY   | ANY      | ANY    | ANY          | ANY       | ANY    | ANY          | ANY       | 0         |
+    +-------+--------+----------+--------+--------------+-----------+--------+--------------+-----------+-----------+
+
+    +---------------------------------------------------------------------------------------------------------------+
+    |                                  firewall_1 - DMZ Inbound Access Control List                                 |
+    +-------+--------+----------+--------+--------------+-----------+--------+--------------+-----------+-----------+
+    | Index | Action | Protocol | Src IP | Src Wildcard | Src Port  | Dst IP | Dst Wildcard | Dst Port  | Matched   |
+    +-------+--------+----------+--------+--------------+-----------+--------+--------------+-----------+-----------+
+    | 1     | PERMIT | ANY      | ANY    | ANY          | 123 (NTP) | ANY    | ANY          | 123 (NTP) | 1         |
+    | 22    | PERMIT | ANY      | ANY    | ANY          | 219 (ARP) | ANY    | ANY          | 219 (ARP) | 0         |
+    | 23    | PERMIT | ICMP     | ANY    | ANY          | ANY       | ANY    | ANY          | ANY       | 0         |
+    | 24    | DENY   | ANY      | ANY    | ANY          | ANY       | ANY    | ANY          | ANY       | 0         |
+    +-------+--------+----------+--------+--------------+-----------+--------+--------------+-----------+-----------+
+
+    +---------------------------------------------------------------------------------------------------------------+
+    |                                 firewall_1 - DMZ Outbound Access Control List                                 |
+    +-------+--------+----------+--------+--------------+-----------+--------+--------------+-----------+-----------+
+    | Index | Action | Protocol | Src IP | Src Wildcard | Src Port  | Dst IP | Dst Wildcard | Dst Port  | Matched   |
+    +-------+--------+----------+--------+--------------+-----------+--------+--------------+-----------+-----------+
+    | 1     | PERMIT | ANY      | ANY    | ANY          | 123 (NTP) | ANY    | ANY          | 123 (NTP) | 1         |
+    | 22    | PERMIT | ANY      | ANY    | ANY          | 219 (ARP) | ANY    | ANY          | 219 (ARP) | 1         |
+    | 23    | PERMIT | ICMP     | ANY    | ANY          | ANY       | ANY    | ANY          | ANY       | 0         |
+    | 24    | DENY   | ANY      | ANY    | ANY          | ANY       | ANY    | ANY          | ANY       | 0         |
+    +-------+--------+----------+--------+--------------+-----------+--------+--------------+-----------+-----------+
+
+
+The ``firewall.py`` module within PrimAITE empowers users to accurately model and simulate the pivotal role of
+firewalls in network security. It provides detailed command over traffic flow and enforces security policies to safeguard
+networked assets.

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

@@ -0,0 +1,47 @@
+
+#########
+Host Node
+#########
+
+The ``host_node.py`` module is a core component of the PrimAITE project, aimed at simulating network host. It
+encapsulates the functionality necessary for modelling the behaviour, communication capabilities, and interactions of
+hosts in a networked environment.
+
+
+HostNode Class
+==============
+
+The ``HostNode`` class acts as a foundational representation of a networked device or computer, capable of both
+initiating and responding to network communications.
+
+**Attributes:**
+
+- Manages IP addressing with support for IPv4.
+- Employs ``NIC`` or ``WirelessNIC`` (subclasses of``IPWiredNetworkInterface``) to simulate wired network connections.
+- Integrates with ``SysLog`` for logging operational events, aiding in debugging and monitoring the host node's
+  behaviour.
+
+**Key Methods:**
+
+- Facilitates the sending and receiving of ``Frame`` objects to simulate data link layer communications.
+- Manages a variety of network services and applications, enhancing the simulation's realism and functionality.
+
+Default Services and Applications
+=================================
+
+Both the ``HostNode`` and its subclasses come equipped with a suite of default services and applications critical for
+fundamental network operations:
+
+1. **ARP (Address Resolution Protocol):** The ``HostARP`` subclass enhances ARP functionality for host-specific
+   operations.
+
+2. **DNS (Domain Name System) Client:** Facilitates domain name resolution to IP addresses, enabling web navigation.
+
+3. **FTP (File Transfer Protocol) Client:** Supports file transfers across the network.
+
+4. **ICMP (Internet Control Message Protocol):** Utilised for network diagnostics and control, such as executing ping
+   requests.
+
+5. **NTP (Network Time Protocol) Client:** Synchronises the host's clock with network time servers.
+
+6. **Web Browser:** A simulated application that allows the host to request and display web content.

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

@@ -0,0 +1,41 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+############
+Network Node
+############
+
+
+The ``network_node.py`` module within the PrimAITE project is pivotal for simulating network nodes like routers and
+switches, which are integral to network traffic management. This module establishes the framework for these devices,
+enabling them to receive and process network frames effectively.
+
+Overview
+========
+
+The module defines the ``NetworkNode`` class, an abstract base class that outlines essential behaviours for network
+devices tasked with handling network traffic. It is designed to be extended by more specific device simulations that
+implement these foundational capabilities.
+
+NetworkNode Class
+=================
+
+The ``NetworkNode`` class is at the heart of the module, providing an interface for network devices that participate
+in the transmission and routing of data within the simulated environment.
+
+**Key Features:**
+
+- **Frame Processing:** Central to the class is the ability to receive and process network frames, facilitating the
+   simulation of data flow through network devices.
+
+- **Abstract Methods:** Includes abstract methods such as ``receive_frame``, which subclasses must implement to specify
+   how devices handle incoming traffic.
+
+- **Extensibility:** Designed for extension, allowing for the creation of specific device simulations, such as router
+   and switch classes, that embody unique behaviours and functionalities.
+
+
+The ``network_node.py`` module's abstract approach to defining network devices allows the PrimAITE project to simulate
+a wide range of network behaviours and scenarios comprehensively. By providing a common framework for all network
+nodes, it facilitates the development of a modular and scalable simulation environment.

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

@@ -0,0 +1,41 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+######
+Router
+######
+
+The ``router.py`` module is a pivotal component of the PrimAITE, designed to simulate the complex functionalities of a
+router within a network simulation. Routers are essential for directing traffic between different network segments,
+and this module provides the tools necessary to model these devices' behaviour and capabilities accurately.
+
+Router Class
+------------
+
+The ``Router`` class embodies the core functionalities of a network router, extending the ``NetworkNode`` class to
+incorporate routing-specific behaviours.
+
+**Key Features:**
+
+- **IP Routing:** Supports dynamic handling of IP packets, including forwarding based on destination IP addresses and
+  subnetting.
+- **Routing Table:** Maintains a routing table to determine the best path for forwarding packets.
+- **Protocol Support:** Implements support for key networking protocols, including ARP for address resolution and ICMP
+  for diagnostic messages.
+- **Interface Management:** Manages multiple ``RouterInterface`` instances, enabling connections to different network
+  segments.
+- **Network Interface Configuration:** Tools for configuring router interfaces, including setting IP addresses, subnet
+  masks, and enabling/disabling interfaces.
+- **Logging and Monitoring:** Integrates with ``SysLog`` for logging operational events, aiding in debugging and
+  monitoring router behaviour.
+
+**Operations:**
+
+- **Packet Forwarding:** Utilises the routing table to forward packets to their correct destination across
+  interconnected networks.
+- **ARP Handling:** Responds to ARP requests for any IP addresses configured on its interfaces, facilitating
+  communication within local networks.
+- **ICMP Processing:** Generates and processes ICMP packets, such as echo requests and replies, for network diagnostics.
+
+The ``router.py`` module offers a comprehensive simulation of router functionalities. By providing detailed modelling of router operations, including packet forwarding, interface management, and protocol handling, PrimAITE enables the exploration of advanced network topologies and routing scenarios.

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

@@ -0,0 +1,29 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+######
+Switch
+######
+
+The ``switch.py`` module is a crucial component of the PrimAITE, aimed at simulating network switches within a network simulation environment. Network switches play a vital role in managing data flow within local area networks (LANs) by forwarding frames based on MAC addresses. This module provides a comprehensive framework for modelling switch operations and behaviours.
+
+Switch Class Overview
+---------------------
+
+The module introduces the concept of switch ports through the ``SwitchPort`` class, which extends the functionality of ``WiredNetworkInterface`` to simulate the operation of switch ports in a network.
+
+**Key Features:**
+
+- **Data Link Layer Operation:** Operates at the data link layer (Layer 2) of the OSI model, handling the reception and forwarding of frames based on MAC addresses.
+- **Port Management:** Tools for configuring switch ports, including enabling/disabling ports, setting port speeds, and managing port security features.
+- **Logging and Monitoring:** Integrates with ``SysLog`` for logging operational events, aiding in debugging and
+  monitoring switch behaviour.
+
+Functionality and Implementation
+---------------------------------
+
+- **MAC Address Learning:** Dynamically learns and associates MAC addresses with switch ports, enabling intelligent frame forwarding.
+- **Frame Forwarding:** Utilises the learned MAC address table to forward frames only to the specific port associated with the destination MAC address, minimising unnecessary network traffic.
+
+The ``switch.py`` module offers a realistic and configurable representation of switch operations. By detailing the functionalities of the ``SwitchPort`` class, the module lays the foundation for simulating complex network topologies.

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

@@ -0,0 +1,193 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+######
+Router
+######
+
+The ``WirelessRouter`` class extends the functionality of the standard ``Router`` class within PrimAITE,
+integrating wireless networking capabilities. This class enables the simulation of a router that supports both wired
+and wireless connections, allowing for a more comprehensive network simulation environment.
+
+Overview
+--------
+
+The ``WirelessRouter`` class is designed to simulate the operations of a real-world wireless router, offering both
+Ethernet and Wi-Fi connectivity. This includes managing wireless access points, configuring network interfaces for
+different frequencies, and handling wireless frames transmission.
+
+Features
+--------
+
+- **Dual Interface Support:** Supports both wired (Ethernet) and wireless network interfaces.
+- **Wireless Access Point Configuration:** Allows configuring a wireless access point, including setting its IP
+  address, subnet mask, and operating frequency.
+- **Frequency Management:** Utilises the ``AirSpaceFrequency`` enum to set the operating frequency of wireless
+  interfaces, supporting common Wi-Fi bands like 2.4 GHz and 5 GHz.
+- **Seamless Wireless Communication:** Integrates with the ``AirSpace`` class to manage wireless transmissions across
+  different frequencies, ensuring that wireless communication is realistically simulated.
+
+Usage
+-----
+
+To use the ``WirelessRouter`` class in a network simulation, instantiate it similarly to a regular router but with
+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
+
+    # Instantiate the WirelessRouter
+    wireless_router = WirelessRouter(hostname="MyWirelessRouter")
+
+    # Configure a wired Ethernet interface
+    wireless_router.configure_port(port=2, ip_address="192.168.1.1", subnet_mask="255.255.255.0")
+
+    # Configure a wireless access point
+    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
+    )
+
+
+
+Integration with AirSpace
+-------------------------
+
+The ``WirelessRouter`` class works closely with the ``AirSpace`` class to simulate the transmission of wireless frames.
+Frames sent from wireless interfaces are transmitted across the simulated airspace, allowing for interactions with
+other wireless devices within the same frequency band.
+
+Example Scenario
+----------------
+
+This example sets up a network with two PCs (PC A and PC B), each connected to their own `WirelessRouter`
+(Router 1 and Router 2). These routers are then wirelessly connected to each other, enabling communication between the
+PCs through the routers over the airspace. Access Control Lists (ACLs) are configured on the routers to permit ARP and
+ICMP traffic, ensuring basic network connectivity and ping functionality.
+
+.. code-block:: python
+
+    from primaite.simulator.network.airspace import AIR_SPACE, AirSpaceFrequency
+    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
+    from primaite.simulator.network.hardware.nodes.network.wireless_router import WirelessRouter
+    from primaite.simulator.network.transmission.network_layer import IPProtocol
+    from primaite.simulator.network.transmission.transport_layer import Port
+
+    network = Network()
+
+    # Configure PC A
+    pc_a = Computer(
+        hostname="pc_a",
+        ip_address="192.168.0.2",
+        subnet_mask="255.255.255.0",
+        default_gateway="192.168.0.1",
+        start_up_duration=0,
+    )
+    pc_a.power_on()
+    network.add_node(pc_a)
+
+    # Configure Router 1
+    router_1 = WirelessRouter(hostname="router_1", start_up_duration=0)
+    router_1.power_on()
+    network.add_node(router_1)
+
+    # Configure the connection between PC A and Router 1 port 2
+    router_1.configure_router_interface("192.168.0.1", "255.255.255.0")
+    network.connect(pc_a.network_interface[1], router_1.router_interface)
+
+    # Configure Router 1 ACLs
+    router_1.acl.add_rule(action=ACLAction.PERMIT, src_port=Port.ARP, dst_port=Port.ARP, position=22)
+    router_1.acl.add_rule(action=ACLAction.PERMIT, protocol=IPProtocol.ICMP, position=23)
+
+    # Configure PC B
+    pc_b = Computer(
+        hostname="pc_b",
+        ip_address="192.168.2.2",
+        subnet_mask="255.255.255.0",
+        default_gateway="192.168.2.1",
+        start_up_duration=0,
+    )
+    pc_b.power_on()
+    network.add_node(pc_b)
+
+    # Configure Router 2
+    router_2 = WirelessRouter(hostname="router_2", start_up_duration=0)
+    router_2.power_on()
+    network.add_node(router_2)
+
+    # Configure the connection between PC B and Router 2 port 2
+    router_2.configure_router_interface("192.168.2.1", "255.255.255.0")
+    network.connect(pc_b.network_interface[1], router_2.router_interface)
+
+    # Configure the wireless connection between Router 1 and Router 2
+    router_1.configure_wireless_access_point(
+        port=1,
+        ip_address="192.168.1.1",
+        subnet_mask="255.255.255.0",
+        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
+    )
+
+    # Configure routes for inter-router communication
+    router_1.route_table.add_route(
+        address="192.168.2.0", subnet_mask="255.255.255.0", next_hop_ip_address="192.168.1.2"
+    )
+
+    router_2.route_table.add_route(
+        address="192.168.0.0", subnet_mask="255.255.255.0", next_hop_ip_address="192.168.1.1"
+    )
+
+    # Test connectivity
+    print(pc_a.ping(pc_b.network_interface[1].ip_address))
+    print(pc_b.ping(pc_a.network_interface[1].ip_address))
+
+This setup demonstrates the `WirelessRouter` class's capability to manage both wired and wireless connections within a
+simulated network environment. By configuring the wireless access points and enabling the appropriate ACL rules, the
+example facilitates basic network operations such as ARP resolution and ICMP pinging between devices across different
+network segments.
+
+Viewing Wireless Network Configuration
+--------------------------------------
+
+The `AirSpace.show()` function is an invaluable tool for inspecting the current wireless network configuration within
+the PrimAITE environment. It presents a table summarising all wireless interfaces, including routers and access points,
+that are active within the airspace. The table outlines each device's connected node name, MAC address, IP address,
+subnet mask, operating frequency, and status, providing a comprehensive view of the wireless network topology.
+
+Example Output
+^^^^^^^^^^^^^^^
+
+Below is an example output of the `AirSpace.show()` function, demonstrating the visibility it provides into the
+wireless network:
+
+.. code-block:: none
+
+    +----------------+-------------------+-------------+---------------+--------------+---------+
+    | Connected Node |    MAC Address    |  IP Address |  Subnet Mask  |  Frequency   |  Status |
+    +----------------+-------------------+-------------+---------------+--------------+---------+
+    |    router_1    | 31:29:46:53:ed:f8 | 192.168.1.1 | 255.255.255.0 | WiFi 2.4 GHz | Enabled |
+    |    router_2    | 34:c8:47:43:98:78 | 192.168.1.2 | 255.255.255.0 | WiFi 2.4 GHz | Enabled |
+    +----------------+-------------------+-------------+---------------+--------------+---------+
+
+This table aids in verifying that wireless devices are correctly configured and operational. It also helps in
+diagnosing connectivity issues by ensuring that devices are on the correct frequency and have the appropriate network
+settings. The `Status` column, indicating whether a device is enabled or disabled, further assists in troubleshooting
+by quickly identifying any devices that are not actively participating in the network.
+
+Utilising the `AirSpace.show()` function is particularly beneficial in complex network simulations where multiple
+wireless devices are in use. It provides a snapshot of the wireless landscape, facilitating the understanding of how
+devices interact within the network and ensuring that configurations are aligned with the intended network architecture.
+
+The addition of the ``WirelessRouter`` class enriches the PrimAITE simulation toolkit by enabling the simulation of
+mixed wired and wireless network environments.