Codex Security CLI リファレンス

このリファレンスでは、サポートされている codex-security コマンド、フラグ、 出力形式、終了時の動作を確認できます。ガイドに沿って最初のスキャンを行う場合は、 CLI クイックスタートから始めてください。

公開パッケージをプロジェクトにインストールします。

npm install @openai/codex-security

インストールしたパッケージは npx @openai/codex-security として呼び出します。実行可能ファイルが PATH で利用可能な場合は、 codex-security を直接使用できます。

コマンドの概要

usage: codex-security [--version] <command> [options]

CLI には次のコマンドがあります。

CLI には次の統合コマンドもあります。

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

npx @openai/codex-security --help

コマンドの引数とオプションを確認するには、--help を追加します。

npx @openai/codex-security scan --help

codex-security --version はインストール済みのバージョンを出力して終了します。 codex-security info --json は SDK と同梱プラグインのバージョンを報告します。 どちらのコマンドにも Python は必要ありません。

コマンドを検出してエージェントを接続する

エージェントが読み取れるコマンドマニフェストを出力します。

npx @openai/codex-security --llms

スキャン引数のスキーマを JSON として確認します。

npx @openai/codex-security scan --schema --format json

Bash 用のシェル補完を生成します。

npx @openai/codex-security completions bash

それらのシェルでは、bash を zsh または fish に置き換えてください。

スキャン結果は --format toon|json|yaml|jsonl と --full-output をサポートします。この フレームワークレベルの --format は、完了したスキャンからエクスポートする アーティファクトの形式を選択する --export-format とは別のものです。グローバルコマンドのヘルプには md も表示されますが、スキャン結果は Markdown 出力をサポートしません。

CLI を MCP サーバーとして登録します。

npx @openai/codex-security mcp add

Codex Security スキルをエージェントに同期します。

npx @openai/codex-security skills add

MCP が公開するのは、読み取り専用の info メタデータコマンドだけです。スキャン、エクスポート、 認証、検証、パッチ適用は CLI でのみ利用できます。

codex-security scan

リポジトリ、選択したパス、コミット済みの変更、または ワーキングツリーに対してスキャンを実行します。

