运行批量安全扫描#

Codex 中文站说明： 本页围绕“运行批量安全扫描”重新补充了中文使用场景和验证重点。界面名称可能随 Codex 版本更新，请以当前客户端为准。

从 GitHub 发现仓库，或使用 CSV 清单运行可恢复的安全扫描。

使用 npx @openai/codex-security bulk-scan 评审同一批次中的多个仓库。你可以从个人 GitHub 账号或组织发现仓库，也可以提供 CSV，将每个仓库固定到精确的 Git revision。

@openai/codex-security 软件包已公开发布。运行扫描仍需获得 Codex Security 访问权限。请按照 CLI 快速入门安装 CLI 并登录。

选择仓库源#

这两个工作流都会保存进度、保留每个仓库的结果，并让你在中断后恢复扫描活动。

发现 GitHub 仓库#

使用 GitHub CLI 登录：

gh auth login

启动交互式批量扫描：

npx @openai/codex-security bulk-scan

CLI 指导你完成以下步骤：

1. 选择你的个人 GitHub 账号或组织。
2. 查看过去 90 天内活动的仓库。
3. 搜索仓库列表并选择要扫描的仓库。
4. 选择扫描结果的目录。
5. 查看选定的仓库并确认扫描批次。

发现不包括已归档仓库和 fork。CLI 记录 /repositories.csv 中每个选定仓库的确切默认分支提交。在你确认选择之前，不会开始扫描。

要使用 GitHub Enterprise Server，请首先登录你的 GitHub 主机：

gh auth login --hostname github.example.com

启动仓库发现时设置 GH_HOST：

GH_HOST=github.example.com npx @openai/codex-security bulk-scan

交互式发现需要终端。对于 CI、容器或准备好的仓库列表，请改用 CSV 清单。

创建仓库 CSV#

创建一个 CSV，其中每个仓库和固定修订包含一行：

id,repository,revision,scope,mode,prompt
payments,https://github.com/example/payments.git,0123456789abcdef0123456789abcdef01234567,services/api,standard,Review payment authorization and refunds.
identity,https://github.com/example/identity.git,fedcba9876543210fedcba9876543210fedcba98,,deep,Review session and identity boundaries.

CSV 支持这些列：

要查找本地仓库的完整提交 SHA，请运行：

git -C /path/to/repository rev-parse HEAD

从 CSV 运行批量扫描#

传递 CSV 和仓库外部的私有输出目录：

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

