Codex Security CLI リファレンス

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

CLI は npx @openai/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] [--scan-prompt-file FILE]
                           [--post-scan-prompt-file FILE]
                           [--mode {standard,deep}] [--workers N]
                           [--subagents N] [--stop-after-no-new N]
                           [--max-discovery-runs N] [--max-time-hours HOURS]
                           [--model MODEL]
                           [--effort {minimal,low,medium,high,xhigh,max}]
                           [--output-dir DIR]
                           [--archive-existing]
                           [--plugin-path PATH] [--python PATH]
                           [--codex KEY=VALUE] [--fail-on-severity LEVEL]
                           [--patch] [--patch-severity {critical,high,medium,low}]
                           [--create-pr]
                           [--max-cost USD] [--dry-run] [--headless] [--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 を実行します。

OpenRouter または Fireworks を使用する

API key と明示的なモデルを指定して OpenRouter を選択します。

export OPENROUTER_API_KEY="your-openrouter-api-key"
npx @openai/codex-security scan . \
  --provider openrouter \
  --model anthropic/claude-sonnet-4.5

API key と明示的なモデルを指定して Fireworks を選択します。

export FIREWORKS_API_KEY="your-fireworks-api-key"
npx @openai/codex-security scan . \
  --provider fireworks \
  --model accounts/fireworks/models/qwen3-235b-a22b

どちらのプロバイダーも bulk-scan をサポートしています。

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 が必要です。deep モードでは リポジトリとパスを対象にできます。

差分スキャンとワーキングツリーのスキャンでは、リポジトリ引数に 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

deep スキャンを設定する

--mode deep では、次のオプションを使用してワーカーの並行処理数と実行時間を制御します。

--subagents には 0 または正の整数を指定できます。--max-time-hours には、 96 以下の正の数値を指定できます。残りのオプションには正の 整数が必要です。これらのオプションは standard スキャンでは利用できません。

たとえば、2 つのワーカーを使用し、最大 10 回の実行を許可し、1.5 時間後に ワーカーの実行を停止するには、次のようにします。

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

制限時間が切れると、スキャンは未完了のワーカーを停止し、完了済みの スキャン結果を保持して最終レポートに集約します。ソースレビューを完了したワーカーが 1 つもない場合、スキャンは部分的なカバレッジを記録し、終了コード 2 を返します。

永続的なデフォルト値は ~/.codex/codex-security/config.toml に設定します。CODEX_HOME を設定している場合は、 $CODEX_HOME/codex-security/config.toml に設定します。

[deep_scan]
workers = 2
subagents = 0
stop_after_no_new = 3
max_discovery_runs = 10
max_time_hours = 1.5

コマンドラインオプションはこれらのデフォルト値を上書きします。scan --workers は、 1 回の deep スキャン内で独立して実行される standard-scan ワーカーを制御し、bulk-scan --workers は 同時に実行するリポジトリスキャンを制御します。stop_after_consecutive_errors は TOML ファイル内でのみ設定してください。デフォルトは 3 です。

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

--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 はディレクトリを再帰的に検索し、リンクされた入力パスを拒否し、 リンクされたディレクトリエントリをスキップします。また、抽出した文書の内容は 保存されるスキャン結果に含めません。

スキャン指示を追加する

スキャン指示を追加するには、テキストまたは Markdown ファイルを --scan-prompt-file で指定します。スキャンが成功した後、および カバレッジが不完全またはエラーのあるスキャンの後に、同じ認証済みセッションで追加の指示を実行するには、--post-scan-prompt-file を使用します。

npx @openai/codex-security scan . \
  --scan-prompt-file security-focus.md \
  --post-scan-prompt-file follow-up.md

たとえば、スキャンプロンプトで認可境界に焦点を当て、 追加指示でスキャンディレクトリに新しい post-scan-summary.md を書き込むよう依頼できます。 追加指示が失敗した場合、CLI は警告を報告し、完了したスキャンを保持します。 キャンセル後、またはスキャンがコスト上限に達した場合、追加指示は実行されません。

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

次のオプションを使用して、成果物の保持、以前の結果の保存、または 機械可読な結果の作成を行います。

コスト上限は推定値であり、厳密な支出上限ではありません。すでに進行中の リクエストは、上限をわずかに超えて完了することがあります。Codex Security が完了済みワーカーの結果を 集約した後に deep スキャンが上限に達した場合、CLI は利用可能な結果を封印し、 カバレッジを partial としてマークして、終了コード 2 を返します。 それ以外の場合は 2 を返し、利用可能な部分出力をディスクに残します。

--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 を記述せずに別のモデルと reasoning effort を選択するには、次のようにします。

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}]
                                [--knowledge-base PATH]
                                [--scan-prompt-file FILE]
                                [--post-scan-prompt-file FILE]
                                [--max-attempts N] [--plugin-path PATH]
                                [--python PATH] [--codex KEY=VALUE]

