教程2026-11-15 · 智涌AI

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

Codex Security CLI 教程头图:左侧大字「Codex Security CLI 上手」与 0.10.0 版本、13,571 GitHub 星数、193,660 npm 周下载数据卡;右侧终端依次演示安装 @openai/codex-security、按目录带预算扫描生成报告、对高危发现出补丁以及 PR 改动扫描在高危时返回退出码 1

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 导出

前置条件

第一步:安装并登录

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 找到结果目录,重点看三个文件:

文档专门提醒,扫描「完成」只代表流程跑完,不代表每个文件、每类漏洞都看过了。重要目录被排除了,就针对它再跑一次 --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 的任务要保持失败。

常见坑

做到哪一步算完成

编程 Agent 本身的权限和密钥也要管,可以接着看 Claude Code 权限自查:清理含密钥的 allow 规则;Codex 的沙箱和审批配置见 Codex CLI 的 config.toml 审批与沙箱配置;要测 Agent 自己的行为安全,见 用 Inspect 给你的 Agent 做第一套安全评测。

最后

挑一个你最担心的目录,今天就跑一次 cs scan . --path 那个目录 --max-cost 2,看它找到了什么、花了多少。

关注公众号「智涌AI速递」

每天的 AI 快讯、实用教程和 AI项目实测,也会同步发到微信公众号。在微信里搜索「智涌AI速递」就能关注;不用微信的话,可以用 RSS 订阅本站。