visa-vulnerability-agentic-harness - Visa Vulnerability Agentic Harness

项目说明

<!--
Copyright 2026 Visa, Inc.

Licensed under the Apache License, 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language go permissions and
limitations under the License.
-->

Visa Agentic Harness — Agentic Discovery, Remediation, and

!License
!Python
!
!Output

VVAH is Visa's open-source harness for autonomous discovery,
remediation, and using large language models, built on learnings from
Project Glasswing (Anthropic's
initiative for AI-assisted research).

V a four-phase pipeline: an S0 static seed followed by detection
and reporting (S1–S9), with optional remediation and (S10–S11).
The shipped default.yaml and full.yaml profiles derive that seed from the
model; taint.yaml uses rules mode, which needs operator-supplied source/sink
YAML. The four phases:

Phase 1 — Discovery & Modeling (S1–S3): map the attack surface and build a

threat-aware plan.

Phase 2 — Deep Dive & (S4–S6): run multi-lens analysis and

ad to assess likely exploitability.

Phase 3 — Synthesis & Reporting (S7–S9): deduplicate, chain, and emit

structured findings (Markdown + SARIF).

Phase 4 — Remediation & (S10–S11, optional): propose candidate

fixes and ad them before adoption. Disabled in the shipped
default profile, which stops after Phase 3 (S9). See
Run your first scan for how to enable these stages.

Three design choices dri quality: threat modeling before analysis
focuses the attack surface; multi-agent deterministic reduces false
positives; and structured triage artifacts compress the lifecycle from
AI-discovered weakness to actionable finding. The bottleneck in AI-assisted
management is triage speed, not discovery. VVAH is designed
around that constraint. The primary effecti metric is **Mean Time to
Adapt (MTTA)**: elapsed time from AI-discovered exploitability to a
fix in production.

Multi-model by design. Every model-driven role — S0 through S11 — can be
pointed at its own model and provider:

Anthropic Claude — nati

OpenAI-compatible — OpenAI models and any OpenAI-compatible gateway

Open-weight — served over Chat Completions-compatible endpoints

No single provider is a hard dependency. Detection and remediation/
draw on the same set; see docs/models.md for the per-role
matrix.

For setup, see docs/SETUP_GUIDE.md. GitHub Issues are
open for bug, documentation, setup, and feature-request reports — see
Reporting issues. 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 ha
> permission to test. Findings and fixes are LLM-generated triage candidates
> that require human review — see Limitations.
>
> Data egress warning. Any role routed to via: cli, via: sdk,
> via: openai, or via: deepagents sends prompt data to that model provider
> endpoint (Anthropic/OpenAI or your configured gateway). Use only approved
> endpoints and scan targets you are authorized to process.

Docs: docs/ — full documentation index ·
SETUP_GUIDE.md — install & configuration ·
USER_GUIDE.md — commands & options ·
models.md — model/backend selection ·
remediation.md · .md ·
Project Glasswing white paper — technical background.

---

What's new in 1.4

Exploit (S6) — VVAH can now prove a finding is exploitable by

attacking it with real HTTP traffic, so a confirmed finding arrives with
e attached instead of waiting on a human to reproduce it. That is a
direct move on MTTA: confirming exploitability is usually the slowest manual
step between an AI-discovered weakness and a fix. Additive and
positi — it ne a finding, and the static keeps the
. Beta, API-only, localhost-only, and off unless
E is set — see
Exploit below for
the full safety constraints.

e — regression-test your fix with the exploit that

found the bug. After you patch and redeploy, replay re-runs the confirmed
attack against the target and tells you whether it still lands — a regression
test derived from the attack itself, not from a guess about it. We are not
aware of another open-source harness that closes that loop.

--stop-after ev — a collection and target with no model spend

Exploit- credentials — EV's own auth credentials are read only

from E* en , never from a profile or a CLI flag, and
a collection may name the auth *scheme* but never a value. Other secrets can
still reach the target on the wire: a token sa the collection's own
requests, the client-key passphrase EPHRASE, and any
hardcoded credential the attacker agent finds in the repo and replays.

---

Features

From detection to a graded fix — the S0–S11 pipeline combines threat-

modeled discovery, deep-di, ad , reporting,
remediation, and fix .

Threat-aware analysis — threat modeling and multi-lens research focus review

on the attack surface that matters.

Reachable-code analysis — AST/call-graph seeding focuses model review on

relevant code paths rather than the whole repo.

Real data-flow e — interprocedural taint analysis complements

model-based review across supported application languages.

Co backstop — unrecognised files can be added to catch-all review

