Codex Security CLI クイックスタート

スタンドアロンの Codex Security CLI を使用して、ローカルリポジトリの標準スキャンを実行します。このクイックスタートでは、後から確認し直せるレポートを保存するところまで進めます。 Codex の会話内でスキャンする場合は、Codex Security プラグインを使用してください。

前提条件を確認する

Node.js 24 または 26、あるいは 22.13.0 以降の Node.js 22 を使用してください。 Python 3.10 以降も必要です。 Python 3.10 では tomli も必要です。OpenAI の推論を使用するスキャンには、Codex Security へのアクセス権が必要です。アカウントとリポジトリによっては、リポジトリ全体のスキャンに Trusted Access for Cyber も必要になる場合があります。

CLI はオペレーティングシステム上のユーザー権限で実行され、承認を求めて一時停止することはありません。スキャンプロセスは環境を引き継ぐ可能性があるため、関係のない認証情報を削除してから開始してください。ローカルスキャンの権限を参照してください。

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

npx で公開パッケージを実行します。

npx @openai/codex-security --version

このコマンドは、インストールされているパッケージのバージョンを表示します。info --json で同梱プラグインのバージョンを確認するか、--help でコマンド一覧を表示できます。パッケージの変更は、 CLI と SDK のリリースに記載されています。

サインインする

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

npx @openai/codex-security login

ブラウザーのないマシンでは、--device-auth を追加し、表示されるサインイン手順に従ってください。環境に API key も含まれている場合でも、このサインインを選択するには、以下のスキャンコマンドで --auth chatgpt を使用してください。

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

スキャンを準備する

これらのパスを、リポジトリのパスと、その Git ワークツリー外にある新しい結果ディレクトリのパスに置き換えてください。

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 を追加してください。ダッシュボードや保存されたログには、ソースコードや認証情報が含まれる場合があります。共有する前に内容を確認してください。

スキャンが完了すると、stderr にレポートのパス、検出件数、経過時間が出力されます。例：

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

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

デフォルトでは、検出結果の重大度によってスキャンが失敗することはありません。機械可読な stdout を出力するには、--json を追加してください。検出結果に応じて CI チェックを失敗させるには、 重大度ポリシーを設定してください。

結果を確認する

表示されたディレクトリ内の report.md を開いてください。対象とリビジョンを確認し、個々の検出結果を確認する前に、カバレッジを読んでください。

scan.statusをscan-manifest.jsonで確認し、スキャンが完了したことを確かめます。 coverage.jsonで、レビュー済みの範囲、除外されたパス、後回しにした作業、未解決の疑問点を確認します。

完了したスキャンは0で終了します。ただし、検出事項が設定された重大度のしきい値に達した場合は1を返します。カバレッジの不足は終了コードに影響しないため、終了コード0はすべてのファイルがレビュー済みであることを意味しません。入力、実行、結果の整合性、または必須出力に関するエラーの場合は2を返します。 CLI リファレンスで終了コードについて説明しています。

検出事項ごとに、影響を受けるコード、攻撃者に必要な前提条件、検証の証拠、残る不確実性を確認します。ソースコードに基づく検出事項には、必ずしも実行時の再現成功が含まれるとは限りません。修正対象の検出事項を選ぶのは、その証拠が指摘された問題を裏付けていることを確認してからにしてください。

共有やアーカイブの際は、スキャンディレクトリを丸ごと保持してください。このディレクトリには、 scan-manifest.json、findings.json、coverage.jsonのほか、レポートと裏付けとなるアーティファクトが含まれます。全体の構成はスキャンアーティファクトを参照してください。

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

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

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

結果からスキャン ID をコピーします。

npx @openai/codex-security scans show SCAN_ID

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

次のスキャンを選ぶ

認証の問題、スキャンを繰り返した際の差異、誤検知に関するフィードバックについては、CLI FAQを参照してください。