0.2.0

Changes since v0.1.0 (commit 9f0bbdd)

---

New Features

Topology Randomization Seed

• Agents can now pass an explicit seed during reset() to deterministically control topology randomization.
• The seed is propagated through all RNG processes (IP re-mapping, network mapping) ensuring reproducible episodes.
• GameCoordinator validates that a seed value is present before accepting a topology-randomization reset request; malformed requests are rejected with a descriptive error response.

Agent Name Sanitization

• Agent names are now sanitized during the join handshake, preventing downstream issues caused by invalid or adversarial names.

Goal Description Validation

• The config parser now validates attacker goal descriptions at load time, including checking that referenced C&C IP addresses exist in the scenario topology.

Block Action Serialization

• blocked_ip is now correctly parsed as an IP object in BlockIP action parameters, fixing a silent serialization bug.

Malformed Action Handling

• The coordinator now returns an explicit error response when an agent sends a malformed or unrecognized action, rather than silently dropping it.

WhiteBox Docker Image

• A new Dockerfile build argument allows building a WhiteBox variant of the environment image.
• Instructions added to the README along with a (currently disabled) GitHub workflow for publishing the WhiteBox image.

---

Improvements

World Classes — Refactored

• NetSecGame and WhiteBoxNetSecGame were split into separate files under netsecgame/game/worlds/ for cleaner project organization.
• Network mapping logic refactored to preserve relative distances between hosts and adds fallback handling for edge cases in IP assignment.
• WhiteBoxNetSecGame now correctly reports that IP re-mapping is not supported when responding to reset requests.
• Reset processing for topology randomization moved to the coordinator level, separating concerns more clearly.
• get_valid_actions() return type unified to Set[Action].

GameCoordinator — Hardened Reset Logic

• Correctly detects and handles the case where an agent disconnects mid-reset.
• Rewards are not assigned when there are no remaining players.
• Improved logging around reset and reward assignment flows.

Config Parser — Extended

• Handles integer and None values in Action parameters gracefully.
• Added support for parsing the new seed parameter in reset requests.
• Removed deprecated and unused configuration options.

ConfigurationManager — Extended

• Extended with additional utility methods and improved test coverage.

Scenarios Module

• Added netsecgame/game/scenarios/__init__.py for cleaner imports.
• Restored missing scenario configurations and example task configuration entries.

Utilities

• gamaplay_graphs.py renamed to gameplay_graphs.py (typo fix).
• trajectory_recorder.py: CSV storage for replay buffers is now deprecated; JSONL format is recommended instead.
• Import compatibility shim added in netsecgame/utils/utils.py with deprecation warnings for utilities that were moved.

Parameter Naming — Standardized

• use_dynamic_ips renamed to use_dynamic_addresses uniformly across code, docstrings, and tests.

Dockerfile — Optimized

• Reduced image size through build optimizations.

False-Positive Reward Fix

• The FP reward is now enforced as non-positive with an explicit validation check and corrected sign convention.

---

Documentation

• Added dedicated API documentation pages for NetSecGame and WhiteBoxNetSecGame.
• Added configuration parser documentation (docs/config_parser.md).
• Improved docs/index.md, docs/game_coordinator.md, and docs/configuration_manager.md with updated content and links.
• Added a separate PyPI README (README_pypi.md) and wired it into pyproject.toml.
• Enhanced the main README.md with configuration details and WhiteBox Docker build instructions.
• All docstrings migrated to Google-style notation.
• mkdocs.yml updated to include all new documentation pages.

---

Tests

Three new test modules added:

Module	Coverage
tests/agents/test_base_agent.py	Base agent lifecycle and message handling
tests/game/test_config_parser.py	Config parser — full coverage including edge cases
tests/game/test_configuration_manager.py	Configuration manager — full coverage

Additional test additions:

• Tests for BlockIP action serialization.
• Tests for malformed action handling.
• Tests for topology-randomization seed reset behaviour.
• Fixed mock scope in existing config parser tests.

---

Housekeeping

• Added GitHub community files: CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md.
• Added GitHub Issue Templates for bug reports and feature requests (YAML format).
• Added Pull Request template with an expanded testing checklist.
• Updated cyst-core dependency to the latest release.
• Removed unused imports and dead code throughout the codebase.
• Fixed multiple typos across code, comments, and documentation.
• Added .coverage to .gitignore.

0.1.0

First version of the NetSecGame package

We are excited to announce the release of NetSecGame (NSG) v0.1.0, a framework for training and evaluating AI agents in network security environments. Developed at the Stratosphere Laboratory at CTU in Prague, NSG provides a highly configurable testbed for both offensive and defensive security tasks.

