# duriantaco/ravage architecture

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

- Interactive diagram: https://gitdiagram.com/duriantaco/ravage
- Repository: https://github.com/duriantaco/ravage

## Overview

Ravage is an evidence-first CLI for authorized web-application security assessment. Its main workflow scopes an engagement, discovers the target surface, runs deterministic probes and optionally a model-guided attack, then validates and reports findings with evidence. Separate capabilities include authentication, source-guided prioritization, and bounded read-only repository review. The graph reflects documented capabilities and sampled source; several internal connections are omitted where implementation was not inspected.

Main entry points: [`packages/ravage/src/orchestrator.py`](https://github.com/duriantaco/ravage/blob/main/packages/ravage/src/orchestrator.py) (Run orchestration), [`packages/ravage/src/ravage/agent_core/autonomous_graph/entrypoint.py`](https://github.com/duriantaco/ravage/blob/main/packages/ravage/src/ravage/agent_core/autonomous_graph/entrypoint.py) (Autonomous attack), [`packages/ravage/src/ravage/__main__.py`](https://github.com/duriantaco/ravage/blob/main/packages/ravage/src/ravage/__main__.py) (Ravage CLI), [`packages/ravage/src/ravage/finding_evidence.py`](https://github.com/duriantaco/ravage/blob/main/packages/ravage/src/ravage/finding_evidence.py) (Finding evidence)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_engagement["Engagement setup"]
  node_cli["Ravage CLI<br/>[__main__.py]"]
  node_brief["Engagement brief<br/>[brief.py]"]
  node_auth["Auth sessions"]
end

subgraph group_assessment["Assessment workflow"]
  node_orchestrator["Run orchestration<br/>[orchestrator.py]"]
  node_recon["Surface discovery<br/>[recon.py]"]
  node_scan["Deterministic probes<br/>[probe_suite.py]"]
  node_probes["Vulnerability probes"]
  node_source["Source analysis<br/>[source_analysis.py]"]
end

subgraph group_agent["Agent and runtime"]
  node_agent["Autonomous attack<br/>[entrypoint.py]"]
  node_runtime["Tool runtime"]
  node_traffic["Traffic capture"]
end

subgraph group_evidence["Evidence and results"]
  node_finding["Finding evidence"]
  node_proof["Proof validation"]
  node_report["Assessment report<br/>[report.py]"]
  node_run["Run artifacts"]
end

subgraph group_review["Repository review"]
  node_reviewcli["Review command"]
  node_context["Frozen source context"]
  node_review["Review protocol"]
end

node_user(("Authorized tester"))
node_target(("Web application"))
node_model(("Model provider"))

node_user -->|"runs commands"| node_cli
node_cli -->|"creates or reads"| node_brief
node_cli -->|"manages identity"| node_auth
node_cli -->|"starts assessment"| node_orchestrator
node_brief -->|"configures scope"| node_orchestrator
node_auth -->|"provides session"| node_orchestrator
node_orchestrator -->|"discovers surface"| node_recon
node_recon -->|"sends requests"| node_target
node_orchestrator -->|"runs probes"| node_scan
node_scan -->|"dispatches checks"| node_probes
node_probes -->|"tests endpoints"| node_target
node_orchestrator -.->|"optionally analyzes"| node_source
node_source -.->|"prioritizes candidates"| node_agent
node_orchestrator -.->|"optionally starts loop"| node_agent
node_agent -.->|"requests decisions"| node_model
node_agent -->|"dispatches actions"| node_runtime
node_runtime -->|"executes scoped tests"| node_target
node_runtime -->|"accounts traffic"| node_traffic
node_probes -->|"records observations"| node_finding
node_agent -->|"records outcomes"| node_finding
node_finding -->|"checks evidence"| node_proof
node_orchestrator -->|"produces results"| node_report
node_finding -->|"supplies findings"| node_report
node_orchestrator -->|"persists run data"| node_run
node_user -->|"requests review"| node_reviewcli
node_reviewcli -->|"captures snapshot"| node_context
node_reviewcli -->|"runs review"| node_review
node_context -->|"supplies bounded context"| node_review
node_review -->|"requests analysis"| node_model

click node_cli "https://github.com/duriantaco/ravage/blob/main/packages/ravage/src/ravage/__main__.py"
click node_brief "https://github.com/duriantaco/ravage/blob/main/packages/schemas/src/pentest_schemas/brief.py"
click node_auth "https://github.com/duriantaco/ravage/tree/main/packages/ravage/src/ravage/auth"
click node_orchestrator "https://github.com/duriantaco/ravage/blob/main/packages/ravage/src/orchestrator.py"
click node_recon "https://github.com/duriantaco/ravage/blob/main/packages/ravage/src/ravage/web_core/recon.py"
click node_scan "https://github.com/duriantaco/ravage/blob/main/packages/ravage/src/ravage/probe_suite.py"
click node_probes "https://github.com/duriantaco/ravage/tree/main/packages/ravage/src/ravage/probes"
click node_source "https://github.com/duriantaco/ravage/blob/main/packages/ravage/src/ravage/source_analysis.py"
click node_agent "https://github.com/duriantaco/ravage/blob/main/packages/ravage/src/ravage/agent_core/autonomous_graph/entrypoint.py"
click node_runtime "https://github.com/duriantaco/ravage/tree/main/packages/ravage/src/ravage/runtime"
click node_traffic "https://github.com/duriantaco/ravage/tree/main/packages/ravage/src/ravage/traffic"
click node_finding "https://github.com/duriantaco/ravage/blob/main/packages/ravage/src/ravage/finding_evidence.py"
click node_proof "https://github.com/duriantaco/ravage/blob/main/packages/ravage/src/ravage/proof_bundle_verifier.py"
click node_report "https://github.com/duriantaco/ravage/blob/main/packages/ravage/src/ravage/report.py"
click node_run "https://github.com/duriantaco/ravage/tree/main/packages/ravage/src/ravage/run_data"
click node_reviewcli "https://github.com/duriantaco/ravage/blob/main/packages/ravage/src/ravage/repository_review_cli.py"
click node_context "https://github.com/duriantaco/ravage/blob/main/packages/ravage/src/ravage/repository_context.py"
click node_review "https://github.com/duriantaco/ravage/blob/main/packages/ravage/src/ravage/repository_review.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_brief,node_auth toneBlue
class node_orchestrator,node_recon,node_scan,node_probes,node_source toneAmber
class node_agent,node_runtime,node_traffic toneMint
class node_finding,node_proof,node_report,node_run toneRose
class node_reviewcli,node_context,node_review,node_user,node_target,node_model toneIndigo
```

## Components

### Engagement setup

- [Ravage CLI](https://github.com/duriantaco/ravage/blob/main/packages/ravage/src/ravage/__main__.py): `packages/ravage/src/ravage/__main__.py`
- [Engagement brief](https://github.com/duriantaco/ravage/blob/main/packages/schemas/src/pentest_schemas/brief.py): `packages/schemas/src/pentest_schemas/brief.py`
- [Auth sessions](https://github.com/duriantaco/ravage/tree/main/packages/ravage/src/ravage/auth): `packages/ravage/src/ravage/auth`

### Assessment workflow

- [Run orchestration](https://github.com/duriantaco/ravage/blob/main/packages/ravage/src/orchestrator.py): `packages/ravage/src/orchestrator.py`
- [Surface discovery](https://github.com/duriantaco/ravage/blob/main/packages/ravage/src/ravage/web_core/recon.py): `packages/ravage/src/ravage/web_core/recon.py`
- [Deterministic probes](https://github.com/duriantaco/ravage/blob/main/packages/ravage/src/ravage/probe_suite.py): `packages/ravage/src/ravage/probe_suite.py`
- [Vulnerability probes](https://github.com/duriantaco/ravage/tree/main/packages/ravage/src/ravage/probes): `packages/ravage/src/ravage/probes`
- [Source analysis](https://github.com/duriantaco/ravage/blob/main/packages/ravage/src/ravage/source_analysis.py): `packages/ravage/src/ravage/source_analysis.py`

### Agent and runtime

- [Autonomous attack](https://github.com/duriantaco/ravage/blob/main/packages/ravage/src/ravage/agent_core/autonomous_graph/entrypoint.py): `packages/ravage/src/ravage/agent_core/autonomous_graph/entrypoint.py`
- [Tool runtime](https://github.com/duriantaco/ravage/tree/main/packages/ravage/src/ravage/runtime): `packages/ravage/src/ravage/runtime`
- [Traffic capture](https://github.com/duriantaco/ravage/tree/main/packages/ravage/src/ravage/traffic): `packages/ravage/src/ravage/traffic`

### Evidence and results

- [Finding evidence](https://github.com/duriantaco/ravage/blob/main/packages/ravage/src/ravage/finding_evidence.py): `packages/ravage/src/ravage/finding_evidence.py`
- [Proof validation](https://github.com/duriantaco/ravage/blob/main/packages/ravage/src/ravage/proof_bundle_verifier.py): `packages/ravage/src/ravage/proof_bundle_verifier.py`
- [Assessment report](https://github.com/duriantaco/ravage/blob/main/packages/ravage/src/ravage/report.py): `packages/ravage/src/ravage/report.py`
- [Run artifacts](https://github.com/duriantaco/ravage/tree/main/packages/ravage/src/ravage/run_data): `packages/ravage/src/ravage/run_data`

### Repository review

- [Review command](https://github.com/duriantaco/ravage/blob/main/packages/ravage/src/ravage/repository_review_cli.py): `packages/ravage/src/ravage/repository_review_cli.py`
- [Frozen source context](https://github.com/duriantaco/ravage/blob/main/packages/ravage/src/ravage/repository_context.py): `packages/ravage/src/ravage/repository_context.py`
- [Review protocol](https://github.com/duriantaco/ravage/blob/main/packages/ravage/src/ravage/repository_review.py): `packages/ravage/src/ravage/repository_review.py`

### Other components

- **Authorized tester**
- **Web application**
- **Model provider**

## Connections

- Authorized tester → Ravage CLI: runs commands
- Ravage CLI → Engagement brief: creates or reads
- Ravage CLI → Auth sessions: manages identity
- Ravage CLI → Run orchestration: starts assessment
- Engagement brief → Run orchestration: configures scope
- Auth sessions → Run orchestration: provides session
- Run orchestration → Surface discovery: discovers surface
- Surface discovery → Web application: sends requests
- Run orchestration → Deterministic probes: runs probes
- Deterministic probes → Vulnerability probes: dispatches checks
- Vulnerability probes → Web application: tests endpoints
- Run orchestration → Source analysis: optionally analyzes
- Source analysis → Autonomous attack: prioritizes candidates
- Run orchestration → Autonomous attack: optionally starts loop
- Autonomous attack → Model provider: requests decisions
- Autonomous attack → Tool runtime: dispatches actions
- Tool runtime → Web application: executes scoped tests
- Tool runtime → Traffic capture: accounts traffic
- Vulnerability probes → Finding evidence: records observations
- Autonomous attack → Finding evidence: records outcomes
- Finding evidence → Proof validation: checks evidence
- Run orchestration → Assessment report: produces results
- Finding evidence → Assessment report: supplies findings
- Run orchestration → Run artifacts: persists run data
- Authorized tester → Review command: requests review
- Review command → Frozen source context: captures snapshot
- Review command → Review protocol: runs review
- Frozen source context → Review protocol: supplies bounded context
- Review protocol → Model provider: requests analysis