/bug-hunter

对抗式 AI 漏洞检测与自动修复工具，专为 Coding Agent 设计
多 Agent 流水线，能够发现安全漏洞、逻辑错误和运行时 Bug —— 然后在安全的分支上自主修复它们。

## 为什么选择 Bug Hunter？ LLM 是盲从的代码审查者。让它找 Bug，它会过度报告。让它验证这些 Bug，它会自我附和。结果就是：噪音、误报、浪费时间。 **Bug Hunter** 通过让多个 AI Agent 在隔离的上下文中相互对抗来解决这个问题。每个 Agent 都有相互竞争的激励 —— 这种对抗性的张力能产生高保真、极少误报的 Bug 报告。 与传统的静态分析工具不同，Bug Hunter 理解运行时行为、跨文件依赖和特定框架的模式。它能捕捉到 Linter 遗漏的 Bug。 ## 对抗式 Bug 检测的工作原理 ### 阶段 1 —— 发现并验证 Bug ``` +-- Hunter-A (Security lens) --+ +-- Skeptic-A (cluster 1) --+ Recon (map) ------->| |-- merge ->| |-- merge --> Referee +-- Hunter-B (Logic lens) --+ +-- Skeptic-B (cluster 2) --+ ``` | 步骤 | Agent | 功能 | 评分激励 | |------|-------|--------------|-------------------| | 1 | **Recon** | 映射代码库架构，识别信任边界，计算上下文预算 | 准确的风险图 = 更好的 Hunter 覆盖率 | | 2 | **Hunters** | 双重视角扫描（安全 + 逻辑），每个文件强制执行安全检查清单 | 每个真实 Bug +1/+5/+10。每个误报 -3 | | 3 | **Skeptics** | 对抗性地质疑每一个发现，通过 Context7 对照真实文档验证声明 | 驳倒误报 +分数。错误驳回真实 Bug **-2x 惩罚** | | 4 | **Referee** | 独立阅读代码，抽查证据引用，做出最终裁决 | 对称的 +1/-1 评分。基于事实的框架 | 每个 Agent 都在**完全隔离的上下文**中运行 —— 它们看不到彼此的推理过程，只能看到结构化的发现。这可以防止锚定偏差并强制进行独立验证。 ### 阶段 2 —— 自动修复与验证 ``` +-- Fixer-A (worktree 1) --+ Git branch ------>| |-- merge --> Test diff --> Report +-- Fixer-B (worktree 2) --+ ``` | 步骤 | Agent | 功能 | |------|-------|--------------| | 5 | **Fixers** | 在隔离的 git worktree 中应用最小化的手术式修复，每个 Bug 一个检查点提交 | | 6 | **Verify** | 运行测试套件，与基线进行对比，自动回退任何引入回归的修复 | | 7 | **Re-scan** | 轻量级 Hunter 仅扫描更改的行，以捕捉修复者引入的 Bug | 每个修复都是一个独立的提交，可以单独回退。失败的修复会自动回退 —— 保持代码库整洁。 ## 支持的 Coding Agent 和编辑器 ### Coding Agents (CLI) | Agent | 状态 | |-------|--------| | **Claude Code** | 完全支持 | | **OpenAI Codex CLI** | 完全支持 | | **GitHub Copilot CLI** | 完全支持 | | **Kiro CLI** (AWS) | 完全支持 | | **Pi Coding Agent** | 完全支持 | | **Opencode** | 完全支持 | | **Gemini CLI** | 完全支持 | | **Amp** | 完全支持 | ### 编辑器和 IDE | 编辑器 | 状态 | |--------|--------| | **Cursor** | 完全支持 | | **VS Code** / **Windsurf** | 完全支持 | | **JetBrains** (IntelliJ, PyCharm, WebStorm) | 完全支持 | | **Antigravity** (Google) | 完全支持 | | **Neovim** / **Vim** | 通过终端完全支持 | ### 终端 适用于**任何终端** —— iTerm2, Ghostty, Warp, Alacritty, Kitty, Hyper, Windows Terminal。 ## 安装 ``` git clone https://github.com/codexstar69/bug-hunter.git ~/.claude/skills/bug-hunter ``` Coding Agent 会自动发现 `~/.claude/skills/` 中的技能。 ### 设置 Context7（推荐） Bug Hunter 使用 [Context7](https://context7.com) API 根据真实文档验证有关库和框架行为的声明。这显著减少了因臆造框架假设而产生的误报。 1. 从 [context7.com](https://context7.com) 获取免费的 API 密钥 2. 添加到你的 shell 配置文件（`.zshrc`, `.bashrc` 等）： ``` export CONTEXT7_API_KEY="your-api-key-here" ``` 3. 重启你的终端 首次运行时，Bug Hunter 会检查密钥并运行冒烟测试。如果缺失，它会提示你进行设置。 ## 使用方法 ``` /bug-hunter # Scan entire project /bug-hunter src/ # Scan specific directory /bug-hunter lib/auth.ts # Scan specific file /bug-hunter -b feature-xyz # Scan files changed in feature-xyz vs main /bug-hunter -b feature-xyz --base dev # Scan files changed in feature-xyz vs dev /bug-hunter --staged # Scan staged files (pre-commit check) /bug-hunter --fix src/ # Find bugs AND auto-fix them /bug-hunter --fix -b feature-xyz # Find + fix on branch diff /bug-hunter --fix --approve src/ # Find + fix, but approve each fix manually /bug-hunter --loop src/ # Loop mode: audit until 100% coverage /bug-hunter --loop --fix src/ # Loop mode: find + fix until clean ``` ### 自动缩放模式 流水线根据代码库大小自动选择合适的模式。Recon 根据平均文件大小动态计算每个 Agent 的上下文预算。 | 模式 | 源文件数 | 启动的 Agent | |------|-------------|-----------------| | **Single-file** | 1 | 1 Hunter + 1 Skeptic + 1 Referee | | **Small** | 2-10 | 1 Hunter + 1 Skeptic + 1 Referee | | **Parallel** | 11-40 | Recon + 2 Hunters + 2 Skeptics + Referee | | **Extended** | 41-80 | Recon + 4 Hunters + 2 Skeptics + Referee | | **Scaled** | 81-120 | Recon + 6 Hunters + 3 Skeptics + Referee | | **Loop** | 120+ | 分批迭代，直到实现完全覆盖 | ## 它能捕捉哪些 Bug？ Bug Hunter 扫描**行为性 Bug** —— 即在运行时导致不正确行为的问题： - **安全漏洞** —— SQL 注入、身份验证绕过、SSRF、路径遍历、硬编码密钥、无过期时间的 JWT - **逻辑错误** —— 差一错误、错误的比较、条件反转、分页功能损坏 - **错误处理缺失** —— 静默吞掉错误、缺少 null 检查、未处理的 promise rejection - **类型安全问题** —— 跨边界的类型强制转换陷阱、向仅接受字符串的 API 传递非字符串输入 - **竞态条件** —— 异步 I/O 交错、未经协调的共享可变状态 - **API 契约违规** —— 错误的状态码、缺少必需字段、调用方损坏 - **数据完整性 Bug** —— 截断、编码问题、时区 Bug、整数溢出 - **跨文件 Bug** —— 跨模块边界的假设不匹配、调用链中的身份验证缺口 ### 它跳过的内容（设计如此） 风格、格式、命名约定、未使用的导入、缺失的类型、TODO 注释、测试覆盖率缺口、依赖版本。这些是 Linter 和类型检查器的职责。 ## 评分系统 评分激励是**承载关键作用的** —— 它们利用了每个 Agent 想要最大化其分数的愿望： | Agent | 评分 | 效果 | |-------|---------|--------| | **Hunter** | 每个真实的低/中/危级 Bug +1/+5/+10。每个误报 -3 | 激励彻底性，但惩罚草率 | | **Skeptic** | 有效驳倒 +分数。错误驳回真实 Bug **-2x 分数** | 产生校准过的谨慎 —— 仅在置信度 >67% 时才进行驳倒 | | **Referee** | 对称的 +1/-1，基于事实框架 | 精确而非偏向任何一方 | 五个真实的 Bug 胜过二十个误报。质量胜于数量。 ## 自主修复流水线 默认情况下，修复流水线是**完全自主的** —— 无需人工干预。Bug 会被发现、修复、测试和端到端验证。 **所有修复都在单独的分支上进行。** 你的工作分支永远不会被触碰。审查 diff，然后在准备好时合并。 | 模式 | 行为 | |------|----------| | `--fix` (默认) | 完全自主 —— 创建分支、应用修复、运行测试、自动回退失败项 | | `--fix --approve` | 在每次修复前暂停以等待人工批准 | ### Git 安全与分支保护 1. **专用修复分支** —— 从你当前的分支创建 `bug-hunter-fix-`。你的代码在合并前保持原样。 2. **暂存未提交的工作** —— 在修复开始前，任何脏的工作树都会被暂存，并在之后恢复 3. **测试基线** —— 捕获修复前的测试结果，用于准确的回归对比 4. **检查点提交** —— 每个 Bug 修复都是一个单独的 `fix(bug-hunter): BUG-N` 提交 5. **回归时自动回退** —— 如果修复导致新的测试失败，会通过 `git revert` 自动回退 6. **修复后重新扫描** —— 轻量级 Hunter 仅扫描更改的行，以捕捉修复者引入的 Bug 7. **单独的可回退性** —— 任何单个修复都可以被手术式回退，而不影响其他修复 8. **测试钩子自动检测** —— 从你的项目配置中自动检测测试运行器、类型检查和构建命令 ## 支持的语言 Bug Hunter 适用于你的 Coding Agent 能读取的任何语言。已在以下语言中进行了广泛测试： - TypeScript / JavaScript (Node.js, React, Next.js, Express) - Python (Django, Flask, FastAPI) - Go - Rust - Java / Kotlin - Ruby - PHP ## 项目结构 ``` bug-hunter/ SKILL.md # Core dispatcher (argument parsing, mode routing, report) prompts/ # Agent prompt files recon.md # Architecture mapper hunter.md # Bug finder (dual-lens: security + logic) skeptic.md # Adversarial challenger referee.md # Final arbiter fixer.md # Surgical code fixer doc-lookup.md # Context7 doc verification reference modes/ # Execution mode files (loaded on demand) single-file.md # 1 file small.md # 2-10 files parallel.md # 11-40 files extended.md # 41-80 files scaled.md # 81-120 files loop.md # Coverage tracking across iterations fix-pipeline.md # Phase 2: fix + verify fix-loop.md # Combined find + fix loop scripts/ context7-api.cjs # Context7 doc lookup CLI init-test-fixture.sh # Initialize test fixture git repo test-fixture/ # Self-test app with planted bugs assets/ # Images and diagrams ``` ## 自我测试 Bug Hunter 附带一个测试固件 —— 一个包含 6 个故意植入的 Bug（2 个危级，2 个中级，2 个低级）的小型 Express 应用。运行它来验证流水线： ``` /bug-hunter test-fixture/ ``` 预期结果： - Recon 将 3 个文件归类为 CRITICAL，1 个归类为 HIGH - Hunters 发现所有 6 个 Bug - Skeptic 质疑至少 1 个误报 - Referee 确认所有植入的 Bug ## 常见问题 ### 这与 Linter 或静态分析工具有何不同？ Linter 检查语法和风格。静态分析工具检查类型安全和简单模式。Bug Hunter 发现**运行时行为性 Bug** —— 逻辑错误、安全漏洞、竞态条件以及任何 Linter 都无法检测的跨文件假设不匹配。它理解你的代码*做什么*，而不仅仅是它看起来怎么样。 ### 它会直接修改我的代码吗？ 不会。所有修复都应用在**专用分支**（`bug-hunter-fix-`）上。你的工作分支永远不会被修改。你审查 diff 并在准备好时合并。 ### 如果修复破坏了某些东西怎么办？ 每个修复都是一个单独的检查点提交。如果修复导致新的测试失败，它会**自动回退** —— 无需手动清理。代码库保持整洁。 ### 如何在应用修复前进行审查？ 使用 `--approve` 模式：`/bug-hunter --fix --approve src/`。系统会在每次修复前暂停并等待你的批准。 ### 它支持哪些语言？ 你的 Coding Agent 能读取的任何语言。已在 TypeScript、JavaScript、Python、Go、Rust、Java、Kotlin、Ruby 和 PHP 上进行过测试。 ### 它如何减少误报？ 三种机制：(1) 对抗性 Skeptic Agent 质疑每一个发现，(2) Context7 文档验证对照真实的库文档，(3) 独立的 Referee 在做出最终裁决前从头阅读代码。Agent 的评分带有非对称惩罚，使得误报代价高昂。 ## 更新 ``` cd ~/.claude/skills/bug-hunter && git pull ``` ## 卸载 ``` rm -rf ~/.claude/skills/bug-hunter ``` ## 许可证 MIT —— 详情请参阅 [LICENSE](LICENSE)。

标签：Bug Bounty, CISA项目, Claude Code, DevSecOps, DLL 劫持, GitHub Copilot, JS文件枚举, LNA, PyRIT, Python, 上游代理, 云安全监控, 人工智能, 代码安全, 代码审查, 可自定义解析器, 可视化界面, 多智能体系统, 大语言模型, 对抗性AI, 数据可视化, 无后门, 日志审计, 漏洞枚举, 用户模式Hook绕过, 自动修复, 自定义脚本, 软件开发, 运行时错误, 逆向工具, 逻辑错误检测, 错误基检测, 静态代码分析, 静态分析