Skip to content

README.md

Latest commit

 

History

History
executable file
·
82 lines (59 loc) · 4.5 KB

README.md

File metadata and controls

executable file
·
82 lines (59 loc) · 4.5 KB

Network Security Game

Python Checks Autotag Docs Docker Publish PyPI Version

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 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.

Installation

Docker (recommended)

docker pull stratosphereips/netsecgame

pip install

pip install netsecgame

From source

pip install -e .

For detailed installation instructions (venv, conda, building Docker locally, Whitebox variant), see the Getting Started guide.

Quick Start

  1. Prepare a task configuration YAML file (see example or the Configuration docs).

  2. Start the server:

# Docker
docker run -d --rm --name nsg-server \
  -v $(pwd)/examples/example_task_configuration.yaml:/netsecgame/netsecenv_conf.yaml \
  -v $(pwd)/logs:/netsecgame/logs \
  -p 9000:9000 stratosphereips/netsecgame

# Or locally
python3 -m netsecgame.game.worlds.NetSecGame \
  --task_config=./examples/example_task_configuration.yaml \
  --game_port=9000
  1. Connect an agent (see NetSecGameAgents for reference implementations).

Documentation

Full documentation is available at https://stratosphereips.github.io/NetSecGame/

Assumptions of the NetSecGame

  1. NetSecGame works with the closed-world assumption. Only the defined entities exist in the simulation.
  2. If the attacker does a successful action in the same step that the defender successfully detects the action, the priority goes to the attacker. (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 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.

For detailed action preconditions and effects, see the Architecture documentation.

Contributing

Testing the environment

After every change, verify the environment is working correctly:

tests/run_all_tests.sh

This runs the unit tests in the tests folder, followed by linting and formatting checks with ruff.

Code adaptation

The code can be adapted to new configurations of games and for new agents. See the Agent repository for more details.

About us

This code was developed at the Stratosphere Laboratory at the Czech Technical University in Prague.