# aaa1234fdja/ely-soe-harness architecture

> Architecture diagram of the GitHub repository aaa1234fdja/ely-soe-harness, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aaa1234fdja/ely-soe-harness
- Repository: https://github.com/aaa1234fdja/ely-soe-harness

## Overview

ELY Security Lab & SOE is an audit and release-readiness platform for agentic software. Users start scheduled, on-demand, or pre-release audits through the CLI or web command center; the SOE lifecycle scopes and analyzes a target, runs isolated security exercises, independently validates findings, and produces maturity and release-gate results. Its documented capabilities also include frontier research tools, broad cyber-domain auditing, untrusted-agent simulation, signed evidence, history, and verified remediation. Relationships among unsampled subsystems are included only where the README documents the workflow; source excerpts and the index support the other cited links.

Main entry points: [`ely_soe/soe/lifecycle.py`](https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/soe/lifecycle.py) (Audit Lifecycle), [`ely_soe/soe/engine.py`](https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/soe/engine.py) (SOE Engine), [`ely_soe/lab/auditor.py`](https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/lab/auditor.py) (Independent Auditor), [`ely_soe/cli.py`](https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/cli.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_web["Web Command Center<br/>[api_handlers.py]"]
end

subgraph group_orchestration["Audit Orchestration"]
  node_engine["SOE Engine<br/>[engine.py]"]
  node_lifecycle["Audit Lifecycle<br/>[lifecycle.py]"]
  node_scheduler["Audit Scheduler<br/>[scheduler.py]"]
  node_history[("Audit History<br/>[store.py]")]
  node_scope["Scope and Config<br/>[scope_guard.py]"]
end

subgraph group_analysis["Discovery and Research"]
  node_repo_analysis["Repository Analysis<br/>[repo_analyzer.py]"]
  node_domain_analysis["Cyber Domain Audits"]
  node_taint["Taint Analysis<br/>[taint_engine.py]"]
  node_frontier["Frontier Research"]
  node_hypotheses["Hypothesis Planning"]
end

subgraph group_lab["Isolated Security Lab"]
  node_snapshot["Snapshot and Scrubbing<br/>[snapshot.py]"]
  node_sandbox["Sandbox Exercises<br/>[sandbox.py]"]
  node_redteam["Adversarial Campaigns<br/>[red_team.py]"]
  node_rogue_agents["Untrusted Agents"]
end

subgraph group_assurance["Validation and Assurance"]
  node_validator["Independent Auditor<br/>[auditor.py]"]
  node_models["Finding Models<br/>[models.py]"]
  node_ledger[("Signed Evidence Ledger<br/>[crypto_ledger.py]")]
  node_maturity["Maturity Gate<br/>[maturity.py]"]
  node_reporter["Reports and Remediation<br/>[reporter.py]"]
  node_autopatch["Verified Autopatching"]
end

node_user(("Audit Operator"))

node_user -->|"invokes"| node_cli
node_user -->|"uses"| node_web
node_cli -->|"starts audits"| node_engine
node_web -->|"starts audits"| node_engine
node_engine -->|"runs lifecycle"| node_lifecycle
node_engine -->|"registers schedules"| node_scheduler
node_engine -->|"stores history"| node_history
node_scheduler -->|"reads and writes"| node_history
node_lifecycle -->|"checks scope"| node_scope
node_lifecycle -->|"analyzes target"| node_repo_analysis
node_lifecycle -->|"runs domain audits"| node_domain_analysis
node_lifecycle -->|"runs static analysis"| node_taint
node_lifecycle -->|"runs research tools"| node_frontier
node_lifecycle -->|"creates snapshot"| node_snapshot
node_lifecycle -->|"runs isolated tests"| node_sandbox
node_lifecycle -->|"runs campaigns"| node_redteam
node_lifecycle -->|"runs simulation"| node_rogue_agents
node_lifecycle -->|"requests validation"| node_validator
node_validator -->|"certifies findings"| node_models
node_validator -->|"signs evidence"| node_ledger
node_lifecycle -->|"evaluates release gate"| node_maturity
node_lifecycle -->|"produces results"| node_reporter
node_reporter -.->|"offers remediation"| node_autopatch
node_lifecycle -.->|"plans verification"| node_hypotheses

click node_cli "https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/cli.py"
click node_web "https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/web/api_handlers.py"
click node_engine "https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/soe/engine.py"
click node_lifecycle "https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/soe/lifecycle.py"
click node_scheduler "https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/soe/scheduler.py"
click node_history "https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/soe/store.py"
click node_scope "https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/core/scope_guard.py"
click node_repo_analysis "https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/analyzers/repo_analyzer.py"
click node_domain_analysis "https://github.com/aaa1234fdja/ely-soe-harness/tree/main/ely_soe/cyber"
click node_taint "https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/analyzers/taint_engine.py"
click node_frontier "https://github.com/aaa1234fdja/ely-soe-harness/tree/main/ely_soe/frontier"
click node_hypotheses "https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/harness_squared/hypothesis_engine.py"
click node_snapshot "https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/lab/snapshot.py"
click node_sandbox "https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/lab/sandbox.py"
click node_redteam "https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/lab/red_team.py"
click node_rogue_agents "https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/lab/untrusted_agents.py"
click node_validator "https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/lab/auditor.py"
click node_models "https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/core/models.py"
click node_ledger "https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/core/crypto_ledger.py"
click node_maturity "https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/soe/maturity.py"
click node_reporter "https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/harness/reporter.py"
click node_autopatch "https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/harness/verified_autopatch_engine.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_cli,node_web toneBlue
class node_engine,node_lifecycle,node_scheduler,node_history,node_scope toneAmber
class node_repo_analysis,node_domain_analysis,node_taint,node_frontier,node_hypotheses toneMint
class node_snapshot,node_sandbox,node_redteam,node_rogue_agents toneRose
class node_validator,node_models,node_ledger,node_maturity,node_reporter,node_autopatch,node_user toneIndigo
```

## Components

### User Interfaces

- [CLI](https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/cli.py): `ely_soe/cli.py`
- [Web Command Center](https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/web/api_handlers.py): `ely_soe/web/api_handlers.py`

### Audit Orchestration

- [SOE Engine](https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/soe/engine.py): `ely_soe/soe/engine.py`
- [Audit Lifecycle](https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/soe/lifecycle.py): `ely_soe/soe/lifecycle.py`
- [Audit Scheduler](https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/soe/scheduler.py): `ely_soe/soe/scheduler.py`
- [Audit History](https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/soe/store.py): `ely_soe/soe/store.py`
- [Scope and Config](https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/core/scope_guard.py): `ely_soe/core/scope_guard.py`

### Discovery and Research

- [Repository Analysis](https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/analyzers/repo_analyzer.py): `ely_soe/analyzers/repo_analyzer.py`
- [Cyber Domain Audits](https://github.com/aaa1234fdja/ely-soe-harness/tree/main/ely_soe/cyber): `ely_soe/cyber`
- [Taint Analysis](https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/analyzers/taint_engine.py): `ely_soe/analyzers/taint_engine.py`
- [Frontier Research](https://github.com/aaa1234fdja/ely-soe-harness/tree/main/ely_soe/frontier): `ely_soe/frontier`
- [Hypothesis Planning](https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/harness_squared/hypothesis_engine.py): `ely_soe/harness_squared/hypothesis_engine.py`

### Isolated Security Lab

- [Snapshot and Scrubbing](https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/lab/snapshot.py): `ely_soe/lab/snapshot.py`
- [Sandbox Exercises](https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/lab/sandbox.py): `ely_soe/lab/sandbox.py`
- [Adversarial Campaigns](https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/lab/red_team.py): `ely_soe/lab/red_team.py`
- [Untrusted Agents](https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/lab/untrusted_agents.py): `ely_soe/lab/untrusted_agents.py`

### Validation and Assurance

- [Independent Auditor](https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/lab/auditor.py): `ely_soe/lab/auditor.py`
- [Finding Models](https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/core/models.py): `ely_soe/core/models.py`
- [Signed Evidence Ledger](https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/core/crypto_ledger.py): `ely_soe/core/crypto_ledger.py`
- [Maturity Gate](https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/soe/maturity.py): `ely_soe/soe/maturity.py`
- [Reports and Remediation](https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/harness/reporter.py): `ely_soe/harness/reporter.py`
- [Verified Autopatching](https://github.com/aaa1234fdja/ely-soe-harness/blob/main/ely_soe/harness/verified_autopatch_engine.py): `ely_soe/harness/verified_autopatch_engine.py`

### Other components

- **Audit Operator**

## Connections

- Audit Operator → CLI: invokes
- Audit Operator → Web Command Center: uses
- CLI → SOE Engine: starts audits (evidence: `ely_soe/cli.py`)
- Web Command Center → SOE Engine: starts audits (evidence: `ely_soe/web/api_handlers.py`)
- SOE Engine → Audit Lifecycle: runs lifecycle (evidence: `ely_soe/soe/engine.py`)
- SOE Engine → Audit Scheduler: registers schedules (evidence: `ely_soe/soe/engine.py`)
- SOE Engine → Audit History: stores history (evidence: `ely_soe/soe/engine.py`)
- Audit Scheduler → Audit History: reads and writes (evidence: `ely_soe/soe/scheduler.py`)
- Audit Lifecycle → Scope and Config: checks scope (evidence: `ely_soe/soe/lifecycle.py`)
- Audit Lifecycle → Repository Analysis: analyzes target (evidence: `ely_soe/soe/lifecycle.py`)
- Audit Lifecycle → Cyber Domain Audits: runs domain audits
- Audit Lifecycle → Taint Analysis: runs static analysis
- Audit Lifecycle → Frontier Research: runs research tools (evidence: `ely_soe/soe/lifecycle.py`)
- Audit Lifecycle → Snapshot and Scrubbing: creates snapshot (evidence: `ely_soe/soe/lifecycle.py`)
- Audit Lifecycle → Sandbox Exercises: runs isolated tests
- Audit Lifecycle → Adversarial Campaigns: runs campaigns (evidence: `ely_soe/soe/lifecycle.py`)
- Audit Lifecycle → Untrusted Agents: runs simulation (evidence: `ely_soe/soe/lifecycle.py`)
- Audit Lifecycle → Independent Auditor: requests validation (evidence: `ely_soe/soe/lifecycle.py`)
- Independent Auditor → Finding Models: certifies findings (evidence: `ely_soe/core/models.py`)
- Independent Auditor → Signed Evidence Ledger: signs evidence
- Audit Lifecycle → Maturity Gate: evaluates release gate (evidence: `ely_soe/soe/lifecycle.py`)
- Audit Lifecycle → Reports and Remediation: produces results (evidence: `ely_soe/soe/lifecycle.py`)
- Reports and Remediation → Verified Autopatching: offers remediation
- Audit Lifecycle → Hypothesis Planning: plans verification
