vuln-hunter

<p align="center"> <img src="https://capsule-render.vercel.app/api?type=waving&color=0:7F1D1D,100:DC2626&height=250&section=header&text=vuln-hunter&fontSize=75&fontColor=ffffff&animation=fadeIn&fontAlignY=35&desc=真正的静态代码分析用于漏洞检测，Claude用于漏洞分诊 — 绝不进行逆向分析&descAlignY=58&descSize=18&descColor=ffffff" alt="vuln-hunter" width="100%"/> </p> AI辅助安全代码审查工具，基于混合架构构建：**Semgrep负责检测，Claude负责分诊。** Claude绝不会自行发现Semgrep未标记的漏洞。 --- ## 为什么选择混合架构，而不是纯LLM 让LLM自由搜索漏洞会导致过多的误报和漏报，难以置信 — 这是“AI安全工具”典型的失败模式。vuln-hunter将任务一分为二： - **Semgrep** （一种真实、广泛使用的静态分析引擎）根据已知的规则模式进行检测 — 作为基本事实。 - **Claude** 严格位于Semgrep的下游：它解释为什么匹配的发现是有风险的，提供可利用性的评级，并建议具体的修复方案。它不会主动搜索Semgrep未发现的问题。 一个刻意的例外是 **业务逻辑推理阶段** （如下所述） — 即使如此，该阶段也保持诚实地独立和清晰标记，从未与规则确认的发现混淆。 --- ## 功能列表 ### 检测 — `scanner.py` 封装`semgrep scan`，为每个发现的结果丰富实际的源代码片段。社区规则包（`p/security-audit`，`p/secrets`）仅凭自身无法完全检测常见的原始Python模式 — 三个自定义规则（`rules/custom-python-security.yml`）弥补了这一空白：通过字符串连接注入SQL， 通过`os.system()`进行Shell注入，通过变量名启发式进行硬编码秘密。针对一个植入的4个漏洞测试用例进行验证：仅使用社区包时发现1/4 → 使用自定义规则时发现4/4，在匹配的干净文件中没有误报。 ### 漏洞分诊 — `triage.py` Claude解释、评估可利用性并为Semgrep已经标记的每个发现建议修复方案 — 系统提示约束使其无法自行发现新的漏洞。 ### 业务逻辑推理阶段 — `business_logic.py` 最具创新性的部分：第二次Claude推理，关注**意图** — 缺失的授权/所有权检查，这种类型的漏洞在结构上对模式匹配是不可见的。来自此阶段的每个发现都标记为`finding_type: "ai_reasoning"` （与Semgrep路径中的`"rule_confirmed"`相对），并在前端以不同的徽章显示 — 绝不混合显示。针对三个测试用例进行验证：一个真实的IDOR漏洞，没有所有权检查（捕获，2/2，高置信度），相同的函数形状**添加了真正的所有权检查**（正确地发现为零 — 证明它正在推理实际的检查，而不是函数名称），以及一个无关的干净测试用例（零制造噪声）。 **此阶段发现了vuln-hunter自身代码中的一个真实漏洞**：`/ignore`和`/scan`端点上没有所有权检查，以及忽略列表泄露被抑制的发现信息给任何调用者。调查**为什么**这很重要，揭示了一个更严重的问题 — **服务器绑定到`0.0.0.0`** （每个网络接口）而不是localhost，这意味着同一网络上的任何人都可以访问这些未经身份验证的端点。已修复：默认为`127.0.0.1`，可通过`API_HOST`覆盖。 ### MCP服务器 — `mcp_server.py` 将`scan_repo`、`scan_diff`、`ignore_finding`和`list_ignored`公开为MCP工具，注册到全局，任何Claude Code会话都可以直接调用它们 — 不仅限于此仓库。使用真实的Anthropic API调用针对植入的漏洞测试用例进行端到端验证，而不仅仅是导入和假设其有效。 ### SARIF 2.1.0 输出 GitHub的Security选项卡和大多数CI工具链所消耗的格式。输出使用`jsonschema`针对真正的官方模式（`schemastore.org/sarif-2.1.0.json`）进行验证，而不仅仅是肉眼检查。 ### 抑制/忽略列表 持久的每个仓库`.vulnhunter-ignore.json`，根据精确匹配的代码（不是行号，不是填充的显示片段）进行指纹识别，因此标记发现为安全后，可以在不相关的编辑附近存活。 ### 仅差异扫描 仅扫描相对于引用更改的文件 — 适用于CI/PR使用。将`git diff`与`git ls-files --others --exclude-standard`联合使用，以便新创建、从未被`git add`的文件对其可见。 ### 凭证的从未读取保证 `.env`、`*.pem`、`*.key`、`id_rsa`、`credentials.json`等在三个层面上被排除 — 作为`--exclude`传递给Semgrep本身（通过Semgrep自己的扫描路径列表确认，而不仅仅是信任），对返回的发现进行防御性过滤，并在源代码片段读取调用站点再次排除。使用临时目录中的伪凭证测试用例进行回归测试。 ### 前端 Next.js 16 + Tailwind 4仪表盘 — 仓库路径输入、扫描按钮、带有可利用性彩色徽章的发现列表、可展开的每个发现的详细信息（源代码片段、解释、markdown渲染的修复方案、CWE/OWASP）。 --- ## 快速入门 ```bash # 后端 cd backend pip install -r requirements.txt python main.py # 默认绑定到 127.0.0.1:8001 # 前端（独立终端） cd frontend npm install npm run dev ``` API默认仅限本地访问 — 它可以扫描任意文件系统路径且无身份验证，因此必须在添加身份验证之前，绝不能在网络上访问。 --- ## 为Claude Code安装 在安装完上述后端依赖后，将其注册为MCP服务器，以便任何Claude Code会话都可以直接调用`scan_repo`、`scan_diff`、`ignore_finding`和`list_ignored`，而无需您单独运行API： ```bash claude mcp add vuln-hunter -- /path/to/vuln-hunter/backend/venv/Scripts/python.exe /path/to/vuln-hunter/backend/mcp_server.py ``` （在macOS/Linux上，请使用`venv/bin/python`而不是`venv/Scripts/python.exe`。） 然后只需告诉Claude Code扫描仓库或差异 — 它将直接调用工具。要让Claude Code为您从头开始设置（克隆、安装依赖、注册MCP服务器），只需告诉它： > “克隆 https://github.com/albatrossflyon-coder/vuln-hunter，在虚拟环境中安装后端依赖，并将其注册为名为vuln-hunter的MCP服务器。” --- ## 已知限制 - 仅为Python编写和测试了自定义规则（社区包涵盖其他语言，但具有上述相同的盲点） - 尚未有正式的测试套件 — 仅手动烟雾测试（`backend/`中的`test_*.py`） - 尚未在任何地方部署 — 在本地运行 - `deep_review`（业务逻辑阶段）目前仅限API使用；前端没有对应的开关，差异扫描端点也没有专用的UI --- ## 许可证 尚未获得许可 — 默认保留所有权利，直到选择许可证。 ## 作者 Chris Brown [Albatross AI](https://albatrossai.online) [作品集](https://chrisbrown-dev.vercel.app)