oma-deepsec

Deepsec：由 Agent 驱动的漏洞扫描器

调度

目标

在目标代码仓库中安全且注重成本地运行 Vercel 的 deepsec 安全扫描器：初始化 .deepsec/ 工作区，编写精简的 INFO.md，按正确顺序执行扫描、处理、分流、重新验证和导出；通过 process --diff 在 CI 中设置 PR 门禁；扩展项目专属匹配器，展示真实且经重新验证的发现，同时避免成本失控。

意图特征

• 用户提到 deepsec、“deep security scan”、bunx deepsec、pnpm deepsec、npx deepsec。
• 用户要求 Agent 扫描代码仓库中的漏洞、安全问题或 CVE，且项目已有（或应该有）.deepsec/ 目录。
• 用户询问如何添加 deepsec PR / CI 安全门禁，或询问 process --diff、--diff-staged、--diff-working、--files-from、--comment-out。
• 用户提到 deepsec 产物：INFO.md、SETUP.md、data/<id>/files/、FileRecord、RunMeta、revalidation、triage、自定义匹配器、MatcherPlugin、noiseTier、priorityPaths。
• 用户询问 deepsec 配置：deepsec.config.ts、defaultAgent、AI_GATEWAY_API_KEY、VERCEL_OIDC_TOKEN、AI Gateway、Vercel Sandbox、--agent codex、--agent claude。
• 用户询问如何降低 deepsec 成本、减少误报率，或解读严重性、分流或重新验证判定。

适用场景

• 在代码仓库中首次安装 deepsec（init、编写 INFO.md、首次校准扫描）。
• 运行完整扫描或范围扫描并处理发现。
• 使用 process --diff 和 --comment-out 设置逐 PR 的 CI 门禁。
• 编写项目专属匹配器，覆盖默认匹配器集遗漏的入口点。
• 分流积压的发现（按严重性分类、通过 revalidate 筛除误报、导出到问题跟踪系统）。
• 诊断 deepsec 故障：缺少凭据、AI Gateway 配额用尽而停止、拒绝、沙箱身份验证问题。

不适用场景

• 不使用 deepsec 的通用 OWASP / lint 风格审查 → 使用 oma-qa。
• 通用 CVE / 依赖项公告 → 使用 oma-qa 或 oma-search。
• 设计不使用 deepsec 的全新 SAST 流水线 → 使用 oma-architecture。
• 编写或审计应用程序代码本身 → 转交给 oma-backend / oma-frontend / oma-mobile。
• 云 / IAM / Terraform 加固 → 使用 oma-tf-infra（deepsec 只扫描 IaC；修复工作由该工具负责）。
• 仅针对产品代码中某项发现进行推理并确定修复方案 → deepsec 生成该发现后，使用 oma-debug。

预期输入

• target_repo_root：要扫描的代码库的绝对路径（.deepsec/ 的父目录）。
• intent：setup | scan | pr-review | matchers | triage | config | troubleshoot 之一。
• credential_mode：ai-gateway-key | vercel-oidc | direct-anthropic | direct-openai | subscription。
• agent_choice：使用用户指定的后端、已配置的 defaultAgent，或授权范围内的选项；仅在仍有重要选项未确定时才询问。
• severity_floor：值得展示的最低严重性（通常为 HIGH）。
• 可选：现有 .deepsec/data/<id>/、deepsec.config.ts、自定义匹配器、CI 提供方。

预期输出

• 一个已关联到目标代码仓库的可用 .deepsec/ 工作区。
• 一份内容完整的 data/<id>/INFO.md（50-100 行，针对项目编写，不含行号）。
• 一次或多次已完成的 scan → process（→ triage/revalidate）运行，并附有可复现的成本说明。
• PR 模式：使用 process --diff <base> 的 CI 工作流文件，并采用双作业拆分（处理 PR 代码的作业不得写入 PR）。
• 匹配器：新增 .deepsec/matchers/<slug>.ts 文件，并通过 deepsec.config.ts 中的内联插件接入。
• 发现项导出（md-dir 和/或 json），以及关于最高严重性和误报率的简短摘要。
• 在任何可能花费超过约 $25 的扫描轮次开始之前，明确说明以金额和时间为限的计划。

