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

merged 3.0.0 into main for git history alignment

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

.azure/.pypirc

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

.azure/artifact-release-pipeline.yaml

@@ -15,16 +15,17 @@ steps:
   displayName: 'Use Python $(python.version)'
 
 - script: |
-    python -m pip install --upgrade pip
-    pip install build
-    pip install wheel
+    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 setup.py sdist bdist_wheel
+    python -m build
   displayName: 'Build PrimAITE sdist and wheel'
 
 - task: TwineAuthenticate@1
@@ -33,5 +34,5 @@ steps:
     artifactFeed: PrimAITE/PrimAITE
 
 - script: |
-    python -m twine upload --verbose -r PrimAITE --config-file  $(PYPIRC_PATH) dist/*
+    python -m twine upload --verbose -r PrimAITE --config-file  $(PYPIRC_PATH) dist/*.whl
   displayName: 'Artifact Upload'

.azure/azure-benchmark-pipeline.yaml

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

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

@@ -0,0 +1,53 @@
+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,rl]
+    displayName: 'Install PrimAITE for docs autosummary'
+
+  - script: |
+      apt-get install pandoc
+    displayName: 'Install Pandoc'
+
+  - 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

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

.azuredevops/pull_request_template.md

@@ -0,0 +1,16 @@
+## 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
+- [ ] PR is linked to a **work item**
+- [ ] **acceptance criteria** of linked ticket are met
+- [ ] performed **self-review** of the code
+- [ ] written **tests** for any new functionality added with this PR
+- [ ] updated the **documentation** if this PR changes or adds functionality
+- [ ] written/updated **design docs** if this PR implements new functionality
+- [ ] updated the **change log**
+- [ ] ran **pre-commit** checks for code style
+- [ ] attended to any **TO-DOs** left in the code

.flake8

@@ -0,0 +1,20 @@
+[flake8]
+max-line-length=120
+extend-ignore =
+    D105
+    D107
+    D100
+    D104
+    E203
+    E712
+    D401
+    F811
+    ANN002
+    ANN003
+    ANN101
+    ANN102
+exclude =
+    docs/source/*
+    tests/*
+suppress-none-returning=True
+suppress-dummy-args=True

.github/ISSUE_TEMPLATE/bug_report.md

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

.github/ISSUE_TEMPLATE/feature_request.md

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

.github/workflows/build-sphinx.yml

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

.github/workflows/python-package.yml

@@ -0,0 +1,66 @@
+name: Python package
+
+on:
+  push:
+    branches:
+      - main
+      - dev
+      - dev-gui
+      - 'release/**'
+  pull_request:
+    branches:
+      - main
+      - dev
+      - dev-gui
+      - 'release/**'
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10"]
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install python dev
+        run: |
+          sudo apt update
+          sudo add-apt-repository ppa:deadsnakes/ppa -y
+          sudo apt install python${{ matrix.python-version}}-dev -y
+
+      - name: Install Build Dependencies
+        run: |
+          python -m pip install --upgrade pip==23.0.1
+          pip install wheel==0.38.4 --upgrade
+          pip install setuptools==66 --upgrade
+          pip install build
+
+      - name: Build PrimAITE
+        run: |
+          python -m build
+
+      - name: Install PrimAITE
+        run: |
+          PRIMAITE_WHEEL=$(ls ./dist/primaite*.whl)
+          python -m pip install $PRIMAITE_WHEEL[dev,rl]
+
+      - name: Perform PrimAITE Setup
+        run: |
+          primaite setup
+
+      - name: Lint with flake8
+        run: |
+          # stop the build if there are Python syntax errors or undefined names
+          flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+          # exit-zero treats all errors as warnings.
+          flake8 . --count --exit-zero --max-complexity=10 --max-line-length=120 --statistics
+
+      - name: Run tests
+        run: |
+          pytest tests/

.gitignore

@@ -1,8 +1,3 @@
-# PrimAITE Package
-PRIMAITE/outputs
-PRIMAITE/outputs/*
-TestResults
-
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
@@ -42,6 +37,7 @@ pip-log.txt
 pip-delete-this-directory.txt
 
 # Unit test / coverage reports
+junit/
 htmlcov/
 .tox/
 .nox/
@@ -55,6 +51,9 @@ coverage.xml
 .hypothesis/
 .pytest_cache/
 cover/
+tests/assets/**/*.png
+tests/assets/**/tensorboard_logs/
+tests/assets/**/checkpoints/
 
 # Translations
 *.mo
@@ -75,6 +74,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/source/_autosummary
 
 # PyBuilder
 .pybuilder/
@@ -82,6 +82,10 @@ target/
 
 # Jupyter Notebook
 .ipynb_checkpoints
+PPO_UC2/
+# ignore everything but the executed notebooks rst in the docs/source/notebooks directory
+!docs/source/notebooks/executed_notebooks.rst
+docs/source/notebooks/**/*
 
 # IPython
 profile_default/
@@ -141,3 +145,26 @@ dmypy.json
 
 # Cython debug symbols
 cython_debug/
+
+# IDE
+.idea/
+docs/source/primaite-dependencies.rst
+.vscode/
+
+# outputs
+src/primaite/outputs/
+simulation_output/
+sessions/
+PrimAITE-PPO-example-agent.zip
+
+# benchmark session outputs
+benchmark/output
+# src/primaite/notebooks/scratch.ipynb
+src/primaite/notebooks/scratch.py
+sandbox.py
+sandbox/
+sandbox.ipynb
+
+# benchmarking
+**/benchmark/sessions/
+**/benchmark/output/

.pre-commit-config.yaml

@@ -0,0 +1,35 @@
+repos:
+  - repo: http://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
+    hooks:
+      - id: check-yaml
+        exclude: scenario_with_placeholders/
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-added-large-files
+        args: ['--maxkb=5000']
+      - id: mixed-line-ending
+      - id: requirements-txt-fixer
+  - repo: http://github.com/psf/black
+    rev: 23.1.0
+    hooks:
+      - id: black
+        args: [ "--line-length=120" ]
+        additional_dependencies:
+          - jupyter
+  - repo: http://github.com/pycqa/isort
+    rev: 5.12.0
+    hooks:
+      - id: isort
+        args: [ "--profile", "black" ]
+  - repo: http://github.com/PyCQA/flake8
+    rev: 6.0.0
+    hooks:
+      - id: flake8
+        additional_dependencies:
+          - flake8-docstrings
+          - flake8-annotations
+  - repo: https://github.com/kynan/nbstripout
+    rev: 0.7.1
+    hooks:
+      - id: nbstripout

