# suve362/visa-vulnerability-agentic-harness architecture

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

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

## Overview

#### Purpose and Entry Points
VVAH is a Python 3.10+ agentic SAST harness: it discovers vulnerabilities, produces Markdown/SARIF findings, can apply LLM-generated remediation, then adversarially validates fixes. The installed `vvaharness` command enters through `vvaharness/__main__.py` and `vvaharness/cli.py`; scan orchestration begins in `vvaharness/orchestrator/entry.py`.

#### Execution Orchestration and Persistence
The scan command resolves target/configuration, runs preflight checks, supports single-repo or CSV batch operation, and persists resumable checkpoints outside the target repository in SQLite. Run metadata/manifests capture versions, model roles, config hash, target SHA, and timing.
- `vvaharness/orchestrator/entry.py`
- `vvaharness/orchestrator/batch.py`
- `vvaharness/orchestrator/checkpoints.py`
- `vvaharness/orchestrator/store.py`

#### Detection Pipeline (S1–S9)
The primary detection flow is staged: preprocessing/automatic exclusions; attack-surface mapping; threat modeling; research-plan decomposition; specialized deep dives; deterministic/semantic prefiltering; adversarial verification; finding deduplication; and exploit-chain/report synthesis. S9 SARIF emission is deterministic; model-driven stages are expressed as reusable role/skill prompts.
- `vvaharness/pipeline/stages/s1_preprocess.py`
- `vvaharness/pipeline/stages/s2_threatmodel.py`
- `vvaharness/pipeline/stages/s4_deepdive.py`
- `vvaharness/pipeline/stages/s6_verify.py`
- `vvaharness/pipeline/stages/s7_dedup.py`
- `vvaharness/pipeline/stages/s8_chain.py`

#### Models, Backends, and Trust Boundary
A backend abstraction dispatches model roles to Claude CLI, Anthropic SDK, OpenAI-compatible APIs, or local deterministic tools. Profiles select roles/models and execution strategy. Credentials come from environment/.env; SDK connections can use private endpoints and mTLS. Claude CLI is the default runtime; OpenAI remediation is constrained to read-only/report-only because it lacks mutation tools.
- `vvaharness/backends/claude_cli.py`
- `vvaharness/backends/sdk.py`
- `vvaharness/backends/oai.py`
- `vvaharness/config/profiles/default.yaml`

#### Findings and Output Boundary
The pipeline normalizes/enriches findings with CWE/CVSS information, redacts output, and writes reports into the scanned target’s `security-scan/` directory. Outputs are Markdown, SARIF 2.1.0, and JSONL non-fatal errors; external feeds can inject CVE, design-control, CMDB, language-hint, and repository metadata context.
- `vvaharness/report/enrich.py`
- `vvaharness/report/redact.py`
- `vvaharness/orchestrator/enrich_findings.py`
- `vvaharness/injectors/cve_feed.py`
- `vvaharness/orchestrator/cmdb.py`

#### Remediation (S10)
Given synthesized findings, the remediation agent selects playbooks by CWE/language/framework, proposes minimal changes, and in fix mode may modify the target repository. It captures patch/snapshot artifacts, emits per-finding remediation DTO/report artifacts under `security-remediation/`, and applies policy gates before/after mutation.
- `vvaharness/remediation_agent/remediate.py`
- `vvaharness/remediation_agent/runner.py`
- `vvaharness/remediation_agent/policy_gate/gate.py`
- `vvaharness/remediation_agent/artifacts/diff/synth.py`

#### Validation (S11)
The standalone or scan-integrated validation stage ingests remediation DTOs, creates a workspace manifest, and runs an Anthropic-only adversarial persona panel. It is read-only with respect to code changes, scores fixes against weighted gates, records verdicts, and augments remediation reports. Validation rejects OpenAI roles.
- `vvaharness/pipeline/stages/s11_validate.py`
- `vvaharness/validation/execution/pipeline.py`
- `vvaharness/validation/backends/registry.py`
- `vvaharness/validation/scoring/_engine.py`
- `vvaharness/validation/report/augment.py`

