Codex Security:用CLI与SDK扫描、验证并修复代码漏洞
一个给开发团队用的代码漏洞扫描CLI和SDK,能验证发现、生成补丁,区别于只报结果的扫描器。
GitHub openai/codex-security 更新 2026-11-12 分支 main 星标 11.7K 分叉 937
TypeScript Python JavaScript Rust Shell 代码安全 Codex Security CLI TypeScript SDK GitHub Actions CI

🧭 决策指南

适合,如果你

  • 你需要用cs scan检查整个仓库、src路径或origin/main到HEAD的Git变更。
    README的Quick start与Scan options列出cs scan .、--path和--diff origin/main。
  • 你希望扫描结果继续进入补丁生成、修复验证或SECURITY.md策略流程。
    README的Features、Generate SECURITY.md和Use in Codex章节明确支持这些流程。
  • 你要在TypeScript项目中调用安全扫描,而不是只运行命令行。
    README的TypeScript SDK章节给出npm install @openai/codex-security和CodexSecurity.run示例。
  • 你要在GitHub-hosted Ubuntu上按周运行仓库扫描。
    README的GitHub Actions章节提供weekly repository scan示例。

不适合,如果你

  • 你的环境无法满足Node.js 22.13.0+、24.x或26.x以及Python 3.10+要求。
    README的Quick start明确列出Node.js和Python版本要求。
  • 你要求本地浏览器dashboard或serve命令管理扫描结果。
    README的Findings storage and deduplication章节说明local serve命令和browser dashboard已移除。
  • 你的GitHub Action必须在发现安全问题时让CI任务失败。
    README的GitHub Actions章节说明示例报告发现但不失败任务,并将阈值配置放到Action guide。
  • 你的账号无法获得需要Trusted Access for Cyber的受保护发现能力。
    README的Scan options章节说明部分网络安全请求和受保护发现需要Trusted Access for Cyber。

前置条件

  • Node.js 22.13.0+ within 22.x,或Node.js 24.x或26.x。
  • Python 3.10+;Python 3.10还需要tomli。
  • CLI登录需要执行cs login;CI扫描进程需要设置OPENAI_API_KEY或CODEX_API_KEY。
  • GitHub Action示例需要仓库密钥CODEX_SECURITY_API_KEY和GitHub-hosted Ubuntu。
  • TypeScript SDK项目需要安装@openai/codex-security。

第一步命令(README 原文)

npm install --global @openai/codex-security

要注意

  • cs和codex-security是同一CLI,命令冲突时应使用codex-security。
    README的Quick start明确说明两个命令运行同一CLI。
  • npm出现EEXIST时,README要求改用npx @openai/codex-security。
    README的Quick start给出了EEXIST处理方式。
  • Deep scan会重复Standard扫描,且README另有Deep Scan limits说明。
    README的Features和Scan options分别说明重复扫描与限制文档。
  • GitHub Action示例估算每次扫描$5,但进行中的请求可能超过该限制。
    README的GitHub Actions章节直接说明estimated $5 limit和超限可能。
  • 链接Git worktree要保持CODEX_SECURITY_STATE_DIR稳定,才能共享历史和登录范围。
    README的TypeScript SDK章节说明共享scan history和saved findings的条件。

替代方案

  • Codex Security GitHub Action:当扫描需要固定在GitHub Actions的weekly workflow中运行,而不是由开发者手动执行cs scan时。
    GitHub Actions
  • 现有第三方扫描器与Scanner import guides:当团队已有第三方scanner结果,需要在Codex Security中预览、保存或发布支持的报告时。
    Scanner import guides

材料未说明

  • README未说明支持哪些具体编程语言的漏洞检测范围。
  • README未说明扫描调用的实际计费模型、免费额度或Codex Security Cloud价格。
  • README未提供检测准确率、误报率或基准测试数字。
  • README未说明源代码发送、保存和处理的具体数据保留政策。
  • README未说明是否支持完全离线扫描或自托管模型后端。
  • README未说明Codex Security Cloud的账号开放范围和具体可用地区。

💡 深度解析

6
适合 我负责维护根目录和组件级 `SECURITY.md`,还会提供 `architecture.md` 作为上下文;我要求先验证候选漏洞,再生成补丁并验证修复,这个项目能覆盖这条工作流吗?
适合读者: 应用安全工程师,负责审查仓库级与组件级漏洞,使用 `SECURITY.md`、架构文档和威胁模型,并需要验证候选发现后再生成补丁

