ChatGPT ドキュメント
日本語
お問い合わせ goolvyouyou@gmail.com

Codex Security CLI FAQ

Codex Security のスキャン、検出結果、誤検知、カバレッジ、コスト、CI に関する回答です。

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

リポジトリのスキャン

CLI を利用できるユーザー

@openai/codex-security パッケージは公開されています。CLI と SDK をインストールします。

npm install @openai/codex-security

スキャンを実行するには、Codex Security へのアクセス権が必要です。最良の結果を得るには、 Trusted Access for Cyber の認証を受けたアカウントを使用してください。

サインイン後にスキャンが 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 リファレンスを参照してください。

リポジトリの一括スキャンの仕組み

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

gh auth login

GitHub アカウントまたは Organization からリポジトリを検出して選択します。

npx @openai/codex-security bulk-scan

用意済みのリストを使用する場合は、リポジトリの CSV と出力ディレクトリを指定します。

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4

GitHub での検出、CSV 形式、キャンペーン結果、利用可能なオプションについては、セキュリティスキャンを一括実行するを参照してください。

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

はい。元の 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

スキャンでアーキテクチャとセキュリティポリシーを使用する方法

--knowledge-base を使用して、アーキテクチャ文書、脅威モデル、セキュリティポリシーを渡します。

npx @openai/codex-security scan . \
  --knowledge-base /path/to/architecture.md \
  --knowledge-base /path/to/security-policies

Codex Security は、これらの文書を現在のスキャンのコンテキストとして使用します。サポートされるファイル形式とディレクトリの動作については、セキュリティコンテキストを追加するを参照してください。

検出結果とカバレッジ

チームが以前のスキャン結果を確認できる場所

リポジトリに保存されているスキャンを一覧表示します。

npx @openai/codex-security scans list /path/to/repository

結果に含まれるスキャン ID を使用して、検出結果を確認します。

npx @openai/codex-security scans show SCAN_ID

完了した各スキャンでは、レポート、検出結果、カバレッジ、補助成果物がまとめて保持されます。完全な構成については、スキャン成果物を参照してください。

CLI がスキャン履歴を保存できない場合

Codex Security は、スキャン履歴をワークベンチデータベースに保持します。デフォルトの状態ディレクトリに書き込めない場合は、リポジトリの外部にある非公開ディレクトリを選択してください。

export CODEX_SECURITY_STATE_DIR=/path/outside/repository/codex-security-state

スキャンで新規と既知の検出結果を区別する方法

2 つのスキャン間で根本原因が共通する検出結果を照合します。

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

照合された検出結果を比較します。

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 match BASELINE_SCAN_ID REPEAT_SCAN_ID

照合された結果を比較します。

npx @openai/codex-security scans compare BASELINE_SCAN_ID REPEAT_SCAN_ID

コンテキストの不足が結果の変動につながっている可能性がある場合は、共通のアーキテクチャとセキュリティのガイダンスを提供してください。照合により、複数回の実行にまたがる同一の根本的な検出結果を特定できますが、スキャンが決定論的になるわけではありません。消えた重要な検出結果は、直接再確認してください。

修正が有効だったことをチームで確認する方法

修正を適用した後、元のスキャンを再実行します。

npx @openai/codex-security scans rerun BEFORE_SCAN_ID

元の検出結果を新しいスキャンと照合します。

npx @openai/codex-security scans match BEFORE_SCAN_ID AFTER_SCAN_ID

照合された検出結果を比較します。

npx @openai/codex-security scans compare BEFORE_SCAN_ID AFTER_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"

検出結果が見つからないことやスキャン比較だけでは、修正が有効だったとは証明できません。

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

カバレッジは complete、partial、unknown のいずれかです。スキャンをレビューの証拠として扱う前に、coverage.json で除外されたパス、保留された対象、未解決の質問を確認してください。

カバレッジが partial または unknown のスキャンは、重大度ポリシーがない場合でも終了コード 2 を返します。それでも、利用可能な検出結果とカバレッジは保持されます。後のスキャンが以前の検出結果の元のパスを網羅していなければ、その検出結果が存在しなくなったことを立証できません。

自動化とコスト

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

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

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

この上限は推定値であり、厳格な支出上限ではありません。すでに進行中のリクエストは、上限を超えて完了する場合があります。スキャンが停止した時点で利用可能な結果は、 Codex Security によって保持されます。

スキャンでコミットと pull request を確認できるか

ステージ済みおよび未ステージの変更に対する pre-commit セキュリティチェックをインストールします。

npx @openai/codex-security install-hook

pull-request のチェックでは、コミット済みの変更をスキャンし、重大度のしきい値を設定します。

npx @openai/codex-security scan . \
  --diff origin/main \
  --fail-on-severity high

完全なスキャンで、選択した重大度以上の問題が見つかると、終了コード 1 が返されます。完全な GitHub Actions ワークフロー、成果物の処理、SARIF のエクスポートについては、CI でスキャンを実行するを参照してください。

別のアプリケーションからスキャンを直接実行できるか

はい。TypeScript SDK を使用すると、アプリケーションまたは開発者ツールからスキャンを開始し、対象を選択し、検出結果とカバレッジを確認し、進行状況を追跡して、コスト管理を適用できます。