CHANGELOG.md

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

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

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 - 2025 Defence Science and Technology Laboratory UK (https://dstl.gov.uk)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

MANIFEST.in

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

PRIMAITE/Main.py

@@ -1,312 +0,0 @@
-# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.
-"""
-PRIMAITE - main (harness) module
-
-Coding Standards: PEP 8
-"""
-
-from sys import exc_info
-import time
-import yaml
-import os.path
-import logging
-from datetime import datetime
-
-from environment.primaite import PRIMAITE
-from transactions.transactions_to_file import write_transaction_to_file
-from common.config_values_main import config_values_main
-
-from stable_baselines3 import PPO
-from stable_baselines3.ppo import MlpPolicy as PPOMlp
-from stable_baselines3 import A2C
-from stable_baselines3.common.env_checker import check_env
-from stable_baselines3.common.evaluation import evaluate_policy
-
-################################# FUNCTIONS ######################################
-
-def run_generic():
-    """
-    Run against a generic agent
-    """
-
-    for episode in range(0, config_values.num_episodes):
-        for step in range(0, config_values.num_steps):
-
-            # Send the observation space to the agent to get an action
-            # TEMP - random action for now
-            # action = env.blue_agent_action(obs)
-            action = env.action_space.sample()
-
-            # Run the simulation step on the live environment
-            obs, reward, done, info = env.step(action)
-
-            # Break if done is True
-            if done:
-                break
-
-            # Introduce a delay between steps
-            time.sleep(config_values.time_delay / 1000)
-
-        # Reset the environment at the end of the episode
-        env.reset()
-
-    env.close()
-
-
-def run_stable_baselines3_ppo():
-    """
-    Run against a stable_baselines3 PPO agent
-    """ 
-
-    if config_values.load_agent == True:
-        try:
-            agent = PPO.load(config_values.agent_load_file, env, verbose=0, n_steps=config_values.num_steps)
-        except:
-            print("ERROR: Could not load agent at location: " + config_values.agent_load_file)
-            logging.error("Could not load agent")
-            logging.error("Exception occured", exc_info=True)
-    else:
-        agent = PPO(PPOMlp, env, verbose=0, n_steps=config_values.num_steps)
-
-    if config_values.session_type == "TRAINING":
-        # We're in a training session
-        print("Starting training session...")
-        logging.info("Starting training session...")
-        for episode in range(0, config_values.num_episodes):
-            agent.learn(total_timesteps=1)     
-        save_agent(agent)
-    else:
-        # Default to being in an evaluation session
-        print("Starting evaluation session...")
-        logging.info("Starting evaluation session...")
-        evaluate_policy(agent, env, n_eval_episodes=config_values.num_episodes)
-
-    env.close()
-
-def run_stable_baselines3_a2c():
-    """
-    Run against a stable_baselines3 A2C agent
-    """
-
-    if config_values.load_agent == True:
-        try:
-            agent = A2C.load(config_values.agent_load_file, env, verbose=0, n_steps=config_values.num_steps)
-        except:
-            print("ERROR: Could not load agent at location: " + config_values.agent_load_file)
-            logging.error("Could not load agent")
-            logging.error("Exception occured", exc_info=True)
-    else:
-        agent = A2C("MlpPolicy", env, verbose=0, n_steps=config_values.num_steps)
-
-    if config_values.session_type == "TRAINING":
-        # We're in a training session
-        print("Starting training session...")
-        logging.info("Starting training session...")
-        for episode in range(0, config_values.num_episodes):
-            agent.learn(total_timesteps=1)     
-        save_agent(agent)
-    else:
-        # Default to being in an evaluation session
-        print("Starting evaluation session...")
-        logging.info("Starting evaluation session...")
-        evaluate_policy(agent, env, n_eval_episodes=config_values.num_episodes)   
-
-    env.close()
-
-def save_agent(_agent):
-    """
-    Persist an agent (only works for stable baselines3 agents at present)
-    """
-
-    now = datetime.now() # current date and time
-    time = now.strftime("%Y%m%d_%H%M%S")
-
-    try:
-        path = 'outputs/agents/'
-        is_dir = os.path.isdir(path)
-        if not is_dir:
-            os.makedirs(path)
-        filename = "outputs/agents/agent_saved_" + time
-        _agent.save(filename)
-        logging.info("Trained agent saved as " + filename)
-    except Exception as e:
-        logging.error("Could not save agent")
-        logging.error("Exception occured", exc_info=True)
-
-def configure_logging():
-    """
-    Configures logging
-    """
-
-    try:
-        now = datetime.now() # current date and time
-        time = now.strftime("%Y%m%d_%H%M%S")
-        filename = "logs/app_" + time + ".log"
-        path = 'logs/'
-        is_dir = os.path.isdir(path)
-        if not is_dir:
-            os.makedirs(path)
-        logging.basicConfig(filename=filename, filemode='w', format='%(asctime)s - %(levelname)s - %(message)s', datefmt='%d-%b-%y %H:%M:%S', level=logging.INFO)
-    except:
-        print("ERROR: Could not start logging")
-
-def load_config_values():
-    """
-    Loads the config values from the main config file into a config object
-    """
-
-    try:
-        # Generic
-        config_values.agent_identifier = config_data['agentIdentifier']           
-        config_values.num_episodes = int(config_data['numEpisodes'])                                
-        config_values.time_delay = int(config_data['timeDelay'])                  
-        config_values.config_filename_use_case = config_data['configFilename']   
-        config_values.session_type = config_data['sessionType']
-        config_values.load_agent = bool(config_data['loadAgent'])
-        config_values.agent_load_file = config_data['agentLoadFile']
-        # Environment
-        config_values.observation_space_high_value = int(config_data['observationSpaceHighValue'])
-        # Reward values
-        # Generic
-        config_values.all_ok = int(config_data['allOk']) 
-        # Node Operating State
-        config_values.off_should_be_on = int(config_data['offShouldBeOn'])
-        config_values.off_should_be_resetting = int(config_data['offShouldBeResetting'])
-        config_values.on_should_be_off = int(config_data['onShouldBeOff'])
-        config_values.on_should_be_resetting = int(config_data['onShouldBeResetting'])
-        config_values.resetting_should_be_on = int(config_data['resettingShouldBeOn'])
-        config_values.resetting_should_be_off = int(config_data['resettingShouldBeOff']) 
-        config_values.resetting = int(config_data['resetting'])
-        # Node O/S or Service State
-        config_values.good_should_be_patching = int(config_data['goodShouldBePatching'])
-        config_values.good_should_be_compromised = int(config_data['goodShouldBeCompromised'])
-        config_values.good_should_be_overwhelmed = int(config_data['goodShouldBeOverwhelmed'])
-        config_values.patching_should_be_good = int(config_data['patchingShouldBeGood'])
-        config_values.patching_should_be_compromised = int(config_data['patchingShouldBeCompromised'])
-        config_values.patching_should_be_overwhelmed = int(config_data['patchingShouldBeOverwhelmed'])
-        config_values.patching = int(config_data['patching'])
-        config_values.compromised_should_be_good = int(config_data['compromisedShouldBeGood'])
-        config_values.compromised_should_be_patching = int(config_data['compromisedShouldBePatching'])
-        config_values.compromised_should_be_overwhelmed = int(config_data['compromisedShouldBeOverwhelmed'])
-        config_values.compromised = int(config_data['compromised'])     
-        config_values.overwhelmed_should_be_good = int(config_data['overwhelmedShouldBeGood'])
-        config_values.overwhelmed_should_be_patching = int(config_data['overwhelmedShouldBePatching'])
-        config_values.overwhelmed_should_be_compromised = int(config_data['overwhelmedShouldBeCompromised'])
-        config_values.overwhelmed = int(config_data['overwhelmed'])
-        # Node File System State
-        config_values.good_should_be_repairing = int(config_data['goodShouldBeRepairing'])
-        config_values.good_should_be_restoring = int(config_data['goodShouldBeRestoring'])
-        config_values.good_should_be_corrupt = int(config_data['goodShouldBeCorrupt'])
-        config_values.good_should_be_destroyed = int(config_data['goodShouldBeDestroyed'])
-        config_values.repairing_should_be_good = int(config_data['repairingShouldBeGood'])
-        config_values.repairing_should_be_restoring = int(config_data['repairingShouldBeRestoring'])
-        config_values.repairing_should_be_corrupt = int(config_data['repairingShouldBeCorrupt'])
-        config_values.repairing_should_be_destroyed = int(config_data['repairingShouldBeDestroyed'])   
-        config_values.repairing = int(config_data['repairing'])
-        config_values.restoring_should_be_good = int(config_data['restoringShouldBeGood'])
-        config_values.restoring_should_be_repairing = int(config_data['restoringShouldBeRepairing'])
-        config_values.restoring_should_be_corrupt = int(config_data['restoringShouldBeCorrupt'])     
-        config_values.restoring_should_be_destroyed = int(config_data['restoringShouldBeDestroyed'])
-        config_values.restoring = int(config_data['restoring'])
-        config_values.corrupt_should_be_good = int(config_data['corruptShouldBeGood'])
-        config_values.corrupt_should_be_repairing = int(config_data['corruptShouldBeRepairing'])
-        config_values.corrupt_should_be_restoring = int(config_data['corruptShouldBeRestoring'])
-        config_values.corrupt_should_be_destroyed = int(config_data['corruptShouldBeDestroyed'])
-        config_values.corrupt = int(config_data['corrupt'])
-        config_values.destroyed_should_be_good = int(config_data['destroyedShouldBeGood'])
-        config_values.destroyed_should_be_repairing = int(config_data['destroyedShouldBeRepairing'])
-        config_values.destroyed_should_be_restoring = int(config_data['destroyedShouldBeRestoring'])
-        config_values.destroyed_should_be_corrupt = int(config_data['destroyedShouldBeCorrupt'])
-        config_values.destroyed = int(config_data['destroyed'])
-        config_values.scanning = int(config_data['scanning'])
-        # IER status
-        config_values.red_ier_running = int(config_data['redIerRunning'])
-        config_values.green_ier_blocked = int(config_data['greenIerBlocked'])
-        # Patching / Reset durations
-        config_values.os_patching_duration = int(config_data['osPatchingDuration'])                         
-        config_values.node_reset_duration = int(config_data['nodeResetDuration'])                           
-        config_values.service_patching_duration = int(config_data['servicePatchingDuration']) 
-        config_values.file_system_repairing_limit = int(config_data['fileSystemRepairingLimit']) 
-        config_values.file_system_restoring_limit = int(config_data['fileSystemRestoringLimit']) 
-        config_values.file_system_scanning_limit = int(config_data['fileSystemScanningLimit']) 
-        
-        logging.info("Training agent: " + config_values.agent_identifier)
-        logging.info("Training environment config: " + config_values.config_filename_use_case)
-        logging.info("Training cycle has " + str(config_values.num_episodes) + " episodes")
-
-    except Exception as e:
-        logging.error("Could not save load config data")
-        logging.error("Exception occured", exc_info=True)
-
-
-################################# MAIN PROCESS ############################################
-
-# Starting point
-
-# Welcome message
-print("Welcome to the Primary-level AI Training Environment (PrimAITE)")
-
-# Configure logging
-configure_logging()
-
-# Open the main config file
-try:
-    config_file_main = open("config/config_main.yaml", "r")
-    config_data = yaml.safe_load(config_file_main)
-    # Create a config class
-    config_values = config_values_main()
-    # Load in config data
-    load_config_values()
-except Exception as e:
-    logging.error("Could not load main config")
-    logging.error("Exception occured", exc_info=True)
-
-# Create a list of transactions
-# A transaction is an object holding the: 
-# - episode # 
-# - step # 
-# - initial observation space
-# - action
-# - reward
-# - new observation space  
-transaction_list = []
-
-# Create the PRIMAITE environment
-try:
-    env = PRIMAITE(config_values, transaction_list)
-    logging.info("PrimAITE environment created")
-except Exception as e:
-    logging.error("Could not create PrimAITE environment")
-    logging.error("Exception occured", exc_info=True)
-
-# Get the number of steps (which is stored in the child config file)
-config_values.num_steps = env.episode_steps
-
-# Run environment against an agent
-if config_values.agent_identifier == "GENERIC":
-    run_generic()
-elif config_values.agent_identifier == "STABLE_BASELINES3_PPO":
-    run_stable_baselines3_ppo()
-elif config_values.agent_identifier == "STABLE_BASELINES3_A2C":
-    run_stable_baselines3_a2c()
-
-print("Session finished")
-logging.info("Session finished")
-
-print("Saving transaction logs...")
-logging.info("Saving transaction logs...")
-
-write_transaction_to_file(transaction_list)
-
-config_file_main.close
-
-print("Finished")
-logging.info("Finished")
-
-
-
-
-
-
-
-

PRIMAITE/acl/__init__.py

@@ -1 +0,0 @@
-# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.

PRIMAITE/acl/access_control_list.py

@@ -1,134 +0,0 @@
-# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.
-"""
-A class that implements the access control list implementation for the network
-"""
-
-from acl.acl_rule import ACLRule
-
-class AccessControlList():
-    """
-    Access Control List class
-    """
-
-    def __init__(self):
-        """
-        Init
-        """
-
-        self.acl = {}       # A dictionary of ACL Rules
-    
-    def check_address_match(self, _rule, _source_ip_address, _dest_ip_address):
-        """
-        Checks for IP address matches
-
-        Args:
-            _rule: The rule being checked
-            _source_ip_address: the source IP address to compare
-            _dest_ip_address: the destination IP address to compare
-
-        Returns:
-             True if match; False otherwise.
-        """
-
-        if ((_rule.get_source_ip() == _source_ip_address and _rule.get_dest_ip() == _dest_ip_address) or
-            (_rule.get_source_ip() == "ANY" and _rule.get_dest_ip() == _dest_ip_address) or
-            (_rule.get_source_ip() == _source_ip_address and _rule.get_dest_ip() == "ANY") or
-            (_rule.get_source_ip() == "ANY" and _rule.get_dest_ip() == "ANY")):
-            return True
-        else:
-            return False
-
-    def is_blocked(self, _source_ip_address, _dest_ip_address, _protocol, _port):
-        """
-        Checks for rules that block a protocol / port
-
-        Args:
-            _source_ip_address: the source IP address to check
-            _dest_ip_address: the destination IP address to check
-            _protocol: the protocol to check
-            _port: the port to check
-
-        Returns:
-             Indicates block if all conditions are satisfied.
-        """
-        
-        for rule_key, rule_value in self.acl.items():
-            if self.check_address_match(rule_value, _source_ip_address, _dest_ip_address):
-                if ((rule_value.get_protocol() == _protocol or rule_value.get_protocol() == "ANY") and
-                    (str(rule_value.get_port()) == str(_port) or rule_value.get_port() == "ANY")):
-                    # There's a matching rule. Get the permission
-                    if rule_value.get_permission() == "DENY":
-                        return True
-                    elif rule_value.get_permission() == "ALLOW":
-                        return False
-
-        # If there has been no rule to allow the IER through, it will return a blocked signal by default
-        return True
-
-    def add_rule(self, _permission, _source_ip, _dest_ip, _protocol, _port):
-        """
-        Adds a new rule
-
-        Args:
-            _permission: the permission value (e.g. "ALLOW" or "DENY")
-            _source_ip: the source IP address
-            _dest_ip: the destination IP address
-            _protocol: the protocol
-            _port: the port
-        """
-
-        new_rule = ACLRule(_permission, _source_ip, _dest_ip, _protocol, str(_port))
-        hash_value = hash(new_rule)
-        self.acl[hash_value] = new_rule
-
-    def remove_rule(self, _permission, _source_ip, _dest_ip, _protocol, _port):
-        """
-        Removes a rule
-
-        Args:
-            _permission: the permission value (e.g. "ALLOW" or "DENY")
-            _source_ip: the source IP address
-            _dest_ip: the destination IP address
-            _protocol: the protocol
-            _port: the port
-        """
-
-        rule = ACLRule(_permission, _source_ip, _dest_ip, _protocol, str(_port))
-        hash_value = hash(rule)
-        # There will not always be something 'popable' since the agent will be trying random things
-        try:
-            self.acl.pop(hash_value)
-        except:
-            return
-
-    def remove_all_rules(self):
-        """
-        Removes all rules
-        """
-
-        self.acl.clear()
-
-    def get_dictionary_hash(self, _permission, _source_ip, _dest_ip, _protocol, _port):
-        """
-        Produces a hash value for a rule
-
-        Args:
-            _permission: the permission value (e.g. "ALLOW" or "DENY")
-            _source_ip: the source IP address
-            _dest_ip: the destination IP address
-            _protocol: the protocol
-            _port: the port
-
-        Returns:
-             Hash value based on rule parameters.
-        """
-
-        rule = ACLRule(_permission, _source_ip, _dest_ip, _protocol, str(_port))
-        hash_value = hash(rule)
-        return hash_value
-
-
-
-
-
-

PRIMAITE/acl/acl_rule.py

@@ -1,88 +0,0 @@
-# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.
-"""
-A class that implements an access control list rule
-"""
-
-class ACLRule():
-    """
-    Access Control List Rule class
-    """
-
-    def __init__(self, _permission, _source_ip, _dest_ip, _protocol, _port):
-        """
-        Init
-
-        Args:
-            _permission: The permission (ALLOW or DENY)
-            _source_ip: The source IP address
-            _dest_ip: The destination IP address
-            _protocol: The rule protocol
-            _port: The rule port
-        """
-
-        self.permission = _permission
-        self.source_ip = _source_ip
-        self.dest_ip = _dest_ip
-        self.protocol = _protocol
-        self.port = _port
-
-    def __hash__(self):
-        """
-        Override the hash function
-
-        Returns:
-             Returns hash of core parameters.
-        """
-
-        return hash((self.permission, self.source_ip, self.dest_ip, self.protocol, self.port))
-
-    def get_permission(self):
-        """
-        Gets the permission attribute
-
-        Returns:
-             Returns permission attribute
-        """
-
-        return self.permission
-
-    def get_source_ip(self):
-        """
-        Gets the source IP address attribute
-
-        Returns:
-             Returns source IP address attribute
-        """
-
-        return self.source_ip
-
-    def get_dest_ip(self):
-        """
-        Gets the desintation IP address attribute
-
-        Returns:
-             Returns destination IP address attribute
-        """
-
-        return self.dest_ip
-
-    def get_protocol(self):
-        """
-        Gets the protocol attribute
-
-        Returns:
-             Returns protocol attribute
-        """
-        return self.protocol
-
-    def get_port(self):
-        """
-        Gets the port attribute
-
-        Returns:
-             Returns port attribute
-        """
-
-        return self.port
-        
-

PRIMAITE/common/__init__.py

@@ -1,2 +0,0 @@
-
-# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.

PRIMAITE/common/config_values_main.py

@@ -1,91 +0,0 @@
-# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.
-"""
-The config class
-"""
-
-class config_values_main(object):
-    """
-    Class to hold main config values
-    """
-
-    def __init__(self):
-        """
-        Init
-        """
-
-        # Generic
-        self.agent_identifier = ""                  # the agent in use
-        self.num_episodes = 0                       # number of episodes to train over
-        self.num_steps = 0                          # number of steps in an episode
-        self.time_delay = 0                         # delay between steps (ms) - applies to generic agents only
-        self.config_filename_use_case = ""          # the filename for the Use Case config file
-        self.session_type = ""                      # the session type to run (TRAINING or EVALUATION)
-
-        # Environment
-        self.observation_space_high_value = 0       # The high value for the observation space
-
-        # Reward values
-        # Generic
-        self.all_ok = 0 
-        # Node Operating State
-        self.off_should_be_on = 0
-        self.off_should_be_resetting = 0
-        self.on_should_be_off = 0
-        self.on_should_be_resetting = 0
-        self.resetting_should_be_on = 0
-        self.resetting_should_be_off = 0 
-        self.resetting = 0
-        # Node O/S or Service State
-        self.good_should_be_patching = 0
-        self.good_should_be_compromised = 0
-        self.good_should_be_overwhelmed = 0
-        self.patching_should_be_good = 0
-        self.patching_should_be_compromised = 0
-        self.patching_should_be_overwhelmed = 0
-        self.patching = 0
-        self.compromised_should_be_good = 0
-        self.compromised_should_be_patching = 0
-        self.compromised_should_be_overwhelmed = 0
-        self.compromised = 0     
-        self.overwhelmed_should_be_good = 0
-        self.overwhelmed_should_be_patching = 0
-        self.overwhelmed_should_be_compromised = 0
-        self.overwhelmed = 0
-        # Node File System State
-        self.good_should_be_repairing = 0
-        self.good_should_be_restoring = 0
-        self.good_should_be_corrupt = 0
-        self.good_should_be_destroyed = 0
-        self.repairing_should_be_good = 0
-        self.repairing_should_be_restoring = 0
-        self.repairing_should_be_corrupt = 0
-        self.repairing_should_be_destroyed = 0   # Repairing does not fix destroyed state - you need to restore
-        self.repairing = 0
-        self.restoring_should_be_good = 0
-        self.restoring_should_be_repairing = 0
-        self.restoring_should_be_corrupt = 0     # Not the optimal method (as repair will fix corruption)
-        self.restoring_should_be_destroyed = 0
-        self.restoring = 0
-        self.corrupt_should_be_good = 0
-        self.corrupt_should_be_repairing = 0
-        self.corrupt_should_be_restoring = 0
-        self.corrupt_should_be_destroyed = 0
-        self.corrupt = 0
-        self.destroyed_should_be_good = 0
-        self.destroyed_should_be_repairing = 0
-        self.destroyed_should_be_restoring = 0
-        self.destroyed_should_be_corrupt = 0
-        self.destroyed = 0
-        self.scanning = 0
-        # IER status
-        self.red_ier_running = 0
-        self.green_ier_blocked = 0
-
-        # Patching / Reset
-        self.os_patching_duration = 0                         # The time taken to patch the OS
-        self.node_reset_duration = 0                          # The time taken to reset a node (hardware)
-        self.service_patching_duration = 0                    # The time taken to patch a service   
-        self.file_system_repairing_limit = 0				  # The time take to repair a file
-        self.file_system_restoring_limit = 0				  # The time take to restore a file
-        self.file_system_scanning_limit = 0                   # The time taken to scan the file system
-

PRIMAITE/common/enums.py

@@ -1,104 +0,0 @@
-# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.
-"""
-Enumerations for APE
-"""
-
-from enum import Enum
-
-class TYPE(Enum):
-    """
-    Node type enumeration
-    """
-
-    CCTV = 1
-    SWITCH = 2
-    COMPUTER = 3
-    LINK = 4
-    MONITOR = 5
-    PRINTER = 6
-    LOP = 7
-    RTU = 8
-    ACTUATOR = 9
-    SERVER = 10
-
-class PRIORITY(Enum):
-    """
-    Node priority enumeration
-    """
-
-    P1 = 1
-    P2 = 2
-    P3 = 3
-    P4 = 4
-    P5 = 5
-
-class HARDWARE_STATE(Enum):
-    """
-    Node hardware state enumeration
-    """
-
-    ON = 1
-    OFF = 2
-    RESETTING = 3
-
-class SOFTWARE_STATE(Enum):
-    """
-    O/S or Service state enumeration
-    """
-
-    GOOD = 1
-    PATCHING = 2
-    COMPROMISED = 3
-    OVERWHELMED = 4
-
-class NODE_POL_TYPE(Enum):
-    """
-    Node Pattern of Life type enumeration
-    """
-
-    OPERATING = 1
-    OS = 2
-    SERVICE = 3
-    FILE = 4
-
-class NODE_POL_INITIATOR(Enum):
-    """
-    Node Pattern of Life initiator enumeration
-    """
-
-    DIRECT = 1
-    IER = 2
-    SERVICE = 3
-
-class PROTOCOL(Enum):
-    """
-    Service protocol enumeration
-    """
-
-    LDAP = 0
-    FTP = 1
-    HTTPS = 2
-    SMTP = 3
-    RTP = 4
-    IPP = 5
-    TCP = 6
-    NONE = 7
-
-class ACTION_TYPE(Enum):
-    """
-    Action type enumeration
-    """
-
-    NODE = 0
-    ACL = 1
-
-class FILE_SYSTEM_STATE(Enum):
-    """
-    File System State
-    """
-
-    GOOD = 1
-    CORRUPT = 2
-    DESTROYED = 3
-    REPAIRING = 4
-    RESTORING = 5

PRIMAITE/common/protocol.py

@@ -1,59 +0,0 @@
-# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.
-"""
-The protocol class
-"""
-
-class Protocol(object):
-    """
-    Protocol class
-    """
-
-    def __init__(self, _name):
-        """
-        Init
-
-        Args:
-            _name: The protocol name
-        """
-
-        self.name = _name
-        self.load = 0       # bps
-
-    def get_name(self):
-        """
-        Gets the protocol name
-
-        Returns:
-             The protocol name
-        """
-
-        return self.name
-
-    def get_load(self):
-        """
-        Gets the protocol load
-
-        Returns:
-             The protocol load (bps)
-        """
-
-        return self.load
-
-    def add_load(self, _load):
-        """
-        Adds load to the protocol
-
-        Args:
-            _load: The load to add
-        """
-
-        self.load += _load
-
-    def clear_load(self):
-        """
-        Clears the load on this protocol
-        """
-
-        self.load = 0
-
-

PRIMAITE/common/service.py

@@ -1,100 +0,0 @@
-# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.
-"""
-The Service class
-"""
-
-from common.enums import SOFTWARE_STATE
-
-class Service(object):
-    """
-    Service class
-    """
-
-    def __init__(self, _name, _port, _state):
-        """
-        Init
-
-        Args:
-            _name: The service name
-            _port: The service port
-            _state: The service state
-        """
-
-        self.name = _name
-        self.port = _port
-        self.state = _state
-        self.patching_count = 0
-
-    def set_name(self, _name):
-        """
-        Sets the service name
-
-        Args:
-            _name: The service name
-        """
-
-        self.name = _name
-
-    def get_name(self):
-        """
-        Gets the service name
-
-        Returns:
-             The service name
-        """
-
-        return self.name
-
-    def set_port(self, _port):
-        """
-        Sets the service port
-
-        Args:
-            _port: The service port
-        """
-
-        self.port = _port
-
-    def get_port(self):
-        """
-        Gets the service port
-
-        Returns:
-             The service port
-        """
-
-        return self.port
-
-    def set_state(self, _state):
-        """
-        Sets the service state
-
-        Args:
-            _state: The service state
-        """
-
-        self.state = _state
-
-    def get_state(self):
-        """
-        Gets the service state
-
-        Returns:
-             The service state
-        """
-
-        return self.state
-
-    def reduce_patching_count(self):
-        """
-        Reduces the patching count for the service
-        """
-
-        self.patching_count -= 1
-        if self.patching_count <= 0:
-            self.patching_count = 0
-            self.state = SOFTWARE_STATE.GOOD
-
-
-
-

PRIMAITE/config/config_1_DDOS_BASIC.yaml

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

PRIMAITE/config/config_2_DDOS_BASIC.yaml

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

PRIMAITE/config/config_3_DOS_VERY_BASIC.yaml

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

PRIMAITE/config/config_5_DATA_MANIPULATION.yaml

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

PRIMAITE/config/config_UNIT_TEST.yaml

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

PRIMAITE/config/config_main.yaml

@@ -1,89 +0,0 @@
-# Main Config File
-
-# Generic config values
-# Choose one of these (dependent on Agent being trained)
-# "STABLE_BASELINES3_PPO"
-# "STABLE_BASELINES3_A2C"
-# "GENERIC"
-agentIdentifier: STABLE_BASELINES3_A2C
-# Number of episodes to run per session
-numEpisodes: 10
-# Time delay between steps (for generic agents)
-timeDelay: 10
-# Filename of the scenario / laydown
-configFilename: config_5_DATA_MANIPULATION.yaml
-# Type of session to be run (TRAINING or EVALUATION)
-sessionType: TRAINING
-# Determine whether to load an agent from file
-loadAgent: False
-# File path and file name of agent if you're loading one in
-agentLoadFile: C:\[Path]\[agent_saved_filename.zip]
-
-# Environment config values
-# The high value for the observation space
-observationSpaceHighValue: 1000000000                   
-
-# Reward values
-# Generic
-allOk: 0 
-# Node Operating State
-offShouldBeOn: -10
-offShouldBeResetting: -5
-onShouldBeOff: -2
-onShouldBeResetting: -5
-resettingShouldBeOn: -5
-resettingShouldBeOff: -2 
-resetting: -3
-# Node O/S or Service State
-goodShouldBePatching: 2
-goodShouldBeCompromised: 5
-goodShouldBeOverwhelmed: 5
-patchingShouldBeGood: -5
-patchingShouldBeCompromised: 2
-patchingShouldBeOverwhelmed: 2
-patching: -3
-compromisedShouldBeGood: -20
-compromisedShouldBePatching: -20
-compromisedShouldBeOverwhelmed: -20
-compromised: -20     
-overwhelmedShouldBeGood: -20
-overwhelmedShouldBePatching: -20
-overwhelmedShouldBeCompromised: -20
-overwhelmed: -20
-# Node File System State
-goodShouldBeRepairing: 2
-goodShouldBeRestoring: 2
-goodShouldBeCorrupt: 5
-goodShouldBeDestroyed: 10
-repairingShouldBeGood: -5
-repairingShouldBeRestoring: 2
-repairingShouldBeCorrupt: 2
-repairingShouldBeDestroyed: 0
-repairing: -3
-restoringShouldBeGood: -10
-restoringShouldBeRepairing: -2
-restoringShouldBeCorrupt: 1     
-restoringShouldBeDestroyed: 2
-restoring: -6
-corruptShouldBeGood: -10
-corruptShouldBeRepairing: -10
-corruptShouldBeRestoring: -10
-corruptShouldBeDestroyed: 2
-corrupt: -10
-destroyedShouldBeGood: -20
-destroyedShouldBeRepairing: -20
-destroyedShouldBeRestoring: -20
-destroyedShouldBeCorrupt: -20
-destroyed: -20
-scanning: -2
-# IER status
-redIerRunning: -5
-greenIerBlocked: -10
-
-# Patching / Reset durations
-osPatchingDuration: 5            # The time taken to patch the OS
-nodeResetDuration: 5             # The time taken to reset a node (hardware)
-servicePatchingDuration: 5       # The time taken to patch a service
-fileSystemRepairingLimit: 5      # The time take to repair the file system
-fileSystemRestoringLimit: 5      # The time take to restore the file system
-fileSystemScanningLimit: 5       # The time taken to scan the file system

PRIMAITE/docs/source/about.rst

@@ -1,345 +0,0 @@
-.. _about:
-
-About PrimAITE
-==============
-
-Features
-********
-
-PrimAITE provides the following features:
-
-* A flexible network / system laydown based on the Python networkx framework​
-* Nodes and links (edges) host Python classes in order to present attributes and methods (and hence, a more representative model of a platform / system)​
-* A ‘green agent’ Information Exchange Requirement (IER) function allows the representation of traffic (protocols and loading) on any / all links. Application of IERs is based on the status of node operating systems and services​
-* A ‘green agent’ node Pattern-of-Life (PoL) function allows the representation of core behaviours on nodes (e.g. Operating state, Operating System state, Service state, File System state)​
-* An Access Control List (ACL) function, mimicking the behaviour of a network firewall, is applied across the model, following standard ACL rule format (e.g. DENY/ALLOW, source IP, destination IP, protocol and port). Application of IERs adheres to any ACL restrictions​
-* Presents an OpenAI Gym interface to the environment, allowing integration with any OpenAI Gym compliant defensive agents ​
-* Red agent activity based on ‘red’ IERs and ‘red’ PoL
-* Defined reward function for use with RL agents (based on nodes status, and green / red IER success)​
-* Fully configurable (network / system laydown, IERs, node PoL, ACL, episode step period, episode max steps) and repeatable to suit the training requirements of agents. Therefore, not bound to a representation of any particular platform, system or technology​
-* Full capture of discrete metrics relating to agent training (full system state, agent actions taken, average reward)​
-* Networkx provides laydown visualisation capability ​
-
-Architecture - Nodes and Links
-******************************
-
-**Nodes**
-
-An inheritance model has been adopted in order to model nodes. All nodes have the following base attributes (Class: Node):​
-
-* ID​
-* Name
-* Type (e.g. computer, switch, RTU - enumeration)​
-* Priority (P1, P2, P3, P4 or P5 - enumeration)​
-* Operating State (ON, OFF, RESETTING - enumeration)​
-
-Active Nodes also have the following attributes (Class: Active Node):​
-
-* IP Address​
-* Operating System State (GOOD, PATCHING, COMPROMISED - enumeration)​
-* File System State (GOOD, CORRUPT, DESTROYED, REPAIRING, RESTORING - enumeration)
-
-Service Nodes also have the following attributes (Class: Service Node)​:
-
-* List of Services (where service is composed of service name and port). There is no theoretical limit on the number of services that can be modelled. Services and protocols are currently intrinsically linked (i.e. a service is an application on a node transmitting traffic of this protocol type)​
-* Service state (GOOD, PATCHING, COMPROMISED, OVERWHELMED - enumeration)
-
-Passive Nodes are currently not used (but may be employed for non IP-based components such as machinery actuators in future releases).
-
-**Links**
-
-Links are modelled both as network edges (networkx) and as Python classes, in order to extend their functionality​. Links include the following attributes:​
-
-* ID​
-* Name
-* Bandwidth (bits/s)​
-* Source node ID
-* Destination node ID
-* Protocol list (containing the loading of protocols currently running on the link)
-
-When the simulation runs, IERs are applied to the links in order to model traffic loading, individually assigned to each protocol. This allows green (background) and red agent behaviour to be modelled, and defensive agents to identify suspicious traffic patterns at a protocol / traffic loading level of fidelity.
-
-Information Exchange Requirements (IERs)
-****************************************
-
-PrimAITE adopts the concept of Information Exchange Requirements (IERs) to model both green agent (background) and red agent (adversary) behaviour. IERs are used to initiate modelling of traffic loading on the network, and have the following attributes:​
-
-* ID​
-* Start step (i.e. which step in the training episode should the IER start)​
-* End step​ (i.e. which step in the training episode should the IER end)
-* Source node ID
-* Destination node ID​
-* Load (bits/s)​
-* Protocol​
-* Port​
-* Running status (i.e. on / off)
-
-The application of green agent IERs between a source and destination follows a number of rules. Specifically:​
-
-1. Does the current simulation time step fall between IER start and end step​
-2. Is the source node operational (both physically and at an O/S level), and is the service (protocol / port) associated with the IER (a) present on this node, and (b) in an operational state (i.e. not PATCHING)​
-3. Is the destination node operational (both physically and at an O/S level), and is the service (protocol / port) associated with the IER (a) present on this node, and (b) in an operational state (i.e. not PATCHING)​
-4. Are there any Access Control List rules in place that prevent the application of this IER​
-5. Are all switches in the (OSPF) path between source and destination operational (both physically and at an O/S level)​
-
-For red agent IERs, the application of IERs between a source and destination follows a number of subtly different rules. Specifically:​
-
-1. Does the current simulation time step fall between IER start and end step​
-2. Is the source node operational, and is the service (protocol / port) associated with the IER (a) present on that node and (b) already in a compromised state​
-3. Is the destination node operational, and is the service (protocol / port) associated with the IER present on that node​
-4. Are there any Access Control List rules in place that prevent the application of this IER​
-5. Are all switches in the (OSPF) path between source and destination operational (both physically and at an O/S level)
-
-Assuming the rules pass, the IER is applied to all relevant links (based on use of OSPF) between source and destination.
-
-Node Pattern-of-Life
-********************
-
-Every node can be impacted (i.e. have a status change applied to it) by either green agent pattern-of-life or red agent pattern-of-life. This is distinct from IERs, and allows for attacks (and defence) to be modelled purely within the confines of a node.
-
-The status changes that can be made to a node are as follows:
-
-* All Nodes:
-
-   * Operating State:
-
-      * ON
-      * OFF
-      * RESETTING - when a status of resetting is entered, the node will automatically exit this state after a number of steps (as defined by the nodeResetDuration configuration item) after which it returns to an ON state 
-
-* Active Nodes and Service Nodes:
-
-   * Operating System State:
-
-      * GOOD
-      * PATCHING - when a status of patching is entered, the node will automatically exit this state after a number of steps (as defined by the osPatchingDuration configuration item) after which it returns to a GOOD state
-      * COMPROMISED
-
-   * File System State:
-
-      * GOOD
-      * CORRUPT (can be resolved by repair or restore)
-      * DESTROYED (can be resolved by restore only)
-      * REPAIRING - when a status of repairing is entered, the node will automatically exit this state after a number of steps (as defined by the fileSystemRepairingLimit configuration item) after which it returns to a GOOD state
-      * RESTORING - when a status of repairing is entered, the node will automatically exit this state after a number of steps (as defined by the fileSystemRestoringLimit configuration item) after which it returns to a GOOD state
-
-* Service Nodes only:
-
-   * Service State (for any associated service):
-
-      * GOOD
-      * PATCHING - when a status of patching is entered, the service will automatically exit this state after a number of steps (as defined by the servicePatchingDuration configuration item) after which it returns to a GOOD state
-      * COMPROMISED
-      * OVERWHELMED
-
-Red agent pattern-of-life has an additional feature not found in the green pattern-of-life. This is the ability to influence the state of the attributes of a node via a number of different conditions:
-
-   * DIRECT:
-
-   The pattern-of-life described by the configuration file item will be applied regardless of any other conditions in the network. This is particularly useful for direct red agent entry into the network.
-
-   * IER:
-
-   The pattern-of-life described by the configuration file item will be applied to the service on the node, only if there is an IER of the same protocol / service type incoming at the specified timestep.
-
-   * SERVICE:
-
-   The pattern-of-life described by the configuration file item will be applied to the node based on the state of a service. The service can either be on the same node, or a different node within the network.
-
-Access Control List modelling
-*****************************
-
-An Access Control List (ACL) is modelled to provide the means to manage traffic flows in the system. This will allow defensive agents the means to turn on / off rules, or potentially create new rules, to counter an attack​.
-
-The ACL follows a standard network firewall format. For example:
-
-.. list-table:: ACL example
-   :widths: 25 25 25 25 25
-   :header-rows: 1
-
-   * - Permission
-     - Source IP
-     - Dest IP
-     - Protocol
-     - Port
-   * - DENY
-     - 192.168.1.2
-     - 192.168.1.3
-     - HTTPS
-     - 443
-   * - ALLOW
-     - 192.168.1.4
-     - ANY
-     - SMTP
-     - 25
-   * - DENY
-     - ANY
-     - 192.168.1.5
-     - ANY
-     - ANY
-
-All ACL rules are considered when applying an IER. Logic follows the order of rules, so a DENY or ALLOW for the same parameters will override an earlier entry.
-
-Observation Spaces
-******************
-
-The OpenAI Gym observation space provides the status of all nodes and links across the whole system:​
-
-* Nodes (in terms of operating state, operating system state, file system state and services state) ​
-* Links (in terms of current loading for each service/protocol)
-
-An example observation space is provided below:
-
-.. list-table:: Observation Space example
-   :widths: 25 25 25 25 25 25 25
-   :header-rows: 1
-
-   * - 
-     - ID
-     - Operating State
-     - O/S State
-     - File System State
-     - Service / Protocol A
-     - Service / Protocol B
-   * - Node A
-     - 1
-     - 1
-     - 1
-     - 1
-     - 1
-     - 1
-   * - Node B
-     - 2
-     - 1
-     - 3
-     - 1
-     - 1
-     - 1
-   * - Node C
-     - 3
-     - 2
-     - 1
-     - 1
-     - 3
-     - 2
-   * - Link 1
-     - 5
-     - 0
-     - 0
-     - 0
-     - 0
-     - 10000
-   * - Link 2
-     - 6
-     - 0
-     - 0
-     - 0
-     - 0
-     - 10000
-   * - Link 3
-     - 7
-     - 0
-     - 0
-     - 0
-     - 5000
-     - 0
-
-The observation space is a 6 x 6 Box type (OpenAI Gym Space) in this example. This is made up from the node and link information detailed below.
-
-For the nodes, the following values are represented:
-
- * ID
- * Operating State:
-
-    * 1 = ON
-    * 2 = OFF
-    * 3 = RESETTING
-
- * O/S State:
-
-    * 1 = GOOD
-    * 2 = PATCHING
-    * 3 = COMPROMISED
-
- * Service State:
-
-    * 1 = GOOD
-    * 2 = PATCHING
-    * 3 = COMPROMISED
-    * 4 = OVERWHELMED
-
- * File System State:
-
-    * 1 = GOOD
-    * 2 = CORRUPT
-    * 3 = DESTROYED
-    * 4 = REPAIRING
-    * 5 = RESTORING
-
-(Note that each service available in the network is provided as a column, although not all nodes may utilise all services)
-
-For the links, the following statuses are represented:
-
- * ID
- * Operating State = N/A
- * O/S State = N/A
- * Protocol = loading in bits/s
-
-Action Spaces
-**************
-
-The action space available to the blue agent comes in two types:
-
- 1. Node-based
- 2. Access Control List
-
-The choice of action space used during a training session is determined in the config_[name].yaml file.
-
-**Node-Based**
-
-The agent is able to influence the status of nodes by switching them off, resetting, or patching operating systems and services. In this instance, the action space is an OpenAI Gym multidiscrete type, as follows:
-
- * [0, num nodes] - Node ID (0 = nothing, node ID)
- * [0, 4] - What property it's acting on (0 = nothing, 1 = state, 2 = O/S state, 3 = service state, 4 = file system state)
- * [0, 3] - Action on property (0 = nothing, 1 = on / scan, 2 = off / repair, 3 = reset / patch / restore)
- * [0, num services] - Resolves to service ID (0 = nothing, resolves to service)
-
-**Access Control List**
-
-The blue agent is able to influence the configuration of the Access Control List rule set (which implements a system-wide firewall). In this instance, the action space is an OpenAI multidiscrete type, as follows:
-
-
- * [0, 2] - Action (0 = do nothing, 1 = create rule, 2 = delete rule)
- * [0, 1] - Permission (0 = DENY, 1 = ALLOW)
- * [0, num nodes] - Source IP (0 = any, then 1 -> x resolving to IP addresses)
- * [0, num nodes] - Dest IP (0 = any, then 1 -> x resolving to IP addresses)
- * [0, num services] - Protocol (0 = any, then 1 -> x resolving to protocol)
- * [0, num ports] - Port (0 = any, then 1 -> x resolving to port)
-
-Rewards
-*******
-
-A reward value is presented back to the blue agent on the conclusion of every step. The reward value is calculated via two methods which combine to give the total value:
-
- 1. Node and service status
- 2. IER status
-
-**Node and service status**
-
-On every step, the status of each node is compared against both a reference environment (simulating the situation if the red and blue agents had not impacted the environment) 
-and the before and after state of the environment. If the comparison against the reference environment shows no difference, then the score provided is "AllOK". If there is a 
-difference with respect to the reference environment, the before and after states are compared, and a score determined. See :ref:`config` for details of reward values.
-
-**IER status**
-
-On every step, the full IER set is examined to determine whether green and red agent IERs are being permitted to run. Any red agent IERs running incur a penalty; any green agent
-IERs not permitted to run also incur a penalty. See :ref:`config` for details of reward values.
-
-Future Enhancements
-*******************
-
-The PrimAITE project has an ambition to include the following enhancements in future releases:
-
-* Integration with a suitable standardised framework to allow multi-agent integration
-* Integration with external threat emulation tools, either using off-line data, or integrating at runtime
-* Provision of data such that agents can construct alternative observation spaces (as an alternative to the default PrimAITE observation space)

PRIMAITE/docs/source/conf.py

@@ -1,28 +0,0 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# For the full list of built-in configuration values, see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-
-# -- Project information -----------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-
-project = 'PrimAITE'
-copyright = '2022, jashort'
-author = 'jashort'
-release = '0.1.0'
-
-# -- General configuration ---------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
-
-extensions = ['sphinx_rtd_theme']
-
-templates_path = ['_templates']
-exclude_patterns = []
-
-
-
-# -- Options for HTML output -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
-
-html_theme = 'sphinx_rtd_theme'
-html_static_path = ['_static']

PRIMAITE/docs/source/config.rst

@@ -1,397 +0,0 @@
-.. _config:
-
-The Config Files Explained
-==========================
-
-PrimAITE uses two configuration files for its operation:
-
-* config_main.yaml - used to define the top-level settings of the PrimAITE environment, and the session that is to be run.
-* config_[name].yaml - used to define the low-level settings of a session, including the network laydown, green / red agent information exchange requirements (IERSs), Access Control Rules, Action Space type, and the number of steps in each episode.
-
-config_main.yaml:
-*****************
-
-The config_main.yaml file consists of the following attributes:
-
-**Generic Config Values**
-
-* **agentIdentifier** [enum]
-
-   This identifies the agent to use for the session. Select from one of the following:
-
-   * GENERIC - Where a user developed agent is to be used
-   * STABLE_BASELINES3_PPO - Use a SB3 PPO agent
-   * STABLE_BASELINES3_A2C - use a SB3 A2C agent
-
-* **numEpisodes** [int]
-
-   This defines the number of episodes that the agent will train or be evaluated over. Each episode consists of a number of steps (with step number defined in the config_[name].yaml file)
-
-* **timeDelay** [int]
-
-   The time delay (in milliseconds) to take between each step when running a GENERIC agent session
-
-* **configFilename** [filename]
-
-   The name of the config_[name].yaml file to use for this session
-
-* **sessionType** [text]
-
-   Type of session to be run (TRAINING or EVALUATION)
-
-* **loadAgent** [bool]
-
-   Determine whether to load an agent from file
-
-* **agentLoadFile** [text]
-
-   File path and file name of agent if you're loading one in
-
-* **observationSpaceHighValue** [int]
-
-   The high value to use for values in the observation space. This is set to 1000000000 by default, and should not need changing in most cases
-
-**Reward-Based Config Values**
-
-* **Generic [allOk]** [int]
-
-   The score to give when the current situation (for a given component) is no different from that expected in the baseline (i.e. as though no blue or red agent actions had been undertaken)
-
-* **Node Operating State [offShouldBeOn]** [int]
-
-   The score to give when the node should be on, but is off
-
-* **Node Operating State [offShouldBeResetting]** [int]
-
-   The score to give when the node should be resetting, but is off
-
-* **Node Operating State [onShouldBeOff]** [int]
-    
-   The score to give when the node should be off, but is on
-
-* **Node Operating State [onShouldBeResetting]** [int]
-    
-   The score to give when the node should be resetting, but is on
-
-* **Node Operating State [resettingShouldBeOn]** [int]
-    
-   The score to give when the node should be on, but is resetting
-
-* **Node Operating State [resettingShouldBeOff]** [int]
-    
-   The score to give when the node should be off, but is resetting
-
-* **Node Operating State [resetting]** [int]
-    
-   The score to give when the node is resetting
-
-* **Node Operating System or Service State [goodShouldBePatching]** [int]
-    
-   The score to give when the state should be patching, but is good
-
-* **Node Operating System or Service State [goodShouldBeCompromised]** [int]
-    
-   The score to give when the state should be compromised, but is good
-
-* **Node Operating System or Service State [goodShouldBeOverwhelmed]** [int]
-    
-   The score to give when the state should be overwhelmed, but is good
-
-* **Node Operating System or Service State [patchingShouldBeGood]** [int]
-    
-   The score to give when the state should be good, but is patching
-
-* **Node Operating System or Service State [patchingShouldBeCompromised]** [int]
-    
-   The score to give when the state should be compromised, but is patching
-
-* **Node Operating System or Service State [patchingShouldBeOverwhelmed]** [int]
-    
-   The score to give when the state should be overwhelmed, but is patching
-
-* **Node Operating System or Service State [patching]** [int]
-    
-   The score to give when the state is patching
-
-* **Node Operating System or Service State [compromisedShouldBeGood]** [int]
-    
-   The score to give when the state should be good, but is compromised
-
-* **Node Operating System or Service State [compromisedShouldBePatching]** [int]
-    
-   The score to give when the state should be patching, but is compromised
-
-* **Node Operating System or Service State [compromisedShouldBeOverwhelmed]** [int]
-    
-   The score to give when the state should be overwhelmed, but is compromised
-
-* **Node Operating System or Service State [compromised]** [int]
-    
-   The score to give when the state is compromised
-
-* **Node Operating System or Service State [overwhelmedShouldBeGood]** [int]
-    
-   The score to give when the state should be good, but is overwhelmed
-
-* **Node Operating System or Service State [overwhelmedShouldBePatching]** [int]
-    
-   The score to give when the state should be patching, but is overwhelmed
-
-* **Node Operating System or Service State [overwhelmedShouldBeCompromised]** [int]
-    
-   The score to give when the state should be compromised, but is overwhelmed
-
-* **Node Operating System or Service State [overwhelmed]** [int]
-    
-   The score to give when the state is overwhelmed
-
-* **Node File System State [goodShouldBeRepairing]** [int]
-
-    The score to give when the state should be repairing, but is good
-
-* **Node File System State [goodShouldBeRestoring]** [int]
-
-    The score to give when the state should be restoring, but is good
-
-* **Node File System State [goodShouldBeCorrupt]** [int]
-
-    The score to give when the state should be corrupt, but is good
-
-* **Node File System State [goodShouldBeDestroyed]** [int]
-
-    The score to give when the state should be destroyed, but is good
-
-* **Node File System State [repairingShouldBeGood]** [int]
-
-    The score to give when the state should be good, but is repairing
-
-* **Node File System State [repairingShouldBeRestoring]** [int]
-
-    The score to give when the state should be restoring, but is repairing
-
-* **Node File System State [repairingShouldBeCorrupt]** [int]
-
-    The score to give when the state should be corrupt, but is repairing
-
-* **Node File System State [repairingShouldBeDestroyed]** [int]
-
-    The score to give when the state should be destroyed, but is repairing
-
-* **Node File System State [repairing]** [int]
-
-    The score to give when the state is repairing
-
-* **Node File System State [restoringShouldBeGood]** [int]
-
-    The score to give when the state should be good, but is restoring
-
-* **Node File System State [restoringShouldBeRepairing]** [int]
-
-    The score to give when the state should be repairing, but is restoring
-
-* **Node File System State [restoringShouldBeCorrupt]** [int]
-
-    The score to give when the state should be corrupt, but is restoring
-
-* **Node File System State [restoringShouldBeDestroyed]** [int]
-
-    The score to give when the state should be destroyed, but is restoring
-
-* **Node File System State [restoring]** [int]
-
-    The score to give when the state is restoring
-
-* **Node File System State [corruptShouldBeGood]** [int]
-
-    The score to give when the state should be good, but is corrupt
-
-* **Node File System State [corruptShouldBeRepairing]** [int]
-
-    The score to give when the state should be repairing, but is corrupt
-
-* **Node File System State [corruptShouldBeRestoring]** [int]
-
-    The score to give when the state should be restoring, but is corrupt
-
-* **Node File System State [corruptShouldBeDestroyed]** [int]
-
-    The score to give when the state should be destroyed, but is corrupt
-
-* **Node File System State [corrupt]** [int]
-
-    The score to give when the state is corrupt
-
-* **Node File System State [destroyedShouldBeGood]** [int]
-
-    The score to give when the state should be good, but is destroyed
-
-* **Node File System State [destroyedShouldBeRepairing]** [int]
-
-    The score to give when the state should be repairing, but is destroyed
-
-* **Node File System State [destroyedShouldBeRestoring]** [int]
-
-    The score to give when the state should be restoring, but is destroyed
-
-* **Node File System State [destroyedShouldBeCorrupt]** [int]
-
-    The score to give when the state should be corrupt, but is destroyed
-
-* **Node File System State [destroyed]** [int]
-
-    The score to give when the state is destroyed
-
-* **Node File System State [scanning]** [int]
-
-    The score to give when the state is scanning
-
-* **IER Status [redIerRunning]** [int]
-    
-   The score to give when a red agent IER is permitted to run
-
-* **IER Status [greenIerBlocked]** [int]
-    
-   The score to give when a green agent IER is prevented from running
-
-**Patching / Reset Durations**
-
-* **osPatchingDuration** [int]
-
-   The number of steps to take when patching an Operating System
-
-* **nodeResetDuration** [int]
-   
-   The number of steps to take when resetting a node's operating state
-
-* **servicePatchingDuration** [int]
-   
-   The number of steps to take when patching a service
-
-* **fileSystemRepairingLimit** [int]: 
-
-   The number of steps to take when repairing the file system
-
-* **fileSystemRestoringLimit** [int]
-
-   The number of steps to take when restoring the file system
-
-* **fileSystemScanningLimit** [int]
-
-   The number of steps to take when scanning the file system
-
-config_[name].yaml:
-*******************
-
-The config_[name].yaml file consists of the following attributes:
-
-* **itemType: ACTIONS** [enum]
-   
-   Determines whether a NODE or ACL action space format is adopted for the session
-
-* **itemType: STEPS** [int]
-    
-   Determines the number of steps to run in each episode of the session
-
-* **itemType: PORTS** [int]
-   
-   Provides a list of ports modelled in this session
-
-* **itemType: SERVICES** [freetext]
-   
-   Provides a list of services modelled in this session
-
-* **itemType: NODE**
-    
-   Defines a node included in the system laydown being simulated. It should consist of the following attributes:
-
-     * **id** [int]: Unique ID for this YAML item
-     * **name** [freetext]: Human-readable name of the component
-     * **baseType** [enum]: Relates to the base type of the node. Can be SERVICE, ACTIVE or PASSIVE. PASSIVE nodes do not have an operating system or services. ACTIVE nodes have an operating system, but no services. SERVICE nodes have both an operating system and one or more services
-     * **nodeType** [enum]: Relates to the component type. Can be one of CCTV, SWITCH, COMPUTER, LINK, MONITOR, PRINTER, LOP, RTU, ACTUATOR or SERVER
-     * **priority** [enum]: Provides a priority for each node. Can be one of P1, P2, P3, P4 or P5 (which P1 being the highest)
-     * **hardwareState** [enum]: The initial hardware state of the node. Can be one of ON, OFF or RESETTING
-     * **ipAddress** [IP address]: The IP address of the component in format xxx.xxx.xxx.xxx
-     * **softwareState** [enum]: The intial state of the node operating system. Can be GOOD, PATCHING or COMPROMISED
-     * **fileSystemState** [enum]: The initial state of the node file system. Can be GOOD, CORRUPT, DESTROYED, REPAIRING or RESTORING
-     * **services**: For each service associated with the node:
-
-        * **name** [freetext]: Free-text name of the service, but must match one of the services defined for the system in the services list
-        * **port** [int]: Integer value of the port related to this service, but must match one of the ports defined for the system in the ports list
-        * **state** [enum]: The initial state of the service. Can be one of GOOD, PATCHING, COMPROMISED or OVERWHELMED
-     
-* **itemType: LINK**
-   
-   Defines a link included in the system laydown being simulated. It should consist of the following attributes:
-
-     * **id** [int]: Unique ID for this YAML item
-     * **name** [freetext]: Human-readable name of the component
-     * **bandwidth** [int]: The bandwidth (in bits/s) of the link
-     * **source** [int]: The ID of the source node
-     * **destination** [int]: The ID of the destination node
-
-* **itemType: GREEN_IER**
-
-   Defines a green agent Information Exchange Requirement (IER). It should consist of:
-
-     * **id** [int]: Unique ID for this YAML item
-     * **startStep** [int]: The start step (in the episode) for this IER to begin
-     * **endStep** [int]: The end step (in the episode) for this IER to finish
-     * **load** [int]: The load (in bits/s) for this IER to apply to links
-     * **protocol** [freetext]: The protocol to apply to the links. This must match a value in the services list
-     * **port** [int]: The port that the protocol is running on. This must match a value in the ports list
-     * **source** [int]: The ID of the source node
-     * **destination** [int]: The ID of the destination node
-     * **missionCriticality** [enum]: The mission criticality of this IER (with 5 being highest, 1 lowest)
-
-* **itemType: RED_IER**
-    
-   Defines a red agent Information Exchange Requirement (IER). It should consist of:
-
-     * **id** [int]: Unique ID for this YAML item
-     * **startStep** [int]: The start step (in the episode) for this IER to begin
-     * **endStep** [int]: The end step (in the episode) for this IER to finish
-     * **load** [int]: The load (in bits/s) for this IER to apply to links
-     * **protocol** [freetext]: The protocol to apply to the links. This must match a value in the services list
-     * **port** [int]: The port that the protocol is running on. This must match a value in the ports list
-     * **source** [int]: The ID of the source node
-     * **destination** [int]: The ID of the destination node
-     * **missionCriticality** [enum]: Not currently used. Default to 0
-
-* **itemType: GREEN_POL**
-     
-    Defines a green agent pattern-of-life instruction. It should consist of:
-
-      * **id** [int]: Unique ID for this YAML item
-      * **startStep** [int]: The start step (in the episode) for this PoL to begin
-      * **endStep** [int]: Not currently used. Default to same as start step
-      * **nodeId** [int]: The ID of the node to apply the PoL to
-      * **type** [enum]: The type of PoL to apply. Can be one of OPERATING, OS or SERVICE
-      * **protocol** [freetext]: The protocol to be affected if SERVICE type is chosen. Must match a value in the services list
-      * **state** [enuum]: The state to apply to the node (which represents the PoL change). Can be one of ON, OFF or RESETTING (for node state) or GOOD, PATCHING or COMPROMISED (for operating system state) or GOOD, PATCHING, COMPROMISED or OVERWHELMED (for service state)
-
-* **itemType: RED_POL**
-     
-    Defines a red agent pattern-of-life instruction. It should consist of:
-
-      * **id** [int]: Unique ID for this YAML item
-      * **startStep** [int]: The start step (in the episode) for this PoL to begin
-      * **endStep** [int]: Not currently used. Default to same as start step
-      * **targetNodeId** [int]: The ID of the node to apply the PoL to
-      * **initiator** [enum]: What initiates the PoL. Can be DIRECT, IER or SERVICE
-      * **type** [enum]: The type of PoL to apply. Can be one of OPERATING, OS or SERVICE
-      * **protocol** [freetext]: The protocol to be affected if SERVICE type is chosen. Must match a value in the services list
-      * **state** [enum]: The state to apply to the node (which represents the PoL change). Can be one of ON, OFF or RESETTING (for node state) or GOOD, PATCHING or COMPROMISED (for operating system state) or GOOD, PATCHING, COMPROMISED or OVERWHELMED (for service state) or GOOD, CORRUPT, DESTROYED, REPAIRING or RESTORING (for file system state)
-      * **sourceNodeId** [int] The ID of the source node containing the service to check (used for SERVICE initiator)
-      * **sourceNodeService** [freetext]: The service on the source node to check (used for SERVICE initiator). Must match a value in the services list for this node
-      * **sourceNodeServiceState** [enum]: The state of the source node service to check (used for SERVICE initiator). Can be one of GOOD, PATCHING, COMPROMISED or OVERWHELMED
-
-* **itemType: ACL_RULE**
-     
-    Defines an initial Access Control List (ACL) rule. It should consist of:
-
-      * **id** [int]: Unique ID for this YAML item
-      * **permission** [enum]: Defines either an allow or deny rule. Value must be either DENY or ALLOW
-      * **source** [IP address]: Defines the source IP address for the rule in xxx.xxx.xxx.xxx format
-      * **destination** [IP address]: Defines the destination IP address for the rule in xxx.xxx.xxx.xxx format
-      * **protocol** [freetext]: Defines the protocol for the rule. Must match a value in the services list
-      * **port** [int]: Defines the port for the rule. Must match a value in the ports list

PRIMAITE/docs/source/dependencies.rst

@@ -1,26 +0,0 @@
-.. _dependencies:
-
-PrimAITE Dependencies
-=====================
-
-PrimAITE is built with the following versions of dependencies:
-
-* Python 3.10.9
-* PyYAML 6.0
-* numpy 1.23.5
-* networkx 2.8.8
-* gym 0.21.0
-* matplotlib 3.6.2 
-* stable_baselines_3 1.6.2
-
-The latest release of PrimAITE has been tested against the following versions of dependencies:
-
-* Python 3.10.9
-* PyYAML 6.0
-* numpy 1.23.5
-* networkx 2.8.8
-* gym 0.21.0
-* matplotlib 3.6.2 
-* stable_baselines_3 1.6.2
-
-

PRIMAITE/docs/source/index.rst

@@ -1,42 +0,0 @@
-.. PrimAITE documentation master file, created by
-   sphinx-quickstart on Thu Dec  8 09:51:18 2022.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-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:​
-
-* 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
-* `Stable Baselines 3 <https://github.com/DLR-RM/stable-baselines3>`_ is used as a default source of RL algorithms (although PrimAITE is not limited to SB3 agents)
-
-Where next?
-------------
-
-The best place to start is :ref:`about`
-
-.. toctree::
-   :maxdepth: 8
-   :caption: Contents:
-
-   about
-   dependencies
-   config
-   session
-   results

PRIMAITE/docs/source/results.rst

@@ -1,42 +0,0 @@
-.. _results:
-
-Results, Output and Logging from PrimAITE
-=========================================
-
-PrimAITE produces four types of data:
-
-* Outputs - Results
-* Outputs - Diagrams
-* Outputs - Saved agents
-* Logging
-
-Outputs can be found in the *[Install Directory]\\PRIMAITE\\PRIMAITE\\outputs* directory
-
-Logging can be found in the *[Install Directory]\\PRIMAITE\\PRIMAITE\\logs* directory
-
-**Outputs - Results**
-
-PrimAITE automatically creates two sets of results from each session, and stores them in the *Results* folder:
-
-* Average reward per episode - a csv file listing the average reward for each episode of the session. This provides, for example, an indication of the change over a training session of the reward value
-* All transactions - a csv file listing the following values for every step of every episode:
-
-	* Timestamp
-	* Episode number
-	* Step number
-	* Initial observation space (before red and blue agent actions have been taken). Individual elements of the observation space are presented in the format OSI_X_Y
-	* Resulting observation space (after the red and blue agent actions have been taken) Individual elements of the observation space are presented in the format OSN_X_Y
-	* Reward value
-	* Action space (as presented by the blue agent on this step). Individual elements of the action space are presented in the format AS_X
-
-**Outputs - Diagrams**
-
-For each session, PrimAITE automatically creates a visualisation of the system / network laydown configuration, and stores it in the *Diagrams* folder.
-
-**Outputs - Saved agents**
-
-For each training session, assuming the agent being trained implements the *save()* function and this function is called by the code, PrimAITE automatically saves the agent state and stores it in the *agents* folder.
-
-**Logging**
-
-PrimAITE also provides output logs (for diagnosis) using the Python Logging package. These can be found in the *[Install Directory]\\PRIMAITE\\PRIMAITE\\logs* directory

PRIMAITE/docs/source/session.rst

@@ -1,88 +0,0 @@
-.. _session:
-
-Running a PrimAITE Training or Evaluation Session
-=================================================
-
-The application will determine whether a Training or Evaluation session is being executed via the 'sessionType' value in the config_mail.yaml file. A PrimAITE session will usually be associated with a "Use Case Profile"; this document will present:
-
-* The Use Case name, default number of steps in an episode and default number of episodes in a session. The number of steps and episodes can be modified in the configuration files
-* The system laydown being modelled
-* The objectives of the session (steady-state), the red agent and the blue agent (in a defensive role)
-* The green agent pattern-of-life profile
-* The red agent attack profile
-* The observation space definition
-* The action space definition
-* Agent integration guidance
-* Initial Access Control List settings (if applicable)
-* The reward function definition
-
-**Integrating a user defined blue agent**
-
-Integrating a blue agent with PrimAITE requires some modification of the code within the main.py file. The main.py file consists of a number of functions, each of which will invoke training for a particular agent. These are:
-
-* Generic (run_generic)
-* Stable Baselines 3 PPO (run_stable_baselines3_ppo)
-* Stable Baselines 3 A2C (run_stable_baselines3_a2c)
-
-The selection of which agent type to use is made via the config_main.yaml file. In order to train a user generated agent, 
-the run_generic function should be selected, and should be modified (typically) to be:
-
-.. code:: python
-
-    agent = MyAgent(environment, max_steps)​
-    for episode in range(0, num_episodes):​
-        agent.learn()      ​
-    env.close()​
-    save_agent(agent)
-
-Where:
-
-* *MyAgent* is the user created agent
-* *environment* is the PrimAITE environment
-* *max_steps* is the number of steps in an episode, as defined in the config_[name].yaml file
-* *num_episodes* is the number of episodes in the session, as defined in the config_main.yaml file
-* the *.learn()* function should be defined in the user created agent
-* the *env.close()* function is defined within PrimAITE
-* the *save_agent()* assumes that a *save()* function has been defined in the user created agent. If not, this line can be ommitted (although it is encouraged, since it will allow the agent to be saved and ported)
-
-The code below provides a suggested format for the learn() function within the user created agent.
-It's important to include the *self.environment.reset()* call within the episode loop in order that the 
-environment is reset between episodes. Note that the example below should not be considered exhaustive.
-
-.. code:: python
-
-    def learn(self) :​
-
-    # pre-reqs​​
-
-    # reset the environment​
-    self.environment.reset()​
-    done = False​
-    
-    for step in range(max_steps):​
-        # calculate the action​
-        action = ...
-
-        ​# execute the environment step​
-        new_state, reward, done, info = self.environment.step(action)​
-
-        # algorithm updates​
-        ...
-
-        # update to our new state​
-        state = new_state​
-
-        # if done, finish episode​
-        if done == True:​
-            break
-
-**Running the session**
- 
-In order to execute a session, carry out the following steps:
-
-1. Navigate to "[Install directory]\\PRIMAITE\\PRIMAITE\\” 
-2. Start a console window (type “CMD” in path window, or start a console window first and navigate to “[Install Directory]\\PRIMAITE\\PRIMAITE\\”) 
-3. Type “python main.py” 
-4. The session will start with an output indicating the current episode, and average reward value for the episode 
-
- 

PRIMAITE/environment/__init__.py

@@ -1,2 +0,0 @@
-
-# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.

PRIMAITE/environment/reward.py

@@ -1,340 +0,0 @@
-# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.
-"""
-Implements reward function
-"""
-
-from common.enums import *
-from nodes.active_node import ActiveNode
-from nodes.service_node import ServiceNode
-
-def calculate_reward_function(initial_nodes, final_nodes, reference_nodes, green_iers, red_iers, step_count, config_values):
-    """
-    Compares the states of the initial and final nodes/links to get a reward
-
-    Args:
-        initial_nodes: The nodes before red and blue agents take effect
-        final_nodes: The nodes after red and blue agents take effect
-        reference_nodes: The nodes if there had been no red or blue effect
-        green_iers: The green IERs (should be running)
-        red_iers: Should be stopeed (ideally) by the blue agent
-        step_count: current step
-        config_values: Config values
-    """
-
-    reward_value = 0
-
-    # For each node, compare operating state, o/s operating state, service states
-    for node_key, final_node in final_nodes.items():
-        initial_node = initial_nodes[node_key]
-        reference_node = reference_nodes[node_key]
-            
-        # Operating State
-        reward_value += score_node_operating_state(final_node, initial_node, reference_node, config_values)
-
-        # Operating System State
-        if (isinstance(final_node, ActiveNode) or isinstance(final_node, ServiceNode)):
-            reward_value += score_node_os_state(final_node, initial_node, reference_node, config_values)
-
-        # Service State
-        if (isinstance(final_node, ServiceNode)):
-            reward_value += score_node_service_state(final_node, initial_node, reference_node, config_values)
-
-        # File System State
-        if isinstance(final_node, ActiveNode):
-            reward_value += score_node_file_system(final_node, initial_node, reference_node, config_values)
- 
-    # Go through each red IER - penalise if it is running
-    for ier_key, ier_value in red_iers.items():
-        start_step = ier_value.get_start_step()
-        stop_step = ier_value.get_end_step()
-        if step_count >= start_step and step_count <= stop_step:
-            if ier_value.get_is_running():
-                reward_value += config_values.red_ier_running
-
-    # Go through each green IER - penalise if it's not running (weighted)
-    for ier_key, ier_value in green_iers.items():
-        start_step = ier_value.get_start_step()
-        stop_step = ier_value.get_end_step()
-        if step_count >= start_step and step_count <= stop_step:
-            if not ier_value.get_is_running():
-                reward_value += config_values.green_ier_blocked * ier_value.get_mission_criticality()
-
-    return reward_value
-
-
-def score_node_operating_state(final_node, initial_node, reference_node, config_values):
-    """
-    Calculates score relating to the operating state of a node
-
-    Args:
-        final_node: The node after red and blue agents take effect
-        initial_node: The node before red and blue agents take effect
-        reference_node: The node if there had been no red or blue effect
-        config_values: Config values
-    """
-    
-    score = 0    
-    final_node_operating_state = final_node.get_state()
-    initial_node_operating_state = initial_node.get_state()
-    reference_node_operating_state = reference_node.get_state()
-
-    if final_node_operating_state == reference_node_operating_state:
-        # All is well - we're no different from the reference situation
-        score += config_values.all_ok
-    else:     
-        # We're different from the reference situation
-        # Need to compare initial and final state of node (i.e. after red and blue actions)
-        if initial_node_operating_state == HARDWARE_STATE.ON:
-            if final_node_operating_state == HARDWARE_STATE.OFF:
-                score += config_values.off_should_be_on
-            elif final_node_operating_state == HARDWARE_STATE.RESETTING:
-                score += config_values.resetting_should_be_on
-            else:
-                pass
-        elif initial_node_operating_state == HARDWARE_STATE.OFF:
-            if final_node_operating_state == HARDWARE_STATE.ON:
-                score += config_values.on_should_be_off
-            elif final_node_operating_state == HARDWARE_STATE.RESETTING:
-                score += config_values.resetting_should_be_off  
-            else:
-                pass
-        elif initial_node_operating_state == HARDWARE_STATE.RESETTING:
-            if final_node_operating_state == HARDWARE_STATE.ON:
-                score += config_values.on_should_be_resetting
-            elif final_node_operating_state == HARDWARE_STATE.OFF:
-                score += config_values.off_should_be_resetting
-            elif final_node_operating_state == HARDWARE_STATE.RESETTING:
-                score += config_values.resetting
-            else:
-                pass
-        else:
-            pass
-
-    return score
-
-def score_node_os_state(final_node, initial_node, reference_node, config_values):
-    """
-    Calculates score relating to the operating system state of a node
-
-    Args:
-        final_node: The node after red and blue agents take effect
-        initial_node: The node before red and blue agents take effect
-        reference_node: The node if there had been no red or blue effect
-        config_values: Config values
-    """
-
-    score = 0    
-    final_node_os_state = final_node.get_os_state()
-    initial_node_os_state = initial_node.get_os_state()
-    reference_node_os_state = reference_node.get_os_state()
-
-    if final_node_os_state == reference_node_os_state:
-        # All is well - we're no different from the reference situation
-        score += config_values.all_ok
-    else:  
-        # We're different from the reference situation
-        # Need to compare initial and final state of node (i.e. after red and blue actions)
-        if initial_node_os_state == SOFTWARE_STATE.GOOD:
-            if final_node_os_state == SOFTWARE_STATE.PATCHING:
-                score += config_values.patching_should_be_good
-            elif final_node_os_state == SOFTWARE_STATE.COMPROMISED:
-                score += config_values.compromised_should_be_good
-            else:
-                pass
-        elif initial_node_os_state == SOFTWARE_STATE.PATCHING:
-            if final_node_os_state == SOFTWARE_STATE.GOOD:
-                score += config_values.good_should_be_patching
-            elif final_node_os_state == SOFTWARE_STATE.COMPROMISED:
-                score += config_values.compromised_should_be_patching  
-            elif final_node_os_state == SOFTWARE_STATE.PATCHING:
-                score += config_values.patching 
-            else:
-                pass              
-        elif initial_node_os_state == SOFTWARE_STATE.COMPROMISED:
-            if final_node_os_state == SOFTWARE_STATE.GOOD:
-                score += config_values.good_should_be_compromised
-            elif final_node_os_state == SOFTWARE_STATE.PATCHING:
-                score += config_values.patching_should_be_compromised
-            elif final_node_os_state == SOFTWARE_STATE.COMPROMISED:
-                score += config_values.compromised 
-            else:
-                pass
-        else:
-            pass
-
-    return score
-
-def score_node_service_state(final_node, initial_node, reference_node, config_values):
-    """
-    Calculates score relating to the service state(s) of a node
-
-    Args:
-        final_node: The node after red and blue agents take effect
-        initial_node: The node before red and blue agents take effect
-        reference_node: The node if there had been no red or blue effect
-        config_values: Config values
-    """
-
-    score = 0    
-    final_node_services = final_node.get_services()
-    initial_node_services = initial_node.get_services()
-    reference_node_services = reference_node.get_services()
-    
-    for service_key, final_service in final_node_services.items():
-        reference_service = reference_node_services[service_key]
-        initial_service = initial_node_services[service_key]
-
-        if final_service.get_state() == reference_service.get_state():
-            # All is well - we're no different from the reference situation
-            score += config_values.all_ok
-        else:
-            # We're different from the reference situation
-            # Need to compare initial and final state of node (i.e. after red and blue actions)
-            if initial_service.get_state() == SOFTWARE_STATE.GOOD:
-                if final_service.get_state() == SOFTWARE_STATE.PATCHING:
-                    score += config_values.patching_should_be_good
-                elif final_service.get_state() == SOFTWARE_STATE.COMPROMISED:
-                    score += config_values.compromised_should_be_good
-                elif final_service.get_state() == SOFTWARE_STATE.OVERWHELMED:
-                    score += config_values.overwhelmed_should_be_good
-                else:
-                    pass
-            elif initial_service.get_state() == SOFTWARE_STATE.PATCHING:
-                if final_service.get_state() == SOFTWARE_STATE.GOOD:
-                    score += config_values.good_should_be_patching
-                elif final_service.get_state() == SOFTWARE_STATE.COMPROMISED:
-                    score += config_values.compromised_should_be_patching    
-                elif final_service.get_state() == SOFTWARE_STATE.OVERWHELMED:
-                    score += config_values.overwhelmed_should_be_patching 
-                elif final_service.get_state() == SOFTWARE_STATE.PATCHING:
-                    score += config_values.patching 
-                else:
-                    pass
-            elif initial_service.get_state() == SOFTWARE_STATE.COMPROMISED:
-                if final_service.get_state() == SOFTWARE_STATE.GOOD:
-                    score += config_values.good_should_be_compromised
-                elif final_service.get_state() == SOFTWARE_STATE.PATCHING:
-                    score += config_values.patching_should_be_compromised
-                elif final_service.get_state() == SOFTWARE_STATE.COMPROMISED:
-                    score += config_values.compromised 
-                elif final_service.get_state() == SOFTWARE_STATE.OVERWHELMED:
-                    score += config_values.overwhelmed_should_be_compromised 
-                else:
-                    pass
-            elif initial_service.get_state() == SOFTWARE_STATE.OVERWHELMED:
-                if final_service.get_state() == SOFTWARE_STATE.GOOD:
-                    score += config_values.good_should_be_overwhelmed
-                elif final_service.get_state() == SOFTWARE_STATE.PATCHING:
-                    score += config_values.patching_should_be_overwhelmed
-                elif final_service.get_state() == SOFTWARE_STATE.COMPROMISED:
-                    score += config_values.compromised_should_be_overwhelmed 
-                elif final_service.get_state() == SOFTWARE_STATE.OVERWHELMED:
-                    score += config_values.overwhelmed 
-                else:
-                    pass
-            else:
-                pass
-
-    return score
-
-def score_node_file_system(final_node, initial_node, reference_node, config_values):
-    """
-    Calculates score relating to the file system state of a node
-
-    Args:
-        final_node: The node after red and blue agents take effect
-        initial_node: The node before red and blue agents take effect
-        reference_node: The node if there had been no red or blue effect
-    """
-
-    score = 0    
-    final_node_file_system_state = final_node.get_file_system_state_actual()
-    initial_node_file_system_state = initial_node.get_file_system_state_actual()
-    reference_node_file_system_state = reference_node.get_file_system_state_actual()
-
-    final_node_scanning_state = final_node.is_scanning_file_system()
-    reference_node_scanning_state = reference_node.is_scanning_file_system()
-
-    # File System State
-    if final_node_file_system_state == reference_node_file_system_state:
-        # All is well - we're no different from the reference situation
-        score += config_values.all_ok
-    else:  
-        # We're different from the reference situation
-        # Need to compare initial and final state of node (i.e. after red and blue actions)
-        if initial_node_file_system_state == FILE_SYSTEM_STATE.GOOD:
-            if final_node_file_system_state == FILE_SYSTEM_STATE.REPAIRING:
-                score += config_values.repairing_should_be_good
-            elif final_node_file_system_state == FILE_SYSTEM_STATE.RESTORING:
-                score += config_values.restoring_should_be_good
-            elif final_node_file_system_state == FILE_SYSTEM_STATE.CORRUPT:
-                score += config_values.corrupt_should_be_good
-            elif final_node_file_system_state == FILE_SYSTEM_STATE.DESTROYED:
-                score += config_values.destroyed_should_be_good
-            else:
-                pass
-        elif initial_node_file_system_state == FILE_SYSTEM_STATE.REPAIRING:
-            if final_node_file_system_state == FILE_SYSTEM_STATE.GOOD:
-                score += config_values.good_should_be_repairing
-            elif final_node_file_system_state == FILE_SYSTEM_STATE.RESTORING:
-                score += config_values.restoring_should_be_repairing  
-            elif final_node_file_system_state == FILE_SYSTEM_STATE.CORRUPT:
-                score += config_values.corrupt_should_be_repairing  
-            elif final_node_file_system_state == FILE_SYSTEM_STATE.DESTROYED:
-                score += config_values.destroyed_should_be_repairing 
-            elif final_node_file_system_state == FILE_SYSTEM_STATE.REPAIRING:
-                score += config_values.repairing
-            else:
-                pass              
-        elif initial_node_file_system_state == FILE_SYSTEM_STATE.RESTORING:
-            if final_node_file_system_state == FILE_SYSTEM_STATE.GOOD:
-                score += config_values.good_should_be_restoring
-            elif final_node_file_system_state == FILE_SYSTEM_STATE.REPAIRING:
-                score += config_values.repairing_should_be_restoring
-            elif final_node_file_system_state == FILE_SYSTEM_STATE.CORRUPT:
-                score += config_values.corrupt_should_be_restoring
-            elif final_node_file_system_state == FILE_SYSTEM_STATE.DESTROYED:
-                score += config_values.destroyed_should_be_restoring  
-            elif final_node_file_system_state == FILE_SYSTEM_STATE.RESTORING:
-                score += config_values.restoring  
-            else:
-                pass
-        elif initial_node_file_system_state == FILE_SYSTEM_STATE.CORRUPT:
-            if final_node_file_system_state == FILE_SYSTEM_STATE.GOOD:
-                score += config_values.good_should_be_corrupt
-            elif final_node_file_system_state == FILE_SYSTEM_STATE.REPAIRING:
-                score += config_values.repairing_should_be_corrupt
-            elif final_node_file_system_state == FILE_SYSTEM_STATE.RESTORING:
-                score += config_values.restoring_should_be_corrupt
-            elif final_node_file_system_state == FILE_SYSTEM_STATE.DESTROYED:
-                score += config_values.destroyed_should_be_corrupt  
-            elif final_node_file_system_state == FILE_SYSTEM_STATE.CORRUPT:
-                score += config_values.corrupt  
-            else:
-                pass
-        elif initial_node_file_system_state == FILE_SYSTEM_STATE.DESTROYED:
-            if final_node_file_system_state == FILE_SYSTEM_STATE.GOOD:
-                score += config_values.good_should_be_destroyed
-            elif final_node_file_system_state == FILE_SYSTEM_STATE.REPAIRING:
-                score += config_values.repairing_should_be_destroyed
-            elif final_node_file_system_state == FILE_SYSTEM_STATE.RESTORING:
-                score += config_values.restoring_should_be_destroyed
-            elif final_node_file_system_state == FILE_SYSTEM_STATE.CORRUPT:
-                score += config_values.corrupt_should_be_destroyed  
-            elif final_node_file_system_state == FILE_SYSTEM_STATE.DESTROYED:
-                score += config_values.destroyed  
-            else:
-                pass
-        else:
-            pass
-
-    # Scanning State
-    if final_node_scanning_state == reference_node_scanning_state:
-        # All is well - we're no different from the reference situation
-        score += config_values.all_ok
-    else: 
-        # We're different from the reference situation
-        # We're scanning the file system which incurs a penalty (as it slows down systems)
-        score += config_values.scanning
-
-    return score

PRIMAITE/links/__init__.py

@@ -1 +0,0 @@
-# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.

PRIMAITE/links/link.py

@@ -1,132 +0,0 @@
-# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.
-"""
-The link class
-"""
-
-from common.protocol import Protocol
-from common.enums import *
-
-class Link(object):
-    """
-    Link class
-    """
-
-    def __init__(self, _id, _bandwidth, _source_node_name, _dest_node_name, _services):
-        """
-        Init
-
-        Args:
-            _id: The IER id
-            _bandwidth: The bandwidth of the link (bps)
-            _source_node_name: The name of the source node
-            _dest_node_name: The name of the destination node
-            _protocols: The protocols to add to the link
-        """
-
-        self.id = _id
-        self.bandwidth = _bandwidth     
-        self.source_node_name = _source_node_name
-        self.dest_node_name = _dest_node_name
-        self.protocol_list = []
-
-        # Add the default protocols
-        for protocol_name in _services:
-            self.add_protocol(protocol_name)
-
-    def add_protocol(self, _protocol):
-        """
-        Adds a new protocol to the list of protocols on this link
-
-        Args:
-            _protocol: The protocol to be added (enum)
-        """
-
-        self.protocol_list.append(Protocol(_protocol))
-
-    def get_id(self):
-        """
-        Gets link ID
-
-        Returns:
-             Link ID
-        """
-
-        return self.id
-
-    def get_source_node_name(self):
-        """
-        Gets source node name
-
-        Returns:
-             Source node name
-        """
-
-        return self.source_node_name
-
-    def get_dest_node_name(self):
-        """
-        Gets destination node name
-
-        Returns:
-             Destination node name
-        """
-
-        return self.dest_node_name
-
-    def get_bandwidth(self):
-        """
-        Gets bandwidth of link
-
-        Returns:
-             Link bandwidth (bps)
-        """
-
-        return self.bandwidth
-
-    def get_protocol_list(self):
-        """
-        Gets list of protocols on this link
-
-        Returns:
-             List of protocols on this link
-        """
-
-        return self.protocol_list
-
-    def get_current_load(self):
-        """
-        Gets current total load on this link
-
-        Returns:
-             Total load on this link (bps)
-        """
-
-        total_load = 0
-        for protocol in self.protocol_list:
-            total_load += protocol.get_load()
-        return total_load
-
-    def add_protocol_load(self, _protocol, _load):
-        """
-        Adds a loading to a protocol on this link
-
-        Args:
-            _protocol: The protocol to load
-            _load: The amount to load (bps)
-        """
-
-        for protocol in self.protocol_list:
-            if protocol.get_name() == _protocol:
-                protocol.add_load(_load)
-            else:
-                pass
-
-    def clear_traffic(self):
-        """
-        Clears all traffic on this link
-        """
-
-        for protocol in self.protocol_list:
-            protocol.clear_load()
-
-

PRIMAITE/nodes/__init__.py

@@ -1 +0,0 @@
-# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.

PRIMAITE/nodes/active_node.py

@@ -1,205 +0,0 @@
-# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.
-"""
-An Active Node (i.e. not an actuator)
-"""
-
-from nodes.node import Node
-from common.enums import *
-
-class ActiveNode(Node):
-    """
-    Active Node class
-    """
-
-    def __init__(self, _id, _name, _type, _priority, _state, _ip_address, _os_state, _file_system_state, _config_values):
-        """
-        Init
-
-        Args:
-            _id: The node ID
-            _name: The node name
-            _type: The node type (enum)
-            _priority: The node priority (enum)
-            _state: The node state (enum)
-            _ip_address: The node IP address
-            _os_state: The node Operating System state
-            _file_system_state: The node file system state
-            _config_values: The config values
-        """
-
-        super().__init__(_id, _name, _type, _priority, _state, _config_values)
-        self.ip_address = _ip_address
-        # Related to O/S
-        self.os_state = _os_state
-        self.patching_count = 0
-        # Related to File System
-        self.file_system_state_actual = _file_system_state
-        self.file_system_state_observed = _file_system_state
-        self.file_system_scanning = False
-        self.file_system_scanning_count = 0
-        self.file_system_action_count = 0
-
-
-    def set_ip_address(self, _ip_address):
-        """
-        Sets IP address
-
-        Args:
-            _ip_address: IP address
-        """
-
-        self.ip_address = _ip_address
-
-    def get_ip_address(self):
-        """
-        Gets IP address
-
-        Returns:
-             IP address
-        """
-        return self.ip_address
-
-    def set_os_state(self, _os_state):
-        """
-        Sets operating system state
-
-        Args:
-            _os_state: Operating system state
-        """
-
-        self.os_state = _os_state
-        if _os_state == SOFTWARE_STATE.PATCHING:
-            self.patching_count = self.config_values.os_patching_duration
-
-    def set_os_state_if_not_compromised(self, _os_state):
-        """
-        Sets operating system state if the node is not compromised
-
-        Args:
-            _os_state: Operating system state
-        """
-
-        if self.os_state != SOFTWARE_STATE.COMPROMISED:
-            self.os_state = _os_state
-            if _os_state == SOFTWARE_STATE.PATCHING:
-                self.patching_count = self.config_values.os_patching_duration
-
-    def get_os_state(self):
-        """
-        Gets operating system state
-
-        Returns:
-             Operating system state
-        """
-
-        return self.os_state
-
-    def update_os_patching_status(self):
-        """
-        Updates operating system status based on patching cycle
-        """
-
-        self.patching_count -= 1
-        if self.patching_count <= 0:
-            self.patching_count = 0
-            self.os_state = SOFTWARE_STATE.GOOD
-
-    def set_file_system_state(self, _file_system_state):
-        """
-        Sets the file system state (actual and observed)
-
-        Args:
-            _file_system_state: File system state
-        """
-
-        self.file_system_state_actual = _file_system_state
-
-        if _file_system_state == FILE_SYSTEM_STATE.REPAIRING:
-            self.file_system_action_count = self.config_values.file_system_repairing_limit
-            self.file_system_state_observed = FILE_SYSTEM_STATE.REPAIRING
-        elif _file_system_state == FILE_SYSTEM_STATE.RESTORING:
-            self.file_system_action_count = self.config_values.file_system_restoring_limit
-            self.file_system_state_observed = FILE_SYSTEM_STATE.RESTORING
-        elif _file_system_state == FILE_SYSTEM_STATE.GOOD:
-            self.file_system_state_observed = FILE_SYSTEM_STATE.GOOD
-
-    def set_file_system_state_if_not_compromised(self, _file_system_state):
-        """
-        Sets the file system state (actual and observed) if not in a compromised state
-        Use for green PoL to prevent it overturning a compromised state
-
-        Args:
-            _file_system_state: File system state
-        """
-
-        if self.file_system_state_actual != FILE_SYSTEM_STATE.CORRUPT and self.file_system_state_actual != FILE_SYSTEM_STATE.DESTROYED:
-            self.file_system_state_actual = _file_system_state
-
-            if _file_system_state == FILE_SYSTEM_STATE.REPAIRING:
-                self.file_system_action_count = self.config_values.file_system_repairing_limit
-                self.file_system_state_observed = FILE_SYSTEM_STATE.REPAIRING
-            elif _file_system_state == FILE_SYSTEM_STATE.RESTORING:
-                self.file_system_action_count = self.config_values.file_system_restoring_limit
-                self.file_system_state_observed = FILE_SYSTEM_STATE.RESTORING
-            elif _file_system_state == FILE_SYSTEM_STATE.GOOD:
-                self.file_system_state_observed = FILE_SYSTEM_STATE.GOOD
-
-    def get_file_system_state_actual(self):
-        """
-        Gets file system state (actual)
-
-        Returns:
-             File system state (actual)
-        """
-
-        return self.file_system_state_actual
-
-    def get_file_system_state_observed(self):
-        """
-        Gets file system state (observed)
-
-        Returns:
-             File system state (observed)
-        """
-
-        return self.file_system_state_observed
-
-    def start_file_system_scan(self):
-        """
-        Starts a file system scan
-        """
-
-        self.file_system_scanning = True
-        self.file_system_scanning_count = self.config_values.file_system_scanning_limit
-
-    def is_scanning_file_system(self):
-        """
-        Gets true/false on whether file system is being scanned
-
-        Returns:
-             True if file system is being scanned
-        """
-
-        return self.file_system_scanning
-
-    def update_file_system_state(self):
-        """
-        Updates file system status based on scanning / restore / repair cycle
-        """
-
-        # Deprecate both the action count (for restoring or reparing) and the scanning count
-        self.file_system_action_count -= 1
-        self.file_system_scanning_count -= 1
-
-        # Reparing / Restoring updates
-        if self.file_system_action_count <= 0:
-            self.file_system_action_count = 0
-            if self.file_system_state_actual == FILE_SYSTEM_STATE.REPAIRING or self.file_system_state_actual == FILE_SYSTEM_STATE.RESTORING:
-                self.file_system_state_actual = FILE_SYSTEM_STATE.GOOD
-                self.file_system_state_observed = FILE_SYSTEM_STATE.GOOD
-
-        # Scanning updates
-        if self.file_system_scanning == True and self.file_system_scanning_count < 0:
-            self.file_system_state_observed = self.file_system_state_actual
-            self.file_system_scanning = False
-            self.file_system_scanning_count = 0

PRIMAITE/nodes/node.py

@@ -1,176 +0,0 @@
-# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.
-"""
-The base Node class
-"""
-
-from common.enums import *
-
-class Node:
-    """
-    Node class
-    """
-
-    def __init__(self, _id, _name, _type, _priority, _state, _config_values):
-        """
-        Init
-
-        Args:
-            _id: The node id
-            _name: The name of the node
-            _type: The type of the node
-            _priority: The priority of the node
-            _state: The state of the node
-        """
-
-        self.id = _id
-        self.name = _name
-        self.type = _type
-        self.priority = _priority
-        self.operating_state = _state
-        self.resetting_count = 0    
-        self.config_values = _config_values
-
-    def __repr__(self):
-        """
-        Returns the name of the node
-        """
-
-        return self.name
-
-    def set_id(self, _id):
-        """
-        Sets the node ID
-
-        Args:
-            _id: The node ID
-        """
-
-        self.id = _id
-
-    def get_id(self):
-        """
-        Gets the node ID
-
-        Returns:
-             The node ID
-        """
-
-        return self.id
-
-    def set_name(self, _name):
-        """
-        Sets the node name
-
-        Args:
-            _name: The node name
-        """
-
-        self.name = _name
-
-    def get_name(self):
-        """
-        Gets the node name
-
-        Returns:
-             The node name
-        """
-
-        return self.name
-
-    def set_type(self, _type):
-        """
-        Sets the node type
-
-        Args:
-            _type: The node type
-        """
-
-        self.type = _type
-
-    def get_type(self):
-        """
-        Gets the node type
-
-        Returns:
-             The node type
-        """
-
-        return self.type
-
-    def set_priority(self, _priority):
-        """
-        Sets the node priority
-
-        Args:
-            _priority: The node priority
-        """
-
-        self.priority = _priority
-
-    def get_priority(self):
-        """
-        Gets the node priority
-
-        Returns:
-             The node priority
-        """
-
-        return self.priority
-
-    def set_state(self, _state):
-        """
-        Sets the node state
-
-        Args:
-            _state: The node state
-        """
-
-        self.operating_state = _state
-
-    def get_state(self):
-        """
-        Gets the node operating state
-
-        Returns:
-             The node operating state
-        """
-
-        return self.operating_state
-
-    def turn_on(self):
-        """
-        Sets the node state to ON
-        """
-
-        self.operating_state = HARDWARE_STATE.ON
-
-    def turn_off(self):
-        """
-        Sets the node state to OFF
-        """
-
-        self.operating_state = HARDWARE_STATE.OFF
-
-    def reset(self):
-        """
-        Sets the node state to Resetting and starts the reset count
-        """
-
-        self.operating_state = HARDWARE_STATE.RESETTING
-        self.resetting_count = self.config_values.node_reset_duration
-
-    def update_resetting_status(self):
-        """
-        Updates the resetting count
-        """
-
-        self.resetting_count -= 1
-        if self.resetting_count <= 0:
-            self.resetting_count = 0
-            self.operating_state = HARDWARE_STATE.ON
-
-
-
-
-
-

PRIMAITE/nodes/node_state_instruction_green.py

@@ -1,92 +0,0 @@
-# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.
-"""
-Defines node behaviour for Green PoL
-"""
-
-class NodeStateInstructionGreen(object):
-    """
-    The Node State Instruction class
-    """
-
-    def __init__(self, _id, _start_step, _end_step, _node_id, _node_pol_type, _service_name, _state):
-        """
-        Init
-
-        Args:
-            _id: The node state instruction id
-            _start_step: The start step of the instruction
-            _end_step: The end step of the instruction
-            _node_id: The id of the associated node
-            _node_pol_type: The pattern of life type
-            _service_name: The service name
-            _state: The state (node or service)
-        """
-
-        self.id = _id
-        self.start_step = _start_step
-        self.end_step = _end_step
-        self.node_id = _node_id
-        self.node_pol_type = _node_pol_type
-        self.service_name = _service_name # Not used when not a service instruction
-        self.state = _state     
-
-    def get_start_step(self):
-        """
-        Gets the start step
-
-        Returns:
-             The start step
-        """
-
-        return self.start_step
-
-    def get_end_step(self):
-        """
-        Gets the end step
-
-        Returns:
-             The end step
-        """
-
-        return self.end_step
-
-    def get_node_id(self):
-        """
-        Gets the node ID
-
-        Returns:
-             The node ID
-        """
-
-        return self.node_id
-
-    def get_node_pol_type(self):
-        """
-        Gets the node pattern of life type (enum)
-
-        Returns:
-             The node pattern of life type (enum)
-        """
-
-        return self.node_pol_type
-
-    def get_service_name(self):
-        """
-        Gets the service name
-
-        Returns:
-             The service name
-        """
-
-        return self.service_name
-
-    def get_state(self):
-        """
-        Gets the state (node or service)
-
-        Returns:
-             The state (node or service)
-        """
-
-        return self.state
-        

PRIMAITE/nodes/node_state_instruction_red.py

@@ -1,140 +0,0 @@
-# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.
-"""
-Defines node behaviour for Green PoL
-"""
-
-class NodeStateInstructionRed(object):
-    """
-    The Node State Instruction class
-    """
-
-    def __init__(self, _id, _start_step, _end_step, _target_node_id, _pol_initiator, _pol_type, pol_protocol, _pol_state, _pol_source_node_id, _pol_source_node_service, _pol_source_node_service_state):
-        """
-        Init
-
-        Args:
-            _id: The node state instruction id
-            _start_step: The start step of the instruction
-            _end_step: The end step of the instruction
-            _target_node_id: The id of the associated node
-            -pol_initiator: The way the PoL is applied (DIRECT, IER or SERVICE)
-            _pol_type: The pattern of life type
-            -pol_protocol: The pattern of life protocol/service affected
-            _pol_state: The state (node or service)
-            _pol_source_node_id: The source node Id (used for initiator type SERVICE)
-            _pol_source_node_service: The source node service (used for initiator type SERVICE)
-            _pol_source_node_service_state: The source node service state (used for initiator type SERVICE)
-        """
-
-        self.id = _id
-        self.start_step = _start_step
-        self.end_step = _end_step
-        self.target_node_id = _target_node_id
-        self.initiator = _pol_initiator
-        self.pol_type = _pol_type
-        self.service_name = pol_protocol # Not used when not a service instruction
-        self.state = _pol_state
-        self.source_node_id = _pol_source_node_id
-        self.source_node_service = _pol_source_node_service
-        self.source_node_service_state = _pol_source_node_service_state
-
-    def get_start_step(self):
-        """
-        Gets the start step
-
-        Returns:
-             The start step
-        """
-
-        return self.start_step
-
-    def get_end_step(self):
-        """
-        Gets the end step
-
-        Returns:
-             The end step
-        """
-
-        return self.end_step
-
-    def get_target_node_id(self):
-        """
-        Gets the node ID
-
-        Returns:
-             The node ID
-        """
-
-        return self.target_node_id
-
-    def get_initiator(self):
-        """
-        Gets the initiator
-
-        Returns:
-             The initiator
-        """
-
-        return self.initiator
-
-    def get_pol_type(self):
-        """
-        Gets the node pattern of life type (enum)
-
-        Returns:
-             The node pattern of life type (enum)
-        """
-
-        return self.pol_type
-
-    def get_service_name(self):
-        """
-        Gets the service name
-
-        Returns:
-             The service name
-        """
-
-        return self.service_name
-
-    def get_state(self):
-        """
-        Gets the state (node or service)
-
-        Returns:
-             The state (node or service)
-        """
-
-        return self.state
-
-    def get_source_node_id(self):
-        """
-        Gets the source node id (used for initiator type SERVICE)
-
-        Returns:
-             The source node id
-        """
-
-        return self.source_node_id
-
-    def get_source_node_service(self):
-        """
-        Gets the source node service (used for initiator type SERVICE)
-
-        Returns:
-             The source node service
-        """
-
-        return self.source_node_service
-
-    def get_source_node_service_state(self):
-        """
-        Gets the source node service state (used for initiator type SERVICE)
-
-        Returns:
-             The source node service state
-        """
-
-        return self.source_node_service_state
-        

PRIMAITE/nodes/passive_node.py

@@ -1,37 +0,0 @@
-# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.
-"""
-The Passive Node class (i.e. an actuator)
-"""
-
-from nodes.node import Node
-
-class PassiveNode(Node):
-    """
-    The Passive Node class
-    """
-
-    def __init__(self, _id, _name, _type, _priority, _state, _config_values):
-        """
-        Init
-
-        Args:
-            _id: The node id
-            _name: The name of the node
-            _type: The type of the node
-            _priority: The priority of the node
-            _state: The state of the node
-        """
-
-        # Pass through to Super for now
-        super().__init__(_id, _name, _type, _priority, _state, _config_values)
-
-    def get_ip_address(self):
-        """
-        Gets the node IP address
-
-        Returns:
-             The node IP address
-        """
-
-        # No concept of IP address for passive nodes for now
-        return ""

PRIMAITE/nodes/service_node.py

@@ -1,162 +0,0 @@
-# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.
-"""
-A Service Node (i.e. not an actuator)
-"""
-
-from nodes.active_node import ActiveNode
-from common.enums import *
-
-class ServiceNode(ActiveNode):
-    """
-    ServiceNode class
-    """
-
-    def __init__(self, _id, _name, _type, _priority, _state, _ip_address, _os_state, _file_system_state, _config_values):
-        """
-        Init
-
-        Args:
-            _id: The node id
-            _name: The name of the node
-            _type: The type of the node
-            _priority: The priority of the node
-            _state: The state of the node
-            _ipAddress: The IP address of the node
-            _osState: The operating system state of the node
-            _file_system_state: The file system state of the node
-        """
-
-        super().__init__(_id, _name, _type, _priority, _state, _ip_address, _os_state, _file_system_state, _config_values)
-        self.services = {}
-
-    def add_service(self, _service):
-        """
-        Adds a service to the node
-
-        Args:
-            _service: The service to add
-        """
-
-        self.services[_service.get_name()] = _service
-
-    def get_services(self):
-        """
-        Gets the dictionary of services on this node
-
-        Returns:
-             Dictionary of services on this node
-        """
-
-        return self.services
-
-    def has_service(self, _protocol):
-        """
-        Indicates whether a service is on a node
-
-        Returns:
-             True if service (protocol) is on the node
-        """
-
-        for service_key, service_value in self.services.items():
-            if service_key == _protocol:
-                return True
-            else:
-                pass
-        return False
-
-    def service_running(self, _protocol):
-        """
-        Indicates whether a service is in a running state on the node
-
-        Returns:
-             True if service (protocol) is in a running state on the node
-        """
-
-        for service_key, service_value in self.services.items():
-            if service_key == _protocol:
-                if service_value.get_state() != SOFTWARE_STATE.PATCHING:
-                    return True
-                else:
-                    return False
-            else:
-                pass
-        return False
-
-    def service_is_overwhelmed(self, _protocol):
-        """
-        Indicates whether a service is in an overwhelmed state on the node
-
-        Returns:
-             True if service (protocol) is in an overwhelmed state on the node
-        """
-
-        for service_key, service_value in self.services.items():
-            if service_key == _protocol:
-                if service_value.get_state() == SOFTWARE_STATE.OVERWHELMED:
-                    return True
-                else:
-                    return False
-            else:
-                pass
-        return False
-
-    def set_service_state(self, _protocol, _state):
-        """
-        Sets the state of a service (protocol) on the node
-
-        Args:
-            _protocol: The service (protocol)
-            _state: The state value
-        """
-
-        for service_key, service_value in self.services.items():
-            if service_key == _protocol:
-                # Can't set to compromised if you're in a patching state
-                if (_state == SOFTWARE_STATE.COMPROMISED and service_value.get_state() != SOFTWARE_STATE.PATCHING) or _state != SOFTWARE_STATE.COMPROMISED:
-                    service_value.set_state(_state)
-                else:
-                    # Do nothing
-                    pass
-                if _state == SOFTWARE_STATE.PATCHING:
-                    service_value.patching_count = self.config_values.service_patching_duration
-                else:
-                    # Do nothing
-                    pass
-
-    def set_service_state_if_not_compromised(self, _protocol, _state):
-        """
-        Sets the state of a service (protocol) on the node if the operating state is not "compromised"
-
-        Args:
-            _protocol: The service (protocol)
-            _state: The state value
-        """
-
-        for service_key, service_value in self.services.items():
-            if service_key == _protocol:
-                if service_value.get_state() != SOFTWARE_STATE.COMPROMISED:
-                    service_value.set_state(_state)
-                    if _state == SOFTWARE_STATE.PATCHING:
-                        service_value.patching_count = self.config_values.service_patching_duration
-
-    def get_service_state(self, _protocol):
-        """
-        Gets the state of a service
-
-        Returns:
-             The state of the service
-        """
-
-        for service_key, service_value in self.services.items():
-            if service_key == _protocol:
-                return service_value.get_state()
-
-    def update_services_patching_status(self):
-        """
-        Updates the patching counter for any service that are patching
-        """
-
-        for service_key, service_value in self.services.items():
-            if service_value.get_state() == SOFTWARE_STATE.PATCHING:
-                service_value.reduce_patching_count()
-

PRIMAITE/pol/__init__.py

@@ -1 +0,0 @@
-# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.

PRIMAITE/pol/green_pol.py

@@ -1,230 +0,0 @@
-# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.
-"""
-Implements Pattern of Life on the network (nodes and links)
-"""
-
-from networkx import shortest_path
-
-from common.enums import *
-from nodes.active_node import ActiveNode
-from nodes.service_node import ServiceNode
-
-_VERBOSE = False
-
-def apply_iers(network, nodes, links, iers, acl, step):
-    """
-    Applies IERs to the links (link pattern of life)
-
-    Args:
-        network: The network modelled in the environment
-        nodes: The nodes within the environment
-        links: The links within the environment
-        iers: The IERs to apply to the links
-        acl: The Access Control List
-        step: The step number
-    """
-
-    if _VERBOSE:
-        print("Applying IERs")
-
-    # Go through each IER and check the conditions for it being applied
-    # If everything is in place, apply the IER protocol load to the relevant links
-    for ier_key, ier_value in iers.items():
-        start_step = ier_value.get_start_step()
-        stop_step = ier_value.get_end_step()
-        protocol = ier_value.get_protocol()
-        port = ier_value.get_port()
-        load = ier_value.get_load()
-        source_node_id = ier_value.get_source_node_id()
-        dest_node_id = ier_value.get_dest_node_id()
-
-        # Need to set the running status to false first for all IERs 
-        ier_value.set_is_running(False)
-
-        source_valid = True
-        dest_valid = True
-        acl_block = False
-
-        if step >= start_step and step <= stop_step:
-            # continue --------------------------           
-                
-            # Get the source and destination node for this link
-            source_node = nodes[source_node_id]
-            dest_node = nodes[dest_node_id]
-
-            # 1. Check the source node situation
-            if source_node.get_type() == TYPE.SWITCH:
-                # It's a switch
-                if source_node.get_state() == HARDWARE_STATE.ON and source_node.get_os_state() != SOFTWARE_STATE.PATCHING:
-                    source_valid = True
-                else:
-                    # IER no longer valid
-                    source_valid = False
-            elif source_node.get_type() == TYPE.ACTUATOR:
-                # It's an actuator
-                # TO DO
-                pass
-            else:
-                # It's not a switch or an actuator (so active node)
-                if source_node.get_state() == HARDWARE_STATE.ON and source_node.get_os_state() != SOFTWARE_STATE.PATCHING:
-                    if source_node.has_service(protocol):
-                        if source_node.service_running(protocol) and not source_node.service_is_overwhelmed(protocol):
-                            source_valid = True
-                        else:
-                            source_valid = False
-                    else:
-                        # Do nothing - IER is not valid on this node
-                        # (This shouldn't happen if the IER has been written correctly)
-                        source_valid = False
-                else:
-                    # Do nothing - IER no longer valid
-                    source_valid = False
-
-
-            # 2. Check the dest node situation
-            if dest_node.get_type() == TYPE.SWITCH:
-                # It's a switch
-                if dest_node.get_state() == HARDWARE_STATE.ON and dest_node.get_os_state() != SOFTWARE_STATE.PATCHING:
-                    dest_valid = True
-                else:
-                    # IER no longer valid
-                    dest_valid = False
-            elif dest_node.get_type() == TYPE.ACTUATOR:
-                # It's an actuator
-                pass
-            else:
-                # It's not a switch or an actuator (so active node)
-                if dest_node.get_state() == HARDWARE_STATE.ON and dest_node.get_os_state() != SOFTWARE_STATE.PATCHING:
-                    if dest_node.has_service(protocol):
-                        if dest_node.service_running(protocol) and not dest_node.service_is_overwhelmed(protocol):
-                            dest_valid = True
-                        else:
-                            dest_valid = False
-                    else:
-                        # Do nothing - IER is not valid on this node
-                        # (This shouldn't happen if the IER has been written correctly)
-                        dest_valid = False
-                else:
-                    # Do nothing - IER no longer valid
-                    dest_valid = False
-
-            # 3. Check that the ACL doesn't block it
-            acl_block = acl.is_blocked(source_node.get_ip_address(), dest_node.get_ip_address(), protocol, port)
-            if acl_block:
-                if _VERBOSE:
-                    print("ACL block on source: " + source_node.get_ip_address() + ", dest: " + dest_node.get_ip_address() + ", protocol: " + protocol + ", port: " + port)
-            else:
-                if _VERBOSE:
-                    print("No ACL block")
-
-            # Check whether both the source and destination are valid, and there's no ACL block
-            if source_valid and dest_valid and not acl_block:
-                # Load up the link(s) with the traffic
-
-                if _VERBOSE:
-                    print("Source, Dest and ACL valid")
-
-                # Get the shortest path (i.e. nodes) between source and destination
-                path_node_list = shortest_path(network, source_node, dest_node)
-                path_node_list_length = len(path_node_list)
-                path_valid = True
-
-                # We might have a switch in the path, so check all nodes are operational
-                for node in path_node_list:
-                    if node.get_state() != HARDWARE_STATE.ON or node.get_os_state() == SOFTWARE_STATE.PATCHING:
-                        path_valid = False
-                
-                if path_valid:
-                    if _VERBOSE:
-                        print("Applying IER to link(s)")
-                    count = 0
-                    link_capacity_exceeded = False
-                    
-                    # Check that the link capacity is not exceeded by the new load
-                    while count < path_node_list_length - 1:
-                        # Get the link between the next two nodes
-                        edge_dict = network.get_edge_data(path_node_list[count], path_node_list[count+1])
-                        link_id = edge_dict[0].get('id')
-                        link = links[link_id]
-                        # Check whether the new load exceeds the bandwidth
-                        if (link.get_current_load() + load) > link.get_bandwidth():
-                            link_capacity_exceeded = True
-                            if _VERBOSE:
-                                print("Link capacity exceeded")
-                            pass
-                        count+=1
-
-                    # Check whether the link capacity for any links on this path have been exceeded
-                    if link_capacity_exceeded == False:
-                        # Now apply the new loads to the links
-                        count = 0
-                        while count < path_node_list_length - 1:
-                            # Get the link between the next two nodes
-                            edge_dict = network.get_edge_data(path_node_list[count], path_node_list[count+1])
-                            link_id = edge_dict[0].get('id')
-                            link = links[link_id]
-                            # Add the load from this IER
-                            link.add_protocol_load(protocol, load)
-                            count+=1
-                        # This IER is now valid, so set it to running
-                        ier_value.set_is_running(True)               
-                else:
-                    # One of the nodes is not operational
-                    if _VERBOSE:
-                        print("Path not valid - one or more nodes not operational")
-                    pass
-                
-            else:
-                if _VERBOSE:
-                    print("Source, Dest or ACL were not valid")
-                pass
-            # ------------------------------------
-        else:
-            # Do nothing - IER no longer valid
-            pass
-
-def apply_node_pol(nodes, node_pol, step):
-    """
-    Applies node pattern of life
-
-    Args:
-        nodes: The nodes within the environment
-        node_pol: The node pattern of life to apply
-        step: The step number
-    """
-
-    if _VERBOSE:
-        print("Applying Node PoL")
-    
-    for key, node_instruction in node_pol.items():
-        start_step = node_instruction.get_start_step()
-        stop_step = node_instruction.get_end_step()
-        node_id = node_instruction.get_node_id()
-        node_pol_type = node_instruction.get_node_pol_type()
-        service_name = node_instruction.get_service_name()
-        state = node_instruction.get_state()
-
-        if step >= start_step and step <= stop_step:
-            # continue -------------------------- 
-            node = nodes[node_id]
-
-            if node_pol_type == NODE_POL_TYPE.OPERATING:
-                # Change operating state
-                node.set_state(state)
-            elif node_pol_type == NODE_POL_TYPE.OS:
-                # Change OS state
-                # Don't allow PoL to fix something that is compromised. Only the Blue agent can do this
-                if isinstance(node, ActiveNode) or isinstance(node, ServiceNode):
-                    node.set_os_state_if_not_compromised(state)
-            elif node_pol_type == NODE_POL_TYPE.SERVICE:
-                # Change a service state
-                # Don't allow PoL to fix something that is compromised. Only the Blue agent can do this
-                if isinstance(node, ServiceNode):
-                    node.set_service_state_if_not_compromised(service_name, state)
-            else:
-                # Change the file system status
-                if isinstance(node, ActiveNode) or isinstance(node, ServiceNode):
-                    node.set_file_system_state_if_not_compromised(state)
-        else:
-            # PoL is not valid in this time step
-            pass

PRIMAITE/pol/ier.py

@@ -1,147 +0,0 @@
-# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.
-"""
-Information Exchange Requirements for APE
-Used to represent an information flow from source to destination
-"""
-
-class IER(object):
-    """
-    Information Exchange Requirement class
-    """
-
-    def __init__(self, _id, _start_step, _end_step, _load, _protocol, _port, _source_node_id, _dest_node_id, _mission_criticality, _running=False):
-        """
-        Init
-
-        Args:
-            _id: The IER id
-            _start_step: The step when this IER should start
-            _end_step: The step when this IER should end
-            _load: The load this IER should put on a link (bps)
-            _protocol: The protocol of this IER
-            _port: The port this IER runs on
-            _source_node_id: The source node ID
-            _dest_node_id: The destination node ID
-            _mission_criticality: Criticality of this IER to the mission (0 none, 5 mission critical)
-            _running: Indicates whether the IER is currently running
-        """
-
-        self.id = _id
-        self.start_step = _start_step
-        self.end_step = _end_step
-        self.source_node_id = _source_node_id
-        self.dest_node_id = _dest_node_id
-        self.load = _load       
-        self.protocol = _protocol
-        self.port = _port
-        self.mission_criticality = _mission_criticality
-        self.running = _running
-
-    def get_id(self):
-        """
-        Gets IER ID
-
-        Returns:
-             IER ID
-        """
-
-        return self.id
-
-    def get_start_step(self):
-        """
-        Gets IER start step
-
-        Returns:
-             IER start step
-        """
-
-        return self.start_step
-
-    def get_end_step(self):
-        """
-        Gets IER end step
-
-        Returns:
-             IER end step
-        """
-
-        return self.end_step
-
-    def get_load(self):
-        """
-        Gets IER load
-
-        Returns:
-             IER load
-        """
-
-        return self.load
-
-    def get_protocol(self):
-        """
-        Gets IER protocol
-
-        Returns:
-             IER protocol
-        """
-
-        return self.protocol
-
-    def get_port(self):
-        """
-        Gets IER port
-
-        Returns:
-             IER port
-        """
-
-        return self.port
-
-    def get_source_node_id(self):
-        """
-        Gets IER source node ID
-
-        Returns:
-             IER source node ID
-        """
-
-        return self.source_node_id
-
-    def get_dest_node_id(self):
-        """
-        Gets IER destination node ID
-
-        Returns:
-             IER destination node ID
-        """
-
-        return self.dest_node_id
-
-    def get_is_running(self):
-        """
-        Informs whether the IER is currently running
-
-        Returns:
-             True if running
-        """
-
-        return self.running
-
-    def set_is_running(self, _value):
-        """
-        Sets the running state of the IER
-
-        Args:
-             _value: running status
-        """
-        self.running = _value
-
-    def get_mission_criticality(self):
-        """
-        Gets the IER mission criticality (used in the reward function)
-
-        Returns:
-             Mission criticality value (0 lowest to 5 highest)
-        """
-
-        return self.mission_criticality

PRIMAITE/pol/red_agent_pol.py

@@ -1,301 +0,0 @@
-# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.
-"""
-Implements Pattern of Life on the network (nodes and links) resulting from the red agent attack
-"""
-
-from networkx import shortest_path
-
-from common.enums import *
-from nodes.active_node import ActiveNode
-from nodes.service_node import ServiceNode
-
-_VERBOSE = False
-
-def apply_red_agent_iers(network, nodes, links, iers, acl, step):
-    """
-    Applies IERs to the links (link pattern of life) resulting from red agent attack
-
-    Args:
-        network: The network modelled in the environment
-        nodes: The nodes within the environment
-        links: The links within the environment
-        iers: The red agent IERs to apply to the links
-        acl: The Access Control List
-        step: The step number
-    """
-
-    # Go through each IER and check the conditions for it being applied
-    # If everything is in place, apply the IER protocol load to the relevant links
-    for ier_key, ier_value in iers.items():
-        start_step = ier_value.get_start_step()
-        stop_step = ier_value.get_end_step()
-        protocol = ier_value.get_protocol()
-        port = ier_value.get_port()
-        load = ier_value.get_load()
-        source_node_id = ier_value.get_source_node_id()
-        dest_node_id = ier_value.get_dest_node_id()
-
-        # Need to set the running status to false first for all IERs 
-        ier_value.set_is_running(False)
-
-        source_valid = True
-        dest_valid = True
-        acl_block = False
-
-        if step >= start_step and step <= stop_step:
-            # continue --------------------------           
-                
-            # Get the source and destination node for this link
-            source_node = nodes[source_node_id]
-            dest_node = nodes[dest_node_id]
-
-            # 1. Check the source node situation
-            if source_node.get_type() == TYPE.SWITCH:
-                # It's a switch
-                if source_node.get_state() == HARDWARE_STATE.ON:
-                    source_valid = True
-                else:
-                    # IER no longer valid
-                    source_valid = False
-            elif source_node.get_type() == TYPE.ACTUATOR:
-                # It's an actuator
-                # TO DO
-                pass
-            else:
-                # It's not a switch or an actuator (so active node)
-                if source_node.get_state() == HARDWARE_STATE.ON:
-                    if source_node.has_service(protocol):
-                        # Red agents IERs can only be valid if the source service is in a compromised state
-                        if source_node.get_service_state(protocol) == SOFTWARE_STATE.COMPROMISED:
-                            source_valid = True
-                        else:
-                            source_valid = False
-                    else:
-                        # Do nothing - IER is not valid on this node
-                        # (This shouldn't happen if the IER has been written correctly)
-                        source_valid = False
-                else:
-                    # Do nothing - IER no longer valid
-                    source_valid = False
-
-
-            # 2. Check the dest node situation
-            if dest_node.get_type() == TYPE.SWITCH:
-                # It's a switch
-                if dest_node.get_state() == HARDWARE_STATE.ON:
-                    dest_valid = True
-                else:
-                    # IER no longer valid
-                    dest_valid = False
-            elif dest_node.get_type() == TYPE.ACTUATOR:
-                # It's an actuator
-                pass
-            else:
-                # It's not a switch or an actuator (so active node)
-                if dest_node.get_state() == HARDWARE_STATE.ON:
-                    if dest_node.has_service(protocol):
-                        # We don't care what state the destination service is in for an IER
-                        dest_valid = True
-                    else:
-                        # Do nothing - IER is not valid on this node
-                        # (This shouldn't happen if the IER has been written correctly)
-                        dest_valid = False
-                else:
-                    # Do nothing - IER no longer valid
-                    dest_valid = False
-
-            # 3. Check that the ACL doesn't block it
-            acl_block = acl.is_blocked(source_node.get_ip_address(), dest_node.get_ip_address(), protocol, port)
-            if acl_block:
-                if _VERBOSE:
-                    print("ACL block on source: " + source_node.get_ip_address() + ", dest: " + dest_node.get_ip_address() + ", protocol: " + protocol + ", port: " + port)
-            else:
-                if _VERBOSE:
-                    print("No ACL block")
-
-            # Check whether both the source and destination are valid, and there's no ACL block
-            if source_valid and dest_valid and not acl_block:
-                # Load up the link(s) with the traffic
-
-                if _VERBOSE:
-                    print("Source, Dest and ACL valid")
-
-                # Get the shortest path (i.e. nodes) between source and destination
-                path_node_list = shortest_path(network, source_node, dest_node)
-                path_node_list_length = len(path_node_list)
-                path_valid = True
-
-                # We might have a switch in the path, so check all nodes are operational
-                # We're assuming here that red agents can get past switches that are patching
-                for node in path_node_list:
-                    if node.get_state() != HARDWARE_STATE.ON:
-                        path_valid = False
-              
-                if path_valid:
-                    if _VERBOSE:
-                        print("Applying IER to link(s)")
-                    count = 0
-                    link_capacity_exceeded = False
-
-                    # Check that the link capacity is not exceeded by the new load
-                    while count < path_node_list_length - 1:
-                        # Get the link between the next two nodes
-                        edge_dict = network.get_edge_data(path_node_list[count], path_node_list[count+1])
-                        link_id = edge_dict[0].get('id')
-                        link = links[link_id]
-                        # Check whether the new load exceeds the bandwidth
-                        if (link.get_current_load() + load) > link.get_bandwidth():
-                            link_capacity_exceeded = True
-                            if _VERBOSE:
-                                print("Link capacity exceeded")
-                            pass
-                        count+=1
-
-                    # Check whether the link capacity for any links on this path have been exceeded
-                    if link_capacity_exceeded == False:
-                        # Now apply the new loads to the links
-                        count = 0
-                        while count < path_node_list_length - 1:
-                            # Get the link between the next two nodes
-                            edge_dict = network.get_edge_data(path_node_list[count], path_node_list[count+1])
-                            link_id = edge_dict[0].get('id')
-                            link = links[link_id]
-                            # Add the load from this IER
-                            link.add_protocol_load(protocol, load)
-                            count+=1
-                        # This IER is now valid, so set it to running
-                        ier_value.set_is_running(True)
-                        if _VERBOSE:
-                            print("Red IER was allowed to run in step " + str(step))
-                else:
-                    # One of the nodes is not operational
-                    if _VERBOSE:
-                        print("Path not valid - one or more nodes not operational")
-                    pass
-                
-            else:
-                if _VERBOSE:
-                    print("Red IER was NOT allowed to run in step " + str(step))
-                    print("Source, Dest or ACL were not valid")
-                pass
-            # ------------------------------------
-        else:
-            # Do nothing - IER no longer valid
-            pass
-
-    pass
-
-def apply_red_agent_node_pol(nodes, iers, node_pol, step):
-    """
-    Applies node pattern of life
-
-    Args:
-        nodes: The nodes within the environment
-        iers: The red agent IERs
-        node_pol: The red agent node pattern of life to apply
-        step: The step number
-    """
-
-    if _VERBOSE:
-        print("Applying Node Red Agent PoL")
-    
-    for key, node_instruction in node_pol.items():
-        start_step = node_instruction.get_start_step()
-        stop_step = node_instruction.get_end_step()
-        target_node_id = node_instruction.get_target_node_id()
-        initiator = node_instruction.get_initiator()
-        pol_type = node_instruction.get_pol_type()
-        service_name = node_instruction.get_service_name()
-        state = node_instruction.get_state()
-        source_node_id = node_instruction.get_source_node_id()
-        source_node_service_name = node_instruction.get_source_node_service()
-        source_node_service_state_value = node_instruction.get_source_node_service_state()
-
-        passed_checks = False
-
-        if step >= start_step and step <= stop_step:
-            # continue -------------------------- 
-            target_node = nodes[target_node_id]
-
-            # Based the action taken on the initiator type
-            if initiator == NODE_POL_INITIATOR.DIRECT:
-                # No conditions required, just apply the change
-                passed_checks = True
-            elif initiator == NODE_POL_INITIATOR.IER:
-                # Need to check there is a red IER incoming
-                passed_checks = is_red_ier_incoming(target_node, iers, pol_type)
-            elif initiator == NODE_POL_INITIATOR.SERVICE:
-                # Need to check the condition of a service on another node
-                source_node = nodes[source_node_id]
-                if source_node.has_service(source_node_service_name):
-                    if source_node.get_service_state(source_node_service_name) == SOFTWARE_STATE[source_node_service_state_value]:
-                        passed_checks = True
-                    else:
-                        # Do nothing, no matching state value
-                        pass
-                else:
-                    # Do nothing, service not on this node
-                    pass
-            else:
-                if _VERBOSE:
-                    print("Node Red Agent PoL not allowed - misconfiguration")
-
-            # Only apply the PoL if the checks have passed (based on the initiator type)
-            if passed_checks:
-                # Apply the change
-                if pol_type == NODE_POL_TYPE.OPERATING:
-                    # Change operating state
-                    target_node.set_state(state)
-                elif pol_type == NODE_POL_TYPE.OS:
-                    # Change OS state
-                    if isinstance(target_node, ActiveNode) or isinstance(target_node, ServiceNode):
-                        target_node.set_os_state(state)
-                elif pol_type == NODE_POL_TYPE.SERVICE:
-                    # Change a service state
-                    if isinstance(target_node, ServiceNode):
-                        target_node.set_service_state(service_name, state)
-                else:
-                    # Change the file system status
-                    if isinstance(target_node, ActiveNode) or isinstance(target_node, ServiceNode):
-                        target_node.set_file_system_state(state)
-            else:
-                if _VERBOSE:
-                        print("Node Red Agent PoL not allowed - did not pass checks")
-        else:
-            # PoL is not valid in this time step
-            pass
-
-def is_red_ier_incoming(node, iers, node_pol_type):
-
-    node_id = node.get_id()
-
-    for ier_key, ier_value in iers.items():     
-        if ier_value.get_is_running() and ier_value.get_dest_node_id() == node_id:
-            if node_pol_type == NODE_POL_TYPE.OPERATING or node_pol_type == NODE_POL_TYPE.OS or node_pol_type == NODE_POL_TYPE.FILE:
-                # It's looking to change operating state, file system or O/S state, so valid 
-                return True
-            elif node_pol_type == NODE_POL_TYPE.SERVICE:
-                # Check if the service is present on the node and running
-                ier_protocol = ier_value.get_protocol()
-                if isinstance(node, ServiceNode):
-                    if node.has_service(ier_protocol):
-                        if node.service_running(ier_protocol):
-                            # Matching service is present and running, so valid
-                            return True
-                        else:
-                            # Service is present, but not running
-                            return False
-                    else:
-                        # Service is not present
-                        return False
-                else:
-                    # Not a service node
-                    return False
-            else:
-                # Shouldn't get here - instruction type is undefined
-                return False
-        else:
-            # The IER destination is not this node, or the IER is not running
-            return False
-            
-

PRIMAITE/tests/test_acl.py

@@ -1,105 +0,0 @@
-
-# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.
-"""
-Used to tes the ACL functions
-"""
-
-from acl.acl_rule import ACLRule
-from acl.access_control_list import AccessControlList
-
-def test_acl_address_match_1():
-    """
-    Test that matching IP addresses produce True
-    """
-
-    acl = AccessControlList()
-
-    rule = ACLRule("ALLOW", "192.168.1.1", "192.168.1.2", "TCP", "80")
-
-    assert acl.check_address_match(rule, "192.168.1.1", "192.168.1.2") == True
-
-def test_acl_address_match_2():
-    """
-    Test that mismatching IP addresses produce False
-    """
-
-    acl = AccessControlList()
-
-    rule = ACLRule("ALLOW", "192.168.1.1", "192.168.1.2", "TCP", "80")
-
-    assert acl.check_address_match(rule, "192.168.1.1", "192.168.1.3") == False
-
-def test_acl_address_match_3():
-    """
-    Test the ANY condition for source IP addresses produce True
-    """
-
-    acl = AccessControlList()
-
-    rule = ACLRule("ALLOW", "ANY", "192.168.1.2", "TCP", "80")
-
-    assert acl.check_address_match(rule, "192.168.1.1", "192.168.1.2") == True
-
-def test_acl_address_match_4():
-    """
-    Test the ANY condition for dest IP addresses produce True
-    """
-
-    acl = AccessControlList()
-
-    rule = ACLRule("ALLOW", "192.168.1.1", "ANY", "TCP", "80")
-
-    assert acl.check_address_match(rule, "192.168.1.1", "192.168.1.2") == True
-
-def test_check_acl_block_affirmative():
-    """
-    Test the block function (affirmative)
-    """
-
-    # Create the Access Control List
-    acl = AccessControlList()
-
-    # Create a rule
-    acl_rule_permission = "ALLOW"
-    acl_rule_source = "192.168.1.1"
-    acl_rule_destination = "192.168.1.2"
-    acl_rule_protocol = "TCP"
-    acl_rule_port = "80"
-
-    acl.add_rule(acl_rule_permission, acl_rule_source, acl_rule_destination, acl_rule_protocol, acl_rule_port)
-
-    assert acl.is_blocked("192.168.1.1", "192.168.1.2", "TCP", "80") == False
-
-def test_check_acl_block_negative():
-    """
-    Test the block function (negative)
-    """
-
-    # Create the Access Control List
-    acl = AccessControlList()
-
-    # Create a rule
-    acl_rule_permission = "DENY"
-    acl_rule_source = "192.168.1.1"
-    acl_rule_destination = "192.168.1.2"
-    acl_rule_protocol = "TCP"
-    acl_rule_port = "80"
-
-    acl.add_rule(acl_rule_permission, acl_rule_source, acl_rule_destination, acl_rule_protocol, acl_rule_port)
-
-    assert acl.is_blocked("192.168.1.1", "192.168.1.2", "TCP", "80") == True
-
-def test_rule_hash():
-    """
-    Test the rule hash
-    """
-
-    # Create the Access Control List
-    acl = AccessControlList()
-
-    rule = ACLRule("DENY", "192.168.1.1", "192.168.1.2", "TCP", "80")
-    hash_value_local = hash(rule)
-
-    hash_value_remote = acl.get_dictionary_hash("DENY", "192.168.1.1", "192.168.1.2", "TCP", "80")
-
-    assert hash_value_local == hash_value_remote

PRIMAITE/transactions/__init__.py

@@ -1 +0,0 @@
-# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.

PRIMAITE/transactions/transaction.py

@@ -1,69 +0,0 @@
-# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.
-"""
-The Transaction class
-"""
-
-class Transaction(object):
-    """
-    Transaction class
-    """
-    def __init__(self, _timestamp, _agent_identifier, _episode_number, _step_number):
-        """
-        Init
-
-        Args:
-            _timestamp: The time this object was created
-            _agent_identifier: An identifier for the agent in use
-            _episode_number: The episode number
-            _step_number: The step number        
-        """
-
-        self.timestamp = _timestamp
-        self.agent_identifier = _agent_identifier
-        self.episode_number = _episode_number
-        self.step_number = _step_number      
-
-    def set_obs_space_pre(self, _obs_space_pre):
-        """
-        Sets the observation space (pre)
-
-        Args:
-            _obs_space_pre: The observation space before any actions are taken
-        """
-
-        self.obs_space_pre = _obs_space_pre
-
-    def set_obs_space_post(self, _obs_space_post):
-        """
-        Sets the observation space (post)
-
-        Args:
-            _obs_space_post: The observation space after any actions are taken
-        """
-
-        self.obs_space_post = _obs_space_post
-
-    def set_reward(self, _reward):
-        """
-        Sets the reward
-
-        Args:
-            _reward: The reward value
-        """
-
-        self.reward = _reward
-
-    def set_action_space(self, _action_space):
-        """
-        Sets the action space
-
-        Args:
-            _action_space: The action space invoked by the agent
-        """
-
-        self.action_space = _action_space
-
-
-
-
-

PRIMAITE/transactions/transactions_to_file.py

@@ -1,104 +0,0 @@
-# Crown Copyright (C) Dstl 2022. DEFCON 703. Shared in confidence.
-"""
-Writes the Transaction log list out to file for evaluation to utilse
-"""
-
-import csv
-import logging
-import os.path
-
-from datetime import datetime
-
-from transactions.transaction import Transaction
-
-def turn_action_space_to_array(_action_space):
-    """
-    Turns action space into a string array so it can be saved to csv
-
-    Args:
-        _action_space: The action space
-    """
-
-    return_array = []
-    for x in range(len(_action_space)):
-        return_array.append(str(_action_space[x]))
-
-    return return_array
-
-def turn_obs_space_to_array(_obs_space, _obs_assets, _obs_features):
-    """
-    Turns observation space into a string array so it can be saved to csv
-
-    Args:
-        _obs_space: The observation space
-        _obs_assets: The number of assets (i.e. nodes or links) in the observation space
-        _obs_features: The number of features associated with the asset
-    """
-
-    return_array = []
-    for x in range(_obs_assets):
-        for y in range(_obs_features):
-            return_array.append(str(_obs_space[x][y]))
-
-    return return_array
-
-def write_transaction_to_file(_transaction_list):
-    """
-    Writes transaction logs to file to support training evaluation
-
-    Args:
-        _transaction_list: The list of transactions from all steps and all episodes
-        _num_episodes: The number of episodes that were conducted
-    """
-
-    # Get the first transaction and use it to determine the makeup of the observation space and action space
-    # Label the obs space fields in csv as "OSI_1_1", "OSN_1_1" and action space as "AS_1"
-    # This will be tied into the PrimAITE Use Case so that they make sense
-    template_transation = _transaction_list[0]
-    action_length = template_transation.action_space.size
-    obs_assets = template_transation.obs_space_post.shape[0]
-    obs_features = template_transation.obs_space_post.shape[1]
-
-    # Create the action space headers array   
-    action_header = []
-    for x in range(action_length):
-        action_header.append('AS_' + str(x))
-
-    # Create the observation space headers array
-    obs_header_initial = []
-    obs_header_new = []
-    for x in range(obs_assets):
-        for y in range(obs_features):
-            obs_header_initial.append('OSI_' + str(x) + '_' + str(y))
-            obs_header_new.append('OSN_' + str(x) + '_' + str(y))
-
-    # Open up a csv file
-    header = ['Timestamp', 'Episode', 'Step', 'Reward']
-    header = header + action_header + obs_header_initial + obs_header_new
-    now = datetime.now() # current date and time
-    time = now.strftime("%Y%m%d_%H%M%S")
-
-    try:
-        path = 'outputs/results/'
-        is_dir = os.path.isdir(path)
-        if not is_dir:
-            os.makedirs(path)
-
-        filename = "outputs/results/all_transactions_" + time + ".csv"
-        csv_file = open(filename, 'w', encoding='UTF8', newline='')
-        csv_writer = csv.writer(csv_file)
-        csv_writer.writerow(header)
-
-        for transaction in _transaction_list:
-            csv_data = [str(transaction.timestamp),  str(transaction.episode_number), str(transaction.step_number), str(transaction.reward)]
-            csv_data = csv_data + turn_action_space_to_array(transaction.action_space) + \
-                turn_obs_space_to_array(transaction.obs_space_pre, obs_assets, obs_features) + \
-                turn_obs_space_to_array(transaction.obs_space_post, obs_assets, obs_features)
-            csv_writer.writerow(csv_data)
-
-        csv_file.close()
-    except Exception as e:
-        logging.error("Could not save the transaction file")
-        logging.error("Exception occured", exc_info=True)
-
-

README.md

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

benchmark/benchmark.py

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

benchmark/config/benchmark_training_config.yaml

@@ -0,0 +1,164 @@
+# © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+# Training Config File
+
+# Sets which agent algorithm framework will be used.
+# Options are:
+# "SB3" (Stable Baselines3)
+# "RLLIB" (Ray RLlib)
+# "CUSTOM" (Custom Agent)
+agent_framework: SB3
+
+# Sets which deep learning framework will be used (by RLlib ONLY).
+# Default is TF (Tensorflow).
+# Options are:
+# "TF" (Tensorflow)
+# TF2 (Tensorflow 2.X)
+# TORCH (PyTorch)
+deep_learning_framework: TF2
+
+# Sets which Agent class will be used.
+# Options are:
+# "A2C" (Advantage Actor Critic coupled with either SB3 or RLLIB agent_framework)
+# "PPO" (Proximal Policy Optimization coupled with either SB3 or RLLIB agent_framework)
+# "HARDCODED" (The HardCoded agents coupled with an ACL or NODE action_type)
+# "DO_NOTHING" (The DoNothing agents coupled with an ACL or NODE action_type)
+# "RANDOM" (primaite.agents.simple.RandomAgent)
+# "DUMMY" (primaite.agents.simple.DummyAgent)
+agent_identifier: PPO
+
+# Sets whether Red Agent POL and IER is randomised.
+# Options are:
+# True
+# False
+random_red_agent: False
+
+# The (integer) seed to be used in random number generation
+# Default is None (null)
+seed: null
+
+# Set whether the agent will be deterministic instead of stochastic
+# Options are:
+# True
+# False
+deterministic: False
+
+# Sets what view of the environment the deterministic hardcoded agent has. The default is BASIC.
+# Options are:
+# "BASIC" (The current observation space only)
+# "FULL" (Full environment view with actions taken and reward feedback)
+hard_coded_agent_view: FULL
+
+# Sets How the Action Space is defined:
+# "NODE"
+# "ACL"
+# "ANY" node and acl actions
+action_type: NODE
+
+# observation space
+observation_space:
+  flatten: true
+  components:
+    - name: NODE_LINK_TABLE
+    - name: NODE_STATUSES
+    - name: LINK_TRAFFIC_LEVELS
+
+# Number of episodes for training to run per session
+num_train_episodes: 500
+
+# 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
+
+# Sets how often the agent will save a checkpoint (every n time episodes).
+# Set to 0 if no checkpoints are required. Default is 10
+checkpoint_every_n_episodes: 0
+
+# Time delay (milliseconds) between steps for CUSTOM agents.
+time_delay: 5
+
+# Type of session to be run. Options are:
+# "TRAIN" (Trains an agent)
+# "EVAL" (Evaluates an agent)
+# "TRAIN_EVAL" (Trains then evaluates an agent)
+session_type: TRAIN
+
+# Environment config values
+# The high value for the observation space
+observation_space_high_value: 1000000000
+
+# The Stable Baselines3 learn/eval output verbosity level:
+# Options are:
+# "NONE" (No Output)
+# "INFO" (Info Messages (such as devices and wrappers used))
+# "DEBUG" (All Messages)
+sb3_output_verbose_level: NONE
+
+# Reward values
+# Generic
+all_ok: 0
+# Node Hardware State
+off_should_be_on: -0.001
+off_should_be_resetting: -0.0005
+on_should_be_off: -0.0002
+on_should_be_resetting: -0.0005
+resetting_should_be_on: -0.0005
+resetting_should_be_off: -0.0002
+resetting: -0.0003
+# Node Software or Service State
+good_should_be_patching: 0.0002
+good_should_be_compromised: 0.0005
+good_should_be_overwhelmed: 0.0005
+patching_should_be_good: -0.0005
+patching_should_be_compromised: 0.0002
+patching_should_be_overwhelmed: 0.0002
+patching: -0.0003
+compromised_should_be_good: -0.002
+compromised_should_be_patching: -0.002
+compromised_should_be_overwhelmed: -0.002
+compromised: -0.002
+overwhelmed_should_be_good: -0.002
+overwhelmed_should_be_patching: -0.002
+overwhelmed_should_be_compromised: -0.002
+overwhelmed: -0.002
+# Node File System State
+good_should_be_repairing: 0.0002
+good_should_be_restoring: 0.0002
+good_should_be_corrupt: 0.0005
+good_should_be_destroyed: 0.001
+repairing_should_be_good: -0.0005
+repairing_should_be_restoring: 0.0002
+repairing_should_be_corrupt: 0.0002
+repairing_should_be_destroyed: 0.0000
+repairing: -0.0003
+restoring_should_be_good: -0.001
+restoring_should_be_repairing: -0.0002
+restoring_should_be_corrupt: 0.0001
+restoring_should_be_destroyed: 0.0002
+restoring: -0.0006
+corrupt_should_be_good: -0.001
+corrupt_should_be_repairing: -0.001
+corrupt_should_be_restoring: -0.001
+corrupt_should_be_destroyed: 0.0002
+corrupt: -0.001
+destroyed_should_be_good: -0.002
+destroyed_should_be_repairing: -0.002
+destroyed_should_be_restoring: -0.002
+destroyed_should_be_corrupt: -0.002
+destroyed: -0.002
+scanning: -0.0002
+# IER status
+red_ier_running: -0.0005
+green_ier_blocked: -0.001
+
+# Patching / Reset durations
+os_patching_duration: 5            # The time taken to patch the OS
+node_reset_duration: 5             # The time taken to reset a node (hardware)
+service_patching_duration: 5       # The time taken to patch a service
+file_system_repairing_limit: 5      # The time take to repair the file system
+file_system_restoring_limit: 5      # The time take to restore the file system
+file_system_scanning_limit: 5       # The time taken to scan the file system

benchmark/primaite_benchmark.py

@@ -0,0 +1,200 @@
+# © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+import json
+import shutil
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, Final, Tuple
+
+from report import build_benchmark_md_report
+from stable_baselines3 import PPO
+
+import primaite
+from benchmark import BenchmarkPrimaiteGymEnv
+from primaite.config.load import data_manipulation_config_path
+
+_LOGGER = primaite.getLogger(__name__)
+
+_MAJOR_V = primaite.__version__.split(".")[0]
+
+_BENCHMARK_ROOT = Path(__file__).parent
+_RESULTS_ROOT: Final[Path] = _BENCHMARK_ROOT / "results" / f"v{_MAJOR_V}"
+_VERSION_ROOT: Final[Path] = _RESULTS_ROOT / f"v{primaite.__version__}"
+_SESSION_METADATA_ROOT: Final[Path] = _VERSION_ROOT / "session_metadata"
+
+_SESSION_METADATA_ROOT.mkdir(parents=True, exist_ok=True)
+
+
+class BenchmarkSession:
+    """Benchmark Session class."""
+
+    gym_env: BenchmarkPrimaiteGymEnv
+    """Gym environment used by the session to train."""
+
+    num_episodes: int
+    """Number of episodes to run the training session."""
+
+    episode_len: int
+    """The number of steps per episode."""
+
+    total_steps: int
+    """Number of steps to run the training session."""
+
+    batch_size: int
+    """Number of steps for each episode."""
+
+    learning_rate: float
+    """Learning rate for the model."""
+
+    start_time: datetime
+    """Start time for the session."""
+
+    end_time: datetime
+    """End time for the session."""
+
+    def __init__(
+        self,
+        gym_env: BenchmarkPrimaiteGymEnv,
+        episode_len: int,
+        num_episodes: int,
+        n_steps: int,
+        batch_size: int,
+        learning_rate: float,
+    ):
+        """Initialise the BenchmarkSession."""
+        self.gym_env = gym_env
+        self.episode_len = episode_len
+        self.n_steps = n_steps
+        self.num_episodes = num_episodes
+        self.total_steps = self.num_episodes * self.episode_len
+        self.batch_size = batch_size
+        self.learning_rate = learning_rate
+
+    def train(self):
+        """Run the training session."""
+        # start timer for session
+        self.start_time = datetime.now()
+        model = PPO(
+            policy="MlpPolicy",
+            env=self.gym_env,
+            learning_rate=self.learning_rate,
+            n_steps=self.n_steps,
+            batch_size=self.batch_size,
+            verbose=0,
+            tensorboard_log="./PPO_UC2/",
+        )
+        model.learn(total_timesteps=self.total_steps)
+
+        # end timer for session
+        self.end_time = datetime.now()
+
+        self.session_metadata = self.generate_learn_metadata_dict()
+
+    def _learn_benchmark_durations(self) -> Tuple[float, float, float]:
+        """
+        Calculate and return the learning benchmark durations.
+
+        Calculates the:
+        - Total learning time in seconds
+        - Total learning time per time step in seconds
+        - Total learning time per 100 time steps per 10 nodes in seconds
+
+        :return: The learning benchmark durations as a Tuple of three floats:
+            Tuple[total_s, s_per_step, s_per_100_steps_10_nodes].
+        """
+        delta = self.end_time - self.start_time
+        total_s = delta.total_seconds()
+
+        total_steps = self.batch_size * self.num_episodes
+        s_per_step = total_s / total_steps
+
+        num_nodes = len(self.gym_env.game.simulation.network.nodes)
+        num_intervals = total_steps / 100
+        av_interval_time = total_s / num_intervals
+        s_per_100_steps_10_nodes = av_interval_time / (num_nodes / 10)
+
+        return total_s, s_per_step, s_per_100_steps_10_nodes
+
+    def generate_learn_metadata_dict(self) -> Dict[str, Any]:
+        """Metadata specific to the learning session."""
+        total_s, s_per_step, s_per_100_steps_10_nodes = self._learn_benchmark_durations()
+        self.gym_env.total_reward_per_episode.pop(0)  # remove episode 0
+        return {
+            "total_episodes": self.gym_env.episode_counter,
+            "total_time_steps": self.gym_env.total_time_steps,
+            "total_s": total_s,
+            "s_per_step": s_per_step,
+            "s_per_100_steps_10_nodes": s_per_100_steps_10_nodes,
+            "total_reward_per_episode": self.gym_env.total_reward_per_episode,
+        }
+
+
+def _get_benchmark_primaite_environment() -> BenchmarkPrimaiteGymEnv:
+    """
+    Create an instance of the BenchmarkPrimaiteGymEnv.
+
+    This environment will be used to train the agents on.
+    """
+    env = BenchmarkPrimaiteGymEnv(env_config=data_manipulation_config_path())
+    return env
+
+
+def _prepare_session_directory():
+    """Prepare the session directory so that it is easier to clean up after the benchmarking is done."""
+    # override session path
+    session_path = _BENCHMARK_ROOT / "sessions"
+
+    if session_path.is_dir():
+        shutil.rmtree(session_path)
+
+    primaite.PRIMAITE_PATHS.user_sessions_path = session_path
+    primaite.PRIMAITE_PATHS.user_sessions_path.mkdir(exist_ok=True, parents=True)
+
+
+def run(
+    number_of_sessions: int = 5,
+    num_episodes: int = 1000,
+    episode_len: int = 128,
+    n_steps: int = 1280,
+    batch_size: int = 32,
+    learning_rate: float = 3e-4,
+) -> None:
+    """Run the PrimAITE benchmark."""
+    benchmark_start_time = datetime.now()
+
+    session_metadata_dict = {}
+
+    _prepare_session_directory()
+
+    # run training
+    for i in range(1, number_of_sessions + 1):
+        print(f"Starting Benchmark Session: {i}")
+
+        with _get_benchmark_primaite_environment() as gym_env:
+            session = BenchmarkSession(
+                gym_env=gym_env,
+                num_episodes=num_episodes,
+                n_steps=n_steps,
+                episode_len=episode_len,
+                batch_size=batch_size,
+                learning_rate=learning_rate,
+            )
+            session.train()
+
+            # Dump the session metadata so that we're not holding it in memory as it's large
+            with open(_SESSION_METADATA_ROOT / f"{i}.json", "w") as file:
+                json.dump(session.session_metadata, file, indent=4)
+
+    for i in range(1, number_of_sessions + 1):
+        with open(_SESSION_METADATA_ROOT / f"{i}.json", "r") as file:
+            session_metadata_dict[i] = json.load(file)
+    # generate report
+    build_benchmark_md_report(
+        benchmark_start_time=benchmark_start_time,
+        session_metadata=session_metadata_dict,
+        config_path=data_manipulation_config_path(),
+        results_root_path=_RESULTS_ROOT,
+    )
+
+
+if __name__ == "__main__":
+    run()

benchmark/report.py

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

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

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

benchmark/utils.py

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

diagram/classes.puml

@@ -0,0 +1,521 @@
+@startuml classes
+set namespaceSeparator none
+class "ACLRule" as primaite.acl.acl_rule.ACLRule {
+  dest_ip : str
+  permission
+  port : str
+  protocol : str
+  source_ip : str
+  get_dest_ip() -> str
+  get_permission() -> str
+  get_port() -> str
+  get_protocol() -> str
+  get_source_ip() -> str
+}
+class "AbstractObservationComponent" as primaite.environment.observations.AbstractObservationComponent {
+  current_observation : NotImplementedType, ndarray
+  env : str
+  space : Space
+  structure : List[str]
+  {abstract}generate_structure() -> List[str]
+  {abstract}update() -> None
+}
+class "AccessControlList" as primaite.acl.access_control_list.AccessControlList {
+  acl
+  acl_implicit_permission
+  acl_implicit_rule
+  max_acl_rules : int
+  add_rule(_permission: RulePermissionType, _source_ip: str, _dest_ip: str, _protocol: str, _port: str, _position: str) -> None
+  check_address_match(_rule: ACLRule, _source_ip_address: str, _dest_ip_address: str) -> bool
+  get_dictionary_hash(_permission: RulePermissionType, _source_ip: str, _dest_ip: str, _protocol: str, _port: str) -> int
+  get_relevant_rules(_source_ip_address: str, _dest_ip_address: str, _protocol: str, _port: str) -> Dict[int, ACLRule]
+  is_blocked(_source_ip_address: str, _dest_ip_address: str, _protocol: str, _port: str) -> bool
+  remove_all_rules() -> None
+  remove_rule(_permission: RulePermissionType, _source_ip: str, _dest_ip: str, _protocol: str, _port: str) -> None
+}
+class "AccessControlList_" as primaite.environment.observations.AccessControlList_ {
+  current_observation : ndarray
+  space : MultiDiscrete
+  structure : list
+  generate_structure() -> List[str]
+  update() -> None
+}
+
+class "ActiveNode" as primaite.nodes.active_node.ActiveNode {
+  file_system_action_count : int
+  file_system_scanning : bool
+  file_system_scanning_count : int
+  file_system_state_actual : GOOD
+  file_system_state_observed : REPAIRING, RESTORING, GOOD
+  ip_address : str
+  fixing_count : int
+  software_state
+  software_state : GOOD
+  set_file_system_state(file_system_state: FileSystemState) -> None
+  set_file_system_state_if_not_compromised(file_system_state: FileSystemState) -> None
+  set_software_state_if_not_compromised(software_state: SoftwareState) -> None
+  start_file_system_scan() -> None
+  update_booting_status() -> None
+  update_file_system_state() -> None
+  update_os_patching_status() -> None
+  update_resetting_status() -> None
+}
+class "AgentSessionABC" as primaite.agents.agent_abc.AgentSessionABC {
+  checkpoints_path
+  evaluation_path
+  is_eval : bool
+  learning_path
+  sb3_output_verbose_level : NONE
+  session_path : Union[str, Path]
+  session_timestamp : datetime
+  timestamp_str
+  uuid
+  close() -> None
+  {abstract}evaluate() -> None
+  {abstract}export() -> None
+  {abstract}learn() -> None
+  load(path: Union[str, Path]) -> None
+  {abstract}save() -> None
+}
+
+class "DoNothingACLAgent" as primaite.agents.simple.DoNothingACLAgent {
+}
+class "DoNothingNodeAgent" as primaite.agents.simple.DoNothingNodeAgent {
+}
+class "DummyAgent" as primaite.agents.simple.DummyAgent {
+}
+class "HardCodedACLAgent" as primaite.agents.hardcoded_acl.HardCodedACLAgent {
+  get_allow_acl_rules(source_node_id: int, dest_node_id: str, protocol: int, port: str, acl: AccessControlList, nodes: Dict[str, NodeUnion], services_list: List[str]) -> Dict[int, ACLRule]
+  get_allow_acl_rules_for_ier(ier: IER, acl: AccessControlList, nodes: Dict[str, NodeUnion]) -> Dict[int, ACLRule]
+  get_blocked_green_iers(green_iers: Dict[str, IER], acl: AccessControlList, nodes: Dict[str, NodeUnion]) -> Dict[str, IER]
+  get_blocking_acl_rules_for_ier(ier: IER, acl: AccessControlList, nodes: Dict[str, NodeUnion]) -> Dict[int, ACLRule]
+  get_deny_acl_rules(source_node_id: int, dest_node_id: str, protocol: int, port: str, acl: AccessControlList, nodes: Dict[str, NodeUnion], services_list: List[str]) -> Dict[int, ACLRule]
+  get_matching_acl_rules(source_node_id: str, dest_node_id: str, protocol: str, port: str, acl: AccessControlList, nodes: Dict[str, Union[ServiceNode, ActiveNode]], services_list: List[str]) -> Dict[int, ACLRule]
+  get_matching_acl_rules_for_ier(ier: IER, acl: AccessControlList, nodes: Dict[str, NodeUnion]) -> Dict[int, ACLRule]
+}
+class "HardCodedAgentSessionABC" as primaite.agents.hardcoded_abc.HardCodedAgentSessionABC {
+  is_eval : bool
+  evaluate() -> None
+  export() -> None
+  learn() -> None
+  load(path: Union[str, Path]) -> None
+  save() -> None
+}
+class "HardCodedNodeAgent" as primaite.agents.hardcoded_node.HardCodedNodeAgent {
+}
+class "IER" as primaite.pol.ier.IER {
+  dest_node_id : str
+  end_step : int
+  id : str
+  load : int
+  mission_criticality : int
+  port : str
+  protocol : str
+  running : bool
+  source_node_id : str
+  start_step : int
+  get_dest_node_id() -> str
+  get_end_step() -> int
+  get_id() -> str
+  get_is_running() -> bool
+  get_load() -> int
+  get_mission_criticality() -> int
+  get_port() -> str
+  get_protocol() -> str
+  get_source_node_id() -> str
+  get_start_step() -> int
+  set_is_running(_value: bool) -> None
+}
+class "Link" as primaite.links.link.Link {
+  bandwidth : int
+  dest_node_name : str
+  id : str
+  protocol_list : List[Protocol]
+  source_node_name : str
+  add_protocol(_protocol: str) -> None
+  add_protocol_load(_protocol: str, _load: int) -> None
+  clear_traffic() -> None
+  get_bandwidth() -> int
+  get_current_load() -> int
+  get_dest_node_name() -> str
+  get_id() -> str
+  get_protocol_list() -> List[Protocol]
+  get_source_node_name() -> str
+}
+class "LinkTrafficLevels" as primaite.environment.observations.LinkTrafficLevels {
+  current_observation : ndarray
+  space : MultiDiscrete
+  structure : list
+  generate_structure() -> List[str]
+  update() -> None
+}
+class "Node" as primaite.nodes.node.Node {
+  booting_count : int
+  config_values
+  hardware_state : BOOTING, ON, RESETTING, OFF
+  name : Final[str]
+  node_id : Final[str]
+  node_type : Final[NodeType]
+  priority
+  resetting_count : int
+  shutting_down_count : int
+  reset() -> None
+  turn_off() -> None
+  turn_on() -> None
+  update_booting_status() -> None
+  update_resetting_status() -> None
+  update_shutdown_status() -> None
+}
+class "NodeLinkTable" as primaite.environment.observations.NodeLinkTable {
+  current_observation : ndarray
+  space : Box
+  structure : list
+  generate_structure() -> List[str]
+  update() -> None
+}
+class "NodeStateInstructionGreen" as primaite.nodes.node_state_instruction_green.NodeStateInstructionGreen {
+  end_step : int
+  id : str
+  node_id : str
+  node_pol_type : str
+  service_name : str
+  start_step : int
+  state : Union['HardwareState', 'SoftwareState', 'FileSystemState']
+  get_end_step() -> int
+  get_node_id() -> str
+  get_node_pol_type() -> 'NodePOLType'
+  get_service_name() -> str
+  get_start_step() -> int
+  get_state() -> Union['HardwareState', 'SoftwareState', 'FileSystemState']
+}
+class "NodeStateInstructionRed" as primaite.nodes.node_state_instruction_red.NodeStateInstructionRed {
+  end_step : int
+  id : str
+  initiator : str
+  pol_type
+  service_name : str
+  source_node_id : str
+  source_node_service : str
+  source_node_service_state : str
+  start_step : int
+  state : Union['HardwareState', 'SoftwareState', 'FileSystemState']
+  target_node_id : str
+  get_end_step() -> int
+  get_initiator() -> 'NodePOLInitiator'
+  get_pol_type() -> NodePOLType
+  get_service_name() -> str
+  get_source_node_id() -> str
+  get_source_node_service() -> str
+  get_source_node_service_state() -> str
+  get_start_step() -> int
+  get_state() -> Union['HardwareState', 'SoftwareState', 'FileSystemState']
+  get_target_node_id() -> str
+}
+class "NodeStatuses" as primaite.environment.observations.NodeStatuses {
+  current_observation : ndarray
+  space : MultiDiscrete
+  structure : list
+  generate_structure() -> List[str]
+  update() -> None
+}
+class "ObservationsHandler" as primaite.environment.observations.ObservationsHandler {
+  current_observation
+  registered_obs_components : List[AbstractObservationComponent]
+  space
+  deregister(obs_component: AbstractObservationComponent) -> None
+  describe_structure() -> List[str]
+  from_config(env: 'Primaite', obs_space_config: dict) -> 'ObservationsHandler'
+  register(obs_component: AbstractObservationComponent) -> None
+  update_obs() -> None
+  update_space() -> None
+}
+class "PassiveNode" as primaite.nodes.passive_node.PassiveNode {
+  ip_address
+}
+class "Primaite" as primaite.environment.primaite_env.Primaite {
+  ACTION_SPACE_ACL_ACTION_VALUES : int
+  ACTION_SPACE_ACL_PERMISSION_VALUES : int
+  ACTION_SPACE_NODE_ACTION_VALUES : int
+  ACTION_SPACE_NODE_PROPERTY_VALUES : int
+  acl
+  action_dict : dict, Dict[int, List[int]]
+  action_space : Discrete, Space
+  action_type : int
+  actual_episode_count
+  agent_identifier
+  average_reward : float
+  env_obs : ndarray, tuple
+  episode_av_reward_writer
+  episode_count : int
+  episode_steps : int
+  green_iers : Dict[str, IER]
+  green_iers_reference : Dict[str, IER]
+  lay_down_config
+  links : Dict[str, Link]
+  links_post_blue : dict
+  links_post_pol : dict
+  links_post_red : dict
+  links_reference : Dict[str, Link]
+  max_number_acl_rules : int
+  network : Graph
+  network_reference : Graph
+  node_pol : Dict[str, NodeStateInstructionGreen]
+  nodes : Dict[str, NodeUnion]
+  nodes_post_blue : dict
+  nodes_post_pol : dict
+  nodes_post_red : dict
+  nodes_reference : Dict[str, NodeUnion]
+  num_links : int
+  num_nodes : int
+  num_ports : int
+  num_services : int
+  obs_config : dict
+  obs_handler
+  observation_space : Tuple, Box, Space
+  observation_type
+  ports_list : List[str]
+  red_iers : Dict[str, IER], dict
+  red_node_pol : dict, Dict[str, NodeStateInstructionRed]
+  services_list : List[str]
+  session_path : Final[Path]
+  step_count : int
+  step_info : Dict[Any]
+  timestamp_str : Final[str]
+  total_reward : float
+  total_step_count : int
+  training_config
+  transaction_writer
+  apply_actions_to_acl(_action: int) -> None
+  apply_actions_to_nodes(_action: int) -> None
+  apply_time_based_updates() -> None
+  close() -> None
+  create_acl_action_dict() -> Dict[int, List[int]]
+  create_acl_rule(item: Dict) -> None
+  create_green_ier(item: Dict) -> None
+  create_green_pol(item: Dict) -> None
+  create_link(item: Dict) -> None
+  create_node(item: Dict) -> None
+  create_node_action_dict() -> Dict[int, List[int]]
+  create_node_and_acl_action_dict() -> Dict[int, List[int]]
+  create_ports_list(ports: Dict) -> None
+  create_red_ier(item: Dict) -> None
+  create_red_pol(item: Dict) -> None
+  create_services_list(services: Dict) -> None
+  get_action_info(action_info: Dict) -> None
+  get_observation_info(observation_info: Dict) -> None
+  init_acl() -> None
+  init_observations() -> Tuple[spaces.Space, np.ndarray]
+  interpret_action_and_apply(_action: int) -> None
+  load_lay_down_config() -> None
+  output_link_status() -> None
+  reset() -> np.ndarray
+  reset_environment() -> None
+  reset_node(item: Dict) -> None
+  save_obs_config(obs_config: dict) -> None
+  set_as_eval() -> None
+  step(action: int) -> Tuple[np.ndarray, float, bool, Dict]
+  update_environent_obs() -> None
+}
+class "PrimaiteSession" as primaite.primaite_session.PrimaiteSession {
+  evaluation_path : Optional[Path], Path
+  is_load_session : bool
+  learning_path : Optional[Path], Path
+  session_path : Optional[Path], Path
+  timestamp_str : str, Optional[str]
+  close() -> None
+  evaluate() -> None
+  learn() -> None
+  setup() -> None
+}
+class "Protocol" as primaite.common.protocol.Protocol {
+  load : int
+  name : str
+  add_load(_load: int) -> None
+  clear_load() -> None
+  get_load() -> int
+  get_name() -> str
+}
+class "RLlibAgent" as primaite.agents.rllib.RLlibAgent {
+  {abstract}evaluate() -> None
+  {abstract}export() -> None
+  learn() -> None
+  {abstract}load(path: Union[str, Path]) -> RLlibAgent
+  save(overwrite_existing: bool) -> None
+}
+class "RandomAgent" as primaite.agents.simple.RandomAgent {
+}
+class "SB3Agent" as primaite.agents.sb3.SB3Agent {
+  is_eval : bool
+  evaluate() -> None
+  {abstract}export() -> None
+  learn() -> None
+  save() -> None
+}
+class "Service" as primaite.common.service.Service {
+  name : str
+  fixing_count : int
+  port : str
+  software_state : GOOD
+  reduce_fixing_count() -> None
+}
+class "ServiceNode" as primaite.nodes.service_node.ServiceNode {
+  services : Dict[str, Service]
+  add_service(service: Service) -> None
+  get_service_state(protocol_name: str) -> SoftwareState
+  has_service(protocol_name: str) -> bool
+  service_is_overwhelmed(protocol_name: str) -> bool
+  service_running(protocol_name: str) -> bool
+  set_service_state(protocol_name: str, software_state: SoftwareState) -> None
+  set_service_state_if_not_compromised(protocol_name: str, software_state: SoftwareState) -> None
+  update_booting_status() -> None
+  update_resetting_status() -> None
+  update_services_patching_status() -> None
+}
+class "SessionOutputWriter" as primaite.utils.session_output_writer.SessionOutputWriter {
+  learning_session : bool
+  transaction_writer : bool
+  close() -> None
+  write(data: Union[Tuple, Transaction]) -> None
+}
+class "TrainingConfig" as primaite.config.training_config.TrainingConfig {
+  action_type
+  agent_framework
+  agent_identifier
+  agent_load_file : Optional[str]
+  all_ok : float
+  checkpoint_every_n_episodes : int
+  compromised : float
+  compromised_should_be_good : float
+  compromised_should_be_overwhelmed : float
+  compromised_should_be_patching : float
+  corrupt : float
+  corrupt_should_be_destroyed : float
+  corrupt_should_be_good : float
+  corrupt_should_be_repairing : float
+  corrupt_should_be_restoring : float
+  deep_learning_framework
+  destroyed : float
+  destroyed_should_be_corrupt : float
+  destroyed_should_be_good : float
+  destroyed_should_be_repairing : float
+  destroyed_should_be_restoring : float
+  deterministic : bool
+  file_system_repairing_limit : int
+  file_system_restoring_limit : int
+  file_system_scanning_limit : int
+  good_should_be_compromised : float
+  good_should_be_corrupt : float
+  good_should_be_destroyed : float
+  good_should_be_overwhelmed : float
+  good_should_be_patching : float
+  good_should_be_repairing : float
+  good_should_be_restoring : float
+  green_ier_blocked : float
+  hard_coded_agent_view
+  implicit_acl_rule
+  load_agent : bool
+  max_number_acl_rules : int
+  node_booting_duration : int
+  node_reset_duration : int
+  node_shutdown_duration : int
+  num_eval_episodes : int
+  num_eval_steps : int
+  num_train_episodes : int
+  num_train_steps : int
+  observation_space : dict
+  observation_space_high_value : int
+  off_should_be_on : float
+  off_should_be_resetting : float
+  on_should_be_off : float
+  on_should_be_resetting : float
+  os_patching_duration : int
+  overwhelmed : float
+  overwhelmed_should_be_compromised : float
+  overwhelmed_should_be_good : float
+  overwhelmed_should_be_patching : float
+  patching : float
+  patching_should_be_compromised : float
+  patching_should_be_good : float
+  patching_should_be_overwhelmed : float
+  random_red_agent : bool
+  red_ier_running : float
+  repairing : float
+  repairing_should_be_corrupt : float
+  repairing_should_be_destroyed : float
+  repairing_should_be_good : float
+  repairing_should_be_restoring : float
+  resetting : float
+  resetting_should_be_off : float
+  resetting_should_be_on : float
+  restoring : float
+  restoring_should_be_corrupt : float
+  restoring_should_be_destroyed : float
+  restoring_should_be_good : float
+  restoring_should_be_repairing : float
+  sb3_output_verbose_level
+  scanning : float
+  seed : Optional[int]
+  service_fixing_duration : int
+  session_type
+  time_delay : int
+  from_dict(config_dict: Dict[str, Any]) -> TrainingConfig
+  to_dict(json_serializable: bool) -> Dict
+}
+class "Transaction" as primaite.transactions.transaction.Transaction {
+  action_space : Optional[int]
+  agent_identifier
+  episode_number : int
+  obs_space : str
+  obs_space_description : NoneType, Optional[List[str]], list
+  obs_space_post : Optional[Union['np.ndarray', Tuple['np.ndarray']]]
+  obs_space_pre : Optional[Union['np.ndarray', Tuple['np.ndarray']]]
+  reward : Optional[float], float
+  step_number : int
+  timestamp : datetime
+  as_csv_data() -> Tuple[List, List]
+}
+primaite.agents.hardcoded_abc.HardCodedAgentSessionABC --|> primaite.agents.agent_abc.AgentSessionABC
+primaite.agents.hardcoded_acl.HardCodedACLAgent --|> primaite.agents.hardcoded_abc.HardCodedAgentSessionABC
+primaite.agents.hardcoded_node.HardCodedNodeAgent --|> primaite.agents.hardcoded_abc.HardCodedAgentSessionABC
+primaite.agents.rllib.RLlibAgent --|> primaite.agents.agent_abc.AgentSessionABC
+primaite.agents.sb3.SB3Agent --|> primaite.agents.agent_abc.AgentSessionABC
+primaite.agents.simple.DoNothingACLAgent --|> primaite.agents.hardcoded_abc.HardCodedAgentSessionABC
+primaite.agents.simple.DoNothingNodeAgent --|> primaite.agents.hardcoded_abc.HardCodedAgentSessionABC
+primaite.agents.simple.DummyAgent --|> primaite.agents.hardcoded_abc.HardCodedAgentSessionABC
+primaite.agents.simple.RandomAgent --|> primaite.agents.hardcoded_abc.HardCodedAgentSessionABC
+primaite.environment.observations.AccessControlList_ --|> primaite.environment.observations.AbstractObservationComponent
+primaite.environment.observations.LinkTrafficLevels --|> primaite.environment.observations.AbstractObservationComponent
+primaite.environment.observations.NodeLinkTable --|> primaite.environment.observations.AbstractObservationComponent
+primaite.environment.observations.NodeStatuses --|> primaite.environment.observations.AbstractObservationComponent
+primaite.nodes.active_node.ActiveNode --|> primaite.nodes.node.Node
+primaite.nodes.passive_node.PassiveNode --|> primaite.nodes.node.Node
+primaite.nodes.service_node.ServiceNode --|> primaite.nodes.active_node.ActiveNode
+primaite.common.service.Service --|> primaite.nodes.service_node.ServiceNode
+primaite.acl.access_control_list.AccessControlList --* primaite.environment.primaite_env.Primaite : acl
+primaite.acl.acl_rule.ACLRule --* primaite.acl.access_control_list.AccessControlList : acl_implicit_rule
+primaite.agents.hardcoded_acl.HardCodedACLAgent --* primaite.primaite_session.PrimaiteSession : _agent_session
+primaite.agents.hardcoded_node.HardCodedNodeAgent --* primaite.primaite_session.PrimaiteSession : _agent_session
+primaite.agents.rllib.RLlibAgent --* primaite.primaite_session.PrimaiteSession : _agent_session
+primaite.agents.sb3.SB3Agent --* primaite.primaite_session.PrimaiteSession : _agent_session
+primaite.agents.simple.DoNothingACLAgent --* primaite.primaite_session.PrimaiteSession : _agent_session
+primaite.agents.simple.DoNothingNodeAgent --* primaite.primaite_session.PrimaiteSession : _agent_session
+primaite.agents.simple.DummyAgent --* primaite.primaite_session.PrimaiteSession : _agent_session
+primaite.agents.simple.RandomAgent --* primaite.primaite_session.PrimaiteSession : _agent_session
+primaite.config.training_config.TrainingConfig --* primaite.agents.agent_abc.AgentSessionABC : _training_config
+primaite.config.training_config.TrainingConfig --* primaite.environment.primaite_env.Primaite : training_config
+primaite.environment.observations.ObservationsHandler --* primaite.environment.primaite_env.Primaite : obs_handler
+primaite.environment.primaite_env.Primaite --* primaite.agents.agent_abc.AgentSessionABC : _env
+primaite.environment.primaite_env.Primaite --* primaite.agents.hardcoded_abc.HardCodedAgentSessionABC : _env
+primaite.environment.primaite_env.Primaite --* primaite.agents.sb3.SB3Agent : _env
+primaite.utils.session_output_writer.SessionOutputWriter --* primaite.environment.primaite_env.Primaite : episode_av_reward_writer
+primaite.utils.session_output_writer.SessionOutputWriter --* primaite.environment.primaite_env.Primaite : transaction_writer
+primaite.config.training_config.TrainingConfig --o primaite.nodes.node.Node : config_values
+primaite.nodes.node_state_instruction_green.NodeStateInstructionGreen --* primaite.environment.primaite_env.Primaite
+primaite.nodes.node_state_instruction_red.NodeStateInstructionRed --* primaite.environment.primaite_env.Primaite
+primaite.pol.ier.IER --* primaite.environment.primaite_env.Primaite
+primaite.common.protocol.Protocol --o primaite.links.link.Link
+primaite.links.link.Link --* primaite.environment.primaite_env.Primaite
+primaite.config.training_config.TrainingConfig --o primaite.nodes.active_node.ActiveNode
+primaite.utils.session_output_writer.SessionOutputWriter --> primaite.transactions.transaction.Transaction
+primaite.transactions.transaction.Transaction --> primaite.environment.primaite_env.Primaite
+@enduml

docs/Makefile

@@ -1,12 +1,21 @@
 # Minimal makefile for Sphinx documentation
-#
-
 # You can set these variables from the command line, and also
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = source
-BUILDDIR      = build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+AUTOSUMMARY="source/_autosummary"
+
+# Remove command is different depending on OS
+ifdef OS
+	RM = IF exist $(AUTOSUMMARY) (  RMDIR $(AUTOSUMMARY) /s /q )
+else
+   ifeq ($(shell uname), Linux)
+      RM = rm -rf $(AUTOSUMMARY)
+   endif
+endif
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -14,7 +23,11 @@ help:
 
 .PHONY: help Makefile
 
+clean:
+	$(RM)
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
+%: Makefile | clean
+
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_templates/custom-class-template.rst

@@ -0,0 +1,41 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+..
+    Credit to https://github.com/JamesALeedham/Sphinx-Autosummary-Recursion for the custom templates.
+..
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :show-inheritance:
+   :inherited-members:
+   :special-members: __init__, __call__, __add__, __mul__
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+      :nosignatures:
+   {% for item in methods %}
+      {%- if not item.startswith('_') %}
+      ~{{ name }}.{{ item }}
+      {%- endif -%}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/_templates/custom-module-template.rst

@@ -0,0 +1,73 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+..
+    Credit to https://github.com/JamesALeedham/Sphinx-Autosummary-Recursion for the custom templates.
+..
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Module attributes
+
+   .. autosummary::
+      :toctree:
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :toctree:
+      :nosignatures:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :toctree:
+      :template: custom-class-template.rst
+      :nosignatures:
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. autosummary::
+   :toctree:
+   :template: custom-module-template.rst
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

docs/api.rst

@@ -0,0 +1,21 @@
+:orphan:
+
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+..
+   DO NOT DELETE THIS FILE! It contains the all-important `.. autosummary::` directive with `:recursive:` option, without
+   which API documentation wouldn't get extracted from docstrings by the `sphinx.ext.autosummary` engine. It is hidden
+   (not declared in any toctree) to remove an unnecessary intermediate page; index.rst instead points directly to the
+   package page. DO NOT REMOVE THIS FILE!
+
+    Credit to https://github.com/JamesALeedham/Sphinx-Autosummary-Recursion for the custom templates.
+..
+
+.. autosummary::
+   :toctree: source/_autosummary
+   :template: custom-module-template.rst
+   :recursive:
+
+   primaite

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

@@ -0,0 +1,185 @@
+# © Crown-owned copyright 2023, 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:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import datetime
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+import os
+import shutil
+import sys
+from pathlib import Path
+from typing import Any, List, Optional
+
+import furo  # noqa
+
+sys.path.insert(0, os.path.abspath("../"))
+
+# -- Project information -----------------------------------------------------
+year = datetime.datetime.now().year
+project = "PrimAITE"
+copyright = f"Copyright (C) Defence Science and Technology Laboratory UK 2021 - {year}"
+author = "Defence Science and Technology Laboratory UK"
+
+# The short Major.Minor.Build version
+with open("../src/primaite/VERSION", "r") as file:
+    version = file.readline()
+# The full version, including alpha/beta/rc tags
+release = version
+
+# set global variables
+rst_prolog = f"""
+.. |VERSION| replace::  {release}
+"""
+
+html_title = f"{project} v{release} docs"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.autodoc",  # Core Sphinx library for auto html doc generation from docstrings
+    "sphinx.ext.autosummary",  # Create summary tables for modules/classes/methods etc
+    "sphinx.ext.intersphinx",  # Link to other project's documentation (see mapping below)
+    "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
+    "nbsphinx",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "furo"
+html_static_path = ["_static"]
+html_theme_options = {"globaltoc_collapse": True, "globaltoc_maxdepth": 2}
+html_copy_source = False
+nbsphinx_allow_errors = False  # set to True to take shortcuts
+html_scaled_image_link = False
+
+# make some stuff easier to read
+nbsphinx_prolog = """
+.. raw:: html
+
+    <style>
+        .stderr {
+            color: #000 !important
+        }
+    </style>
+"""
+
+
+def replace_token(app: Any, docname: Any, source: Any):
+    """Replaces a token from the list of tokens."""
+    result = source[0]
+    for key in app.config.tokens:
+        result = result.replace(key, app.config.tokens[key])
+    source[0] = result
+
+
+tokens = {
+    "{VERSION}": release,
+}  # Token VERSION is replaced by the value of the PrimAITE version in the version file
+"""Dict containing the tokens that need to be replaced in documentation."""
+
+
+def notebook_assets(ignored_files: Optional[List[str]] = [], include_file_types: Optional[List[str]] = []) -> Any:
+    """
+    Creates a function to be used with `shutil.copytree`'s `ignore` parameter.
+
+    :param ignored_files: A list of specific file names to ignore. If a file in the directory matches one of these
+    names, it will be excluded from the copy process.
+    :type ignored_files: Optional[List[str]]
+    :param include_file_types: A list of file extensions to include in the copy process. Files that do not match these
+    extensions will be excluded. If this list is empty, all files will be excluded, effectively copying only
+    directories.
+    :type include_file_types: Optional[List[str]]
+    """
+
+    def ignore_items(directory: List[str], contents: List[str]) -> List[str]:
+        """
+        Determines which files and directories should be ignored during the copy process.
+
+        :param directory: The directory being copied.
+        :type directory: str
+        :param contents: A list of contents in the directory.
+        :type contents: List[str]
+        :return: A list of items to exclude from the copy process.
+        :rtype: List[str]
+        """
+        exclude_items = []
+
+        for item in contents:
+            if item in ignored_files:
+                exclude_items.append(item)
+                continue
+
+            if len(include_file_types) > 0:
+                if not any(item.lower().endswith(ext.lower()) for ext in include_file_types) and os.path.isdir(item):
+                    exclude_items.append(item)
+            else:
+                # if we dont specify which files to include, exclude everything
+                exclude_items.append(item)
+
+        # exclude files but not directories
+        return [path for path in exclude_items if not (Path(directory) / path).is_dir()]
+
+    return ignore_items
+
+
+def copy_notebooks_to_docs() -> Any:
+    """
+    Incredibly over-engineered method that copies the notebooks and its assets to a directory within the docs directory.
+
+    This allows developers to create new notebooks without having to worry about updating documentation when
+    a new notebook is included within PrimAITE.
+    """
+    notebook_asset_types = [".ipynb", ".png"]
+    notebook_directories = []
+
+    # find paths where notebooks are contained
+    for notebook in Path("../src/primaite").rglob("*.ipynb"):
+        # add parent path to notebook directory if not already added
+        if notebook.parent not in notebook_directories:
+            notebook_directories.append(notebook.parent)
+
+    # go through the notebook directories and copy the notebooks and extra assets
+    for notebook_parent in notebook_directories:
+        shutil.copytree(
+            src=notebook_parent,
+            dst=Path("source") / "notebooks" / notebook_parent.name,
+            ignore=notebook_assets(include_file_types=notebook_asset_types),
+            dirs_exist_ok=True,
+        )
+
+
+def suppress_log_output():
+    """Sets the log level while building the documentation."""
+    from primaite import _FILE_HANDLER, _LOGGER, _STREAM_HANDLER
+
+    log_level = "WARN"
+
+    _LOGGER.setLevel(log_level)
+    _STREAM_HANDLER.setLevel(log_level)
+    _FILE_HANDLER.setLevel(log_level)
+
+
+def setup(app: Any):
+    """Custom setup for sphinx."""
+    suppress_log_output()
+    copy_notebooks_to_docs()
+    app.add_config_value("tokens", {}, True)
+    app.connect("source-read", replace_token)

docs/index.rst

@@ -0,0 +1,142 @@
+.. only:: comment
+
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+
+Welcome to PrimAITE's documentation
+====================================
+
+What is PrimAITE?
+-----------------
+
+Overview
+^^^^^^^^
+
+The ARCD Primary-level AI Training Environment (**PrimAITE**) provides an effective simulation capability for training and evaluating AI in a cyber-defensive role. It incorporates the functionality required of a primary-level  ARCD environment:
+
+- The ability to model a relevant system context;
+- Modelling an adversarial agent that the defensive agent can be trained and evaluated against;
+- The ability to model key characteristics of a system by representing hosts, servers, network devices, IP addresses, ports, operating systems, folders / files, applications, services and links;
+- Modelling background (green) pattern-of-life;
+- Operates at machine-speed to enable fast training cycles via Reinforcement Learning (RL).
+
+Features
+^^^^^^^^
+
+PrimAITE incorporates the following features:
+
+- Architected with a separate Simulation layer and Game layer. This separation of concerns defines a clear path towards transfer learning with environments of differing fidelity;
+- Ability to reconfigure an RL reward function based on (a) the ability to counter the modelled adversarial cyber-attack, and (b) the ability to ensure success for green agents;
+- Access Control List (ACL) functions for network devices (routers and firewalls), following standard ACL rule format (e.g., DENY / ALLOW, source / destination IP addresses, protocol and port);
+- Application of traffic to the links of the system laydown adheres to the ACL rulesets and routing tables contained within each network device;
+- Provides RL environments adherent to the Farama Foundation Gymnasium (Previously OpenAI Gym) API, allowing integration with any compliant RL Agent frameworks;
+- Provides RL environments adherent to Ray RLlib environment specifications for single-agent and multi-agent scenarios;
+- Assessed for compatibility with Stable-Baselines3 (SB3), Ray RLlib, and bespoke agents;
+- Persona-based adversarial (Red) agent behaviour; several out-the-box personas are provided, and more can be developed to suit the needs of the task. Stochastic variations in Red agent behaviour are also included as required;
+- A robust system logging tool, automatically enabled at the node level and featuring various log levels and terminal output options, enables PrimAITE users to conduct in-depth network simulations;
+- A PCAP service is seamlessly integrated within the simulation, automatically capturing and logging frames for both
+  inbound and outbound traffic at the network interface level. This automatic functionality, combined with the ability
+  to separate traffic directions, significantly enhances network analysis and troubleshooting capabilities;
+- Agent action logs provide a description of every action taken by each agent during the episode. This includes timestep, action, parameters, request and response, for all Blue agent activity, which is aligned with the Track 2 Common Action / Observation Space (CAOS) format. Action logs also details of all scripted / stochastic red / green agent actions;
+- Environment ground truth is provided at every timestep, providing a full description of the environment’s true state;
+- Alignment with CAOS provides the ability to transfer agents between CAOS compliant environments.
+
+Architecture
+^^^^^^^^^^^^
+
+PrimAITE is a Python application and will operate on multiple Operating Systems (Windows, Linux and Mac);
+a comprehensive installation and user guide is provided with each release to support its usage.
+
+Configuration of PrimAITE is achieved via included YAML files which support full control over the network / system laydown being modelled, background pattern of life, adversarial (red agent) behaviour, and step and episode count.
+A Simulation Controller layer manages the overall running of the simulation, keeping track of all low-level objects.
+
+It is agnostic to the number of agents, their action / observation spaces, and the RL library being used.
+
+It presents a public API providing a method for describing the current state of the simulation, a method that accepts action requests and provides responses, and a method that triggers a timestep advancement.
+The Game Layer converts the simulation into a playable game for the agent(s).
+
+It translates between simulation state and Gymnasium.Spaces to pass action / observation data between the agent(s) and the simulation. It is responsible for calculating rewards, managing Multi-Agent RL (MARL) action turns, and via a single agent interface can interact with Blue, Red and Green agents.
+
+Agents can either generate their own scripted behaviour or accept input behaviour from an RL agent.
+
+Finally, a Gymnasium / Ray RLlib Environment Layer forwards requests to the Game Layer as the agent sends them. This layer also manages most of the I/O, such as reading in the configuration files and saving agent logs.
+
+.. image:: ../../_static/primAITE_architecture.png
+    :width: 500
+    :align: center
+
+
+Training & Evaluation Capability
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+PrimAITE provides a training and evaluation capability to AI agents in the context of cyber-attack, via its Gymnasium / Ray RLlib compliant interface.
+
+Scenarios can be constructed to reflect network / system laydowns consisting of any configuration of nodes (e.g., PCs, servers etc.) and the networking equipment and links between them.
+
+All nodes can be configured to contain applications, services, folders and files (and their status).
+
+Traffic flows between services and applications as directed by an ‘execution definition,’ with the traffic flow on the network governed by the network equipment (switches, routers and firewalls) and the ACL rules and routing tables they employ.
+
+Highlights of PrimAITE’s training and evaluation capability are:
+
+- The scenario is not bound to a representation of any platform, system, or technology;
+- Fully configurable (network / system laydown, green pattern-of-life, red personas, reward function, ACL rules for each device, number of episodes / steps, action / observation space) and repeatable to suit the requirements of AI agents;
+- Can integrate with any Gymnasium / Ray RLlib compliant AI agent .
+
+
+PrimAITE provides a number of use cases (network and red/green action configurations) by default which the user is able to extend and modify as required.
+
+What is PrimAITE built with
+---------------------------
+
+* `Gymnasium <https://gymnasium.farama.org/>`_ is used as the basis for AI blue agent interaction with the PrimAITE environment
+* `Networkx <https://github.com/networkx/networkx>`_ is used as the underlying data structure used for the PrimAITE environment
+* `Stable Baselines 3 <https://github.com/DLR-RM/stable-baselines3>`_ is used as a default source of RL algorithms (although PrimAITE is not limited to SB3 agents)
+* `Ray RLlib <https://github.com/ray-project/ray>`_ is used as an additional source of RL algorithms
+* `Typer <https://github.com/tiangolo/typer>`_ is used for building CLIs (Command Line Interface applications)
+* `Jupyterlab <https://github.com/jupyterlab/jupyterlab>`_ is used as an extensible environment for interactive and reproducible computing, based on the Jupyter Notebook Architecture
+* `Platformdirs <https://github.com/platformdirs/platformdirs>`_ is used for finding the right location to store user data and configuration but varies per platform
+* `Plotly <https://github.com/plotly/plotly.py>`_ is used for building high level charts
+
+
+Getting Started with PrimAITE
+-----------------------------
+
+Head over to the :ref:`getting-started` page to install and setup PrimAITE!
+
+.. toctree::
+   :maxdepth: 8
+   :caption: About PrimAITE:
+   :hidden:
+
+   source/about
+   source/dependencies
+   source/glossary
+
+.. toctree::
+   :caption: Usage:
+   :hidden:
+
+   source/getting_started
+   source/simulation
+   source/game_layer
+   source/config
+   source/environment
+   source/customising_scenarios
+   source/varying_config_files
+
+.. toctree::
+   :caption: Notebooks:
+   :hidden:
+
+   source/example_notebooks
+   source/notebooks/executed_notebooks
+
+.. toctree::
+   :caption: Developer information:
+   :hidden:
+
+   source/developer_tools
+   source/state_system
+   source/request_system
+   PrimAITE API <source/_autosummary/primaite>
+   PrimAITE Tests <source/_autosummary/tests>

docs/make.bat

@@ -1,5 +1,7 @@
 @ECHO OFF
 
+setlocal EnableDelayedExpansion
+
 pushd %~dp0
 
 REM Command file for Sphinx documentation
@@ -7,8 +9,10 @@ REM Command file for Sphinx documentation
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
-set SOURCEDIR=source
-set BUILDDIR=build
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+set AUTOSUMMARYDIR="%cd%\source\_autosummary\"
 
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
@@ -25,11 +29,25 @@ if errorlevel 9009 (
 
 if "%1" == "" goto help
 
+REM delete autosummary if it exists
+
+IF EXIST %AUTOSUMMARYDIR% (
+    echo deleting %AUTOSUMMARYDIR%
+    RMDIR %AUTOSUMMARYDIR% /s /q
+)
+
+
 %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 goto end
 
 :help
 %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 
+:clean
+IF EXIST %AUTOSUMMARYDIR% (
+    echo deleting %AUTOSUMMARYDIR%
+    RMDIR %AUTOSUMMARYDIR% /s /q
+)
+
 :end
 popd

docs/source/about.rst

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

docs/source/config.rst

@@ -0,0 +1,41 @@
+.. only:: comment
+
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+
+PrimAITE |VERSION| Configuration
+********************************
+
+PrimAITE uses YAML configuration files to define everything needed to create the training environment for RL agents, including the network, the scripted agents, and the RL agent's action space, observation space, and reward function.
+
+Example Configuration Hierarchy
+###############################
+The top level configuration items in a configuration file is as follows
+
+.. code-block:: yaml
+
+    io_settings:
+    ...
+    game:
+    ...
+    agents:
+    ...
+    simulation:
+    ...
+
+These are expanded upon in the Configurable items section below
+
+Configurable items
+##################
+
+.. toctree::
+   :maxdepth: 1
+
+   configuration/io_settings.rst
+   configuration/game.rst
+   configuration/agents.rst
+   configuration/simulation.rst
+
+Varying The Configuration Each Episode
+######################################
+
+PrimAITE allows for the configuration to be varied each episode. This is done by specifying a configuration folder instead of a single file. A full explanation is provided in the notebook `Using-Episode-Schedules.ipynb`. Please find the notebook in the user notebooks directory.