# ydnyshhh/offsec-gym architecture

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

- Interactive diagram: https://gitdiagram.com/ydnyshhh/offsec-gym
- Repository: https://github.com/ydnyshhh/offsec-gym

## Overview

OffSecGym is a research testbed for measuring autonomous security agents on isolated synthetic applications. Its main workflow provisions a range, lets an agent explore through a controlled gateway, validates submitted findings against hidden ground truth, and records evidence and resource use for scoring. Experiments compare scripted, monolithic, and worker-based orchestration, with optional structured memory and model providers. Range B adds an enterprise change-control scenario. The graph follows README-documented flows and relationships visible in the supplied source index; unsampled implementation details and research-script wiring are not inferred.

Main entry points: [`src/offsecgym/experiment/scripted.py`](https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/experiment/scripted.py) (Experiment runner), [`src/offsecgym/gateway/compose.py`](https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/gateway/compose.py) (Audited HTTP gateway), [`src/offsecgym/solver/workers.py`](https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/solver/workers.py) (Worker orchestration), [`src/offsecgym/validation/deterministic.py`](https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/validation/deterministic.py) (Finding validator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experiment["Experiment orchestration"]
  node_cli["Command line<br/>[main.py]"]
  node_experiment_runner["Experiment runner<br/>[scripted.py]"]
  node_scripted_solver["Scripted solver<br/>[scripted.py]"]
  node_monolithic_solver["Monolithic solver<br/>[monolithic.py]"]
  node_worker_solver["Worker orchestration<br/>[workers.py]"]
  node_provider["Model providers<br/>[base.py]"]
end

subgraph group_range["Ranges and access"]
  node_range_runtime["Range runtime<br/>[compose.py]"]
  node_saas_range["Synthetic SaaS range<br/>[saas.py]"]
  node_enterprise_range["Enterprise range<br/>[enterprise.py]"]
  node_gateway["Audited HTTP gateway<br/>[compose.py]"]
end

subgraph group_assessment["Validation and records"]
  node_validator["Finding validator<br/>[deterministic.py]"]
  node_oracle["Hidden ground truth<br/>[oracle.py]"]
  node_evaluation["Scoring and evaluation<br/>[evaluation.py]"]
  node_event_store[("Event store<br/>[event_store.py]")]
  node_projection["Event projections<br/>[projection.py]"]
  node_artifacts["Evidence artifacts<br/>[artifacts.py]"]
  node_worldview["Structured worldview<br/>[state.py]"]
end

subgraph group_contracts["Contracts and providers"]
  node_schemas["Domain and event contracts"]
  node_interfaces["Runtime interfaces<br/>[interfaces.py]"]
end

subgraph group_research["Research analysis"]
  node_research_analysis["Research analyses"]
end

node_researcher(("Researcher"))

node_researcher -->|"runs commands"| node_cli
node_cli -->|"manages ranges"| node_range_runtime
node_cli -->|"starts experiments"| node_experiment_runner
node_experiment_runner -->|"runs solver"| node_scripted_solver
node_experiment_runner -.->|"runs solver"| node_monolithic_solver
node_experiment_runner -.->|"runs orchestration"| node_worker_solver
node_monolithic_solver -.->|"requests model turns"| node_provider
node_worker_solver -.->|"requests model turns"| node_provider
node_range_runtime -->|"builds range"| node_saas_range
node_range_runtime -->|"builds range"| node_enterprise_range
node_experiment_runner -->|"provisions access"| node_gateway
node_gateway -->|"forwards requests"| node_saas_range
node_gateway -.->|"forwards requests"| node_enterprise_range
node_scripted_solver -.->|"executes actions"| node_gateway
node_monolithic_solver -.->|"executes actions"| node_gateway
node_worker_solver -.->|"executes actions"| node_gateway
node_experiment_runner -->|"submits findings"| node_validator
node_validator -->|"checks ground truth"| node_oracle
node_validator -->|"returns results"| node_evaluation
node_gateway -->|"records actions"| node_event_store
node_experiment_runner -->|"records run"| node_event_store
node_validator -->|"records validation"| node_event_store
node_event_store -->|"projects events"| node_projection
node_experiment_runner -.->|"stores evidence"| node_artifacts
node_worker_solver -->|"retrieves state"| node_worldview
node_experiment_runner -->|"uses contracts"| node_schemas
node_worker_solver -->|"uses task contracts"| node_schemas
node_experiment_runner -->|"uses boundaries"| node_interfaces
node_researcher -.->|"compares results"| node_research_analysis

click node_cli "https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/cli/main.py"
click node_experiment_runner "https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/experiment/scripted.py"
click node_scripted_solver "https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/solver/scripted.py"
click node_monolithic_solver "https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/solver/monolithic.py"
click node_worker_solver "https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/solver/workers.py"
click node_provider "https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/providers/base.py"
click node_range_runtime "https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/runtime/compose.py"
click node_saas_range "https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/runtime/saas.py"
click node_enterprise_range "https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/runtime/enterprise.py"
click node_gateway "https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/gateway/compose.py"
click node_validator "https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/validation/deterministic.py"
click node_oracle "https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/runtime/oracle.py"
click node_evaluation "https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/evaluation.py"
click node_event_store "https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/storage/event_store.py"
click node_projection "https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/storage/projection.py"
click node_artifacts "https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/providers/artifacts.py"
click node_worldview "https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/worldview/state.py"
click node_schemas "https://github.com/ydnyshhh/offsec-gym/tree/main/src/offsecgym/schemas"
click node_interfaces "https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/interfaces.py"
click node_research_analysis "https://github.com/ydnyshhh/offsec-gym/tree/main/src/offsecgym/research"

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_cli,node_experiment_runner,node_scripted_solver,node_monolithic_solver,node_worker_solver,node_provider toneBlue
class node_range_runtime,node_saas_range,node_enterprise_range,node_gateway toneAmber
class node_validator,node_oracle,node_evaluation,node_event_store,node_projection,node_artifacts,node_worldview toneMint
class node_schemas,node_interfaces toneRose
class node_research_analysis,node_researcher toneIndigo
```

## Components

### Experiment orchestration

- [Command line](https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/cli/main.py): `src/offsecgym/cli/main.py`
- [Experiment runner](https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/experiment/scripted.py): `src/offsecgym/experiment/scripted.py`
- [Scripted solver](https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/solver/scripted.py): `src/offsecgym/solver/scripted.py`
- [Monolithic solver](https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/solver/monolithic.py): `src/offsecgym/solver/monolithic.py`
- [Worker orchestration](https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/solver/workers.py): `src/offsecgym/solver/workers.py`
- [Model providers](https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/providers/base.py): `src/offsecgym/providers/base.py`

### Ranges and access

- [Range runtime](https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/runtime/compose.py): `src/offsecgym/runtime/compose.py`
- [Synthetic SaaS range](https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/runtime/saas.py): `src/offsecgym/runtime/saas.py`
- [Enterprise range](https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/runtime/enterprise.py): `src/offsecgym/runtime/enterprise.py`
- [Audited HTTP gateway](https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/gateway/compose.py): `src/offsecgym/gateway/compose.py`

### Validation and records

- [Finding validator](https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/validation/deterministic.py): `src/offsecgym/validation/deterministic.py`
- [Hidden ground truth](https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/runtime/oracle.py): `src/offsecgym/runtime/oracle.py`
- [Scoring and evaluation](https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/evaluation.py): `src/offsecgym/evaluation.py`
- [Event store](https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/storage/event_store.py): `src/offsecgym/storage/event_store.py`
- [Event projections](https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/storage/projection.py): `src/offsecgym/storage/projection.py`
- [Evidence artifacts](https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/providers/artifacts.py): `src/offsecgym/providers/artifacts.py`
- [Structured worldview](https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/worldview/state.py): `src/offsecgym/worldview/state.py`

### Contracts and providers

- [Domain and event contracts](https://github.com/ydnyshhh/offsec-gym/tree/main/src/offsecgym/schemas): `src/offsecgym/schemas`
- [Runtime interfaces](https://github.com/ydnyshhh/offsec-gym/blob/main/src/offsecgym/interfaces.py): `src/offsecgym/interfaces.py`

### Research analysis

- [Research analyses](https://github.com/ydnyshhh/offsec-gym/tree/main/src/offsecgym/research): `src/offsecgym/research`

### Other components

- **Researcher**

## Connections

- Researcher → Command line: runs commands (evidence: `README.md`)
- Command line → Range runtime: manages ranges (evidence: `src/offsecgym/cli/main.py`)
- Command line → Experiment runner: starts experiments (evidence: `src/offsecgym/cli/main.py`)
- Experiment runner → Scripted solver: runs solver (evidence: `src/offsecgym/experiment/scripted.py`)
- Experiment runner → Monolithic solver: runs solver (evidence: `README.md`)
- Experiment runner → Worker orchestration: runs orchestration (evidence: `README.md`)
- Monolithic solver → Model providers: requests model turns (evidence: `README.md`)
- Worker orchestration → Model providers: requests model turns (evidence: `README.md`)
- Range runtime → Synthetic SaaS range: builds range (evidence: `src/offsecgym/runtime/compose.py`)
- Range runtime → Enterprise range: builds range (evidence: `src/offsecgym/runtime/compose.py`)
- Experiment runner → Audited HTTP gateway: provisions access (evidence: `README.md`)
- Audited HTTP gateway → Synthetic SaaS range: forwards requests (evidence: `README.md`)
- Audited HTTP gateway → Enterprise range: forwards requests (evidence: `README.md`)
- Scripted solver → Audited HTTP gateway: executes actions (evidence: `README.md`)
- Monolithic solver → Audited HTTP gateway: executes actions (evidence: `README.md`)
- Worker orchestration → Audited HTTP gateway: executes actions (evidence: `README.md`)
- Experiment runner → Finding validator: submits findings (evidence: `README.md`)
- Finding validator → Hidden ground truth: checks ground truth (evidence: `README.md`)
- Finding validator → Scoring and evaluation: returns results (evidence: `README.md`)
- Audited HTTP gateway → Event store: records actions (evidence: `README.md`)
- Experiment runner → Event store: records run (evidence: `README.md`)
- Finding validator → Event store: records validation (evidence: `README.md`)
- Event store → Event projections: projects events
- Experiment runner → Evidence artifacts: stores evidence (evidence: `README.md`)
- Worker orchestration → Structured worldview: retrieves state (evidence: `src/offsecgym/solver/workers.py`)
- Experiment runner → Domain and event contracts: uses contracts (evidence: `src/offsecgym/experiment/scripted.py`)
- Worker orchestration → Domain and event contracts: uses task contracts (evidence: `src/offsecgym/solver/workers.py`)
- Experiment runner → Runtime interfaces: uses boundaries (evidence: `src/offsecgym/experiment/scripted.py`)
- Researcher → Research analyses: compares results (evidence: `README.md`)
