# visa/visa-vulnerability-agentic-harness architecture

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

- Interactive diagram: https://gitdiagram.com/visa/visa-vulnerability-agentic-harness
- Repository: https://github.com/visa/visa-vulnerability-agentic-harness

## Overview

VVAH is an LLM-powered vulnerability discovery harness whose main workflow scans a repository, models threats, investigates and verifies findings, then synthesizes Markdown/SARIF reports. Optional branches verify exploits over HTTP, replay confirmed attacks, and propose and validate fixes. The graph preserves the README’s documented stages and major capabilities; several subsystem links reflect README-level workflow because their implementation was not sampled.

Main entry points: [`vvaharness/backends/llm/registry.py`](https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/backends/llm/registry.py) (LLM Registry), [`vvaharness/exploit_verification/verify/router.py`](https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/exploit_verification/verify/router.py) (Exploit Verification), [`vvaharness/orchestrator/scan.py`](https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/orchestrator/scan.py) (Scan Orchestrator), [`vvaharness/pipeline/stages/s3_decompose.py`](https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s3_decompose.py) (Discovery S1–S3)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scan["Scan Workflow"]
  node_cli["CLI<br/>[cli.py]"]
  node_orchestrator["Scan Orchestrator<br/>[scan.py]"]
  node_seed["Static Seed<br/>[s0_seed.py]"]
  node_discovery["Discovery S1–S3<br/>[s3_decompose.py]"]
  node_synthesis["Synthesis S7–S9<br/>[s8_chain.py]"]
  node_portfolio["Portfolio Scans<br/>[batch.py]"]
end

subgraph group_analysis["Analysis and Verification"]
  node_deepdive["Deep Dive S4<br/>[s4_deepdive.py]"]
  node_callgraph["Call Graph<br/>[_scan.py]"]
  node_verify["Static Verification S6<br/>[s6_verify.py]"]
  node_exploit["Exploit Verification<br/>[router.py]"]
  node_replay["Exploit Replay<br/>[run.py]"]
end

subgraph group_models["Model Backends"]
  node_backends["Backend Routing"]
  node_llmregistry["LLM Registry<br/>[registry.py]"]
  node_llmcli["CLI LLM<br/>[cli.py]"]
  node_llmsdk["SDK LLM<br/>[sdk.py]"]
  node_llmdeep["DeepAgents LLM<br/>[deepagents.py]"]
end

subgraph group_outputs["Triage and Fixes"]
  node_report["Report Enrichment<br/>[enrich.py]"]
  node_redaction["Report Redaction<br/>[redact.py]"]
  node_remediation["Remediation<br/>[remediate.py]"]
  node_validation["Fix Validation<br/>[pipeline.py]"]
end

subgraph group_runtime["Configuration and Runtime"]
  node_evsettings["EV Settings<br/>[settings.py]"]
  node_config["Configuration<br/>[__init__.py]"]
  node_tokens["Token Accounting<br/>[tokens.py]"]
  node_counters["Run Counters<br/>[counters.py]"]
  node_store[("Run State<br/>[store.py]")]
end

node_operator(("Operator"))

node_operator -->|"invokes"| node_cli
node_cli -.->|"starts scan"| node_orchestrator
node_orchestrator -->|"runs stages"| node_seed
node_seed -->|"seeds analysis"| node_discovery
node_discovery -->|"feeds review"| node_deepdive
node_discovery -->|"uses reachable-code analysis"| node_callgraph
node_deepdive -->|"submits findings"| node_verify
node_verify -->|"optionally verifies"| node_exploit
node_evsettings -->|"configures"| node_exploit
node_exploit -->|"enables replay"| node_replay
node_verify -->|"passes findings"| node_synthesis
node_synthesis -->|"emits findings"| node_report
node_report -->|"redacts output"| node_redaction
node_report -->|"supports fix proposals"| node_remediation
node_remediation -->|"proposes validation"| node_validation
node_orchestrator -->|"routes model roles"| node_backends
node_backends -->|"resolves provider"| node_llmregistry
node_llmregistry -.->|"selects route"| node_llmcli
node_llmregistry -.->|"selects route"| node_llmsdk
node_llmregistry -.->|"selects route"| node_llmdeep
node_config -->|"provides settings"| node_backends
node_exploit -->|"accounts usage"| node_tokens
node_llmdeep -->|"records fallback"| node_counters
node_operator -->|"starts batch"| node_portfolio
node_portfolio -->|"persists run state"| node_store

