v3.0.0

PrimAITE v3.0.0

PrimAITE was rebuilt from the ground up. This release note is aimed at users of PrimAITE 2 to highlight the key changes and new concepts. However, both new and returning users are encouraged to read the docs and example notebooks because of the magnitude of changes since the last release.

✨ What's New

High-level software architecture

• PrimAITE now consists of a standalone network simulation and a game layer which sits on top of the simulation and turns it into an environment for training RL agents.
• Request and State - The game layer receives simulation data via the state interface, and it sends agents' actions via the request interface. Refer to the docs for a full description.
• Common Action and Observation Space (CAOS) - PrimAITE 3.0.0 adheres to CAOS v0.8 specification.
• Multi-agents - Red, green, and blue agents all inherit from the same interface, allowing arbitrarily many scripted and RL agents.
• Pydantic - PrimAITE uses Pydantic throughout for type safety

Simulation

• Fidelity - PrimAITE has the ability to model layers 1-5 of the OSI networking model.
• Packets - Network traffic consists of packets with realistic headers.
• Routers, switches, and firewalls contain internal logic such as ARP tables, route tables, and ACLs.
• Software - Software on nodes can generate network traffic, respond to actions, and interact with other software and files.
• File system - Host nodes now have a file system with folders and files.

Game Layer

• Agents - The game layer now contains red and green agents which displace the previous notions of IERs and PoL. Agents are classes with custom logic for selection CAOS actions in response to observations.
• Actions - Agent actions are interpreted as a simulation request. Agents receive a request response with a success status and data generated by the action.
• Observations - Blue agent observations are configured hierarchically and they are based on the state interface of the simulation. Agents can have a view over everything or they can be specialised to see certain parts of the network.
• Rewards - Red, green, and blue agents all support rewards, which can take into account the simulation state, and the agent's past actions. Agents' rewards can also contribute to other agents' rewards.

Configuration

• Schema - There is a new schema for configuring PrimAITE scenarios. This is explained in the full documentation.
• Episode schedule - Curriculum learning and enhanced domain randomisation is possible by creating variations around a base config that change between episodes. This is achieved by creating a folder containing a base config with placeholders and files with options for populating those placeholders. The user specifies a schedule listing which placeholders to use in each episode. This allows for training defensive agents against a variety of red agents, green agent behaviours, or even different network layouts.

Running PrimAITE

• Notebooks - New Jupyter notebooks have been provided to demonstrate examples of agent training, saving, loading, and evaluation using SB3 and Ray RLLib. These displace the Session module from PrimAITE 2 - PrimAITE 3 focuses purely on providing an RL environment, not any training / evaluation infrastructure.
• Support - As a pure Python package, PrimAITE supports Windows, Linux, and MacOS.

🐞 Bug Fixes

The bugs present in PrimAITE 2 are no longer present as a result of the software rewrite. This includes:
Transaction CSV incorrect headers - PrimAITE 3 logging no longer uses a CSV file for transactions, however agent action history and step-wise environment state can be logged which provides the same information.

PrimAITE not installing on Mac Sonoma 14.2.1 - MacOS installation success is assured as part of the CI builds that are part of PrimAITE development cadence.

ACL action filtering incorrect with implicit ALLOW - the ACL system has been rewritten to work with the new node system. This has been fixed.

Traffic always blocked - This bug was caused by inconsistent data type handling in PrimAITE 2. PrimAITE 3 is using Pydantic to avoid issues like this. This has been fixed.

Documentation not rendering properly - The documentation is not currently hosted online but it can be built locally.

🔨 Breaking Changes

Code and configuration files written for PrimAITE 2 are not compatible with PrimAITE 3.

♻️ Refactoring

Since the software was rewritten, there are too many refactoring items to list here, but the software structure is described in the documentation.

🚦 Tests

📚 Docs

Rendered sphinx docs are attached to the PrimAITE 3.0.0 GitHub release page. Users can also build the docs manually after installing PrimAITE by running the following:

cd docs
make html

• User guide and developer docs - The user guide, developer docs, and API reference have been updated to reflect the new codebase.
• Jupyter notebooks - Several notebooks are provided with example usage, and explanations of new features. Upon installation, these are copied to the user data directory (~/primaite/3.0.0/notebooks) for running interactively. Static versions of the notebooks are also available within the sphinx documentation.

⚡️ Performance Notes

Users should note that the heavy demands made on CPU and RAM by some PrimAITE activities, particularly when a complex scenario is modelled, may result in other applications running slower than they would on an otherwise unloaded system.

⚠️ Known Issues

• Bandwidth - Link bandwidth has been disabled; links are able to transmit an unlimited amount of data each step. Therefore, it is not possible to model certain types of denial of service attacks. The link bandwidth is only used for observations to report percent utilisation, but if the load exceeds bandwidth, they are treated as 100% loading.
• Agent actions - Agents action spaces must use the gymnasium.spaces.Discrete shape, and a list of actions must be provided using the action_map config option for each agent. Other action spaces and more flexible action space definition will be part of a future release.
• Open file limit exceeded - On certain platforms, loggers might open too many file descriptors. This can be circumvented by increasing the open file limit (such as by using ulimit -n 9999 on linux), or by disabling PCAP logs via the config.

💫 Getting started

Installing from wheel

• On Linux, create your virtual environment and install PrimAITE:

  python -m venv path-to-your/venv
  source path-to-your/venv/bin/activate
  pip install path-to-your/primaite-3.0.0-wheel.whl[rl]
  primaite setup
  

• On Windows, create your virtual environment and install PrimAITE:

  python -m venv path-to-your\venv
  path-to-your\venv\Scripts\Activate.ps1
  pip install path-to-your\primaite-3.0.0-wheel.whl[rl]
  primaite setup

Installing from repository

• On Linux, clone PrimAITE, and install:

  git clone https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE.git --branch v3.0.0
  cd PrimAITE
  python -m venv venv
  source venv/bin/activate
  pip install -e .[rl]
  primaite setup

• On Windows, clone PrimAITE, and install

  git clone https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE.git --branch v3.0.0
  cd PrimAITE
  python -m venv venv
  venv\bin\Activate.ps1
  pip install -e .[rl]
  primaite setup

🛠 Engineering Notes

• After installing PrimAITE, if you wish to run in dev mode, run the following commands:

  pip install -e .[rl,dev]
  primaite setup
  primaite mode dev

  This overrides logging options to output logs to the project directory instead of the user data directory.

Contributors

@pufferfish-seaweed
@CharlieC-QQ
@czar-ec-envitia
@ChrisMcCarthyDev
@njtodd
@marek-methods