v4.0.0

PrimAITE 4.0.0 Release Note

📰 Headlines 📰

• Major Release - Users are encouraged to also familiarise themselves with what's new in PrimAITE 3.0.0.
• Plugins - PrimAITE now supports external plugins to extend existing functionality, such as new node types, services, applications, agent types, observations, actions, and rewards.
• Improved config schema - The YAML config files have a new schema which simplifies the definition of agents by using named references in actions and observations instead of id references.
• Use Case 7 - Introduction of much larger UC7 network with example notebooks and config files.

✨ What's new ✨

• Use Case 7 is a new pre-defined scenario in PrimAITE with a more complex set of nodes that demonstrates some of the new capabilities of PrimAITE 4.
• Threat Actor Profiles are a new type of malicious scripted agent:
  • Extensible base class that allows defining a multi-stage kill chain with success conditions and network knowledge tracking.
  • TAP001 agent - agent that exfiltrates and corrupts data from a database.
  • TAP003 agent - agent that maliciously introduces ACL rules to a network to disrupt normal users.
• Users, Terminals, SSH, and Command&Control (introduced in PrimAITE 3.3).
• Determinism Support for determinism by setting and logging randomness seeds.
• Action Masking (introduced in 3.2.0).
• MARL support (introduced in 3.0.0).
• Logging was improved by adding the following:
  • detailed information about agent actions, decisions, and rewards.
  • the full state of the simulation after each environment step.
  • sys logs for each node.
  • pcap logs for each network interface.
• Domain Randomisation - the Gym environment can use different variations of the same scenario, alternating between them each episode by providing a folder of YAML files instead of a single file at initialisation.

👍 General Improvements 👍

• The organisation of the codebase has been improved by splitting long files into smaller ones.
• Agent logs can now show observation history and more detail about the reward.
• Some classes' .show() methods now show more useful or correct information (like agents, and networks).
• More example notebooks and introduction of how-to guides in the Sphinx docs.
• Ability to set scenario-wide default values for certain actions like scan, node power-off, node start-up, etc.
• It's now easier to build complex networks with the new, extensible NetworkNodeAdder class.
• NMAP application.
• The YAML config files:
  • support extended classes from plugins
  • information has been deduplicated - actions no longer rely on IDs, instead users can specify meaningful labels.
  • more objects have default values so there is less boilerplate.
  • the way agent settings are defined has been standardised.
  • more data validation was added to catch configuration errors earlier.
  • PrimAITE 3 to PrimAITE 4 YAML migration guide.
• Observations can be configured to not require a scan action to show the true health state of software or files.

🐛 Bug Fixes 🐛

•   DNS client no longer fails to check its cache if a DNS server address is missing.
•   DNS client now correctly inherits the node's DNS address configuration setting.
•   ACL observations now include the ACL at index 0.
•   SoftwareManager show method correctly displays all the software associated with a port whether the software is listening or not.

🚦 Tests

This release was checked against specified unit/integration test suite across Windows, Linux and MacOS with Python 3.9-3.11.

⌛ Deprecated ⌛

PrimAITE can no longer be used with Ray versions < 2.32.

⚠️ Breaking Changes ⚠️

This is a major release so many classes and methods have changed as well as the config files. See the documentation for further details of API changes and YAML Migration Guide for config updates.

🔍 Known Issues 🔍

• Action Masking - There is a known issue with the API stack for Ray RLlib affecting the saving of RL policies. A suggested workaround can be found on this issue ticket.
• 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.
• Determinism - Ray RLLib MultiAgent environments are not reproducing identical training runs even after setting random seeds in PrimAITE. This might be caused by the spawning of multiple threads for the RL algorithm.
• Random Number Generators (RNG) with different devices - When using StableBaselines3, different results will be generated for the same seed if trained on a CPU vs a GPU. For example: WSL will perform training on the CPU but Windows will attempt to train on a graphics card if possible. In the notebook Training-an-SB3-Agent add the following argument to the PPO command (cells 6 and 9): device=cpu,  to force training on the CPU rather than GPU. NB: This can impact training times. This issue has not been observed with Single Agent Ray RLLib training.
• NMNE - when using NMNE, both config parameters include_nmne and  capture_nmne must be set to the same Boolean value.

⬆️ Upgrade Instructions ⬆️

From GitHub

pip install git+https://github.com/Autonomous-Resilient-Cyber-Defence/primaite@v4.0.0#egg=primaite

From wheel

pip install path/to/primaite-4.0.0-wheel.whl[rl] --upgrade

As a repo

git clone https://github.com/Autonomous-Resilient-Cyber-Defence/primaite
cd PrimAITE/
git fetch
git checkout tags/v4.0.0
pip install -e .[rl] --upgrade

👥 Contributors 👥

@pufferfish-seaweed
@CharlieC-QQ
@MethodsGRS
@jamesshort1
@njtodd
@marek-methods
@ChrisMcCarthyDev
@CGenes-Methods

📚 References 📚

• PrimAITE 4.0.0 is compatible with Common Action and Observation Space (CAOS) v 0.10.3, a copy of which has been provided with this release.

The Common Action / Observation Space (CAOS) defines a common language for agents to adopt when interacting with PrimAITE and potential other environments. It consists of an evolving definition of Blue, Green and Red Agent Action and Observation Spaces compatible with the MITRE frameworks and is employed to define an agent-environment interface. CAOS was born out of a necessity for environments to speak ‘one language’ with external agents; this is essential to support the transfer of agents that have undergone training in a simulator, and then require evaluation or demonstration in a higher fidelity environment.