How suve362/visa-vulnerability-agentic-harness works
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: entry.py Scan entry · sdk.py Backend dispatch · s8_chain.py Exploit-chain synthesis · s1_preprocess.py S1–S9 detection flow
Components 22
Control Plane
CLI orchestration and resumable scan state.
- vvaharness command · Installed entry point for scan and validation commands.
vvaharness/cli.py - Scan entry · Resolves targets, configuration, and scan execution.
vvaharness/orchestrator/entry.py - Batch runner · Runs scans across CSV-provided repositories.
vvaharness/orchestrator/batch.py - Checkpoint store · Stores resumable checkpoints and run manifests outside targets.
vvaharness/orchestrator/checkpoints.py
Detection Pipeline
Staged SAST analysis through report synthesis.
- S1–S9 detection flow · Runs staged analysis from preprocessing to synthesis.
vvaharness/pipeline/stages/s1_preprocess.py - Threat modeling · Maps attack surface and decomposes research work.
vvaharness/pipeline/stages/s2_threatmodel.py - Specialist deep dives · Performs role-driven focused security analysis.
vvaharness/pipeline/stages/s4_deepdive.py - Adversarial verification · Verifies candidate vulnerabilities after prefiltering.
vvaharness/pipeline/stages/s6_verify.py - Finding deduplication · Collapses overlapping verified findings.
vvaharness/pipeline/stages/s7_dedup.py - Exploit-chain synthesis · Builds exploit chains and deterministic SARIF output.
vvaharness/pipeline/stages/s8_chain.py
Model Trust Boundary
Role dispatch across constrained model backends.
- Model profiles · Selects models, roles, and execution strategy.
vvaharness/config/profiles/default.yaml - Backend dispatch · Routes role requests to configured model runtimes.
vvaharness/backends/sdk.py - Claude CLI · Default runtime with mutation-capable tooling.
vvaharness/backends/claude_cli.py - OpenAI-compatible API · 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 · Selects playbooks, proposes fixes, and may mutate the target.
vvaharness/remediation_agent/remediate.py - Mutation policy gates · Applies controls before and after target mutation.
vvaharness/remediation_agent/policy_gate/gate.py - security-remediation artifacts · Captures patches, snapshots, and per-finding remediation reports.
vvaharness/remediation_agent/artifacts/diff/synth.py - S11 adversarial validation · Anthropic-only persona panel scores remediation fixes.
vvaharness/validation/execution/pipeline.py - Weighted verdict scoring · Evaluates fixes against weighted gates.
vvaharness/validation/scoring/_engine.py
Findings & Outputs
Enrichment, redaction, and target-repository artifacts.
- External context feeds · Injects CVE and repository context into analysis.
vvaharness/injectors/cve_feed.py - Finding enrichment · Adds CWE/CVSS and operational context.
vvaharness/report/enrich.py - security-scan outputs · Redacted reports written inside the scanned target.
vvaharness/report/redact.py
Connections 23
- 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