# microsoft/cyberbattlesim architecture

> Architecture diagram of the GitHub repository microsoft/cyberbattlesim, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/cyberbattlesim
- Repository: https://github.com/microsoft/cyberbattlesim

## Overview

CyberBattleSim is a research simulator for training and comparing automated agents on abstract enterprise-network attacks and defense. The main workflow is to select or generate a network scenario, run an attacker through the Gym environment, resolve actions against the simulated network, optionally let a defender detect and mitigate attacks, and use observations and rewards to train or evaluate agents. The repository also provides graph/observation wrappers and benchmark plotting. Connections among unsampled scenario and algorithm modules are limited to documented references; those implementations were not inspected.

Main entry points: [`cyberbattle/_env/cyberbattle_env.py`](https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/_env/cyberbattle_env.py) (Gym Environment), [`cyberbattle/agents/baseline/learner.py`](https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/agents/baseline/learner.py) (Learning Loop), [`cyberbattle/simulation/model.py`](https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/simulation/model.py) (Network Model), [`cyberbattle/agents/baseline/agent_wrapper.py`](https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/agents/baseline/agent_wrapper.py) (Agent Wrapper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Simulation Core"]
  node_environment["Gym Environment<br/>[cyberbattle_env.py]"]
  node_network_model["Network Model<br/>[model.py]"]
  node_agent_actions["Attacker Actions<br/>[actions.py]"]
  node_command_control["Command Control<br/>[commandcontrol.py]"]
  node_defender["Stochastic Defender<br/>[defender.py]"]
end

subgraph group_scenarios["Network Scenarios"]
  node_environment_generation["Environment Generation"]
  node_network_generation["Random Networks"]
  node_scenario_ad["Active Directory"]
  node_scenario_chain["Chain Scenario"]
  node_scenario_random["Random Scenario"]
  node_scenario_tiny["Tiny Scenario"]
  node_scenario_toyctf["Toy CTF"]
end

subgraph group_agents["Agents and Training"]
  node_runner["Training Runner<br/>[run.py]"]
  node_learner["Learning Loop<br/>[learner.py]"]
  node_dql_agent["Deep Q Agent<br/>[agent_dql.py]"]
  node_tabular_agent["Tabular Q Agent"]
  node_credential_agent["Credential Agent"]
  node_random_agent["Random Agent<br/>[random_agent.py]"]
  node_plotting["Training Plots<br/>[plotting.py]"]
end

subgraph group_observation["Observation Tools"]
  node_agent_wrapper["Agent Wrapper<br/>[agent_wrapper.py]"]
  node_graph_wrapper["Graph Wrapper<br/>[graph_wrapper.py]"]
  node_graph_spaces["Graph Spaces<br/>[graph_spaces.py]"]
  node_flatten_wrapper["Flatten Wrapper<br/>[flatten_wrapper.py]"]
  node_option_wrapper["Option Wrapper<br/>[option_wrapper.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"starts training"| node_runner
node_runner -->|"configures episodes"| node_environment
node_runner -->|"runs learning"| node_learner
node_learner -->|"steps environment"| node_environment
node_learner -->|"uses features"| node_agent_wrapper
node_learner -->|"records metrics"| node_plotting
node_dql_agent -->|"implements policy"| node_learner
node_dql_agent -->|"uses features"| node_agent_wrapper
node_tabular_agent -->|"implements policy"| node_learner
node_tabular_agent -->|"uses features"| node_agent_wrapper
node_credential_agent -->|"implements policy"| node_learner
node_credential_agent -->|"reads observations"| node_agent_wrapper
node_random_agent -->|"samples actions"| node_environment
node_environment -->|"uses state model"| node_network_model
node_environment -->|"dispatches actions"| node_agent_actions
node_environment -->|"uses control logic"| node_command_control
node_environment -->|"steps defender"| node_defender
node_agent_actions -->|"updates network"| node_network_model
node_command_control -->|"uses state model"| node_network_model
node_defender -->|"scans nodes"| node_network_model
node_defender -->|"uses mitigation actions"| node_agent_actions
node_environment_generation -->|"builds environments"| node_network_model
node_network_generation -->|"builds random networks"| node_network_model
node_scenario_random -->|"creates topology"| node_network_generation
node_scenario_random -->|"provides environment"| node_environment
node_scenario_ad -->|"provides environment"| node_environment
node_scenario_chain -->|"provides environment"| node_environment
node_scenario_tiny -.->|"provides environment"| node_environment
node_scenario_toyctf -.->|"provides environment"| node_environment
node_graph_wrapper -->|"uses spaces"| node_graph_spaces
node_flatten_wrapper -->|"wraps environment"| node_environment
node_option_wrapper -->|"wraps environment"| node_environment

click node_runner "https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/agents/baseline/run.py"
click node_environment "https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/_env/cyberbattle_env.py"
click node_network_model "https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/simulation/model.py"
click node_agent_actions "https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/simulation/actions.py"
click node_command_control "https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/simulation/commandcontrol.py"
click node_defender "https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/_env/defender.py"
click node_environment_generation "https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/simulation/environment_generation.py"
click node_network_generation "https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/simulation/generate_network.py"
click node_scenario_ad "https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/_env/active_directory.py"
click node_scenario_chain "https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/_env/cyberbattle_chain.py"
click node_scenario_random "https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/_env/cyberbattle_random.py"
click node_scenario_tiny "https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/_env/cyberbattle_tiny.py"
click node_scenario_toyctf "https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/_env/cyberbattle_toyctf.py"
click node_agent_wrapper "https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/agents/baseline/agent_wrapper.py"
click node_graph_wrapper "https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/_env/graph_wrapper.py"
click node_graph_spaces "https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/_env/graph_spaces.py"
click node_flatten_wrapper "https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/_env/flatten_wrapper.py"
click node_option_wrapper "https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/_env/option_wrapper.py"
click node_learner "https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/agents/baseline/learner.py"
click node_dql_agent "https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/agents/baseline/agent_dql.py"
click node_tabular_agent "https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/agents/baseline/agent_tabularqlearning.py"
click node_credential_agent "https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/agents/baseline/agent_randomcredlookup.py"
click node_random_agent "https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/agents/random_agent.py"
click node_plotting "https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/agents/baseline/plotting.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_environment,node_network_model,node_agent_actions,node_command_control,node_defender toneBlue
class node_environment_generation,node_network_generation,node_scenario_ad,node_scenario_chain,node_scenario_random,node_scenario_tiny,node_scenario_toyctf toneAmber
class node_runner,node_learner,node_dql_agent,node_tabular_agent,node_credential_agent,node_random_agent,node_plotting toneMint
class node_agent_wrapper,node_graph_wrapper,node_graph_spaces,node_flatten_wrapper,node_option_wrapper toneRose
class node_researcher toneIndigo
```

## Components

### Simulation Core

- [Gym Environment](https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/_env/cyberbattle_env.py): `cyberbattle/_env/cyberbattle_env.py`
- [Network Model](https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/simulation/model.py): `cyberbattle/simulation/model.py`
- [Attacker Actions](https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/simulation/actions.py): `cyberbattle/simulation/actions.py`
- [Command Control](https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/simulation/commandcontrol.py): `cyberbattle/simulation/commandcontrol.py`
- [Stochastic Defender](https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/_env/defender.py): `cyberbattle/_env/defender.py`

### Network Scenarios

- [Environment Generation](https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/simulation/environment_generation.py): `cyberbattle/simulation/environment_generation.py`
- [Random Networks](https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/simulation/generate_network.py): `cyberbattle/simulation/generate_network.py`
- [Active Directory](https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/_env/active_directory.py): `cyberbattle/_env/active_directory.py`
- [Chain Scenario](https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/_env/cyberbattle_chain.py): `cyberbattle/_env/cyberbattle_chain.py`
- [Random Scenario](https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/_env/cyberbattle_random.py): `cyberbattle/_env/cyberbattle_random.py`
- [Tiny Scenario](https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/_env/cyberbattle_tiny.py): `cyberbattle/_env/cyberbattle_tiny.py`
- [Toy CTF](https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/_env/cyberbattle_toyctf.py): `cyberbattle/_env/cyberbattle_toyctf.py`

### Agents and Training

- [Training Runner](https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/agents/baseline/run.py): `cyberbattle/agents/baseline/run.py`
- [Learning Loop](https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/agents/baseline/learner.py): `cyberbattle/agents/baseline/learner.py`
- [Deep Q Agent](https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/agents/baseline/agent_dql.py): `cyberbattle/agents/baseline/agent_dql.py`
- [Tabular Q Agent](https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/agents/baseline/agent_tabularqlearning.py): `cyberbattle/agents/baseline/agent_tabularqlearning.py`
- [Credential Agent](https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/agents/baseline/agent_randomcredlookup.py): `cyberbattle/agents/baseline/agent_randomcredlookup.py`
- [Random Agent](https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/agents/random_agent.py): `cyberbattle/agents/random_agent.py`
- [Training Plots](https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/agents/baseline/plotting.py): `cyberbattle/agents/baseline/plotting.py`

### Observation Tools

- [Agent Wrapper](https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/agents/baseline/agent_wrapper.py): `cyberbattle/agents/baseline/agent_wrapper.py`
- [Graph Wrapper](https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/_env/graph_wrapper.py): `cyberbattle/_env/graph_wrapper.py`
- [Graph Spaces](https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/_env/graph_spaces.py): `cyberbattle/_env/graph_spaces.py`
- [Flatten Wrapper](https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/_env/flatten_wrapper.py): `cyberbattle/_env/flatten_wrapper.py`
- [Option Wrapper](https://github.com/microsoft/cyberbattlesim/blob/main/cyberbattle/_env/option_wrapper.py): `cyberbattle/_env/option_wrapper.py`

### Other components

- **Researcher**

## Connections

- Researcher → Training Runner: starts training (evidence: `README.md`)
- Training Runner → Gym Environment: configures episodes (evidence: `cyberbattle/agents/baseline/run.py`)
- Training Runner → Learning Loop: runs learning (evidence: `cyberbattle/agents/baseline/run.py`)
- Learning Loop → Gym Environment: steps environment (evidence: `cyberbattle/agents/baseline/learner.py`)
- Learning Loop → Agent Wrapper: uses features (evidence: `cyberbattle/agents/baseline/learner.py`)
- Learning Loop → Training Plots: records metrics (evidence: `cyberbattle/agents/baseline/learner.py`)
- Deep Q Agent → Learning Loop: implements policy (evidence: `cyberbattle/agents/baseline/agent_dql.py`)
- Deep Q Agent → Agent Wrapper: uses features (evidence: `cyberbattle/agents/baseline/agent_dql.py`)
- Tabular Q Agent → Learning Loop: implements policy (evidence: `cyberbattle/agents/baseline/agent_tabularqlearning.py`)
- Tabular Q Agent → Agent Wrapper: uses features (evidence: `cyberbattle/agents/baseline/agent_tabularqlearning.py`)
- Credential Agent → Learning Loop: implements policy (evidence: `cyberbattle/agents/baseline/agent_randomcredlookup.py`)
- Credential Agent → Agent Wrapper: reads observations (evidence: `cyberbattle/agents/baseline/agent_randomcredlookup.py`)
- Random Agent → Gym Environment: samples actions (evidence: `cyberbattle/agents/random_agent.py`)
- Gym Environment → Network Model: uses state model (evidence: `cyberbattle/_env/cyberbattle_env.py`)
- Gym Environment → Attacker Actions: dispatches actions (evidence: `cyberbattle/_env/cyberbattle_env.py`)
- Gym Environment → Command Control: uses control logic (evidence: `cyberbattle/_env/cyberbattle_env.py`)
- Gym Environment → Stochastic Defender: steps defender (evidence: `cyberbattle/_env/cyberbattle_env.py`)
- Attacker Actions → Network Model: updates network (evidence: `cyberbattle/simulation/actions.py`)
- Command Control → Network Model: uses state model (evidence: `cyberbattle/simulation/commandcontrol.py`)
- Stochastic Defender → Network Model: scans nodes (evidence: `cyberbattle/_env/defender.py`)
- Stochastic Defender → Attacker Actions: uses mitigation actions (evidence: `cyberbattle/_env/defender.py`)
- Environment Generation → Network Model: builds environments (evidence: `cyberbattle/simulation/environment_generation.py`)
- Random Networks → Network Model: builds random networks (evidence: `cyberbattle/simulation/generate_network.py`)
- Random Scenario → Random Networks: creates topology (evidence: `cyberbattle/_env/cyberbattle_random.py`)
- Random Scenario → Gym Environment: provides environment (evidence: `cyberbattle/_env/cyberbattle_random.py`)
- Active Directory → Gym Environment: provides environment (evidence: `cyberbattle/_env/active_directory.py`)
- Chain Scenario → Gym Environment: provides environment (evidence: `cyberbattle/_env/cyberbattle_chain.py`)
- Tiny Scenario → Gym Environment: provides environment
- Toy CTF → Gym Environment: provides environment
- Graph Wrapper → Graph Spaces: uses spaces (evidence: `cyberbattle/_env/graph_wrapper.py`)
- Flatten Wrapper → Gym Environment: wraps environment (evidence: `cyberbattle/_env/flatten_wrapper.py`)
- Option Wrapper → Gym Environment: wraps environment (evidence: `cyberbattle/_env/option_wrapper.py`)
