Codex Security CLI FAQ

ターミナルからリポジトリをスキャンし、セキュリティの検出結果を管理する際のよくある質問への回答を紹介します。インストールと初回スキャンについては、 CLI クイックスタートから始めてください。

リポジトリのスキャン

サインイン後にスキャンが API key を使用する理由

環境に OPENAI_API_KEY または CODEX_API_KEY が設定されている場合、対話型ターミナルを使用しないスキャン、および JSON、JSONL 形式のスキャンでは、ChatGPT またはアクセストークンでのログインに成功した後でも、デフォルトで環境の API key が使用されます。テキスト出力を伴う対話型スキャンでは、 ChatGPT サインインも利用できる場合に、使用する認証情報の選択を求められます。ドライランでは、認証情報の入力を求めたり読み込んだりしません。

保存済みの認証情報をスキャンで使用するには、明示的に選択します。

npx @openai/codex-security scan . --auth chatgpt

OPENAI_API_KEY または CODEX_API_KEY の API key を必須にするには、次を実行します。

npx @openai/codex-security scan . --auth api-key

保存済みの認証情報を自動的なデフォルトにするには、 unset OPENAI_API_KEY CODEX_API_KEY を実行します。サポートされているすべての認証モードについては、 CLI リファレンスを参照してください。

中断された一括スキャンを再開できるか

はい。元の CSV と出力ディレクトリを指定して、同じ bulk-scan コマンドを実行します。 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"

脆弱性につながる経路が遮断され、正当な動作が引き続き機能することを示す証拠を確認してください。元の再現手順や回帰テストがあれば実行します。確認を実行できない場合は、結果に残る不確実性を記載してください。

スキャンの比較では、指摘事項の変化を確認できますが、指摘事項が検出されなくなっただけでは修正を検証したことにはなりません。

不完全なカバレッジの意味

除外されたパス、保留された対象領域、未解決の疑問点は coverage.json で確認してください。新しい結果には、カバレッジの完全性を示すフィールドは含まれません。実行ステータスは、scan.status を scan-manifest.json 内で確認してください。

カバレッジの不足によって、完了したスキャンの終了コードが変わることはありません。終了コード 0 は、すべてのファイルがレビューされたことを意味しません。後のスキャンが以前の指摘事項の元のパスを対象に含めていない場合、その指摘事項が存在しなくなったとは確認できません。

自動化とコスト

ディープスキャンの制限時間はどのように機能しますか

ディープスキャンの開始時に、ワーカーの期限を設定します。

npx @openai/codex-security scan . --mode deep --max-time-hours 1.5

デフォルトは 96 時間です。96 以下の正の値を使用でき、小数も指定できます。期限に達すると、Codex Security は未完了のワーカーを停止し、完了した標準スキャンの結果を保持して、最終レポートに集約します。レビュー済みの領域と保留された作業はレポートで確認してください。期限に達したことだけで終了コードが決まるわけではなく、実行ステータスと重大度ポリシーによって決まります。

設定を永続化する場合や一括キャンペーンを実行する場合は、ディープスキャンの 設定で、[deep_scan] の下に max_time_hours を設定します。

スキャンのコスト上限の仕組み

スキャンを開始する前に、推定コストの上限を USD で設定します。

npx @openai/codex-security scan . --max-cost 5

この制限は見積もりであり、厳密な支出上限ではありません。すでに実行中のリクエストは、上限を超えて完了する場合があります。Codex Security が完了したワーカーの結果を集約した後にディープスキャンが上限に達した場合、CLI は予算に関する警告付きで完了したレポートを保存できます。終了コードは 0 ですが、指摘事項が設定された重大度のしきい値を満たす場合は 1 になります。有効な完了結果を生成できない場合は、 2 を返し、利用可能な出力をすべて保持します。

GitHub プルリクエストのチェックと定期的なリポジトリスキャンには、 Codex Security GitHub Action を使用してください。 action-v0.3.0 では、スキャンの完了は、設定された分析によって有効な結果が得られたことを意味します。スコープからの除外や調査の保留によって、重大度ポリシーが回避されることはありません。coverage.json を確認し、スキャンの範囲と制限を評価してください。空の差分やドライランも拒否するには、Action の scan-status 出力が completed であることを必須にしてください。重大度ポリシーを選択するを参照してください。

その他のプロバイダーについては、CI/CD の概要を参照してください。コミットの前に毎回チェックするには、 install-hook を使用してください。