openai/codex-security · 上手攻略

仓库：openai/codex-security
链接：https://github.com/openai/codex-security
分类：安全审计 / AI 驱动扫描
作者：Tom
更新：2026-07-30

一、是什么

@openai/codex-security 是 OpenAI 官方发布的命令行工具（CLI）和 TypeScript SDK，专注于用大语言模型能力发现、验证并修复代码中的安全漏洞。与传统的规则匹配式 SAST 工具（如 Semgrep、CodeQL）不同，它由 GPT 系列模型驱动，能够理解代码上下文、推理漏洞利用路径，并给出可操作的修复建议。

简单说：Codex Security 是把 AI 安全研究员的能力打包成了 npm 包，让你用一条命令就能对仓库做深度安全审查。

官方文档入口：https://learn.chatgpt.com/docs/security/cli

二、解决什么问题

传统安全扫描工具的痛点：

规则僵硬：基于正则或 AST 模式匹配，容易漏报（规则没覆盖）也容易误报（一堆 low severity 没人看）
上下文盲区：不理解业务逻辑，分不清"故意暴露的 API"和"意外的信息泄露"
修复建议敷衍：只说"这里有问题"，不给具体怎么改
集成复杂：SAST 工具各自一套生态，CI 配置成本高

Codex Security 想用 LLM 的推理能力解决以上问题：能理解代码语义，能推理攻击链，能给出接近人类安全工程师水平的报告。

三、快速安装

系统要求

Node.js：22.13.0 或更高（支持 22.x / 24.x / 26.x 三个分支）
Python：3.10 或更高（扫描和导出结果时需要）
若使用 Python 3.10，需额外安装 tomli：pip install tomli

安装命令

# 全局安装 CLI
npm install -g @openai/codex-security

# 或通过 npx 临时运行（无需全局安装）
npx @openai/codex-security --version   # 验证安装

⚠️ 注意：官方推荐 Node.js 22.13.0+（需是 22.x 发行线）、24.x 或 26.x。使用其他版本（如 20.x、18.x）可能导致兼容性问题，建议通过 nvm 管理 Node 版本。

四、核心用法

4.1 认证登录

方式一：ChatGPT 账号登录（本地交互式）

npx @openai/codex-security login

方式二：设备认证（远程/无头机器）

npx @openai/codex-security login --device-auth

方式三：API Key（CI/自动化场景，推荐）

export OPENAI_API_KEY="sk-..."
# 或
export CODEX_API_KEY="sk-..."

⚠️ 环境变量中的 API Key 会优先于存储的 ChatGPT 登录态使用（交互式扫描例外，会询问）。如需强制用 ChatGPT 登录态，追加 --auth chatgpt。

4.2 基础扫描

# 标准扫描整个仓库
npx @openai/codex-security scan .

# 指定模型和推理强度（effort: minimal/low/medium/high/xhigh）
npx @openai/codex-security scan . --model gpt-5.6-terra --effort high

# 只扫描特定路径
npx @openai/codex-security scan . --path src --path tests

# dry-run（只验证参数，不真正扫描）
npx @openai/codex-security scan . --dry-run

# 限制最大花费（美元）
npx @openai/codex-security scan . --max-cost 5

⚠️ 默认模型：当前文档中写的是 gpt-5.6-sol（xhigh effort），但 README 示例中使用 --model gpt-5.6-terra。实际以 npx @openai/codex-security info --json 输出为准，模型名称和可用版本可能随 API 迭代变化。

4.3 增量扫描（diff / working-tree）

# 扫描已提交变更（对比两个分支/提交）
npx @openai/codex-security scan . --diff origin/main

# 扫描未提交变更（staged + unstaged）
npx @openai/codex-security scan . --working-tree --base HEAD

4.4 深度扫描

npx @openai/codex-security scan . --mode deep

Deep 模式扫描范围更广，支持仓库和路径目标，不支持 diff / working-tree 扫描。

4.5 知识库辅助

传入架构文档、威胁模型、安全策略，让模型更准确地判断什么是漏洞：

npx @openai/codex-security scan . \
  --knowledge-base /path/to/architecture.md \
  --knowledge-base /path/to/security-policies.pdf

4.6 扫描结果对比（增量追踪）

# 列出仓库历史扫描
npx @openai/codex-security scans list /path/to/repo

# 对比两次扫描，自动识别新增/已解决/复现的漏洞
npx @openai/codex-security scans compare BEFORE_SCAN_ID AFTER_SCAN_ID

4.7 验证与修复

# 验证某条 finding 是否真实漏洞
npx @openai/codex-security validate "Possible SQL injection in src/query.ts:42"

# 自动生成修复补丁
npx @openai/codex-security patch "Missing authorization check in src/routes.ts:18"

4.8 导出报告

# SARIF 格式（兼容 GitHub Advanced Security / Azure DevOps / Splunk 等）
npx @openai/codex-security export ./results --export-format sarif --output findings.sarif

# CSV 格式
npx @openai/codex-security export ./results --export-format csv --output findings.csv

# JSON 格式
npx @openai/codex-security export ./results --export-format json --output findings.json

4.9 批量扫描

# 交互式选择 GitHub 仓库扫描（需先 gh auth login）
npx @openai/codex-security bulk-scan

