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

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 は固定された各リビジョンをチェックアウトし、選択された対象をスキャンして結果を記録した後、一時的なリポジトリのチェックアウトを削除します。リポジトリは、スキャンのマニフェストのステータスが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 には、リポジトリの 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 はキャンペーンを再開し、再試行の対象となる未完了のリポジトリで新しい試行を開始します。カバレッジが不足しているものも含め、完了済みのスキャンはスキップします。それらの結果は引き続き利用できます。

既存の出力ディレクトリでは、リポジトリインベントリやスキャン指示、フォローアップ指示を変更しないでください。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を参照してください。