Codex Security 用 CLI 与 SDK 查漏洞

OpenAI 已将 Codex Security CLI 与 TypeScript SDK 开源，开发者可以通过命令行扫描代码仓库、发现并验证漏洞、跟踪不同运行周期中的安全问题，也能把扫描接入 CI/CD；项目仓库是 openai/codex-security，npm 包名为 @openai/codex-security。

Codex Security 不是另一套传统 SAST，也不是可以完全离线部署的安全模型；它开源的是一层本地编排机制，用 Skills、产物契约和脚本把候选发现、漏洞验证、攻击路径、报告与修复串成可复核流程。实际扫描仍依赖 Codex Security 访问权限及 ChatGPT 登录或 API Key，因此它的输出不能直接等同于安全结论，自动生成的补丁也不能绕过代码审查。

Codex Security 是一套编排层而非离线安全模型

本文分析的版本快照来自 2026 年 7 月 30 日取得的官方仓库，对应 Git 提交 ab3b91c8b1fc0403d7fd6ae35a3a46f7fb2a470f、npm 版本 @openai/[email protected]，开源许可证为 Apache License 2.0。由于项目仍处早期开发阶段，这些信息只能描述当前快照，不能视作稳定接口或长期兼容性承诺。

仓库公开了 CLI、TypeScript SDK、Codex 插件、13 个安全工作流 Skill、MCP 工作台、JSON Schema、报告生成脚本和容器配置。它没有开源底层模型权重，也没有把扫描能力变成一套可以脱离服务环境运行的本地安全引擎。

这一区别直接影响部署预期。传统 SAST 通常依靠语法树、数据流或规则匹配，以确定性和可重复性换取已知模式的稳定覆盖；Codex Security 的 Skills 则更像可执行的安全评审标准作业程序，规定何时启动、读取哪些证据、生成哪些文件，以及满足什么条件后才能结束。它更适合处理跨文件语义、业务意图和攻击路径，但并不天然具备确定性扫描器的覆盖稳定性。

因此，“开源”在这里主要意味着团队可以检查和调整安全工作流，而不是获得一个完全离线、行为固定的安全模型。安装 CLI 只是获得编排入口，扫描仍然需要相应的 Codex Security 访问权限，并通过 ChatGPT 账号或 API Key 完成认证。

SAST 适合稳定覆盖已知代码模式，SCA 负责依赖组件风险，密钥扫描擅长发现凭证形态，人工审计则需要判断业务背景、权限模型和滥用路径；Codex Security 不替代这些工具和人工审计，其补充作用在于把这些结果放进同一套上下文，帮助模型追踪跨文件调用关系并形成候选攻击路径。

它可以减少安全人员手工组织扫描、补充上下文、记录证据和同步状态的工作，但并不替代现有确定性扫描器与专业安全人员的全部工作。只要团队仍把“模型没有报告问题”理解为“代码没有安全问题”，这项工具就可能被放错位置。

13 个 Skills 如何把候选漏洞变成证据链

13 个 Security Skills 共同覆盖一条完整链路，但它们与流程阶段并非简单的一一对应关系。整体流程可以概括为：

威胁建模与范围界定
        ↓
候选漏洞发现
        ↓
漏洞验证
        ↓
攻击路径分析
        ↓
安全报告生成
        ↓
修复处理
        ↓
工单与复核闭环

威胁建模阶段先限定本次审查的代码范围、入口和信任边界，避免扫描在缺乏上下文的情况下漫无边际地寻找可疑代码。候选发现阶段负责阅读实现并形成待验证假设，此时的结果仍然只是线索，不能直接写成“已发现漏洞”。

进入验证阶段后，工具需要为候选补充证据强度、验证过程和处置状态；攻击路径分析则把入口、可控输入、中间调用链和敏感操作连接起来。报告阶段还要单独记录覆盖范围与最终结论，使“检查了哪里”“发现了什么”“哪些区域仍未确认”不会被压缩成一段自然语言摘要。

修复处理与工单闭环是后续独立环节。安全结论、攻击路径、修复建议和工单状态承担不同职责：前者回答是否存在风险，攻击路径解释风险如何到达敏感操作，修复建议给出处置方向，工单状态则记录由谁处理、是否验证通过。把它们混在一个文件里，会让后续复核、责任追踪和回归验证变得困难。

