セキュリティスキャンの一括実行

npx @openai/codex-security bulk-scan を使うと、複数のリポジトリを 1 つのキャンペーンでまとめて検査できます。個人の GitHub アカウントや組織からリポジトリを選ぶか、リポジトリごとに Git リビジョンを固定した CSV を指定します。

対象リポジトリの指定方法

どちらの方法でも進捗とリポジトリごとの結果が保存されるため、中断したキャンペーンを再開できます。

GitHub でのリポジトリ検索

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

gh auth login

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

npx @openai/codex-security bulk-scan

CLI の案内に従って、次の手順を進めます。

1. 個人の GitHub アカウントまたは組織を選択します。
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 行ずつ記載した 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 です。各ディープスキャン内で標準スキャンを独立して実行するワーカーの数は、このオプションでは指定できません。その上限は [deep_scan] で設定します。--mode deep を指定すると、mode が空欄の行にディープスキャンが適用されます。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 の利用条件を確認してください。

1
2
3
4
5npx @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

--effort には、使用するモデル、プロバイダー、Codex のバージョンがサポートする値を指定してください。

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
    │       └── report.md
    └── identity/
        └── attempt-1/
            ├── scan-manifest.json
            ├── findings.json
            └── report.md

• manifest.json には、キャンペーンの対象リポジトリ、固定したリビジョン、スキャン範囲、スキャンモード、共通の指示やリポジトリ固有の指示が記録されます。
• results.jsonl には、リポジトリごとの各試行について、ステータスと結果ファイルの保存先ディレクトリが記録されます。費用やエラーの詳細も、取得できた場合は記録されます。
• report.md では、リポジトリに対する 1 回の試行結果を読みやすいレポート形式で確認できます。
• その試行で検出した問題を確認するには findings.json を開きます。設定したスキャン範囲とレビュー対象から除外した項目を確認するには scan-manifest.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を参照してください。