依赖项

• Node.js 22+，以及一个包管理器：bun / bunx（在此 monorepo 中优先使用）、pnpm、npm 或 yarn。
• 可用的 AI 凭据：AI_GATEWAY_API_KEY=vck_…、VERCEL_OIDC_TOKEN、直接使用 ANTHROPIC_AUTH_TOKEN + ANTHROPIC_BASE_URL，或已登录的 claude / codex CLI 订阅。
• Git（revalidate 和 --diff 模式会参考历史记录）。
• 可选：用于 deepsec sandbox … 分布式运行的 Vercel Sandbox 身份验证。
• resources/ 下的参考资源（仅在场景需要时加载）。

控制流功能

• 根据 intent 分支（setup、scan、pr-review、matchers、triage、config 或 troubleshoot）。
• 根据仓库规模分支（大规模扫描前先用 --limit 50 进行校准）。
• 根据凭据来源分支（网关密钥、OIDC、直接凭据、订阅）。
• 配额 / 额度耗尽时停止，并在充值后恢复运行同一命令。
• 尚未校准且仓库规模较大时，拒绝启动无界的 process。
• 读取代码库、写入 .deepsec/ 文件和 CI 配置，并运行长时间的 AI 进程。

结构流程

入口

1. 确认 .deepsec/ 是否已存在；如果存在，将本次运行视为增量运行，绝不重新初始化。
2. 根据用户提示确定 intent；如果含义不明确（例如“扫描这个仓库”），则默认为先 setup 再 scan（校准模式）。
3. 估算规模：统计源文件数量（粗略使用 rg --files | wc -l，排除 node_modules、.git、dist），在任何 AI 扫描前预测成本。
4. 确定所选的凭据模式和后端。检查其所需的环境配置或现有的 claude / codex 订阅登录状态，不回显机密信息。有效的订阅会话无需 API 密钥环境变量。仅在调用 AI 前补齐缺失的配置。
5. 根据现有说明和 ../_shared/core/execution-policy.md 中的配置，确定后端、范围和支出。在付费工作或自定义范围的工作开始前，使用 resources/decision-records.md 记录实际获批、受限或被拒绝的操作。已配置后端并不代表获准增加支出；仅在缺少重要选项或需要新的授权时询问。

转换

• 如果 .deepsec/ 不存在，且 intent 涉及扫描 → 运行 bunx deepsec init（或 npx deepsec init），并按照打印出的提示，在任何 AI 扫描前填写 INFO.md。
• 如果 INFO.md 为空或仍为模板内容 → 填写该文件（50-100 行，针对具体项目，每个部分提供 3-5 个示例，不含行号，不枚举通用 CWE）。
• 如果仓库文件超过 500 个，且尚未进行校准 → 先运行校准扫描（deepsec 文档建议使用 --limit 50 --concurrency 5），并在完整扫描前报告成本推算。
• 如果 process / revalidate 运行因配额耗尽而中止 → 保留文件锁，显示确切的补救 URL，并在充值后重新运行同一命令。
• 如果 Agent 报告拒绝（refused: true）→ 绝不能默默忽略；记录受影响的文件，并使用另一个后端重试，或仅在问题可复现时将路径添加到 config.json:ignorePaths。
• 如果用户需要 CI 门禁 → 使用双作业模式（PR 代码作业没有 pull-requests: write 权限，评论作业不运行任何 PR 代码）。
• 如果用户希望扩大匹配器覆盖范围 → 针对 data/<id>/files/ 和父仓库的入口点运行匹配器编写工作流。

失败与恢复