引数なしで npx @openai/codex-security bulk-scan を実行すると、 リポジトリを対話形式で選択できます。このフローには GitHub CLI へのサインインが必要です。

対話型の検出中にモデルと reasoning effort を選択するには、次のようにします。

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、prompt 列で 個々のリポジトリを設定できます。

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

すべてのリポジトリでセキュリティ文書を共有するには、--knowledge-base PATH を使用します。 共有のスキャン指示を追加するには、--scan-prompt-file FILE を使用します。CSV の prompt 列は、その共有プロンプトの後にリポジトリ固有の指示を追加します。 --post-scan-prompt-file FILE は、カバレッジが不完全またはエラーのあるスキャンを含め、各 スキャン後に追加指示を実行します。キャンセル後、またはスキャンがコスト上限に達した場合は 実行されません。

--workers は同時に実行するリポジトリスキャンを制限し、デフォルトは 4 です。--mode の デフォルトは standard、--max-attempts のデフォルトは 1 です。 リポジトリまたはスキャンのエラーを再試行するには、--max-attempts を設定します。カバレッジが 不完全な完了済みスキャンは再試行されません。その結果は引き続き利用でき、 コマンドは終了コード 2 を返します。

同じコマンドをもう一度実行すると、既存の出力ディレクトリから再開できます。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

以前のスキャンからの検出結果リンクを含めるには、--show-linked-findings を追加します。

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

npx @openai/codex-security scans rerun SCAN_ID

再実行には、元のスキャンに記録されたプラグインバージョンが必要です。 インストール済みのバージョンが異なる場合、別のプラグインで実行せずに コマンドは停止します。

保存済みスキャンログを調査する

スキャンとそのワーカーについて、保存された完全なセッションイベントを読み取ります。これらのログは マスキングされておらず、ソースコードや認証情報が含まれる可能性があるため、共有する前に 確認してください。

npx @openai/codex-security scans logs SCAN_ID

完全な情報を含む機械処理用の結果を取得するには、--json を追加します。

検出結果を照合して比較する

2 つのスキャンを比較し、新規、継続、再オープン、解決済み、不明の 検出結果を見つけます。

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

比較では、同じ根本原因を持つ検出結果が自動的に照合され、保存済みの照合結果が 再利用されます。照合結果を明示的に保存するには、scans match を使用します。

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

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

他のチェックアウトからのスキャンも含め、現在のリポジトリについて完了したすべてのスキャンを 照合するには、次のようにします。

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

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

codex-security findings

現在のリポジトリのスキャン全体にわたる未解決の検出結果を一覧表示します。

npx @openai/codex-security findings list

別のチェックアウトを調査するには、リポジトリパスを渡します。

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

構造化出力には --json を追加します。この一覧では、最新のスキャンで確認された検出結果と、 そのスキャンで確認されなかった以前の検出結果を識別できます。

以前の検出結果は、解決済みまたは却下済みになるまで未解決のままです（最新のスキャンに 存在しないことは、修正済みの証拠とは解釈されません）。

