事前準備

CLI クイックスタートに沿って、Codex Security のインストールと認証を済ませてください。セキュリティスキャンを実行する権限があることと、自分が所有しているか評価の許可を得ている対象リポジトリに Git でアクセスできることを確認してください。スキャンはローカルの権限で実行され、承認を待たずに進みます。スキャン権限に関するガイドを確認してください。

対象リポジトリ一覧の作成

まずは少数のリポジトリから始めます。以下の内容を repositories.csv として保存し、例示の URL とコミットのプレースホルダーを実際の値に置き換えてください。

id,repository,revision
payments,https://github.com/YOUR-ORG/payments.git,REPLACE_WITH_FULL_COMMIT_SHA
identity,https://github.com/YOUR-ORG/identity.git,REPLACE_WITH_FULL_COMMIT_SHA

各リポジトリに一意の id と省略していないコミット SHA を指定します。ローカルにチェックアウトしたリポジトリの SHA は、次のコマンドで取得できます。

git -C /path/to/repository rev-parse HEAD

各スキャンでは、指定したコミット時点のリポジトリ全体を調べます。この手順では、ブランチ名や短縮ハッシュは使用できず、未コミットの変更はスキャン対象に含まれません。スキャン範囲をフォルダー単位で指定する方法や、リポジトリごとに指示を設定する方法は、CSV のオプションを参照してください。

スキャンの実行

repositories.csv があるディレクトリに移動します。以下のコマンドの出力先パスを、スキャン対象のリポジトリの外にある非公開ディレクトリのパスに置き換えてから実行してください。

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 2 \
  --mode standard \
  --max-attempts 1 \
  --max-cost 5

この設定では、標準モードのスキャンを同時に 2 件ずつ実行し、各リポジトリの試行は 1 回に限ります。--max-cost 5 を指定すると、各試行の推定費用が 5 ドルを超えた時点でその試行を停止します。すでに進行中の処理にかかる費用が見積もりを上回ることがあるため、この金額は厳密な上限ではありません。また、実行全体で共有する予算でもありません。これらの設定値は、実行前に決めてください。

CLI は、security-scans/artifacts/ 配下のリポジトリ別のフォルダーに結果を保存します。結果にはソースコードの抜粋や脆弱性の詳細が含まれる場合があるため、非公開で保管してください。

結果の確認

結果のディレクトリを開き、次の項目を確認します。

1. 対象一覧： manifest.json で対象のリポジトリとコミットを確認します。
2. 実行状況： results.jsonl で各試行のステータスと成果物の保存先を確認します。
3. カバレッジと検出結果： 各試行のフォルダーにある coverage.json で未スキャンの箇所と除外項目を確認し、続いて report.md と findings.json で検出内容とその根拠を確認します。

終了コード 0 は、すべてのリポジトリのスキャンが正常に完了したことを示します。脆弱性が存在しないことを保証するものではありません。終了コード 2 は、スキャン範囲の一部を調べきれなかった場合、スキャンを完了できなかったリポジトリがある場合、または入力エラーや実行時エラーが発生した場合に返されます。スキャン範囲に未確認の箇所がある場合は、検出結果が空でもコードが安全だとは判断できません。

リポジトリごとに、検出事項を調査する、対応すると決めた検出事項を修正する、未スキャンの箇所を追加で確認するなど、次に取る対応を記録します。担当チームに引き継ぐ際は、スキャンしたコミットと判断の根拠を示してください。

中断したスキャンを再開するには、同じ CSV、指示、出力ディレクトリを指定して、同じコマンドをもう一度実行します。CLI は完了済みのスキャンをスキップします。スキャン範囲に未確認の箇所があっても、自動では再試行しません。対象リポジトリの一覧、リビジョン、スキャン範囲、モード、指示のいずれかを変更する場合は、新しい出力ディレクトリを使用してください。復旧手順の詳細は、再開と再試行に関するガイドを参照してください。