chunks instead of being silently excluded. The backstop is best-effort, not a
guarantee; see docs/security.md for co guidance.

Proof, not just suspicion *(Beta — API only)* — optional exploit

attacks a candidate finding over live HTTP and reports back
whether it is really exploitable, and e re-runs that same exploit
after you ship the fix. Off unless you arm it; see
Exploit .

Actionable output — produce Markdown and SARIF 2.1.0 reports with CVSS,

CWE, and per-run diagnostics.

Your models and gateway — use Anthropic or OpenAI-compatible models through

cli, sdk, openai, or deepagents routes, configured per role.

Portfolio-scale operations — scan CS repositories with resumable

state and monitor long-running work through stderr output or the optional
--s6-progress-file artifact.

See docs/features.md for the full capability reference,
including backend and stage details, specialist lenses, taint analysis, and
limitations.

---

Quick start

Prerequisites

Python 3.11 or newer.

Permission to scan the target repository.

One Anthropic credential for the packaged default profile:

ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, or ANTHROPIC_SDK_API_KEY.
Claude Code CLI auth (run claude, then /login; or claude setup-token)
is optional and needed only for a role you configure with via: cli; no
shipped profile does.

Credential and profile details are in docs/SETUP_GUIDE.md
and docs/models.md.

Install and configure

macOS / Linux

Windows PowerShell

pipx install . is an alternative. For platform-specific setup, TLS/proxy notes, editable installs, and profile selection, use docs/SETUP_GUIDE.md.

Check the installation

For the full configuration reference, see docs/configuration.md and docs/models.md.

Run your first scan

Step 1 — Detection only, no code edits. Always start here:

Step 2 — Review the Markdown report and SARIF output in
/path/to/your/repo/security-scan/.

Step 3 (optional) — When ready, explicitly enable remediation in a scan.
This can edit source files:

The packaged default sets step_remediate.enabled: false and
step_.enabled: false. --remediate enables S10 only, not S11; run
standalone afterward to grade the fixes. In-scan S11 requires
step_.enabled: true in the effecti (no scan --
flag). Other configs or a local o can change these defaults; keep
--stop-after s9 to explicitly skip S10/S11 with any profile.

Alternatively, after a detection-only run, remediate and independently:

For command flags and troubleshooting, see USER_GUIDE.md.

Use with an AI agent (Claude / Copilot / Gemini)

This writes AGENTS.md (cross-tool) and .github/copilot-instructions.md
(Copilot) unconditionally; when the claude CLI is detected it also writes
CLAUDE.md + a Claude skill in ~/.claude/skills/ (Claude Code), and when the
gemini CLI is detected it writes GEMINI.md (Gemini CLI). Existing files are
left untouched. See docs/SKILLS.md for the analysis capabilities.

---

Pipeline

V an S0 static seed plus an ele workflow. The common
operator path is detection through S9. The shipped default profile disables
S10 remediation and S11 ; sdk and full still enable both, while
taint also leaves them off. These stages remain a by explicit opt-in
or standalone commands.

| Stage group | Stages | Purpose |
|---|---|---|
| Static seed (optional) | S0 | Source/sink callgraph seed for taint-first scanning |
| Discovery & Modeling | S1–S3 | Attack surface mapping, threat modeling, hunting plan |
| Deep Dive & | S4–S6 | Multi-lens research, policy gates, ad |
| Synthesis, Chaining & Reporting | S7–S9 | Deduplication, chain construction, SARIF emission |
| Remediation & | S10–S11 | Candidate fixes and ad fix |

For stage-by-stage internals, see docs/architecture.md.
For every command and flag, see docs/USER_GUIDE.md.

---

Skills

The pipeline combines stage prompts, language-specific lenses, specialist
security lenses, remediation playbooks, and personas. See
docs/SKILLS.md for the full capability in, and
docs/features.md for how those capabilities are selected by
configuration.

---

Exploit (S6) — Beta (API only)

What you get. Exploit proves a finding is really exploitable by
attacking it with live HTTP traffic, so the finding reaches you with e
attached rather than waiting in a queue for someone to reproduce it by hand.
That is aimed squarely at MTTA, VVAH's primary metric: for findings that map
to an endpoint, it removes the slowest manual step between an AI-discovered
weakness and a fix. It is positi and additive — a
confirmation is a fact you can act on, a non-confirmation means *not proven*
(never *safe*), and nothing is e because E not reach it.

And e closes the loop. Once you ha and redeployed,
e re-runs the exploit that found the bug against the same
target — a regression test derived from the attack itself, not from a guess about
it. We are not aware of another open-source harness that does this.

