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

Codex Security CLI クイックスタート

Codex Security をセットアップし、ローカルスキャンを実行して、レポート、検出結果、カバレッジを確認します。

Codex Security は、セキュリティチームとエンジニアリングチームが脆弱性を発見、確認、修正するのに役立ちます。 コマンドラインインターフェース（CLI）を使用して、所有している、または評価する権限がある リポジトリをスキャンし、検出結果を継続的に確認し、変更が取り込まれる前にチェックできます。

前提条件を確認する

CLI には Node.js 22 以降が必要です。スキャンの実行や検出結果のエクスポートには、 Python 3.10 以降も必要です。詳しくは、認証と 前提条件を参照してください。

CLI をセットアップして確認する

公開パッケージをインストールします。

npm install @openai/codex-security

使用可能なコマンドを一覧表示します。

npx @openai/codex-security --help

CLI リファレンスも参照してください。

サインインする

ローカルで使用する場合は、ChatGPT アカウントでサインインします。

npx @openai/codex-security login

リモートマシンまたはヘッドレスマシンでは、デバイス認証を使用します。

npx @openai/codex-security login --device-auth

CI やその他の自動化ワークフローでは、OpenAI API key を設定します。

export OPENAI_API_KEY="<your-api-key>"

AWS 認証情報については、Amazon Bedrock の セットアップを参照してください。

API key も設定されている場合に ChatGPT のサインインを使用するには、明示的に選択します。

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

環境の API key を必須にするには、API key 認証を選択します。

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

アカウントとリポジトリによっては、リポジトリ全体のスキャンに Trusted Access for Cyberも必要になる場合があります。

スキャンを準備する

スキャンするリポジトリと、結果を書き込むディレクトリを選択します。

REPOSITORY=/path/to/repository
SCAN_DIR=/path/outside/repository/codex-security-results

--output-dir を省略すると、Codex Security は独自の永続的な状態ディレクトリに 結果を保存します。結果にはソースの抜粋や脆弱性の詳細が含まれる場合があるため、 非公開の場所と適切な保持ポリシーを選択してください。

デフォルトの状態ディレクトリに書き込めない場合は、スキャン対象リポジトリの 外部にある書き込み可能なディレクトリを選択します。

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

スキャンを開始する前に、リポジトリ、ターゲット、出力ディレクトリを確認します。

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --dry-run

ドライランでは、Codex の起動、認証情報の読み込み、プラグインの Python インタープリターの 検査を行わずに、ローカル入力を確認します。

最初のスキャンを実行する

標準スキャンを実行し、選択したディレクトリに結果を保存します。

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR"

デフォルトでは、CLI はスキャンの進行状況と完了サマリーを stderr に書き込みます。 完全なスキャン結果は stdout に出力しません。完了したスキャンでは、次のような サマリーが出力されます。

codex-security: Findings: 2 (1 high, 1 medium). Coverage: complete.
codex-security: Elapsed: 42s.
codex-security: Report: /path/outside/repository/codex-security-results/report.md
codex-security: Results: /path/outside/repository/codex-security-results

利用可能な場合は、トークン使用量と推定コストも表示されます。完全な結果を 機械可読な JSON として出力するには、構造化出力を明示的に要求します。

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --json

スキャンはデフォルトでレポートのみを生成するため、検出結果はローカルで 確認できます。CI でスキャンを実行する準備ができたら、 重大度のしきい値を追加するとよいでしょう。

モデルと推論エフォートを選択する

スキャンではデフォルトで gpt-5.6-sol と xhigh の推論エフォートが使用されます。タスクで 必要な場合は、別のモデルとエフォートを選択します。

npx @openai/codex-security scan "$REPOSITORY" \
  --model gpt-5.6-terra \
  --effort high

サポートされるエフォートレベルは、minimal、low、medium、high、xhigh です。

結果を確認する

読みやすい結果を確認するには、report.md を開きます。スキャンディレクトリには、自動化で 使用する構造化ファイルも含まれています。

codex-security-results/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
    └── results.sarif       # when produced
  • scan-manifest.json には、ターゲット、スコープ、生成元、封印された アーティファクトが記録されます。
  • findings.json には、各検出結果の重大度、信頼度、場所、証拠、 修復方法が記録されます。
  • coverage.json には、確認済みの領域、除外項目、保留中の作業、未解決の 問題、カバレッジの完全性が記録されます。

