ターミナルからリポジトリをスキャンし、セキュリティ上の問題を管理する際によくある質問にお答えします。インストールから初回のスキャンまでの手順は、CLI クイックスタートを参照してください。
リポジトリのスキャン
サインイン後もスキャンで API キーが使われる理由
環境変数 OPENAI_API_KEY または CODEX_API_KEY が設定されている場合、対話型ターミナルを使わないスキャンと、JSON または JSONL 形式で出力するスキャンでは、デフォルトで環境変数の API キーを使用します。これは、ChatGPT またはアクセストークンでログイン済みの場合も同様です。テキスト形式で出力する対話型スキャンでは、ChatGPT のサインイン情報も利用できる場合、使用する認証方法を選ぶよう求められます。ドライランでは認証方法の選択を求められることはなく、認証情報も読み込まれません。
保存済みの認証情報でスキャンするには、認証方法を明示的に指定します。
npx @openai/codex-security scan . --auth chatgptOPENAI_API_KEY または CODEX_API_KEY の API キーを必須にするには、次のコマンドを実行します。
npx @openai/codex-security scan . --auth api-key保存済みの認証情報をデフォルトで使用するには、unset OPENAI_API_KEY CODEX_API_KEY を実行します。対応するすべての認証モードについては、CLI リファレンスを参照してください。
中断した一括スキャンの再開方法
一括スキャンは再開できます。元の CSV と出力ディレクトリを指定して、同じ一括スキャンコマンドを実行します。Codex Security はスキャンが完了したリポジトリをスキップします。
リポジトリやスキャンで一時的なエラーが発生した場合に再試行するには、--max-attempts 3 を追加します。
npx @openai/codex-security bulk-scan repositories.csv \
--output-dir /path/outside/repositories/security-scans \
--workers 4 \
--max-attempts 3完了したスキャンの結果は保持されます。未調査の箇所が残っていても、そのスキャンは再試行されません。未調査の箇所があることを理由に、一括スキャンの終了コードが 2 になることはありません。
検出結果とカバレッジ
過去のスキャン結果の確認方法
リポジトリの保存済みスキャンを一覧表示します。
npx @openai/codex-security scans list /path/to/repository一覧に表示されたスキャン ID を使って、そのスキャンの検出結果を確認します。
npx @openai/codex-security scans show SCAN_ID完了したスキャンごとに、レポート、検出結果、マニフェスト、裏付けとなる成果物がまとめて保存されます。ディレクトリ構成の詳細は、スキャンの成果物を参照してください。
保存されたスキャンとワーカーのイベントを確認するには、scans logs SCAN_ID を実行します。これらのログにはマスキング処理が施されていないため、ソースコードや認証情報が含まれることがあります。
CLI がスキャン履歴を保存できない場合の対処方法
Codex Security はスキャン履歴をワークベンチのデータベースに保存します。状態の保存先となるデフォルトのディレクトリに書き込めない場合は、リポジトリの外にある自分専用のディレクトリを指定します。
export CODEX_SECURITY_STATE_DIR=/path/outside/repository/codex-security-state新規の問題と既知の問題の判別方法
リポジトリの全スキャンで検出された問題のうち、まだクローズされていないものを一覧表示します。
npx @openai/codex-security findings list /path/to/repository一覧では、最新のスキャンで確認できた問題と、以前に検出され、まだクローズされていないものの、最新のスキャンでは確認できなかった問題を区別できます。
次のコマンドで 2 回のスキャンの検出結果を比較します。
npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID比較時には、根本原因に基づいて検出結果を自動的に照合し、保存済みの照合結果も再利用します。各問題は「新規」「継続」「再オープン」「未検出」「解決済み」「不明」に分類されます。以前に検出された問題が、後続のスキャンで調べたコードから見つからなかった場合は「未検出」です。修正済みとして明示的にクローズした場合に限り、「解決済み」とみなされます。パスが調査対象から除外された場合や、同じ問題かどうかを判定できない場合は「不明」のままです。
誤検知のフィードバックの仕組み
保存済みのスキャンを開き、該当する検出事例の ID を確認します。
npx @openai/codex-security scans show SCAN_ID検出された問題がこのケースに当てはまらない理由を記録します。
npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
--reason "The framework escapes this input before it reaches the query"以降、同じリポジトリをスキャンするたびに、記録した理由がコンテキストとして渡されます。その場合も、各スキャンは現在のソースコード、セキュリティ対策、脆弱な箇所に到達できるかどうかを独立して確認します。ある検出結果を誤検知として退けても、該当するルール、パス、脆弱性の種類が検出対象から除外されることはありません。
コマンドの詳細は、検出結果のリファレンスを参照してください。
スキャンを繰り返すと検出結果が変わる理由
AI を使ったスキャンでは、設定が同じでも結果が変わることがあります。まず、基準となるスキャンを再実行します。
npx @openai/codex-security scans rerun BASELINE_SCAN_ID再実行には元のスキャン設定が引き継がれ、同じバージョンのプラグインが必要です。インストール済みのプラグインのバージョンが変わっている場合、コマンドは停止します。
基準となるスキャンと新しいスキャンを比較します。
npx @openai/codex-security scans compare BASELINE_SCAN_ID REPEAT_SCAN_ID背景情報の不足が結果のばらつきにつながっている可能性がある場合は、アーキテクチャとセキュリティに関する共通の指針を各スキャンに渡します。照合によって複数のスキャンで検出された問題が同一かどうかを判別できますが、毎回同じ結果が得られるわけではありません。重要な問題が検出結果から消えた場合は、その問題を直接再確認してください。
修正の有効性の確認方法
修正を反映したチェックアウトで、元のスキャンが検出した問題を再確認します。そのチェックアウトから、元のスキャンのレポートと検証する問題を指定して、次のコマンドを実行します。
npx @openai/codex-security validate /path/to/original/findings.json \
"Recheck the SQL injection in src/orders.ts:42 against the current code"脆弱性を悪用できた経路が塞がれ、正規の利用時には引き続き正常に動作することを、検証で得られた証拠から確認します。元の再現手順や回帰テストがある場合は実行してください。検証を実行できない場合は、何を確認できなかったかを結果に記録します。
スキャンの比較では検出結果の変化を確認できますが、問題が検出されなくなったというだけでは、修正が有効だったとは判断できません。
カバレッジが不完全な場合の結果の読み方
scan-manifest.json の scan.status で、スキャンが完了したかどうかを確認します。scan.scope には設定したスキャン範囲が記録されています。scan.review.excludedPaths には、スキャンで調査対象から除外したパスのパターンが列挙されています。古いマニフェストに scan.coverageRef がある場合は、その値が指すファイルを開いてカバレッジの詳細を確認してください。
未調査の箇所が残っていても、完了したスキャンの終了コードは変わりません。終了コード 0 は、すべてのファイルを調査したことを意味しません。以前に問題が検出されたパスを後続のスキャンで調べていない場合、そのスキャンでは問題がなくなったことを確認できません。
自動化と費用
詳細スキャンの制限時間
詳細スキャンの開始時に、ワーカーの制限時間を指定します。
npx @openai/codex-security scan . --mode deep --max-time-hours 1.5デフォルトは 96 時間です。96 以下の正の値を指定でき、小数も使用できます。制限時間に達すると、Codex Security は処理が終わっていないワーカーを停止します。完了した標準スキャンの結果は保持し、最終レポートに集約します。調査済みの箇所と見送った作業はレポートで確認してください。終了コードは制限時間に達したかどうかだけでは決まりません。実行状態と重大度ポリシーによって決まります。
設定を継続して使用する場合や一括スキャンに適用する場合は、max_time_hours を [deep_scan] セクションに指定します。詳しくは、詳細スキャンの設定を参照してください。
スキャン費用の上限
スキャンを開始する前に、見積もり費用の上限を米ドルで指定します。
npx @openai/codex-security scan . --max-cost 5上限は見積もりに基づく目安です。すでに進行中のリクエストが完了すると、実際の費用が上限を超えることがあります。詳細スキャンで Codex Security が処理を終えたワーカーの結果を集約した後に上限に達した場合、CLI は予算に関する警告を添えて、完了したスキャンのレポートを保存できます。この場合の終了コードは 0 ですが、設定した重大度のしきい値以上の問題が検出された場合は 1 です。有効な完了結果を生成できない場合は 2 を返し、その時点で得られた出力を保持します。
GitHub の Pull Request チェックやリポジトリの定期スキャンには、Codex Security GitHub Action を使用します。action-v0.3.0 では、スキャンの完了は、設定した分析によって有効な結果が得られたことを意味します。対象から除外した箇所や見送った調査があっても、重大度ポリシーは適用されます。スキャンの対象範囲と制約は coverage.json で確認してください。差分が空の場合やドライランの場合もチェックを不合格にするには、GitHub Action の scan-status 出力が completed であることを必須条件にします。詳しくは、重大度ポリシーの選択を参照してください。
その他のプロバイダーについては、CI/CD の概要を参照してください。コミットのたびに事前チェックを行うには、install-hook を使用します。