每个 Skill 的内部也有明确分工。通常以 SKILL.md 为入口，辅以参考文档、脚本、模板和 Agent 元数据。SKILL.md 定义触发边界、工作流、Artifact Contract 与 Hard Rules；agents/openai.yaml 主要提供客户端展示名称、短描述和推荐默认 Prompt。

默认 Prompt 不足以构成完整的安全规范。“Validate a security finding”这样的短指令只描述推荐用法，真正约束验证行为的是 Skill 中关于证据强度、处置状态、台账回执以及禁止虚构验证的规则。只看 YAML 里的 Prompt，无法判断一个候选凭什么被提升为已验证漏洞。

验证结果使用四种 Disposition，而不是简单的真或假。资料确认验证 Skill 会记录证据强度、给出四种 Disposition，并要求在验证台账中留下回执，同时禁止把没有复现或证明的候选写成已验证漏洞。 现有公开摘要没有列出四个处置状态的官方枚举名称，因此集成程序不应自行硬编码一组中文标签，而应读取当前仓库的 Schema。

从使用语义看，这些状态用于区分结论强度：证据充分时可以确认漏洞，只有静态迹象但缺少运行条件时仍应保持疑似，无法建立完整调用链时应标记为无法验证，出现有效反证时则可以排除候选。具体状态名称和门禁映射，应以所安装版本的结构化输出为准。

假设一个仓库存在跨文件权限绕过。公开接口在控制器层检查角色，但另一个模块可以写入被下游服务信任的内部标记；只检查控制器文件可能看不出问题，单独检查服务文件又可能把标记当作可信输入。

这类候选进入验证阶段后，需要沿着“外部请求进入控制器”“角色检查”“标记写入”“下游服务读取标记”“敏感数据操作”追踪调用关系。只有入口可达、信任假设成立、越权结果能够被证明时，讨论确认漏洞才有基础；如果缺少运行环境或关键配置，就应保留为待补证候选，而不能把静态推断包装成成功复现。

攻击路径产物随后负责把已经建立的证据组织成可复核链条，例如说明攻击者需要控制哪些输入、满足哪些前置条件，以及最终能够到达什么操作。报告再将候选、验证状态、攻击路径和未覆盖区域分别记录。修复建议不会自动成为结论，工单关闭也不能只依据“补丁已生成”，而应关联修复后的再次验证结果。

这种证据闭环可以减少模型跳步、丢失候选，以及把未知状态直接写成安全问题的做法，但它不能消除误报和漏报，也不能证明代码绝对安全。模型可能误解业务约束，确定性工具可能不理解隐含规则，人工判断同样会受到时间和上下文限制；Codex Security 能改善过程可审计性，但不提供零误差保证。

CLI 与 SDK 接进工程后怎样守住安全边界

本地使用 Codex Security 的基本前提是 Node.js 22 或更高版本、Python 3.10 或更高版本，以及可用的 Codex Security 访问权限。官方文档给出的安装、帮助、登录和扫描命令如下：

npm install @openai/codex-security
npx @openai/codex-security@latest --help
npx codex-security login
npx codex-security scan .

npx codex-security login 用于完成交互式登录，也可以选择 API Key 认证；npx codex-security scan . 则扫描当前目录对应的代码仓库。CLI 还支持查看代码变化、跟踪不同运行周期中的安全问题，以及验证漏洞修复效果，具体子命令和参数应以当前版本的 --help 为准。

上面的 latest 适合快速体验，不适合直接固化企业流水线。本文对应的版本仍是 0.1.4，团队应安装经过验证的精确版本并提交 lockfile，在升级前重新检查命令、报告 Schema 和门禁逻辑，避免工具包更新悄然改变 CI 行为。

CLI 会提供报告路径，供后续归档或交给其他系统使用。扫描历史用于比较不同周期的发现，工作目录保存运行状态，修复验证结果则用来判断问题是否真正关闭。公开资料确认扫描历史会保存在 Codex Security 工作目录；如果默认目录不可写，可以通过 CODEX_SECURITY_STATE_DIR 指定其他可写位置。

