Codex Security CLI 快速入门

Codex Security 可帮助安全和工程团队发现、确认并修复 漏洞。使用其命令行界面 (CLI) 扫描 您拥有或获准评估的仓库、持续查看发现的问题， 并在更改合入前进行检查。

检查先决条件

CLI 需要 Node.js 22（22.13.0 或更高版本）、24 或 26。扫描、批量扫描、 导出、扫描历史记录和已保存的发现也需要 Python 3.10 或更高版本。 有关更多详细信息，请参阅身份验证和 先决条件。

设置并验证 CLI

使用 npx 运行 CLI 并检查其版本：

npx @openai/codex-security --version

要同时查看包版本及其捆绑插件的版本，请运行：

npx @openai/codex-security info --json

有关包的变更，请参阅 CLI 和 SDK 版本。

列出可用命令：

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 设置。对于 OpenRouter 或 Fireworks，请设置 提供商的 API key，并使用 --provider 和 --model 选择模型。

要在同时设置 API key 时使用 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

试运行会检查本地输入，包括所有 --knowledge-base 路径， 但不会启动 Codex、加载凭据或探测插件的 Python 解释器。

运行首次扫描

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

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

交互式终端会显示实时扫描仪表板。添加 --headless 可改为显示 纯文本进度行。CI 和没有交互式会话的终端 会自动使用纯文本进度。

仪表板还会显示实时会话详细信息。这些信息可能包含源代码 或凭据，因此请在分享前进行检查。

默认情况下，CLI 会将扫描进度及其完成摘要写入 stderr。 它不会将完整扫描结果输出到 stdout。扫描完成后会输出类似以下内容的 摘要：

  REPORT    /path/outside/repository/codex-security-results/report.md

  FINDINGS  2 (2 confirmed this scan; 0 previously found; 1 high, 1 medium)
  COVERAGE  complete
  ELAPSED   42s
  RESULTS   /path/outside/repository/codex-security-results

Token 用量和预估费用会在可用时显示。要以机器可读的 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 和 max。

查看结果

打开 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 参考介绍了 完整的工件和输出约定。

查看并修复发现的问题

完成包含发现问题的交互式扫描后，CLI 会提供发现问题 浏览器。查看证据并选择要修复的问题。您可以在 Codex 桌面应用中找到已保存的任务。

要在不使用浏览器的情况下修复高危和严重问题：

npx @openai/codex-security scan "$REPOSITORY" \
  --patch --patch-severity high --json

添加 --create-pr 可提交已验证的补丁并创建 GitHub pull request。

您还可以修复已保存的发现问题或导入 Linear issue。请参阅 validate 和 patch 参考。

选择下一种扫描

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

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

要控制 worker、子智能体以及扫描何时停止：

npx @openai/codex-security scan "$REPOSITORY" \
  --mode deep \
  --workers 2 \
  --subagents 0 \
  --stop-after-no-new 3 \
  --max-discovery-runs 10 \
  --max-time-hours 1.5

这些选项需要深度模式；该模式支持仓库和路径目标， 不支持差异扫描或工作树扫描。此处，--workers 控制一次扫描中的独立 标准扫描 worker；bulk-scan --workers 控制并发 仓库扫描。--max-time-hours 接受不超过 96 的正数， 包括小数小时。达到限制时，扫描会停止尚未完成的 worker、 保留已完成的扫描结果，并将其汇总到最终报告中。

添加架构和安全上下文

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

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

添加自定义扫描指令

添加指令，使扫描聚焦于您的安全重点。使用 第二个文件提供后续指令：

npx @openai/codex-security scan "$REPOSITORY" \
  --scan-prompt-file /path/to/scan.md \
  --post-scan-prompt-file /path/to/follow-up.md

后续操作会在成功扫描以及覆盖不完整或出现错误的扫描之后， 在同一已验证身份的会话中运行。如果后续操作失败，CLI 会报告警告并保留已完成的扫描。它不会在 扫描取消或达到费用限制后运行。这两个选项也适用于 bulk-scan；CSV 的 prompt 列可添加仓库专属指令。

设置扫描预算

使用 --max-cost 可在扫描的预估模型费用超过以 USD 计的限制时 停止扫描：

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

正在进行的请求完成后可能会略微超过限制。如果深度 扫描在 Codex Security 汇总已完成的 worker 结果后达到限制，CLI 会保存已完成的报告，将其覆盖范围标记为 partial， 并返回退出代码 2。如果扫描无法生成完整报告，任何 可用的部分输出都会保留在磁盘上。

在每次提交前扫描更改

为您的仓库安装 Git pre-commit 安全检查：

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

再次运行相同命令即可恢复现有的批量扫描。Codex Security 会跳过已完成的仓库。要重试临时的 仓库或扫描错误，请添加 --max-attempts 3。

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

在 Docker 中运行批量扫描

如果您的访问权限包含 Codex Security Docker 镜像，请在 Linux Docker 主机上使用随附的 强化 Compose 配置和安全配置文件。 主机必须支持创建非特权用户命名空间。提供仓库 CSV，将结果和登录状态保存在持久化挂载目录中，并 通过环境或密钥管理器提供凭据：

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

容器运行批量扫描时不会显示交互式提示。要以交互方式 发现仓库，请在 Docker 外使用 CLI。对于私有 仓库，请通过环境或 密钥管理器提供 GH_TOKEN 或 GITHUB_TOKEN。登录要求（包括账户和 仓库访问权限）也适用于容器化扫描。

重新查看已保存的扫描

列出仓库已保存的扫描：

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

从结果中复制扫描 ID，以检查其发现的问题和配置：

npx @openai/codex-security scans show SCAN_ID

要检查某次扫描及其 worker 保存的事件：

npx @openai/codex-security scans logs SCAN_ID

保存的日志未经过脱敏，可能包含源代码或凭据。请在 分享前进行检查。

列出仓库各次扫描中仍未解决的发现：

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

如果最新扫描未确认某个较早的发现，该发现仍会保持未解决状态。

要将已查看的发现标记为误报，请说明该发现为何 不适用：

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

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

使用原始配置对当前 checkout 运行相同的扫描：

npx @openai/codex-security scans rerun SCAN_ID

比较两次扫描，以找出新增、持续存在、重新出现、已解决或状态未知的 发现：

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

比较功能会按根本原因自动匹配发现，并复用已保存的 匹配结果。

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

继续选择符合您目标的工作流：

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