73 lines
4.5 KiB
ReStructuredText
73 lines
4.5 KiB
ReStructuredText
.. only:: comment
|
|
|
|
© Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
|
|
|
|
.. _about:
|
|
|
|
About PrimAITE
|
|
==============
|
|
|
|
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), including a powerful terminal simulation for SSH tunnelling and remote command execution.
|
|
|
|
Realistic network traffic generated by software or by users. Packets move through the network devices (switches, routers, firewalls, network interfaces) in accordance to control rules such as: internet protocols, Access control lists (ACLs), and routing tables.
|
|
|
|
Highlights of PrimAITE's training and evaluation capability are:
|
|
|
|
- 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;
|
|
- Domain randomisation through stochastic agent behaviour and the ability to switch between scenario variants between environment episodes.
|
|
- Extensible through plugins to model any network behaviour.
|
|
- 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
|
|
* `Pydantic <https://docs.pydantic.dev/latest/>`_ is used for data validation
|
|
* `Platformdirs <https://github.com/platformdirs/platformdirs>`_ is used for storing user data and configuration correctly between platforms
|
|
* `Typer <https://github.com/tiangolo/typer>`_ is used for the Command Line Interface
|
|
* `Jupyterlab <https://github.com/jupyterlab/jupyterlab>`_ is used as an extensible environment for interactive and reproducible computing, based on the Jupyter Notebook Architecture
|
|
* `Plotly <https://github.com/plotly/plotly.py>`_ is used for building high level charts
|
|
* `Stable Baselines 3 <https://github.com/DLR-RM/stable-baselines3>`_ is used for ensuring compatibility with RL libraries
|
|
* `Ray RLlib <https://github.com/ray-project/ray>`_ is also used for ensuring compatibility with RL libraries
|
|
|
|
|
|
Getting Started with PrimAITE
|
|
-----------------------------
|
|
|
|
Head over to the :ref:`getting-started` page to install and setup PrimAITE!
|