deepsec

deepsec 是一个基于智能体的漏洞扫描器，可在您自己的基础设施中运行，专门针对现有大规模仓库中的所有代码进行按需审查，并经过优化。

deepsec 旨在发现那些长期潜伏在应用中、难以定位的问题。它配置为使用最佳模型并以最高思考级别运行（可通过 --thinking-level 调节，详见 docs/models.md），这意味着对于大型代码库，扫描成本可能高达数千甚至数万美元。我们的客户认为，考虑到他们能够迅速修补那些原本可能永远无法修复的漏洞，这笔成本是值得的。

对于大型代码库，工作会并行分发到多台工作机器上。如果运行中断或在途中出错，只需重新运行相同的命令——deepsec 会从断点处继续，跳过已经分析过的文件，只处理剩余部分。

快速开始

进入您要扫描的仓库根目录，然后运行：

npx deepsec init       # 创建 .deepsec/ 并将此仓库设为第一个项目
cd .deepsec
pnpm install           # 从 npm 安装 deepsec

# 按照 `init` 输出的指示继续

现在，让您的编码助手引导完成安装。打开您选择的助手并输入提示：

阅读 .deepsec/node_modules/deepsec/SKILL.md 了解该工具。然后阅读 .deepsec/data/<id>/SETUP.md 并按照其指示：浏览本仓库的 README、任何 AGENTS.md/CLAUDE.md 以及少量代表性代码文件，然后替换 .deepsec/data/<id>/INFO.md 中的每个部分。

保持简短——目标总行数为 50–100 行。每个部分挑选 3–5 个示例，不要穷举。提及原语（如认证助手、中间件）但不要包含行号。跳过通用的 CWE 类别——内置匹配器会覆盖这些。只覆盖项目特有的内容。INFO.md 会被注入到每个扫描批次中；冗长的上下文会稀释信号。

然后从 .deepsec/ 目录内进行扫描：

pnpm deepsec scan
pnpm deepsec process    
pnpm deepsec revalidate # 可选，降低误报率
pnpm deepsec export --format md-dir --out ./findings

如果您觉得 deepsec 应该查看更多代码部分，可以向它提供 编写匹配器 文档，以便在代码库中找到更多有价值的起点。

文档

• docs/getting-started.md — 首次扫描指南
• docs/reviewing-changes.md — 用于 PR 审查和 CI 门控的 process --diff
• docs/supported-tech.md — deepsec 开箱即用的框架和生态系统
• docs/writing-matchers.md — 提示您的编码助手扩展匹配器集
• docs/configuration.md — deepsec.config.ts 参考
• docs/plugins.md — 插件开发
• docs/models.md — 模型选择、默认值、拒绝情况及未来模型
• docs/vercel-setup.md — AI Gateway + Vercel Sandbox 密钥/令牌
• docs/architecture.md — 管道内部原理
• docs/data-layout.md — data/ 模式（FileRecord、RunMeta 等）
• docs/faq.md — 成本、模型选择、沙箱模式、误报率
• samples/ — 可复制粘贴的起点（当前为 webapp/）
• CONTRIBUTING.md — 仓库布局、开发工作流

AI 提供商

在本地运行时，如果您已在本机器上登录，deepsec 会自动回退到您现有的 claude / codex 订阅。订阅（Claude Pro/Max、ChatGPT Plus）对于评估 deepsec 很有用，但通常没有足够的额度来完成完整的仓库扫描。

对于真实扫描，请使用 Vercel AI Gateway。一个密钥即可同时覆盖 Claude 和 Codex，且该网关的默认配额专为高并发研究而设计。

AI_GATEWAY_API_KEY=vck_...

有关如何获取密钥以及 Vercel Sandbox 的设置，请参阅 docs/vercel-setup.md。若要绕过网关，请显式设置 ANTHROPIC_AUTH_TOKEN + ANTHROPIC_BASE_URL（或对应的 OpenAI 配对）。显式值始终优先于 AI_GATEWAY_API_KEY 扩充。

如果 process 或 revalidate 运行因上游凭证配额或积分耗尽而停止，deepsec 会优雅地停止并告知您在哪里充值。之后重新运行相同的命令，它会从断点处继续。

分布式执行（可选）

大型单体仓库可以将工作分散到 Vercel Sandbox 微虚拟机中：

pnpm deepsec sandbox process --project-id my-app --sandboxes 10 --concurrency 4

需要一个 Vercel 账户。本地工作树会被打包并上传；.git 被排除。支持 OIDC 令牌（本地）和访问令牌（CI）——请参阅 docs/vercel-setup.md。

deepsec 自身的安全模型

将 deepsec 视为一个具有对其运行环境完全 shell 访问权限的编码代理。它被设计为在受信任的输入（您的源代码）上运行，但您可能仍然担心由于外部依赖或供应商代码而导致的提示注入。

在沙箱中运行（见上文）确实可以显著限制潜在暴露：

• 编码代理的 API 密钥在沙箱外部注入，因此无法被渗透
• 对于工作沙箱，沙箱的网络出站仅限制为编码代理主机（引导过程中允许出站，但此过程不运行编码代理）

工作流参考

许可证

Apache 2.0。参见 LICENSE 和 NOTICE。