运行批量安全扫描

身份非官方简体中文镜像

翻译状态 AI 翻译

来源版本官方未提供

同步日期 2026-07-31

官方原文 learn.chatgpt.com

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

使用 npx @openai/codex-security bulk-scan 在一个活动中审查仓库。从你的个人 GitHub 账号或组织中发现仓库，或提供一个 CSV 将每个仓库固定到精确 Git 修订版本的清单。

该 @openai/codex-security 包是公开的。运行扫描需要 Codex Security 访问权限。按照 CLI 快速入门安装该 CLI 并登录。

选择仓库来源

来源	使用时机
GitHub 发现	从你的个人 GitHub 账号或组织中交互式选择仓库。
CSV 清单	针对精确的仓库修订版本运行可重复的自动化活动。

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

发现 GitHub 仓库

使用 GitHub CLI登录：

gh auth login

启动交互式批量扫描：

npx @openai/codex-security bulk-scan

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

选择你的个人 GitHub 账号或组织。
审查过去 90 天内活跃的仓库。
搜索仓库列表并选择要扫描的仓库。
选择扫描结果目录。
审查所选仓库并确认活动。

发现流程会排除已归档仓库和复刻仓库。该 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
payments,https://github.com/example/payments.git,0123456789abcdef0123456789abcdef01234567,services/api,standard
identity,https://github.com/example/identity.git,fedcba9876543210fedcba9876543210fedcba98,,deep

该 CSV 支持以下列：

列	必需	描述
`id`	是	唯一仓库标识符。使用字母、数字、句点、连字符或下划线。
`repository`	是	HTTPS URL、 SSH URL或本地仓库路径。相对路径从 CSV 目录解析。
`revision`	是	完整的 40 或 64 个字符 Git 提交 SHA。不支持分支名称、标签和缩短的提交哈希。
`scope`	否	要扫描的仓库相对目录。省略该值则扫描整个仓库。
`mode`	否	`standard` 或 `deep`。省略该值则使用命令选择的模式。

要查找本地仓库的完整提交 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。使用 --mode deep 为没有自己的 mode的行选择深度扫描。每个 CSV 行仍可选择自己的扫描模式和仓库范围。

该 CLI 会签出每个固定的修订版本，扫描所选目标，记录结果，并移除临时仓库签出。只有当扫描覆盖范围完整且所有必需的结果制品都存在时，仓库才算完成。

选择模型和推理强度

批量扫描默认使用 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。

审查活动结果

输出目录包含固定的活动、仅追加的结果账本，以及每个仓库和尝试对应的单独制品：

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

重试仓库错误

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

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

默认每个仓库尝试一次。每次尝试都会获得自己的收据和制品目录。

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

退出码	含义
`0`	每个仓库都已成功完成。
`2`	某个仓库无法完成、某次扫描覆盖范围不完整，或命令遇到输入或运行时错误。
`130`	Ctrl-C 中断了活动。
`143`	SIGTERM 终止了活动。

在 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 主机。

有关每个可用标志，请参阅 bulk-scan 命令参考。有关扫描覆盖范围和发现的常见问题，请参阅 CLI FAQ。