Codex Security CLI クイックスタート

スタンドアロンの Codex Security CLI を使って、ローカルリポジトリの標準スキャンを実行します。完了するとレポートが保存され、その場でも後からでも結果を確認できます。Codex の会話内でスキャンするには、Codex Security プラグインを使ってください。

前提条件の確認

Node.js 24 または 26 を使用してください。Node.js 22 系を使う場合は 22.13.0 以降が必要です。Python 3.10 以降も必要です。Python 3.10 を使う場合は tomli をインストールしてください。一部のサイバーセキュリティ関連のリクエストや、保護された検出事項へのアクセスには、Trusted Access for Cyber が必要です。

CLI は OS 上でユーザーに付与された権限で動作し、承認を待たずに処理を進めます。スキャンプロセスがユーザーの環境を引き継ぐことがあるため、スキャンに不要な認証情報は開始前に環境から削除してください。詳しくはローカルスキャンの権限を参照してください。

CLI のセットアップと動作確認

公開パッケージをグローバルにインストールし、バージョンを確認します。

npm install -g @openai/codex-security
codex-security --version

このパッケージには codex-security コマンドとそのエイリアス cs が含まれます。npm がグローバルにインストールした実行ファイルのディレクトリが PATH に含まれていることを確認してください。

グローバルにインストールせずに実行するには、npx を使います。

npx @openai/codex-security --version

以降の例では npx @openai/codex-security を使います。グローバルにインストールした場合は、代わりに codex-security を使えます。

上のコマンドを実行すると、インストールされたパッケージのバージョンが表示されます。同梱のプラグインのバージョンを確認するには info --json を、コマンド一覧を表示するには --help を使います。

サインイン

ChatGPT アカウントでサインインします。

npx @openai/codex-security login

ブラウザのないマシンでは、ワークスペースでデバイス認証が許可されていれば --device-auth を追加し、表示される手順に従ってサインインしてください。デバイス認証が無効の場合は、SSH を使ったログイン手順に従ってください。以降のスキャンコマンドに --auth chatgpt を指定すると、環境に API キーが設定されていても、サインイン済みの ChatGPT アカウントで認証できます。

API キーや他のプロバイダーを使う場合は、スキャンの認証方法の選択を参照してください。Amazon Bedrock の場合は、ChatGPT でのサインインや OpenAI API キーの代わりに、AWS 認証情報とモデルへのアクセスを設定してください。

スキャンの準備

次のパスを、対象のリポジトリと、結果を保存する新しいディレクトリのパスに置き換えてください。結果の保存先は、リポジトリの Git Worktree の外に指定します。

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

結果にはソースコードの抜粋や脆弱性の詳細が含まれることがあります。アクセスを制限した場所に保存してください。--output-dir を省略すると、CLI は状態を永続化するためのディレクトリに結果を保存します。

スキャン対象と出力先を確認します。

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

ドライランが成功すれば、ローカルの入力に問題がないことを確認できます。ドライランではスキャンを開始せず、認証情報の読み込みやプラグインの Python インタープリターの確認も行いません。そのため、認証に成功するかどうかや、実行環境が正しく設定されているかどうかは、この段階では分かりません。

初回スキャンの実行

--dry-run を外してスキャンを開始します。

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

対話型ターミナルではダッシュボードがリアルタイムで更新されます。非対話型ターミナルでは進捗が行単位で出力されます。対話型ターミナルでも行単位で進捗を表示するには、--headless を追加してください。ダッシュボードや保存されたログには、ソースコードや認証情報が含まれることがあります。共有する前に内容を確認してください。

スキャンが終了すると、レポートのパス、検出件数、経過時間が標準エラー出力に表示されます。以下はその例です。

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

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

デフォルトでは、検出事項の重大度を理由にスキャンが失敗することはありません。機械で読み取れる形式で標準出力に結果を出すには、--json を追加してください。検出事項の重大度に応じて CI チェックを失敗させるには、重大度ポリシーを設定します。

結果の確認

結果ディレクトリの report.md を開きます。スキャン対象とリビジョンを確認してから、検出事項を確認してください。記録されたスキャンの状態と範囲は、それぞれ scan.status と scan.scope に示されています。どちらも scan-manifest.json にあります。

スキャンが完了すると、終了コードは 0 になります。ただし、設定した重大度のしきい値に達する検出事項がある場合は 1 を返します。終了コードが 0 でも、すべてのファイルが確認されたとは限りません。入力や実行に問題がある場合、結果の整合性が損なわれている場合、または必要な出力を生成できない場合は 2 を返します。終了コードの詳細は CLI リファレンスを参照してください。

検出事項ごとに、影響を受けるコード、攻撃が成立するための前提条件、検証で得られた証拠、まだ確認できていない点を確認してください。ソースコードに基づく検出事項については、実行時に問題を再現できたとは限りません。報告された問題を証拠が裏付けていることを確認してから、修正対象に選んでください。

スキャン結果を共有またはアーカイブする際は、スキャンディレクトリを丸ごと含めてください。このディレクトリには、scan-manifest.json と findings.json のほか、レポートとその裏付けとなる成果物が含まれています。ディレクトリ構成の詳細はスキャンの成果物を参照してください。

保存済みの脅威モデルのエクスポート

標準スキャン、詳細スキャン、差分スキャンでは、脅威モデルが結果とともに保存されます。サインインやモデルの再呼び出しをせずに、脅威モデルを Markdown 形式でエクスポートできます。

npx @openai/codex-security export "$SCAN_DIR" \
  --artifact threat-model --output "$SCAN_DIR/exports/threatmodel.md"

脅威モデルが保存されていない場合、export はエラーを返します。保存済みのスキャンを選ぶ方法や、別の出力形式を指定する方法は、エクスポートのリファレンスを参照してください。

保存済みスキャンの再確認

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

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

一覧からスキャン ID をコピーし、次のコマンドの SCAN_ID に指定します。

npx @openai/codex-security scans show SCAN_ID

対話型スキャンが完了し、検出事項があった場合は、CLI で各検出事項を閲覧することもできます。修正方法を選ぶ前に、そこで証拠を確認してください。保存済みの検出事項には、検証とパッチ適用のコマンドを使います。

次のスキャンの選択

認証に問題がある場合、再スキャンで結果が異なる場合、または誤検出についてフィードバックを送る場合は、CLI に関するよくある質問を参照してください。