Codex Security CLI 开源审计指南
了解 Codex Security CLI 如何扫描代码仓库、验证发现、导出 SARIF 报告，以及如何融入本地检查、CI 门禁和安全审计工作流。
OpenAI 表示，这款工具在 30 天内扫描了 1.2 百万次 commit，发现 792 个严重问题、10,561 个高危问题，并推动了 14 个 CVE 的产生。 这让我明白 Codex Security CLI 的定位：尽早发现严重的代码和配置问题，无论是在我的终端中还是 CI 里。
简要来说：
- 我可以用它进行完整代码仓库审计或仅检查 diff 的 PR 审查
- 它会检查密钥、注入 bug、SSRF、路径遍历、错误配置、不安全依赖项等问题
- 它不只是进行模式匹配，还会构建威胁模型、在沙箱中测试发现，并建议小型补丁
- 它支持 JSON、CSV 和 SARIF 输出，可用于流水线和报告
- 它需要 Node.js 22+、Python 3.10+、GitHub 访问权限，以及适当的 ChatGPT 工作区访问权限
- 在 CI 中，它使用简单的退出码，例如通过时为
0，发现问题时为51 - 团队可以在本地检查、pre-commit hook、PR 审查流程和批量扫描中运行它
换句话说，这是一款面向希望获得高信噪比安全审查的团队的 CLI，让他们无需等到后期审查或生产阶段。它仍然需要人工分类，但能缩短我必须手动检查的项目列表。
快速比较
| 方面 | 功能 | 我的使用场景 |
|---|---|---|
| 完整审计 | 扫描整个代码仓库和 commit 历史 | 首次扫描、定期深度检查 |
| Diff 审查 | 只扫描已更改的代码 | Pull request、分支审查 |
| 本地 hook | 在 commit 或 push 前检查 | 日常开发工作 |
| CI 门禁 | 发现问题时让构建失败 | 执行团队策略 |
| 批量扫描 | 扫描多个代码仓库 | 组织级审查 |
最让我关注的是，它把代码审查、威胁建模、沙箱验证和可直接导出的输出结合在一个命令行工作流中。
核心能力：CLI 会扫描、标记和导出什么
代码仓库扫描与基于 diff 的审查
Codex Security CLI 支持两种扫描模式：完整审计和基于 diff 的审查。
完整代码仓库审计会检查整个代码库及 commit 历史，以绘制入口点、信任边界、敏感数据和高风险路径 [3]。当你首次把新项目接入工具，或执行定期深度扫描时，这种模式最合适 [3]。
基于 diff 的审查只检查一组特定改动，因此运行速度远快于完整审计 [3][4]。它很适合 Pull request 更新和其他小规模代码改动 [3][4]。
| 扫描模式 | 范围 | 速度 | 最适合用于 |
|---|---|---|---|
| 完整代码仓库审计 | 整个代码库和 commit 历史 | 较慢；随代码仓库大小变化 | 初次接入、定期深度扫描 |
| 基于 Diff 的审查 | 特定 commit 或 PR 改动集 | 快得多 | 发现新代码中的回归问题 |
命令 codex-security scan 可从代码仓库路径或 GitHub URL 运行完整审计。它会返回威胁模型、已确认发现和建议补丁 [3]。
对于 Pull request 工作，codex-security review 接收分支名称或 commit SHA，并返回对新引入代码的集中风险分析 [3]。
简单来说：
- 使用完整审计进行初次接入和深度扫描
- 使用 diff 审查检查新添加的代码
这些扫描会直接产生下一部分介绍的发现。
CLI 可以发现的风险类型
CLI 会跟踪贯穿代码库的真实攻击路径，然后在报告前于隔离沙箱中确认发现 [3][7]。
这意味着它可以发现硬编码密钥、SQL 注入、LDAP 注入、服务器端请求伪造（SSRF）、路径遍历、租户隔离失效和缓冲区溢出等问题 [7]。它还可以标记配置错误，例如没有强制执行 ExpectedBucketOwner 的不安全 S3 设置 [2]。
早期测试数据可以反映其规模。在前 30 天的研究测试中，该工具扫描了 1.2 百万次 commit，发现 792 个严重问题和 10,561 个高危问题，并在包括 OpenSSH、PHP 和 Chromium 在内的主要开源项目中推动了 14 个 CVE 的产生 [7][1]。
发现、严重性标签和导出格式
CLI 识别风险后，会以便于审查和传入报告工作流的方式组织它们。
每项发现都会获得一个严重性标签：严重、高、中或低。该分数基于真实漏洞利用发生的可能性及其影响 [3]。发现还包含严重性、沙箱日志、概念验证证据，以及一个针对根本原因的最小补丁 [3][7]。
为了用于报告和流水线，发现可以导出为 JSON 和 CSV [6]。输出还支持 SARIF，便于 CI 系统和仪表板摄取数据 [3][4]。
| 发现类别 | 可能的严重性 | 典型修复方式 | 验证方法 |
|---|---|---|---|
| 硬编码密钥 | 严重 | 轮换凭据；将密钥移至环境变量 | 对 450+ 种凭据模式进行确定性模式匹配 [2][4] |
| 注入（SQL/LDAP） | 高 | 清理输入；参数化查询 | 在沙箱中复现漏洞利用 [7][3] |
| 身份认证失效 | 严重 | 轮换会话；强制执行 MFA | 攻击路径分析和信任边界映射 [7][3] |
| 不安全的 S3 配置 | 高 | 向 API 调用添加 ExpectedBucketOwner | 通过 SonarQube 插件进行 Agentic Analysis [2] |
| 缓冲区溢出 | 严重 | 边界检查；更安全的内存函数 | 在沙箱中复现漏洞利用 [7][3] |
团队还可以编辑威胁模型，使其符合实际部署假设并与项目约定保持一致 [3][4]。
接下来：安装、登录和首次扫描。
设置和环境支持：安装、登录与要求
系统要求与访问权限
Codex Security CLI 需要 ChatGPT Pro、Enterprise、Business 或 Edu 访问权限。管理员还需要在 Workspace Settings 中启用 Codex Cloud 和 Codex Security 权限 [1][3]。
在本地使用时，CLI 需要 Node.js 22+ 和 Python 3.10+ [2]。它还需要直接访问 GitHub，以便审查代码仓库和 commit 历史 [3]。
如果要使用 MCP server 或特定安全插件，需要 Docker、Podman 或 Nerdctl 等容器运行时 [2]。CLI 可跨多个平台工作，但某些 shim 和备用认证方法依赖 Linux [8]。
安装 CLI 并运行首次扫描
访问权限、语言运行时和容器支持准备就绪后，安装 CLI，并先在一个小型代码仓库上进行测试。首次扫描应从非生产代码仓库开始 [3]。
这次小规模测试让团队可以在转向更繁忙的代码库前检查输出、发现设置问题，并熟悉工作流。
身份认证
安装后，登录一次并在本地存储 token。运行 codex-security login 来认证 CLI。之后，token 会保存在系统钥匙串中 [2]。
如果使用 SonarQube 流程，可能还需要运行 sonar auth login [2]。
如果 MCP 启动失败，首先检查容器运行时是否已启动并正常运行。然后重新启动会话 [2]。
团队使用方式：本地检查、CI 门禁和审计工作流
Codex Security CLI 设置并登录后，团队通常在三个位置使用它：本地编辑、pre-commit 检查和 CI 门禁。
本地开发和 pre-commit 扫描
一种常见模式是在开发人员仍在编写代码、尚未 commit 任何内容时运行扫描。PostToolUse hook 可以在每次编辑后触发 Agentic Analysis，让 Agent 有机会在开发者看到输出之前发现并修复安全问题 [2][4]。这意味着问题能被尽早阻止，而不会不断累积到以后。
如果团队希望获得更严格的控制，可以把相同的检查移入 hook 和流水线步骤。install-hook 命令将扫描器连接到 pre-commit 和 pre-push 工作流，因此当 commit 或 push 中包含密钥或脆弱依赖项时，它们会被阻止。此外还有一个 UserPromptSubmit hook，可以阻止包含 450+ 种密钥模式的提示词，其中包括 GitHub personal access token [2][6]。
CI/CD 安全门禁和批量扫描
在 CI/CD 中，CLI 提供适合自动化的退出码：成功时为 0，发现密钥、漏洞或依赖风险时为 51 [6]。这样流水线规则就很简单：0 时通过，51 时失败。
如果只想关注最可能造成损害的问题，团队还可以使用 --severities CRITICAL,HIGH 缩小扫描范围。
对于需要处理大量代码仓库的组织，bulk-scan 可以在一次运行中检查多个代码库。它还能通过保存的扫描历史，长期跟踪安全态势 [7]。
常见代码审计场景
根据扫描运行的位置，相同的发现可以支持截然不同的工作流。
| 环境 | 调用方式 | 生成的工件 | 团队收益 |
|---|---|---|---|
| 本地开发 | 交互式 CLI 会话 / PostToolUse hook | 内联发现、建议补丁 | 即时反馈；在问题写入磁盘前进行修复 |
| Pre-commit hook | install-hook / pre-commit 或 pre-push | 拒绝消息、被阻止的 commit 尝试 | 防止凭据泄露和明显 bug 进入代码仓库历史 |
| CI/CD 流水线 | bulk-scan / 非交互式 CLI | JSON/CSV/Table 报告、通过/失败状态、扫描历史 | 大规模执行安全标准并跟踪长期态势 |
| Agent 驱动的审计 | Agentic Analysis / 沙箱验证 | 可编辑威胁模型、已验证 PoC、上下文感知补丁 | 通过高可信度验证进行深层架构分析 |
当团队将 CLI 输出传回 AI Agent 时，--format toon 标志有助于减少 token 使用量。它生成一种类似 YAML 的编码，在保留完整发现细节的同时使用更少的 token [6]。
安全采用与结论：限制、最佳实践和关键要点
运行工具时的安全卫生
将 Codex Security CLI 接入本地或 CI 工作流前，首先检查它的运行时攻击面和执行设置。如果即将扫描一个不熟悉的代码仓库，请先暂停片刻，检查 .codex/config.toml、.codex/hooks.json 和 .env。这些文件控制注册了哪些 MCP server 以及启用了哪些 hook，因此预先检查它们是标准的安全实践[2]。
定期更新 CLI 并保持最新也很有帮助[6]。如果处理敏感代码库，请使用该工具的隔离容器执行功能。这样，分析会在代码的临时沙箱副本上运行，而不是你的在线工作环境中[9]。
数据处理和工作流边界
这些防护措施有助于让扫描专注于你确实打算分析的代码和权限。同样重要的是，Codex Security CLI 是一个高信噪比发现工具，并不负责对风险作出最终裁决。它可以呈现发现和补丁，但仍然需要人来分类问题、轮换泄露的凭据，并判断特定风险是否可以接受[5][7]。
这种分工很重要。工具帮助你更快发现问题，而人工审查确保判断权回归人类。
本指南的最后要点
Codex Security CLI 可以发现代码文件和用户提示词中的硬编码密钥、依赖风险，以及 SSRF 和路径遍历等更复杂的漏洞类型[2][6][7]。它的 Agent 方法将架构分析与沙箱验证相结合，有助于区分真实问题与嘈杂或推测性的发现[1][5][7]。
Codex Security CLI 的突出之处，是它在一个易于融入工作流的 CLI 中结合了上下文分析、可编辑威胁模型和经过人工审查的安全输出。
常见问题
谁应该使用 Codex Security CLI？
Codex Security CLI 面向需要通过发现、检查和修复漏洞来保护代码库的开发者、安全工程师和团队。
它很适合在大型代码仓库或复杂配置中工作的团队、处理漏洞分类的开源维护者，以及所有希望直接在终端工作流中获得更清晰、更低噪声安全发现的人。
完整审计与 diff 审查有什么区别？
Diff 审查是对工作树中改动的集中检查，通常在 commit 代码前进行。它能帮助你在刚完成的编辑中发现 bug、风险模式和边缘情况。
完整审计会更深入地检查整个代码库。它会跟踪攻击路径、为项目构建威胁模型，并在沙箱中测试潜在漏洞。最终会得到可信度更高的发现和更广泛的补丁建议。
运行它之前需要准备什么？
你需要订阅 ChatGPT Pro、Enterprise、Business 或 Edu 计划。
运行 Codex Security CLI 前，请先设置开发环境。激活源语言虚拟环境、启动任何必要的 daemon，并导出所需的环境变量。
如果使用 SonarQube 插件，请确保已安装并运行 Docker、Podman 或 Nerdctl。
去模型市场挑选你想要的模型
在 APIMart 模型市场尝试聊天、图像和视频模型，用统一 API 快速体验模型能力。