Now the constraints. EV is an optional S6 add-on, in Beta. "API only"
means it needs a Postman/OpenAPI/Swagger collection and can only findings
that map to an HTTP endpoint; off-wire classes stay SAST-only. It is off by
default — it arms when E is set (including a stale value left
in .env), with no CLI flag. It is not a sandbox: it sends real HTTP
requests (POST always, and PUT/PATCH on every shipped profile) to a live
target, and a reachability pass calls every distinct path in your collection
with its example body — downgrading any method the run has not opted into to
OPTIONS, so a DELETE route is ne exercised there — before any
finding is selected, so arming it is li even when nothing maps to an
endpoint. Its destination is pinned in code to a localhost/loopback host —
enforced in code rather than left to con — which establishes where EV
sends, not what is listening there, so pointing it only at a disposable local
instance you are authorized to attack is the operator's job. See
docs/exploit-.md for supported collections, safety
rules, and setup, and the Limitations note below.

---

Output

Per target, under <target>/security-scan/:

findings.json — typed FinalReport JSON

<module>_<ts>_report.md — findings + dropped-findings appendix

<module>_<ts>_report.sarif — SARIF 2.1.0

<module>_<ts>_errors.jsonl — non-fatal errors, written only when one is logged

With S10 enabled by config or --remediate, a successful remediation session
can also write <target>/security-remediation/<NN_slug>/finding_case.json and
edit source files in the target repo (fix mode — see
Run your first scan). The packaged default skips S10/S11;
--stop-after s9 explicitly skips them with any profile.
A timestamped 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 $/.db (default
~/./state/); prune old runs with gc.

For report, SARIF, findings.json, remediation, , and manifest
schemas, see docs/outputs.md.

---

Limitations (read before you trust output)

LLM-generated, non-deterministic. Findings and fixes are triage candidates,

not confirmed or production-ready patches. Human review is
required, and runs may differ.

No compilation or execution. V the target and does not build,

run, or test it; findings are ne by execution. No shipped profile
grants the agent Bash. Exploit is the one component that
generates traffic, and only against a target you are already running.

No published accuracy numbers yet. Precision and recall have not been

published.

Co is bounded, not complete. Stage caps, failed or timed-out chunks,

unsupported languages, and non-path-sensiti analysis can leave code
unre. See docs/security.md for co guidance.

Enabled remediation modifies the target. The default and taint

profiles disable S10/S11; full and sdk still enable them. --remediate
enables S10 only. Use --stop-after s9 to explicitly skip both stages with
any profile.

Review remediation fixes before you rely on them. VVAH does not build or

test patched code; review and test generated fixes before merging.

Elevated pri. Run VVAH only against authorized, trusted repositories;

prompt data may expose sensiti or credentials to configured pro.

Exploit (S6) is Beta, API only, and localhost-only. It exists to remove the

slowest manual step in triage — proving a finding is really exploitable — and
the price of that e is li traffic, so it is a trade to make
deliberately rather than by accident. When armed it sends real
HTTP requests — POST always, plus state-changing methods on every shipped
profile — to a running target; its destination is pinned in code to a localhost
address, which fixes where it sends but not what is listening there, so
confirming the target is yours to do. "API only" means it works from a
Postman/OpenAPI/Swagger collection you supply and skips any finding with no
endpoint in that collection. It is positi — a non-confirmation is *not
proven*, not *safe* — and some classes need manual review. See
docs/security.md → Execution boundary
and docs/exploit-.md → What needs manual .

Token-hungry. There is no global spend cap. Run estimate first

and scope large scans; see docs/configuration.md.

See docs/features.md and docs/security.md
for the complete limitations and safety model.

---

Learn more

Visa Perspecti

— the public V.

Project Glasswing white paper

— technical background on the approach behind VVAH.

---

Security

Report responsibly through the private channels in
SECURITY.md. The public issue tracker is open for bug,
documentation, setup, and feature-request reports — never for security .

---

Reporting issues

Bugs, documentation, setup, and feature requests go
through the issue forms in .github/ISSUE_TEMPLATE/ (blank issues are
disabled). See reporter guidance in
docs/contributor-issue-guide.md. Report
security pri — see SECURITY.md.

---

License

Licensed under the Apache License, 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 in in
THIRD_PARTY_LICENSES.md.

See CHANGELOG.md for release history.

项目信息

开发语言：Python

Star 数：2854

技术要点

该项目属于漏洞知识库方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Visa Vulnerability Agentic Harness展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。