詳細スキャンでは、同じリポジトリまたはフォルダーを対象に、複数の標準スキャンを独立して実行し、検出結果をまとめます。レビューを繰り返したい場合で、実行時間とトークン使用量の増加を許容できるときに使います。
まず標準スキャンを実行し、対象範囲とセキュリティに関するコンテキストが目的に合っていることを確認してください。レビューを繰り返すと、前のスキャンで見逃した問題が見つかることがあります。ただし、すべての問題を検出できる保証はなく、実行するたびに同じ結果が得られるとも限りません。
標準スキャンと詳細スキャンの使い分け
| 標準スキャン | 詳細スキャン | |
|---|---|---|
| レビュー方法 | 標準スキャンを 1 回実行 | 標準スキャンを複数回実行し、検出結果を集約 |
| 用途 | 初回のスキャン、または範囲を指定したレビュー | 同じ範囲に対する追加の独立したレビュー |
| 対象範囲 | リポジトリまたはフォルダー | リポジトリまたはフォルダー |
| 変更箇所のレビュー | 変更レビュー用のワークフローを使用 | 非対応 |
詳細スキャンの開始
スキャンの品質を最大限に高めるには、モデルに gpt-5.6-sol を使用し、推論強度を xhigh に設定します。
- セキュリティ > スキャンを開き、+ スキャンを選択します。
- リポジトリまたはフォルダーを選び、コードベースを選択して詳細スキャンをオンにします。選択したリポジトリまたはフォルダー全体がレビューの対象になります。
- モデルと推論強度を選択します。追加のコンテキストに、脅威モデルやデプロイ環境に関する情報を入力します。
- スキャンを開始を選択します。
Codex との会話からも詳細スキャンを開始できます。
$codex-security:deep-security-scan を使って、このリポジトリを対象に詳細セキュリティスキャンを実行してください。特定のコンポーネントだけを対象にする場合は、プロンプト内の「このリポジトリ」をそのコンポーネントのフォルダーへのパスに置き換えます。
詳細スキャンの各ワーカーは、選択したモデルと推論設定を引き継ぎます。各ワーカーが標準スキャンを一通り実行し、Codex Security が完了したスキャンの結果を集約します。スキャンで保存済みのスキャンの進捗を確認できます。対応する Codex タスクを確認するには、アクティビティを表示を選択します。同時実行数や実行時間を制限したい場合は、開始前に実行時の上限を設定してください。
スキャン結果を確認する前に、詳細スキャンがどの段階まで進んでいるかを確認し、対応する Codex タスクのアクティビティを参照できます。
スキャン結果の確認
最終処理が成功し、report.md が生成された時点でスキャンは完了します。集約が終了したというメッセージや scan-manifest.json ファイルの存在だけでは、完了したとは判断できません。
詳細スキャンでは、標準スキャンと同じように、保存済みのスキャンの詳細とスキャンディレクトリ一式を参照できます。スキャンで完了したスキャンを開くか、検出結果で見つかった問題を確認します。脆弱性の詳細レポートやコードの構造を強化するためのガイダンスの出力を指定した場合、生成された report.md にそれらへのリンクが含まれます。結果を共有またはアーカイブする際は、リンク先の findings/ ディレクトリや hardening/ ディレクトリもレポートと一緒に保存してください。
検出結果を見る前に、レビュー範囲の概要を確認してください。詳細スキャンにも限界があります。結論を出す前に、レビューを見送った箇所や、裏付けがまだ取れていない点を確認します。検出された問題が妥当だと判断したら、検出された問題の修正と検証に進んでください。
pull request、コミット、ブランチ間の変更、ローカルパッチをレビューするには、コード変更のレビューの手順に従います。詳細スキャンでは差分を対象に指定できません。
詳細スキャンの同時実行数と実行時間の設定
詳細スキャンの同時実行数や実行時間を制限するには、~/.codex/codex-security/config.toml を作成または編集します。CODEX_HOME を設定している場合は、代わりに $CODEX_HOME/codex-security/config.toml を使用します。
次の設定例では、同時実行数を抑え、スキャンの実行時間を短くします。
[deep_scan]
workers = 2
subagents = 0
stop_after_no_new = 3
max_discovery_runs = 10
max_time_hours = 1.5| 設定 | デフォルト値 | 説明 |
|---|---|---|
workers |
4 |
独立した標準スキャンを同時に実行できるワーカーの数です。従来の設定値 "auto" も 4 として扱われます。 |
subagents |
3 |
各ワーカーが起動できるサブエージェントの数です。0 に設定すると無効になります。 |
stop_after_no_new |
4 |
新たな問題を検出せずに完了したワーカーのスキャンが、指定した回数だけ連続すると停止します。 |
stop_after_consecutive_errors |
3 |
ワーカーでエラーが指定した回数だけ連続して発生すると停止します。 |
max_discovery_runs |
40 |
結果を集約するまでに実行する独立した標準スキャンの回数に上限を設定します。 |
max_time_hours |
96 |
ワーカーの実行時間の上限を時間単位で指定します。96 以下の正の数を指定でき、小数も使用できます。 |
値を小さくすると、スキャン時間やトークン使用量を減らせる一方で、問題を見逃す可能性があります。設定の変更は新しく開始する詳細スキャンに適用されます。すでに進行中のスキャンには適用されません。
制限時間に達すると、Codex Security は実行中のワーカーを停止し、完了したスキャンの結果を保持して最終レポートにまとめます。どのワーカーも期限までにソースコードのレビューを完了できなかった場合は、レビューが対象範囲の一部にとどまったことがレポートに記録されます。
max_time_hours を使用するには、プラグインのバージョン 0.1.19 以降が必要です。リリースの詳細はプラグインの変更履歴を参照してください。
中断または失敗時の対応
別のスキャンを開始する前に、保存済みのスキャンの状態を確認します。デスクトップアプリでは、スキャンから該当するスキャンを開きます。Codex との会話では、既存のスキャンの状態を確認するよう Codex に依頼します。
- 待機が終了してもスキャンが進行中の場合は、同じスキャンまたは会話に戻り、続行するよう Codex に依頼してください。応答が終了したり、待機がタイムアウトしたりしても、スキャンはキャンセルされません。
- スキャンがエラーで終了した場合やキャンセルされた場合は、エラーの内容と保存済みのスキャンディレクトリを保持してください。保存済みの検出結果と、まだ確認が済んでいない候補は分けて確認します。レビューは対象範囲のすべてに及んでいないため、検出結果の一覧が空でも、コードに脆弱性がないとは判断できません。
サポートを求める際は、スキャンが失敗したときに使用していた Codex CLI またはデスクトップアプリのバージョンと、プラグインのバージョンを伝えてください。あわせて、プロバイダー、モデル、スキャンの状態、正確なエラー内容も記載します。更新後に確認したバージョンは、失敗時のものと異なる場合があります。バージョンと更新の確認を参照してください。