Skip to content

0.2.0

Latest
Latest

Choose a tag to compare

View all tags
@ondrej-lukas ondrej-lukas released this 01 Apr 15:00
· 35 commits to main since this release
v0.250.0
95325e2
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

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.
Assets 2
Loading