vvts-alpha/VERDICT

VERDICT 运行一个真实的浏览器和一个限定了作用域的 HTTP client，通过这些工具由 **Claude 操控** —— 侦察 → 方法论 → 诊断 → （多步逻辑） → （Burp） → 报告。它**特意采用分阶段设计**，这样模型就无法“走马观花和跳过”，并且具有**严格的证据纪律**，因此只有当发现真正复现时才被标记为 `confirmed`。所有过程都会实时流式传输到 WebUI。 ## 📊 基准测试 **实测数据，而非自我宣称。** 每一个发现都有 agent 自身记录的请求/响应证据作为支撑 —— 点击查看每次运行的报告。VERDICT 在**两个维度**上进行评分 —— **① 检测准确性**（给定一个漏洞，它能否找到并证明它 —— 甚至突破防御？）以及 **② 自主探索**（从一个 URL 出发，它能在无人干预的情况下映射和利用多少未知应用？）。→ **[完整的跨基准分析](benchmarks/)**。 **① 检测准确性** —— 较小的目标，已知答案，以命中率衡量： - 🏆 **XBOW-Bench (XBEN-24) — [92% · 100/109](benchmarks/xbow-bench)** 遍布 104 项基准的 XBEN-24 套件。无辅助（不依赖基准测试自身的描述）：**91/91 = 100%**。*覆盖全类别的广度 × 命中率。* → *完整分析、按类别/难度的细分，以及 104 份单次运行报告。* - 🎓 **PortSwigger Web Security Academy — [检测到 16/20](benchmarks/web-security-academy)** 位于最难的两个级别（**Expert ×10 + Practitioner ×10**），以**漏洞*检测***而非 flag 捕获来评分 —— **12 个已确认**（对照组失败 + ≥2 次正向重放），突破了每个实验室的标志性防御（严格的缓存能力、无键查询缓存、AngularJS sandbox **以及** CSP、HMAC 签名的反序列化、仅 OOB 的 blind XXE）**+ 4 个可疑线索**。仅有 3 个真正的空白。*当应用存在防御时，它还能找到漏洞吗？* → *严格的单实验室检测评分 + 证据报告。* **② 自主探索** —— 一个 URL，未知表面，以覆盖率衡量： - 🧃 **OWASP Juice Shop — [38 个已确认的发现](benchmarks/juice-shop)**，在单次自主运行中，横跨 **16 个漏洞类别** —— 从**关键的 SQLi 认证绕过到管理员权限**再到业务逻辑欺诈（负数数量结账、自我充值钱包）—— 外加 5 个可疑的 CVE 线索。*没有人告诉它该去哪里找。* → *完整分析 + 每一个发现的证据报告。* - 🌐 **实际的漏洞赏金** —— VERDICT 还针对实际的漏洞赏金目标，从一个 URL 出发产出了**已确认的、有证据支撑的发现**。具体的计划和报告根据协调披露原则予以保留 —— 上述可复现的基准测试即为公开证明。 ## 🔬 `confirmed` 的含义 不是“模型这么认为”。一个发现只有在**对照组失败**并且**≥2 次正向重放成功**时才被标记为 `confirmed` —— 否则将自动被**反驳**。以下是 VERDICT 为 Juice Shop 运行中的关键 SQLi 记录的实际证据（38 个发现中的第 1 个）： ``` finding #1 · CRITICAL · SQL injection → auth-bypass to admin · POST /rest/user/login ✗ negative control {"email":"nonexistent@juice-sh.op","password":"wrong"} → 401 "Invalid email or password" ✓ positive replay 1 {"email":"' OR 1=1--","password":"anything"} → 200 JWT ⇒ { id:1, role:"admin" } ✓ positive replay 2 {"email":"' OR 1=1--","password":"anything"} → 200 JWT ⇒ { id:1, role:"admin" } control failed + 2 stable positives ⇒ CONFIRMED · full request/response recorded for every finding ``` 那些通用的 200 状态码、0 字节响应体、软 404 和不稳定响应一律不计入在内。WebUI 内联展示了对照组、重放和原始的请求/响应 —— 因此你审计的是证据，而不是模型的一面之词：

## ✨ 功能特性

