Codex 安全 CLI 快速入门

身份非官方简体中文镜像

翻译状态 AI 翻译

来源版本官方未提供

同步日期 2026-07-31

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

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

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

检查先决条件

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

设置并验证 CLI

安装已发布的包：

npm install @openai/codex-security

检查已安装的版本：

npx @openai/codex-security --version

列出可用命令：

npx @openai/codex-security --help

使用 npx @openai/codex-security scan --help 或 npx @openai/codex-security export --help 查看完整命令帮助。 CLI 参考涵盖每个参数、输出格式和退出码。

将 API 密钥保存在你的 shell 或密钥管理器中。 Codex Security 也可以复用现有的基于文件的 Codex 登录。当同时有已存储的 ChatGPT 登录和环境 API 密钥可用时，带文本输出的交互式扫描会询问使用哪一个。 CI、 JSON 和 JSONL 扫描以及其他无人值守扫描默认使用 API 密钥。

当同时设置了 ChatGPT 密钥时，如需使用你的 API 登录，请显式选择它：

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

如需要求使用环境 API 密钥，请选择 API-key 身份验证：

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

如需将已存储的登录设为自动默认值，请取消设置两个环境 API 密钥：

unset OPENAI_API_KEY CODEX_API_KEY

根据你的账户和代码库，完整代码库扫描可能还需要 Trusted Access for Cyber。登录或设置 API 密钥并不会授予该访问权限。

准备扫描

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

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

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

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

添加架构和安全上下文

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

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

设置扫描预算

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

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

已在进行中的请求可能会在超过限制后完成。 Codex Security 会保留扫描停止时已有的结果。

在每次提交前扫描变更

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

再次运行同一命令可恢复现有批量扫描。已完成且结果工件完整的代码库不会再次扫描。若要重试临时代码库或扫描错误，请添加 --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 match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

然后检查哪些发现项是新增、持续存在、重新打开、已解决或未知：

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

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

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

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