click node_cli "https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/cli.py"
click node_orchestrator "https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/orchestrator/scan.py"
click node_seed "https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s0_seed.py"
click node_discovery "https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s3_decompose.py"
click node_deepdive "https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s4_deepdive.py"
click node_callgraph "https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/callgraph_engine/_scan.py"
click node_verify "https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s6_verify.py"
click node_exploit "https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/exploit_verification/verify/router.py"
click node_evsettings "https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/exploit_verification/settings.py"
click node_replay "https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/exploit_verification/replay/run.py"
click node_synthesis "https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s8_chain.py"
click node_report "https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/report/enrich.py"
click node_redaction "https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/report/redact.py"
click node_remediation "https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/remediation_agent/remediate.py"
click node_validation "https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/validation/execution/pipeline.py"
click node_backends "https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/backends/harness/provider_routing.py"
click node_llmregistry "https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/backends/llm/registry.py"
click node_llmcli "https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/backends/llm/cli.py"
click node_llmsdk "https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/backends/llm/sdk.py"
click node_llmdeep "https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/backends/llm/deepagents.py"
click node_config "https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/config/__init__.py"
click node_tokens "https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/util/tokens.py"
click node_counters "https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/util/counters.py"
click node_portfolio "https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/orchestrator/batch.py"
click node_store "https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/orchestrator/store.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_orchestrator,node_seed,node_discovery,node_synthesis,node_portfolio toneBlue
class node_deepdive,node_callgraph,node_verify,node_exploit,node_replay toneAmber
class node_backends,node_llmregistry,node_llmcli,node_llmsdk,node_llmdeep toneMint
class node_report,node_redaction,node_remediation,node_validation toneRose
class node_evsettings,node_config,node_tokens,node_counters,node_store,node_operator toneIndigo
```

## Components

### Scan Workflow

- [CLI](https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/cli.py): `vvaharness/cli.py`
- [Scan Orchestrator](https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/orchestrator/scan.py): `vvaharness/orchestrator/scan.py`
- [Static Seed](https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s0_seed.py): `vvaharness/pipeline/stages/s0_seed.py`
- [Discovery S1–S3](https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s3_decompose.py): `vvaharness/pipeline/stages/s3_decompose.py`
- [Synthesis S7–S9](https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s8_chain.py): `vvaharness/pipeline/stages/s8_chain.py`
- [Portfolio Scans](https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/orchestrator/batch.py): `vvaharness/orchestrator/batch.py`

### Analysis and Verification

- [Deep Dive S4](https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s4_deepdive.py): `vvaharness/pipeline/stages/s4_deepdive.py`
- [Call Graph](https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/callgraph_engine/_scan.py): `vvaharness/pipeline/stages/callgraph_engine/_scan.py`
- [Static Verification S6](https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s6_verify.py): `vvaharness/pipeline/stages/s6_verify.py`
- [Exploit Verification](https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/exploit_verification/verify/router.py): `vvaharness/exploit_verification/verify/router.py`
- [Exploit Replay](https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/exploit_verification/replay/run.py): `vvaharness/exploit_verification/replay/run.py`

### Model Backends

- [Backend Routing](https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/backends/harness/provider_routing.py): `vvaharness/backends/harness/provider_routing.py`
- [LLM Registry](https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/backends/llm/registry.py): `vvaharness/backends/llm/registry.py`
- [CLI LLM](https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/backends/llm/cli.py): `vvaharness/backends/llm/cli.py`
- [SDK LLM](https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/backends/llm/sdk.py): `vvaharness/backends/llm/sdk.py`
- [DeepAgents LLM](https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/backends/llm/deepagents.py): `vvaharness/backends/llm/deepagents.py`

### Triage and Fixes

- [Report Enrichment](https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/report/enrich.py): `vvaharness/report/enrich.py`
- [Report Redaction](https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/report/redact.py): `vvaharness/report/redact.py`
- [Remediation](https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/remediation_agent/remediate.py): `vvaharness/remediation_agent/remediate.py`
- [Fix Validation](https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/validation/execution/pipeline.py): `vvaharness/validation/execution/pipeline.py`

### Configuration and Runtime

- [EV Settings](https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/exploit_verification/settings.py): `vvaharness/exploit_verification/settings.py`
- [Configuration](https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/config/__init__.py): `vvaharness/config/__init__.py`
- [Token Accounting](https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/util/tokens.py): `vvaharness/util/tokens.py`
- [Run Counters](https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/util/counters.py): `vvaharness/util/counters.py`
- [Run State](https://github.com/visa/visa-vulnerability-agentic-harness/blob/main/vvaharness/orchestrator/store.py): `vvaharness/orchestrator/store.py`

### Other components

- **Operator**

## Connections

- Operator → CLI: invokes
- CLI → Scan Orchestrator: starts scan
- Scan Orchestrator → Static Seed: runs stages
- Static Seed → Discovery S1–S3: seeds analysis
- Discovery S1–S3 → Deep Dive S4: feeds review
- Discovery S1–S3 → Call Graph: uses reachable-code analysis (evidence: `vvaharness/pipeline/stages/s3_decompose.py`)
- Deep Dive S4 → Static Verification S6: submits findings
- Static Verification S6 → Exploit Verification: optionally verifies (evidence: `vvaharness/exploit_verification/verify/router.py`)
- EV Settings → Exploit Verification: configures (evidence: `vvaharness/exploit_verification/settings.py`)
- Exploit Verification → Exploit Replay: enables replay
- Static Verification S6 → Synthesis S7–S9: passes findings
- Synthesis S7–S9 → Report Enrichment: emits findings
- Report Enrichment → Report Redaction: redacts output (evidence: `vvaharness/report/redact.py`)
- Report Enrichment → Remediation: supports fix proposals
- Remediation → Fix Validation: proposes validation
- Scan Orchestrator → Backend Routing: routes model roles
- Backend Routing → LLM Registry: resolves provider (evidence: `vvaharness/backends/harness/provider_routing.py`)
- LLM Registry → CLI LLM: selects route (evidence: `vvaharness/backends/llm/registry.py`)
- LLM Registry → SDK LLM: selects route
- LLM Registry → DeepAgents LLM: selects route (evidence: `vvaharness/backends/llm/deepagents.py`)
- Configuration → Backend Routing: provides settings (evidence: `vvaharness/backends/harness/provider_routing.py`)
- Exploit Verification → Token Accounting: accounts usage (evidence: `vvaharness/exploit_verification/verify/router.py`)
- DeepAgents LLM → Run Counters: records fallback (evidence: `vvaharness/backends/llm/deepagents.py`)
- Operator → Portfolio Scans: starts batch
- Portfolio Scans → Run State: persists run state