例如，本地或 CI 可以使用：

export CODEX_SECURITY_STATE_DIR="$PWD/.codex-security"

这个目录可能包含报告、运行状态和与代码路径有关的信息，应纳入访问控制、留存周期和 CI 制品策略。临时 CI 节点结束后如果目录没有被归档，下次任务可能无法继续使用此前状态，因此“让目录可写”和“让状态跨任务存在”是两个不同问题。

TypeScript SDK 的集成链路可以概括为：由程序启动仓库扫描，等待任务完成，取得结构化报告路径，再由业务程序读取报告并交给缺陷平台、任务系统或发布门禁。现有官方资料能够确认 SDK 可以调用扫描并返回报告路径，但没有给出可以脱离仓库示例确认的统一函数名，因此不宜凭印象编写 API。

实际使用时，可以把 SDK 看成 CLI 之上的程序化入口，而不是另一套扫描引擎。团队自己的 TypeScript 代码需要负责选择仓库和运行参数、处理任务状态、解析报告结构、映射严重级别，以及决定哪些结果阻断发布。SDK 返回报告路径，不等于自动创建高质量工单，更不等于自动完成风险处置。

三种接入方式的职责并不相同：

在 CI/CD 中，非交互环境可以通过 OPENAI_API_KEY 认证。密钥应由 CI 密钥系统注入，而不是写进仓库、命令行参数或构建日志；状态目录也需要显式配置并随任务归档。

export OPENAI_API_KEY="<由 CI 密钥系统注入>"
export CODEX_SECURITY_STATE_DIR="$PWD/.codex-security"
npx codex-security scan .

安全门禁不能只读取自然语言摘要。团队至少应区分三种结果：发现达到阻断标准的已确认漏洞、尚未完成验证的候选，以及工具自身因认证、超时、额度或运行错误导致的失败。这三种结果不应共用一个退出状态。

这是团队的工程建议，而不是官方对退出码的固定承诺。对于持续迭代的项目，还可以利用运行历史区分新增问题与历史遗留问题，但不应简单忽略所有旧发现，否则门禁会随着代码库增长而逐渐失去约束力。

权限边界需要由团队明确配置，不能依赖工具默认值。API Key 应按最小权限、轮换周期和项目范围管理；面向外部贡献者的 Pull Request 是否允许扫描，需要单独评估，因为这类任务可能同时接触不可信代码和带权限的 CI 环境。生产密钥、部署凭据及高敏感制品不应出现在可由外部 PR 触发的任务中。

现有资料可以确认 Codex Security 不是完全离线部署，但仅凭这些资料无法准确断言每次扫描具体传输了哪些代码片段、报告保存多久、数据位于哪个地域，也不能据此宣称代码“绝不出端”。涉及商业机密、监管数据或跨地域团队时，使用者必须核对当时的官方条款、部署说明与企业合规要求，再决定允许扫描哪些仓库。

修复环节同样需要明确责任人。即使工作流能够生成补丁，补丁仍应经过代码所有者审查、测试验证和变更范围检查。模型可能修复了表面症状，却改变业务行为、遗漏兼容路径，或者为了封闭一个入口而引入新的权限问题。合理流程是“发现问题—形成修复—人工审查—回归扫描—关闭工单”，而不是“生成补丁—自动合并”。

项目早期阶段还意味着团队需要为超时、并发、费用和报告留存制定策略。安全扫描不应无限占用 CI 资源，也不能因为成本控制而静默跳过关键仓库。升级版本时，则需要重新验证 CLI 输出、SDK 消费方式和 CI 门禁是否发生变化。

更稳妥的做法是让 Codex Security 负责跨文件语义分析和业务逻辑审查，同时保留 SAST、SCA、密钥扫描与人工审计。门禁阈值不应凭演示效果设定，而应使用真实项目中的历史误报、漏报、修复时长和回归结果进行校准：哪些已确认问题必须阻断，哪些候选适合进入复核队列，哪些工具错误需要重试。 Codex Security 能否改善安全结果，取决于团队是否同时定义了证据标准、权限边界和人工复核责任。