レビュー済みの検出結果を誤検知として記録するには、次のようにします。

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 は現在の作業ディレクトリで、SARIF を results.sarif、JSON を findings.json、CSV を findings.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 publish scan

完了したスキャンのすべての検出結果を Linear に公開します。

usage: codex-security publish scan [SCAN_DIR] --to linear
                                   [--linear-team TEAM_ID]
                                   [--project PROJECT_ID]
                                   [--linear-api-key KEY]
                                   [--linear-assignee EMAIL_OR_USER_ID]
                                   [--dry-run] [--json]

SCAN_DIR には、完了して封印されたスキャンが含まれている必要があります。対話型 ターミナルでは省略すると、ローカルのスキャン履歴から完了済みスキャンを選択できます。Issue の 作成には、スキャンとその検出結果がローカルのスキャン履歴に存在することも必要です。ドライ ランでは、この永続化の確認を行わずに封印済み成果物を検証します。

ドライラン以外の各呼び出しでは、検出結果ごとに新しい Issue の作成を試みます。 同じスキャンを再度公開しても、既存の Issue の照合、更新、再利用は行われません。 一部の検出結果で失敗した場合、コマンドは作成に成功した Issue を保持し、 終了コード 2 を返します。 --json を使用する場合は、重複を避けるため、再試行前に created と failed の 結果を確認してください。

公開前に Issue のペイロードをプレビューします。

npx @openai/codex-security publish scan /path/to/completed-scan \
  --to linear \
  --linear-team TEAM_ID \
  --dry-run \
  --json

接続済みの Linear アプリで公開する

Linear API key を使用しない場合、コマンドは既存の設定と 接続済みの Linear アプリを使用して Codex を起動します。公開前にサインインし、Linear を Codex アカウントに接続してください。

npx @openai/codex-security login
npx @openai/codex-security publish scan /path/to/completed-scan \
  --to linear \
  --linear-team TEAM_ID \
  --project PROJECT_ID

Linear API key で公開する

--linear-api-key または CODEX_SECURITY_LINEAR_API_KEY を指定すると、 Linear API を介して直接公開され、Codex は起動しません。担当者を選択しない限り、 直接公開された Issue は未割り当てになります。

export CODEX_SECURITY_LINEAR_API_KEY=YOUR_LINEAR_PERSONAL_API_KEY
npx @openai/codex-security publish scan /path/to/completed-scan \
  --to linear \
  --linear-team TEAM_ID \
  --linear-assignee teammate@example.com

コマンドラインの値は、対応する環境変数を上書きします。API key には、--linear-api-key より CODEX_SECURITY_LINEAR_API_KEY を使用してください。 コマンドライン引数はシェル履歴やプロセス一覧に表示される可能性があるためです。

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 を使用します。スキャンの比較だけでは、修正が 機能したことは証明できません。

どちらのコマンドでも reasoning effort を選択するには、--effort を使用します。

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

スキャン後に検出結果へパッチを適用する

完全なスキャン後に検出結果を修正するには、scan --patch を使用します。これには @openai/codex-security 0.1.15 以降が必要です。デフォルトの重大度しきい値は low です。このコマンドは high および critical の検出結果を選択します。

npx @openai/codex-security scan . --patch --patch-severity high --json

検証済みおよび修正済みの検出結果では、--fail-on-severity は実行されません。

保存済みの検出結果にパッチを適用する

検出結果または発生 ID を渡して元のリポジトリにパッチを適用するか、 保存済みスキャンから検出結果を選択します。

npx @openai/codex-security patch OCCURRENCE_ID
npx @openai/codex-security patch --scan SCAN_ID --severity high --json
npx @openai/codex-security patch --scan latest --severity medium

--scan latest は、現在のリポジトリで最後に完了したスキャンを選択します。 保存済み検出結果のコマンドでは --json を使用できますが、リテラルテキストとファイル入力では使用できません。

検証済みのパッチファイルだけをコミットし、GitHub CLI で pull request を 開くには、--create-pr を追加します。

