Codex Security 怎么用:让 AI 扫仓库、拦 PR 高危漏洞

OpenAI 的 Codex Security 是一个 Apache-2.0 开源的命令行工具加 TypeScript SDK,npm 包名 @openai/codex-security,11 月 12 日发了 0.10.0。截至 11 月 15 日,仓库有 13,571 颗星,npm 包 11 月 8 日到 14 日一周下载 193,660 次。它让 Codex 去读你的代码找漏洞,把每条发现连同源码证据存成报告,还能接着验证、出补丁、复查修复。这篇按官方 README、CLI 参考和 GitHub Action 文档,把本地首次扫描、只扫改动、控制花费、接进 CI 这几步串起来。
它和传统扫描器差在哪
Semgrep、CodeQL 这类工具靠规则匹配,Codex Security 让模型去读代码、追数据流,再把结论落到具体源码位置上。每条发现在 findings.json 里都带 codeEvidence(源码片段)、rootCause 和 attackPath.dataflow。代价是要调模型、要花钱,跑一次也比规则扫描慢。两类工具可以并存:Semgrep、Snyk、Wiz 等扫描器的结果能导进它的本地工作台,和自己的发现放在一起看重复项。
| 对比项 | 规则型扫描器 | Codex Security |
|---|---|---|
| 判断方式 | 规则 / 查询匹配 | 模型读代码,附源码证据 |
| 后续动作 | 以报告为主 | 验证、出补丁、复查修复、开草稿 PR |
| 成本 | 本地算力 | 按模型 token 计费,可设预算上限 |
| CI 输出 | SARIF 常见 | 自动写 SARIF,另有 JSON / CSV 导出 |
前置条件
- Node.js 22.13.0 及以上的 22.x,或 24.x、26.x;另需 Python 3.10+(3.10 还要装
tomli)。 - 一个 ChatGPT 账号,或一个有对应模型权限的 OpenAI API Key。官方也支持 Amazon Bedrock、OpenRouter、Fireworks AI 等提供方。
- 要扫的代码最好是 Git 仓库,
--diff和--working-tree都依赖 Git。
第一步:安装并登录
npm install --global @openai/codex-security
cs login
cs 和 codex-security 是同一个命令,短名和别的工具撞了就用长名。不想全局安装,或者 npm 报 EEXIST,把下文所有 cs 换成 npx @openai/codex-security。
服务器上没有浏览器时,工作区允许的话用 cs login --device-auth;不允许就在本机开 ssh -L 1455:localhost:1455 user@remote-host,再在这个 SSH 会话里执行 cs login,用本机浏览器打开登录链接。CI 里直接设环境变量 OPENAI_API_KEY 或 CODEX_API_KEY,不用保存登录。
第二步:跑第一次扫描
cd your-repo
cs scan . --max-cost 5
交互模式下会出一个全屏进度面板,按 d 看详情。跑完终端会给出 REPORT 路径,打开那份 Markdown 就是报告。之后想再找到它,在同一个仓库里执行 cs scans show。
--max-cost 5 的意思是估算花费超过 5 美元就停下扫描和所有 worker。文档写得很直白:已经发出去的请求会跑完,实际花费可能略超。估算按模型的标准 token 单价算,ChatGPT 订阅额度、折扣都不在里面。交互扫描花到上限的 80% 时,面板会问你要不要提高预算。
第一次扫自家仓库,先带上 --max-cost,再加 --path 只扫最担心的目录,看清一次大概花多少,再决定要不要扫全仓或开深度模式。
第三步:缩小范围
# 只扫指定目录
cs scan . --path src --path tests
# 只扫从 origin/main 到 HEAD 的已提交改动
cs scan . --diff origin/main
# 扫暂存区和未暂存的改动
cs scan . --working-tree
# 深度扫描:多轮标准扫描去重合并
cs scan . --mode deep
深度模式会成批重复跑标准扫描,再按源码位置和漏洞描述合并重复发现,可用 --workers、--stop-after-no-new、--max-time 控制规模。想让扫描懂你的业务,用 --knowledge-base architecture.md 喂架构文档;仓库根目录或组件目录里的 SECURITY.md 会被自动读取,没有的话可以用 cs policy . 起草一份,草稿存在仓库外,你审完再拷进来。
第四步:读报告、验证、出补丁
用 cs scans show SCAN_ID --json 找到结果目录,重点看三个文件:
scan-manifest.json:scan.status是结果,scan.scope列出包含和排除的路径。findings.json:每条发现的位置和证据。report.md:给人看的摘要。
文档专门提醒,扫描「完成」只代表流程跑完,不代表每个文件、每类漏洞都看过了。重要目录被排除了,就针对它再跑一次 --path。
拿到发现之后:
# 对某条发现单独复核(只读代码,不联网,不跑程序)
cs validate findings.json --context "重点看租户隔离"
# 按扫描结果给高危及以上出补丁,附风险评估并开草稿 PR
cs patch --scan SCAN_ID --severity high --assess-patch-risk --create-pr
# 复查已有修复
cs verify-fix --scan SCAN_ID
补丁结果分 verified、no_change、blocked、failed 四种。0.10.0 改进了 blocked 的说明:会写清楚卡在哪、修复是否依赖仓库外的改动、下一步该做什么。--create-pr 依赖已登录的 gh(GitLab 用 glab)。
第五步:接进 GitHub Actions
官方给了两个示例工作流。先把 API Key 存成仓库 Secret CODEX_SECURITY_API_KEY,再到 Releases 里挑一个审过的 action-vX.Y.Z,把发布说明里的完整 distribution commit SHA 填进 uses。每周全仓扫描的核心部分:
- name: Scan the repository
id: security
uses: openai/codex-security@<审过的 commit SHA>
with:
scope: repository
model: gpt-5.6-sol
effort: high
max-cost: "5"
fail-on-severity: none
env:
OPENAI_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}
PR 版把 scope 换成 diff、fail-on-severity 设成 high,有高危或严重发现时检查失败。官方示例只处理同仓库分支发起的 PR,fork 来的 PR 不跑扫描。不用 Action、自己写脚本的话,命令行等价写法和退出码是:
cs scan . --diff origin/main --output-dir "$SCAN_ROOT/results" \
--json --fail-on-severity high > "$SCAN_ROOT/findings.json"
退出码 0 是通过或只报告,1 是触发了严重度门槛,2 是输入或运行出错,130 / 143 是被中断。0 和 1 时再用 cs export 导 SARIF 上传,1 的任务要保持失败。
常见坑
- 扫描被打断。0.10.0 起,状态还是
running的标准扫描可以cs scans resume SCAN_ID从检查点接着跑,用量和预算一并保留;前提是原始 checkout、输出目录和 Codex 会话都还在。已完成、失败、取消的扫描只能cs scans rerun。 - 预算和后续动作冲突。
--validate不能和--max-cost一起用,因为验证的模型调用不计入成本统计;设了预算的扫描也会跳过--patch,要用cs patch --scan SCAN_ID单独出补丁。 - 批量扫多个仓库超支。
--max-cost在批量扫描里按单个仓库算。0.10.0 新增--max-total-cost,让多个仓库或组件共用一个总预算,含重试。 --diff报错。已提交改动的扫描要求干净的完整 checkout,且停在目标 head 上;有本地改动就先提交或 stash。- 以为本地钩子能兜底。
cs install-hook /path/to/repo会装一个 pre-commit 钩子,默认高危拦截提交,但本地钩子装不装全看开发者自己,文档建议把强制检查放在 CI。
做到哪一步算完成
cs scans show能看到一次已完成的扫描,你读过report.md和 manifest 里的排除路径。- 至少一条发现走过
validate或patch,结果是verified或你确认过的结论。 - 仓库里有一个带
max-cost的工作流,PR 扫描在高危时会让检查失败。
编程 Agent 本身的权限和密钥也要管,可以接着看 Claude Code 权限自查:清理含密钥的 allow 规则;Codex 的沙箱和审批配置见 Codex CLI 的 config.toml 审批与沙箱配置;要测 Agent 自己的行为安全,见 用 Inspect 给你的 Agent 做第一套安全评测。
最后
挑一个你最担心的目录,今天就跑一次 cs scan . --path 那个目录 --max-cost 2,看它找到了什么、花了多少。