- 🧠 **Claude 主导，分阶段进行** —— 侦察 → 方法论 → 每个页面的诊断。有界限的查询阻止模型省略工作。 - 🔬 **证据纪律** —— `confirmed` 需要一个失败的对照组 **+ ≥2 次稳定的正向重放**。通用的 200 响应/不稳定的响应会被自动反驳。*从根本上*降低了误报 (FP)。 - 🔐 **扫描登录后内容** —— Bearer-JWT 传播 + 一个提取**经过身份验证的请求本身**的 Burp 扩展，从而真正测试到了认证表面（真正的核心资产）。 - 🧬 **API 规范评估** —— 将其指向一个 `swagger.json`（OpenAPI 3.x / Swagger 2.0），它会在 Bearer 身份验证之后测试**每一个声明的 endpoint** —— 无需 Web UI —— 或者将规范叠加在爬取结果上，以触达 UI 从未调用的 endpoint。 - 🧩 **A04 多步逻辑** —— 一个专门的场景阶段通过差异预言机跨 endpoint 链接请求（优惠券叠加、负数数量结账、批量赋值）。 - 🤝 **AI 深度 × Burp 广度** —— agent 负责处理 IDOR / authz / 业务逻辑；Burp 负责注入的广度。导入的内容会进行去重，并由 **AI 重新验证**。 - ✅ **覆盖率关卡** —— `screen_done` 必须涵盖每一个计划的攻击类别 —— 杜绝“找到一个就转向下一个”。 - 🛰 **确认预言机** —— `probe_xss` / `probe_redirect` / `probe_jwt` (alg:none) 将“看起来可疑”转化为证据。 - 🖥 **观察与启动 UI** —— 一个 3 栏 React 应用，映射出一个只追加的事件日志：站点树、截图、发现结果、证据查看器、实时诊断日志。从浏览器中启动并控制运行过程。 - 🧾 **报告** —— Markdown / HTML / PDF / CSV + 一个页面清单 + 一个关于它所发现的一切的 OpenAPI 规范。 - 🛡 **安全设计** —— 仅使用操作员提供的认证（绝不伪造），绝不自动点击登出，在证据中对敏感信息进行脱敏，LLM 采用订阅模式（无按量计费的 API）。 ## 🚀 快速开始 ``` # 要求：Node >= 24 (内置 node:sqlite)，通过 corepack 安装 pnpm，一个 chromium binary corepack enable pnpm pnpm install && pnpm -r build npx playwright install chromium # or pass --browser-path # 1) observability UI (单独的终端) → http://127.0.0.1:4317 node packages/cli/dist/main.js serve # 2) 从单个 URL 进行 Claude 主导的评估 … node packages/cli/dist/main.js pilot --url https://app.example.com/ # … 或者基于 scope + auth manifest (推荐) node packages/cli/dist/main.js pilot --manifest scope.json # … 或者将其指向 API spec — 无需 Web UI (m.json 携带 Bearer) node packages/cli/dist/main.js spec-import --spec swagger.json --url https://api.example.com node packages/cli/dist/main.js scan --id --manifest m.json && node packages/cli/dist/main.js logic --id --manifest m.json ``` 使用 `node packages/cli/dist/main.js init` 交互式地生成一个 manifest。发现、截图、API 和诊断日志会实时填充 WebUI；`runs//report.md` 会在最后写入。 ## 🔍 工作原理 由一个契约 (`screen_inventory.json`) 连接的两个阶段：**侦察 + 标记**负责写入它，**扫描 + 逻辑**和 WebUI 负责读取它。 ``` flowchart LR A[🗺 Survey
map screens + APIs
incl. HTML form POSTs] --> B[📋 Methodology
per-screen attack plan] B --> C[🔬 Diagnosis
1 screen = 1 bounded query
coverage gate] C --> D[🧩 Scenario A04
multi-step logic abuse] D --> E[🐝 Burp scan
authenticated · de-dup · re-verify] E --> F[📄 Report
md · html · pdf · csv · openapi] C -.evidence discipline.-> C ``` 每个阶段都是一次带有工具白名单的**单次 `query()`**，因此模型每次只在一个有界限的上下文中工作。模型分层会将高价值的页面路由给深度模型（例如 Opus），而将侦察/静态页面路由给快速模型（例如 Sonnet）。`--survey-only` / `--resume` / `--attended` 可用于调整流程。 ## 🧠 为什么选择 VERDICT | | 其他工具的做法 | VERDICT 的做法 | |---|---|---| | **覆盖率** | “扫描站点” → 模型走马观花并跳过 | 阶段化 + 覆盖率关卡让完整性成为一项*契约*，而不是碰运气 | | **误报** | 一堆需要分诊的可能存在的漏洞 | 只有在对照组失败 + ≥2 次稳定的重放之后，才会设置 `confirmed` | | **认证表面** | 扫描器无法保持 session → 报 401 错误 | session **就在请求中** (Burp Audit REST) + Bearer 传播 | | **广度与深度** | 一个工具，一种权衡 | AI 的深度 (IDOR/authz/逻辑) × Burp 的广度 (注入)，合并后并重新验证 | | **真实基准** | 依赖 Burp 有损的自动发现机制 | VERDICT 掌握 auth + 每一个 param，并**声明**它们 (OpenAPI / 原始请求) | | **过拟合** | 硬编码的启发式规则 | 标准技术 + LLM 的判断 —— 没有内置针对特定应用的词汇 | ## 🛠 命令 ``` node packages/cli/dist/main.js [options] # after pnpm -r build ``` | 命令 | 用途 | |---|---| | **`pilot`** | 由 Claude 主导的评估。`--manifest`/`--url`, `--model` (+ `--fast-model` 分层), `--max-turns`, `--max-screens`, `--rate`, `--headed`, `--burp-proxy [url]`, `--burp-scan`, `--login-url`, `--keepalive-min ` | | `pilot --survey-only` | 仅映射（页面 + 截图 + API）；稍后使用 `--resume` 进行诊断。 | | `pilot --resume --id ` | 继续现有的运行（诊断仍在队列中的页面）。 | | `pilot --attended[ a,b,c]` | 手动多 session 登录 (MFA/CAPTCHA)：每个角色一个有头浏览器窗口，手动登录，并在实时 session 上进行诊断。 | | **`asr`** | 攻击面侦察（广泛-浅层，位于 `pilot` 的*左侧*）：`--domain ` → 发现 (crt.sh 被动 + `--tools subfinder` + 离线 `--import` recon.sh + 可选的主动 `--brute`) → 探测/评分/排名主机 → `asset_inventory.json`。`--paths`/`--triage`/`--screenshot`。拥有自己的 WebUI 查看器。 | | `pilot --from-asr ` | 将 ASR 运行中排名靠前的、**在范围内、第一方、存活**的主机提升为按主机划分的 pilot 评估 —— 作用域**固定**在 ASR 边界内（绝不扩大），分诊角度作为 `focus` 注入。`--from-asr-top`/`--from-asr-band`/`--from-asr-concurrency`。 | | `assess` | 确定性的一次性执行：爬取 → 标记 → 扫描 → 逻辑 → 报告。 | | `serve` | 可观测性 WebUI + 状态 API/WS (`127.0.0.1:4317`; `--host 0.0.0.0` + `--password` 以便对外开放)。 | | `init` / `manifest` | 交互式作用域 manifest 生成器。 | | `report` / `inventory` / `openapi` | 导出报告 / 页面清单 / 所发现表面的 OpenAPI。 | | `spec-import` | 摄取 OpenAPI 3.x / Swagger 2.0 规范 (`--spec` + `--url`) → 为纯 评估初始化表面，或者将其叠加在爬取结果上 (`--id`)。 | | `burp-scan` / `burp-import` | 通过 REST 进行主动 Burp 扫描 → 合并全新发现 / 导入 Burp XML 报告。 | | `header-audit` | 信息级别的安全标头检查。 | ## 🎛 作用域与认证 ``` { "target": "https://app.example.com/", "scopeMode": "etld", // same-origin | etld | unrestricted "scope": { "outOfScopePathPrefixes": ["/logout"] }, "http": { "headers": { "X-Forwarded-For": "127.0.0.1" } }, // WAF bypass / required headers "auth": { "httpBasic": { "user": "u", "pass": "p" }, // site-wide Basic/Digest "roles": [ { "name": "admin", "pass": "…", "description": "full admin" }, { "name": "alice", "cookieFile": "alice.cookies" } // pre-captured session (MFA walls) ] } } ``` **认证 = 仅限操作员提供的材料。** 提供凭证 → `smartLogin` 自动发现表单。提供 cookie 文件 → 按原样注入（用于 agent 无法自动登录的防护墙）。没有 cookie 文件的 MFA/CAPTCHA → `--attended`（由人工登录实时有头浏览器 session）。**agent 绝不伪造或窃取 cookies**，并且**绝不自动点击登出**（因为这会中断 session）。`roles[0]` 是主角色；多个角色用于驱动多角色的 authz 差异对比。 ## 🔐 复杂认证 (SSO / MFA) 位于 **Microsoft / Okta SSO**、**MFA / TOTP** 或 **CAPTCHA / Arkose** 之后的应用会击败所有自动登录扫描器 —— 流程会离开目标源跳转到 IdP 然后再返回，这是任何表单填充器都无法跨越的壁垒。这是**第三层认证**，是凭证→`smartLogin`和预先捕获的 `cookieFile` 的交互式补充：**你**来完成登录，**agent** 完成剩下的工作。 VERDICT 为**每个角色保持一个真实的浏览器** —— 每个都是一个实时的持久化上下文，而不是一个交换 cookie 的共享浏览器。你**只需手动登录你需要的角色**，从那一刻起，VERDICT 就会**继承每个经过认证的 session**，并在其上驱动完整的 pipeline —— 侦察 → 方法论 → 诊断 → 场景 —— 涵盖你提供的每一个角色。 **配置** —— 在启动时，在 WebUI 中将每个角色的模式设置为 **manual (Sessions 标签页)**，或者在 CLI 上传递 **`--attended`**（使用 `--attended admin,user1,user2` 内联命名角色）：

