JoseAFlores777/vuln-hunter

# vuln-hunter 🛡️ (v1.1) 适用于 Claude Code 的**多智能体**工具包，用于在项目或 monorepo 中**检测、监控威胁、分类、规划、修复、修补和验证**漏洞。与 **OWASP Top 10 (2021 和 2025)** 保持一致。每个子智能体都被设定为真实的安全专业人员模型。 ## 7 个智能体 | 智能体 | 角色 / 设定 | 方法论 | |---|---|---| | `recon-cartographer` | 攻击面测绘者 | PTES, STRIDE, PASTA, attack trees | | `sast-analyst` | 静态分析（**自有代码**） | Taint/data-flow, Semgrep/Bandit/Roslyn, SARIF | | `threat-intel-scout` | CTI / 漏洞管理（**依赖项**） | OSV/NVD/KEV/EPSS, SSVC, MITRE ATT&CK T1190 | | `redteam-whitehat` | 道德渗透测试员 (OSCP/OSWE) | PTES, WSTG — **概念性 PoC** | | `triage-judge` | 分类分析师 | CVSS v4.0/v3.1, EPSS, CISA KEV | | `appsec-fixer` | 安全架构师 / AppSec | OWASP ASVS v5.0.0 — 根本原因修复 | | `verify-engineer` | 验证 / 检测 | 重新扫描 + 测试，诚实验证 | ## 命令 | 命令 | 功能 | |---|---| | `/vuln-hunter:hunt [path] [--dry-run] [--solo-deteccion]` | 统筹完整流程（自动检测并恢复之前的运行） | | `/vuln-hunter:resume [path]` | 从上次运行中断的地方**恢复**（迁移账本，向后兼容，并继续执行链而不重复阶段） | | `/vuln-hunter:detect [path]` | 检测 monorepo 的技术栈（范围界定） | | `/vuln-hunter:scan [path]` | 代码的 SAST（委托给 sast-analyst） | | `/vuln-hunter:rescan ` | **重新扫描**子树的 SAST 并与账本合并；将不再出现的漏洞标记为已解决候选 | | `/vuln-hunter:watch [lockfile] [--gate]` | **针对生产环境依赖项的威胁情报**（OSV/NVD/KEV/EPSS） | | `/vuln-hunter:redteam [VULN\|all]` | 确认可利用性（概念性） | | `/vuln-hunter:triage` | 优先级排序（CVSS+EPSS+KEV） | | `/vuln-hunter:plan` | 补救计划（如果有则使用 superpowers，否则使用自带功能） | | `/vuln-hunter:fix [VULN\|all]` | 应用修复（不提交） | | `/vuln-hunter:patch` | 生成 Diffs + 通过哈希值进行人工审批 + 提交 | | `/vuln-hunter:verify [VULN\|all]` | 验证漏洞已修复且无回归 | | `/vuln-hunter:report [salida.html]` | 从账本生成可重现的 HTML 报告 | | `/vuln-hunter:status` | **仪表盘**：流程进度、发现的问题及下一个命令 | | `/vuln-hunter:panel [puerto]` | **实时面板**（React+CDN，静态）：读取 `.vuln-hunter/ledger.json` + `activity.jsonl` 并每 2 秒轮询一次，以实时查看发现的问题及其缓解措施 | ## 流程 ``` recon → [ scan (SAST código) ∥ watch (SCA dependencias) ] → red-team → triage → PLAN → fix → patch (aprobación por hash) → verify → report ``` ## 共享状态：账本 所有智能体都会读写 `.vuln-hunter/ledger.json`（schema 位于 `schemas/ledger.schema.json`）。任何人都不会传递纯文本：每个智能体都会丰富同一对象的相应部分。这统一了严重程度、去重以及最终报告。 ## 勒索软件防护（新增） `threat-intel-scout` 将你的**生产环境**依赖项与官方数据源进行交叉比对，并将 **CISA KEV** 中或 **EPSS** 高危的 CVE 标记为**部署阻断项** —— 这是勒索软件典型的初始攻击向量（MITRE ATT&CK **T1190**）。 `scripts/deploy-gate.py` 会从账本中提取 `.vuln-hunter/deploy-blocked`，并且 hook 会在修补之前**阻止通过 Claude 执行的部署命令**（在插件之外启动的部署不在其管控范围内）。请按如下方式使用： ``` /vuln-hunter:watch --gate # veredicto APTO / BLOQUEADO ``` ## 安装 ``` /plugin marketplace add JoseAFlores777/vuln-hunter /plugin install vuln-hunter@vuln-hunter-marketplace ``` Marketplace 跟踪 `main` 分支，因此你**安装的始终是最新版本**。 **superpowers 是可选的**（用于改进规划）。如果你需要它： ``` /plugin marketplace add obra/superpowers-marketplace /plugin install superpowers@superpowers-marketplace ``` ### 更新到最新版本 Claude Code 不会在后台自动更新；当你刷新时会拉取 `main` 的最新内容： ``` /plugin marketplace update vuln-hunter-marketplace /plugin update vuln-hunter ``` ## 版本控制与发布（维护者） 版本信息存在于单一逻辑位置，并使用 `scripts/bump-version.py` 在 Claude Code 读取的三个字段（`plugin.json:version`、`marketplace.json:metadata.version` 和 `marketplace.json:plugins[].version`）中保持同步。 发布流程是**基于 tag 的** —— 你只需推送一个 tag，GitHub Actions 会完成剩下的工作： ``` scripts/release.sh 1.3.0 # = git tag v1.3.0 && git push origin v1.3.0 ``` 随后，`Release` 工作流（`.github/workflows/release.yml`）将执行以下操作： 1. 运行测试套件（门槛检查）。 2. 如果存在偏差，将清单中的版本同步为 `1.3.0` 并提交至 `main` 分支（这由 `github-actions[bot]` 完成，而不是你本地的 hook）。 3. 发布自动生成更新说明的 **GitHub Release** `v1.3.0`。 `scripts/release.sh` **不会在本地提交**（仅推送 tag），因此不会与 `guard-commit` hook 产生冲突。此外，`CI`（`.github/workflows/ci.yml`）会在每次推送/PR 时验证版本字段是否同步。 ## 验证这不是“安全剧场” 包含一个内置了 **9 个漏洞**及其 ground truth 的实验室，位于 `examples/vulnerable-lab/`。在 `--dry-run` 模式下运行流程并进行对比： ``` /vuln-hunter:detect examples/vulnerable-lab /vuln-hunter:hunt examples/vulnerable-lab --dry-run ``` 计算真正例（9个中的）、假反例和假正例数量（包含一个不应被标记的负对照组）。这个数字会告诉你该插件是否有效。 ## 批准补丁（人工操作） ``` git add # stagea EXACTO lo revisado git diff --cached HEAD # revisa el indice staged python3 scripts/approve-diff.py # aprueba ESE indice (por hash) # 如果重新 stageas/editas，批准将会过期：请重新批准 ``` ## 安全防护 —— 深度防御，而非绝对保障 **首先要诚实：** 最主要的防线是**对 diff 的人工审查**以及每个智能体的 **`tools:` 白名单**。这些 hook 属于**深度防御**，在检查 shell 命令字符串时，它们是**尽力而为的，且可以被绕过的**（足够混淆的命令可能会避开它们；此外，PreToolUse hook 只能看到 Claude 执行的内容，看不到在插件之外启动的操作）。请勿将其视为绝对的保障。 - `guard-commit-and-exec.py` — 将批准与**暂存区索引**（`git diff --cached HEAD`）绑定；拦截明显的包装器（`bash -c`、`eval`、`git -C/-c`、`commit -a`），但其提交检测机制属于保守的黑名单机制。 - `block-exploit-write.py` — 拦截可执行的漏洞利用代码内容；对可疑文件名发出警告。遇到无法读取的输入时执行关闭/阻断。 - `guard-webfetch.py` — 将 `threat-intel-scout` 的 WebFetch 限制在官方来源（https + 主机白名单）；不影响会话其余部分的 WebFetch。 ## 结构 ``` vuln-hunter/ ├── .claude-plugin/{plugin.json, marketplace.json} ├── agents/ (7 subagentes) ├── commands/ (15 slash commands) ├── skills/ (stack-detector, owasp-reference, ledger-contract, ...) ├── hooks/ (hooks.json + 3 guardianes: commit/exec/deploy, exploit-write, webfetch) ├── scripts/ (run-scan.sh, intel-cache.sh, approve-diff.py, deploy-gate.py, │ report.py, ledger.py, status.py, activity.py, build-panel.sh, ...) ├── panel/ (index.html compilado + app.jsx fuente) ├── schemas/ (ledger.schema.json) ├── examples/ (vulnerable-lab con ground truth) ├── docs/ (landing + informes de auditoría) ├── CLAUDE.md (reglas persistentes) · SECURITY.md (aislamiento + reporte) └── README.md ``` ## 隔离（重要） 审计某个 repo 会执行该 repo 的工具（测试、eslint 的 config/plugins、安装脚本） → 可能会运行其代码。如果你**不信任**该 repo，请在没有凭证或内部网络的隔离容器/虚拟机中运行。参见 [`SECURITY.md`](SECURITY.md)。 ## 用途 —— 以及它无法替代的内容 vuln-hunter 可帮助你尽早（左移）**识别、确定优先级并缓解**漏洞：这是一次**严谨、可重现且具备可追溯性**的初步扫描，能指明重点检查方向并加快修复速度。 不建议将其作为**唯一**的安全措施。它**无法替代**： - **独立的人工审计**或**专业的渗透测试**； - 在你的 pipeline 中运行的**专用 SAST/DAST 工具**（或商业工具）； - 正式的**代码审查**和漏洞管理流程。 并且请记住：**这些 hook 是可被绕过的深度防御机制，而非绝对保障**；最根本的防线是对变更的**人工审查**。请将其作为一种加速和聚焦工作的**辅助工具**，通过实验室（`examples/vulnerable-lab`）衡量其准确性，在信任并用于生产环境之前，务必结合更严格的措施。MIT 许可证。 ## 可视化与分步指南 (v1.2) 每个智能体都以统一的格式呈现其结果（`agent-presentation` skill）：带图标的标题、3 行摘要、带有严重程度红绿灯表情符号的发现表（🔴P0 🟠P1 🟡P2 🟢P3 ⚪已过滤）、流程进度条，以及一个**"▶ 下一步"**区块，推荐需要执行的确切命令。 你随时可以使用 `/vuln-hunter:status` 来显示**确定性仪表盘**（由 `scripts/status.py` 从账本中生成，不依赖 LLM），它会展示你当前所处的流程节点、按严重程度分类的发现、KEV 警报以及推荐的后续命令。系统会通过逐一列出的问题（一次一个）或在环境支持的情况下通过按钮来请求决策。 要进行实时查看，`/vuln-hunter:panel` 会启动一个静态前端（预编译的 JSX，浏览器端无需构建），**仅在 127.0.0.1** 上提供服务。状态的唯一事实来源是账本；`activity.jsonl`（仅追加，由 `scripts/activity.py` 写入）是时间线。面板会在审计运行期间每 2 秒进行一次轮询。参见 `docs/adr/0001-panel-liveness-architecture.md`。 **运行历史。** 生成报告时，`scripts/archive-run.py` 会将本次运行快照（账本 + 活动 + 报告 + 摘要）保存到 `.vuln-hunter/history//` 并更新 `history/index.json`。面板提供了一个**运行选择器**：可以选择“实时”（当前正在运行，带轮询）或以只读模式查看过去的任何审计记录。历史记录是**本地**的（`.vuln-hunter/` 在 .gitignore 中）：它会保存在你的机器上但不会被提交，因此漏洞发现的细节不会被推送到 git 中。  流水线图（GitHub Actions 风格）显示了正在工作的智能体，以及并行的 `scan`/`watch` 分支；日志是不断发现内容的时间线；**已发现 / 修复中 / 已修复**标签页会随着进展移动每一项发现。若要恢复之前的运行，请使用 `/vuln-hunter:resume`（向后兼容：在不丢失状态的情况下迁移账本），若要重新扫描某个子树，请使用 `/vuln-hunter:rescan `。

标签：CISA项目, Claude Code, DevSecOps, GPT, 上游代理, 代码安全审计, 多智能体, 安全漏洞利用, 漏洞管理, 逆向工具