Codex Security CLI 快速入门

使用独立的 Codex Security CLI 对本地仓库运行 标准扫描。本快速入门最终会生成一份已保存的报告，供你审查和日后查阅。 要在 Codex 对话中运行扫描，请使用 Codex Security 插件。

检查先决条件

请使用 Node.js 24 或 26，或 22.13.0 及以上的 Node.js 22。 你还需要 Python 3.10 或更高版本。 Python 3.10 还需要 tomli。使用 OpenAI 推理的扫描需要 Codex Security 访问权限。 根据你的账户和仓库情况，全仓库扫描可能还 需要 Trusted Access for Cyber。

CLI 使用你在操作系统中的权限运行，不会暂停以等待 批准。 扫描进程可能继承你的环境，因此请在开始前移除无关的 凭据。请参阅本地扫描 权限。

设置并验证 CLI

使用 npx 运行公开发布的包：

npx @openai/codex-security --version

该命令会输出已安装的包版本。使用 info --json 检查 随包附带的插件版本，或使用 --help 列出命令。包的变更记录 列在 CLI 和 SDK 版本中。

登录

使用你的 ChatGPT 账户登录：

npx @openai/codex-security login

在没有浏览器的机器上，添加 --device-auth 并按照显示的 登录说明操作。在下方的扫描命令中使用 --auth chatgpt，即可选择 该登录方式，即使环境中同时存在 API key。

有关 API key 和其他提供商，请参阅选择扫描 身份验证方式。 对于 Amazon Bedrock，请使用 AWS 凭据和模型 访问权限，而不是 ChatGPT 登录或 OpenAI API key。

准备扫描

将这些路径替换为你的仓库路径，以及位于 其 Git 工作树之外的新结果目录路径：

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

结果可能包含源代码摘录和漏洞详情。请选择私密的 位置。如果省略 --output-dir，CLI 将使用其持久状态目录。

检查目标和输出位置：

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

试运行成功可确认本地输入有效。它不会启动扫描、加载 凭据，也不会检查插件的 Python 解释器，因此不能据此确定 身份验证和运行环境设置能否成功。

运行首次扫描

移除 --dry-run 以启动扫描：

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

交互式终端会显示实时仪表板。非交互式终端会逐行显示 进度。添加 --headless 也可在交互式终端中逐行显示进度。 仪表板和保存的日志可能包含源代码或凭据。分享前请先 检查这些内容。

扫描完成后，stderr 会包含报告路径、发现项数量和 耗时。例如：

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

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

默认情况下，发现项的严重程度不会导致扫描失败。如需 机器可读的 stdout，请添加 --json。要让发现项导致 CI 检查失败，请设置 严重程度策略。

查看结果

从所报告的目录中打开 report.md。确认目标和修订版本， 然后先阅读覆盖范围，再逐一审查发现项。

检查 scan-manifest.json 中的 scan.status，确认扫描已完成。 查看 coverage.json，了解已审查的范围、排除的路径、暂缓的工作 以及待解决的问题。

扫描完成后会以 0 退出，除非发现项达到已配置的严重程度 阈值，此时返回 1。覆盖缺口不会改变退出码，因此 退出码为 0 并不意味着每个文件都已审查。输入、执行、结果完整性 或必需输出方面的故障会返回 2。 CLI 参考介绍了 这些退出码。

对于每个发现项，请检查受影响的代码、攻击者所需的前提条件、验证 证据以及尚存的不确定性。基于源代码的发现项不一定 包含成功的运行时复现。只有在证据足以支持所述问题后， 才应选择修复该发现项。

分享或归档时，请保留完整的扫描目录。其中包含 scan-manifest.json、findings.json 和 coverage.json，以及报告 和支持性产物。完整布局请参阅扫描 产物。

重新查看已保存的扫描

列出该仓库的扫描：

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

从结果中复制扫描 ID：

npx @openai/codex-security scans show SCAN_ID

交互式扫描完成且存在发现项后，CLI 还会提供发现项 浏览器。选择修复方案前，请先在其中审查证据。对于已保存的发现项， 请使用验证和修补 命令。

选择下一次扫描

有关身份验证问题、重复扫描的差异或误报 反馈，请参阅 CLI 常见问题。