9835b31dc5
## Description: This pull request introduces the Firewall class and extends the ACLRule functionality within PrimAITE to provide comprehensive network traffic management and security capabilities. These enhancements enable detailed control over data flow through network simulations, mimicking real-world firewall operations and ACL configurations. The updates focus on the addition of a Firewall node that extends the Router class functionalities and the enhancement of ACLRule to support IP ranges through wildcard masking, thus offering granular traffic filtering based on IP addresses, protocols, ports, and more. ## Key Features: **Firewall Class:** A new class that extends the Router class, incorporating firewall-specific logic for inspecting, directing, and filtering traffic between the internal, external, and DMZ (De-Militarized Zone) network interfaces. The Firewall class supports configuring network interfaces and applying Access Control Lists (ACLs) for inbound and outbound traffic control. **Enhanced ACLRule:** The ACLRule class has been updated to support IP ranges using wildcard masking. This allows for more flexible rule definitions, enabling users to specify broad network ranges or individual IP addresses in ACL rules. **Comprehensive ACL Configuration:** Six distinct ACLs (internal inbound, internal outbound, DMZ inbound, DMZ outbound, external inbound, and external outbound) provide meticulous control over traffic flow, ensuring robust network security. Examples included in the documentation illustrate how to configure ACLs for common scenarios, such as blocking external threats, permitting specific services, and restricting access to sensitive internal resources. **Intuitive Interface and ACL Management:** Simplified methods for configuring firewall interfaces and ACL rules enhance usability. The Firewall class offers intuitive functions for rule management, including adding, removing, and listing ACL rules. **Detailed Documentation and Examples:** Accompanying the code updates, comprehensive documentation and example configurations are provided, detailing the use and configuration of the Firewall node and ACL rules within PrimAITE simulations. ## Impact: The introduction of the Firewall class and the enhancement of ACLRule significantly broaden PrimAITE's capabilities for simulating realistic network security scenarios. Users can now accurately model the behavior of firewalls in their network simulations, applying complex ACLs to control traffic flow and enforce security policies. This update enables more detailed network security analyses, teaching, and experimentation within the PrimAITE environment. ## Test process Extensive unit tests have been added to cover the new functionality, ensuring reliability and correctness. Tests include scenarios for firewall configuration, ACL rule application, traffic filtering based on various criteria, and interaction between different network zones. ## Checklist - [X] PR is linked to ...
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
Getting Started with PrimAITE
💫 Install & Run
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:
mkdir ~\primaite
cd ~\primaite
python3 -m venv .venv
attrib +h .venv /s /d # Hides the .venv directory
.\.venv\Scripts\activate
pip install https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE/releases/download/v2.0.0/primaite-2.0.0-py3-none-any.whl
primaite setup
Run:
primaite session
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 https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE/releases/download/v2.0.0/primaite-2.0.0-py3-none-any.whl
primaite setup
Run:
primaite session
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]
6. Perform the PrimAITE setup:
primaite setup
📚 Building 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.