執行批次安全掃描

使用 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 常見問題。