usage: codex-security scan [-h] [--auth {auto,chatgpt,api-key}]
                           [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                           [--path PATH | --diff BASE | --working-tree]
                           [--head HEAD] [--base BASE]
                           [--knowledge-base PATH]
                           [--mode {standard,deep}] [--model MODEL]
                           [--effort {minimal,low,medium,high,xhigh}]
                           [--output-dir DIR]
                           [--archive-existing]
                           [--plugin-path PATH] [--python PATH]
                           [--codex KEY=VALUE] [--fail-on-severity LEVEL]
                           [--max-cost USD] [--dry-run] [--verbose]
                           [--json] [--format {toon,json,yaml,jsonl}]
                           [--full-output] [repository]

repository のデフォルトは現在のディレクトリです。

スキャンの認証方法を選択する

デフォルトの --auth auto を使用すると、認証情報が自動的に選択されます。ChatGPT のサインインと OPENAI_API_KEY または CODEX_API_KEY の両方が利用可能な場合、 テキスト出力を使用するインタラクティブスキャンでは、使用する認証情報の選択を求められます。CI、JSON、 JSONL スキャン、およびインタラクティブターミナルを使用しないその他のスキャンでは、 環境の API key が使用されます。ドライランでは、プロンプトの表示も認証情報の読み込みも行われません。

保存済みの認証情報を使用するには、--auth chatgpt を渡します。

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

環境の API key を使用するには、--auth api-key を渡します。

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

保存済みの認証情報を自動選択のデフォルトにするには、 unset OPENAI_API_KEY CODEX_API_KEY を実行します。

Amazon Bedrock を使用する

--provider amazon-bedrock で Amazon Bedrock を選択し、--model で明示的な Bedrock モデルを指定します。

npx @openai/codex-security scan . \
  --provider amazon-bedrock \
  --model openai.gpt-5.6-sol

AWS_REGION を設定し、AWS_BEARER_TOKEN_BEDROCK、標準の AWS アクセスキー、AWS プロファイル、ウェブアイデンティティ、コンテナ認証情報、または デフォルトの AWS 認証情報チェーンで認証します。Bedrock スキャンでは、 --auth、ChatGPT のサインイン、OpenAI API key の代わりに AWS 認証情報を使用します。scan と bulk-scan はどちらも --provider をサポートします。

スキャンターゲットを選択する

スキャンごとにターゲットの種類を 1 つ選択します。

--path、--diff、--working-tree は相互に排他的です。--head には --diff が必要で、--base には --working-tree が必要です。ディープモードは リポジトリとパスのターゲットをサポートします。

差分スキャンとワーキングツリースキャンでは、リポジトリ引数に Git ワークツリーのルートを指定する必要があります。選択した ref はそのチェックアウトに存在している必要があります。

リポジトリ全体をスキャンします。

npx @openai/codex-security scan .

選択したパスをスキャンします。

npx @openai/codex-security scan . --path src --path tests

コミット済みの変更をスキャンします。

npx @openai/codex-security scan . --diff origin/main --head HEAD

ステージ済みおよび未ステージの変更をスキャンします。

npx @openai/codex-security scan . --working-tree --base HEAD

リポジトリをより詳細に確認します。

npx @openai/codex-security scan . --mode deep

セキュリティコンテキストを追加する

アーキテクチャ文書、脅威モデル、セキュリティポリシーを指定するには、 --knowledge-base PATH を使用します。複数のファイルやディレクトリにはオプションを繰り返します。

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

サポートされる文書には、.md、.markdown、.txt、.pdf、.docx ファイルが含まれます。CLI はディレクトリを再帰的に検索し、リンクされた入力パスを拒否し、 リンクされたディレクトリエントリをスキップし、抽出した文書内容を 保存済みのスキャン結果には含めません。

出力とポリシーのオプションを設定する

アーティファクトの保持、以前の結果の保存、機械可読な結果の作成には、 次のオプションを使用します。

コスト上限は推定値であり、厳密な支出上限ではありません。すでに進行中の リクエストは上限を超えて完了する場合があり、部分的なスキャン結果は引き続き利用できます。

--output-dir を省略すると、結果は $CODEX_HOME/state/plugins/codex-security/scans/<repository> に保持されます。CODEX_HOME の デフォルトは ~/.codex です。代わりに $CODEX_SECURITY_STATE_DIR/scans/<repository> 配下へ結果を保存するには、 CODEX_SECURITY_STATE_DIR を設定します。これらのディレクトリには ソースの抜粋や脆弱性の詳細が含まれる場合があるため、権限と保持期間を 適切に管理してください。

ワークベンチはスキャン履歴を $CODEX_HOME/state/plugins/codex-security/workbench.sqlite3 に保持します。 CODEX_SECURITY_STATE_DIR を設定すると、ワークベンチのデータベースも移動します。

出力ディレクトリは、スキャン対象ディレクトリおよびそれを包含する Git ワークツリーの外部に配置する必要があります。--archive-existing を使用すると、スキャンで既存の結果ディレクトリを置き換えられます。

出力ディレクトリを再利用する前に、以前の結果を保存します。

npx @openai/codex-security scan . \
  --output-dir /path/outside/repository/results \
  --archive-existing

スキャンはデフォルトでレポートのみを生成します。CI で重大度ポリシーを評価するには、 --fail-on-severity を追加します。

npx @openai/codex-security scan . \
  --diff origin/main \
  --output-dir /path/outside/repository/results \
  --json \
  --fail-on-severity high \
  > /path/outside/repository/codex-security.json

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

npx @openai/codex-security scan . \
  --output-dir /path/outside/repository/results \
  --dry-run

ランタイムを設定する

モデル、インタープリター、プラグイン、Codex 設定値を明示的に指定する必要がある場合は、 ランタイムオプションを使用します。

TOML を記述せずに別のモデルと推論エフォートを選択します。

npx @openai/codex-security scan . --model gpt-5.6-terra --effort high

--codex を通じて渡す文字列値は、TOML パーサーが文字列として受け取れるよう引用符で囲みます。

npx @openai/codex-security scan . --codex 'model="gpt-5.6-terra"'

codex-security install-hook

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

npx @openai/codex-security install-hook

このチェックは各コミットの前にステージ済みおよび未ステージの変更をスキャンし、 重大度の高い検出結果やスキャンエラーがある場合にブロックします。core.hooksPath を尊重し、 既存の pre-commit スクリプトは置き換えません。必要に応じて別の重大度しきい値を 設定します。

npx @openai/codex-security install-hook . --fail-on-severity medium

codex-security bulk-scan

GitHub リポジトリを検出してスキャンするか、リポジトリ CSV から 再開可能なスキャンを実行します。

GitHub での検出、CSV インベントリ、キャンペーン結果、コンテナ化されたスキャンの 完全なガイドについては、セキュリティスキャンを一括 実行するを参照してください。

usage: codex-security bulk-scan [input] [--output-dir DIR]
                                [--workers N] [--mode {standard,deep}]
                                [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                                [--model MODEL]
                                [--effort {minimal,low,medium,high,xhigh}]
                                [--max-attempts N] [--plugin-path PATH]
                                [--python PATH] [--codex KEY=VALUE]

リポジトリをインタラクティブに選択するには、引数なしで npx @openai/codex-security bulk-scan を実行します。 このフローには GitHub CLI へのサインインが必要です。

インタラクティブな検出中にモデルと推論エフォートを選択します。

npx @openai/codex-security bulk-scan --model gpt-5.6-terra --effort high

準備済みのリポジトリ一覧では、CSV と --output-dir を指定します。

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

CSV には id、repository、revision 列が必要です。リビジョンには 完全なコミットハッシュを指定する必要があります。オプションの scope 列と mode 列で、個々の リポジトリを設定できます。

id,repository,revision,scope,mode
service,https://github.com/example/service.git,0123456789abcdef0123456789abcdef01234567,src,standard

--workers は同時スキャン数を制限し、デフォルトは 4 です。--mode のデフォルトは standard、--max-attempts のデフォルトは 1 です。エラー後にリポジトリを 再試行する場合は、--max-attempts を設定します。同じコマンドをもう一度実行すると、既存の出力ディレクトリから 一括スキャンを再開できます。CLI が完了済みリポジトリをスキップするのは、記録された 結果アーティファクトがすべて残っている場合だけです。

コンテナ化されたキャンペーンについては、Docker で一括スキャンを 実行するを参照してください。

codex-security scans

保存済みスキャンを検索する

現在のディレクトリの保存済みスキャンを一覧表示します。

npx @openai/codex-security scans

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

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

特定の出力ディレクトリに保存されたスキャンを検索します。

npx @openai/codex-security scans list --scan-root /path/outside/repository/results

スキャンを確認または再実行する

保存済みスキャンの結果と設定を表示します。

npx @openai/codex-security scans show SCAN_ID

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

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

後のスキャンのカバレッジが不完全な場合や、検出結果の元の場所が 対象外の場合、その検出結果は不明になります。既存の照合を再計算する必要がある場合は、 match に --force を追加します。

他のチェックアウトのスキャンを含め、現在のリポジトリで完了したすべてのスキャンを照合します。

npx @openai/codex-security scans match --all

同じ設定を再実行しても、スキャン結果が異なる場合があります。照合と 比較は変更を追跡するものであり、結果を決定論的にしたり、脆弱性が 存在しなくなったことを証明したりするものではありません。セキュリティ上重要な検出結果を現在のコードに対して 再確認するには、validate を使用します。

codex-security findings

確認済みの検出結果を誤検知として記録します。

usage: codex-security findings false-positive OCCURRENCE_ID
                       --reason REASON

保存済みスキャンを確認して、検出結果の発生箇所を特定します。

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"

理由を空にすることはできません。Codex Security はリポジトリに対する判断を保存し、 以降のスキャンにコンテキストとして提供します。各スキャンでは、現在のソース、制御、 到達可能性が個別に再確認されます。以前の判断によって、ルール、パス、脆弱性クラスが 抑制されることはありません。

codex-security export

完了して封印されたスキャンから、CSV、JSON、SARIF をエクスポートします。エクスポートでは、 出力を書き込む前にスキャンアーティファクトを検証し、Codex ランタイムと 認証情報には触れません。

usage: codex-security export [--export-format {csv,json,sarif}]
                             [--output FILE|-] [--source-root PATH]
                             [--python PATH] scan_dir

scan_dir は完了したスキャンのディレクトリです。

--source-root は --export-format sarif でのみ機能します。JSON は 封印された検出結果文書を保持します。CSV には移植可能な検出結果の列が含まれますが、 ローカルワークベンチのトリアージ状態は含まれません。

--output を指定しない場合、CLI は現在の作業ディレクトリの results.sarif に SARIF、 findings.json に JSON、findings.csv に CSV を書き込みます。 エクスポートにはソースの抜粋や脆弱性の詳細が含まれる場合があります。コマンドは リポジトリの外部で実行するか、スキャン対象チェックアウトの外部にある非公開パスを --output で指定してください。

SARIF をファイルに書き込みます。

npx @openai/codex-security export /path/to/scan \
  --export-format sarif \
  --source-root /path/to/repository \
  --output /path/outside/repository/exports/results.sarif

SARIF を stdout に書き込みます。

npx @openai/codex-security export /path/to/scan \
  --export-format sarif \
  --source-root . \
  --output -

検出結果を JSON としてエクスポートします。

npx @openai/codex-security export /path/to/scan \
  --export-format json \
  --output /path/outside/repository/exports/findings.json

検出結果を CSV としてエクスポートします。

npx @openai/codex-security export /path/to/scan \
  --export-format csv \
  --output /path/outside/repository/exports/findings.csv

codex-security validate と codex-security patch

検出結果候補が有効かどうかを確認します。

npx @openai/codex-security validate findings.json \
  "Possible SQL injection in src/query.ts:42"

同梱の修復スキルで修正を生成します。

npx @openai/codex-security patch findings.json \
  "Missing authorization check in src/routes.ts:18"

各引数にはリテラルテキストを含めるか、ファイルを指定できます。どちらのコマンドも 現在のディレクトリを対象に動作します。修正後、または後のスキャンで報告されなくなった後に 元の検出結果を直接再確認するには、validate を使用します。スキャンの 比較だけでは、修正が機能したことを証明できません。外部ツールは、スキャナーを再構築せずに これらのコマンドを使用できます。

どちらのコマンドでも、推論エフォートを選択するには --effort を使用します。

npx @openai/codex-security validate "Possible SQL injection" --effort high

codex-security login、logout、info

インタラクティブにサインインします。

npx @openai/codex-security login

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

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

現在のサインインを確認します。

npx @openai/codex-security login status

保存済みのサインインを削除します。

npx @openai/codex-security logout

stdin で API key を渡して保存します。

printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key

エンタープライズアクセストークンを保存します。

printenv CODEX_ACCESS_TOKEN | npx @openai/codex-security login --with-access-token

読み取り専用の SDK と同梱プラグインのメタデータを確認します。

npx @openai/codex-security info --json

CLI を MCP サーバーとして公開する場合、利用可能なコマンドは info だけです。 スキャン、エクスポート、サインイン、検証、パッチ適用は CLI でのみ利用できます。

スキャン出力を読み取る

デフォルトでは、スキャンは進行状況、完了サマリー、エラーを stderr に送り、 完全なスキャン結果を stdout には書き込みません。構造化されたスキャン結果を stdout に送るには、 --json、--format、--full-output のいずれかを要求します。

詳細な診断情報

マスキングされたライフサイクル、認証、進行状況、コストの診断情報を stderr に出力するには、 --verbose を追加します。

npx @openai/codex-security scan . --verbose

フラグなしで同じ診断情報を有効にするには、CODEX_SECURITY_LOG_LEVEL=debug を設定します。 CODEX_SECURITY_LOG_LEVEL が未設定の場合は、LOG_LEVEL=debug でも診断情報が有効になります。

これらのログ制御は CLI にのみ適用されます。認証情報とプロバイダー識別子は 引き続きマスキングされ、構造化されたスキャン結果は stdout に出力されます。

完了サマリー

完了したスキャンでは、検出結果数、重大度別の内訳、カバレッジ、 経過時間、レポートのパス、結果ディレクトリが stderr に書き込まれます。利用可能な場合は、 トークン使用量と推定コストも含まれます。

codex-security: Findings: 4 (1 critical, 2 high, 1 informational). Coverage: complete.
codex-security: Elapsed: 1s.
codex-security: Tokens: 1,250 input, 200 cached, 30 output.
codex-security: Report: /path/to/scan/report.md
codex-security: Results: /path/to/scan

情報レベルの検出結果もサマリーの合計に含まれます。重大度ポリシーが 評価するのは、critical、high、medium、low の検出結果だけです。

JSON 出力

scan --json は、1 つの完全な JSON 文書を stdout に書き込みます。最上位の構造は 次のとおりです。

manifest
findings
coverage
scanDir
threadId
reportPath
artifactsDir
sarifPath
turn
  id
  status
  durationMs
  finalResponse
  usage

進行状況、完了サマリー、アーカイブ通知、エラーは引き続き stderr に出力されます。 重大度ポリシーによって終了コード 1 が返される場合や、カバレッジが不完全で 終了コード 2 が返される場合でも、完了したスキャンでは完全な JSON 結果が出力されます。

スキャンアーティファクト

完了したスキャンでは、読みやすいレポートと構造化されたアーティファクトがまとめて保存されます。

<scan-directory>/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
    └── results.sarif       # when produced

構造化ファイルには、それぞれ異なる役割があります。

カバレッジの完全性には 3 つの値があります。

• complete: 選択したスコープが完全にカバーされたことをスキャンが記録しています。
• partial: 保留中の作業やその他のカバレッジ制限をスキャンが記録しています。
• unknown: カバレッジの完全性が不明であるとスキャンが報告しています。

セキュリティ上の判断の証拠としてカバレッジを使用する前に、保留中の領域、 明示的な除外項目、未解決の問題を確認してください。

終了コードとシグナル

CLI は次の終了コードを使用します。

partial または unknown のカバレッジを持つスキャンは、重大度ポリシーがなくても 2 を返します。構造化出力を要求した場合、完了したスキャンでは 利用可能な結果が引き続き stdout に書き込まれます。中断またはランタイムエラーの後は、 部分的な出力がある場合、その場所が CLI によって出力されます。

認証と前提条件

OPENAI_API_KEY または CODEX_API_KEY を設定するか、 npx @openai/codex-security login でサインインするか、既存のファイルベースの Codex サインインを使用します。Amazon Bedrock では、代わりに Bedrock API key または標準の AWS 認証情報チェーンを使用します。

認証情報の選択については、スキャンの認証方法を 選択するを参照してください。

CI では、API key のスコープをスキャンステップに限定し、信頼できるワークフローを使用してください。

CLI には Node.js 22 以降が必要です。スキャンの実行や検出結果のエクスポートには、 Python 3.10 以降も必要です。Python 3.10 では tomli も必要です。自動検出が適切でない場合は、 --python または PYTHON を使用してインタープリターを選択します。

CLI クイックスタート、一括スキャン ガイド、CLI FAQ、CI ガイド、TypeScript SDK ガイドのいずれかに進んでください。

プレーンテキストのエイリアス

• --output FILE|-