# ppd-ibm/vulnerability-agentic-harness architecture

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

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

## Overview

VVAH is an agentic vulnerability-discovery, remediation, and fix-validation harness. Its principal workflow scans a target repository through discovery, threat modeling, analysis, verification, and finding synthesis; remediation can then propose or apply fixes, followed by adversarial validation. The README documents all eleven stages and Markdown/SARIF outputs. Sampled code confirms the scan orchestrator’s stage wiring, model-backend dispatch, remediation plugin invocation, and validation execution. Some stage internals are unsampled, so their documented sequence is shown without asserting unobserved internal calls.

Main entry points: [`vvaharness/orchestrator/scan.py`](https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/orchestrator/scan.py) (Scan orchestrator), [`vvaharness/cli.py`](https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/cli.py) (Command interface), [`vvaharness/remediation_agent/runner.py`](https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/remediation_agent/runner.py) (Remediation runner), [`vvaharness/validation/execution/pipeline.py`](https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/validation/execution/pipeline.py) (Validation execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scan["Discovery and Scan"]
  node_scanflow["Scan orchestrator<br/>[scan.py]"]
  node_preprocess["Preprocess and scope<br/>[s1_preprocess.py]"]
  node_threat["Threat modeling"]
  node_decompose["Hunting plan<br/>[s3_decompose.py]"]
  node_deepdive["Deep analysis<br/>[s4_deepdive.py]"]
  node_verify["Adversarial verification<br/>[s6_verify.py]"]
  node_synthesis["Dedup and chain"]
  node_report["Finding reports<br/>[models.py]"]
end

subgraph group_shared["Models and Integrations"]
  node_enrichment["Finding enrichment<br/>[enrich.py]"]
  node_redaction["Sensitive-data redaction<br/>[redact.py]"]
  node_language["Language hints<br/>[hints.py]"]
  node_models["Finding data models<br/>[models.py]"]
  node_llm["Model backend routing<br/>[llm.py]"]
  node_checkpoints[("Run checkpoints<br/>[checkpoints.py]")]
  node_configpaths["Configuration paths<br/>[config_paths.py]"]
  node_store[("Run state store<br/>[store.py]")]
end

subgraph group_remediate["Remediation"]
  node_remrunner["Remediation runner<br/>[runner.py]"]
  node_parse["Finding parser<br/>[parse.py]"]
  node_plugin["Patch plugin<br/>[run.py]"]
  node_artifacts["Patch artifacts"]
end

subgraph group_validate["Validation"]
  node_validation["Validation command<br/>[_run.py]"]
  node_execution["Validation execution<br/>[pipeline.py]"]
  node_session["Agent validation session<br/>[launcher.py]"]
  node_collector["Result collection"]
  node_scoring["Fix-quality scoring<br/>[_engine.py]"]
  node_validationbackend["Validation model clients"]
end

node_engineer(("Authorized engineer"))
node_target["Target repository"]
node_cli["Command interface<br/>[cli.py]"]

node_engineer -->|"runs commands"| node_cli
node_cli -->|"starts scan"| node_scanflow
node_scanflow -->|"scans code"| node_target
node_scanflow -->|"runs stage"| node_preprocess
node_scanflow -->|"runs stage"| node_threat
node_scanflow -->|"runs stage"| node_decompose
node_scanflow -->|"runs stage"| node_deepdive
node_scanflow -->|"runs stage"| node_verify
node_scanflow -->|"runs stages"| node_synthesis
node_preprocess -->|"precedes"| node_threat
node_threat -->|"precedes"| node_decompose
node_decompose -->|"precedes"| node_deepdive
node_deepdive -->|"precedes"| node_verify
node_verify -->|"precedes"| node_synthesis
node_scanflow -->|"dispatches models"| node_llm
node_llm -.->|"uses shared types"| node_models
node_synthesis -->|"emits findings"| node_report
node_scanflow -.->|"enriches findings"| node_enrichment
node_scanflow -->|"uses checkpoints"| node_checkpoints
node_cli -->|"resolves configuration"| node_configpaths
node_cli -->|"uses run state"| node_store
node_cli -->|"starts remediation"| node_remrunner
node_remrunner -->|"parses findings"| node_parse
node_remrunner -->|"invokes plugin"| node_plugin
node_plugin -->|"writes patch artifacts"| node_artifacts
node_remrunner -->|"saves progress"| node_checkpoints
node_cli -->|"starts validation"| node_validation
node_validation -.->|"executes plans"| node_execution
node_execution -->|"launches session"| node_session
node_execution -->|"collects results"| node_collector
node_execution -.->|"returns validation results"| node_scoring
node_session -.->|"uses model client"| node_validationbackend
node_report -->|"provides findings"| node_remrunner
node_artifacts -->|"supplies remediation DTOs"| node_validation

click node_cli "https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/cli.py"
click node_scanflow "https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/orchestrator/scan.py"
click node_preprocess "https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s1_preprocess.py"
click node_threat "https://github.com/ppd-ibm/vulnerability-agentic-harness/tree/main/vvaharness/pipeline/stages"
click node_decompose "https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s3_decompose.py"
click node_deepdive "https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s4_deepdive.py"
click node_verify "https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s6_verify.py"
click node_synthesis "https://github.com/ppd-ibm/vulnerability-agentic-harness/tree/main/vvaharness/pipeline/stages"
click node_report "https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/models.py"
click node_enrichment "https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/report/enrich.py"
click node_redaction "https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/report/redact.py"
click node_language "https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/lang/hints.py"
click node_models "https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/models.py"
click node_llm "https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/backends/llm.py"
click node_checkpoints "https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/orchestrator/checkpoints.py"
click node_configpaths "https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/orchestrator/config_paths.py"
click node_store "https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/orchestrator/store.py"
click node_remrunner "https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/remediation_agent/runner.py"
click node_parse "https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/remediation_agent/report_parser/parse.py"
click node_plugin "https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/remediation_agent/plugin_runner/run.py"
click node_artifacts "https://github.com/ppd-ibm/vulnerability-agentic-harness/tree/main/vvaharness/remediation_agent/artifacts"
click node_validation "https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/validation/cli/_run.py"
click node_execution "https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/validation/execution/pipeline.py"
click node_session "https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/validation/session/launcher.py"
click node_collector "https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/validation/io/result_collector.py"
click node_scoring "https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/validation/scoring/_engine.py"
click node_validationbackend "https://github.com/ppd-ibm/vulnerability-agentic-harness/tree/main/vvaharness/validation/backends"

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_scanflow,node_preprocess,node_threat,node_decompose,node_deepdive,node_verify,node_synthesis,node_report toneBlue
class node_enrichment,node_redaction,node_language,node_models,node_llm,node_checkpoints,node_configpaths,node_store toneAmber
class node_remrunner,node_parse,node_plugin,node_artifacts toneMint
class node_validation,node_execution,node_session,node_collector,node_scoring,node_validationbackend toneRose
class node_engineer,node_target toneIndigo
class node_cli toneTeal
```

## Components

### Discovery and Scan

- [Scan orchestrator](https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/orchestrator/scan.py): `vvaharness/orchestrator/scan.py`
- [Preprocess and scope](https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s1_preprocess.py): `vvaharness/pipeline/stages/s1_preprocess.py`
- [Threat modeling](https://github.com/ppd-ibm/vulnerability-agentic-harness/tree/main/vvaharness/pipeline/stages): `vvaharness/pipeline/stages`
- [Hunting plan](https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s3_decompose.py): `vvaharness/pipeline/stages/s3_decompose.py`
- [Deep analysis](https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s4_deepdive.py): `vvaharness/pipeline/stages/s4_deepdive.py`
- [Adversarial verification](https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s6_verify.py): `vvaharness/pipeline/stages/s6_verify.py`
- [Dedup and chain](https://github.com/ppd-ibm/vulnerability-agentic-harness/tree/main/vvaharness/pipeline/stages): `vvaharness/pipeline/stages`
- [Finding reports](https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/models.py): `vvaharness/models.py`

### Models and Integrations

- [Finding enrichment](https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/report/enrich.py): `vvaharness/report/enrich.py`
- [Sensitive-data redaction](https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/report/redact.py): `vvaharness/report/redact.py`
- [Language hints](https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/lang/hints.py): `vvaharness/lang/hints.py`
- [Finding data models](https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/models.py): `vvaharness/models.py`
- [Model backend routing](https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/backends/llm.py): `vvaharness/backends/llm.py`
- [Run checkpoints](https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/orchestrator/checkpoints.py): `vvaharness/orchestrator/checkpoints.py`
- [Configuration paths](https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/orchestrator/config_paths.py): `vvaharness/orchestrator/config_paths.py`
- [Run state store](https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/orchestrator/store.py): `vvaharness/orchestrator/store.py`

### Remediation

- [Remediation runner](https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/remediation_agent/runner.py): `vvaharness/remediation_agent/runner.py`
- [Finding parser](https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/remediation_agent/report_parser/parse.py): `vvaharness/remediation_agent/report_parser/parse.py`
- [Patch plugin](https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/remediation_agent/plugin_runner/run.py): `vvaharness/remediation_agent/plugin_runner/run.py`
- [Patch artifacts](https://github.com/ppd-ibm/vulnerability-agentic-harness/tree/main/vvaharness/remediation_agent/artifacts): `vvaharness/remediation_agent/artifacts`

### Validation

- [Validation command](https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/validation/cli/_run.py): `vvaharness/validation/cli/_run.py`
- [Validation execution](https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/validation/execution/pipeline.py): `vvaharness/validation/execution/pipeline.py`
- [Agent validation session](https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/validation/session/launcher.py): `vvaharness/validation/session/launcher.py`
- [Result collection](https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/validation/io/result_collector.py): `vvaharness/validation/io/result_collector.py`
- [Fix-quality scoring](https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/validation/scoring/_engine.py): `vvaharness/validation/scoring/_engine.py`
- [Validation model clients](https://github.com/ppd-ibm/vulnerability-agentic-harness/tree/main/vvaharness/validation/backends): `vvaharness/validation/backends`

### Other components

- **Authorized engineer**
- **Target repository**
- [Command interface](https://github.com/ppd-ibm/vulnerability-agentic-harness/blob/main/vvaharness/cli.py): `vvaharness/cli.py`

## Connections

- Authorized engineer → Command interface: runs commands (evidence: `README.md`)
- Command interface → Scan orchestrator: starts scan (evidence: `vvaharness/cli.py`)
- Scan orchestrator → Target repository: scans code (evidence: `README.md`)
- Scan orchestrator → Preprocess and scope: runs stage (evidence: `vvaharness/orchestrator/scan.py`)
- Scan orchestrator → Threat modeling: runs stage (evidence: `vvaharness/orchestrator/scan.py`)
- Scan orchestrator → Hunting plan: runs stage (evidence: `vvaharness/orchestrator/scan.py`)
- Scan orchestrator → Deep analysis: runs stage (evidence: `vvaharness/orchestrator/scan.py`)
- Scan orchestrator → Adversarial verification: runs stage (evidence: `vvaharness/orchestrator/scan.py`)
- Scan orchestrator → Dedup and chain: runs stages (evidence: `vvaharness/orchestrator/scan.py`)
- Preprocess and scope → Threat modeling: precedes (evidence: `README.md`)
- Threat modeling → Hunting plan: precedes (evidence: `README.md`)
- Hunting plan → Deep analysis: precedes (evidence: `README.md`)
- Deep analysis → Adversarial verification: precedes (evidence: `README.md`)
- Adversarial verification → Dedup and chain: precedes (evidence: `README.md`)
- Scan orchestrator → Model backend routing: dispatches models (evidence: `vvaharness/orchestrator/scan.py`)
- Model backend routing → Finding data models: uses shared types
- Dedup and chain → Finding reports: emits findings (evidence: `README.md`)
- Scan orchestrator → Finding enrichment: enriches findings (evidence: `vvaharness/orchestrator/scan.py`)
- Scan orchestrator → Run checkpoints: uses checkpoints (evidence: `vvaharness/orchestrator/scan.py`)
- Command interface → Configuration paths: resolves configuration (evidence: `vvaharness/cli.py`)
- Command interface → Run state store: uses run state (evidence: `vvaharness/cli.py`)
- Command interface → Remediation runner: starts remediation (evidence: `vvaharness/cli.py`)
- Remediation runner → Finding parser: parses findings (evidence: `vvaharness/remediation_agent/runner.py`)
- Remediation runner → Patch plugin: invokes plugin (evidence: `vvaharness/remediation_agent/runner.py`)
- Patch plugin → Patch artifacts: writes patch artifacts (evidence: `vvaharness/remediation_agent/plugin_runner/run.py`)
- Remediation runner → Run checkpoints: saves progress (evidence: `vvaharness/remediation_agent/runner.py`)
- Command interface → Validation command: starts validation (evidence: `README.md`)
- Validation command → Validation execution: executes plans
- Validation execution → Agent validation session: launches session (evidence: `vvaharness/validation/execution/pipeline.py`)
- Validation execution → Result collection: collects results (evidence: `vvaharness/validation/execution/pipeline.py`)
- Validation execution → Fix-quality scoring: returns validation results
- Agent validation session → Validation model clients: uses model client
- Finding reports → Remediation runner: provides findings (evidence: `README.md`)
- Patch artifacts → Validation command: supplies remediation DTOs (evidence: `README.md`)