**实时登录** —— 打开 **Sessions** 标签页。每个角色都有自己单独的标签页（红点 = 等待登录），在 **WebUI 内部渲染出目标登录页面的实时录屏**；你的鼠标 / 键盘 / 粘贴操作会通过 CDP 直接中继到真实的浏览器中，因此由你亲自通过 SSO 重定向、MFA 和 CAPTCHA。点击 **Done (logged in)**，VERDICT 就会接管该角色。所有角色标签页同时开启并同时等待：

**绝不会伪造 Cookies 和 token。** Agent 使用的一切都直接来源于*你*的真实 session —— 在你完成后，VERDICT 会读取实时上下文的 cookie + Bearer，并在浏览器和原始 HTTP 探测中都使用该 session。作用域关卡仍然守护着 agent 的每一个动作；只有你手动接管的导航操作不受作用域限制，因为 SSO/IdP 跳跃在设计上就是跨域的。 ## 🐝 Burp 集成 可选且附加的 —— 在标志关闭的情况下，行为在字节级别是完全一致的。通过 `.env`（自动加载）或参数进行连接。 ``` # proxy — 通过 Burp 路由所有流量 (已认证流量会在 Burp 中积累) node packages/cli/dist/main.js pilot --manifest m.json --burp-proxy # 诊断后进行 active scan → 合并 net-new → AI 重新验证 High+ node packages/cli/dist/main.js pilot --manifest m.json --burp-scan # standard REST (1337), unauth crawl+audit # 🔐 authenticated active scan (推荐) — VERDICT Audit REST extension (端口 1338) export BURP_AUDIT_API=http://127.0.0.1:1338 BURP_AUDIT_TOKEN= node packages/cli/dist/main.js pilot --manifest m.json --burp-scan # → routes through the extension automatically ``` 标准的 REST API 无法将 session 传递给扫描。**[`tools/burp-audit-ext/`](tools/burp-audit-ext/) Montoya 扩展**避开了这个问题：VERDICT 提交**经过身份验证的原始请求本身**（内置 cookie + Bearer），因此 Burp 可以在*登录之后*进行审计，而不会引发爬取爆炸。`BURP_AUDIT_API` 会将 `--burp-scan` 切换到此路径；否则它将回退到标准的 REST。使用 `gradle shadowJar` 构建它，并在 Burp 中加载该 jar 包。