What is NetSecGame?

NetSecGame is a simulation environment designed specifically for cybersecurity scenarios. It enables researchers and developers to create rapid, highly configurable experiments where autonomous agents can be trained to perform complex network security operations.

Unlike traditional static datasets or rigid simulations, NSG offers a dynamic playground where:

• Attackers can learn to scan networks, find services, exploit vulnerabilities, and exfiltrate data.
• Defenders can learn to monitor traffic, detect anomalies, block malicious actors, and protect critical assets.

The environment adopts standard Reinforcement Learning (RL) principles to make it intuitive for anyone familiar with the field. It provides a richer game state representation than standard interfaces, allowing for more complex and realistic security interactions.

Why is it Useful?

For security researchers and AI practitioners, reliable evaluation of autonomous agents is a major challenge. NetSecGame solves this by providing:

• Reproducibility: Standardized scenarios ensure that agent performance can be consistently measured and compared.
• Speed: Being a simulation rather than a virtualization-based range, it runs extremely fast, allowing for millions of training steps in a fraction of the time.
• Flexibility: Users can define custom network topologies, services, vulnerabilities, and goals using simple YAML configurations.
• Realistic Noise: Includes a stochastic Global Defender (SIEM-like) simulation to provide realistic opposition and noise for attackers, even without a trained opponent.

Running the Game

The simulation runs as a game server, where agents connect remotely to interact with the environment. This separation allows for flexibility in how and where agents are deployed.

Getting started with NetSecGame is designed to be straightforward. The easiest way to run the NetSecGame server is via Docker:

docker pull stratosphereips/netsecgame
docker run -d --rm --name nsg-server \
    -v $(pwd)/<scenarion-configuration>.yaml:/netsecgame/netsecenv_conf.yaml \
    -v $(pwd)/logs:/netsecgame/logs \
    -p 9000:9000 stratosphereips/netsecgame

To run a specific scenario, you simply pass a Task Configuration file to the server (mapped via volumes), defining the network layout and objectives. You can find some examples in the examples directory.

What's Coming Next

We are continuously improving NetSecGame to push the boundaries of AI in cybersecurity. Our roadmap includes:

• Expanded Scenario Library: We are working on a wider range of pre-built complex topologies to test agent generalization.
• Advanced Agents: New reference implementations for state-of-the-art RL and hierarchical agents are in the pipeline.
• Enhanced Dynamics: Future updates will include more granular network actions and deeper integration with realistic network traffic generation.
• Community Competitions: We plan to host challenges where users can pit their best attacker/defender agents against each other!

(Note to authors: Please add any specific internal roadmap items here if applicable)

Learn More

• GitHub Repository: https://github.com/stratosphereips/game-states-maker
• Documentation: https://stratosphereips.github.io/NetSecGame/ - Comprehensive guides on configuration, agent creation, and architecture.
• PyPi Package: https://pypi.org/project/netsecgame/
• Docker Hub: https://hub.docker.com/r/stratosphereips/netsecgame

Contributing

We invite the community to try out NetSecGame, build agents, and contribute to the future of autonomous network security!

We especially welcome new agent implementations of all kinds: Attackers, Defenders, and Benign agents (simulation of normal user behavior). If you've built an agent you'd like to share:

1. Fork the NetSecGameAgents repository.
2. Implement your agent inheriting from BaseAgent.
3. Submit a Pull Request with your agent code and a brief description of its strategy.

Whether you are a researcher looking for a new benchmark or a developer interested in cybersecurity, we look forward to seeing what you build!

Coordinator-orchestrated, single player game

This is the last version of the NetSecEnv which only supports single player interaction.

ICAART papers

This release contains the code that was used for the following two papers:

Bandhana, A.; Lukáš, O.; Garcia, S. and Kroupa, T. (2023). Catch Me if You Can: Improving Adversaries in Cyber-Security with Q-Learning Algorithms. In Proceedings of the 15th International Conference on Agents and Artificial Intelligence - Volume 3: ICAART; ISBN 978-989-758-623-1; ISSN 2184-433X, SciTePress, pages 442-449. DOI: 10.5220/0011684500003393

Rigaki, M.; Lukáš, O.; Catania, C. and Garcia, S. (2024). Out of the Cage: How Stochastic Parrots Win in Cyber Security Environments. In Proceedings of the 16th International Conference on Agents and Artificial Intelligence - Volume 3, ISBN 978-989-758-680-4, ISSN 2184-433X, pages 775-782.