deepsec

/deepsec — 使用 deepsec 扫描此代码库

deepsec 是一款 AI 驱动的漏洞扫描器。

• 现代 AI 模型非常擅长进行安全代码审查。
• 大多数审查解决方案只会在拉取请求上运行。
• 这意味着大多数遗留代码从未经过审查，而你 6 个月前编写的代码接受审查时，使用的还是较旧的模型。
• deepsec 则通过扩展 VM 扇出，对你所有现有代码进行安全审查。
• Vercel 的 deepsec 是开源的，可在你自己的基础设施中运行，并支持强大的 Agent 沙箱隔离。

快速正则扫描会标记候选文件，随后 AI Agent 会深入调查每个候选文件，并记录带有严重性评级的发现；之后可以重新验证、分类处理和导出这些发现。它在代码库中添加的所有内容都位于单个 .deepsec/ 工作区中（配置、已安装的程序包、各项目数据）。由于处理过程会运行真正的 AI Agent，因此费用会根据其调查的代码量而变化。

当用户调用 /deepsec 或要求扫描时，请按照此操作手册执行。

1. 首先询问范围

询问用户要处理的范围；如果有结构化提问工具，请使用该工具（在 Claude Code 中使用 AskUserQuestion），否则使用普通文本：

• 未提交的更改 — 工作树 + 未跟踪文件
• 与 main 的差异 — 相对于 origin/main 的更改（如果没有 origin 远程仓库，则使用 main）
• 整个代码库 — 提醒用户这是费用较高的选项：AI 处理会调查每个候选文件，大型代码库可能产生实际费用

在进行其他操作前先询问，以便后续流程可以无人值守地运行。

2. 检测引导设置状态

在代码库根目录中：

• 不存在 .deepsec/deepsec.config.ts → 尚未完成引导设置。完整执行步骤 3。
• .deepsec/ 存在，但缺少 .deepsec/node_modules/deepsec，或者之前的设置被中断 → 重新运行步骤 3 中的初始化命令；该命令会从检查点恢复并修复安装，而不是从头开始。
• 否则 → 已完成引导设置；跳到步骤 4。

3. 完成引导设置，但不进行完整处理

引导设置通常会以对整个代码库进行一次 AI 处理结束。由于用户已经选择了范围，请在覆盖阶段之后停止设置——这仍包括安装、登录、威胁模型、匹配器生成和最终正则扫描，但会跳过针对整个代码库的 AI process 阶段。步骤 4 会进行范围限定的处理。

在代码库根目录中，先检查只读计划，然后运行设置：

npx -y deepsec init --plan --output json
npx -y deepsec init --yes --through coverage --output jsonl

将每一行输出都解析为 JSON。遇到 needs_input 事件时，应向用户显示提供的消息和操作选项，不要自行编造补救措施。特别是，VERCEL_AUTH_REQUIRED 通常会要求用户运行 npx vercel login；用户完成后，请在 .deepsec 中执行返回的链接操作（如果用户需要选择项目，则使用 npx vercel link），然后重新运行相同的初始化命令。退出代码 2 表示需要输入；退出代码 3 表示运行因费用或时长限制而停止，且可以恢复——重新运行相同的命令即可继续。绝不要泄露凭据值、替用户绕过 --yes 提示（该标志本身除外），也不要自行启动交互式登录。

4. 运行范围限定的处理

在 .deepsec/ 中运行（配置加载器只会在当前目录或其祖先目录中查找 deepsec.config.ts；完成步骤 3 后，npx deepsec 会解析到安装在此处的副本）：

范围	命令
未提交的更改	cd .deepsec && npx deepsec process --diff-working
与 main 的差异	cd .deepsec && npx deepsec process --diff origin/main
整个代码库，且紧接步骤 3 之后	cd .deepsec && npx deepsec process（设置期间的最终扫描已生成候选集）
整个代码库，且之前已完成引导设置	cd .deepsec && npx deepsec scan && npx deepsec process

5. 解读结果

• 直接模式（--diff*）的退出代码：0 = 没有新增发现，1 = 至少有一项新增发现（不是错误），其他任何值 = 运行时错误。 被触及文件中已有的发现不计入门禁。
• 向用户总结发现的问题，然后提供后续操作（均在 .deepsec/ 内执行）：npx deepsec report、npx deepsec revalidate 和 npx deepsec export --format md-dir --out ./findings。

深入了解

完成入门配置后，完整文档会随已安装的包一同提供，位于 .deepsec/node_modules/deepsec/dist/docs/ — getting-started.md、 reviewing-changes.md（直接模式、退出代码、CI 门禁）、 configuration.md、models.md 等。更改上述命令之前，请先阅读相关文档；不同版本中的标志和默认值会有所变化。