## 🖥 WebUI 一个目标 = 一个页面。左侧：**SITE TREE**（URL 层级 + 扫描徽章）。顶部：进度条。右侧标签页：**Screen**（截图 + API + 发现）、**Findings**（过滤 + 内联证据查看器）、**APIs**、**Diagnostic log**（实时）、**💬 Ask**（在评估之上进行的只读问答）。

随着 agent 的工作，进度、发现、截图和诊断日志会通过 WebSocket 实时流入 —— 该 UI 是一个只追加事件日志的纯投影：

从 `/`（**项目列表**）你可以**启动和控制运行**：**+ New** 会打开一个完整的 manifest 编辑器 —— 目标、作用域模式、模型分层、**自定义标头**（名称/值）、**登录 URL**、**目标 URL 列表导入**（CSV / 每行一个）、**最大屏幕数**、HTTP Basic、认证角色 —— 并且服务器会生成 CLI 作为子进程。支持对每次运行进行停止 / 恢复。两个角色（**operator** = 完全权限 · **viewer** = 只读）。使用 `--host 0.0.0.0` **和**环境变量 `VERDICT_WEB_PASSWORD`（+ `VERDICT_WEB_PASSWORD_VIEWER`）进行对外暴露。

## 🎯 检测覆盖率 映射 OWASP：**A01** 访问控制 (IDOR/BOLA，认证绕过) · **A03** 注入 (SQLi，反射型 XSS，路径遍历) · **A04** 业务逻辑 (价格/数量篡改，批量赋值，工作流绕过) · **A07** 认证 (JWT alg:none / 声明篡改，可预测的 cookies) · **A10** SSRF / 开放重定向 · 外加信息泄露和标头审计。深度的 payload 广度（XSS 变体、SSTI、desync）被委托给 **Burp**；VERDICT 负责导入并重新验证。 ## ⚙️ 安装与要求 - **Node.js ≥ 24**（强制要求 —— 状态存储使用内置的 `node:sqlite`）。`nvm use 24`。 - 通过 corepack 安装的 **pnpm** (`corepack enable pnpm`)。 - 用于 Playwright 的 **Chromium**：`npx playwright install chromium`，或者 `--browser-path ` / `VERITAS_BROWSER_PATH`。在容器中需添加 `--no-sandbox`。 - **LLM = `claude` CLI**（订阅认证）—— 无需 `ANTHROPIC_API_KEY`，无按量计费。 ``` pnpm install pnpm -r build # tsc per package (+ Vite for webui) pnpm -r test # node:test via tsx (FakeDriver / FakeHttpClient / FakeLlmClient — no network/LLM) ``` `.env`（位于 repo 根目录，自动加载；优先使用 shell `export`；已被 gitignore 忽略）：`VERITAS_BROWSER_PATH`、`BURP_API`、`BURP_PROXY`、`BURP_RESOURCE_POOL`、`BURP_AUDIT_API`、`BURP_AUDIT_TOKEN`。 ## 🧩 架构 TypeScript monorepo；依赖关系向下流动；契约类型仅存在于 `@veritas/core` 中。 ``` cli ── orchestrates everything pilot ─ agent ─ scanner ─┐ crawler ─ llm ───────────┤ server webui ──────────┴── core (types · SQLite store · scope gate · evidence discipline · projections · OpenAPI) ``` `AssessmentStore` (`state.sqlite`) 是 agent 的工作内存**也是** WebUI 的数据源：规范化的数据表 + 一个服务器轮询以推送 WS 差异的**只追加事件日志**。WebUI 是一个纯粹的投影。`tools/burp-audit-ext/` 是一个独立的 Java/Montoya Burp 扩展。 ## 🛡 安全与不变式 - **每个网络动作都有作用域关卡** —— `isInScope(url, scope)` 默认拒绝；超出范围的返回被阻止状态，而不是抛出异常。 - **证据纪律** —— 确认需要一个失败的对照组 + ≥2 次稳定的重放；任何内容都不能被手动标记为已确认。 - **认证由操作员提供** —— 凭证或 cookie 文件；绝不伪造或窃取；cookie 文件属于敏感信息（已被 gitignore）。 - **绝不自动登出** —— agent 绝不能触碰登出/注销操作（这会破坏 session）。 - **只追加、可重放的状态** —— 每次状态转换都会在同一事务中追加一个事件。 - **LLM = `claude` CLI 订阅**，而非按量计费的 API。

**VERDICT** —— 自主 · 证据驱动 · 深入认证表面的 Web/API 渗透测试。

标签：API安全, CISA项目, JSON输出, MITM代理, Web安全, 后端开发, 特征检测, 蓝队分析