运行批量安全扫描

使用 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 会将每个所选仓库 默认分支的确切 commit 记录在 <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 支持以下列：

要查找本地仓库的完整 commit 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 会 checkout 每个固定修订版本、扫描所选目标、记录 结果，然后移除临时仓库 checkout。仅当扫描覆盖完整且所有必需的结果 工件均存在时，该仓库才算完成。

共享安全上下文和指令

使用 --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 扫描活动选择其他模型和强度：

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 会检查固定的 manifest，并拒绝 不同的扫描活动。当您更改仓库、修订版本、范围、扫描模式， 或共享或仓库专属指令时，请使用新的输出目录。

重试仓库错误

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

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

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

批量扫描使用以下退出代码：

在 Docker 中运行批量扫描

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

将仓库 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 常见问题。