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 serverとして登録します。

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 と Bedrock モデル ID を、scan または bulk-scan で使用します。AWS でモデルアクセスが設定されると、スキャンは AWS 認証情報を使用するため、 --auth、OpenAI へのログイン、OpenAI API key は不要です。

Daybreak Blue と Daybreak Red

Daybreak Blue と Daybreak Red には、Trusted Access for Cyber の承認が必要です。 アクセスを申請するには、エンタープライズ向けアクセス申請を提出するか、OpenAI のアカウント担当チームにお問い合わせください。 承認後、AWS のアカウント担当チームと連携して、 Amazon Bedrock でモデルアクセスを設定します。

Daybreak Red の承認には、GPT-5.6-Cyber へのアクセスは含まれません。GPT-5.6-Cyber には、 米国政府（USG）による別途の承認が必要です。Amazon Bedrock で GPT-5.6-Cyber の アクセスを設定する前に、OpenAI のアカウント担当チームに この追加承認の申請を依頼してください。Daybreak のアクセス要件をご覧ください。

利用可能かどうかは、AWS の Daybreak Blue と Daybreak Red のモデルカードで確認してください。

Daybreak Blue でスキャンするには、<aws-profile-name> を、Daybreak Blue モデルへのアクセス権を持つ AWS プロファイルに置き換えてください。

export AWS_PROFILE="<aws-profile-name>"
export AWS_REGION="us-east-2"
npx @openai/codex-security scan . \
  --provider amazon-bedrock \
  --model openai.gpt-daybreak-blue-5.6-sol --effort high

Daybreak Red でスキャンするには、GPT-5.6-Cyber へのアクセス権を持つ AWS プロファイルを選択してください。 Daybreak Blue に使用するプロファイルとは異なる場合があります。

export AWS_PROFILE="<aws-profile-name>"
export AWS_REGION="us-east-2"
npx @openai/codex-security scan . \
  --provider amazon-bedrock \
  --model openai.gpt-5.6-cyber --effort high

AWS_BEARER_TOKEN_BEDROCK または標準の AWS 認証情報チェーンを使って 認証することもできます。一時的なアクセスキーには AWS_SESSION_TOKEN が必要です。 認証情報と AWS_REGION は、スキャンを実行するシェルまたは CI ジョブ内で設定してください。

ローカルの結果とアクセスの確認

保存済みのローカルレポート、scans show、export は、クラウドの認証情報なしで利用できます。 検出結果を Codex Security Cloud にアップロードするには、別途 ChatGPT に サインインし、アップロード先へのアクセス権を持っている必要があります。

info と scan --dry-run では、AWS の認証情報やモデルへのアクセスは検証されません。 アクセスを確認するにはスキャンを実行してください。AWS の認証エラーやアクセス拒否エラーが発生した場合は、 認証情報、リージョン、モデルの権限を確認してください。

Bedrock のリリース状況

@openai/codex-security@0.1.31 は Amazon Bedrock でのスキャンに対応しています。このバージョンでは、 コストの見積もりや --max-cost は、上記の Daybreak Blue および Daybreak Red のモデル ID に対して利用できません。

インストール済みのパッケージと同梱されている Codex のバージョンを確認してください。

npx @openai/codex-security --version
npx @openai/codex-security info --json

npx @openai/codex-security scan --help を使うと、インストール済みのバージョンで利用できる オプションを確認できます。

スキャン対象を選択する

各スキャンでは対象の種類を 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

制限時間に達すると、スキャンは未完了のワーカーを停止し、完了済みのスキャン結果を保持して最終レポートに集約します。レビュー済みの領域や後回しにした作業はレポートで確認してください。期限に達したことだけでは終了コードは決まりません。実行ステータスと重大度ポリシーによって決まります。

永続的なデフォルト値は ~/.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 が完了済みワーカーの結果を集約していれば、CLI は完了した結果を確定し、予算に関する警告を表示できます。この場合は0を返し、検出事項が設定された重大度のしきい値に達していれば1を返します。有効な完了結果を生成できない場合は、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 を記述せずに別のモデルと推論エフォートを選択する場合は、 使用する認証情報でアクセスできるモデルを選んでください。ChatGPT サインインを使用する場合は、GPT-6.1 Sol の利用可否を確認してから、次の例を使用してください。

npx @openai/codex-security scan . --model gpt-6.1-sol --effort medium

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

npx @openai/codex-security scan . --codex 'model="gpt-6.1-sol"'

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 へのサインインが必要です。

対話形式での検出時にモデルと推論エフォートを選択する場合は、 使用する認証情報でアクセスできるモデルを使用してください。ChatGPT サインインでの GPT-6.1 Sol の利用可否を参照してください。

npx @openai/codex-security bulk-scan --model gpt-6.1-sol --effort medium

準備済みのリポジトリ一覧を使用する場合は、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を設定します。完了済みのスキャンは、カバレッジの不足や重大度ポリシー違反を理由に再試行されることはありません。それらの結果は引き続き利用できます。

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

パスが除外されている場合や、対応関係が不確かな場合、検出事項は「不明」になります。後のスキャンがスキャン対象のコード内でその検出事項を見つけなかった場合は、「未観測」になります。修正済みとして明示的にクローズされた検出事項だけが「解決済み」になります。--forceを matchに追加すると、既存の対応関係を再計算できます。

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

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

どちらのコマンドでも 推論エフォート を選択するには、--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 serverとして公開する場合、利用できるコマンドは 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)
  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が返される場合でも、完全な JSON 結果が出力されます。

スキャン成果物

完了したスキャンは、読みやすいレポートと構造化されたアーティファクトをまとめて保存します。確定済みのマニフェストにはアーティファクトのハッシュが記録されるため、後から読む人がそれらのファイルが変更されていないことを確認できます。

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

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

実行ステータスは、scan.status（scan-manifest.json 内）で確認できます。値は completed、 failed、canceled、または interrupted です。新しい結果には coverage.completeness は含まれません。保留中の領域、明示的な除外事項、および未解決の疑問を coverage.json で確認し、スキャンでレビューされた範囲を把握してください。

終了コードとシグナル

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

カバレッジの不足によって、完了したスキャンの終了コードが変わったり、重大度ポリシーが回避されたりすることはありません。終了コード 0 は、すべてのファイルがレビューされたことを意味しません。構造化出力を指定した場合、完了したスキャンや一部のみ完了した公開処理でも、利用可能な結果は 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 24 または 26、あるいは 22.13.0 以降の Node.js 22 が必要です。スキャン、一括スキャン、エクスポート、スキャン履歴、保存済みの検出事項には、Python 3.10 以降も必要です。 Python 3.10 では tomli も必要です。--python を scan、bulk-scan、または export と併用するか、Python を使用するコマンドに対して PYTHON を設定してください。

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

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

• --output FILE|-