Merged PR 479: merged 3.1.0 into main for git history alignment

merged 3.1.0 into main for git history alignment

Related work items: #1847, #2502, #2610, #2618, #2628, #2646, #2658, #2659, #2660, #2661, #2682

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

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

.github/workflows/build-sphinx.yml

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

.github/workflows/python-package.yml

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

.gitignore

@@ -148,7 +148,7 @@ cython_debug/
 
 # IDE
 .idea/
-docs/source/primaite-dependencies.rst
+
 .vscode/
 
 # outputs

.pre-commit-config.yaml

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

CHANGELOG.md

@@ -43,6 +43,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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.
+- Added NMAP application to all host and layer-3 network nodes.
 
 ### Bug Fixes
 

CONTRIBUTING.md

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

LICENSE

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

README.md

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

copyright_clause_pre_commit_hook.py

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

docs/Makefile

@@ -1,3 +1,4 @@
+# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
 # Minimal makefile for Sphinx documentation
 # You can set these variables from the command line, and also
 # from the environment for the first two.

docs/_templates/custom-class-template.rst

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

docs/_templates/custom-module-template.rst

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

docs/api.rst

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

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

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

docs/conf.py

@@ -1,4 +1,4 @@
-# © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
 # Configuration file for the Sphinx documentation builder.
 #
 # For the full list of built-in configuration values, see the documentation:
@@ -147,7 +147,7 @@ def copy_notebooks_to_docs() -> Any:
     This allows developers to create new notebooks without having to worry about updating documentation when
     a new notebook is included within PrimAITE.
     """
-    notebook_asset_types = [".ipynb", ".png"]
+    notebook_asset_types = [".ipynb", ".png", ".svg"]
     notebook_directories = []
 
     # find paths where notebooks are contained

docs/make.bat

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

docs/source/configuration/agents.rst

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

docs/source/configuration/game.rst

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

docs/source/configuration/io_settings.rst

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

docs/source/configuration/simulation.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
 
 
 ``simulation``

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

docs/source/customising_scenarios.rst

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

docs/source/environment.rst

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

docs/source/example_notebooks.rst

@@ -77,6 +77,6 @@ The following extensions should now be installed
     :width: 300
     :align: center
 
-VSCode will then ask for a Python environment version to use. PrimAITE is compatible with Python versions 3.8 - 3.11
+VSCode will then ask for a Python environment version to use. PrimAITE is compatible with Python versions 3.9 - 3.11
 
 You should now be able to interact with the notebook.

docs/source/game_layer.rst

@@ -1,3 +1,7 @@
+.. only:: comment
+
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+
 PrimAITE Game layer
 *******************
 
@@ -81,7 +85,6 @@ blue_agent:
           weight: 1.0
           options:
             agent_name: client_2_green_user
-
 ```
 
 When defining agent reward sharing, users must be careful to avoid circular references, as that would lead to an infinite calculation loop. PrimAITE will prevent circular dependencies and provide a helpful error message if they are detected in the yaml.

docs/source/getting_started.rst

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

docs/source/notebooks/executed_notebooks.rst

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

docs/source/primaite-dependencies.rst

@@ -1,3 +1,7 @@
+.. only:: comment
+
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+
 +-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+----------------------------------------------+
 | Name              | Version | License                            | Description                                                                                           | URL                                          |
 +===================+=========+====================================+=======================================================================================================+==============================================+

docs/source/simulation_components/network/base_hardware.rst

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

docs/source/simulation_components/network/network.rst

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

docs/source/simulation_components/network/network_interfaces.rst

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

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

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

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

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

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

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

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

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

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

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

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

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

docs/source/simulation_components/network/transport_to_data_link_layer.rst

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

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

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

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

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

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

@@ -1,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
 
 .. _DoSBot:
 

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

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

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

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

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

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

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

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

docs/source/simulation_components/system/internal_frame_processing.rst

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

docs/source/simulation_components/system/list_of_applications.rst

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

docs/source/simulation_components/system/list_of_services.rst

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

docs/source/simulation_components/system/list_of_system_applications.rst

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

docs/source/simulation_components/system/list_of_system_services.rst

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

docs/source/simulation_components/system/pcap.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
 
 PCAP
 ====

docs/source/simulation_components/system/services/database_service.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
 
 .. _DatabaseService:
 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

docs/source/simulation_components/system/session_and_software_manager.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
 
 Session and Software Manager
 ============================

docs/source/simulation_components/system/software.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
 
 
 Software

docs/source/simulation_components/system/sys_log.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
 
 SysLog
 ======

pyproject.toml

@@ -7,17 +7,15 @@ name = "primaite"
 description = "PrimAITE (Primary-level AI Training Environment) is a simulation environment for training AI under the ARCD programme."
 authors = [{name="Defence Science and Technology Laboratory UK", email="oss@dstl.gov.uk"}]
 license = {file = "LICENSE"}
-requires-python = ">=3.8, <3.12"
+requires-python = ">=3.9, <3.12"
 dynamic = ["version", "readme"]
 classifiers = [
-    "License :: OSI Approved :: MIT License",
     "Development Status :: 5 - Production/Stable",
     "Operating System :: Microsoft :: Windows",
     "Operating System :: MacOS",
     "Operating System :: POSIX :: Linux",
     "Operating System :: Unix",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.8",
     "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
@@ -91,7 +89,7 @@ order_by_type = "False"
 line-length = 120
 
 [project.urls]
-Homepage = "https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE"
+Homepage = "https://github.com/{todo:fill in URL}/PrimAITE"
-Documentation = "https://Autonomous-Resilient-Cyber-Defence.github.io/PrimAITE/"
+Documentation = "https://{todo:fill in URL}.github.io/PrimAITE"
-Repository = "https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE"
+Repository = "https://github.com/{todo:fill in URL}/PrimAITE"
-Changelog = "https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE/blob/dev/CHANGELOG.md"
+Changelog = "https://github.com/{todo:fill in URL}/PrimAITE/blob/main/CHANGELOG.md"

setup.cfg

@@ -1,4 +1,4 @@
 [metadata]
-url = https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE
+url = https://github.com/{todo:fill in URL}/PrimAITE
 author = Defence Science and Technology Laboratory UK
 author_email = oss@dstl.gov.uk

src/primaite/VERSION

@@ -1 +1 @@
-3.0.0
+3.1.0

src/primaite/__init__.py

@@ -1,4 +1,4 @@
-# © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
 import datetime as datetime
 import logging
 import logging.config
@@ -203,3 +203,6 @@ def getLogger(name: str) -> Logger:  # noqa
     logger.setLevel(PRIMAITE_CONFIG["logging"]["log_level"])
 
     return logger
+
+
+DEFAULT_BANDWIDTH: Final[int] = 100

src/primaite/cli.py

@@ -1,4 +1,4 @@
-# © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
 """Provides a CLI using Typer as an entry point."""
 import logging
 import os

src/primaite/config/__init__.py

@@ -1,2 +1,2 @@
-# © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
 """Configuration parameters for running experiments."""

src/primaite/config/_package_data/data_manipulation.yaml

@@ -188,6 +188,11 @@ agents:
               num_nics: 2
               include_num_access: false
               include_nmne: true
+              monitored_traffic:
+                icmp:
+                    - NONE
+                tcp:
+                    - DNS
               routers:
                 - hostname: router_1
               num_ports: 0
@@ -471,7 +476,7 @@ agents:
           46: # old action num: 22 # "ACL: ADDRULE - Block outgoing traffic from client 1"
             action: "ROUTER_ACL_ADDRULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 1
                 permission: 2
                 source_ip_id: 7 # client 1
@@ -484,7 +489,7 @@ agents:
           47: # old action num: 23 # "ACL: ADDRULE - Block outgoing traffic from client 2"
             action: "ROUTER_ACL_ADDRULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 2
                 permission: 2
                 source_ip_id: 8 # client 2
@@ -497,7 +502,7 @@ agents:
           48: # old action num: 24 # block tcp traffic from client 1 to web app
             action: "ROUTER_ACL_ADDRULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 3
                 permission: 2
                 source_ip_id: 7 # client 1
@@ -510,7 +515,7 @@ agents:
           49: # old action num: 25 # block tcp traffic from client 2 to web app
             action: "ROUTER_ACL_ADDRULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 4
                 permission: 2
                 source_ip_id: 8 # client 2
@@ -523,7 +528,7 @@ agents:
           50: # old action num: 26
             action: "ROUTER_ACL_ADDRULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 5
                 permission: 2
                 source_ip_id: 7 # client 1
@@ -536,7 +541,7 @@ agents:
           51: # old action num: 27
             action: "ROUTER_ACL_ADDRULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 6
                 permission: 2
                 source_ip_id: 8 # client 2
@@ -549,52 +554,52 @@ agents:
           52: # old action num: 28
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 0
           53: # old action num: 29
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 1
           54: # old action num: 30
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 2
           55: # old action num: 31
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 3
           56: # old action num: 32
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 4
           57: # old action num: 33
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 5
           58: # old action num: 34
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 6
           59: # old action num: 35
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 7
           60: # old action num: 36
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 8
           61: # old action num: 37
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 9
           62: # old action num: 38
             action: "HOST_NIC_DISABLE"

src/primaite/config/_package_data/data_manipulation_marl.yaml

@@ -470,7 +470,7 @@ agents:
           46: # old action num: 22 # "ACL: ADDRULE - Block outgoing traffic from client 1"
             action: "ROUTER_ACL_ADDRULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 1
                 permission: 2
                 source_ip_id: 7 # client 1
@@ -483,7 +483,7 @@ agents:
           47: # old action num: 23 # "ACL: ADDRULE - Block outgoing traffic from client 2"
             action: "ROUTER_ACL_ADDRULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 2
                 permission: 2
                 source_ip_id: 8 # client 2
@@ -496,7 +496,7 @@ agents:
           48: # old action num: 24 # block tcp traffic from client 1 to web app
             action: "ROUTER_ACL_ADDRULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 3
                 permission: 2
                 source_ip_id: 7 # client 1
@@ -509,7 +509,7 @@ agents:
           49: # old action num: 25 # block tcp traffic from client 2 to web app
             action: "ROUTER_ACL_ADDRULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 4
                 permission: 2
                 source_ip_id: 8 # client 2
@@ -522,7 +522,7 @@ agents:
           50: # old action num: 26
             action: "ROUTER_ACL_ADDRULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 5
                 permission: 2
                 source_ip_id: 7 # client 1
@@ -535,7 +535,7 @@ agents:
           51: # old action num: 27
             action: "ROUTER_ACL_ADDRULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 6
                 permission: 2
                 source_ip_id: 8 # client 2
@@ -548,52 +548,52 @@ agents:
           52: # old action num: 28
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 0
           53: # old action num: 29
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 1
           54: # old action num: 30
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 2
           55: # old action num: 31
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 3
           56: # old action num: 32
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 4
           57: # old action num: 33
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 5
           58: # old action num: 34
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 6
           59: # old action num: 35
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 7
           60: # old action num: 36
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 8
           61: # old action num: 37
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 9
           62: # old action num: 38
             action: "HOST_NIC_DISABLE"
@@ -834,10 +834,10 @@ agents:
         - type: NODE_RESET
         - type: ROUTER_ACL_ADDRULE
           options:
-            target_router_nodename: router_1
+            target_router: router_1
         - type: ROUTER_ACL_REMOVERULE
           options:
-            target_router_nodename: router_1
+            target_router: router_1
         - type: HOST_NIC_ENABLE
         - type: HOST_NIC_DISABLE
 
@@ -1053,7 +1053,7 @@ agents:
           46: # old action num: 22 # "ACL: ADDRULE - Block outgoing traffic from client 1"
             action: "ROUTER_ACL_ADDRULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 1
                 permission: 2
                 source_ip_id: 7 # client 1
@@ -1066,7 +1066,7 @@ agents:
           47: # old action num: 23 # "ACL: ADDRULE - Block outgoing traffic from client 2"
             action: "ROUTER_ACL_ADDRULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 2
                 permission: 2
                 source_ip_id: 8 # client 2
@@ -1079,7 +1079,7 @@ agents:
           48: # old action num: 24 # block tcp traffic from client 1 to web app
             action: "ROUTER_ACL_ADDRULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 3
                 permission: 2
                 source_ip_id: 7 # client 1
@@ -1092,7 +1092,7 @@ agents:
           49: # old action num: 25 # block tcp traffic from client 2 to web app
             action: "ROUTER_ACL_ADDRULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 4
                 permission: 2
                 source_ip_id: 8 # client 2
@@ -1105,7 +1105,7 @@ agents:
           50: # old action num: 26
             action: "ROUTER_ACL_ADDRULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 5
                 permission: 2
                 source_ip_id: 7 # client 1
@@ -1118,7 +1118,7 @@ agents:
           51: # old action num: 27
             action: "ROUTER_ACL_ADDRULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 6
                 permission: 2
                 source_ip_id: 8 # client 2
@@ -1131,52 +1131,52 @@ agents:
           52: # old action num: 28
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 0
           53: # old action num: 29
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 1
           54: # old action num: 30
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 2
           55: # old action num: 31
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 3
           56: # old action num: 32
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 4
           57: # old action num: 33
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 5
           58: # old action num: 34
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 6
           59: # old action num: 35
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 7
           60: # old action num: 36
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 8
           61: # old action num: 37
             action: "ROUTER_ACL_REMOVERULE"
             options:
-                target_router_nodename: router_1
+                target_router: router_1
                 position: 9
           62: # old action num: 38
             action: "HOST_NIC_DISABLE"

src/primaite/config/_package_data/mini_scenario_with_simulation_variation/base_scenario.yaml

@@ -0,0 +1,86 @@
+game:
+  max_episode_length: 128
+  ports: []
+  protocols: []
+
+agents:
+  - ref: RL_Agent
+    type: ProxyAgent
+    observation_space: null
+    action_space:
+      action_list:
+        - type: DONOTHING
+        - type: NODE_SHUTDOWN
+        - type: NODE_STARTUP
+        - type: HOST_NIC_ENABLE
+        - type: HOST_NIC_DISABLE
+      action_map:
+        0:
+          action: DONOTHING
+          options: {}
+        1:
+          action: NODE_SHUTDOWN
+          options:
+            node_id: 0
+        2:
+          action: NODE_SHUTDOWN
+          options:
+            node_id: 1
+        3:
+          action: NODE_STARTUP
+          options:
+            node_id: 0
+        4:
+          action: NODE_STARTUP
+          options:
+            node_id: 1
+        5:
+          action: HOST_NIC_DISABLE
+          options:
+            node_id: 0
+            nic_id: 0
+        6:
+          action: HOST_NIC_DISABLE
+          options:
+            node_id: 1
+            nic_id: 0
+        7:
+          action: HOST_NIC_ENABLE
+          options:
+            node_id: 0
+            nic_id: 0
+        8:
+          action: HOST_NIC_ENABLE
+          options:
+            node_id: 1
+            nic_id: 0
+      options:
+        nodes:
+        - node_name: client_1
+        - node_name: server
+        max_folders_per_node: 0
+        max_files_per_folder: 0
+        max_services_per_node: 0
+        max_nics_per_node: 1
+        max_acl_rules: 0
+        ip_list:
+          - 192.168.1.2
+          - 192.168.1.3
+    reward_function:
+      reward_components: []
+
+simulation:
+  network:
+    nodes:
+      - hostname: server
+        type: server
+        ip_address: 192.168.1.2
+        subnet_mask: 255.255.255.0
+        default_gateway: 192.168.1.1
+        services: *server_services
+      - hostname: client_1
+        type: computer
+        ip_address: 192.168.1.3
+        subnet_mask: 255.255.255.0
+        default_gateway: 192.168.1.1
+        applications: *client_applications