We are happy to announce the release of NetSecGame v0.2.0. This update brings usability improvements, stronger correctness guarantees, and an expanded test suite, all building on the foundation laid in v0.1.0. Here is a walkthrough of the most important changes.

Reproducible Episodes with Topology Randomization Seeds

One of the most-requested capabilities from the research community was the ability to reproduce exact episodes, even when topology randomization is enabled. Starting in v0.2.0, agents can pass an explicit seed parameter during reset():

observation = agent.reset(seed=42)

The seed is propagated consistently to all internal random processes — including IP re-mapping and network address assignment — so you can replay any episode exactly, compare agent runs under identical conditions, or debug unexpected behaviour without guesswork.

The coordinator now also validates that a seed value is provided before accepting any topology-randomization reset request, giving agents a clear error message rather than silently failing.

A More Robust Multi-Agent Server

Several edge cases in the game coordinator's reset and reward logic have been hardened:

Agent disconnection mid-reset is now correctly detected and handled, preventing the server from entering an inconsistent state.
Reward assignment is skipped when no players remain in the session, avoiding spurious reward signals.
False-positive rewards are now enforced to be non-positive, fixing a sign bug that could produce incorrect reward feedback for defenders.

These fixes matter in long-running experiments where transient connection issues or race conditions between agents could previously corrupt episode statistics.

Agent Name Sanitization and Input Validation

The server now sanitizes agent names at the join handshake, ensuring downstream components are never passed malformed identifiers. Additionally, if an agent sends an unrecognized or malformed action, the server returns an explicit error response rather than silently ignoring the request — making it much easier to debug agent-side serialization issues during development.

The BlockIP action's blocked_ip parameter is also now correctly parsed as an IP object, closing a serialization gap that could cause subtle mismatches between what an agent intended and what the environment recorded.

Goal Description Validation

The configuration parser now validates attacker goal descriptions at load time. This includes checking that any C&C IP address referenced in a goal actually exists in the scenario topology, catching misconfigured task files early rather than at runtime.

Cleaner Code, Cleaner Repository

Several internal refactors improve long-term maintainability:

NetSecGame and WhiteBoxNetSecGame were split into separate files under netsecgame/game/worlds/, making the codebase easier to navigate and extend.
The parameter use_dynamic_ips has been renamed to use_dynamic_addresses everywhere — code, docstrings, configuration examples, and tests — to use more precise terminology.
CSV storage for replay buffers in trajectory_recorder.py is now deprecated in favour of the JSONL format, which is more flexible and easier to parse.
The network mapping logic was refactored to preserve relative distances between hosts and add fallback handling for edge cases in IP assignment.

WhiteBox Environment Docker Support

Building and deploying the WhiteBox variant of NetSecGame is now easier. The Dockerfile accepts a build argument to switch between the standard and WhiteBox environments, and the README now includes step-by-step instructions for building and running the WhiteBox image locally.

New and Improved Documentation

The documentation received a significant update alongside the code:

Dedicated API pages for NetSecGame and WhiteBoxNetSecGame are now part of the online docs.
The configuration parser now has its own documentation page, covering all supported parameters with examples.
All docstrings across the codebase have been migrated to the Google docstring style, making them more consistent and usable with automated documentation generators.
A separate, concise PyPI README has been added for the package listing.

Expanded Test Coverage

The test suite has grown substantially:

New module What it covers test_base_agent.py Agent lifecycle, registration, and message handling test_config_parser.py Config parser correctness, edge cases, and error handling test_configuration_manager.py Configuration manager behaviour

Additional tests cover the new seed-based reset behaviour, BlockIP serialization correctness, and malformed action handling. Overall, the new release adds nearly 650 lines of new test code.

Open Source Community Improvements

With v0.2.0 we also invested in making the project more welcoming for external contributors:

Added CODE_OF_CONDUCT.md, CONTRIBUTING.md, and SECURITY.md to the repository.
Added structured GitHub Issue Templates for bug reports and feature requests.
Added a Pull Request template with an expanded testing checklist.
Updated the cyst-core dependency to the latest release.

Getting Started

If you are already running v0.1.0, upgrading is straightforward:


 pip install --upgrade netsecgame

Or via Docker:

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

The full changelog is available in CHANGELOG and the updated documentation lives at https://stratosphereips.github.io/NetSecGame/.

As always, we welcome contributions — whether that is a new agent implementation, a bug report, or feedback on the framework. Drop by the GitHub repository and join the conversation!

NetSecGame v0.2.0 - Reproducible Experiments and a More Robust Game Server