98617981d7
# PrimAITE 4.0.0 Release Note ## 📰 Headlines 📰 * **Major Release** - This is the first major release of PrimAITE that has been published since PrimAITE 2.0.0. Users are encouraged to also familiarise themselves with [what's new in PrimAITE 3.0.0](todo: 3.0 release note link). * **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** were [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 va...
PrimAITE
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
Whilst PrimAITE ships with a number of example modelled scenarios (a.k.a. Use Cases), it has not been developed to mandate the solving of a single cyber challenge, and instead provides a highly flexible environment application that can be extended and reconfigured by the user to suit their specific cyber defence training and evaluation needs. PrimAITE provides default networks, red agent and green agent behaviour, reward functions, and action / observation space configuration, all of which can be utilised out of the box, but which ultimately can (and in some instances should) be built upon and / or reconfigured to meet the needs of different defensive agent developers. The PrimAITE user guide provides comprehensive instruction on all PrimAITE features, functionality and components, and can be consulted in order to help guide users in any reconfiguration or enhancements they wish to undertake; a library of example Jupyter notebooks are also provided to support such work.
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.9 < 3.12
Install:
mkdir ~\primaite
cd ~\primaite
python3 -m venv .venv
attrib +h .venv /s /d # Hides the .venv directory
.\.venv\Scripts\activate
pip install primaite-{VERSION}-py3-none-any.whl[rl]
primaite setup
Unix
Prerequisites:
- Manual install of Python >= 3.8 < 3.12
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:
mkdir ~/primaite
cd ~/primaite
python3 -m venv .venv
source .venv/bin/activate
pip install primaite-{VERSION}-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
git clone git@github.com:Autonomous-Resilient-Cyber-Defence/PrimAITE.git
2. CD into the repo directory
cd PrimAITE
3. Create a new python virtual environment (venv)
python3 -m venv venv
4. Activate the venv
Unix
source venv/bin/activate
Windows (Powershell)
.\venv\Scripts\activate
5. Install primaite with the dev extra into the venv along with all of it's dependencies
python3 -m pip install -e .[dev,rl]
6. Perform the PrimAITE setup:
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)
.\venv\Scripts\activate
Unix
source venv/bin/activate
2. Open jupyter notebook
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
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
cd docs
make html
Windows (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.