核心问题: 一次限额试跑产出的发现是否对得起模型开销，`revalidate` 之后的误报率是否低到可以直接行动？
RepoDaily 采用评分
RepoDaily 将该项目的采用分评为 91/100（强）：分数来自文章来源、安装路径、生产风险、差异化、许可证清晰度以及 AI/Agent 适配度。
包含 6 个来源、覆盖 4 类来源；如有 RepoDaily 独有模块，会进一步提高证据分。
检测到 6 个工作流步骤、5 个下一步动作，以及 5 个命令/安装信号。
趋势热度为 +783 stars；如内容中有 release、issue 或维护信号，会提高维护可信度。
采纳风险标记为 medium，并包含 6 条安全说明与 5 条跳过条件。
3 个机会视角、5 个替代方案，以及 2 个类型化模块支撑差异化判断。
文章中包含许可证来源或许可证表述。
文章正文和元数据中检测到 5 个 AI/Agent 相关信号。
项目概览
deepsec 是 Vercel Labs 出品、跑在你自己基础设施里的 agent 驱动漏洞扫描器。项目用 TypeScript 编写、采用 Apache-2.0 许可，目标非常具体：对现存大型代码库做按需的全量安全审查，专挑那些在应用里潜伏已久的隐蔽问题。本期趋势它以 783 颗星排在第 6 位；在你的仓库里留下的全部痕迹只有一个 `.deepsec/` 目录，状态、配置和发现结果都放在里面。
设计上把工作拆成一便宜一贵两个阶段：本地快速模式扫描完全免费，产出候选文件；`process` 阶段再把候选交给 AI 审查，默认用最强模型、最高思考档位，可通过 `--thinking-level` 调节。初始化只问两件事——选哪个模型（附 DeepSecBench 基准分数和相对最便宜选项的成本），以及怎么付费：默认走 Vercel AI Gateway，也可以用自己的 OpenAI 或 Anthropic key，甚至用本机已登录的 claude/codex CLI（`--model-auth local`），完全不配置任何凭据。
README 对钱的表述罕见地直白：大型代码库的一次扫描可能花掉数千甚至上万美元，官方说法是客户认为值得，因为那些原本无人修复的漏洞被迅速补上了。每个失控风险都有对应控制：`npx deepsec init --max-cost-usd 100 --max-duration 2h` 会在安全点停下，重跑同一条命令即可从断点继续，已分析过的文件直接跳过；大仓库还会把工作并行分发给多台 worker 机器。
内部结构是公开的。CONTRIBUTING.md 写明这是一个四包 monorepo：core 放类型、schema 和插件契约，scanner 是正则 matcher 加扫描引擎，processor 接入 Claude SDK 和 Codex SDK 并负责 enrich、triage、revalidate，deepsec 包则是可发布 CLI，内含 `deepsec/config` 子导出和 `@vercel/sandbox` 执行器；另有针对一个故意带漏洞的 fixture 应用的端到端测试。官方点名最有价值的贡献是新增 matcher 和插件，工具自身的漏洞通过 [email protected] 报告。
为什么现在变热
- 本期 783 颗星、趋势排名第 6，卖点是找出在应用里潜伏已久的隐蔽漏洞
- 一条命令起步：`npx deepsec init` 自己研究代码库、扫描、并启动 AI 审查，全程无人值守
- 少见的成本坦诚——README 开头就写明大型扫描可能花数千到上万美元
- 运行可断点续跑：Ctrl-C、断网、花费上限、模型额度耗尽，重跑同一命令即可继续
- 模型接入灵活：默认 Vercel AI Gateway，可用自己的 OpenAI/Anthropic key，也可用本地 claude/codex 订阅且不配置任何凭据
- Apache-2.0 的 TypeScript monorepo，内部结构公开：matcher、processor 的 SDK 集成、sandbox 执行器
解决什么问题
- 大型长寿代码库里有从没人复查过的漏洞，因为逐行人工审计无法扩展到整个仓库
- 基于规则的 SAST 会用海量候选淹没审查者；deepsec 专门设了 `revalidate` 阶段，因为原始发现必然带误报
- 整库 AI 审查又贵又慢——入门文档说从几分钟到数小时不等——所以必须有成本上限、时长上限和断点续跑
- 把整个代码库送出去审查带来信任问题：代码去哪、存了哪些凭据、往仓库里提交了什么
- 每个组织都有自己的内部风险模式——特定 helper 名、内部包导入——通用扫描器永远不会标记
工作原理
- 在仓库根目录运行 `npx deepsec init`，只问两个问题：用哪个模型（附 DeepSecBench 分数和相对最便宜选项的成本），以及调用费怎么付
- 工具创建 `.deepsec/` 目录——这是它往你仓库里加的唯一东西——先研究代码库找出风险区域，跑免费模式扫描，再对被标记的文件启动 AI 审查
- `process` 阶段以高思考档位运行 AI 审查，可用 `--thinking-level` 调节；大代码库会把工作并行分发给多台 worker 机器
- 运行中断——Ctrl-C、断网、花费上限、模型额度耗尽——之后重跑同一命令，从停止处继续，跳过已分析文件
- `pnpm deepsec revalidate` 复查发现结果，在任何人为行动之前压低误报率
- `pnpm deepsec export --format md-dir --out ./findings` 每条发现写一个 markdown 文件；`pnpm deepsec report` 给出快速概览
命令面：文档里出现的每一个 flag
- `npx deepsec init`——引导式初始化加首次完整运行；可安全重跑，中断后自动续跑
- `npx deepsec init --max-cost-usd 100 --max-duration 2h`——限制花费和时长；时长单位必须是 `ms`、`s`、`m` 或 `h`
- `pnpm deepsec scan`——免费本地模式扫描，无 AI 调用；`pnpm deepsec process`——昂贵的 AI 审查阶段
- `pnpm deepsec status` 和 `pnpm deepsec report`——进度与概览；`pnpm deepsec export --format md-dir --out ./findings`——每条发现一个 markdown 文件
- 模型接入 flag：`--agent codex` 或 `--agent claude`、`--ai-provider openai|anthropic`、`--model-auth direct` 配 `--ai-api-key-env MY_OPENAI_KEY`，或 `--model-auth local` 直接用已登录的 CLI
- `--thinking-level` 调节推理深度，见 README 链接的 models 文档
- matcher 测试：`pnpm deepsec scan --project-id <id> --root <path> --matchers <slug>` 检查新 matcher 的候选数量
- 给 coding agent 的本地文档：`.deepsec/node_modules/deepsec/SKILL.md` 和 `.deepsec/node_modules/deepsec/dist/docs/`，setup 出错时会以绝对路径暴露
架构解读：四包 TypeScript monorepo
- `packages/core`——类型、schema、插件契约和配置加载器
- `packages/scanner`——正则 matcher 加扫描引擎；matcher 是注册在 `matchers/index.ts` 里的 `MatcherPlugin` 导出
- `packages/processor`——通过 Claude SDK 和 Codex SDK 接入 AI agent，外加 enrich、triage、revalidate 阶段
- `packages/deepsec`——可发布包：打包后的 CLI、`deepsec/config` 子导出、`@vercel/sandbox` 执行器
- `e2e/` 针对一个 fixture 项目做端到端测试；`fixtures/vulnerable-app` 存放故意带漏洞的测试数据，排除在 lint 和 knip 之外
- 发布产物由 esbuild 打包到 `packages/deepsec/dist/{cli,config}.mjs`；触及发布面的 PR 还必须通过 `pnpm test:bundle`
- `e2e/pipeline-sandbox.test.ts` 在真实 Vercel Sandbox 上用 stub agent 跑完整流水线——覆盖 bootstrap、worker 启动、文件上传下载、结果合并，不花任何模型 token，由 `DEEPSEC_E2E_LIVE_SANDBOX=1` 门控
成本模型才是真正的接口
deepsec 把价格当成一等公民而不是小字条款。README 警告大型代码库扫描可能达到数千甚至上万美元；因此 init 的模型选择器把每个选项的 DeepSecBench 分数和相对最便宜选项的成本并排展示，`--max-cost-usd` 与 `--max-duration` 会让运行在安全点停下、之后再续。免费 `scan` 阶段同时是计量工具：在花掉一个 token 之前，先看清付费 `process` 阶段要审多少候选。连项目自己的 CI 都在省钱——live-sandbox 端到端测试特意用 stub agent 跑完整流水线，避免消耗模型 token。
付费路由有三条路。默认把模型调用送到 Vercel AI Gateway：需要时登录 Vercel，并创建一个小型专用项目保存凭据，setup 期间不产生任何计费。第二条路是自带 OpenAI 或 Anthropic key（`--model-auth direct`）：deepsec 只保存环境变量名、从不保存 key 本体，值从环境变量或 `.deepsec/.env.local` 读取。第三条 `--model-auth local` 依赖已登录的 claude/codex CLI，完全不配置 API key、gateway token 或任何环境变量。
扩展性：matcher 和插件就是贡献路径
- CONTRIBUTING.md 点名新 matcher 和新插件是最有价值的贡献，并给出专门指南（`docs/writing-matchers.md`、`docs/plugins.md`）
- 新增 matcher：创建导出 `MatcherPlugin` 的 `packages/scanner/src/matchers/<slug>.ts`，在 `matchers/index.ts` 注册，再用 `pnpm deepsec scan --matchers <slug>` 验证候选数量
- 只对单个组织有意义的 matcher——特定 helper 名、内部包导入——应放进插件而不是提交到上游
- `samples/` 提供可复制的起点；`docs/configuration.md` 讲配置，`docs/plugins.md` 是插件编写参考
- build、test、lint、knip 全部通过后 PR 才可合并，让 matcher 和插件贡献的审查成本保持很低
信任边界：许可、披露与数据落点
- Apache-2.0，含明确的专利授权，见 LICENSE 文件
- deepsec 自身的漏洞按 SECURITY.md 报告到 [email protected]，官方承诺调查所有正当报告
- 被扫描仓库里唯一新增的东西是存放状态和发现的 `.deepsec/` 目录
- 直连 API key 模式下，deepsec 只保存环境变量名、从不保存 key 本体，值从环境或 `.deepsec/.env.local` 读取
- 默认的 Vercel AI Gateway 路由会在 setup 时创建一个小型专用凭据项目；文档明确该步骤不产生任何计费
谁适合关注
适合关注
- 存在多年未复查代码的大型存量仓库，目标就是挖出潜伏已久的问题
- 已持有 OpenAI/Anthropic API key、或本机已登录 claude/codex CLI、不想新建厂商账号的组织
- 需要可续跑审计的安全团队——按成本切片，Ctrl-C、断网、额度耗尽都能接着跑
- 有值得写成插件的内部风险模式的代码库，例如 helper 名或内部包导入
- 需要按 diff 做门禁的 CI 场景，`docs/reviewing-changes.md` 记录了 `process --diff` 的用法
可以先跳过
- 小仓库：整库 AI 审查的成本超过它能找到的 bug 的价值
- 源代码不能送往外部模型供应商的环境——harness 自托管，模型不是
- 需要合规级 SAST 报告格式、而不是从 `.deepsec/` 导出 markdown 发现文件的场景
- 承受不起四位数模型开销的预算；免费的 `scan` 阶段本身不跑 AI 审查
- 要求厂商 SLA 的团队——这是 vercel-labs 项目，源包里没有发布说明或 SLA
风险与注意事项
harness 本身是 Apache-2.0、可断点续跑、可限额，但大仓库上的 AI 审查阶段可能产生数千到上万美元账单，单条发现的质量取决于模型选择和 revalidate 之后未量化的误报率。
- README 自己写明大型代码库扫描可能花数千甚至上万美元
- 默认模型路由走 Vercel AI Gateway；直连 key 和本地订阅模式存在但需要显式 flag
- 源包中没有发布说明、changelog 或版本数据，升级行为无法从这些文档验证
- 误报率在包内任何文档里都没有量化；`revalidate` 能降低它但没有公开数字
- 发布面（`deepsec/config`）带有额外合并门禁（`pnpm test:bundle`），说明接口变动在预期之内
- 跑在你自己的基础设施里；状态和发现都留在仓库内的 `.deepsec/` 目录
- 三种凭据模式：Vercel AI Gateway、自带 OpenAI/Anthropic key、或 `--model-auth local` 完全不配置凭据
- 直连 key 时 deepsec 只保存环境变量名；key 本体留在你的环境变量或 `.deepsec/.env.local`
- 专门设置 `revalidate` 阶段，在发现进入修复队列之前压低误报率
- 工具自身漏洞按 SECURITY.md 报告到 [email protected]，所有正当报告都会被调查
- Apache-2.0 授予覆盖内部使用和衍生作品的版权与专利许可
替代方案比较
| 方案 | 适用场景 | 代价 |
|---|---|---|
Semgrep | 多语言快速规则扫描，单仓库运行成本低、零模型开销 | 开源引擎；云平台单独售卖 |
CodeQL | 在 GitHub CI 内做深度语义查询，查询集大且持续维护 | 公开仓库免费；私有仓库属于 GitHub Advanced Security |
Gitleaks | 只做密钥检测——git 历史里的 key 和 token——成本几乎为零 | 开源 |
TruffleHog | 带凭据验证的密钥扫描，覆盖 git 历史 | 开源核心加付费企业版 |
商用 AI 辅助 SAST（Checkmarx、Veracode） | 更看重厂商管理的合规报告和 SLA，而不是模型选择和原始 markdown 发现 | 企业合同 |
这个趋势说明了什么
把内部规则写成私有插件
CONTRIBUTING.md 明确把组织专属 matcher——特定 helper 名、内部包导入——路由到插件而不是上游，因此一个私有插件包就能承载内部风险知识，无需 fork 扫描器。
为一个内部 helper 写一个 matcher，注册进 `matchers/index.ts`，用 `pnpm deepsec scan --matchers <slug>` 测候选数量——完全免费、不调用 AI。
门禁 PR 而不是整库重扫
一次完整基线之后，`docs/reviewing-changes.md` 记录的 `process --diff` 和 CI 门禁让增量审查只针对变更代码，价格远低于整库 `process`。
在埋了已知缺陷的分支上跑 `process --diff`，把 token 成本与整库 `process` 阶段对比。
把大审计拆成限额切片购买
`--max-cost-usd` 和 `--max-duration` 让运行停在安全点并可重跑续接，把一次五位数审计变成一连串小额、逐笔审批的支出。
连续执行 `npx deepsec init --max-cost-usd 100 --max-duration 2h`，并用 `pnpm deepsec export` 记录每个切片导出的发现。
RepoDaily 判断
deepsec 是少见的把价格写在自己脸上的安全工具：免费模式扫描、可限额可续跑的 AI 审查、能在终端里直接读的 markdown 发现。代价是真金白银——大仓库要数千美元——外加一个没有公开发布记录和误报数字的年轻代码库。对一个从未被深度审查过的存量仓库，一次限额的 `npx deepsec init` 是说得过去的第一笔投入；对小项目或代码无法触达外部模型的场景，它不是合适的工具。