# 从 CSV 读取仓库列表，指定输出目录和并发数
npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir ./security-scans \
  --workers 4

CSV 格式示例：

repository
owner/repo1
owner/repo2

4.10 Git Pre-commit Hook

# 安装后，每次 commit 前自动扫描 staged 文件，高危漏洞会阻止提交
npx @openai/codex-security install-hook

4.11 TypeScript SDK 用法

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

const security = new CodexSecurity();

try {
  const result = await security.run("/path/to/repository", {
    outputDir: "/path/outside/repository/results",
  });

  console.log("报告路径:", result.reportPath);
  console.log("漏洞数:", result.findings.findings.length);
} finally {
  await security.close();
}

SDK 支持的运行选项：

选项	说明
`target`	仓库路径、 committed diff 或 working-tree diff
`mode`	`standard` 或 `deep`
`auth`	`auto` / `chatgpt` / `api-key`
`outputDir`	结果输出目录（建议放在仓库外部）
`archiveExisting`	扫描前归档已有结果
`maxCostUsd`	最高 USD 花费上限
`failureSeverity`	失败严重级别策略
`parentScanId`	关联父扫描
`signal`	`AbortSignal` 取消扫描

五、输出产物

每次扫描完成后，结果目录结构如下：

results/
├── scan-manifest.json    # 扫描元数据（目标、范围、模型版本）
├── findings.json         # 结构化漏洞列表（severity/confidence/locations/remediation）
├── coverage.json         # 扫描覆盖率（complete / partial / unknown）
├── report.md             # 人类可读的安全报告
├── artifacts/
└── exports/
    └── results.sarif     # SARIF 格式（需 export 命令生成）

六、典型适用场景

PR 安全审查：用 --diff 模式在 CI 中扫描变更内容，早于合入发现漏洞
全量仓库审计：新接手项目、收购前尽调，用 deep 模式做全面扫描
第三方依赖审查：结合 --knowledge-base 传入内部安全基线，扫描引入的开源库
安全合规报告：导出 SARIF 对接 GitHub Advanced Security、Azure DevOps 等平台
自动化巡检：对多个仓库用 bulk-scan 定期批量扫描，跟踪漏洞趋势

七、坑与注意

坑	说明	应对
Trusted Access 限制	部分仓库扫描需要账号通过 Trusted Access for Cyber 认证，光有 API Key 不够	确认账号状态，符合条件再扫描
结果目录位置	扫描结果包含源码片段和漏洞详情，不要放在仓库内，防止泄露	用 `--output-dir` 指定仓库外部路径
Python 依赖	扫描和导出依赖 Python 3.10+，Python 3.10 还需额外装 `tomli`	用 `--python` 或 `PYTHON` 指定解释器路径
状态目录不可写	若 `CODEX_SECURITY_STATE_DIR` 不可写，扫描会失败	设置 `CODEX_SECURITY_STATE_DIR` 到可写目录
API Key 优先级	环境变量 `OPENAI_API_KEY` / `CODEX_API_KEY` 优先于存储的 ChatGPT 登录态	CI 中使用 `--auth chatgpt` 强制用登录态，或在本地开发时 unset API key
Node.js 版本要求严	明确要求 22.13.0+（22.x 发行线）/ 24.x / 26.x，其他版本不保证兼容	用 `nvm` 管理 Node 版本
模型名称不稳定	`--model` 参数接受的值可能随 API 迭代变化	先跑 `info --json` 确认可用模型列表
Deep 模式不支持 diff	`--mode deep` 与 `--diff` / `--working-tree` 互斥	根据需求分开跑两次扫描

八、与同类对比

维度	Codex Security	Semgrep	GitHub Advanced Security (CodeQL)
驱动方式	LLM（GPT 系列）推理	规则引擎（YAML 编写）	编译时静态分析（AST 查询）
上下文理解	✅ 能理解业务逻辑	❌ 规则匹配	❌ 规则匹配
误报率	较低（AI 推理）	高（规则死板）	中等
修复建议	✅ 详细，含代码级修复方案	⚠️ 基础	⚠️ 基础
CI 集成	✅ 原生 CLI + SARIF	✅ GitHub Action	✅ 原生集成
无需代码执行	✅ 只读分析	✅	✅
多语言覆盖	依赖 LLM 通用能力，理论通吃	需为每种语言写规则	需为每种语言建数据库
成本	扫描按 API Token 消耗	开源自带	GitHub 付费功能
离线可用	❌ 需要 OpenAI API	✅	⚠️ 部分

一句话总结：Codex Security 适合需要深度语义理解的安全审查，误报少、修复建议质量高，但依赖外部 API（成本+网络可达性）；Semgrep/CodeQL 适合规则可控的标准化扫描，可以完全离线。

九、推荐结论

如果你在找一个能理解代码上下文、误报低、修复建议具体的安全扫描工具，且团队使用 ChatGPT Plus 或有 OpenAI API 用量预算，@openai/codex-security 值得优先试用——尤其适合做增量 PR 扫描和深度代码审计。但注意它目前处于快速迭代期（< 1.0.0），CLI 参数和模型名称可能变化，生产级 CI 集成前建议锁定版本号。