Codex Security CLI クイックスタート

Codex Security は、セキュリティチームとエンジニアリングチームによる脆弱性の発見、確認、修正を支援します。コマンドラインインターフェイス（CLI）を使用して、自分が所有しているか評価の許可を得ているリポジトリをスキャンし、検出結果を時系列で確認して、変更が取り込まれる前にチェックします。

前提条件を確認する

CLI には Node.js 22（22.13.0 以降）、24、または 26 が必要です。スキャン、一括スキャン、エクスポート、スキャン履歴、保存済みの検出結果には、Python 3.10 以降も必要です。詳しくは、認証と前提条件を参照してください。

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

npx で CLI を実行し、そのバージョンを確認します。

npx @openai/codex-security --version

パッケージのバージョンと同梱プラグインのバージョンの両方を表示するには、次を実行します。

npx @openai/codex-security info --json

パッケージの変更点については、CLI と SDK のリリースを参照してください。

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

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 のセットアップを参照してください。OpenRouter または Fireworksの場合は、プロバイダーの API key を設定し、 --provider と --model でモデルを選択します。

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 インタープリターの検査を行わず、--knowledge-base パスを含むローカル入力を確認します。

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

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

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

対話型ターミナルにはライブスキャンダッシュボードが表示されます。代わりに通常の進行状況行を表示するには、--headless を追加します。CI と対話型セッションのないターミナルでは、通常の進行状況が自動的に使用されます。

ダッシュボードにはライブセッションの詳細も表示されます。これにはソースコードや認証情報が含まれる可能性があるため、共有前に確認してください。

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

  REPORT    /path/outside/repository/codex-security-results/report.md

  FINDINGS  2 (2 confirmed this scan; 0 previously found; 1 high, 1 medium)
  COVERAGE  complete
  ELAPSED   42s
  RESULTS   /path/outside/repository/codex-security-results

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

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

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

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

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

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

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

結果を確認する

読みやすい結果を確認するには、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 リファレンスでは、アーティファクトと出力の完全な仕様について説明しています。

検出結果を確認してパッチを適用する

検出結果のある対話型スキャンが完了すると、CLI に検出結果ブラウザーが表示されます。証拠を確認し、修正する検出結果を選択してください。保存されたタスクは Codex デスクトップアプリで確認できます。

ブラウザーを使用せずに重大度が high と critical の検出結果へパッチを適用するには、次を実行します。

npx @openai/codex-security scan "$REPOSITORY" \
  --patch --patch-severity high --json

検証済みのパッチをコミットして GitHub プルリクエストを開くには、--create-pr を追加します。

保存済みの検出結果にパッチを適用したり、Linear の Issue をインポートしたりすることもできます。 validate と patch のリファレンスを参照してください。

次のスキャンを選択する

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

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 ワークツリーのルートを指定する必要があります。差分スキャンを開始する前に、選択したリビジョンをフェッチしてください。

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

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

ワーカー、サブエージェント、スキャンを停止するタイミングを制御するには、次を実行します。

npx @openai/codex-security scan "$REPOSITORY" \
  --mode deep \
  --workers 2 \
  --subagents 0 \
  --stop-after-no-new 3 \
  --max-discovery-runs 10 \
  --max-time-hours 1.5

これらのオプションには deep モードが必要です。deep モードはリポジトリとパスのターゲットに対応しますが、差分スキャンやワーキングツリースキャンには対応しません。ここで、--workers は 1 回のスキャン内で独立して動作する標準スキャンワーカーを制御し、bulk-scan --workers は同時実行するリポジトリスキャンを制御します。--max-time-hours には、端数を含む 96 以下の正の時間数を指定できます。上限に達すると、スキャンは未完了のワーカーを停止し、完了したスキャン結果を保持して、最終レポートに集約します。

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

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

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

カスタムスキャン指示を追加する

セキュリティ上の優先事項にスキャンの焦点を合わせる指示を追加します。フォローアップ指示には 2 つ目のファイルを使用します。

npx @openai/codex-security scan "$REPOSITORY" \
  --scan-prompt-file /path/to/scan.md \
  --post-scan-prompt-file /path/to/follow-up.md

フォローアップは、成功したスキャン、およびカバレッジが不完全かエラーがあるスキャンの後に、同じ認証済みセッションで実行されます。フォローアップが失敗した場合、CLI は警告を報告し、完了したスキャンを保持します。キャンセル後、またはコスト上限に達したスキャンの後には実行されません。どちらのオプションも bulk-scan で使用できます。CSV の prompt 列には、リポジトリ固有の指示を追加できます。

スキャン予算を設定する

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

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

すでに処理中のリクエストが完了することで、上限をわずかに超える場合があります。Codex Security が完了済みワーカーの結果を集約した後に deep スキャンが上限に達した場合、CLI は完了したレポートを保存し、そのカバレッジを partial としてマークして、終了コード 2 を返します。スキャンが完了したレポートを生成できない場合、利用可能な部分出力はディスクに残ります。

コミット前に毎回変更をスキャンする

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

npx @openai/codex-security install-hook

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

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

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

gh auth login

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

npx @openai/codex-security bulk-scan

対話型フローでは、アーカイブ済みリポジトリとフォークが除外されます。スキャン前に、選択したリポジトリの確認を求められます。

用意したリポジトリ一覧をスキャンするには、CSV と出力ディレクトリを指定します。

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

既存の一括スキャンを再開するには、同じコマンドをもう一度実行します。Codex Security は完了済みのリポジトリをスキップします。一時的なリポジトリエラーやスキャンエラーを再試行する場合は、 --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 scans logs SCAN_ID

保存されたログは編集されておらず、ソースコードや認証情報が含まれる可能性があります。共有前に確認してください。

リポジトリの各スキャンにある未解決の検出結果を一覧表示します。

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

最新のスキャンで確認されなかった以前の検出結果は、未解決のままになります。

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

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 compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

比較では、根本原因に基づいて検出結果が自動的に照合され、保存済みの照合結果が再利用されます。

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

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

セキュリティスキャンを一括実行すると、GitHub リポジトリを検出したり、固定された CSV インベントリをスキャンしたりできます。
CLI の FAQ を読むと、スキャン履歴、偽陽性に関するフィードバック、カバレッジ、修正の検証についての回答を確認できます。
CI でスキャンを実行すると、プルリクエストを確認し、結果を保持して、重大度ポリシーを設定できます。
CLI リファレンスを使用すると、すべてのフラグ、出力形式、アーティファクト、終了コードを確認できます。
TypeScript SDK を統合すると、アプリケーションまたは開発者向けツールからスキャンを実行できます。

最近の検索

おすすめの検索

ドキュメントナビゲーション