VVAH is Visa's open-source harness for autonomous vulnerability discovery, remediation, and validation using frontier AI models, built on learnings from Project Glasswing (Anthropic's initiative for AI-assisted vulnerability research).
VVAH runs as a four-phase, eleven-stage pipeline from code ingest to validated fix:
- Phase 1 — Discovery & Modeling (S1–S3): map the attack surface and build a threat-aware plan.
- Phase 2 — Deep Dive & Verification (S4–S6): run multi-lens analysis and adversarial verification to confirm exploitability.
- Phase 3 — Synthesis & Reporting (S7–S9): deduplicate, chain, and emit structured findings (Markdown + SARIF).
- Phase 4 — Remediation & Validation (S10–S11): propose candidate fixes and adversarially validate them before adoption.
Three design choices drive finding quality: threat modeling before analysis focuses the attack surface; multi-agent deterministic voting reduces false positives; and structured triage artifacts compress the lifecycle from AI-discovered weakness to actionable finding. The bottleneck in AI-assisted vulnerability management is triage speed, not discovery. VVAH is designed around that constraint. The primary effectiveness metric is Mean Time to Adapt (MTTA): elapsed time from AI-discovered exploitability to a validated fix in production.
Multi-model by design, VVAH works with Anthropic Claude, OpenAI-compatible models, or a combination via a vendor-neutral abstraction layer. No single provider is a hard dependency, although current remediation and validation capabilities require Anthropic models for full functionality.
For setup, see docs/SETUP_GUIDE.md. This repository is
not currently accepting external code contributions; see
CONTRIBUTING.md for details.
Authorized use only. Run scans only against code you own or have explicit permission to test. Findings and fixes are LLM-generated triage candidates that require human review — see Limitations.
Docs: SETUP_GUIDE.md — install & configuration · USER_GUIDE.md — commands & options · remediation.md · validation.md · Project Glasswing white paper — technical background.
pip install . # venv / pipx options under Install
vvaharness doctor # check credentials & backends
vvaharness estimate --repo /path/to/target # rough scope/cost — spends nothing
vvaharness scan --repo /path/to/target # detection only — ends at S9scan never remediates or validates and does not edit target source files.
Run the standalone remediate and validate commands explicitly when wanted.
New here? Follow Install → Configure → Run.
VVAH implements a nine-stage detection pipeline.
Nine detection stages combine deterministic controls with frontier-model reasoning to produce structured, exploit-validated findings.
| Stage group | Stages | Purpose |
|---|---|---|
| Discovery & Modeling | S1–S3 | Attack surface mapping, threat modeling, hunting plan |
| Deep Dive & Verification | S4–S6 | Multi-lens research, policy gates, adversarial verification |
| Synthesis, Chaining & Reporting | S7–S9 | Deduplication, chain construction, SARIF emission |
After detection, two standalone commands provide an explicit follow-up workflow:
scan— finds issues (S1–S9 detection pipeline above).remediate— proposes, and in fix mode applies, a minimal fix per finding.validate— checks those fixes with an agentic adversarial panel before they are treated as validated.
(The CLI also ships setup, doctor, estimate, and gc — run
vvaharness --help.)
Standardized inputs (batch repositories, GitHub Enterprise metadata, CMDB
records, CVE and control feeds) flow in; structured reports, SARIF artifacts,
remediation DTOs, and validation reports flow out. See
docs/architecture.md for stage-by-stage detail.
Each LLM-driven pipeline stage is implemented as a composable, reusable skill.
Two stages have no dedicated skill of their own: S9 (SARIF emission) is
fully deterministic, and S5 (pre-filter) runs deterministic gates plus one
optional semantic-dedup call that reuses the S7 dedup role — fired only when
the survivor count reaches step7_dedup.pre_verify_threshold (default 25) and
step7_dedup.semantic is on (default true). Skills can be independently tuned,
versioned, and replaced without rewiring the pipeline.
| Stage | Skill |
|---|---|
| S1 — Explore the attack surface | Attack surface mapper (code, CMDB, CVE, controls) |
| S2 — Model threats in business context | AppSec threat modeler (STRIDE, OWASP, trust boundaries) |
| S3 — Strategize and prioritize | Vulnerability research strategist (taint, API boundaries, authorization controls) |
| S4 — Research by specialized lens | Language, Crypto, Logic-bug, Access-control, Batch/ETL, IaC (Deserialization defined but not default-enabled — see docs/SKILLS.md) |
| S6 — Adversarial verification | Adversarial reviewer (exploit chain, trust boundary tracing) |
| S7 — Deduplicate findings | Finding deduplicator (semantic collapse of overlapping findings, atop a deterministic pass) |
| S8 — Chain construction and reporting | Exploit strategist (CWE, attack paths, remediation) |
| S10 — Remediation agent | Remediation playbooks per CWE–language–framework triple, generating candidate patches and remediation DTOs |
| S11 — Validation panel | Agentic adversarial panel (security-architect, penetration-tester, optional cross-repo-analyzer) scoring fixes against weighted gates |
The standalone validate command uses the S11 validation panel (Claude Agent
SDK) to grade each remediation DTO against fix-quality gates and emit verdicts
such as validated, validation_failed, and needs_review.
See docs/SKILLS.md for configuration and extension guidance
and docs/remediation.md /
docs/validation.md for S10/S11 behavior.
- Python ≥ 3.10
- An LLM credential — a Claude Code login (run
claudethen/login) for the default profile, or an Anthropic API key (ANTHROPIC_SDK_API_KEY) /OPENAI_API_KEYif you switch roles tovia: sdk/via: openai; see Configure. - The
claudeCLI — required for the default profile (every rolevia: cli); optional otherwise.
Recommended — install into a virtual environment (keeps the install isolated).
macOS / Linux:
python3 -m venv .venv
source .venv/bin/activate
pip install .Windows (PowerShell):
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install .Or install it as an isolated global command (no venv needed) on any OS:
pipx install .Either way this installs one command: vvaharness. All three backend adapters
(Anthropic SDK, Claude CLI, OpenAI-compatible) ship out of the box. The
Anthropic SDK and OpenAI backends need only an API key, but the Claude CLI
backend used by the default profile also requires the external claude CLI to
be installed separately (see Requirements).
macOS / Linux:
cp .env.example .env # then edit .env to add your credential (see below)Windows (PowerShell):
Copy-Item .env.example .env # then edit .envvvaharness loads a .env automatically — it is searched for starting in the
working directory and walking up the parent directories — so no manual source
step is needed. (Variables you export yourself still take precedence.)
Which credential you need depends on the backend each role uses:
via: cli(the default profile) — use a Claude Code session instead of an API key: runclaudethen/login, or setCLAUDE_CODE_OAUTH_TOKEN(fromclaude setup-token).via: sdk— setANTHROPIC_SDK_API_KEY. Behind a private gateway, also setANTHROPIC_SDK_BASE_URL(plusANTHROPIC_SDK_CA_CERT/ANTHROPIC_SDK_CLIENT_CERTfor mTLS).via: openai— setOPENAI_API_KEY(andOPENAI_BASE_URLfor an OpenAI-compatible endpoint).
The default profile (vvaharness/config/profiles/default.yaml) runs detection
stages (S1–S8) through the claude CLI, with the remediation (S10) and
validation (S11) roles pinned to a higher-tier model — all via: cli, so your
Claude Code login is enough, no SDK key required. (sdk.yaml runs the same
roles via the Anthropic SDK instead — set ANTHROPIC_SDK_API_KEY — and turns
on S4 majority voting.) To use the multi-backend layout (Claude CLI +
Anthropic SDK + OpenAI roles), copy vvaharness/config/profiles/full.yaml to
./config.yaml and edit it.
For a step-by-step walkthrough — picking a profile, config resolution order,
secrets in .env, and copy-then-edit customization — see
docs/configuration.md → Setting up your config.
vvaharness scan --repo /path/to/target --application-id 12345 # detection-only S1–S9
vvaharness remediate --repo /path/to/target # optional; may edit source
vvaharness validate --repo /path/to/target # optional follow-upRun the complete project test suite (all modules under tests/):
vvaharness test
vvaharness test -x # forward pytest flags
vvaharness test --root /path/to/threatweaverThe command covers s1–s9, ASAN and adaptive verification planning,
orchestration, CLI, reports, remediation, and validation. It must be
run from a source checkout (or with --root) because the tests are source files,
not scan-time product data.
Batch (clone + scan, one report per AppId):
vvaharness scan --repo-file repos.csv --workspace ./scans --group-by-app --keep-clonesA scan run writes run_manifest.json (tool version, model roles, config hash,
target git SHA, timing) into the working directory. (doctor and estimate do
no scan and write no manifest.)
vvaharness validate checks the fixes that remediate produced. It discovers
the per-finding reports under
<repo>/security-remediation/<NN_slug>/remediate_report.json, then runs an
agentic adversarial panel (Claude Agent SDK) that scores each fix and records a
verdict (validated, validation_failed, or needs_review). The panel is
read-only — it reads the repo and writes only its own validation artifacts,
never applies a patch, and runs no Docker. Re-runs are idempotent.
vvaharness validate --repo /path/to/targetValidation is Anthropic-only (models.validate must run via: cli or
via: sdk); a via: openai validate role is refused (the validate step aborts
with exit code 2). For the panel personas, weighted gates, and verdict
thresholds, see docs/validation.md and
docs/remediation.md.
vvaharness setup --install-agentsThis detects your installed agent(s) and drops the operating instructions where
each one reads them — AGENTS.md (cross-tool), .github/copilot-instructions.md
(Copilot), CLAUDE.md + a Claude skill in ~/.claude/skills/ (Claude Code),
GEMINI.md (Gemini CLI). Existing files are left untouched. See
AGENTS.md for the operating rules and docs/SKILLS.md
for the analysis capabilities.
Per target, under <target>/security-scan/:
<module>_<ts>_report.md— findings + dropped-findings appendix<module>_<ts>_report.sarif— SARIF 2.1.0<module>_<ts>_errors.jsonl— non-fatal errors
The standalone remediate command writes
<target>/security-remediation/<NN_slug>/remediate_report.json and may edit
source files when run in fix mode. scan itself does neither.
run_manifest.json is written to the working directory.
Pipeline checkpoints and resume state are kept outside the scanned repo, in
a SQLite state DB at $VVAHARNESS_STATE_DIR/vvaharness.db (default
~/.vvaharness/state/); prune old runs with vvaharness gc.
Stage 6 stores static verification and ASAN verification as separate
checkpoints, so --resume can continue ASAN without repeating completed static
verification.
- LLM-generated, non-deterministic. Findings and fixes are triage candidates,
not confirmed vulnerabilities or production-ready patches — human review is
required. Two runs may differ. Majority-vote FP filtering runs on the
sdkandopenaibackends; theclibackend (no temperature control) always runs single-pass, as do SDK/OpenAI models that rejecttemperature. - Token-hungry. Caps are per-stage / per-finding, not global. Use
vvaharness estimateand thestep*.max_budget_usdknobs. - No published accuracy numbers yet. Precision/recall figures are not yet published.
- Elevated privilege. This tool runs with elevated privilege and must only be
used against trusted repositories by authorized operators. Running VVAH
against untrusted or malicious input may expose host credentials, API keys,
and sensitive files. If you must scan a less-trusted target, see
docs/security.md→ Hardening for less-trusted or sensitive targets. - Validation (S11) is Anthropic-only. The validation panel runs only on
Anthropic models (
via: cliorvia: sdk); avia: openaivalidate role is refused. - Remediation fix mode is effectively Anthropic-only. Applying a fix needs
the agent's file-mutation tools (
Edit/Write), which only thevia: cliandvia: sdkbackends expose; the OpenAI-compatible backend is sandboxed to Read/Glob/Grep and cannot edit files. Avia: openaimodels.remediaterole therefore can only run--mode report-only. - Review remediation fixes before you rely on them. The remediation agent proposes — and in fix mode applies — code changes, but VVAH does not compile, build, or run tests against the patched tree. Always review the generated fixes and build/test them yourself before merging.
See docs/ for configuration, models, pipeline, and output details.
Report vulnerabilities responsibly — see SECURITY.md. Please do not open security issues in a public tracker.
Licensed under the Apache License, Version 2.0 — see LICENSE and NOTICE. Copyright 2026 Visa, Inc.
Third-party dependencies are installed from PyPI at install time (not bundled in this repository); their licenses are inventoried in THIRD_PARTY_LICENSES.md.
See CHANGELOG.md for release history.