适合,因为 README 明确把策略上下文、漏洞验证、补丁生成和修复验证串成一条工作流。

  • “Features”列出 validate candidate findings、generate patches 和 verify existing fixes,覆盖你要求的先验证、后修复、再验证。
  • “Quick start”说明扫描会使用根目录和组件级 SECURITY.md 指导范围;cs policy . --path services/api --knowledge-base architecture.md 可为组件生成或修订策略草案。
  • “Use in Codex”要求阅读报告中的 source evidence 和 exclusions,再请求 patch 或验证已有修复,这与证据审查流程一致。
  • 项目还会保存 threat models,并支持 cs export --scan SCAN_ID --artifact threat-model --output threatmodel.md 导出,便于后续评审。

需要注意,README 要求审核生成的策略草案并只复制确认内容;它没有承诺 AI 补丁一定通过测试,也未定义人工审批、回归测试或漏洞确认的合规标准。

  • README「Features」:Validate candidate findings, generate patches, and verify existing fixes
  • README「Quick start」:Scans use existing root and component `SECURITY.md` guidance
  • README「Generate SECURITY.md」:`cs policy . --path services/api --knowledge-base architecture.md`
  • README「Save and export threat models」:`cs export --scan SCAN_ID --artifact threat-model --output threatmodel.md`
cs policy . --path services/api --knowledge-base architecture.md
材料未说明:补丁生成是否支持指定测试命令、代码风格约束或审批门禁;候选漏洞验证的判定标准、证据格式和可审计状态转换;生成的 threat model 是否包含版本控制、访问控制和敏感信息脱敏能力
视情况 我需要为 `services/api` 生成带 `architecture.md` 上下文的 `SECURITY.md`,但不能覆盖既有漏洞报告说明;同时还要单独导出 threat model,这个项目的策略工件流程可靠吗?
适合读者: 需要把生成的 `SECURITY.md` 和威胁模型纳入 TypeScript 安全平台的应用安全负责人,要求保留既有漏洞报告说明并单独导出 threat model

视情况,README 对策略草案和威胁模型的保存边界写得清楚,但它把最终审核和复制责任留给使用者。

  • cs policy . --path services/api --knowledge-base architecture.md 可以针对组件生成或修订策略草案,符合你的组件级上下文要求。
  • README 明确说命令把草案保存到仓库外、保持现有文件不变;需要 review diff and notes、编辑草案,再只复制确认后的 SECURITY.md。
  • 同一章节要求保留现有 vulnerability-reporting instructions,并特别提醒 .github/SECURITY.md 或 docs/SECURITY.md 不会自动提供仓库级扫描指导。
  • 扫描和策略生成会保存 threat model,可用 cs export --scan SCAN_ID --artifact threat-model --output threatmodel.md 单独导出而不启动新分析。

因此流程适合可审计的人工确认链,但不适合期待自动安全合并。README 未说明草案的差异格式、冲突处理、威胁模型版本管理和访问控制。

  • README「Generate SECURITY.md」:`cs policy . --path services/api --knowledge-base architecture.md`
  • README「Generate SECURITY.md」:saves its draft outside the repository and leaves existing files unchanged
  • README「Generate SECURITY.md」:preserve its vulnerability-reporting instructions
  • README「Save and export threat models」:`cs export --scan SCAN_ID --artifact threat-model --output threatmodel.md`
cs policy . --path services/api --knowledge-base architecture.md
材料未说明:策略草案与现有 SECURITY.md 冲突时是否提供结构化合并或冲突报告;threat model 是否具备版本号、来源追踪和跨扫描比较能力;保存到仓库外的策略和威胁模型是否有默认访问控制或加密机制
适合 我正在 Node.js 22.13.0+ 的 TypeScript 项目里集成 Codex Security SDK,要求异步执行扫描、读取 reportPath,并在任务结束时正确释放资源;它适合做这层自动化吗?
适合读者: 在 Node.js 22.13.0+ 的 TypeScript 项目中维护内部安全平台、希望通过 SDK 自动运行仓库扫描并读取报告路径的工程师

