运行批量安全扫描

使用 npx @openai/codex-security bulk-scan 在一次扫描活动中检查多个 仓库。从你的个人 GitHub 账户或组织中发现仓库， 或者提供一个将每个仓库固定到确切 Git 修订版本的 CSV。

选择仓库来源

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

发现 GitHub 仓库

使用 GitHub CLI 登录：

gh auth login

启动交互式批量扫描：

npx @openai/codex-security bulk-scan

CLI 会引导你完成以下步骤：

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

仓库发现功能会排除已归档的仓库和 fork。CLI 会将每个所选仓库 默认分支的确切 提交 记录在 <output-directory>/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。它不 设置每次深度扫描中独立标准扫描 worker 的数量； 请通过 [deep_scan]配置这些限制。对于没有自己的 mode 的行，请使用 --mode deep 选择深度扫描。每个 CSV 行 仍可选择自己的扫描模式和仓库范围。

设置 [deep_scan].max_time_hours 可限制扫描活动中每次深度扫描的 worker 执行时间。 --max-time-hours 标志适用于 scan，不适用于 bulk-scan。

CLI 会检出每个固定的修订版本，扫描选定目标，记录 结果，然后移除临时仓库检出目录。当仓库的扫描在清单中的 状态为 completed，且必需的结果产物有效时，该仓库才算 完成。覆盖缺口不会导致扫描失败。

共享安全上下文和指令

使用 --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 追加到共享扫描 指令之后。扫描成功或出错后，后续指令会在同一个已通过身份验证的会话中 运行，但扫描取消或 达到费用上限后不会运行。提示词文件路径 相对于当前目录解析。

选择模型和推理强度

批量扫描默认使用 gpt-5.6-sol 模型和 xhigh 推理强度。要 为 CSV 扫描计划选择其他模型和推理强度，请使用你的凭据 有权访问的模型。如果你使用 ChatGPT 登录，请在使用此示例前查看 GPT-6.1 Sol 可用性：

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4 \
  --model gpt-6.1-sol \
  --effort medium

相同选项也适用于交互式仓库发现：

npx @openai/codex-security bulk-scan --model gpt-6.1-sol --effort medium

可用的推理强度级别取决于所选模型。批量扫描支持 minimal、low、medium、high、xhigh 和 max；GPT-6.1 Sol 至少 需要 low。

要使用 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 会恢复批量扫描任务，为符合条件的未完成 仓库启动新的尝试，并跳过已完成的扫描，包括存在覆盖缺口的扫描。 这些扫描的结果仍可使用。

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

重试仓库错误

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

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、扫描结果和登录状态挂载到持久化 目录。通过环境或密钥 管理器提供 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 主机。

有关所有可用标志，请参阅批量扫描命令 参考。有关扫描覆盖范围和发现问题的常见 疑问，请参阅 CLI 常见问题。