Codex 安全 CLI 快速入门

如需完整文档索引，请参阅 llms.txt。文档页面的 Markdown 版本可通过在页面后追加 .md 来获取 URL。

Codex Security 可帮助安全和工程团队查找、确认并修复漏洞。使用它的命令行界面（CLI）来扫描你拥有或有权评估的代码库，持续审查发现项，并在变更落地前进行检查。

该 @openai/codex-security 包是公开的。运行扫描需要 Codex Security 访问权限。若要在 Codex中进行交互式扫描，请从 Codex Security 插件快速入门开始。对于已连接的 GitHub 代码库，请参阅 Codex Security 云端设置。

检查先决条件

该 CLI 需要 Node.js 22.13.0 或更高版本。运行扫描或导出发现项还需要 Python 3.10 或更高版本。更多详情，请参阅身份验证和先决条件。

设置并验证 CLI

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

npx @openai/codex-security --version

列出可用命令：

npx @openai/codex-security --help

另请参阅 CLI 参考。

准备扫描

选择要扫描的代码库和用于写入结果的目录。

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。完成的扫描会打印类似如下的摘要：

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

可用时会显示 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。

审查结果

打开 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

Diff 和工作树扫描要求代码库参数是 Git 工作树根目录。开始 diff 扫描前，请获取所选修订版本。

当代码库或路径需要更广泛审查时，请使用深度模式：

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

要控制发现工作器、子代理以及扫描停止的时机：

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

这些选项需要深度模式，该模式支持存储库和路径目标，而不支持差异或工作树扫描。这里， --workers 控制发现工作器在一次扫描内； bulk-scan --workers 控制并发存储库扫描。

添加架构和安全上下文

提供架构文档、威胁模型或安全策略作为扫描上下文。这有助于 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

跟进会在同一个已验证身份的会话中运行。这两个选项也适用于配合 bulk-scan使用； CSV prompt 列会添加特定于存储库的说明。

设置扫描预算

使用 --max-cost 在估算模型成本超过中的限制时停止扫描 USD：

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

已在进行中的请求可能会略微超过限制后才完成。如果扫描因成本限制而中止，部分扫描结果仍会保留在磁盘上。

在每次提交前扫描变更

为你的代码库安装 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

容器会在没有交互式提示的情况下运行批量扫描。使用 CLI 在 Docker 外部以交互方式发现存储库。对于私有存储库，请提供 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 compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

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

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

继续使用符合你目标的工作流：

运行批量安全扫描以发现 GitHub 代码库或扫描固定的 CSV 清单。
阅读 CLI FAQ 以获取有关扫描历史、误报反馈、覆盖范围和修复验证的答案。
在 CI 中运行扫描，以审查拉取请求、保留结果并设置严重性策略。
使用 CLI 参考来检查每个标志、输出格式、工件和退出码。
集成 TypeScript SDK 以从应用程序或开发者工具运行扫描。