deepsec-vulnerability-scanner

用途

deepsec 是一款由智能体驱动的安全漏洞扫描器，面向大型代码库，旨在发现难以定位的安全问题。它结合正则匹配器与 AI 深度调查：先用正则快速筛选候选代码点，再由编码智能体（Claude、Codex）以最高思考等级逐一深入分析，产出带严重性评级的可操作发现。

主要能力

• 两阶段扫描：scan 使用正则匹配器快速定位候选点（无 AI 成本）；process 由 AI 深度调查候选点并生成发现与建议。
• 复核与降噪：revalidate 重新检查发现并查看 git 历史中的修复情况，降低误报率。
• 分级与富化：triage 用更便宜的模型做 P0/P1/P2 轻量分类；enrich 补充 git 提交者与归属信息。
• 报告与导出：report 生成单个项目的 Markdown + JSON 摘要；export 支持按发现输出 JSON 或 Markdown 目录；metrics 提供跨项目统计（严重性、漏洞类型、真阳性）。
• 分布式执行：通过 Vercel Sandbox 微虚拟机将工作分散到多个沙箱，适合大型 monorepo。
• 自定义匹配器：用 defineMatcher 编写正则匹配器，可指定严重性、文件 glob、上下文行数与提示。
• 项目上下文注入：INFO.md 会注入每个扫描批次，帮助 AI 理解项目约定。
• 插件扩展：通过 definePlugin 在 enrich 等钩子中扩展发现元数据。
• 幂等与续跑：命令可安全中断并重启，自动从断点继续。

使用方式

1. 安装：在目标仓库根目录运行 npx deepsec init 创建 .deepsec/ 目录，然后 cd .deepsec 并 pnpm install。之后提示编码智能体阅读 SKILL.md 与 SETUP.md，并填写 INFO.md（建议 50–100 行）。
2. 配置 AI 提供商：推荐使用 Vercel AI Gateway（export AI_GATEWAY_API_KEY=vck_...），一个密钥覆盖 Claude 与 Codex；也可直接设置 Anthropic 或 OpenAI 的密钥与 base URL。
3. 核心工作流（在 .deepsec/ 内运行）：
   • pnpm deepsec scan：正则匹配器扫描候选点。
   • pnpm deepsec process：AI 深度调查并输出发现。
   • pnpm deepsec revalidate：可选，复核发现以降低误报。
   • pnpm deepsec export --format md-dir --out ./findings：导出发现。
4. 配置：在 .deepsec/ 下创建 deepsec.config.ts，用 defineConfig 定义项目、模型选择与并发数。
5. 分布式执行：使用 pnpm deepsec sandbox process --project-id my-app --sandboxes 10 --concurrency 4 等命令，需 Vercel 账号，本地工作树打包上传（排除 .git），支持 OIDC 与访问令牌。
6. 查看结果：pnpm deepsec report --project-id my-app、pnpm deepsec metrics、pnpm deepsec status。

适用场景

• 大型代码库的安全审计，尤其是需要发现难以通过传统规则匹配定位的漏洞。
• 需要按严重性分级、按优先级复核的漏洞管理流程。
• 大型 monorepo 的分布式扫描。
• 需要将发现导出为 Markdown 或 JSON 以集成到现有工作流。

限制与注意事项

• 成本：使用最佳模型与最高思考等级，大型代码库可能花费数千至数万美元；建议用 triage（便宜模型）与 revalidate（定向）控制成本；分布式沙箱按 Vercel 计算时间计费。
• 安全模型：应像对待拥有完整 shell 访问权限的编码智能体一样对待 deepsec，仅用于可信输入（自有源代码）。对不可信输入（第三方代码、外部依赖），使用 Vercel Sandbox 限制暴露，API 密钥在沙箱外注入，网络出口受限。
• 误报与漏报：扫描无结果时需检查匹配器是否覆盖文件扩展名；误报率高时可运行 revalidate 并完善 INFO.md。
• 模型拒绝：部分模型会拒绝某些安全内容，需参考 docs/models.md 处理拒绝与替代模型配置。
• 平台依赖：分布式执行需要 Vercel 账号。
• 具体收费价格、平台支持范围等细节以官方文档为准，本资料未提供完整价格表。