失败	恢复方法
Missing AI credentials for --agent claude / codex	根据 resources/config.md 检查所选模式：密钥/OIDC/直连模式需要配置环境，订阅模式需要通过 CLI 登录。有效的订阅会话无需 .env.local 凭据。
网关返回 401 Unauthorized	OIDC：重新运行 vercel env pull（有效期为 12 h）。API 密钥：重新生成。确认 .env.local 位于 deepsec 运行时所在的当前工作目录中。
Stopped: AI Gateway credits exhausted	通过显示的 URL 充值；重新运行同一命令，已处理的文件会跳过。
Stopped: Claude Pro/Max subscription exhausted	切换到 AI Gateway；订阅无法支持完整扫描。
单个文件持续拒绝处理（占批次的 >5%）	将路径添加到 data/<id>/config.json:ignorePaths，或使用 --batch-size 1 单独运行该文件。
HIGH+ 的 FP 比率过高	运行 revalidate --min-severity HIGH；收紧 INFO.md 中的威胁模型和 FP 说明；优先使用 precise 匹配器。
noisy 匹配器导致扫描器在包含 100k 个文件的仓库中卡住	收紧 filePatterns，使用锚定于语言或目录的 glob。
沙箱身份验证失败	OIDC：重新运行 vercel env pull。访问令牌模式：验证 VERCEL_TOKEN + VERCEL_TEAM_ID + VERCEL_PROJECT_ID。
完整扫描超出既有范围或支出授权	报告校准后的估算值，并保留已完成的免费/有限工作。仅解决缺失的授权；执行前记录实际获批、受限或被拒绝的扫描。

退出

• 成功：已运行计划中的扫描；发现项均有判定（或未产生发现项）；列出已写入的文件；明确说明剩余成本和后续工作。
• 部分成功：部分扫描因凭据/配额/拒绝处理而受阻；报告阻碍、安全恢复命令和建议的下一步。
• 失败：未发生任何破坏性操作；用户已获得解除阻碍所需的确切下一条命令。

逻辑操作

工具与手段

• 包管理器：bun / bunx（首选）、pnpm、npm、yarn 可互换使用。
• CLI 命令：deepsec init、init-project、scan、process、process --diff、triage、revalidate、enrich、report、export、metrics、status、sandbox <cmd>。
• PR 模式的差异来源：--diff <ref|range>、--diff-staged、--diff-working、--files <csv>、--files-from <path>（或用 - 表示 stdin）。
• 检查：使用 jq 查询 data/<id>/files/**/*.json，进行临时的严重性/TP 查询。
• 凭据：AI_GATEWAY_API_KEY、VERCEL_OIDC_TOKEN、ANTHROPIC_AUTH_TOKEN / ANTHROPIC_BASE_URL、OPENAI_API_KEY / OPENAI_BASE_URL、claude login、codex login。
• resources/ 下的资源文件用于设置、扫描、PR 审查、匹配器、分诊、配置；按需加载。

标准工作流路径

1. 初始化（每个仓库仅需一次）：

   cd <target-repo>
   bunx deepsec init
   cd .deepsec
   bun install
   # Edit .env.local: set AI_GATEWAY_API_KEY=vck_… (or VERCEL_OIDC_TOKEN via `vercel env pull`)
   

   然后提示编码 Agent（此技能）阅读 .deepsec/node_modules/deepsec/SKILL.md 和 .deepsec/data/<id>/SETUP.md， 快速浏览 README / AGENTS.md / CLAUDE.md 以及少量有代表性的 文件，并替换 data/<id>/INFO.md 的每个部分（50-100 行， 每个部分提供 3-5 个示例，不含行号，不泛泛重述 CWE）。
2. 全面扫描前先校准。 首先使用 resources/decision-records.md 记录已选定的授权校准范围；--limit 限制的是文件数，而非美元支出。deepsec 文档（getting-started.md、vercel-setup.md、faq.md）建议以 --limit 50 --concurrency 5 作为校准起点。

   bunx deepsec scan
   bunx deepsec status
   bunx deepsec process --limit 50 --concurrency 5
   

   阅读运行成本，并使用 resources/scanning.md 外推至整个仓库。复用已涵盖后端、范围和预计支出的授权。在校准前，以及扩大扫描范围前，分别记录实际范围决策；仅处理缺少的授权。如果用户指定了不同的 --limit / --concurrency 值，则使用用户提供的值。