--workers 控制并发仓库扫描，默认值为 4。它不会 设置每次深度扫描中的发现工作进程数量；请通过 [[deep_scan]](/docs/security/cli/reference#configure-deep-scans) 配置这些限制。 使用 --mode deep 可为没有自行指定 mode 的行选择深度扫描。 每个 CSV 行仍可自行选择扫描模式和仓库范围。

CLI 会检出每个固定 revision、扫描选定目标、记录结果，并删除临时的仓库检出目录。只有当扫描覆盖完整且所有必要结果产物均存在时，仓库才会被视为完成。

共享安全上下文和说明#

使用 --knowledge-base 向每次扫描添加架构文档、威胁模型或安全策略。 如需添加更多文件或目录，请重复使用此标志：

npx @openai/codex-security bulk-scan repositories.csv \
--output-dir /path/outside/repositories/security-scans \
--knowledge-base /path/to/architecture.md \
--knowledge-base /path/to/security-policies

如需添加共享扫描指令，或在每次扫描后执行后续操作， 请提供提示文件：

npx @openai/codex-security bulk-scan repositories.csv \
--output-dir /path/outside/repositories/security-scans \
--scan-prompt-file scan-instructions.md \
--post-scan-prompt-file follow-up.md

CLI 会将每个仓库 CSV 中的 prompt 追加到共享扫描指令之后。后续指令会在同一个已认证 session 中运行，适用于成功完成的扫描，也适用于覆盖范围不完整或出错的扫描；扫描被取消或达到成本上限后不会运行。提示文件路径从当前目录开始解析。

选择模型和推理强度#

批量扫描默认使用 gpt-5.6-sol 和 xhigh 推理强度。要为 CSV 批次选择其它模型和推理强度：

npx @openai/codex-security bulk-scan repositories.csv \
--output-dir /path/outside/repositories/security-scans \
--workers 4 \
--model gpt-5.6-terra \
--effort high

交互式仓库发现也支持相同选项：

npx @openai/codex-security bulk-scan --model gpt-5.6-terra --effort high

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

如需使用 OpenRouter 或 Fireworks，请分别设置 OPENROUTER_API_KEY 或 FIREWORKS_API_KEY， 并指定 --provider 和 --model。有关凭据和示例，请参阅 OpenRouter 或 Fireworks 设置或 Amazon Bedrock 设置。

查看批量扫描结果#

输出目录包含固定的扫描批次、仅附加结果台账以及每个仓库和尝试的单独产物：

security-scans/
├── manifest.json
├── results.jsonl
├── checkouts/
└── artifacts/
├── payments/
│   └── attempt-1/
│       ├── scan-manifest.json
│       ├── findings.json
│       ├── coverage.json
│       └── report.md
└── identity/
└── attempt-1/
├── scan-manifest.json
├── findings.json
├── coverage.json
└── report.md

• manifest.json 记录活动中的仓库、固定修订版本、范围、扫描 模式以及共享或仓库专属指令。
• results.jsonl 记录每次仓库扫描尝试、其状态、工件 目录以及所有可用的成本或错误详情。
• report.md 为一次仓库扫描尝试提供可读报告。
• findings.json 和 coverage.json 记录该次尝试的发现项和 已审查范围。

当你需要可移植结果时，导出一份扫描完成的仓库扫描：

npx @openai/codex-security export \
/path/outside/repositories/security-scans/artifacts/payments/attempt-1 \
--export-format sarif \
--output /path/outside/repositories/payments.sarif

结果可以包含源代码摘录和漏洞详细信息。将输出目录保持私有，位于扫描仓库之外，并遵守适当的保留策略。

恢复批量扫描#

使用相同的 CSV 和输出目录运行原始命令：

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

CLI 会恢复未完成的仓库扫描，并跳过已完成的扫描。覆盖范围 不完整的扫描不会重试。其结果仍然可用，并且 命令会以代码 2 退出。

请勿更改现有输出目录对应的仓库清单、扫描指令或后续指令。 CLI 会检查固定清单，并拒绝不同的扫描活动。更改仓库、 修订版本、范围、扫描模式或者共享或仓库专属指令时， 请使用新的输出目录。

重试仓库错误#

使用 --max-attempts 在临时签出或扫描错误后重试仓库：

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

默认情况下，每个仓库只尝试一次。每次尝试都有各自的 回执和工件目录。重试涵盖检出错误、扫描失败 以及缺少必需工件的情况。覆盖范围不完整的已完成扫描 不会重试。

批量扫描使用这些退出码：

在 Docker 中运行批量扫描#

Codex Security 仓库 包含一个强化的 Compose 配置，用于 Linux Docker 主机上的自动化 CSV 批量扫描。主机必须支持非特权用户命名空间创建。

将仓库 CSV、扫描结果和登录状态挂载到持久目录。通过环境变量或 secret manager 提供 OpenAI 凭据。对于私有 GitHub 仓库，以相同方式提供 GH_TOKEN 或 GITHUB_TOKEN。

使用已安装的 CSV 和输出目录运行映像：

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

使用相同的安装 CSV 和输出目录来恢复扫描活动。对于 GitHub Enterprise Server，将 CODEX_SECURITY_GIT_HOST 设置为你的 GitHub 主机。

要查看所有可用 flag，请参阅批量扫描命令参考。有关扫描覆盖范围和结果的常见问题，请参阅 CLI 常见问题解答。

本站实践建议#

应用“运行批量安全扫描”中的安全设置时，应从最小权限开始，再根据实际任务逐步开放。涉及网络、密钥、生产环境或删除操作时，仍应保留人工确认。

Codex API 与国内使用#

在实践“运行批量安全扫描”相关功能时，如需为 Codex 配置 OpenAI-compatible API，可以前往 APIBest 获取 API Key。第三方服务的模型映射、价格、额度和数据处理方式以 APIBest 当前说明为准。