dmdhrumilmistry/security-harness面向 AI 编码代理的多代理静态应用安全审查框架：映射代码库、搜寻漏洞类别、串联并验证发现结果，并输出 SARIF、JSON 和 PDF 报告。
一个面向 Claude Code（以及后续其他 AI 代理）的多代理应用安全审查框架。一个路由技能会调度到完整的攻击性安全流水线，该流水线会映射代码库、利用按类别划分的知识库搜寻漏洞、将发现串联成升级路径、验证真实影响，并报告为 README / JSON / SARIF / 文档 / PDF。
范围：此框架对您拥有或获授权测试的代码执行静态分析（源代码审查、数据流追踪、PoC/载荷构造）。它不会攻击实时第三方系统。
security-harness/ # a plugin marketplace └── plugins/security-harness/ ├── skills/ │ ├── sh-router # single entry point - routes any appsec request │ ├── sh-security-review # the pipeline orchestrator (Stages 0-5) │ └── sh-kb-* (15) # per-vuln-class knowledge bases ├── agents/ │ ├── sh-recon # map: Graft graph + stack/SBOM/CVE + attack surface │ ├── sh-hunter # find: source→sink hunting, one per class (parallel) │ ├── sh-chainer # escalate: combine findings into attack chains │ ├── sh-verifier # confirm: offensive + seceng + dev verification + PoC │ └── sh-reporter # deliver: README/JSON/SARIF/HTML/PDF/doc └── references/ # shared contracts (finding schema, SARIF map, state files, rubrics)
### 覆盖的漏洞类别（`sh-kb-*` 技能）
访问控制（IDOR/BOLA/权限提升） · sqli · xss · ssrf · 注入（命令/代码/SSTI/LDAP） · 认证（会话/JWT）
· 反序列化 · 路径遍历（LFI/RFI） · 密钥 · csrf · xxe · 开放重定向 · 加密 · 竞态条件
· 文件上传。依赖项 CVE/SBOM 由侦察阶段处理。
## 安装
该测试框架面向多个 agent 发布。完整的打包细节和发布
检查清单见 [`docs/DISTRIBUTION.md`](https://github.com/dmdhrumilmistry/security-harness/blob/main/docs/DISTRIBUTION.md)。
**Claude Code** - 将此仓库添加为插件市场并安装该插件：```
/plugin marketplace add dmdhrumilmistry/security-harness
/plugin install security-harness
/plugin marketplace add 接受以下任意一种形式：GitHub 的 owner/repo（如上所示）、完整的 git URL
（https://github.com/dmdhrumilmistry/security-harness.git），或指向本地克隆的路径
（例如在包含你检出的目录中运行 /plugin marketplace add ./security-harness）。
然后运行 /plugin install security-harness，并在提示时重新加载。
Gemini CLI - 一个原生扩展，清单文件位于仓库根目录：```bash gemini extensions install https://github.com/dmdhrumilmistry/security-harness
**opencode、Codex 或任何 [agentskills.io](https://agentskills.io) agent** - 将技能复制到发现目录中。Codex 还会自动识别 `AGENTS.md`：```bash
git clone https://github.com/dmdhrumilmistry/security-harness
cd security-harness
python3 scripts/sync-agent-skills.py --install agents # ~/.agents/skills
python3 scripts/sync-agent-skills.py --install opencode # ~/.config/opencode/skills
Graft 由流水线自动安装并配置。 阶段 0 会在缺失时运行 npm install -g @nanonets/graft（需要 Node/npm），然后运行 graft init <target> --no-agents --no-global
为目标仓库注册 Graft MCP 服务器和新鲜度钩子。图本身（<target>/graft/，
自动加入 gitignore）在侦察阶段构建。如需手动预安装：npm install -g @nanonets/graft。Graft 的
结构化构建是免费的，无需 API 密钥；可选的 --deep LLM 处理在设置时使用 GRAFT_API_KEY /
GRAFT_PROVIDER / GRAFT_MODEL。
其他工具也会在缺失时由阶段 0 自动安装（通过机器上现有的任意包管理器 -
winget/choco/scoop、brew、apt、npm/pip/go - 参见 references/tooling-setup.md）。安装过程会
有提示，优先采用无需提权的方式，且绝不会阻塞运行：任何无法安装的工具只会被标记为不可用，流水线会
回退处理。阶段 0 只安装用于填补缺失能力组的工具：
syft · CVE：以下之一 grype
（首选）、trivy 或 osv-scannerwkhtmltopdf 或 pandoc（用于 PDF/DOCX）；否则你会得到 report.html（或无头 Chrome PDF）。所有工具都是可选的 - 如果都没有安装，流水线会优雅降级为原生搜索 + 清单解析。
使用自然语言请求调用路由器：``` /sh-router full security review of ./api /sh-router find SQLi and IDOR in src/ /sh-router just map this codebase # recon only
或直接调用管道：```
/sh-security-review . classes:sqli,access-control,ssrf depth:deep
/sh-security-review . stage:report # regenerate reports for the latest run
每个阶段都运行在与自身认知负荷相匹配的模型上，因此 token 会花在真正影响发现质量的地方，并在机械性工作上节省下来。这是默认设置——无需任何参数。
| 阶段 | 默认模型 |
|---|---|
| recon | sonnet |
| hunt（按类别） | 模式类（secrets、crypto、open-redirect、csrf）使用 haiku · 源→汇追踪类（sqli、xss、ssrf、injection、path-traversal、xxe、file-upload、auth）使用 sonnet · 深度逻辑类（access-control、race-conditions、deserialization）使用 opus |
| chain | opus |
| verify | opus（精度关卡——保持强模型） |
| report | haiku |
可通过 models: 参数覆盖（同样会经过路由器传递）：```
/sh-security-review . # default tiered map above
/sh-security-review . models:max # every stage + hunter on opus (max quality, max cost)
/sh-security-review . models:cheap # aggressive downshift (trades some verify precision)
/sh-security-review . models:verify=opus,hunt=sonnet # per-stage overrides
/sh-security-review . models:report=sonnet,hunt.pattern=sonnet # per-hunter-tier override
阶段：`setup, recon, hunt, chain, verify, report`。模型：`opus, sonnet, haiku, inherit`。对于 `hunt`，
单独指定模型会将所有 hunter 都降级为该模型；`hunt.pattern` / `hunt.trace` / `hunt.logic` 则针对某一层级。
其他节省 token 的机制是内置的：recon 只为具有真实攻击面的类生成 hunter，hunter
查询 Graft 图而不是读取整个文件，并且 `findings.json`/SARIF 由
确定性脚本生成，而不是由模型生成。
### 输出
所有内容都位于 `<target>/.security-harness/<run-id>/` 下：
- `recon.md`、`codebase-map.json` - 映射（技术栈、SBOM、CVE、攻击面）。
- `findings.jsonl` → `chains.md` → `verified.jsonl` - 工作状态（参见 `references/state-files.md`）。
- `reports/` - `README.md`、`findings.json`、`results.sarif`、`report.html`、`report.pdf`（+ `report.docx`）。
每个已发布的发现都包含一个 payload、一个 PoC、验证结论、CWE/OWASP id、CVSS 以及
代码级缓解措施。
## Pull request 审查
`sh-pr-review` 审查单个 pull request 而不是整个代码库，将
结果作为内联评论**发布在 PR 本身**，并设置一个 `security/pr-review` commit
状态，分支保护可以强制执行该状态。
**在你自己的机器上运行它，适用于任何你可以读取的 PR。** 安装该插件并询问：```
review https://github.com/acme/api/pull/128
review PR 42
security review this PR
粘贴一个 PR 链接，它就会审查该仓库中的那个 PR，并先将其克隆到临时目录，因为 hunters 会读取文件而不仅仅是补丁。不会向你所工作的仓库写入任何内容。
传入一个纯数字，它会针对你当前所在的仓库进行解析，也就是 git remote 指向的那个仓库。什么都不传，它会取你当前分支对应的开放 PR。
Phase 7 打印发现结果和裁决，并在发布任何内容之前询问——拒绝是正常结果，payload 会留在磁盘上供你稍后发布。
在花费任何分析之前，它会检查你是否真的能写入目标仓库，因此审查别人的项目会提前告诉你发布将返回 403，而不是十分钟后才发现。
有三个特性使它可用作合并门禁而非噪音：
pr_impact，取值为 introduced、aggravated 或 pre_existing。前两者会阻止；pre_existing 会被报告但从不阻止。因为作者从未编写的代码而阻止合并，正是必需检查被删除的原因，所以当 hunter 在 aggravated 和 pre_existing 之间不确定时，它必须选择 pre_existing。sh-kb-* 基础相同的 class slugs 上，然后选择一个层级。Tier 0（无安全相关变更）不启动任何东西，但仍会设置状态。Tier 3 运行完整流水线。| 裁决 | 状态 | 何时 |
|---|---|---|
| fail | failure | 在 --fail-on（默认 medium）或以上存在 introduced 或 aggravated 发现，置信度 >= 80 |
| warn | success | 没有 introduced 或 aggravated；报告 pre-existing 发现 |
| pass | success | 无发现，或 triage 在 Tier 0 停止 |
| error | error | 审查无法完成 |
warn 故意报告 success：一个阻止合并的警告就是带有额外步骤的失败，团队会通过移除该检查来应对。error 与 failure 保持区分，因此一次损坏的运行绝不会看起来像它并未发现的漏洞。
审查事件始终是 COMMENT，绝不是 REQUEST_CHANGES 或 APPROVE。提交状态是执行机制，也是分支保护所读取的内容。
范围： 该 skill 写入 pull request 和提交状态，不写入其他任何地方。它不打开 issue，也不在任何外部跟踪器中创建任何内容。
一个 PR 每次推送审查一次，因此第二次审查必须比第一次更便宜，否则该工具就会成为人们会关掉的东西。
去重发生在花费之前，而不是发布之前。 PR 上已有的指纹会在 Phase 1 中读取，并交给 hunters 和 verifier。在最后才发现重复，意味着流水线中最昂贵的模型已经重新确认了一个一直写在 PR 上的结论。这不需要缓存：状态存在于 PR 中，因此它可以在冷机器和 CI 中工作。
本地缓存使其余部分增量。 sh-review-cache 将每次运行的文件哈希、发现和裁决存储在你的操作系统缓存目录下（绝不在仓库中，因为跨仓库审查会在一个会被删除的临时克隆中运行）。下一次审查只重新 hunt 内容实际发生变化的文件，对未变化的发现复用裁决，并且如果 recon map 覆盖的内容没有移动，则复用它。
一次 base-branch 合并不产生任何成本。 将 main 合并到 PR 分支会改变 head SHA，而作者没有写任何东西，但提交状态固定到某个 SHA，因此必需检查会从新的 head 中悄然消失。当 PR 自身的文件逐字节相同并且 base delta 不触及发现所依赖的任何内容时，先前的裁决会被重新盖到新的 SHA 上，完全不启动任何 agents。最后一个条件正是其安全性的来源：一次删除 sanitizer 的 base 合并会让每个 PR 文件保持不变，同时把一行安全代码变成可利用的代码。
失效处理刻意保守，因为安全工具中的陈旧条目不会让它变慢，而会让它出错。缓存键会哈希每个 sh-kb-* 知识库，因此 KB 更新会使每个缓存发现失效——缓存的“clean”绝不能压制那次更新本要捕获的发现。模型身份、skill 版本、文件内容和 7 天 TTL 也都会使其失效，未指定的模型会被视为未命中。
--no-cache 禁用它，--refresh-cache 重新建立基线，run.md 按阶段记录启动了、复用了和跳过了什么，因此一个悄悄停止命中的缓存是可见的，而不是被假定的。
审查和提交状态默认发布。 一次已计算但从未交付的审查帮不了任何人。--confirm 在发布前恢复提示，--dry-run 不发送任何内容，--no-status 发布审查但不碰提交状态。
发布通过 scripts/sh-pr-post.py 进行，而不是手工构建 API 调用，因为它是一个多步骤操作，并且有一个强制尾部：review，然后 status，然后 receipts，其中 422 通过移动评论而不是移动行号来恢复。该脚本绝不会在让状态停留在 pending 的情况下退出——如果审查无法发布，它仍会设置 error，说明是工具失败，而不是指控 PR。
Inline comments 保留给medium 或以上且置信度 >= 80 的发现。低严重性发现进入折叠的正文部分，因此一个低优先级发现以零条 inline comments 出现，是策略在起作用，而不是失败。
每次运行都会记录其成本，因此“缓存正在工作”和“审查变慢了”不再是见仁见智的问题。```bash python3 /scripts/sh-metrics.py path # where records live python3 /scripts/sh-metrics.py report # aggregate, by model python3 /scripts/sh-metrics.py purge --older-than-days 30
两个仅追加的 JSONL 文件——`runs.jsonl`（仓库、PR、层级、判定、总计、你传入的标志）和 `events.jsonl`（每个阶段或代理一行：模型、令牌、持续时间、结果、是否从缓存复用）。采用 JSONL 格式，因此即使运行崩溃，崩溃点之上仍保留有效行。
| 平台 | 指标 | 缓存 |
|---|---|---|
| **Linux / BSD** | `$XDG_DATA_HOME/security-harness/metrics`<br>默认 `~/.local/share/security-harness/metrics` | `$XDG_CACHE_HOME/security-harness`<br>默认 `~/.cache/security-harness` |
| macOS | `~/Library/Application Support/security-harness/metrics` | `~/Library/Caches/security-harness` |
| Windows | `%LOCALAPPDATA%\security-harness\metrics` | `%LOCALAPPDATA%\security-harness\cache` |
Linux 遵循 XDG Base Directory 规范，因此两者在设置时都会遵循 `XDG_DATA_HOME` 和 `XDG_CACHE_HOME`，未设置时回退到 `~/.local/share` 和 `~/.cache`。可通过 `SH_METRICS_DIR` 和 `SH_REVIEW_CACHE_DIR` 直接覆盖任一目录。
**关于 `python` 与 `python3`：** 大多数 Linux 发行版自带 `python3`，而完全没有 `python`，因此这里的示例使用 `python3`。捆绑的脚本带有 `#!/usr/bin/env python3` shebang 且可执行，因此 `./scripts/sh-metrics.py report` 在 Linux 和 macOS 上可直接运行。该技能在每次运行时解析一次 `PY="$(command -v python3 || command -v python)"`，覆盖所有三个平台，包括 Windows 上的 Git Bash。
**严格本地。** 两个脚本都不包含任何网络代码或上报端点。任何形似令牌的内容在写入前都会被脱敏，因为本地文件会被粘贴到 issue 中。
### 无人值守运行
这是可选的，并且与使用该技能是分开的决定。先在你自己的 PR 上手动运行一段时间，这样在它当着团队的面说出关于你代码库的结论之前，你先知道它会说什么。
当你准备好时，[`references/pr-review-mapping.md`](https://github.com/dmdhrumilmistry/security-harness/blob/main/plugins/security-harness/references/pr-review-mapping.md) 中的“在仓库上强制执行检查”为**你的**仓库提供了可直接复制粘贴的工作流，以及防止死任务让必需检查卡在 `pending` 状态的故障保护机制。
阈值保持默认的 `medium`。预先存在的发现永远不会阻止合并，因此未扫描的代码库不会在第一天就产生一片红色——只有 PR 实际引入或加剧的问题才会导致失败。
## 工作原理
1. **Setup** - 探测可用工具，定义范围，创建运行目录。
2. **Recon**（`sh-recon`）- 构建 Graft 图；检测技术栈/版本；SBOM + CVE；枚举入口点、信任边界和危险汇聚点。
3. **Hunt**（`sh-hunter` ×N，并行）- 每个相关类别一个 hunter，加载其 `sh-kb-*` 知识库，追踪攻击者输入从源到汇聚点的路径，并记录候选。共享的**尝试账本**防止代理重复彼此的探测。
4. **Chain**（`sh-chainer`）- 将发现组合成更高严重性的攻击路径。
5. **Verify**（`sh-verifier`）- 先反驳，再根据证据确认可利用性，构建 PoC，分配 CVSS，并剔除误报。
6. **Report**（`sh-reporter`）- 生成交付物。
子代理之间除了文件不共享任何内容；契约在 `plugins/security-harness/references/state-files.md` 中。
## 扩展
按照共享模板（何时狩猎 · 源与汇聚点 · 检测配方 · 载荷/PoC · 误报过滤器 · CWE/OWASP · 链式提示 · 缓解措施）创建 `skills/sh-kb-<class>/SKILL.md` 来添加新的漏洞类别，然后将其 slug 添加到 `references/finding-schema.json` 中的 `class` 枚举以及 `skills/sh-router/SKILL.md` 中的路由表。
## 自动化知识库更新
一个定时的 GitHub Action（`.github/workflows/update-knowledge-base.yml`）保持 `sh-kb-*` 知识库常新。**每隔一天**（以及手动 `workflow_dispatch` 时），它运行一个代理，将新的、可信的公开安全研究——OWASP、PortSwigger Research、CWE/CAPEC、NIST、MDN、精选 GitHub 仓库以及公开的 HackerOne 披露——提炼为小型、来源充分的改进。然后一个**第二个、对抗性审查代理**扫描生成的 diff 以查找恶意/注入内容，并且 PR **仅在该审查者批准时自动合并**。
### 两个工作流，三个作业
PR 创建被刻意与审查和合并分离，因此写入 diff 的东西永远不是决定发布它的东西。
**阶段 1 - [`update-knowledge-base.yml`](https://github.com/dmdhrumilmistry/security-harness/blob/main/.github/workflows/update-knowledge-base.yml)**
（定时或手动）。一个作业，`create-pr`：
1. **生成** - 代理从允许列表来源编辑 KB。不提交，不推送。
2. **打开 PR** - 一个确定性步骤在 `automated/kb-update` 分支上打开（或更新）一个 PR，标记为 `awaiting-review`。
3. **交接** - 在成功创建 PR 后，它带着 PR 编号派发阶段 2。
**阶段 2 - [`kb-review-and-merge.yml`](https://github.com/dmdhrumilmistry/security-harness/blob/main/.github/workflows/kb-review-and-merge.yml)**
（由阶段 1 派发，或针对任何自动化 PR 手动运行）。两个作业：
- **`review`** - 一个*独立的*代理运行以**对抗性**方式检查 diff，查找提示注入痕迹、范围外编辑、机密/外泄、PII、武器化漏洞利用、允许列表外来源或风格违规。它**没有网络也没有 shell**，并且**故障关闭**：任何可疑内容、任何不确定性或缺少判定文件 → REJECT。判定作为 PR 评论发布并驱动标签。
- **`merge`** - **仅**在 `APPROVE` 时运行，并合并 PR。`REJECT` 会跳过它，`blocked` 作业报告原因。
> **为什么用派发而不是 `pull_request` 触发器：** 由 `GITHUB_TOKEN` 打开的 PR 不会触发 `pull_request` 工作流。`workflow_dispatch` 是豁免于该递归保护的两个事件之一，因此阶段 1 可以可靠地交接。
**自动合并意味着一个批准代理会将代码落到 `main`。** 对此的控制措施：
- 合并作业拒绝任何已关闭、来自 fork 或头分支在 `automated/*` 之外的 PR（工作流中的 `ALLOWED_HEAD_PREFIX`）。
- 它优先使用 GitHub 自己的自动合并，因此**分支保护仍然适用**。在 `main` 上有一条要求批准审查的规则时，PR 会排队等待人工而不是合并。只有在自动合并关闭的仓库上，它才回退到立即合并。
- 在手动运行时将 `auto_merge` 输入设为 `false`，以在不合并的情况下审查。
- 审查者提示告诉代理其判定具有约束力，而非建议性。
> 需要仓库设置 **"Allow GitHub Actions to create and approve pull requests"**（Settings → Actions → General → Workflow permissions），以便工作流可以打开 PR。如果你希望在自动合并之外仍有人工介入，请用分支保护规则保护 `main`，要求一个 PR 和至少一个批准审查——自动合并路径会遵循它。
### 可插拔代理
两个阶段都通过 [`.github/actions/ai-agent`](https://github.com/dmdhrumilmistry/security-harness/blob/main/.github/actions/ai-agent/action.yml) 运行，这是一个复合 action，派发到你配置的任何代理。Claude Code、OpenAI Codex、Gemini CLI，以及适用于其他任何东西的逃生舱：
| `agent` | 运行 | 凭据 |
|---|---|---|
| `claude`（默认） | `anthropics/claude-code-action@v1` | `CLAUDE_CODE_OAUTH_TOKEN` 或 `ANTHROPIC_API_KEY` |
| `codex` | `codex exec --full-auto` | `OPENAI_API_KEY` |
| `gemini` | `gemini --yolo --prompt` | `GEMINI_API_KEY` |
| `custom` | 你的 `KB_AGENT_INSTALL` / `KB_AGENT_COMMAND` | 它需要的任何东西 |
每次运行可从 `workflow_dispatch` 输入中选择，或设置仓库变量来更改默认值：生成器用 `KB_AGENT` 和 `KB_MODEL`，审查者用 `KB_REVIEW_AGENT` 和 `KB_REVIEW_MODEL`。在**不同代理**上运行生成器和审查者是一个有意义的加固步骤：针对一个模型调优的注入不太可能落到第二个独立模型上。
对于 `agent: custom`，将 `KB_AGENT_COMMAND` 设为一个 shell 命令。提示被写入由 `$AGENT_PROMPT_FILE` 命名的文件，`$AGENT_MODEL` 携带模型输入。
提示注入防御，因为生成器读取开放网络：
- **域名允许列表。** `WebFetch` 被限制在 `.github/kb-update/trusted-sources.md` 中的可信域名（镜像在工作流的 `--allowedTools` 中）。`WebSearch` 可以发现 URL，但只有允许列表中的域名才能被实际抓取。
- **内容是数据，不是命令。** 任务提示（`.github/kb-update/prompt.md`）指示 Claude 将每个抓取的字节视为不可信参考材料，并忽略页面中嵌入的任何指令——HackerOne 报告正文（用户生成）被标记为最高风险层级。
- **生成器无 shell、无推送；审查者是关卡。** 生成器只能编辑文件。独立审查者（`.github/kb-update/review-prompt.md`）是站在抓取内容和 `main` 之间的东西——没有它的明确批准，任何东西都不会合并。
- **生成器和审查者使用不同代理。** 可选，并且是该关卡最强的版本：将 `KB_AGENT` 和 `KB_REVIEW_AGENT` 设为两个不同的引擎。
**设置：**
- 添加你所使用代理的凭据（Settings → Secrets and variables → Actions）：
**`CLAUDE_CODE_OAUTH_TOKEN`**（默认）、`ANTHROPIC_API_KEY`、`OPENAI_API_KEY` 或 `GEMINI_API_KEY`。
OAuth 令牌针对**你的 Claude 订阅的使用限制**进行认证，而不是计量 API 密钥——用 `claude setup-token` 在本地生成它（需要有效的 Claude Pro/Max 订阅）并粘贴结果。
- 启用 **"Allow GitHub Actions to create and approve pull requests"**（Settings → Actions → General →
Workflow permissions），以便工作流可以打开其 PR。推荐：在 `main` 上添加分支保护规则，
要求一个 PR 和一个批准审查，这样即使开启自动合并，任何自动化更改也不能在没有人工的情况下落地。
- 要更改允许哪些来源，请编辑 `trusted-sources.md` 中的允许列表**以及**工作流中匹配的
`WebFetch(domain:...)` 条目——保持两者同步。
每次运行都会在 `.github/kb-update/last-run-summary.md` 中记录它做了什么。
## 路线图
- ~~Codex / Cursor 镜像接线。~~
✅ 已发布：`AGENTS.md`、一个 Gemini CLI 扩展，以及用于 `.agents/skills` 和 opencode 的 `scripts/sync-agent-skills.py`。参见 [`docs/DISTRIBUTION.md`](https://github.com/dmdhrumilmistry/security-harness/blob/main/docs/DISTRIBUTION.md)。
- ~~在精选参考之上对知识库（PortSwigger/OWASP/CWE）进行可选的实时抓取增强。~~
✅ 已作为上述定时知识库更新器发布。
- 可选的 DAST 桥接，用于对 `needs-runtime` 发现进行运行时确认。
## 许可证
MIT