Skip to content

Update README.md #340

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
eldraco merged 1 commit into from
Jul 31, 2025
Merged

Update README.md #340

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 30 additions & 30 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
# Netwrok Security Game
# Network Security Game
[![Python Checks](https://github.com/stratosphereips/game-states-maker/actions/workflows/python-checks.yml/badge.svg)](https://github.com/stratosphereips/game-states-maker/actions/workflows/python-checks.yml)
[![Autotag](https://github.com/stratosphereips/game-states-maker/actions/workflows/autotag.yml/badge.svg)](https://github.com/stratosphereips/game-states-maker/actions/workflows/autotag.yml)
[![Docs](https://github.com/stratosphereips/game-states-maker/actions/workflows/deploy-docs.yml/badge.svg)](https://stratosphereips.github.io/NetSecGame/)


The NetSecGame (Network Security Game) is a framework for training and evaluation of AI agents in the network security tasks (both offensive and defensive). It is build with [CYST](https://pypi.org/project/cyst/) network simulator and enables rapid development and testing of AI agents in highly configurable scenarios. Examples of implemented agents can be seen in the submodule [NetSecGameAgents](https://github.com/stratosphereips/NetSecGameAgents/tree/main).
The NetSecGame (Network Security Game) is a framework for training and evaluation of AI agents in network security tasks (both offensive and defensive). It is built with [CYST](https://pypi.org/project/cyst/) network simulator and enables rapid development and testing of AI agents in highly configurable scenarios. Examples of implemented agents can be seen in the submodule [NetSecGameAgents](https://github.com/stratosphereips/NetSecGameAgents/tree/main).

## Installation Guide
It is recommended to install the NetSecGame in a virual environement:
It is recommended to install the NetSecGame in a virtual environment:
### Python venv
1.
```bash
Expand Down Expand Up @@ -37,7 +37,7 @@ The NetSecGame can be run in a Docker container. You can build the image locally
```bash
docker build -t aidojo-nsg-coordinator:latest .
```
or use the availabe image from [Dockerhub](https://hub.docker.com/r/lukasond/aidojo-coordinator).
or use the available image from [Dockerhub](https://hub.docker.com/r/lukasond/aidojo-coordinator).
```bash
docker pull lukasond/aidojo-coordinator:1.0.2
```
Expand Down Expand Up @@ -150,7 +150,7 @@ The NetSecGame environment has several components in the following files:
### Directory Details
- `coordinator.py`: Basic coordinator class. Handles agent communication and coordination. **Does not implement dynamics of the world** and must be extended (see examples in `worlds/`).
- `game_components.py`: Implements a library with objects used in the environment. See [detailed explanation](AIDojoCoordinator/docs/Components.md) of the game components.
- `global_defender.py`: Implements global (omnipresent) defender which can be used to stop agents. Simulation of SIEM.
- `global_defender.py`: Implements a global (omnipresent) defender that can be used to stop agents. Simulation of SIEM.

#### **`worlds/`**
Modules for different world configurations:
Expand All @@ -161,9 +161,9 @@ Modules for different world configurations:
#### **`scenarios/`**
Predefined scenario configurations:
- `tiny_scenario_configuration.py`: A minimal example scenario.
- `smaller_scenario_configuration.py`: A compact scenario configuration used for develompent and rapid testing.
- `smaller_scenario_configuration.py`: A compact scenario configuration used for development and rapid testing.
- `scenario_configuration.py`: The main scenario configuration.
- `three_net_configuration.py`: Configuration for a three-network scenario. Used for evaluation of the model overfitting.
- `three_net_configuration.py`: Configuration for a three-network scenario. Used for the evaluation of the model overfitting.
Implements the network game's configuration of hosts, data, services, and connections. It is taken from [CYST](https://pypi.org/project/cyst/).

#### **`utils/`**
Expand All @@ -184,9 +184,9 @@ The [scenarios](#definition-of-the-network-topology) define the **topology** of
2. If the attacker does a successful action in the same step that the defender successfully detects the action, the priority goes to the defender. The reward is a penalty, and the game ends.
(From commit d6d4ac9, July 18th, 2024, the new action BlockIP removes controlled hosts from the state of others. So the state can get smaller)

- The action FindServices finds the new services in a host. If in a subsequent call to FindServices there are less services, they completely replace the list of previous services found. That is, each list of services is the final one, and no memory of previous open services is retained.
- The action FindServices finds the new services in a host. If in a subsequent call to FindServices there are fewer services, they completely replace the list of previous services found. That is, each list of services is the final one, and no memory of previous open services is retained.

#### Assumption and Conditions for Actions
#### Assumptions and Conditions for Actions
1. When playing the `ExploitService` action, it is expected that the agent has discovered this service before (by playing `FindServices` in the `target_host` before this action)
2. The `Find Data` action finds all the available data in the host if successful.
3. The `Find Data` action requires ownership of the target host.
Expand Down Expand Up @@ -220,7 +220,7 @@ Each action type has a predefined probability of being detected. However, detect
- BlockIP: 0.01

This means that one action of the type ScanNetwork has a 5% probability of being detected by the defender.
This way we can define some basic probabilities based on how good we want the defender to be.
This way, we can define some basic probabilities based on how good we want the defender to be.

- Type Ratio Threshold

Expand Down Expand Up @@ -275,10 +275,10 @@ This approach ensures that only repeated or excessive behavior is flagged, reduc
## Starting the game
The environment should be created before starting the agents. The properties of the game, the task and the topology can be either read from a local file or via REST request to the GameDashboard.

#### To start the game with local configuration file
#### To start the game with a local configuration file
```python3 -m AIDojoCoordinator.worlds.NSEGameCoordinator --task_config=<PATH TO CONFIGURATION FILE>```

#### To start the game with remotely defined configuration
#### To start the game with a remotely defined configuration
```python3 -m AIDojoCoordinator.worlds.CYSTCoordinator --service_host=<URL OF THE REMOTE HOST> --service_port=<PORT FOR THE CONFIGURATION REST API> ```

When created, the environment:
Expand All @@ -289,7 +289,7 @@ When created, the environment:
5. starts the game server in a specified address and port

### Interaction with the Environment
When the game server is created, [agents](https://github.com/stratosphereips/NetSecGameAgents/tree/main) connect to it and interact with the environment. In every step of the interaction, agents submits an [Action](./AIDojoCoordinator/docs/Components.md#actions) and receives [Observation](./AIDojoCoordinator/docs/Components.md#observations) with `next_state`, `reward`, `is_terminal`, `end`, and `info` values. Once the terminal state or timeout is reached, no more interaction is possible until the agent asks for a game reset. Each agent should extend the `BaseAgent` class in [agents](https://github.com/stratosphereips/NetSecGameAgents/tree/main).
When the game server is created, [agents](https://github.com/stratosphereips/NetSecGameAgents/tree/main) connect to it and interact with the environment. In every step of the interaction, agents submits an [Action](./AIDojoCoordinator/docs/Components.md#actions) and receive [Observation](./AIDojoCoordinator/docs/Components.md#observations) with `next_state`, `reward`, `is_terminal`, `end`, and `info` values. Once the terminal state or timeout is reached, no more interaction is possible until the agent asks for a game reset. Each agent should extend the `BaseAgent` class in [agents](https://github.com/stratosphereips/NetSecGameAgents/tree/main).


### Configuration
Expand All @@ -299,17 +299,17 @@ The NetSecEnv is highly configurable in terms of the properties of the world, ta

#### Environment configuration
The environment part defines the properties of the environment for the task (see the example below). In particular:
- `random_seed` - sets seed for any random processes in the environment
- `random_seed` - sets the seed for any random processes in the environment
- `scenario` - sets the scenario (network topology) used in the task (currently, `scenario1_tiny`, `scenario1_small`, `scenario1` and `three_nets` are available)
- `save_tajectories` - if `True`, interaction of the agents is serialized and stored in a file
- `use_dynamic_addresses` - if `True`, the network and IP addresses defined in `scenario` are randomly changed at the beginning of **EVERY** episode (the network topology is kept as defined in the `scenario`. Relations between networks are kept, IPs inside networks are chosen at random based on the network IP and mask)
- `use_firewall` - if `True` firewall rules defined in `scenario` are used when executing actions. When `False`, the firewall is ignored, and all connections are allowed (Default)
- `use_global_defender` - if `True`, enables global defendr which is part of the environment and can stop interaction of any playing agent.
- `use_firewall` - if `True`, firewall rules defined in `scenario` are used when executing actions. When `False`, the firewall is ignored, and all connections are allowed (Default)
- `use_global_defender` - if `True`, enables global defender, which is part of the environment and can stop interaction of any playing agent.
- `required_players` - Minimum required players for the game to start (default 1)
- `rewards`:
- `success` - sets reward which agent gets when it reaches the goal (default 100)
- `fail` - sets the reward that which agent does not reach it's objective (default -10)
- `step_reward` - sets reward which agent gets for every step taken (default -1)
- `success` - sets the reward when the agent reaches the goal (default 100)
- `fail` - sets the reward when the agent does not reach its objective (default -10)
- `step_reward` - sets the reward when the agent does each single step in the game (default -1)
- `actions` - defines the probability of success for every ActionType

```YAML
Expand Down Expand Up @@ -364,7 +364,7 @@ Configuration of the attacking agents. Consists of three parts:
- `known_blocks`(dict)

The initial network configuration must assign at least **one** controlled host to the attacker in the network. Any item in `controlled_hosts` is copied to `known_hosts`, so there is no need to include these in both sets. `known_networks` is also extended with a set of **all** networks accessible from the `controlled_hosts`
3. Definition of maximum allowed amount of steps:
3. Definition of maximum allowed number of steps:
- `max_steps:`(int): defines the maximum allowed number of steps for attackers in **each** episode.

Example attacker configuration:
Expand Down Expand Up @@ -420,38 +420,38 @@ Example of defender configuration:
blocked_ips: {}
known_blocks: {}
```
As in other agents, the description is only a text for the agent, so it can know what is supposed to do to win. In the curent implementation, the *Defender* wins, if **NO ATTACKER** reaches their goal.
As in other agents, the description is only a text for the agent, so it can know what is supposed to do to win. In the current implementation, the *Defender* wins, if **NO ATTACKER** reaches their goal.


### Definition of the network topology
The network topology and rules are defined using a [CYST](https://pypi.org/project/cyst/) simulator configuration. Cyst defines a complex network configuration, and this environment does not use all Cyst features for now. CYST components currently used are:

- Server hosts (are a NodeConf in CYST)
- Interfaces, each with one IP address
- Users that can log in to the host
- Users who can log in to the host
- Active and passive services
- Data in the server
- To which network is connected
- Client host (are a Node in CYST)
- Client host (are of type Node in CYST)
- Interfaces, each with one IP address
- To which network is connected
- Active and passive services if any
- Active and passive services, if any
- Data in the client
- Router (are a RouterConf in CYST)
- Router (are of type RouterConf in CYST)
- Interfaces, each with one IP address
- Networks
- Allowed connections between hosts
- Internet host (as an external router) (are a Node in RouterConf)
- Internet host (as an external router) (are of type Node in RouterConf)
- Interfaces, each with one IP address
- Which host can connect
- Exploits
- which service is the exploit linked to
- Which service is the exploit linked to

### Scenarios
In the current state, we support a single scenario: Data exfiltration to a remote C&C server. However, extensions can be made by modification of the task configuration.

#### Data exfiltration to a remote C&C
For the data exfiltration we support 3 variants. The full scenario contains 5 clients (where the attacker can start) and 5 servers where the data that is supposed to be exfiltrated can be located. *scenario1_small* is a variant with a single client (the attacker always starts there) and all 5 servers. *scenario1_tiny* contains only a single server with data. The tiny scenario is trivial and intended only for debugging purposes.
For the data exfiltration, we support 3 variants. The full scenario contains 5 clients (where the attacker can start) and 5 servers, where the data that is supposed to be exfiltrated can be located. *scenario1_small* is a variant with a single client (the attacker always starts there) and all 5 servers. *scenario1_tiny* contains only a single server with data. The tiny scenario is trivial and intended only for debugging purposes.
<table>
<tr><th>Scenario 1</th><th>Scenario 1 - small</th><th>Scenario 1 -tiny</th></tr>
<tr><td><img src="AIDojoCoordinator/docs/figures/scenarios/scenario_1.png" alt="Scenario 1 - Data exfiltration" width="300"></td><td><img src="AIDojoCoordinator/docs/figures/scenarios/scenario 1_small.png" alt="Scenario 1 - small" width="300"</td><td><img src="AIDojoCoordinator/docs/figures/scenarios/scenario_1_tiny.png" alt="Scenario 1 - tiny" width="300"></td></tr>
Expand All @@ -476,12 +476,12 @@ env:

## Testing the environment

It is advised after every change you test if the env is running correctly by doing
It is advised that after every change, you test if the env is running correctly by doing

```bash
tests/run_all_tests.sh
```
This will load and run the unit tests in the `tests` folder. After passing all tests, linting and formatting is checked with ruff.
This will load and run the unit tests in the `tests` folder. After passing all tests, linting and formatting are checked with ruff.

## Code adaptation for new configurations
The code can be adapted to new configurations of games and for new agents. See [Agent repository](https://github.com/stratosphereips/NetSecGameAgents/tree/main) for more details.
Expand Down