カバレッジは complete、partial、unknown のいずれかです。スキャンをレビューの証拠として扱う前に、 保留中の領域や未解決の問題を確認してください。 CLI リファレンスでは、 アーティファクトと出力の完全な規約について説明しています。

次のスキャンを選択する

リポジトリに複数のサービスやパッケージが含まれる場合は、パススキャンを使用します。

npx @openai/codex-security scan "$REPOSITORY" \
  --path services/billing \
  --path packages/auth

ベースリビジョンから HEAD までのコミット済み変更を確認します。

npx @openai/codex-security scan "$REPOSITORY" --diff origin/main --head HEAD

HEAD に対するステージ済みおよび未ステージの変更を確認します。

npx @openai/codex-security scan "$REPOSITORY" --working-tree --base HEAD

差分スキャンとワーキングツリースキャンでは、リポジトリ引数に Git ワークツリーのルートを指定する必要があります。差分スキャンを開始する前に、選択したリビジョンを取得してください。

リポジトリまたはパスをより広範に確認する必要がある場合は、ディープモードを使用します。

npx @openai/codex-security scan "$REPOSITORY" --mode deep

ディープモードはリポジトリとパスのターゲットをサポートしますが、差分スキャンやワーキングツリースキャンはサポートしません。

アーキテクチャとセキュリティのコンテキストを追加する

アーキテクチャ文書、脅威モデル、セキュリティポリシーをスキャンの コンテキストとして指定します。これにより、Codex Security はシステムの実際の 動作に照らして検出結果を評価できます。

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

スキャン予算を設定する

推定モデルコストが USD の上限を超えたときにスキャンを停止するには、 --max-cost を使用します。

npx @openai/codex-security scan "$REPOSITORY" --max-cost 5

すでに進行中のリクエストは、上限を超えて完了する場合があります。スキャンが停止しても、 Codex Security は利用可能な結果を保持します。

各コミットの前に変更をスキャンする

リポジトリに Git の pre-commit セキュリティチェックをインストールします。

npx @openai/codex-security install-hook

このチェックは、各コミットの前にステージ済みおよび未ステージの変更をスキャンします。既存の pre-commit スクリプトを置き換えることなく、重大度の高い検出結果やスキャンエラーがある場合に コミットをブロックします。

リポジトリを一括スキャンする

リポジトリを検出する前に GitHub にサインインします。

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

既存の一括スキャンを再開するには、同じコマンドをもう一度実行します。結果アーティファクトが すべて残っている完了済みリポジトリは、再スキャンされません。一時的なリポジトリエラーや スキャンエラーを再試行する場合は、--max-attempts 3 を追加します。

GitHub での検出、CSV の準備、キャンペーン結果、Docker のセットアップについては、 セキュリティスキャンを一括実行するを参照してください。

Docker で一括スキャンを実行する

アクセス権に Codex Security Docker イメージが含まれている場合は、Linux Docker ホストで 提供されている強化済み Compose 設定とセキュリティプロファイルを使用します。 ホストは、非特権ユーザー名前空間の作成をサポートしている必要があります。リポジトリの CSV を指定し、結果とサインイン状態を永続的にマウントされたディレクトリに保存し、 環境またはシークレットマネージャーを通じて認証情報を提供します。

docker compose run --rm codex-security \
  bulk-scan /input/repositories.csv \
  --output-dir /output \
  --workers 4

コンテナはプロンプトを表示せずに一括スキャンを実行します。リポジトリをインタラクティブに 検出する場合は、Docker の外部で CLI を使用してください。非公開リポジトリでは、 環境またはシークレットマネージャーを通じて GH_TOKEN または GITHUB_TOKEN を指定します。アカウントとリポジトリへの アクセスを含むサインイン要件は、コンテナ化されたスキャンにも適用されます。

保存済みスキャンを再確認する

リポジトリの保存済みスキャンを一覧表示します。

npx @openai/codex-security scans list "$REPOSITORY"

結果からスキャン ID をコピーし、その検出結果と設定を確認します。

npx @openai/codex-security scans show SCAN_ID

確認済みの検出結果を誤検知としてマークするには、その検出結果が該当しない理由を説明します。

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The route already checks permissions"

以降のスキャンではこの説明が考慮されますが、現在のコードは引き続き再確認されます。

元の設定を使用して、現在のチェックアウトに対して同じスキャンを実行します。

npx @openai/codex-security scans rerun SCAN_ID

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

一括スキャン用 CSV の形式、スキャン履歴のフィルター、コマンドオプションについては、 CLI リファレンスを参照してください。

目的に合ったワークフローに進んでください。