Merge pull request #9 from Autonomous-Resilient-Cyber-Defence/dev

updated primaite logo

.azure/.pypirc

@@ -1,6 +0,0 @@
-[distutils]
-Index-servers =
-  PrimAITE
-
-[PrimAITE]
-Repository = https://pkgs.dev.azure.com/ma-dev-uk/PrimAITE/_packaging/PrimAITE/pypi/upload/

.azure/artifact-release-pipeline.yaml

@@ -1,38 +0,0 @@
-trigger:
-- main
-
-pool:
-  vmImage: ubuntu-latest
-strategy:
-  matrix:
-    Python310:
-      python.version: '3.10'
-
-steps:
-- task: UsePythonVersion@0
-  inputs:
-    versionSpec: '$(python.version)'
-  displayName: 'Use Python $(python.version)'
-
-- script: |
-    python -m pip install --upgrade pip==23.0.1
-    pip install wheel==0.38.4 --upgrade
-    pip install setuptools==66 --upgrade
-    pip install build==0.10.0
-    pip install twine
-    pip install keyring
-    pip install artifacts-keyring
-  displayName: 'Install build dependencies'
-
-- script: |
-    python -m build
-  displayName: 'Build PrimAITE sdist and wheel'
-
-- task: TwineAuthenticate@1
-  displayName: 'Twine Authenticate'
-  inputs:
-    artifactFeed: PrimAITE/PrimAITE
-
-- script: |
-    python -m twine upload --verbose -r PrimAITE --config-file  $(PYPIRC_PATH) dist/*.whl
-  displayName: 'Artifact Upload'

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

@@ -1,49 +0,0 @@
-name: Azure Static Web Apps CI/CD
-
-pr: none
-trigger:
-  branches:
-    include:
-      - dev
-
-jobs:
-- job: build_and_deploy_job
-  displayName: Build and Deploy Job
-  condition: or(eq(variables['Build.Reason'], 'Manual'),or(eq(variables['Build.Reason'], 'PullRequest'),eq(variables['Build.Reason'], 'IndividualCI')))
-  pool:
-    vmImage: ubuntu-latest
-  variables:
-  - group: Azure-Static-Web-Apps-nice-bay-0ad032c03-variable-group
-  steps:
-  - checkout: self
-    submodules: true
-
-  - script: |
-      python -m pip install --upgrade pip==23.0.1
-      pip install wheel==0.38.4 --upgrade
-      pip install setuptools==66 --upgrade
-      pip install build==0.10.0
-    displayName: 'Install build dependencies'
-
-  - script: |
-      pip install -e .[dev]
-    displayName: 'Install Yawning-Titan for docs autosummary'
-
-  - script: |
-      primaite setup
-    displayName: 'Perform PrimAITE Setup'
-
-  - script: |
-      cd docs
-      make html
-      cd ..
-      cd ..
-    displayName: 'Build Docs'
-
-  - task: AzureStaticWebApp@0
-    inputs:
-      azure_static_web_apps_api_token: $(AZURE_STATIC_WEB_APPS_API_TOKEN_NICE_BAY_0AD032C03)
-      app_location: "/docs/_build/html"
-      api_location: ""
-      output_location: "/"
-    displayName: 'Deploy Docs to nice-bay-0ad032c03'

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

@@ -1,90 +0,0 @@
-trigger:
-- main
-- dev
-- feature/*
-- hotfix/*
-- bugfix/*
-- release/*
-
-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'
-      img: 'ubuntu-latest'
-      every_time: true
-    - job_name: 'WindowsPython38'
-      py: '3.8'
-      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'
-      img: 'macOS-latest'
-      every_time: false
-
-stages:
-  - stage: Test
-    jobs:
-    - ${{ each item in parameters.matrix }}:
-      - job: ${{ item.job_name }}
-        pool:
-          vmImage: ${{ item.img }}
-
-        condition: or( eq(variables['Build.Reason'], 'PullRequest'), ${{ item.every_time }} )
-
-        steps:
-          - task: UsePythonVersion@0
-            inputs:
-              versionSpec: ${{ item.py }}
-            displayName: 'Use Python ${{ item.py }}'
-
-          - script: |
-              python -m pip install pre-commit
-              pre-commit install
-              pre-commit run --all-files
-            displayName: 'Run pre-commits'
-
-          - script: |
-              python -m pip install --upgrade pip==23.0.1
-              pip install wheel==0.38.4 --upgrade
-              pip install setuptools==66 --upgrade
-              pip install build==0.10.0
-              pip install pytest-azurepipelines
-            displayName: 'Install build dependencies'
-
-          - script: |
-              python -m build
-            displayName: 'Build PrimAITE'
-
-          - script: |
-              PRIMAITE_WHEEL=$(ls ./dist/primaite*.whl)
-              python -m pip install $PRIMAITE_WHEEL[dev]
-            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]"
-            displayName: 'Install PrimAITE'
-            condition: eq( variables['Agent.OS'], 'Windows_NT' )
-
-          - script: |
-              primaite setup
-            displayName: 'Perform PrimAITE Setup'
-
-          - script: |
-              pytest -n 4
-            displayName: 'Run tests'

.azuredevops/pull_request_template.md

@@ -1,12 +0,0 @@
-## Summary
-*Replace this text with an explanation of what the changes are and how you implemented them. Can this impact any other parts of the codebase that we should keep in mind?*
-
-## Test process
-*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

.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]
+
+      - 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]
+
+      - 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/

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! 🙌

README.md

@@ -1,50 +1,136 @@
 # 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, mission profiles 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 mission success;
+
+- Provision of logging to support AI evaluation and metrics gathering;
+
+- Uses the concept of Information Exchange Requirements (IERs) to model background pattern of life, adversarial behaviour and mission data (on a sliding scale of criticality);
+
+- 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 address, destination IP address, protocol and port);
+
+- Application of IERs to the platform / system laydown adheres to the ACL ruleset;
+
+- Presents an OpenAI gym or RLLib interface to the environment, allowing integration with any compliant defensive agents;
+
+- Full capture of discrete logs relating to agent training (full system state, agent actions taken, instantaneous and average reward for every step of every episode);
+
+- NetworkX provides laydown visualisation capability.
+
 ## Getting Started with PrimAITE
 
-### Pre-Requisites
+### 💫 Install & Run
-
-In order to get **PrimAITE** installed, you will need to have the following installed:
-
-- `python3.8+`
-- `python3-pip`
-- `virtualenv`
-
 **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
+#### Windows (PowerShell)
-#### 1. Navigate to the PrimAITE folder and create a new python virtual environment (venv)
 
-```unix
+**Prerequisites:**
-python3 -m venv <name_of_venv>
+* Manual install of Python >= 3.8 < 3.11
+
+**Install:**
+
+``` powershell
+mkdir ~\primaite
+cd ~\primaite
+python3 -m venv .venv
+attrib +h .venv /s /d # Hides the .venv directory
+.\.venv\Scripts\activate
+pip install https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE/releases/download/v2.0.0/primaite-2.0.0-py3-none-any.whl
+primaite setup
 ```
 
-#### 2. Activate the venv
+**Run:**
+
+``` bash
+primaite session
+```
+
+#### Unix
+
+**Prerequisites:**
+* Manual install of Python >= 3.8 < 3.11
+
+``` 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 https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE/releases/download/v2.0.0/primaite-2.0.0-py3-none-any.whl
+primaite setup
+```
+
+**Run:**
+
+``` bash
+primaite session
+```
+
+
+### 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 .
-```
-
-### Development Installation
-To install the development dependencies, postfix the command in step 3 above with the `[dev]` extra. Example:
 
 ```bash
 python3 -m pip install -e .[dev]
 ```
 
-## Building documentation
+#### 6. Perform the PrimAITE setup:
+
+```bash
+primaite setup
+```
+
+## 📚 Building documentation
 The PrimAITE documentation can be built with the following commands:
 
 ##### Unix
@@ -53,12 +139,8 @@ 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.

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

@@ -43,7 +43,6 @@ 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
 ]
 
 

docs/index.rst

@@ -6,20 +6,74 @@ 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 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;
+- Modelling an adversarial agent that the defensive agent can be trained and evaluated against;
+- The ability to model key characteristics of a platform / system by representing connections, IP addresses, ports, operating systems, services and traffic loading on links;
+- Modelling background pattern-of-life;
+- Operates at machine-speed to enable fast training cycles.
+
+Features
+^^^^^^^^
+
+PrimAITE incorporates the following features:
+
+- Highly configurable (via YAML files) to provide the means to model a variety of platform / system laydowns, mission profiles and adversarial attack scenarios;
+- A Reinforcement Learning (RL) reward function based on (a) the ability to counter the modelled adversarial cyber-attack, and (b) the ability to ensure mission success;
+- Provision of logging to support AI performance / effectiveness assessment;
+- Uses the concept of Information Exchange Requirements (IERs) to model background pattern of life, adversarial behaviour and mission data (on a sliding scale of criticality);
+- 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 address, destination IP address, protocol and port);
+- Application of traffic to the links of the platform / system laydown adheres to the ACL ruleset;
+- Presents both an OpenAI gym and Ray RLLib interface to the environment, allowing integration with any compliant defensive agents;
+- Allows for the saving and loading of trained defensive agents;
+- Stochastic adversarial agent behaviour;
+- Full capture of discrete logs relating to agent training or evaluation (system state, agent actions taken, instantaneous and average reward for every step of every episode);
+- Distinct control over running a training and / or evaluation session;
+- NetworkX provides laydown visualisation capability.
+
+Architecture
+^^^^^^^^^^^^
+
+PrimAITE is a Python application and is therefore Operating System agnostic. The OpenAI gym and Ray RLLib frameworks are employed to provide an interface and source for AI agents. Configuration of PrimAITE is achieved via included YAML files which support full control over the platform / system laydown being modelled, background pattern of life, adversarial (red agent) behaviour, and step and episode count. NetworkX based nodes and links host Python classes to present attributes and methods, and hence a more representative platform / system can be modelled within the simulation.
+
+
+
+Training & Evaluation Capability
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+PrimAITE provides a training and evaluation capability to AI agents in the context of cyber-attack, via its OpenAI Gym and RLLib compliant interface. Scenarios can be constructed to reflect platform / system laydowns consisting of any configuration of nodes (e.g. PCs, servers, switches etc.) and network links between them. All nodes can be configured to model services (and their status) and the traffic loading between them over the network links. Traffic loading is broken down into a per service granularity, relating directly to a protocol (e.g. Service A would be configured as a TCP service, and TCP traffic then flows between instances of Service A under the direction of a tailored IER). Highlights of PrimAITE’s training and evaluation capability are:
+
+- The scenario is not bound to a representation of any platform, system, technology or mission;
+- Fully configurable (network / system laydown, IERs, node pattern-of-life, ACL, number of episodes, steps per episode) and repeatable to suit the requirements of AI agents;
+- Can integrate with any OpenAI Gym or RLLib compliant AI agent.
+
+Use of PrimAITE default scenarios within ARCD is supported by a “Use Case Profile” tailored to the scenario.
+
+AI Assessment Capability
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+PrimAITE includes the capability to support in-depth assessment of cyber defence AI by outputting logs of the environment state and AI behaviour throughout both training and evaluation sessions. These logs include the following data:
+
+- Timestamp;
+- Episode and step number;
+- Agent identifier;
+- Observation space;
+- Action taken (by defensive AI);
+- Reward value.
+
+Logs are available in CSV format and provide coverage of the above data for every step of every episode.
 
-* 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.
 
-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).
 
-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).
 
 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
 * `Networkx <https://github.com/networkx/networkx>`_ is used as the underlying data structure used for the PrimAITE environment
@@ -31,8 +85,8 @@ 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!
 

docs/source/getting_started.rst

@@ -14,20 +14,19 @@ 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:
 
 
-.. tabs:: lang
+.. code-block:: bash
+    :caption: Unix
 
-    .. code-tab:: bash
+    sudo add-apt-repository ppa:deadsnakes/ppa
-        :caption: Unix
+    sudo apt install python3.10
+    sudo apt-get install python3-pip
+    sudo apt-get install python3-venv
 
-        sudo add-apt-repository ppa:deadsnakes/ppa
-        sudo apt install python3.10
-        sudo apt-get install python3-pip
-        sudo apt-get install python3-venv
 
-    .. code-tab:: text
+.. code-block:: text
-        :caption: Windows (Powershell)
+    :caption: Windows (Powershell)
 
-        - Manual install from: https://www.python.org/downloads/release/python-31011/
+    - 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.
 
@@ -36,30 +35,30 @@ Install PrimAITE
 
 1. Create a primaite directory in your home directory:
 
-.. tabs:: lang
 
-    .. code-tab:: bash
-        :caption: Unix
 
-        mkdir ~/primaite/2.0.0
+.. code-block:: bash
+    :caption: Unix
 
-    .. code-tab:: powershell
+    mkdir ~/primaite/2.0.0
-        :caption: Windows (Powershell)
 
-        mkdir ~\primaite\2.0.0
+.. code-block:: powershell
+    :caption: Windows (Powershell)
+
+    mkdir ~\primaite\2.0.0
 
 2. Navigate to the primaite directory and create a new python virtual environment (venv)
 
-.. tabs:: lang
 
-    .. code-tab:: bash
-        :caption: Unix
 
-        cd ~/primaite/2.0.0
+.. code-block:: bash
-        python3 -m venv .venv
+    :caption: Unix
 
-    .. code-tab:: powershell
+    cd ~/primaite/2.0.0
-        :caption: Windows (Powershell)
+    python3 -m venv .venv
+
+.. code-block:: powershell
+    :caption: Windows (Powershell)
 
         cd ~\primaite\2.0.0
         python3 -m venv .venv
@@ -67,44 +66,41 @@ Install PrimAITE
 
 3. Activate the venv
 
-.. tabs:: lang
 
-    .. code-tab:: bash
+.. code-block:: bash
-        :caption: Unix
+    :caption: Unix
 
-        source .venv/bin/activate
+    source .venv/bin/activate
 
-    .. code-tab:: powershell
+.. code-block:: powershell
-        :caption: Windows (Powershell)
+    :caption: Windows (Powershell)
 
-        .\.venv\Scripts\activate
+    .\.venv\Scripts\activate
 
 
 4. Install PrimAITE using pip from PyPi
 
-.. tabs:: lang
 
-    .. code-tab:: bash
+.. code-block:: bash
-        :caption: Unix
+    :caption: Unix
 
-        pip install primaite
+    pip install primaite
 
-    .. code-tab:: powershell
+.. code-block:: powershell
-        :caption: Windows (Powershell)
+    :caption: Windows (Powershell)
 
-        pip install primaite
+    pip install primaite
 
 5. Perform the PrimAITE setup
 
-.. tabs:: lang
 
-    .. code-tab:: bash
+.. code-block:: bash
-        :caption: Unix
+    :caption: Unix
 
-        primaite setup
+    primaite setup
 
-    .. code-tab:: powershell
+.. code-block:: powershell
-        :caption: Windows (Powershell)
+    :caption: Windows (Powershell)
 
         primaite setup
 
@@ -123,33 +119,31 @@ of your choice:
 
 Create and activate your Python virtual environment (venv)
 
-.. tabs:: lang
 
-    .. code-tab:: bash
+.. code-block:: bash
-        :caption: Unix
+    :caption: Unix
 
-        python3 -m venv venv
+    python3 -m venv venv
-        source venv/bin/activate
+    source venv/bin/activate
 
-    .. code-tab:: powershell
+.. code-block:: powershell
-        :caption: Windows (Powershell)
+    :caption: Windows (Powershell)
 
-        python3 -m venv venv
+    python3 -m venv venv
-        .\venv\Scripts\activate
+    .\venv\Scripts\activate
 
 Install PrimAITE with the dev extra
 
-.. tabs:: lang
 
-    .. code-tab:: bash
+.. code-block:: bash
-        :caption: Unix
+    :caption: Unix
 
-        pip install -e .[dev]
+    pip install -e .[dev]
 
-    .. code-tab:: powershell
+.. code-block:: powershell
-        :caption: Windows (Powershell)
+    :caption: Windows (Powershell)
 
-        pip install -e .[dev]
+    pip install -e .[dev]
 
 
 To view the complete list of packages installed during PrimAITE installation, go to the dependencies page (:ref:`Dependencies`).

docs/source/primaite_session.rst

@@ -15,31 +15,31 @@ A PrimAITE session can be ran either with the ``primaite session`` command from
 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
+.. code-block:: bash
-        :caption: Python
+    :caption: Unix CLI
 
-        from primaite.main import run
+    cd ~/primaite/2.0.0
+    source ./.venv/bin/activate
+    primaite session --tc ./config/my_training_config.yaml --ldc ./config/my_lay_down_config.yaml
 
-        training_config = <path to training config yaml file>
+.. code-block:: powershell
-        lay_down_config = <path to lay down config yaml file>
+    :caption: Powershell CLI
-        run(training_config, lay_down_config)
+
+    cd ~\primaite\2.0.0
+    .\.venv\Scripts\activate
+    primaite session --tc .\config\my_training_config.yaml --ldc .\config\my_lay_down_config.yaml
+
+
+.. code-block:: 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>/``
@@ -49,6 +49,36 @@ For example, when running a session at 17:30:00 on 31st January 2023, the sessio
 
 ``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``.
 
+To run a PrimAITE session using legacy training or laydown config files, add the ``--legacy-tc`` and/or ``legacy-ldc`` options.
+
+
+
+.. code-block:: bash
+    :caption: Unix CLI
+
+    cd ~/primaite/2.0.0
+    source ./.venv/bin/activate
+    primaite session --tc ./config/my_legacy_training_config.yaml --legacy-tc --ldc ./config/my_legacy_lay_down_config.yaml --legacy-ldc
+
+.. code-block:: powershell
+    :caption: Powershell CLI
+
+    cd ~\primaite\2.0.0
+    .\.venv\Scripts\activate
+    primaite session --tc .\config\my_legacy_training_config.yaml --legacy-tc --ldc .\config\my_legacy_lay_down_config.yaml --legacy-ldc
+
+
+.. code-block:: python
+    :caption: Python
+
+    from primaite.main import run
+
+    training_config = <path to legacy training config yaml file>
+    lay_down_config = <path to legacy lay down config yaml file>
+    run(training_config, lay_down_config, legacy_training_config=True, legacy_lay_down_config=True)
+
+
+
 
 Outputs
 -------

pyproject.toml

@@ -65,7 +65,6 @@ dev = [
     "pytest-flake8==1.1.1",
     "setuptools==66",
     "Sphinx==6.1.3",
-    "sphinx-code-tabs==0.5.3",
     "sphinx-copybutton==0.5.2",
     "wheel==0.38.4"
 ]
@@ -81,3 +80,9 @@ order_by_type = "False"
 
 [tool.black]
 line-length = 120
+
+[project.urls]
+Homepage = "https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE"
+Documentation = "https://Autonomous-Resilient-Cyber-Defence.github.io/PrimAITE/"
+Repository = "https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE"
+Changelog = "https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE/blob/dev/CHANGELOG.md"

setup.cfg

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

src/primaite/agents/agent_abc.py

@@ -52,6 +52,8 @@ class AgentSessionABC(ABC):
         training_config_path: Optional[Union[str, Path]] = None,
         lay_down_config_path: Optional[Union[str, Path]] = None,
         session_path: Optional[Union[str, Path]] = None,
+        legacy_training_config: bool = False,
+        legacy_lay_down_config: bool = False,
     ) -> None:
         """
         Initialise an agent session from config files, or load a previous session.
@@ -64,6 +66,10 @@ class AgentSessionABC(ABC):
         :type training_config_path: Union[path, str]
         :param lay_down_config_path: YAML file containing configurable items for generating network laydown.
         :type lay_down_config_path: Union[path, str]
+        :param legacy_training_config: True if the training config file is a legacy file from PrimAITE < 2.0,
+            otherwise False.
+        :param legacy_lay_down_config: True if the lay_down config file is a legacy file from PrimAITE < 2.0,
+            otherwise False.
         :param session_path: directory path of the session to load
         """
         # initialise variables
@@ -72,6 +78,8 @@ class AgentSessionABC(ABC):
         self._can_learn: bool = False
         self._can_evaluate: bool = False
         self.is_eval = False
+        self.legacy_training_config = legacy_training_config
+        self.legacy_lay_down_config = legacy_lay_down_config
 
         self.session_timestamp: datetime = datetime.now()
 
@@ -91,12 +99,14 @@ class AgentSessionABC(ABC):
             if not isinstance(training_config_path, Path):
                 training_config_path = Path(training_config_path)
             self._training_config_path: Union[Path, str] = training_config_path
-            self._training_config: TrainingConfig = training_config.load(self._training_config_path)
+            self._training_config: TrainingConfig = training_config.load(
+                self._training_config_path, legacy_file=legacy_training_config
+            )
 
             if not isinstance(lay_down_config_path, Path):
                 lay_down_config_path = Path(lay_down_config_path)
             self._lay_down_config_path: Union[Path, str] = lay_down_config_path
-            self._lay_down_config: Dict = lay_down_config.load(self._lay_down_config_path)
+            self._lay_down_config: Dict = lay_down_config.load(self._lay_down_config_path, legacy_lay_down_config)
             self.sb3_output_verbose_level = self._training_config.sb3_output_verbose_level
 
             # set random UUID for session

src/primaite/agents/sb3.py

@@ -26,6 +26,8 @@ class SB3Agent(AgentSessionABC):
         training_config_path: Optional[Union[str, Path]] = None,
         lay_down_config_path: Optional[Union[str, Path]] = None,
         session_path: Optional[Union[str, Path]] = None,
+        legacy_training_config: bool = False,
+        legacy_lay_down_config: bool = False,
     ) -> None:
         """
         Initialise the SB3 Agent training session.
@@ -35,11 +37,17 @@ class SB3Agent(AgentSessionABC):
         :type training_config_path: Union[path, str]
         :param lay_down_config_path: YAML file containing configurable items for generating network laydown.
         :type lay_down_config_path: Union[path, str]
+        :param legacy_training_config: True if the training config file is a legacy file from PrimAITE < 2.0,
+            otherwise False.
+        :param legacy_lay_down_config: True if the lay_down config file is a legacy file from PrimAITE < 2.0,
+            otherwise False.
         :raises ValueError: If the training config contains an unexpected value for agent_framework (should be "SB3")
         :raises ValueError: If the training config contains an unexpected value for agent_identifies (should be `PPO`
             or `A2C`)
         """
-        super().__init__(training_config_path, lay_down_config_path, session_path)
+        super().__init__(
+            training_config_path, lay_down_config_path, session_path, legacy_training_config, legacy_lay_down_config
+        )
         if not self._training_config.agent_framework == AgentFramework.SB3:
             msg = f"Expected SB3 agent_framework, " f"got {self._training_config.agent_framework}"
             _LOGGER.error(msg)
@@ -75,6 +83,8 @@ class SB3Agent(AgentSessionABC):
             lay_down_config_path=self._lay_down_config_path,
             session_path=self.session_path,
             timestamp_str=self.timestamp_str,
+            legacy_training_config=self.legacy_training_config,
+            legacy_lay_down_config=self.legacy_lay_down_config,
         )
 
         # check if there is a zip file that needs to be loaded

src/primaite/cli.py

@@ -18,9 +18,9 @@ app = typer.Typer()
 @app.command()
 def build_dirs() -> None:
     """Build the PrimAITE app directories."""
-    from primaite.setup import setup_app_dirs
+    from primaite import PRIMAITE_PATHS
 
-    setup_app_dirs.run()
+    PRIMAITE_PATHS.mkdirs()
 
 
 @app.command()
@@ -137,7 +137,13 @@ def setup(overwrite_existing: bool = True) -> None:
 
 
 @app.command()
-def session(tc: Optional[str] = None, ldc: Optional[str] = None, load: Optional[str] = None) -> None:
+def session(
+    tc: Optional[str] = None,
+    ldc: Optional[str] = None,
+    load: Optional[str] = None,
+    legacy_tc: bool = False,
+    legacy_ldc: bool = False,
+) -> None:
     """
     Run a PrimAITE session.
 
@@ -153,6 +159,10 @@ def session(tc: Optional[str] = None, ldc: Optional[str] = None, load: Optional[
     will use the default training config and laydown config. Inversely, if a training config and laydown config
     is passed while a session directory is passed, PrimAITE will load the session and ignore the training config
     and laydown config.
+
+    legacy_tc: If the training config file is a legacy file from PrimAITE < 2.0.
+
+    legacy_ldf: If the lay down config file is a legacy file from PrimAITE < 2.0.
     """
     from primaite.config.lay_down_config import dos_very_basic_config_path
     from primaite.config.training_config import main_training_config_path
@@ -170,7 +180,12 @@ def session(tc: Optional[str] = None, ldc: Optional[str] = None, load: Optional[
         if not ldc:
             ldc = dos_very_basic_config_path()
 
-        run(training_config_path=tc, lay_down_config_path=ldc)
+        run(
+            training_config_path=tc,
+            lay_down_config_path=ldc,
+            legacy_training_config=legacy_tc,
+            legacy_lay_down_config=legacy_ldc,
+        )
 
 
 @app.command()

src/primaite/config/lay_down_config.py

@@ -1,7 +1,7 @@
 # © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
 from logging import Logger
 from pathlib import Path
-from typing import Any, Dict, Final, Union
+from typing import Any, Dict, Final, List, Union
 
 import yaml
 
@@ -12,14 +12,43 @@ _LOGGER: Logger = getLogger(__name__)
 _EXAMPLE_LAY_DOWN: Final[Path] = PRIMAITE_PATHS.user_config_path / "example_config" / "lay_down"
 
 
-def convert_legacy_lay_down_config_dict(legacy_config_dict: Dict[str, Any]) -> Dict[str, Any]:
+def convert_legacy_lay_down_config(legacy_config: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
     """
-    Convert a legacy lay down config dict to the new format.
+    Convert a legacy lay down config to the new format.
 
-    :param legacy_config_dict: A legacy lay down config dict.
+    :param legacy_config: A legacy lay down config.
     """
-    _LOGGER.warning("Legacy lay down config conversion not yet implemented")
+    field_conversion_map = {
-    return legacy_config_dict
+        "itemType": "item_type",
+        "portsList": "ports_list",
+        "serviceList": "service_list",
+        "baseType": "node_class",
+        "nodeType": "node_type",
+        "hardwareState": "hardware_state",
+        "softwareState": "software_state",
+        "startStep": "start_step",
+        "endStep": "end_step",
+        "fileSystemState": "file_system_state",
+        "ipAddress": "ip_address",
+        "missionCriticality": "mission_criticality",
+    }
+    new_config = []
+    for item in legacy_config:
+        if "itemType" in item:
+            if item["itemType"] in ["ACTIONS", "STEPS"]:
+                continue
+        new_dict = {}
+        for key in item.keys():
+            conversion_key = field_conversion_map.get(key)
+            if key == "id" and "itemType" in item:
+                if item["itemType"] == "NODE":
+                    conversion_key = "node_id"
+            if conversion_key:
+                new_dict[conversion_key] = item[key]
+            else:
+                new_dict[key] = item[key]
+        new_config.append(new_dict)
+    return new_config
 
 
 def load(file_path: Union[str, Path], legacy_file: bool = False) -> Dict:
@@ -39,7 +68,7 @@ def load(file_path: Union[str, Path], legacy_file: bool = False) -> Dict:
             _LOGGER.debug(f"Loading lay down config file: {file_path}")
         if legacy_file:
             try:
-                config = convert_legacy_lay_down_config_dict(config)
+                config = convert_legacy_lay_down_config(config)
             except KeyError:
                 msg = (
                     f"Failed to convert lay down config file {file_path} "

src/primaite/config/training_config.py

@@ -291,12 +291,14 @@ def load(file_path: Union[str, Path], legacy_file: bool = False) -> TrainingConf
         if legacy_file:
             try:
                 config = convert_legacy_training_config_dict(config)
-            except KeyError:
+
+            except KeyError as e:
                 msg = (
                     f"Failed to convert training config file {file_path} "
                     f"from legacy format. Attempting to use file as is."
                 )
                 _LOGGER.error(msg)
+                raise e
         try:
             return TrainingConfig.from_dict(config)
         except TypeError as e:
@@ -314,6 +316,9 @@ def convert_legacy_training_config_dict(
     agent_identifier: AgentIdentifier = AgentIdentifier.PPO,
     action_type: ActionType = ActionType.ANY,
     num_train_steps: int = 256,
+    num_eval_steps: int = 256,
+    num_train_episodes: int = 10,
+    num_eval_episodes: int = 1,
 ) -> Dict[str, Any]:
     """
     Convert a legacy training config dict to the new format.
@@ -325,8 +330,14 @@ def convert_legacy_training_config_dict(
         training configs don't have agent_identifier values.
     :param action_type: The action space type to set as legacy training configs
         don't have action_type values.
-    :param num_train_steps: The number of steps to set as legacy training configs
+    :param num_train_steps: The number of train steps to set as legacy training configs
         don't have num_train_steps values.
+    :param num_eval_steps: The number of eval steps to set as legacy training configs
+        don't have num_eval_steps values.
+    :param num_train_episodes: The number of train episodes to set as legacy training configs
+        don't have num_train_episodes values.
+    :param num_eval_episodes: The number of eval episodes to set as legacy training configs
+        don't have num_eval_episodes values.
     :return: The converted training config dict.
     """
     config_dict = {
@@ -334,6 +345,9 @@ def convert_legacy_training_config_dict(
         "agent_identifier": agent_identifier.name,
         "action_type": action_type.name,
         "num_train_steps": num_train_steps,
+        "num_eval_steps": num_eval_steps,
+        "num_train_episodes": num_train_episodes,
+        "num_eval_episodes": num_eval_episodes,
         "sb3_output_verbose_level": SB3OutputVerboseLevel.INFO.name,
     }
     session_type_map = {"TRAINING": "TRAIN", "EVALUATION": "EVAL"}

src/primaite/environment/primaite_env.py

@@ -10,7 +10,6 @@ from typing import Any, Dict, Final, List, Tuple, Union
 
 import networkx as nx
 import numpy as np
-import yaml
 from gym import Env, spaces
 from matplotlib import pyplot as plt
 
@@ -34,6 +33,7 @@ from primaite.common.enums import (
 )
 from primaite.common.service import Service
 from primaite.config import training_config
+from primaite.config.lay_down_config import load
 from primaite.config.training_config import TrainingConfig
 from primaite.environment.observations import ObservationsHandler
 from primaite.environment.reward import calculate_reward_function
@@ -68,6 +68,8 @@ class Primaite(Env):
         lay_down_config_path: Union[str, Path],
         session_path: Path,
         timestamp_str: str,
+        legacy_training_config: bool = False,
+        legacy_lay_down_config: bool = False,
     ) -> None:
         """
         The Primaite constructor.
@@ -76,13 +78,19 @@ class Primaite(Env):
         :param lay_down_config_path: The lay down config filepath.
         :param session_path: The directory path the session is writing to.
         :param timestamp_str: The session timestamp in the format: <yyyy-mm-dd>_<hh-mm- ss>.
+        :param legacy_training_config: True if the training config file is a legacy file from PrimAITE < 2.0,
+            otherwise False.
+        :param legacy_lay_down_config: True if the lay_down config file is a legacy file from PrimAITE < 2.0,
+            otherwise False.
         """
         self.session_path: Final[Path] = session_path
         self.timestamp_str: Final[str] = timestamp_str
         self._training_config_path: Union[str, Path] = training_config_path
         self._lay_down_config_path: Union[str, Path] = lay_down_config_path
+        self.legacy_training_config = legacy_training_config
+        self.legacy_lay_down_config = legacy_lay_down_config
 
-        self.training_config: TrainingConfig = training_config.load(training_config_path)
+        self.training_config: TrainingConfig = training_config.load(training_config_path, self.legacy_training_config)
         _LOGGER.info(f"Using: {str(self.training_config)}")
 
         # Number of steps in an episode
@@ -191,11 +199,8 @@ class Primaite(Env):
         self._obs_space_description: List[str] = None
         "The env observation space description for transactions writing"
 
-        # Open the config file and build the environment laydown
+        self.lay_down_config = load(self._lay_down_config_path, self.legacy_lay_down_config)
-        with open(self._lay_down_config_path, "r") as file:
+        self.load_lay_down_config()
-            # Open the config file and build the environment laydown
-            self.lay_down_config = yaml.safe_load(file)
-            self.load_lay_down_config()
 
         # Store the node objects as node attributes
         # (This is so we can access them as objects)
@@ -1027,7 +1032,7 @@ class Primaite(Env):
         acl_rule_destination = item["destination"]
         acl_rule_protocol = item["protocol"]
         acl_rule_port = item["port"]
-        acl_rule_position = item["position"]
+        acl_rule_position = item.get("position")
 
         self.acl.add_rule(
             acl_rule_permission,

src/primaite/main.py

@@ -14,18 +14,26 @@ def run(
     training_config_path: Optional[Union[str, Path]] = "",
     lay_down_config_path: Optional[Union[str, Path]] = "",
     session_path: Optional[Union[str, Path]] = None,
+    legacy_training_config: bool = False,
+    legacy_lay_down_config: bool = False,
 ) -> None:
     """
     Run the PrimAITE Session.
 
     :param training_config_path: YAML file containing configurable items defined in
             `primaite.config.training_config.TrainingConfig`
-        :type training_config_path: Union[path, str]
+    :type training_config_path: Union[path, str]
-        :param lay_down_config_path: YAML file containing configurable items for generating network laydown.
+    :param lay_down_config_path: YAML file containing configurable items for generating network laydown.
-        :type lay_down_config_path: Union[path, str]
+    :type lay_down_config_path: Union[path, str]
-        :param session_path: directory path of the session to load
+    :param session_path: directory path of the session to load
+    :param legacy_training_config: True if the training config file is a legacy file from PrimAITE < 2.0,
+        otherwise False.
+    :param legacy_lay_down_config: True if the lay_down config file is a legacy file from PrimAITE < 2.0,
+        otherwise False.
     """
-    session = PrimaiteSession(training_config_path, lay_down_config_path, session_path)
+    session = PrimaiteSession(
+        training_config_path, lay_down_config_path, session_path, legacy_training_config, legacy_lay_down_config
+    )
 
     session.setup()
     session.learn()

src/primaite/primaite_session.py

@@ -34,6 +34,8 @@ class PrimaiteSession:
         training_config_path: Optional[Union[str, Path]] = "",
         lay_down_config_path: Optional[Union[str, Path]] = "",
         session_path: Optional[Union[str, Path]] = None,
+        legacy_training_config: bool = False,
+        legacy_lay_down_config: bool = False,
     ) -> None:
         """
         The PrimaiteSession constructor.
@@ -44,12 +46,18 @@ class PrimaiteSession:
         :param lay_down_config_path: YAML file containing configurable items for generating network laydown.
         :type lay_down_config_path: Union[path, str]
         :param session_path: directory path of the session to load
+        :param legacy_training_config: True if the training config file is a legacy file from PrimAITE < 2.0,
+            otherwise False.
+        :param legacy_lay_down_config: True if the lay_down config file is a legacy file from PrimAITE < 2.0,
+            otherwise False.
         """
         self._agent_session: AgentSessionABC = None  # noqa
         self.session_path: Path = session_path  # noqa
         self.timestamp_str: str = None  # noqa
         self.learning_path: Path = None  # noqa
         self.evaluation_path: Path = None  # noqa
+        self.legacy_training_config = legacy_training_config
+        self.legacy_lay_down_config = legacy_lay_down_config
 
         # check if session path is provided
         if session_path is not None:
@@ -67,12 +75,14 @@ class PrimaiteSession:
         if not isinstance(training_config_path, Path):
             training_config_path = Path(training_config_path)
         self._training_config_path: Final[Union[Path, str]] = training_config_path
-        self._training_config: Final[TrainingConfig] = training_config.load(self._training_config_path)
+        self._training_config: Final[TrainingConfig] = training_config.load(
+            self._training_config_path, legacy_training_config
+        )
 
         if not isinstance(lay_down_config_path, Path):
             lay_down_config_path = Path(lay_down_config_path)
         self._lay_down_config_path: Final[Union[Path, str]] = lay_down_config_path
-        self._lay_down_config: Dict = lay_down_config.load(self._lay_down_config_path)  # noqa
+        self._lay_down_config: Dict = lay_down_config.load(self._lay_down_config_path, legacy_lay_down_config)  # noqa
 
     def setup(self) -> None:
         """Performs the session setup."""
@@ -139,7 +149,13 @@ class PrimaiteSession:
         elif self._training_config.agent_framework == AgentFramework.SB3:
             _LOGGER.debug(f"PrimaiteSession Setup: Agent Framework = {AgentFramework.SB3}")
             # Stable Baselines3 Agent
-            self._agent_session = SB3Agent(self._training_config_path, self._lay_down_config_path, self.session_path)
+            self._agent_session = SB3Agent(
+                self._training_config_path,
+                self._lay_down_config_path,
+                self.session_path,
+                self.legacy_training_config,
+                self.legacy_lay_down_config,
+            )
 
         elif self._training_config.agent_framework == AgentFramework.RLLIB:
             _LOGGER.debug(f"PrimaiteSession Setup: Agent Framework = {AgentFramework.RLLIB}")

tests/config/legacy_conversion/legacy_config_1_DDOS_BASIC.yaml

@@ -0,0 +1,170 @@
+# © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+- itemType: ACTIONS
+  type: NODE
+- itemType: STEPS
+  steps: 128
+- itemType: PORTS
+  portsList:
+  - port: '80'
+- itemType: SERVICES
+  serviceList:
+  - name: TCP
+- itemType: NODE
+  id: '1'
+  name: PC1
+  baseType: SERVICE
+  nodeType: COMPUTER
+  priority: P5
+  hardwareState: 'ON'
+  ipAddress: 192.168.1.2
+  softwareState: GOOD
+  fileSystemState: GOOD
+  services:
+  - name: TCP
+    port: '80'
+    state: GOOD
+- itemType: NODE
+  id: '2'
+  name: SERVER
+  baseType: SERVICE
+  nodeType: SERVER
+  priority: P5
+  hardwareState: 'ON'
+  ipAddress: 192.168.1.3
+  softwareState: GOOD
+  fileSystemState: GOOD
+  services:
+  - name: TCP
+    port: '80'
+    state: GOOD
+- itemType: NODE
+  id: '3'
+  name: PC2
+  baseType: SERVICE
+  nodeType: COMPUTER
+  priority: P5
+  hardwareState: 'ON'
+  ipAddress: 192.168.1.4
+  softwareState: GOOD
+  fileSystemState: GOOD
+  services:
+  - name: TCP
+    port: '80'
+    state: GOOD
+- itemType: NODE
+  id: '4'
+  name: SWITCH1
+  baseType: ACTIVE
+  nodeType: SWITCH
+  priority: P2
+  hardwareState: 'ON'
+  ipAddress: 192.168.1.5
+  softwareState: GOOD
+  fileSystemState: GOOD
+- itemType: NODE
+  id: '5'
+  name: SWITCH2
+  baseType: ACTIVE
+  nodeType: SWITCH
+  priority: P2
+  hardwareState: 'ON'
+  ipAddress: 192.168.1.6
+  softwareState: GOOD
+  fileSystemState: GOOD
+- itemType: NODE
+  id: '6'
+  name: SWITCH3
+  baseType: ACTIVE
+  nodeType: SWITCH
+  priority: P2
+  hardwareState: 'ON'
+  ipAddress: 192.168.1.7
+  softwareState: GOOD
+  fileSystemState: GOOD
+- itemType: LINK
+  id: '7'
+  name: link1
+  bandwidth: 1000000000
+  source: '1'
+  destination: '4'
+- itemType: LINK
+  id: '8'
+  name: link2
+  bandwidth: 1000000000
+  source: '4'
+  destination: '2'
+- itemType: LINK
+  id: '9'
+  name: link3
+  bandwidth: 1000000000
+  source: '2'
+  destination: '5'
+- itemType: LINK
+  id: '10'
+  name: link4
+  bandwidth: 1000000000
+  source: '2'
+  destination: '6'
+- itemType: LINK
+  id: '11'
+  name: link5
+  bandwidth: 1000000000
+  source: '5'
+  destination: '3'
+- itemType: LINK
+  id: '12'
+  name: link6
+  bandwidth: 1000000000
+  source: '6'
+  destination: '3'
+- itemType: GREEN_IER
+  id: '13'
+  startStep: 1
+  endStep: 128
+  load: 100000
+  protocol: TCP
+  port: '80'
+  source: '3'
+  destination: '2'
+  missionCriticality: 5
+- itemType: RED_POL
+  id: '14'
+  startStep: 50
+  endStep: 50
+  targetNodeId: '1'
+  initiator: DIRECT
+  type: SERVICE
+  protocol: TCP
+  state: COMPROMISED
+  sourceNodeId: NA
+  sourceNodeService: NA
+  sourceNodeServiceState: NA
+- itemType: RED_IER
+  id: '15'
+  startStep: 60
+  endStep: 100
+  load: 1000000
+  protocol: TCP
+  port: '80'
+  source: '1'
+  destination: '2'
+  missionCriticality: 0
+- itemType: RED_POL
+  id: '16'
+  startStep: 80
+  endStep: 80
+  targetNodeId: '2'
+  initiator: IER
+  type: SERVICE
+  protocol: TCP
+  state: COMPROMISED
+  sourceNodeId: NA
+  sourceNodeService: NA
+  sourceNodeServiceState: NA
+- itemType: ACL_RULE
+  id: '17'
+  permission: ALLOW
+  source: ANY
+  destination: ANY
+  protocol: ANY
+  port: ANY

tests/config/legacy_conversion/legacy_config_2_DDOS_BASIC.yaml

@@ -0,0 +1,362 @@
+# © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+- itemType: ACTIONS
+  type: NODE
+- itemType: STEPS
+  steps: 128
+- itemType: PORTS
+  portsList:
+  - port: '80'
+- itemType: SERVICES
+  serviceList:
+  - name: TCP
+- itemType: NODE
+  id: '1'
+  name: PC1
+  baseType: SERVICE
+  nodeType: COMPUTER
+  priority: P5
+  hardwareState: 'ON'
+  ipAddress: 192.168.10.11
+  softwareState: GOOD
+  fileSystemState: GOOD
+  services:
+  - name: TCP
+    port: '80'
+    state: GOOD
+- itemType: NODE
+  id: '2'
+  name: PC2
+  baseType: SERVICE
+  nodeType: COMPUTER
+  priority: P5
+  hardwareState: 'ON'
+  ipAddress: 192.168.10.12
+  softwareState: GOOD
+  fileSystemState: GOOD
+  services:
+  - name: TCP
+    port: '80'
+    state: GOOD
+- itemType: NODE
+  id: '3'
+  name: PC3
+  baseType: SERVICE
+  nodeType: COMPUTER
+  priority: P5
+  hardwareState: 'ON'
+  ipAddress: 192.168.10.13
+  softwareState: GOOD
+  fileSystemState: GOOD
+  services:
+  - name: TCP
+    port: '80'
+    state: GOOD
+- itemType: NODE
+  id: '4'
+  name: PC4
+  baseType: SERVICE
+  nodeType: COMPUTER
+  priority: P5
+  hardwareState: 'ON'
+  ipAddress: 192.168.20.14
+  softwareState: GOOD
+  fileSystemState: GOOD
+  services:
+  - name: TCP
+    port: '80'
+    state: GOOD
+- itemType: NODE
+  id: '5'
+  name: SWITCH1
+  baseType: ACTIVE
+  nodeType: SWITCH
+  priority: P2
+  hardwareState: 'ON'
+  ipAddress: 192.168.1.2
+  softwareState: GOOD
+  fileSystemState: GOOD
+- itemType: NODE
+  id: '6'
+  name: IDS
+  baseType: SERVICE
+  nodeType: SERVER
+  priority: P5
+  hardwareState: 'ON'
+  ipAddress: 192.168.1.4
+  softwareState: GOOD
+  fileSystemState: GOOD
+  services:
+  - name: TCP
+    port: '80'
+    state: GOOD
+- itemType: NODE
+  id: '7'
+  name: SWITCH2
+  baseType: ACTIVE
+  nodeType: SWITCH
+  priority: P2
+  hardwareState: 'ON'
+  ipAddress: 192.168.1.3
+  softwareState: GOOD
+  fileSystemState: GOOD
+- itemType: NODE
+  id: '8'
+  name: LOP1
+  baseType: SERVICE
+  nodeType: LOP
+  priority: P5
+  hardwareState: 'ON'
+  ipAddress: 192.168.1.12
+  softwareState: GOOD
+  fileSystemState: GOOD
+  services:
+  - name: TCP
+    port: '80'
+    state: GOOD
+- itemType: NODE
+  id: '9'
+  name: SERVER1
+  baseType: SERVICE
+  nodeType: SERVER
+  priority: P5
+  hardwareState: 'ON'
+  ipAddress: 192.168.10.14
+  softwareState: GOOD
+  fileSystemState: GOOD
+  services:
+  - name: TCP
+    port: '80'
+    state: GOOD
+- itemType: NODE
+  id: '10'
+  name: SERVER2
+  baseType: SERVICE
+  nodeType: SERVER
+  priority: P5
+  hardwareState: 'ON'
+  ipAddress: 192.168.20.15
+  softwareState: GOOD
+  fileSystemState: GOOD
+  services:
+  - name: TCP
+    port: '80'
+    state: GOOD
+- itemType: LINK
+  id: '11'
+  name: link1
+  bandwidth: 1000000000
+  source: '1'
+  destination: '5'
+- itemType: LINK
+  id: '12'
+  name: link2
+  bandwidth: 1000000000
+  source: '2'
+  destination: '5'
+- itemType: LINK
+  id: '13'
+  name: link3
+  bandwidth: 1000000000
+  source: '3'
+  destination: '5'
+- itemType: LINK
+  id: '14'
+  name: link4
+  bandwidth: 1000000000
+  source: '4'
+  destination: '5'
+- itemType: LINK
+  id: '15'
+  name: link5
+  bandwidth: 1000000000
+  source: '5'
+  destination: '6'
+- itemType: LINK
+  id: '16'
+  name: link6
+  bandwidth: 1000000000
+  source: '5'
+  destination: '8'
+- itemType: LINK
+  id: '17'
+  name: link7
+  bandwidth: 1000000000
+  source: '6'
+  destination: '7'
+- itemType: LINK
+  id: '18'
+  name: link8
+  bandwidth: 1000000000
+  source: '8'
+  destination: '7'
+- itemType: LINK
+  id: '19'
+  name: link9
+  bandwidth: 1000000000
+  source: '7'
+  destination: '9'
+- itemType: LINK
+  id: '20'
+  name: link10
+  bandwidth: 1000000000
+  source: '7'
+  destination: '10'
+- itemType: GREEN_IER
+  id: '21'
+  startStep: 1
+  endStep: 128
+  load: 100000
+  protocol: TCP
+  port: '80'
+  source: '1'
+  destination: '9'
+  missionCriticality: 2
+- itemType: GREEN_IER
+  id: '22'
+  startStep: 1
+  endStep: 128
+  load: 100000
+  protocol: TCP
+  port: '80'
+  source: '2'
+  destination: '9'
+  missionCriticality: 2
+- itemType: GREEN_IER
+  id: '23'
+  startStep: 1
+  endStep: 128
+  load: 100000
+  protocol: TCP
+  port: '80'
+  source: '9'
+  destination: '3'
+  missionCriticality: 5
+- itemType: GREEN_IER
+  id: '24'
+  startStep: 1
+  endStep: 128
+  load: 100000
+  protocol: TCP
+  port: '80'
+  source: '4'
+  destination: '10'
+  missionCriticality: 2
+- itemType: ACL_RULE
+  id: '25'
+  permission: ALLOW
+  source: 192.168.10.11
+  destination: 192.168.10.14
+  protocol: TCP
+  port: 80
+- itemType: ACL_RULE
+  id: '26'
+  permission: ALLOW
+  source: 192.168.10.12
+  destination: 192.168.10.14
+  protocol: TCP
+  port: 80
+- itemType: ACL_RULE
+  id: '27'
+  permission: ALLOW
+  source: 192.168.10.13
+  destination: 192.168.10.14
+  protocol: TCP
+  port: 80
+- itemType: ACL_RULE
+  id: '28'
+  permission: ALLOW
+  source: 192.168.20.14
+  destination: 192.168.20.15
+  protocol: TCP
+  port: 80
+- itemType: ACL_RULE
+  id: '29'
+  permission: ALLOW
+  source: 192.168.10.14
+  destination: 192.168.10.13
+  protocol: TCP
+  port: 80
+- itemType: ACL_RULE
+  id: '30'
+  permission: DENY
+  source: 192.168.10.11
+  destination: 192.168.20.15
+  protocol: TCP
+  port: 80
+- itemType: ACL_RULE
+  id: '31'
+  permission: DENY
+  source: 192.168.10.12
+  destination: 192.168.20.15
+  protocol: TCP
+  port: 80
+- itemType: ACL_RULE
+  id: '32'
+  permission: DENY
+  source: 192.168.10.13
+  destination: 192.168.20.15
+  protocol: TCP
+  port: 80
+- itemType: ACL_RULE
+  id: '33'
+  permission: DENY
+  source: 192.168.20.14
+  destination: 192.168.10.14
+  protocol: TCP
+  port: 80
+- itemType: RED_POL
+  id: '34'
+  startStep: 20
+  endStep: 20
+  targetNodeId: '1'
+  initiator: DIRECT
+  type: SERVICE
+  protocol: TCP
+  state: COMPROMISED
+  sourceNodeId: NA
+  sourceNodeService: NA
+  sourceNodeServiceState: NA
+- itemType: RED_POL
+  id: '35'
+  startStep: 20
+  endStep: 20
+  targetNodeId: '2'
+  initiator: DIRECT
+  type: SERVICE
+  protocol: TCP
+  state: COMPROMISED
+  sourceNodeId: NA
+  sourceNodeService: NA
+  sourceNodeServiceState: NA
+- itemType: RED_IER
+  id: '36'
+  startStep: 30
+  endStep: 128
+  load: 440000000
+  protocol: TCP
+  port: '80'
+  source: '1'
+  destination: '9'
+  missionCriticality: 0
+- itemType: RED_IER
+  id: '37'
+  startStep: 30
+  endStep: 128
+  load: 440000000
+  protocol: TCP
+  port: '80'
+  source: '2'
+  destination: '9'
+  missionCriticality: 0
+- itemType: RED_POL
+  id: '38'
+  startStep: 30
+  endStep: 30
+  targetNodeId: '9'
+  initiator: IER
+  type: SERVICE
+  protocol: TCP
+  state: OVERWHELMED
+  sourceNodeId: NA
+  sourceNodeService: NA
+  sourceNodeServiceState: NA

tests/config/legacy_conversion/legacy_config_3_DOS_VERY_BASIC.yaml

@@ -0,0 +1,166 @@
+# © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+- itemType: ACTIONS
+  type: NODE
+- itemType: STEPS
+  steps: 256
+- itemType: PORTS
+  portsList:
+  - port: '80'
+- itemType: SERVICES
+  serviceList:
+  - name: TCP
+- itemType: NODE
+  id: '1'
+  name: PC1
+  baseType: SERVICE
+  nodeType: COMPUTER
+  priority: P5
+  hardwareState: 'ON'
+  ipAddress: 192.168.1.2
+  softwareState: GOOD
+  fileSystemState: GOOD
+  services:
+  - name: TCP
+    port: '80'
+    state: GOOD
+- itemType: NODE
+  id: '2'
+  name: PC2
+  baseType: SERVICE
+  nodeType: COMPUTER
+  priority: P5
+  hardwareState: 'ON'
+  ipAddress: 192.168.1.3
+  softwareState: GOOD
+  fileSystemState: GOOD
+  services:
+  - name: TCP
+    port: '80'
+    state: GOOD
+- itemType: NODE
+  id: '3'
+  name: SWITCH1
+  baseType: ACTIVE
+  nodeType: SWITCH
+  priority: P2
+  hardwareState: 'ON'
+  ipAddress: 192.168.1.1
+  softwareState: GOOD
+  fileSystemState: GOOD
+- itemType: NODE
+  id: '4'
+  name: SERVER1
+  baseType: SERVICE
+  nodeType: SERVER
+  priority: P5
+  hardwareState: 'ON'
+  ipAddress: 192.168.1.4
+  softwareState: GOOD
+  fileSystemState: GOOD
+  services:
+  - name: TCP
+    port: '80'
+    state: GOOD
+- itemType: LINK
+  id: '5'
+  name: link1
+  bandwidth: 1000000000
+  source: '1'
+  destination: '3'
+- itemType: LINK
+  id: '6'
+  name: link2
+  bandwidth: 1000000000
+  source: '2'
+  destination: '3'
+- itemType: LINK
+  id: '7'
+  name: link3
+  bandwidth: 1000000000
+  source: '3'
+  destination: '4'
+- itemType: GREEN_IER
+  id: '8'
+  startStep: 1
+  endStep: 256
+  load: 10000
+  protocol: TCP
+  port: '80'
+  source: '1'
+  destination: '4'
+  missionCriticality: 1
+- itemType: GREEN_IER
+  id: '9'
+  startStep: 1
+  endStep: 256
+  load: 10000
+  protocol: TCP
+  port: '80'
+  source: '2'
+  destination: '4'
+  missionCriticality: 1
+- itemType: GREEN_IER
+  id: '10'
+  startStep: 1
+  endStep: 256
+  load: 10000
+  protocol: TCP
+  port: '80'
+  source: '4'
+  destination: '2'
+  missionCriticality: 5
+- itemType: ACL_RULE
+  id: '11'
+  permission: ALLOW
+  source: 192.168.1.2
+  destination: 192.168.1.4
+  protocol: TCP
+  port: 80
+- itemType: ACL_RULE
+  id: '12'
+  permission: ALLOW
+  source: 192.168.1.3
+  destination: 192.168.1.4
+  protocol: TCP
+  port: 80
+- itemType: ACL_RULE
+  id: '13'
+  permission: ALLOW
+  source: 192.168.1.4
+  destination: 192.168.1.3
+  protocol: TCP
+  port: 80
+- itemType: RED_POL
+  id: '14'
+  startStep: 20
+  endStep: 20
+  targetNodeId: '1'
+  initiator: DIRECT
+  type: SERVICE
+  protocol: TCP
+  state: COMPROMISED
+  sourceNodeId: NA
+  sourceNodeService: NA
+  sourceNodeServiceState: NA
+- itemType: RED_IER
+  id: '15'
+  startStep: 30
+  endStep: 256
+  load: 10000000
+  protocol: TCP
+  port: '80'
+  source: '1'
+  destination: '4'
+  missionCriticality: 0
+- itemType: RED_POL
+  id: '16'
+  startStep: 40
+  endStep: 40
+  targetNodeId: '4'
+  initiator: IER
+  type: SERVICE
+  protocol: TCP
+  state: OVERWHELMED
+  sourceNodeId: NA
+  sourceNodeService: NA
+  sourceNodeServiceState: NA

tests/config/legacy_conversion/legacy_config_5_DATA_MANIPULATION.yaml

@@ -0,0 +1,534 @@
+# © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+- itemType: ACTIONS
+  type: NODE
+- itemType: STEPS
+  steps: 256
+- itemType: PORTS
+  portsList:
+  - port: '80'
+  - port: '1433'
+  - port: '53'
+- itemType: SERVICES
+  serviceList:
+  - name: TCP
+  - name: TCP_SQL
+  - name: UDP
+- itemType: NODE
+  id: '1'
+  name: CLIENT_1
+  baseType: SERVICE
+  nodeType: COMPUTER
+  priority: P5
+  hardwareState: 'ON'
+  ipAddress: 192.168.10.11
+  softwareState: GOOD
+  fileSystemState: GOOD
+  services:
+  - name: TCP
+    port: '80'
+    state: GOOD
+  - name: UDP
+    port: '53'
+    state: GOOD
+- itemType: NODE
+  id: '2'
+  name: CLIENT_2
+  baseType: SERVICE
+  nodeType: COMPUTER
+  priority: P5
+  hardwareState: 'ON'
+  ipAddress: 192.168.10.12
+  softwareState: GOOD
+  fileSystemState: GOOD
+  services:
+  - name: TCP
+    port: '80'
+    state: GOOD
+- itemType: NODE
+  id: '3'
+  name: SWITCH_1
+  baseType: ACTIVE
+  nodeType: SWITCH
+  priority: P2
+  hardwareState: 'ON'
+  ipAddress: 192.168.10.1
+  softwareState: GOOD
+  fileSystemState: GOOD
+- itemType: NODE
+  id: '4'
+  name: SECURITY_SUITE
+  baseType: SERVICE
+  nodeType: SERVER
+  priority: P5
+  hardwareState: 'ON'
+  ipAddress: 192.168.1.10
+  softwareState: GOOD
+  fileSystemState: GOOD
+  services:
+  - name: TCP
+    port: '80'
+    state: GOOD
+  - name: UDP
+    port: '53'
+    state: GOOD
+- itemType: NODE
+  id: '5'
+  name: MANAGEMENT_CONSOLE
+  baseType: SERVICE
+  nodeType: SERVER
+  priority: P5
+  hardwareState: 'ON'
+  ipAddress: 192.168.1.12
+  softwareState: GOOD
+  fileSystemState: GOOD
+  services:
+  - name: TCP
+    port: '80'
+    state: GOOD
+  - name: UDP
+    port: '53'
+    state: GOOD
+- itemType: NODE
+  id: '6'
+  name: SWITCH_2
+  baseType: ACTIVE
+  nodeType: SWITCH
+  priority: P2
+  hardwareState: 'ON'
+  ipAddress: 192.168.2.1
+  softwareState: GOOD
+  fileSystemState: GOOD
+- itemType: NODE
+  id: '7'
+  name: WEB_SERVER
+  baseType: SERVICE
+  nodeType: SERVER
+  priority: P5
+  hardwareState: 'ON'
+  ipAddress: 192.168.2.10
+  softwareState: GOOD
+  fileSystemState: GOOD
+  services:
+  - name: TCP
+    port: '80'
+    state: GOOD
+  - name: TCP_SQL
+    port: '1433'
+    state: GOOD
+- itemType: NODE
+  id: '8'
+  name: DATABASE_SERVER
+  baseType: SERVICE
+  nodeType: SERVER
+  priority: P5
+  hardwareState: 'ON'
+  ipAddress: 192.168.2.14
+  softwareState: GOOD
+  fileSystemState: GOOD
+  services:
+  - name: TCP
+    port: '80'
+    state: GOOD
+  - name: TCP_SQL
+    port: '1433'
+    state: GOOD
+  - name: UDP
+    port: '53'
+    state: GOOD
+- itemType: NODE
+  id: '9'
+  name: BACKUP_SERVER
+  baseType: SERVICE
+  nodeType: SERVER
+  priority: P5
+  hardwareState: 'ON'
+  ipAddress: 192.168.2.16
+  softwareState: GOOD
+  fileSystemState: GOOD
+  services:
+  - name: TCP
+    port: '80'
+    state: GOOD
+- itemType: LINK
+  id: '10'
+  name: LINK_1
+  bandwidth: 1000000000
+  source: '1'
+  destination: '3'
+- itemType: LINK
+  id: '11'
+  name: LINK_2
+  bandwidth: 1000000000
+  source: '2'
+  destination: '3'
+- itemType: LINK
+  id: '12'
+  name: LINK_3
+  bandwidth: 1000000000
+  source: '3'
+  destination: '4'
+- itemType: LINK
+  id: '13'
+  name: LINK_4
+  bandwidth: 1000000000
+  source: '3'
+  destination: '5'
+- itemType: LINK
+  id: '14'
+  name: LINK_5
+  bandwidth: 1000000000
+  source: '4'
+  destination: '6'
+- itemType: LINK
+  id: '15'
+  name: LINK_6
+  bandwidth: 1000000000
+  source: '5'
+  destination: '6'
+- itemType: LINK
+  id: '16'
+  name: LINK_7
+  bandwidth: 1000000000
+  source: '6'
+  destination: '7'
+- itemType: LINK
+  id: '17'
+  name: LINK_8
+  bandwidth: 1000000000
+  source: '6'
+  destination: '8'
+- itemType: LINK
+  id: '18'
+  name: LINK_9
+  bandwidth: 1000000000
+  source: '6'
+  destination: '9'
+- itemType: GREEN_IER
+  id: '19'
+  startStep: 1
+  endStep: 256
+  load: 10000
+  protocol: TCP
+  port: '80'
+  source: '1'
+  destination: '7'
+  missionCriticality: 5
+- itemType: GREEN_IER
+  id: '20'
+  startStep: 1
+  endStep: 256
+  load: 10000
+  protocol: TCP
+  port: '80'
+  source: '7'
+  destination: '1'
+  missionCriticality: 5
+- itemType: GREEN_IER
+  id: '21'
+  startStep: 1
+  endStep: 256
+  load: 10000
+  protocol: TCP
+  port: '80'
+  source: '2'
+  destination: '7'
+  missionCriticality: 5
+- itemType: GREEN_IER
+  id: '22'
+  startStep: 1
+  endStep: 256
+  load: 10000
+  protocol: TCP
+  port: '80'
+  source: '7'
+  destination: '2'
+  missionCriticality: 5
+- itemType: GREEN_IER
+  id: '23'
+  startStep: 1
+  endStep: 256
+  load: 5000
+  protocol: TCP_SQL
+  port: '1433'
+  source: '7'
+  destination: '8'
+  missionCriticality: 5
+- itemType: GREEN_IER
+  id: '24'
+  startStep: 1
+  endStep: 256
+  load: 100000
+  protocol: TCP_SQL
+  port: '1433'
+  source: '8'
+  destination: '7'
+  missionCriticality: 5
+- itemType: GREEN_IER
+  id: '25'
+  startStep: 1
+  endStep: 256
+  load: 50000
+  protocol: TCP
+  port: '80'
+  source: '1'
+  destination: '9'
+  missionCriticality: 2
+- itemType: GREEN_IER
+  id: '26'
+  startStep: 1
+  endStep: 256
+  load: 50000
+  protocol: TCP
+  port: '80'
+  source: '2'
+  destination: '9'
+  missionCriticality: 2
+- itemType: GREEN_IER
+  id: '27'
+  startStep: 1
+  endStep: 256
+  load: 5000
+  protocol: TCP
+  port: '80'
+  source: '5'
+  destination: '7'
+  missionCriticality: 1
+- itemType: GREEN_IER
+  id: '28'
+  startStep: 1
+  endStep: 256
+  load: 5000
+  protocol: TCP
+  port: '80'
+  source: '7'
+  destination: '5'
+  missionCriticality: 1
+- itemType: GREEN_IER
+  id: '29'
+  startStep: 1
+  endStep: 256
+  load: 5000
+  protocol: TCP
+  port: '80'
+  source: '5'
+  destination: '8'
+  missionCriticality: 1
+- itemType: GREEN_IER
+  id: '30'
+  startStep: 1
+  endStep: 256
+  load: 5000
+  protocol: TCP
+  port: '80'
+  source: '8'
+  destination: '5'
+  missionCriticality: 1
+- itemType: GREEN_IER
+  id: '31'
+  startStep: 1
+  endStep: 256
+  load: 5000
+  protocol: TCP
+  port: '80'
+  source: '5'
+  destination: '9'
+  missionCriticality: 1
+- itemType: GREEN_IER
+  id: '32'
+  startStep: 1
+  endStep: 256
+  load: 5000
+  protocol: TCP
+  port: '80'
+  source: '9'
+  destination: '5'
+  missionCriticality: 1
+- itemType: ACL_RULE
+  id: '33'
+  permission: ALLOW
+  source: 192.168.10.11
+  destination: 192.168.2.10
+  protocol: ANY
+  port: ANY
+- itemType: ACL_RULE
+  id: '34'
+  permission: ALLOW
+  source: 192.168.10.11
+  destination: 192.168.2.14
+  protocol: ANY
+  port: ANY
+- itemType: ACL_RULE
+  id: '35'
+  permission: ALLOW
+  source: 192.168.10.12
+  destination: 192.168.2.14
+  protocol: ANY
+  port: ANY
+- itemType: ACL_RULE
+  id: '36'
+  permission: ALLOW
+  source: 192.168.10.12
+  destination: 192.168.2.10
+  protocol: ANY
+  port: ANY
+- itemType: ACL_RULE
+  id: '37'
+  permission: ALLOW
+  source: 192.168.2.10
+  destination: 192.168.10.11
+  protocol: ANY
+  port: ANY
+- itemType: ACL_RULE
+  id: '38'
+  permission: ALLOW
+  source: 192.168.2.10
+  destination: 192.168.10.12
+  protocol: ANY
+  port: ANY
+- itemType: ACL_RULE
+  id: '39'
+  permission: ALLOW
+  source: 192.168.2.10
+  destination: 192.168.2.14
+  protocol: ANY
+  port: ANY
+- itemType: ACL_RULE
+  id: '40'
+  permission: ALLOW
+  source: 192.168.2.14
+  destination: 192.168.2.10
+  protocol: ANY
+  port: ANY
+- itemType: ACL_RULE
+  id: '41'
+  permission: ALLOW
+  source: 192.168.10.11
+  destination: 192.168.2.16
+  protocol: ANY
+  port: ANY
+- itemType: ACL_RULE
+  id: '42'
+  permission: ALLOW
+  source: 192.168.10.12
+  destination: 192.168.2.16
+  protocol: ANY
+  port: ANY
+- itemType: ACL_RULE
+  id: '43'
+  permission: ALLOW
+  source: 192.168.1.12
+  destination: 192.168.2.10
+  protocol: ANY
+  port: ANY
+- itemType: ACL_RULE
+  id: '44'
+  permission: ALLOW
+  source: 192.168.1.12
+  destination: 192.168.2.14
+  protocol: ANY
+  port: ANY
+- itemType: ACL_RULE
+  id: '45'
+  permission: ALLOW
+  source: 192.168.1.12
+  destination: 192.168.2.16
+  protocol: ANY
+  port: ANY
+- itemType: ACL_RULE
+  id: '46'
+  permission: ALLOW
+  source: 192.168.2.10
+  destination: 192.168.1.12
+  protocol: ANY
+  port: ANY
+- itemType: ACL_RULE
+  id: '47'
+  permission: ALLOW
+  source: 192.168.2.14
+  destination: 192.168.1.12
+  protocol: ANY
+  port: ANY
+- itemType: ACL_RULE
+  id: '48'
+  permission: ALLOW
+  source: 192.168.2.16
+  destination: 192.168.1.12
+  protocol: ANY
+  port: ANY
+- itemType: ACL_RULE
+  id: '49'
+  permission: DENY
+  source: ANY
+  destination: ANY
+  protocol: ANY
+  port: ANY
+- itemType: RED_POL
+  id: '50'
+  startStep: 50
+  endStep: 50
+  targetNodeId: '1'
+  initiator: DIRECT
+  type: SERVICE
+  protocol: UDP
+  state: COMPROMISED
+  sourceNodeId: NA
+  sourceNodeService: NA
+  sourceNodeServiceState: NA
+- itemType: RED_IER
+  id: '51'
+  startStep: 75
+  endStep: 105
+  load: 10000
+  protocol: UDP
+  port: '53'
+  source: '1'
+  destination: '8'
+  missionCriticality: 0
+- itemType: RED_POL
+  id: '52'
+  startStep: 100
+  endStep: 100
+  targetNodeId: '8'
+  initiator: IER
+  type: SERVICE
+  protocol: UDP
+  state: COMPROMISED
+  sourceNodeId: NA
+  sourceNodeService: NA
+  sourceNodeServiceState: NA
+- itemType: RED_POL
+  id: '53'
+  startStep: 105
+  endStep: 105
+  targetNodeId: '8'
+  initiator: SERVICE
+  type: FILE
+  protocol: NA
+  state: CORRUPT
+  sourceNodeId: '8'
+  sourceNodeService: UDP
+  sourceNodeServiceState: COMPROMISED
+- itemType: RED_POL
+  id: '54'
+  startStep: 105
+  endStep: 105
+  targetNodeId: '8'
+  initiator: SERVICE
+  type: SERVICE
+  protocol: TCP_SQL
+  state: COMPROMISED
+  sourceNodeId: '8'
+  sourceNodeService: UDP
+  sourceNodeServiceState: COMPROMISED
+- itemType: RED_POL
+  id: '55'
+  startStep: 125
+  endStep: 125
+  targetNodeId: '7'
+  initiator: SERVICE
+  type: SERVICE
+  protocol: TCP
+  state: OVERWHELMED
+  sourceNodeId: '8'
+  sourceNodeService: TCP_SQL
+  sourceNodeServiceState: COMPROMISED

tests/config/legacy_conversion/new_training_config.yaml

@@ -21,12 +21,20 @@ agent_identifier: PPO
 # "ACL"
 # "ANY" node and acl actions
 action_type: ANY
+
 # Number of episodes for training to run per session
 num_train_episodes: 10
 
 # Number of time_steps for training per episode
 num_train_steps: 256
 
+# Number of episodes for evaluation to run per session
+num_eval_episodes: 1
+
+# Number of time_steps for evaluation per episode
+num_eval_steps: 256
+
+
 # Time delay between steps (for generic agents)
 time_delay: 10
 # Type of session to be run (TRAINING or EVALUATION)

tests/test_full_legacy_config_session.py

@@ -0,0 +1,29 @@
+# © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+import pytest
+
+from primaite.main import run
+from tests import TEST_CONFIG_ROOT
+
+
+@pytest.mark.parametrize(
+    "legacy_file",
+    [
+        ("legacy_config_1_DDOS_BASIC.yaml"),
+        ("legacy_config_2_DDOS_BASIC.yaml"),
+        ("legacy_config_3_DOS_VERY_BASIC.yaml"),
+        ("legacy_config_5_DATA_MANIPULATION.yaml"),
+    ],
+)
+def test_legacy_training_config_run_session(legacy_file):
+    """Tests using legacy training and lay down config files in PrimAITE session end-to-end."""
+    legacy_training_config_path = TEST_CONFIG_ROOT / "legacy_conversion" / "legacy_training_config.yaml"
+    legacy_lay_down_config_path = TEST_CONFIG_ROOT / "legacy_conversion" / legacy_file
+
+    # Run a PrimAITE session using legacy training and lay down config file paths
+    run(
+        legacy_training_config_path,
+        legacy_lay_down_config_path,
+        legacy_training_config=True,
+        legacy_lay_down_config=True,
+    )

tests/test_lay_down_config.py

@@ -0,0 +1,44 @@
+# © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+import pytest
+import yaml
+
+from primaite.config.lay_down_config import (
+    convert_legacy_lay_down_config,
+    data_manipulation_config_path,
+    ddos_basic_one_config_path,
+    ddos_basic_two_config_path,
+    dos_very_basic_config_path,
+)
+from tests import TEST_CONFIG_ROOT
+
+
+@pytest.mark.parametrize(
+    "legacy_file, new_path",
+    [
+        ("legacy_config_1_DDOS_BASIC.yaml", ddos_basic_one_config_path()),
+        ("legacy_config_2_DDOS_BASIC.yaml", ddos_basic_two_config_path()),
+        ("legacy_config_3_DOS_VERY_BASIC.yaml", dos_very_basic_config_path()),
+        ("legacy_config_5_DATA_MANIPULATION.yaml", data_manipulation_config_path()),
+    ],
+)
+def test_legacy_lay_down_config_load(legacy_file, new_path):
+    """Tests converting legacy lay down files into the new format."""
+    with open(TEST_CONFIG_ROOT / "legacy_conversion" / legacy_file, "r") as file:
+        legacy_lay_down_config = yaml.safe_load(file)
+
+    with open(new_path, "r") as file:
+        new_lay_down_config = yaml.safe_load(file)
+
+    converted_lay_down_config = convert_legacy_lay_down_config(legacy_lay_down_config)
+
+    assert len(converted_lay_down_config) == len(new_lay_down_config)
+
+    for i, new_item in enumerate(new_lay_down_config):
+        converted_item = converted_lay_down_config[i]
+
+        for key, val in new_item.items():
+            if key == "position":
+                continue
+            assert key in converted_item
+
+            assert val == converted_item[key]