Codex Security CLI 快速开始

Codex Security 帮助安全和工程团队发现、确认并修复漏洞。你可以使用命令行界面（CLI）扫描自己拥有或获准评估的仓库，持续评审安全发现，并在变更落地前检查相关风险。

检查先决条件

CLI 需要 Node.js 22 或更高版本。运行扫描或导出结果还需要 Python 3.10 或更高版本。有关更多详细信息，请参阅认证和先决条件。

设置并验证 CLI

安装公开发布的软件包：

npm install @openai/codex-security

列出可用的命令：

npx @openai/codex-security --help

另请参阅 CLI 参考。

登录

对于本地使用，请使用你的 ChatGPT 账号登录：

npx @openai/codex-security login

在远程或无头计算机上，使用设备认证：

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

对于 CI 和其他自动化工作流，请改用 OpenAI API key：

export OPENAI_API_KEY="<your-api-key>"

有关 AWS 凭据，请参阅 Amazon Bedrock 设置。

如需使用已存储的登录凭据，请传入 --auth chatgpt：

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

要强制使用环境变量中的 API key，请显式选择 API key 认证：

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

根据你的账号和仓库，完整仓库扫描可能还需要 Trusted Access for Cyber。

准备扫描

选择要扫描的仓库和要写入结果的目录。

REPOSITORY=/path/to/repository
SCAN_DIR=/path/outside/repository/codex-security-results

如果省略 --output-dir，Codex Security 会将结果保存在其自己的持久状态目录中。结果可以包括源代码摘录和漏洞详细信息，因此请选择私有位置和适当的保留策略。

如果默认状态目录不可写，请选择扫描仓库之外的可写目录：

export CODEX_SECURITY_STATE_DIR=/path/outside/repository/codex-security-state

在开始扫描之前检查仓库、目标和输出目录：

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --dry-run

试运行会检查本地输入，而无需启动 Codex、加载凭据或探测插件的 Python 解释器。

运行你的第一次扫描

运行标准扫描并将其结果保存在选定的目录中：

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR"

默认情况下，CLI 会将扫描进度和完成摘要写入 stderr，而不会把完整扫描结果写入 stdout。完成的扫描会打印如下摘要：

codex-security: Findings: 2 (1 high, 1 medium). Coverage: complete.
codex-security: Elapsed: 42s.
codex-security: Report: /path/outside/repository/codex-security-results/report.md
codex-security: Results: /path/outside/repository/codex-security-results

如果要把完整结果作为机器可读的 JSON 输出，请显式请求结构化输出：

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --json

默认情况下，扫描只生成报告，结果会留在本地供你评审。准备好在 CI 中运行扫描 后，可以再添加严重性阈值。

选择模型和推理强度

扫描默认使用 gpt-5.6-sol 和 xhigh 推理强度。任务需要其它配置时，可以选择不同的模型和推理强度：

npx @openai/codex-security scan "$REPOSITORY" \
  --model gpt-5.6-terra \
  --effort high

支持的推理强度为 minimal、low、medium、high 和 xhigh。

查看结果

打开 report.md 即可得到可读结果。扫描目录还包含自动化使用的结构化文件：

codex-security-results/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
    └── results.sarif       # when produced

• scan-manifest.json 记录目标、范围、生产者和已封存的产物。
• findings.json 记录每项安全发现的严重性、置信度、位置、证据和补救措施。
• coverage.json 记录已评审范围、排除、延后处理的工作、未解决的问题和覆盖范围的完整性。

覆盖范围可以是 complete、partial 或 unknown。在将扫描视为评审证据之前，请阅读任何延后处理的范围或未解决的问题。 CLI 参考 描述了完整的产物和输出合约。

选择下一次扫描

当仓库包含单独的服务或包时，使用路径扫描：

npx @openai/codex-security scan "$REPOSITORY" --path services/billing --path packages/auth

查看基础修订版和 HEAD 之间已提交的更改：

npx @openai/codex-security scan "$REPOSITORY" --diff origin/main --head HEAD

