Codex Security 是什么怎么用：OpenAI 开源安全扫描 CLI 上手

OpenAI 在 2026 年 7 月把 Codex Security 以开源 CLI + TypeScript SDK 形式放出（npm：@openai/codex-security）。它不是「又一个聊天写代码」，而是面向找漏洞 → 验证 → 修建议的安全扫描工具；新闻站多在转「开源白帽 CLI」，但缺可复制的安装与边界说明——本文补这一块。

Codex Security 和普通 Codex 有什么区别

**Codex（编程 Agent）**负责改代码、跑命令、做功能；Codex Security专注安全审查：扫描你有权评估的仓库，降低误报噪音，并给出可复核的证据与修复方向。

维度	Codex CLI / 插件	Codex Security
主目标	实现功能、重构	发现并验证漏洞
典型入口	对话 / Agent 循环	scan CLI 或 Security 插件工作台
输出	代码 diff	报告路径、发现列表、修复建议
适合场景	日常开发	PR 前自查、安全评审、CI 门禁
权限模型	读写仓库、执行命令	只读分析为主，不直接改生产

两者可以并存：日常开发用 Codex；发版/合规用 Security 扫一遍。权限与配额说明以 官方文档 为准，早期版本可能要求账号开通/可信访问。别把 Security 当成「自动修漏洞的 Agent」——它给证据和方向，合并仍要人审。

环境要求与安装

官方 README 要求大致是：

• Node.js：22.13+（22.x），或 24.x / 26.x
• Python：3.10+（部分验证链路依赖）
• 已获得 Codex Security 访问权限（beta/研究预览阶段常见）
• macOS / Linux 为主；Windows 需自行验证 Node 与 Python 路径

本地交互扫描：

npm install @openai/codex-security
npx @openai/codex-security login
npx @openai/codex-security scan .
# 需要更高推理强度时（模型名以当前文档为准）
npx @openai/codex-security scan . --model gpt-5.6-terra --effort high

国内用户注意：npm 源若慢，可临时切镜像装包，但 @openai/codex-security 仍要走 OpenAI 鉴权端点；login 与 API 调用可能受网络影响。建议本机先 curl -I https://api.openai.com 测连通，再跑 scan。公司代理环境需给 Node 配 HTTPS_PROXY，否则 login 会卡在 OAuth。

登录与 API Key 二选一：交互用 login；CI 设 OPENAI_API_KEY（或文档注明的 CODEX_API_KEY），不要用交互登录。若本机同时存在 ChatGPT 登录与 API Key，非交互环境通常优先 API Key；需要时可显式：

npx @openai/codex-security scan . --auth chatgpt
npx @openai/codex-security scan . --auth api-key

扫描历史会写到 Codex Security 的 state 目录；不可写时设 CODEX_SECURITY_STATE_DIR 指到仓库外可写路径。

扫描范围与常用参数

不必每次全仓扫。monorepo 或前端子包场景，先缩小范围能省时间和 token：

场景	建议命令思路	说明
单包 Node 项目	scan . 或 scan ./packages/api	从包根目录执行
只看本次 PR 改动	先 git diff --name-only main...HEAD 筛目录再扫	减少无关 finding
高危路径优先	扫 src/auth、src/api 等	认证与输入处理优先
需要更深推理	加 --effort high	更慢、更贵，适合发版前

扫描完成后 CLI 会输出 report 路径 和 finding 摘要。打开报告看三件事：严重级别、复现证据（文件+行号或 PoC 描述）、修复建议是否可落地。把「已验证的高危」当合并门槛，「信息级 / 待确认」进 backlog，别一刀切全拦。

TypeScript SDK 怎么嵌进流水线

适合把扫描挂进自有脚本，而不是只靠手工敲 CLI：

import { CodexSecurity } from "@openai/codex-security";

const security = new CodexSecurity();
const result = await security.run(".");
console.log(result.reportPath);
await security.close();

拿到 reportPath 后，再决定是失败退出、上传制品，还是只发评论。比「把整段对话贴进 PR」更适合自动化。脚本里记得 await security.close()，避免 CI 进程挂住。

