セキュリティスキャンを一括実行する

npx @openai/codex-security bulk-scan を使用すると、複数のリポジトリを 1 つの キャンペーンでレビューできます。個人の GitHub アカウントまたは Organization から リポジトリを検出するか、各リポジトリを正確な Git リビジョンに固定する CSV を指定します。

リポジトリソースを選択する

どちらのワークフローでも進行状況が保存され、リポジトリごとの結果が保持されるため、 中断後にキャンペーンを再開できます。

GitHub リポジトリを検出する

GitHub CLI でサインインします。

gh auth login

対話型の一括スキャンを開始します。

npx @openai/codex-security bulk-scan

CLI の案内に従って、次の手順を実行します。

1. 個人の GitHub アカウントまたは Organization を選択します。
2. 過去 90 日以内にアクティブだったリポジトリを確認します。
3. リポジトリ一覧を検索し、スキャンするリポジトリを選択します。
4. スキャン結果を保存するディレクトリを選択します。
5. 選択したリポジトリを確認し、キャンペーンを確定します。

検出対象からは、アーカイブ済みのリポジトリとフォークが除外されます。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 を作成する

リポジトリごとに、固定されたリビジョンを含む行を 1 行作成します。

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 です。これは、 各ディープスキャン内で独立して実行される標準スキャンワーカーの数を設定するものではありません。 これらの上限は、 [deep_scan] で設定してください。独自の mode が指定されていない行にディープスキャンを選択するには、--mode deep を使用します。各 CSV 行では、 引き続き独自のスキャンモードとリポジトリスコープを選択できます。

キャンペーン内の各ディープスキャンについて、ワーカーの実行を制限するには [deep_scan].max_time_hours を設定します。 --max-time-hours フラグは scan と組み合わせて使用し、bulk-scan とは組み合わせません。

CLI は、固定された各リビジョンをチェックアウトし、選択した対象をスキャンして結果を記録した後、 一時的なリポジトリのチェックアウトを削除します。スキャン範囲が完全で、必要な結果アーティファクトが すべて存在する場合にのみ、リポジトリは完了として扱われます。

セキュリティコンテキストと指示を共有する

--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 には、リポジトリの 1 回の試行について読みやすいレポートが出力されます。
• findings.json と coverage.json には、その試行での検出結果と レビュー済みのスコープが記録されます。

持ち運び可能な結果が必要な場合は、完了したリポジトリスキャンを 1 件エクスポートします。

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 は固定されたマニフェストを確認し、異なるキャンペーンを拒否します。 リポジトリ、リビジョン、スコープ、スキャンモード、共有指示、またはリポジトリ固有の指示を変更する場合は、 新しい出力ディレクトリを使用してください。

リポジトリのエラーを再試行する

一時的なチェックアウトエラーまたはスキャンエラーの後にリポジトリを再試行するには、--max-attempts を使用します。

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

デフォルトでは、リポジトリごとに 1 回試行します。各試行には、それぞれ専用の レシートとアーティファクトディレクトリが割り当てられます。再試行の対象には、チェックアウトエラー、スキャン失敗、 必要なアーティファクトの不足が含まれます。スキャン範囲が不完全な完了済みスキャンは 再試行されません。

一括スキャンでは、次の終了コードが使用されます。

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 ホストを設定します。

使用可能なすべてのフラグについては、bulk-scan コマンドの リファレンスを参照してください。スキャン範囲と検出結果に関するよくある質問については、CLI FAQを参照してください。