執行批次安全掃描

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