npx @openai/codex-security patch --scan SCAN_ID --severity high --create-pr

push または pull request が失敗した場合は、同じリポジトリから、表示された patch --resume-pr BRANCH コマンドを実行して再試行します。

Linear の Issue にパッチを適用する

個人用 API key には CODEX_SECURITY_LINEAR_API_KEY または LINEAR_API_KEY を設定し、 OAuth トークンには LINEAR_ACCESS_TOKEN を設定します。キーをシェル履歴に残さないよう、 --linear-api-key KEY より環境変数を使用してください。

ID または URL で Issue をインポートします。複数の Issue を選択するには、--linear-issue を 繰り返し指定します。

npx @openai/codex-security patch --linear-issue SEC-123 --linear-issue SEC-124

プロジェクトの未解決 Issue を選択するには、--linear-project を使用します。選択を絞り込むには、 --linear-filter を追加します。

npx @openai/codex-security patch --linear-project "Security backlog" \
  --linear-filter '{"labels":{"name":{"eq":"security"}}}'

フィルターで state を設定しない限り、CLI は完了済みおよびキャンセル済みの Issue を除外します。 Linear の Issue 自体は変更しません。

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 でのみ利用できます。

スキャン出力を読み取る

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

対話型ターミナルには、現在のスキャンフェーズ、レビュー済みファイル、 アクティビティ、トークン使用量、推定コストを示すライブダッシュボードが表示されます。CI とリダイレクトされた 出力ではプレーンテキストの進行状況が使用されます。対話型ターミナルでプレーンテキストの進行状況を使用するには、 --headless を追加します。

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

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

詳細な診断情報

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

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

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

完了サマリー

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

  REPORT    /path/to/scan/report.md

  FINDINGS  4 (3 confirmed this scan; 1 previously found; 1 critical, 2 high, 1 informational)
  COVERAGE  complete
  ELAPSED   1s
  TOKENS    1,250 input, 200 cached, 30 output
  RESULTS   /path/to/scan

informational の検出結果もサマリーの合計に含まれます。重大度ポリシーでは、 リポジトリの合計に表示される以前の検出結果ではなく、現在のスキャンの critical、high、medium、low の 検出結果だけが評価されます。

JSON 出力

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

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

パッチ適用時には、JSON 出力にパッチの 結果と作成された pull request も含まれます。

進行状況、完了サマリー、アーカイブ通知、エラーは引き続き 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 は部分出力があればその場所を表示します。

ローカルスキャンの権限

CLI と SDK のスキャンは、ローカルオペレーティングシステムの権限で実行されます。すべてのスキャンで codex_security_scan ファイルシステムプロファイルが使用され、approvalPolicy は "never" に設定されます。このプロファイルでは、ローカルファイルシステムの読み取りと、 ワークスペースルートおよび選択したスキャン状態ディレクトリへの書き込みが許可されます。スキャンが 対話型の承認を求めるために停止することはありません。

CLI の --codex または SDK の codexOverrides を介して指定された設定（ approval_policy、sandbox_mode、ファイルシステム権限を含む）で、 これらのスキャン制御を置き換えたり制限したりすることはできません。ホストとネットワークの制限は引き続き適用されます。

スキャンおよびワークベンチのプロセスは、無関係な API トークンやクラウド認証情報を含む 環境を継承する可能性があります。信頼でき、評価する権限があるリポジトリだけを スキャンし、スキャンに必要な認証情報だけを指定してください。

認証と前提条件

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

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

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

CLI には Node.js 22（22.13.0 以降）、24、または 26 が必要です。スキャン、一括スキャン、 エクスポート、スキャン履歴、保存済みの検出結果には Python 3.10 以降も必要です。 Python 3.10 では tomli も必要です。scan、bulk-scan、または export とともに --python を使用するか、Python を使用する任意のコマンドに PYTHON を設定してください。

続いて、CLI クイックスタート、一括スキャン ガイド、CLI FAQ、CI ガイド、または TypeScript SDK ガイドを参照してください。

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

• --output FILE|-