针对 HEAD 检查已暂存和未暂存的更改：

npx @openai/codex-security scan "$REPOSITORY" --working-tree --base HEAD

差异和工作树扫描期望仓库参数是 Git 工作树根。在开始差异扫描之前获取选定的修订版本。

当仓库或路径需要更广泛的评审时，请使用深度模式：

npx @openai/codex-security scan "$REPOSITORY" --mode deep

深度模式支持仓库和路径目标，不支持 diff 或工作树扫描。

添加架构和安全上下文

提供架构文档、威胁模型或安全策略作为扫描上下文。这有助于 Codex Security 根据系统的实际工作方式评估结果：

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

设置扫描预算

当估计模型成本超过美元限制时，使用 --max-cost 停止扫描：

npx @openai/codex-security scan "$REPOSITORY" --max-cost 5

已在处理的请求可能会超出限制。Codex Security 在扫描停止时保留可用结果。

每次提交前扫描更改

为你的仓库安装 Git 预提交安全检查：

npx @openai/codex-security install-hook

该检查会在每次提交前扫描已暂存和未暂存的更改。它可以阻止高严重性安全发现和扫描错误，且不会替换现有的 pre-commit 脚本。

批量扫描仓库

在发现仓库之前登录 GitHub：

gh auth login

从你的 GitHub 账号或组织中发现并选择仓库：

npx @openai/codex-security bulk-scan

交互流程不会列出已归档仓库和 fork，并会要求你在扫描前确认所选仓库。

要扫描准备好的仓库列表，请提供 CSV 和输出目录：

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4

再次运行同一命令即可恢复现有批量扫描。已经完成且结果产物完整的仓库不会被重复扫描。需要重试临时的仓库检出错误或扫描错误时，请添加 --max-attempts 3。

有关 GitHub 发现、CSV 准备、批量扫描结果和 Docker 设置，请参阅运行批量安全扫描。

在 Docker 中运行批量扫描

如果你的访问权限包含 Codex Security Docker 镜像，请在 Linux Docker 主机上使用提供的加固版 Compose 配置和安全配置文件。主机必须支持创建非特权用户命名空间。准备仓库 CSV，将结果和登录状态保存在持久挂载目录中，并通过环境变量或 secret manager 提供凭据：

docker compose run --rm codex-security \
  bulk-scan /input/repositories.csv \
  --output-dir /output \
  --workers 4

容器会以非交互方式运行批量扫描。如需交互式发现仓库，请在 Docker 外部使用 CLI。对于私有仓库，请通过环境变量或 secret manager 提供 GH_TOKEN 或 GITHUB_TOKEN。登录要求（包括账号和仓库访问权限）同样适用于容器化扫描。

重新访问保存的扫描

列出仓库中保存的扫描：

npx @openai/codex-security scans list "$REPOSITORY"

从结果中复制扫描 ID 以检查其结果和配置：

npx @openai/codex-security scans show SCAN_ID

要把已评审的安全发现标记为误报，请说明为什么该发现不适用：

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The route already checks permissions"

后续扫描会参考这项说明，但仍会重新检查当前代码。

使用原始配置针对当前检出内容重新运行同一扫描：

npx @openai/codex-security scans rerun SCAN_ID

要比较两次扫描，首先匹配具有相同根本原因的结果：

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

然后检查哪些结果是新的、持续存在的、重新打开的、已解决的或未知的：

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

有关批量扫描 CSV 格式、扫描历史过滤器和命令选项，请参阅 CLI 参考。

继续适合你目标的工作流：

• 运行批量安全扫描，发现 GitHub 仓库或扫描固定 revision 的 CSV 清单。
• 阅读 CLI 常见问题解答 了解有关扫描历史记录、误报反馈、覆盖范围和修复验证的答案。
• 在 CI 中运行扫描 以查看 pull requests、保留结果并设置严重性策略。
• 使用 CLI 参考，查看每个 flag、输出格式、产物和退出码。
• 集成 TypeScript SDK 从应用或开发工具运行扫描。