Main entry points: [`vvaharness/orchestrator/entry.py`](https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/orchestrator/entry.py) (Scan entry), [`vvaharness/backends/sdk.py`](https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/backends/sdk.py) (Backend dispatch), [`vvaharness/pipeline/stages/s8_chain.py`](https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s8_chain.py) (Exploit-chain synthesis), [`vvaharness/pipeline/stages/s1_preprocess.py`](https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s1_preprocess.py) (S1–S9 detection flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control Plane"]
  node_cli["vvaharness command<br/>Python CLI<br/>[cli.py]"]
  node_scan_entry["Scan entry<br/>orchestrator<br/>[entry.py]"]
  node_batch["Batch runner<br/>CSV batch mode<br/>[batch.py]"]
  node_checkpoint_store[("Checkpoint store<br/>SQLite persistence<br/>[checkpoints.py]")]
end

subgraph group_detection["Detection Pipeline"]
  node_pipeline["S1–S9 detection flow<br/>pipeline coordinator<br/>[s1_preprocess.py]"]
  node_threat_model["Threat modeling<br/>S2 stage<br/>[s2_threatmodel.py]"]
  node_deep_dive["Specialist deep dives<br/>S4 stage<br/>[s4_deepdive.py]"]
  node_verify["Adversarial verification<br/>S6 stage<br/>[s6_verify.py]"]
  node_dedup["Finding deduplication<br/>S7 stage<br/>[s7_dedup.py]"]
  node_synthesis["Exploit-chain synthesis<br/>S8/S9 reporting<br/>[s8_chain.py]"]
end

subgraph group_models["Model Trust Boundary"]
  node_profiles["Model profiles<br/>YAML profiles<br/>[default.yaml]"]
  node_backend_dispatch{{"Backend dispatch<br/>model abstraction<br/>[sdk.py]"}}
  node_claude["Claude CLI<br/>default model runtime<br/>[claude_cli.py]"]
  node_openai["OpenAI-compatible API<br/>restricted backend<br/>[oai.py]"]
end

subgraph group_remediation["Remediation &amp; Validation"]
  node_remediation["S10 remediation agent<br/>fix workflow<br/>[remediate.py]"]
  node_policy_gate["Mutation policy gates<br/>policy enforcement<br/>[gate.py]"]
  node_remediation_artifacts["security-remediation artifacts<br/>patches and DTOs<br/>[synth.py]"]
  node_validation["S11 adversarial validation<br/>read-only validation<br/>[pipeline.py]"]
  node_scoring["Weighted verdict scoring<br/>validation scoring<br/>[_engine.py]"]
end

subgraph group_outputs["Findings &amp; Outputs"]
  node_context_feeds["External context feeds<br/>security context<br/>[cve_feed.py]"]
  node_finding_enrichment["Finding enrichment<br/>normalization<br/>[enrich.py]"]
  node_reports["security-scan outputs<br/>Markdown, SARIF, JSONL<br/>[redact.py]"]
end

node_cli -->|"starts scan"| node_scan_entry
node_scan_entry -.->|"batch mode"| node_batch
node_scan_entry -->|"persists run state"| node_checkpoint_store
node_scan_entry -->|"runs S1–S9"| node_pipeline
node_profiles -->|"configures roles"| node_backend_dispatch
node_pipeline -->|"S2"| node_threat_model
node_threat_model -->|"research plan"| node_deep_dive
node_deep_dive -->|"candidates"| node_verify
node_verify -->|"verified findings"| node_dedup
node_dedup -->|"unique findings"| node_synthesis
node_backend_dispatch -->|"default runtime"| node_claude
node_backend_dispatch -.->|"restricted runtime"| node_openai
node_context_feeds -->|"CVE and repo context"| node_finding_enrichment
node_synthesis -->|"findings"| node_finding_enrichment
node_finding_enrichment -->|"redact and emit"| node_reports
node_synthesis -->|"synthesized findings"| node_remediation
node_remediation -->|"before/after mutation"| node_policy_gate
node_policy_gate -->|"approved fix artifacts"| node_remediation_artifacts
node_remediation_artifacts -->|"remediation DTOs"| node_validation
node_validation -->|"persona evidence"| node_scoring
node_scoring -->|"augmented verdicts"| node_remediation_artifacts
node_backend_dispatch -.->|"model roles"| node_pipeline
node_claude -->|"Anthropic-only panel"| node_validation

click node_cli "https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/cli.py"
click node_scan_entry "https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/orchestrator/entry.py"
click node_batch "https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/orchestrator/batch.py"
click node_checkpoint_store "https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/orchestrator/checkpoints.py"
click node_pipeline "https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s1_preprocess.py"
click node_threat_model "https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s2_threatmodel.py"
click node_deep_dive "https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s4_deepdive.py"
click node_verify "https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s6_verify.py"
click node_dedup "https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s7_dedup.py"
click node_synthesis "https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s8_chain.py"
click node_profiles "https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/config/profiles/default.yaml"
click node_backend_dispatch "https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/backends/sdk.py"
click node_claude "https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/backends/claude_cli.py"
click node_openai "https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/backends/oai.py"
click node_context_feeds "https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/injectors/cve_feed.py"
click node_finding_enrichment "https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/report/enrich.py"
click node_reports "https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/report/redact.py"
click node_remediation "https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/remediation_agent/remediate.py"
click node_policy_gate "https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/remediation_agent/policy_gate/gate.py"
click node_remediation_artifacts "https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/remediation_agent/artifacts/diff/synth.py"
click node_validation "https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/validation/execution/pipeline.py"
click node_scoring "https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/validation/scoring/_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_scan_entry,node_batch,node_checkpoint_store toneBlue
class node_pipeline,node_threat_model,node_deep_dive,node_verify,node_dedup,node_synthesis toneAmber
class node_profiles,node_backend_dispatch,node_claude,node_openai toneMint
class node_remediation,node_policy_gate,node_remediation_artifacts,node_validation,node_scoring toneRose
class node_context_feeds,node_finding_enrichment,node_reports toneIndigo
```

## Components

### Control Plane

CLI orchestration and resumable scan state.

- [vvaharness command](https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/cli.py): Python CLI · Installed entry point for scan and validation commands. · `vvaharness/cli.py`
- [Scan entry](https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/orchestrator/entry.py): orchestrator · Resolves targets, configuration, and scan execution. · `vvaharness/orchestrator/entry.py`
- [Batch runner](https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/orchestrator/batch.py): CSV batch mode · Runs scans across CSV-provided repositories. · `vvaharness/orchestrator/batch.py`
- [Checkpoint store](https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/orchestrator/checkpoints.py): SQLite persistence · Stores resumable checkpoints and run manifests outside targets. · `vvaharness/orchestrator/checkpoints.py`

### Detection Pipeline

Staged SAST analysis through report synthesis.

- [S1–S9 detection flow](https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s1_preprocess.py): pipeline coordinator · Runs staged analysis from preprocessing to synthesis. · `vvaharness/pipeline/stages/s1_preprocess.py`
- [Threat modeling](https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s2_threatmodel.py): S2 stage · Maps attack surface and decomposes research work. · `vvaharness/pipeline/stages/s2_threatmodel.py`
- [Specialist deep dives](https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s4_deepdive.py): S4 stage · Performs role-driven focused security analysis. · `vvaharness/pipeline/stages/s4_deepdive.py`
- [Adversarial verification](https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s6_verify.py): S6 stage · Verifies candidate vulnerabilities after prefiltering. · `vvaharness/pipeline/stages/s6_verify.py`
- [Finding deduplication](https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s7_dedup.py): S7 stage · Collapses overlapping verified findings. · `vvaharness/pipeline/stages/s7_dedup.py`
- [Exploit-chain synthesis](https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/pipeline/stages/s8_chain.py): S8/S9 reporting · Builds exploit chains and deterministic SARIF output. · `vvaharness/pipeline/stages/s8_chain.py`

### Model Trust Boundary

Role dispatch across constrained model backends.

- [Model profiles](https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/config/profiles/default.yaml): YAML profiles · Selects models, roles, and execution strategy. · `vvaharness/config/profiles/default.yaml`
- [Backend dispatch](https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/backends/sdk.py): model abstraction · Routes role requests to configured model runtimes. · `vvaharness/backends/sdk.py`
- [Claude CLI](https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/backends/claude_cli.py): default model runtime · Default runtime with mutation-capable tooling. · `vvaharness/backends/claude_cli.py`
- [OpenAI-compatible API](https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/backends/oai.py): restricted backend · Limited to read-only and report-only remediation use. · `vvaharness/backends/oai.py`

### Remediation & Validation

Optional mutation followed by read-only adversarial assessment.

- [S10 remediation agent](https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/remediation_agent/remediate.py): fix workflow · Selects playbooks, proposes fixes, and may mutate the target. · `vvaharness/remediation_agent/remediate.py`
- [Mutation policy gates](https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/remediation_agent/policy_gate/gate.py): policy enforcement · Applies controls before and after target mutation. · `vvaharness/remediation_agent/policy_gate/gate.py`
- [security-remediation artifacts](https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/remediation_agent/artifacts/diff/synth.py): patches and DTOs · Captures patches, snapshots, and per-finding remediation reports. · `vvaharness/remediation_agent/artifacts/diff/synth.py`
- [S11 adversarial validation](https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/validation/execution/pipeline.py): read-only validation · Anthropic-only persona panel scores remediation fixes. · `vvaharness/validation/execution/pipeline.py`
- [Weighted verdict scoring](https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/validation/scoring/_engine.py): validation scoring · Evaluates fixes against weighted gates. · `vvaharness/validation/scoring/_engine.py`

### Findings & Outputs

Enrichment, redaction, and target-repository artifacts.

- [External context feeds](https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/injectors/cve_feed.py): security context · Injects CVE and repository context into analysis. · `vvaharness/injectors/cve_feed.py`
- [Finding enrichment](https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/report/enrich.py): normalization · Adds CWE/CVSS and operational context. · `vvaharness/report/enrich.py`
- [security-scan outputs](https://github.com/suve362/visa-vulnerability-agentic-harness/blob/main/vvaharness/report/redact.py): Markdown, SARIF, JSONL · Redacted reports written inside the scanned target. · `vvaharness/report/redact.py`

## Connections

- vvaharness command → Scan entry: starts scan
- Scan entry → Batch runner: batch mode
- Scan entry → Checkpoint store: persists run state
- Scan entry → S1–S9 detection flow: runs S1–S9
- Model profiles → Backend dispatch: configures roles
- S1–S9 detection flow → Threat modeling: S2
- Threat modeling → Specialist deep dives: research plan
- Specialist deep dives → Adversarial verification: candidates
- Adversarial verification → Finding deduplication: verified findings
- Finding deduplication → Exploit-chain synthesis: unique findings
- Backend dispatch → Claude CLI: default runtime
- Backend dispatch → OpenAI-compatible API: restricted runtime
- External context feeds → Finding enrichment: CVE and repo context
- Exploit-chain synthesis → Finding enrichment: findings
- Finding enrichment → security-scan outputs: redact and emit
- Exploit-chain synthesis → S10 remediation agent: synthesized findings
- S10 remediation agent → Mutation policy gates: before/after mutation
- Mutation policy gates → security-remediation artifacts: approved fix artifacts
- security-remediation artifacts → S11 adversarial validation: remediation DTOs
- S11 adversarial validation → Weighted verdict scoring: persona evidence
- Weighted verdict scoring → security-remediation artifacts: augmented verdicts
- Backend dispatch → S1–S9 detection flow: model roles
- Claude CLI → S11 adversarial validation: Anthropic-only panel