3. 全面调查、分类、重新验证、导出：

   bunx deepsec process --concurrency 5
   bunx deepsec triage --severity HIGH
   bunx deepsec revalidate --min-severity HIGH
   

   在筛选或抑制结果前，使用 resources/decision-records.md 记录并核实每个已分类发现的实际判定，包括不会展示的发现。然后导出：

   bunx deepsec export --format md-dir --out ./findings
   bunx deepsec metrics
   

4. PR 模式（CI 门禁，仅针对变更文件，退出代码 = 0/1）：

   bunx deepsec process \
     --diff origin/${BASE_REF} \
     --comment-out comment.md
   

   按照 resources/pr-review.md 配置双作业 CI 模式。运行由 PR 控制的代码的作业绝不能获得 pull-requests: write 权限。
5. 自定义匹配器（补上步骤 3 中发现的入口点覆盖缺口）：
   • 阅读 .deepsec/node_modules/deepsec/dist/config.d.ts 中的契约，以及 samples/webapp/matchers/* 示例。
   • 编写 .deepsec/matchers/<slug>.ts，并通过 .deepsec/deepsec.config.ts 中的内联插件接入。
   • 验证命中率：bunx deepsec scan --matchers <slug> 应达到每 1k 个文件 1-20 次命中（precise）、5-100 次（normal），或大致等于框架入口点的数量（noisy）。
6. 恢复：遇到任何配额限制、网络中断或 Ctrl-C 后，重新运行相同的命令。状态保存在 .deepsec/data/<id>/ 下。

资源范围

范围	资源目标
CODEBASE	目标仓库的源文件、框架配置、路由目录、README / AGENTS.md / CLAUDE.md。
LOCAL_FS	.deepsec/deepsec.config.ts、.deepsec/.env.local、.deepsec/matchers/、.deepsec/data/<id>/{project.json,INFO.md,config.json,files/,runs/,reports/}、生成的 findings/、comment.md、CI 工作流文件。
PROCESS	`bunx deepsec scan
NETWORK	通过 Vercel AI Gateway（默认）或直接访问提供商端点使用 Anthropic / OpenAI；可选的 Vercel Sandbox 微型虚拟机控制平面。
CREDENTIALS	AI_GATEWAY_API_KEY、VERCEL_OIDC_TOKEN、ANTHROPIC_AUTH_TOKEN、OPENAI_API_KEY、VERCEL_TOKEN / VERCEL_TEAM_ID / VERCEL_PROJECT_ID、claude / codex 订阅令牌。仅以只读方式使用；绝不向用户回显机密信息或将其提交到仓库。
MEMORY	用户为当前会话指定的预算上限、严重性下限和停止条件。

前置条件

• 已提供 Node.js 22+。
• 仓库是 git 检出版本（deepsec 使用 git 历史执行 revalidate 和 --diff）。
• 对于任何 AI 命令：调用前至少配置一种凭据模式，否则暂缓调用，直到配置完成。
• 对于 sandbox 模式：已配置 Vercel 身份验证；否则使用本地模式。
• 对于无界 process：已测量的文件范围和校准成本必须在现有授权范围内；否则使用获批的有限扫描，或补齐缺失的支出/范围决策。

影响和副作用

• 会在目标仓库中创建 .deepsec/（配置、锁文件、脚手架）和 .deepsec/data/<id>/（已加入 Git 忽略）。

• 会写入 .env.local（切勿提交），并可能运行 vercel link / vercel env pull（写入 .vercel/project.json 和令牌）。

• 会启动长期运行的 AI 进程，会产生实际费用。根据官方费用指南，单次完整扫描的费用从 $25 到 $1,200 以上不等；对于非常大的仓库，费用可能高达数万美元。

• 会读取源代码；并将代码片段发送给配置的大模型（网关 = 零保留；直连提供商 = 遵循该提供商的政策）。绝不会泄露机密；在 sandbox 模式下，网关密钥会保留在工作进程沙箱之外。

• 用户要求设置 CI 门禁时，可能会写入 .github/workflows/deepsec.yml（或类似文件）。

• 编写匹配器时，会编辑 deepsec.config.ts 并添加 .deepsec/matchers/*.ts。

• 除非用户明确授权单独的提交步骤（通过 oma-scm 路由），否则不会提交、推送或创建 PR。

防护措施

1. 切勿在尚未测量大小的仓库上启动无界 process。 文件数量未知或超过 500 时，务必先运行校准扫描（deepsec 文档建议使用 --limit 50 --concurrency 5；如果用户指定了值，则以用户指定值为准）。
2. 在任何 AI 扫描开始前说明费用和停止条件。 使用已公布的费用区间（100 个文件 ≈ $25-60，500 个 ≈ $130-300，2,000 个 ≈ $500-1,200；费用可能有 ×2-3 的波动）。
3. 恢复运行，不要重置。 遇到网络 / 配额 / Ctrl-C 中断后，重新运行相同命令。未经用户明确指示，切勿删除 data/<id>/ 来“重新开始”。
4. INFO.md 应简短且针对具体项目。 控制在 50-100 行，每个部分提供 3-5 个示例。注明基本构造，但不要标注行号。跳过通用 CWE 类别；内置匹配器已覆盖这些类别。
5. 对于 PR/CI 门禁，将受 PR 控制的代码放在只读任务中运行。 切勿向执行受 PR 控制的 pnpm install / 配置加载的任务授予 pull-requests: write 权限。使用 resources/pr-review.md 中的双任务模式。
6. 在生产 CI 中将 Actions 固定到完整 SHA；主版本标签仅用于示例。
7. 切勿悄悄丢弃拒绝结果。 如果 Agent 报告 refused: true，则记录该结果，改用另一个后端重试，或者仅在问题可复现时将该文件添加到 ignorePaths。
8. 当漏洞模式明确时，匹配器应优先采用 precise。 仅在覆盖入口点和使用严格 glob 模式时采用 noisy。
9. 切勿回显或提交凭据（vck_…、sk-ant-…、sk-…、OIDC 令牌）。将 .env.local 视为机密。默认将 data/ 视为已加入 Git 忽略。
10. 将 deepsec 视为可访问 shell 的 Agent。 对容易遭受提示词注入的仓库（包含 vendored 代码、不可信依赖）建议使用 sandbox。
11. 发现结果需要判定。 向用户展示任何 HIGH+ 级别结果时，优先使用带 revalidate 标签的判定（true-positive / false-positive / fixed / uncertain），而不是原始 process 输出。
12. 不要臆造 CLI 标志；以 CLI 为准。 凡是 resources/scanning.md 的标志列表之外的内容，都必须先通过 --help 确认。同样，如果 CLI 打印的模型名称、默认值或每批费用与本技能中的值不一致，以 CLI 为准——上游变化速度快于这些资源。
13. 沿用已有的后端、范围和支出决策。 通过 resources/decision-records.md 记录重要的执行选择和每项发现的判定；如果现有授权已涵盖该操作，则不要再要求确认。

参考资料

• L1 执行范围和每条发现的判定记录：resources/decision-records.md（在进行付费工作／自定义范围工作或筛选已分类的发现之前）。
• 工作区安装与 INFO.md 引导：resources/setup.md
• 完整的扫描／处理／分类／重新验证／导出工作流与成本指南：resources/scanning.md
• 通过 process --diff 设置 PR／CI 门禁（双任务模式、退出代码语义）：resources/pr-review.md
• 编写自定义匹配器（slug、噪声等级、文件 glob、插件接线）：resources/matchers.md
• 阅读发现、严重性、分类／重新验证判定、误报筛选：resources/triage.md
• deepsec.config.ts 参考、环境变量、插件顺序、AI Gateway／Vercel Sandbox 身份验证：resources/config.md
• 上游文档（仅在资源文件指向时加载）：
  • 仓库与 README：https://github.com/vercel-labs/deepsec
  • https://github.com/vercel-labs/deepsec/tree/main/docs 上按主题分类的文档（getting-started、reviewing-changes、writing-matchers、configuration、models、plugins、architecture、data-layout、vercel-setup、supported-tech、faq）
• 共享上下文加载：../_shared/core/context-loading.md
• 共享质量原则：../_shared/core/quality-principles.md