0xsharz/vanguard-agentic-security-harness

VASH 会在源代码中寻找真实且可触及的漏洞——并且它的发现绝非臆测。当大多数 LLM 扫描器止步于“这看起来可被利用”时，VASH 更进了一步：它会在隔离的沙箱内**编写并执行针对每个候选漏洞的 proof-of-concept**，并且只保留那些真正被触发的结果。这一核心机制——*静态召回加上沙箱内执行 PoC 确认*——使其与所有纯静态 agent 截然不同。 它建立在经过实战检验的基础 ([evilsocket/audit](https://github.com/evilsocket/audit)) 之上，并融合了 [Capital One VulnHunter](https://github.com/capitalone/VulnHunter) 和 [Visa VVAH](https://github.com/visa/visa-vulnerability-agentic-harness) 中最强大的理念——请参阅 [致谢](#-attribution)。它通过官方的 Claude Code Agent SDK 运行在您的 **Claude Pro/Max 订阅**上；无需 API key。 ``` vash run --repo ./my-project # static analysis (safe by default) vash run --repo ./my-project --dynamic-validation # + sandboxed executed-PoC confirmation ``` ## 📖 目录 - [为什么选择 VASH](#-why-vash) · [核心亮点](#-highlights) · [工作原理](#-how-it-works) · [安装](#-install) · [快速开始](#-quickstart) - [命令](#-commands) · [报告](#-the-report) · [静态与动态](#-static-vs-dynamic-validation) · [项目结构](#-project-structure) - [配置与成本](#-configuration--cost) · [结果](#-results) · [致谢](#-attribution) · [许可证](#-license) ## 🎯 为什么选择 VASH 一个简单的“在此代码中找 bug”的 prompt 往往会产生大量噪音。相反，VASH 运行一个严谨的 pipeline，该 pipeline 以 Cloudflare 的 *Project Glasswing* 研究为模型： | 原则 | VASH 的做法 | |---|---| | **多个专精 agent** | 每个 hunter 只在*一个*限定范围的区域内追踪*一种*攻击类别——而不是一个包揽一切的 agent。 | | **刻意分歧** | 一个具有不同底层模型的 Validate agent 会通过重新阅读代码，对抗性地尝试**反驳**每一项发现。 | | **以可达性作为门槛** | Trace 阶段证明攻击者可控的输入确实能够到达 sink——不可达的“bug”会被丢弃。 | | **反馈循环** | 在一个文件中确认的模式会自动在其他所有地方引发对相同模式的搜寻。 | | **执行 PoC 确认** | *VASH 的差异化优势。*在动态模式下，它会在沙箱中为每个候选对象运行真实的 exploit，并仅保留被触发的结果——每一项交付的发现都经过 exploit 验证，而非静态猜测。 | ## ✨ 核心亮点 - 🧠 **9 阶段 agentic pipeline** — 侦察 → 搜寻 → 验证 → 补漏 → 去重 → 追踪 → 反馈 → 链式 → 报告，基于确定性的 AST **call-graph 骨干**。 - 🎯 **执行 PoC 确认** — 可选的 `--dynamic-validation` 会在隔离的沙箱中运行每个 PoC；在裸机宿主机上，VASH 保持 **100% 静态**，从不执行不受信任的代码。 - 🌐 **多语言支持** — Python, JavaScript/TypeScript, Go, Java, Ruby, PHP, C/C++ 等，外加 Web 模板 (Jinja/EJS/Handlebars…) 和 IaC。 - 🔗 **Exploit 链合成** — 将各个独立的发现拼接成端到端的攻击链。 - 📊 **专业报告** — 一份详细的咨询级 Markdown 报告（包含威胁模型、CVSS + 向量、exploit 场景、对抗性验证判定，以及可直接粘贴的 GitHub 安全公告块），以及机器可读的 `report.json`。 - 📟 **丰富的实时日志** — 各阶段进度、运行成本和逐项发现的确认流；在后台运行时降级为简洁的纯文本行。 - 🛠️ **解耦命令** — `run` (扫描), `remediate` (静态补丁), `validate` (独立的二次审查)。 - 💳 **原生订阅支持** — 通过 Agent SDK 由 Claude Pro/Max 驱动；可选的按量计费 API key 以及 OpenRouter/gateway 支持。 ## 🔍 工作原理 VASH 将代码库映射为 call-graph，展开多个范围限定的 hunter，对每个发现进行对抗性验证，证明可达性，（可选地）通过执行进行确认——然后生成报告。 | # | 阶段 | 模型层级 | 目的 | |---|---|---|---| | 1 | **Recon (侦察)** | Opus | 映射代码库；发出范围限定的搜寻任务 + 包含每个不受信任输入的完整性清单。 | | 2 | **Hunt (搜寻)** | Sonnet | 每个 agent 专注一种攻击类别；进行静态搜寻，然后（在动态模式下）执行 PoC 进行确认。 | | 3 | **Validate (验证)** | Opus | 在*不同*模型上进行对抗性重读——试图**反驳**每一项发现。 | | 4 | **Gapfill (补漏)** | Sonnet | 重新排队覆盖不足的区域，直到覆盖完成。 | | 5 | **Dedupe (去重)** | Sonnet | 按根本原因对发现进行聚类；为每个独立的文件保留一个规范记录。 | | 6 | **Trace (追踪)** | Opus | 证明攻击者控制的输入能够到达 sink（可达性门槛）。 | | 7 | **Feedback (反馈)** | Sonnet | 根据已确认的模式播种新的搜寻任务；重新运行循环。 | | 8 | **Chain (链式)** | Sonnet | 合成包含多个发现的 exploit 链。 | | 9 | **Report (报告)** | Sonnet | 生成 `report.json` (原始数据) + 详细的 `report.md` (咨询级)。 | ## 📦 安装 **环境要求：** Python 3.11+，Node.js（用于内置的 Claude CLI），以及 Claude Pro/Max 订阅（或 Anthropic API key）。 ``` git clone https://github.com/0xsharz/vanguard-agentic-security-harness.git cd vanguard-agentic-security-harness python -m venv .venv && source .venv/bin/activate pip install -e . # 认证（使用您的 Claude 订阅 — 无需 API key） claude login vash auth-check ``` ## 🚀 快速开始 ``` # 1. 扫描 repo（static — 默认安全） vash run --repo ./target-project --run-id my-first-scan # 2. 阅读报告 vash report --run-id my-first-scan --format md # detailed Markdown # raw JSON + report.md 也会写入 results//report/ 下 # 3.（可选）在 sandbox 内通过执行来确认发现 docker build -t vash:latest . ./scripts/run-in-docker.sh ./target-project my-scan-dyn # runs with --dynamic-validation # 4.（可选，decoupled）生成 patches / 二次意见 vash remediate --run-id my-first-scan vash validate --run-id my-first-scan ``` ## 🖥️ 命令 ### `vash run` — 执行扫描 ``` vash run --repo PATH [options] ``` | 参数 | 描述 | |---|---| | `--repo PATH` | **(必填)** 目标源码仓库的路径。 | | `--run-id TEXT` | 运行标识符（默认：随机）。与 `--resume` 结合使用可复用。 | | `--resume` | 恢复现有的运行任务——重新排队中断/失败的任务。 | | `--dynamic-validation` | **启用执行 PoC（沙箱化）验证阶段。**默认为纯静态。需要沙箱环境 (`Docker`/`VASH_SANDBOX=1`) 或使用 `--dangerously-no-sandbox`。 | | `--dangerously-no-sandbox` | 仅限开发使用——允许 `--dynamic-validation` 在没有沙箱的情况下运行 PoC，并会发出明显警告。切勿用于不受信任的目标。 | | `--max-cost-usd FLOAT` | 如果累计成本超过此阈值则中止。 | | `--max-concurrency INT` | 限制每个阶段的并发数（控制成本/速率）。 | | `--max-recon-tasks INT` | 限制初始侦察阶段可能发出的搜寻任务数量上限。 | | `--target-url URL` | 可选的活动部署环境，agent 可以访问它以确认发现。 | | `--target-creds K=V` | 活动目标的凭证（可重复使用）。 | | `--scope-notes FILE` | 特定于目标的作用域规则/排除项，将传递给每个阶段。 | | `--config PATH` | 覆盖 `config/stages.yaml`（模型、并发数、迭代次数）。 | | `--allow-api-key` | 遵循 `ANTHROPIC_API_KEY` 进行按量计费。 | ### `vash report` — 查看结果 ``` vash report --run-id ID --format md # detailed advisory-grade Markdown vash report --run-id ID --format json # raw machine-readable report ``` ### `vash remediate` — 静态补丁生成 *(解耦，可选启用)* 通过*读取*代码，为确认的发现生成受策略控制、针对根本原因的补丁 (unified diffs)——它永远不会执行目标代码。 ``` vash remediate --run-id ID [--repo PATH] [--policy FILE] [--out DIR] [--verify] ``` ### `vash validate` — 独立的二次审查 *(解耦，可选启用)* 通过全新且对抗性的检查流程，对先前运行中确认的发现进行重新验证。 ``` vash validate --run-id ID [--repo PATH] [--model NAME] [--min-confidence FLOAT] ``` ### `vash status` / `vash auth-check` ``` vash status --run-id ID # tasks, findings, traces, cost vash auth-check # verify Claude Code auth is configured ``` ## 📄 报告 每次运行都会生成原始、机器可读的 **`report.json` 和详细、咨询级的 **`report.md`**。Markdown 报告是确定性的，其结构类似于专业的渗透测试交付物： - **摘要** 及严重程度统计 - **扫描指标** — 作用域/已分析文件数、覆盖率 %、成本、按阶段划分的 token 数 - **威胁模型** — 系统上下文、资产、信任边界、排序后的威胁、悬而未决的问题 - **验证** — 原始发现 → 真/假阳性，折叠重复项，精确度 - **发现** — 每一项均包含 CWE (+ MITRE 链接)、**CVSS 3.1 分数及向量**、置信度、“同址存在”共现位置、描述 / 影响 / **Exploit 场景** / 前提条件 / 证据 / **修复建议** / **对抗性验证判定** - **每个发现的 GHSA 公告子块** — 摘要 / 详情 / PoC / 弱点 / 参考资料，可直接粘贴到 GitHub Security Advisory 中 - **Exploit 链** — 跨越各项发现的端到端攻击路径 ## 🔒 静态与动态验证 VASH 是**静态优先**的。它的核心安全不变性在一个地方得到强制执行：agent 运行器会剥离 `Bash` 工具——因此，**来自目标代码的任何内容都不会被执行**——除非明确启用了动态验证并且隔离沙箱处于活动状态。 ``` execution_enabled = --dynamic-validation AND (inside a sandbox OR --dangerously-no-sandbox) ``` | 模式 | 命令 | 行为 | |---|---|---| | **静态** (默认) | `vash run --repo …` | 纯逻辑推理 + call-graph 污染追踪。绝不运行目标代码——对不受信任的代码库也是安全的。 | | **动态** | `vash run --repo … --dynamic-validation` *(在 Docker/`VASH_SANDBOX=1` 环境中)* | 在沙箱中为每个候选对象编写并运行真实的 PoC；只保留被成功触发的项目。 | | **拒绝执行** | 在裸机宿主机上使用 `--dynamic-validation` | **快速失败**并给出明确的补救措施——绝不会在宿主机上默默执行。 | ## 🗂️ 项目结构 ``` vash/ ├── vash/ # the package │ ├── cli.py # Click CLI entry point │ ├── orchestrator.py # pipeline driver (the 9 stages) │ ├── runner.py # agent runner + the Bash safety gate │ ├── sandbox.py # execution sandbox gate (static-first invariant) │ ├── progress.py # RunReporter — rich, fail-soft live logging │ ├── taint.py # deterministic entry→sink taint analysis │ ├── graph_context.py # call-graph queries feeding the hunters │ ├── state.py # SQLite run state (findings, tasks, cost) │ ├── stages/ # recon, hunt, validate, gapfill, dedupe, │ │ # trace, feedback, chain, report, remediate │ └── reporting/markdown.py# VVAH/GHSA-style report renderer ├── prompts/ # one system prompt per stage ├── schemas/ # JSON Schemas — every agent output is validated ├── config/stages.yaml # per-stage model, concurrency, iterations ├── bench/ # CVE-recall benchmark harness + ground truth ├── scripts/run-in-docker.sh # sandboxed (executed-PoC) runner ├── tests/ # 660 offline tests ├── Dockerfile # the isolation sandbox image ├── NOTICE / THIRD_PARTY_LICENSES.md # attribution └── docs/ # design specs & benchmark write-ups ``` ## ⚙️ 配置与成本 - **模型** 在 `config/stages.yaml` 中按阶段配置（默认情况下，recon/validate/trace 阶段使用 Opus，其他阶段使用 Sonnet）——可根据成本与深度自由调整。 - **限制策略：** `--max-cost-usd` (硬预算上限)、`--max-concurrency` 以及 `--max-recon-tasks` 会限制每次运行；运行任务在发生中断或达到预算上限后**支持恢复** (`--resume`)。 - **提供商：** 默认使用订阅；`--allow-api-key`/`ANTHROPIC_API_KEY` 用于按量计费，或使用 OpenRouter/gateway base-URL 接入非 Anthropic 模型。 ## 📈 结果 ### 🎯 `swagger-typescript-api` ≤ 13.12.1 — 盲扫恢复了 **全部 6 个已披露的 CVE (100%)** 仅提供源代码——没有任何提示，也没有任何公告——VASH 独立发现了确认的漏洞，这些漏洞对应于后来在 `swagger-typescript-api` 中披露并在 **13.12.2** 版本中修复的**全部六个 CVE**中的**每一个**。每一个漏洞都通过了 VASH 的对抗性验证阶段。这六个漏洞都有一个共同的根本原因：攻击者控制的 OpenAPI spec 内容在未经 TypeScript 上下文转义的情况下到达了生成 sink。 | 已披露的 CVE | 类别 | VASH | |---|---|:---:| | [CVE-2026-54662](https://github.com/advisories/GHSA-hqj5-cw9f-rx67) | RCE — `fetch` 客户端 `baseUrl` | ✅ | | [CVE-2026-54661](https://github.com/advisories/GHSA-38c3-wv3c-v3xj) | RCE — `axios` 客户端 `baseUrl` | ✅ | | [CVE-2026-54666](https://github.com/advisories/GHSA-w284-33mx-6g9v) | RCE — OpenAPI 路径模板 | ✅ | | [CVE-2026-54664](https://github.com/advisories/GHSA-5f94-x226-ccpm) | RCE — enum 字符串值 | ✅ | | [CVE-2026-54660](https://github.com/advisories/GHSA-h754-fxp7-88wx) | 凭证窃取 — 远程 `$ref` | ✅ | | [CVE-2026-54663](https://github.com/advisories/GHSA-x36r-4347-pm5x) | SSRF — 远程 `$ref` | ✅ | VASH 发现了 **29 项漏洞；12 项通过了对抗性验证**——即上面的六项以及其他看似新颖的问题（原型链污染、ReDoS、YAML 反序列化、路径穿越）。*召回率是根据漏洞 sink/类别与已披露的公告进行映射比对的。* ### 📊 `datamodel-code-generator` 0.55.0 — 与 VVAH 及 audit 的正面交锋 由 `bench/` 测试工具根据已发布的 CVE 真值（50 个 Python 文件 + 20 个 Jinja2 模板，**11 个对应版本的 CVE**）进行确定性评分： | 工具 / 运行 | 交付的召回率 | 发现数量 | 成本 / 耗时 | 基础 | |---|:---:|:---:|---|---| | 🥇 **VASH** (Docker, 执行 PoC) | **5/11 (45%)** | 25 (+3 条链) | ~$88 / ~3.5 hr | 每一项发现均经过 exploit 验证 | | 🥇 **VASH** (宿主机, 静态) | **5/11 (45%)** | 25 (+5 条链) | ~$103 / ~2.5 hr | 静态搜寻 | | 🥈 Visa **VVAH** | 4/11 (36%) | 20 (+6 条链) | ~7.2M tok / ~3 hr | 静态 | | 🥉 evilsocket **audit** | 2/11 (18%) | 13 | ~$48 / ~2.9 hr | 静态 | - **单次运行 5/11，合集 6/11。** 两次独立的运行各自交付了 5/11；综合来看，VASH 覆盖了 **6 个不同的 CVE**。搜寻过程具有随机性——特定的运行会以一个代码生成的 CVE 换取另一个——因此增加迭代次数可以稳定地达到 6/11。 - **模板处理是决定性的优势。** VASH 独特地交付了 `CVE-2026-54654`，这是一个其他工具均未捕获的 `.jinja2` 代码生成 bug，并且在其他模板 CVE 上与 VVAH 持平。 - **执行 PoC 带来了信心。** 在 Docker 运行中，交付的 25 项发现中的每一项都有一个在沙箱中被成功触发的 PoC——这属于执行验证，正是 VASH 与纯静态 agent 形成根本区别的维度。 *可通过 `bench/` 测试工具及其 CVE 真值进行复现。请参阅 [`docs/BENCHMARK-COMPARISON.md`](docs/BENCHMARK-COMPARISON.md) 获取各个 CVE 的对比矩阵及注意事项。* ## 🙏 致谢 VASH 建立在优秀的开源工作之上，并保留了完整的出处（请参阅 [`NOTICE`](NOTICE) 和 [`THIRD_PARTY_LICENSES.md`](THIRD_PARTY_LICENSES.md))： - **[evilsocket/audit](https://github.com/evilsocket/audit)** (MIT) — 基础的 8 阶段 pipeline、prompt、schema 以及 VASH 基于 fork 并进行扩展的编排器。 - **[Capital One VulnHunter](https://github.com/capitalone/VulnHunter)** (Apache-2.0) — 完整性/覆盖率以及反驳验证机制。 - **[Visa VVAH](https://github.com/visa/visa-vulnerability-agentic-harness)** (Apache-2.0) — 模板文件扫描与清晰的报告交付。 - 架构灵感来源于 Cloudflare 的 **[Project Glasswing](https://blog.cloudflare.com/cyber-frontier-models/)** 研究。 ## 📜 许可证 VASH 基于 **MIT License** 发布（继承自 evilsocket/audit），其中的 Apache-2.0 组件已在 [`THIRD_PARTY_LICENSES.md`](THIRD_PARTY_LICENSES.md) 中注明。请参阅 [`LICENSE`](LICENSE)。 ## ⚠️ 负责任地使用 VASH 是一款防御性安全工具，仅用于对您拥有或获准评估的代码进行**授权**测试。动态模式会执行 PoC exploit——请仅在提供的沙箱内运行它，切勿将其指向您未经许可测试的系统。

_{使用 Claude Agent SDK 构建 · 设计上静态优先 · 选择性执行 PoC}

标签：Go语言工具, Python, 加密, 动态验证, 文档安全, 无后门, 漏洞扫描器, 自动化payload嵌入, 请求拦截, 逆向工具, 错误基检测, 静态代码分析