适合,因为项目直接提供 TypeScript SDK,并覆盖扫描执行和报告处理。

  • README 的“TypeScript SDK”给出了 CodexSecurity、security.run("/path/to/repository") 和 result.reportPath 的完整示例,能对应你的异步任务和报告消费需求。
  • 同一示例明确在 finally 中调用 await security.close(),说明 SDK 生命周期管理是使用契约的一部分。
  • SDK 指南还包含 deep-scan 配置、验证、严重性分类、负责人建议和结果处理,适合继续封装到内部平台。
  • 项目主体语言是 TypeScript,npm 包名为 @openai/codex-security,并采用 Apache License 2.0,便于内部集成。

但 README 没有说明并发扫描上限、SDK 错误类型、任务取消机制或 reportPath 文件的保留规则,这些会影响平台化封装。

  • README「TypeScript SDK」:`const result = await security.run("/path/to/repository")`
  • README「TypeScript SDK」:`finally { await security.close(); }`
  • 项目数据:main_language 为 TypeScript;license 为 Apache License 2.0
npm install @openai/codex-security
材料未说明:SDK 是否支持并发任务数量限制、取消任务和重试策略;reportPath 指向的文件是否会自动清理,以及报告中源代码证据的保留周期;SDK 抛出的错误类型和认证失败时的可编程错误码
适合 我在 TypeScript 仓库中通过 Codex 关注 authentication 和 authorization,希望扫描结果保存在本地,并能看到 source evidence、exclusions 和 coverage limits;这个本地工作流适合我吗?
适合读者: 使用 Codex 进行认证与授权代码审查的 TypeScript 开发者,希望在本地不连接 Cloud 的情况下查看源代码证据和覆盖限制

适合,因为 Codex 工作流会保存报告和发现,并要求在继续修复前检查源代码证据与覆盖限制;本地扫描也不强制依赖 Cloud。

  • “Use in Codex”给出了聚焦 authentication 和 authorization 的请求示例,并要求返回 saved report、source evidence 和 coverage limits。
  • 扫描完成后会保存 report 和 findings,README 建议从终端显示的 REPORT 路径打开 Markdown 文件,并可用 cs scans show 找回最近完成的扫描。
  • 项目洞察明确支持本地扫描,不依赖 Cloud 连接;同时 README 说明扫描使用仓库和组件级 SECURITY.md 指导。
  • 若使用多个 Git worktree,稳定设置 CODEX_SECURITY_STATE_DIR 可以共享扫描历史、已保存发现和登录范围。

不过,“本地”不等于不经过外部模型服务:项目依赖 OpenAI API 或 Codex 认证能力。README 没说明源代码上传、数据保留、离线模型或报告加密细节。

  • README「Use in Codex」:focusing on authentication and authorization;返回 saved report、source evidence 和 coverage limits
  • README「Quick start」:open the Markdown file at the REPORT path;`cs scans show`
  • README「TypeScript SDK」:Keep `CODEX_SECURITY_STATE_DIR` stable to retain shared history and sign-in scope
  • 项目洞察 user_experience.usage_limitations:本地扫描与 Cloud 连接是可选关系,但依赖 OpenAI API 或 Codex 认证能力
cs scan .
材料未说明:扫描时源代码和漏洞细节是否发送到 OpenAI 服务,以及可用的数据区域和保留策略;是否存在完全离线的 Codex 模型或本地推理模式;本地状态目录中的报告、发现项和认证信息是否默认加密
视情况 我在多个 GitHub 仓库的 CI 中使用 `OPENAI_API_KEY`,每次只想审查 `origin/main` 到 HEAD 的 Git diff,并避免把 Deep Scan 默认放进每次提交;Codex Security 是否适合这个流水线约束?
适合读者: 负责多个 GitHub 仓库 CI 的 DevSecOps 工程师,使用 `OPENAI_API_KEY`,希望优先扫描 `origin/main` 到 HEAD 的变更而不是每次扫描全仓库

视情况,项目支持基于 Git diff 的变更扫描,但 CI 成本、时间和认证边界仍需要你自行控制。

  • README“Scan options”直接提供 cs scan . --diff origin/main,能够把范围限定为基线到 HEAD 的提交变化。
  • README 同时提供 Standard 与 Deep 模式;Deep 会重复 Standard 扫描并去重发现,因此更适合按需运行,而不是无条件放入每次提交。
  • CI 可以在进程环境中设置 OPENAI_API_KEY 或 CODEX_API_KEY,说明无头流水线有明确认证入口。
  • 项目支持 GitHub Action、批量扫描、SARIF/JSON/CSV 导出,但 README 洞察指出 Deep Scan 和批量运行可能带来更高时间与 API 成本。