CI 里怎么用才不踩坑

1. 只扫你有权评估的代码：开源项目、自家私仓；不要拿去扫别人未授权的仓库。
2. 密钥走 Secrets：OPENAI_API_KEY 放 CI Secret，日志里关掉 echo。
3. 范围要小：对变更目录或 monorepo 子包扫，比全仓每次扫更省钱、更快。
4. 人工仍要看高危项：AI 扫描会漏报也会误报；把「验证过的高危」当合并门槛，别把「零 finding」当成绝对安全。
5. 和 SAST/依赖扫描互补：Codex Security 偏上下文理解；Secret 扫描、依赖 CVE、许可证检查仍要保留。

GitHub Actions 最小示例（路径与模型名以文档为准）：

- name: Codex Security scan
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
    CODEX_SECURITY_STATE_DIR: /tmp/codex-security-state
  run: |
    npx @openai/codex-security scan ./src --auth api-key

常见 CI 故障：

现象	可能原因	处理
login required	未设 API Key 却走了交互鉴权	加 --auth api-key 与 Secret
超时	全仓 + high effort	缩小目录或降 effort
state 目录不可写	容器只读文件系统	设 CODEX_SECURITY_STATE_DIR
429 / rate limit	并发 job 过多	限流或串行扫

国内网络与账号访问若受限，先确认官方文档的区域与鉴权要求，再谈接入；别用不明第三方「代扫」把源码交出去。额度吃紧时可对照 CodePass 与官方订阅成本对比 规划 API 用量。

和 Codex Security 插件 / Cloud 的关系

除 CLI/SDK 外，还有面向 Codex 对话的 Security 插件（本地工作台看证据与修复），以及连接 GitHub 仓库的 Cloud 扫描。选型可以记三条：

• 本地快速自查 → CLI scan .
• 在 Codex 聊天里边写边审 → 插件
• 仓库持续监控、出 PR/Advisory 流程 → Cloud（需按官方步骤连 GitHub）

形态	谁适合	局限
CLI / SDK	工程师本地、CI	需自己解析 report
插件	已在用 Codex 对话	依赖 IDE/客户端
Cloud	组织级持续监控	需 GitHub 授权与策略

产品形态还在早期迭代，命令参数与模型名以文档为准；本文以 2026-07 附近开源 README 为准。升级 CLI 后若 finding 数量突变，先查 changelog 是否换了模型或规则集。

读报告时的优先级（别被 finding 数量吓到）

一次扫描可能返回几十条「信息级」提示。建议按下面顺序处理，避免安全评审变成无限 backlog：

优先级	类型示例	动作
P0	已验证 RCE、SQLi、硬编码密钥	阻塞合并，当天修
P1	认证绕过、SSRF 有 PoC	本 sprint 修
P2	可疑模式、缺输入校验	排期 + 人工确认
P3	风格/最佳实践建议	记录，不阻塞

和依赖扫描（npm audit）对照：CVE 是已知库问题；Codex Security 更偏业务逻辑与组合漏洞。两条线并行，别用一条替代另一条。

常见问题

必须买 ChatGPT Plus 才能扫吗？

不完全是。基础交互扫描可走登录；完整能力与 CI 通常需要 API Key。具体套餐以 OpenAI 当前说明为准。团队场景更建议统一 API Key + 用量告警，而不是每人各自 login。

会不会把整个仓库上传到云端？

扫描依赖模型分析，数据流向以 OpenAI 当前隐私与产品策略为准。企业场景应先读官方数据说明，敏感仓优先隔离环境或内部策略允许的路径。含密钥、PII 的分支不要扫；先跑 Secret 扫描再开 Security。

和「合租账号扫漏洞」能混用吗？

不建议。安全扫描本身就涉及代码与密钥边界；合租账号风险见 AI 编程工具封号行为清单。用自己可控的 API Key + 最小权限仓库。扫描日志里也可能带代码片段，别传到公共频道。

参考资料

• openai/codex-security
• Codex Security CLI 文档
• CodePass vs 官方订阅年成本
• AI 编程工具封号高危行为