因此,变更审查路径是匹配的;但 README 没有给出 GitHub Action 的完整权限、失败门槛、并发限制或 diff 对跨仓库依赖的覆盖语义。

  • README「Scan options」:`cs scan . --diff origin/main`
  • README「Quick start」:For CI, set `OPENAI_API_KEY` or `CODEX_API_KEY`
  • README「Features」:支持 GitHub Action、批量扫描以及 SARIF、JSON、CSV 导出
  • 项目洞察 user_experience.usage_limitations:Deep Scan 和批量扫描可能带来更高的时间和 API 成本
cs scan . --diff origin/main
材料未说明:README 未提供 GitHub Action 的完整 YAML、权限要求和推荐的提交 SHA 固定方式;README 未说明 diff 扫描是否会追踪未修改但被修改代码调用的跨仓库或外部组件;CI 中发现达到何种严重性时是否阻断流水线,需要自行配置或确认
适合 我需要审查多个仓库的重复发现,按自己的严重性标准分级,并把结果导出为 SARIF;项目是否比只输出规则命中的扫描器更适合这项工作?
适合读者: 应用安全工程师,管理多个仓库的扫描发现,需要把结果去重、分级并导出为 SARIF 后交给现有 CI 或安全平台

适合,尤其是在你需要管理扫描结果而不只是接收规则命中时;但它仍是安全分析与编排层,不是完整漏洞管理平台。

  • “Features”列出浏览已保存扫描与发现、识别重复项、按自有 rubric 评估严重性,以及根据源码和 Git 历史建议负责人。
  • 项目支持仓库、指定路径和 Git changes 扫描,也支持 bulk scans,适合多仓库或组件审查。
  • “Save and export threat models”明确提到 SARIF 输出;“Features”还列出 JSON、CSV 和 Linear、Jira、GitHub 跟踪连接,便于接入既有流程。
  • 洞察指出项目会保存本地状态、扫描历史和发现项,可在相关 Git worktree 间共享历史。

限制是 README 没有说明跨仓库去重键、严重性 rubric 的完整配置格式、SARIF 对自定义字段的映射,以及多租户权限模型。

  • README「Features」:identify duplicates、assess severity against your own rubric、suggest owners from source and Git history
  • README「Features」:支持 bulk scans、Linear、Jira、GitHub 以及 SARIF、JSON、CSV
  • 项目洞察 solution_analysis.architectural_strengths:本地状态存储、扫描历史和可选云端连接
cs export --scan SCAN_ID --artifact threat-model --output threatmodel.md
材料未说明:README 未说明 findings 导出为 SARIF 时的具体命令参数和字段映射;README 未说明跨仓库或跨组件去重使用哪些稳定标识;README 未说明不同团队或租户之间的发现项权限隔离

✨ 核心亮点

  • CLI支持仓库、路径与Git变更扫描
  • 可验证发现、生成补丁并复核修复
  • TypeScript SDK与GitHub Action可自动化
  • GitHub Action示例每次估算上限为$5

🔧 工程化

  • Codex Security CLI用cs scan扫描仓库、路径或Git差异
  • Deep scan重复Standard扫描并去重结果
  • TypeScript SDK提供run、验证与结果处理接口
  • 支持SARIF、JSON、CSV导出及Linear、Jira、GitHub集成

⚠️ 风险

  • 运行环境要求Node.js 22.13.0+、24.x或26.x
  • Python 3.10环境还需要tomli依赖
  • GitHub Action示例不因发现问题失败任务
  • 受保护发现可能需要Trusted Access for Cyber
  • 本地serve命令和浏览器dashboard已移除

👥 适合谁?

  • 需要在终端扫描TypeScript或Python仓库的开发团队
  • 需要用TypeScript SDK嵌入安全扫描的自动化系统
  • 使用GitHub-hosted Ubuntu运行每周扫描的仓库维护者
  • 需要Linear、Jira或GitHub跟踪安全发现的团队