codex-security のコマンド、フラグ、出力形式、終了時の動作を確認できます。初めてスキャンを実行する場合は、CLI クイックスタートに従ってください。
スキャンはユーザーのローカル権限で実行され、承認待ちで一時停止することはありません。一部のサイバーセキュリティ関連のリクエストや保護対象の検出結果へのアクセスには、
Trusted Access for Cyber
が必要です。ローカルスキャンの権限を参照してください。
CLI は npx @openai/codex-security で実行します。インストールしたパッケージでは cs エイリアスも使えます。
コマンド一覧
usage: codex-security [--version] <command> [options]CLI には次のコマンドがあります。
| コマンド | 用途 |
|---|---|
codex-security scan |
Codex Security スキャンを実行します。 |
codex-security scan import |
CSV または JSON の検出結果をスキャンとして保存します。 |
codex-security import github |
GitHub のコードスキャンアラートを読み込みます。 |
codex-security policy |
リポジトリのセキュリティポリシーを起草または更新します。 |
codex-security init |
YAML または JSON 形式のプロジェクト設定を作成します。 |
codex-security install-hook |
Git のコミット前にセキュリティスキャンを実行するフックをインストールします。 |
codex-security bulk-scan |
リポジトリを検索し、再開可能な一括スキャンを実行します。 |
codex-security scan-components |
プロジェクトのコンポーネントごとにスキャンを実行します。 |
codex-security scans |
保存済みスキャンの一覧表示、詳細の確認、比較、ログの取得を行います。 |
codex-security findings |
保存済みのセキュリティ検出結果をレビューし、更新します。 |
codex-security export |
検出結果または保存済みの脅威モデルをエクスポートします。 |
codex-security publish |
保存済みのスキャンを確認または公開したり、外部の検出結果をインポートしたりします。 |
codex-security classify-severity |
保存済みの検出結果に重大度の評価基準を適用します。 |
codex-security suggest-owners |
CODEOWNERS と Git の履歴に基づいて検出結果の担当者を提案します。 |
codex-security dedupe |
保存済みの検出結果の重複を排除します。 |
codex-security validate |
1 件以上のセキュリティ上の問題の候補を検証します。 |
codex-security patch |
1 件以上のセキュリティ上の問題を修正します。 |
codex-security verify-fix |
報告された問題が修正済みかどうかを確認します。 |
codex-security feedback |
OpenAI にフィードバックを送信し、フィードバック ID を返します。 |
codex-security login |
サインイン、認証情報の保存、サインイン状態の確認を行います。 |
codex-security logout |
保存されたサインイン情報を削除します。 |
codex-security info |
SDK と同梱プラグインの読み取り専用メタデータを表示します。 |
CLI には次の連携用コマンドもあります。
| コマンド | 用途 |
|---|---|
codex-security completions |
シェルの補完スクリプトを生成します。 |
codex-security mcp |
CLI を MCP サーバーとして登録します。 |
codex-security skills |
Codex Security のスキルをエージェントに同期します。 |
利用可能なすべてのコマンドを表示するには、次を実行します。
npx @openai/codex-security --help各コマンドの引数とオプションを確認するには、--help を追加します。
npx @openai/codex-security scan --helpcodex-security --version はインストール済みのバージョンを表示して終了します。codex-security info --json は SDK と同梱プラグインのバージョンを表示します。どちらのコマンドも Python は不要です。インストール済みの CLI を更新するには codex-security --update を使います。
コマンドの確認とエージェントの接続
エージェントが読み取れるコマンドマニフェストを出力します。
npx @openai/codex-security --llmsスキャン引数のスキーマを JSON で確認します。
npx @openai/codex-security scan --schema --format jsonBash 用のシェル補完スクリプトを生成します。
npx @openai/codex-security completions bashほかのシェルを使う場合は、bash を zsh または fish に置き換えます。
スキャン結果の出力には --format toon|json|yaml|jsonl と --full-output を使えます。--export-format は、完了したスキャンからエクスポートする成果物の形式を指定します。CLI 全体のヘルプには md も表示されますが、スキャン結果の Markdown 出力には対応していません。
CLI を MCP サーバーとして登録します。
npx @openai/codex-security mcp addCodex Security のスキルをエージェントに同期します。
npx @openai/codex-security skills addCLI が MCP サーバー経由で提供するのは、メタデータを表示する読み取り専用の info コマンドだけです。スキャン、エクスポート、公開、認証、検証、修正は CLI からのみ実行できます。
codex-security scan
リポジトリ、指定したパス、コミット済みの変更、または作業ツリーをスキャンします。
usage: codex-security scan [-h] [--auth {auto,chatgpt,api-key}]
[--config FILE]
[--cyber-access-program PROGRAM]
[--provider {openai,openrouter,fireworks,amazon-bedrock}]
[--path PATH | --diff BASE | --working-tree]
[--head HEAD] [--base BASE]
[--knowledge-base PATH] [--scan-prompt-file FILE]
[--validation-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 MINUTES]
[--model MODEL]
[--effort EFFORT]
[--output-dir DIR]
[--archive-existing]
[--plugin-path PATH] [--python PATH]
[--codex KEY=VALUE] [--fail-on-severity LEVEL]
[--validate] [--patch] [--patch-severity {critical,high,medium,low}]
[--create-pr]
[--max-cost USD] [--show-cost] [--dry-run] [--mock]
[--workflow-id ID] [--safety-identifier ID]
[--headless] [--verbose]
[--json] [--format {toon,json,yaml,jsonl}]
[--full-output] [repository]repository のデフォルトはカレントディレクトリです。
プロジェクト設定の読み込み
初期設定ファイルを作成し、スキャン時に明示的に指定します。
npx @openai/codex-security init codex-security.yaml
npx @openai/codex-security scan . --config codex-security.yamlinit は既存のファイルを上書きしません。-c FILE は --config FILE の短縮形です。環境変数 CODEX_SECURITY_PROJECT_CONFIG でも指定できます。明示的に指定したフラグは環境変数より優先されます。CLI はプロジェクト設定ファイルを自動で検索しません。
自分で管理する設定だけを選んでください。設定ファイルには CLI オプションと同じ権限があり、Codex のネイティブ設定で MCP サーバーのプロセスを起動したり、モデルサービスの接続先を指定したりできます。信頼できないリポジトリや pull request の作成者が変更できるファイルを選ばないでください。CI では、評価対象のチェックアウトの外にスキャナーの設定を置きます。設定項目と優先順位については、プロジェクト設定ガイドを参照してください。
スキャンの認証方式の選択
デフォルトの --auth auto を使うと、認証情報が自動的に選択されます。ChatGPT のサインイン情報に加え、OPENAI_API_KEY または CODEX_API_KEY も利用できる場合、テキスト出力の対話型スキャンでは使用する認証情報を尋ねられます。CI、JSON または JSONL 出力のスキャン、その他の対話型ターミナルを使わないスキャンでは、環境変数の API キーを使います。ドライランでは認証情報の選択を求められることはなく、認証情報も読み込まれません。
保存済みの認証情報を使うには、--auth chatgpt を指定します。
npx @openai/codex-security scan . --auth chatgpt環境変数の API キーを使うには、--auth api-key を指定します。
npx @openai/codex-security scan . --auth api-key保存済みの認証情報がデフォルトで自動選択されるようにするには、unset OPENAI_API_KEY CODEX_API_KEY を実行します。
--auth api-key と --cyber-access-program standard|daybreak_blue|daybreak_red を併用すると、OpenAI モデルへのリクエストに使う Cyber アクセスプログラムを選択できます。プログラムを省略すると Codex のデフォルトが適用され、standard を指定すると標準プログラムが明示的に選択されます。プログラムの選択だけではアクセス権は付与されません。利用する API プロジェクトがそのプログラムの承認を受けている必要があります。認証情報の要件は、アクセスプログラムガイドを参照してください。
スキャンとエンドユーザーの関連付け
ユーザーに代わってスキャンする場合、API キー認証では --safety-identifier ID にハッシュ化した固定の識別子を指定できます。長さは 1～64 文字とし、NUL 文字や、メールアドレスなどの個人情報は含めないでください。
識別子を転送するには、CODEX_CLI_PATH でこのオプションに対応する Codex ビルドを選び、識別子をワーカーに渡すプラグインを使います。同梱の Codex ランタイムはこのオプションに対応していません。
OpenRouter または Fireworks の利用
OpenRouter を使うには、API キーを設定し、モデルを明示的に指定します。
export OPENROUTER_API_KEY="your-openrouter-api-key"
npx @openai/codex-security scan . \
--provider openrouter \
--model anthropic/claude-sonnet-4.5Fireworks を使うには、API キーを設定し、モデルを明示的に指定します。
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 キーは不要です。
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 のアクセス要件を参照してください。
| アクセスプログラム | Bedrock モデル ID | AWS リージョン |
|---|---|---|
| Daybreak Blue | openai.gpt-daybreak-blue-5.6-sol |
us-east-2 |
| Daybreak Red | openai.gpt-5.6-cyber |
us-east-2 |
提供状況は、Daybreak Blue と Daybreak Red の AWS モデルカードで確認してください。
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 highDaybreak 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 highAWS_BEARER_TOKEN_BEDROCK または標準の AWS 認証情報チェーンでも認証できます。一時アクセスキーを使う場合は AWS_SESSION_TOKEN が必要です。認証情報と AWS_REGION は、スキャンを実行するシェルまたは CI ジョブ内で設定します。
ローカルの結果とアクセスの確認
ローカルに保存したレポート、scans show、export はクラウドの認証情報がなくても利用できます。
info と scan --dry-run は AWS の認証情報やモデルへのアクセスをテストしません。アクセスを確認するには、スキャンを実行してください。AWS の認証エラーやアクセス拒否エラーが発生した場合は、認証情報、リージョン、モデルのアクセス権を確認してください。
Bedrock のコスト見積もり
上記の Daybreak Blue と Daybreak Red のモデル ID では、CLI によるコスト見積もりと --max-cost を利用できます。見積もりには、AWS の手数料を含む AWS Standard の商用リージョン内料金を使います。コスト上限の判定には、短いコンテキストを基準とする estimatedUsd を使います。処理中のリクエストによって見積額が上限を超える場合があります。長いコンテキストに対する料金が適用されると、報告される estimatedUsdRange が上限を超えることもあります。この上限は請求額を制限するものではありません。
スキャン対象の選択
スキャンごとに対象の種類を 1 つ選択します。
| 引数 | 説明 |
|---|---|
--path PATH |
リポジトリからの相対パスをスキャンします。複数のパスを指定するにはフラグを繰り返します。 |
--diff BASE |
BASE から --head までのコミット済みの変更をスキャンします。比較先のデフォルトは HEAD です。 |
--head HEAD |
--diff の比較先リビジョンを指定します。 |
--working-tree |
--base を基準に、ステージ済みおよび未ステージの変更をスキャンします。基準のデフォルトは HEAD です。 |
--base BASE |
--working-tree の基準リビジョンを指定します。 |
--mode {standard,deep} |
スキャンモードを選択します。デフォルトは standard です。 |
--path、--diff、--working-tree は併用できません。--head には --diff が、--base には --working-tree が必要です。詳細モードでは、リポジトリまたはパスを対象にできます。
差分スキャンと作業ツリーのスキャンでは、リポジトリ引数に Git Worktree のルートを指定する必要があります。指定した参照は、そのチェックアウトに存在している必要があります。
リポジトリ全体をスキャンします。
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詳細スキャンの設定
--mode deep では次のオプションで問題の探索を制御できます。
| 引数 | 説明 |
|---|---|
--workers N |
独立した標準スキャンを同時に実行できるワーカー数の上限です。デフォルトは 4 です。 |
--subagents N |
各ワーカーが使えるサブエージェント数です。デフォルトは 3 です。0 を指定すると無効になります。 |
--stop-after-no-new N |
完了したワーカーのスキャンで N 回連続して新しい問題が見つからなければ探索を終了します。デフォルトは 4 です。 |
--max-discovery-runs N |
独立した標準スキャンの合計実行回数の上限です。デフォルトは 40 です。 |
--max-time MINUTES |
探索の制限時間です。分単位で正の小数も指定できます。デフォルトと最大値はいずれも 5,760 分です。 |
次の例ではワーカーを 2 つ使い、実行回数を最大 10 回、探索時間を最大 90 分に制限します。
npx @openai/codex-security scan . \
--mode deep \
--workers 2 \
--subagents 0 \
--stop-after-no-new 3 \
--max-discovery-runs 10 \
--max-time 90制限時間に達すると、スキャンは実行中のワーカーを停止し、完了済みのワーカーの検出結果をレポートにまとめます。標準スキャンでは、--max-time は調査時間の目安です。レポート作成はその後に完了する場合があります。カスタム検証とスキャン後の指示の実行時間は、この時間に含まれません。
これらの上限を再利用するには、プロジェクト設定ファイルに保存します。
scan:
mode: deep
max_time_minutes: 90
deep:
workers: 2
subagents_per_worker: 0
stop_after_no_new: 3
max_discovery_runs: 10コマンドラインオプションはプロジェクト設定より優先されます。scan.deep.stop_after_consecutive_errors では、ワーカーエラーが何回連続すると探索を終了するかを変更できます。デフォルトは 3 です。bulk-scan では、--workers で同時にスキャンするリポジトリ数を制御します。
セキュリティコンテキストの追加
--knowledge-base PATH でアーキテクチャ文書、脅威モデル、セキュリティポリシーを指定できます。複数のファイルやディレクトリを指定するには、オプションを繰り返します。
npx @openai/codex-security scan . \
--knowledge-base /path/to/architecture.md \
--knowledge-base /path/to/security-policies対応形式は UTF-8 のテキストファイル（JSON、SARIF を含む）、PDF、DOCX です。CLI はディレクトリを再帰的に検索します。リンクを含む入力パスは拒否し、ディレクトリ内のリンクはスキップします。スキャンを再開できるように、抽出した文書をスキャン成果物と同じ場所にある非公開の再開用ファイル .scan-knowledge.json に保存します。このファイルはスキャンディレクトリと一緒に保管してください。正式なレポートに文書の本文は含まれません。
スキャン指示の追加
スキャンに指示を追加するには、テキストまたは 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 は警告を表示し、完了したスキャンは保持します。キャンセルされた場合やスキャンがコスト上限に達した場合は、追加の指示を実行しません。追加の指示を実行する際のコストは、スキャンのコスト追跡と --max-cost の対象外です。
独自の環境での検出結果の検証
--validation-prompt-file FILE を使うと、最後の検証ステップを独自のテスト手順に置き換えられます。Codex は最初にソースをレビューし、問題の候補がなければ検証をスキップします。プロンプトとテストスクリプトは、チェックアウトの外にある自分で管理するディレクトリに置いてください。
npx @openai/codex-security scan . \
--validation-prompt-file /path/to/security-tests/validation.mdたとえば、ローカルのテストサーバーが稼働している場合は、次の指示を validation.md に記述します。
Run /path/to/security-tests/validate.sh against http://localhost:3000.
Report which findings reproduce and include the relevant test output.このフラグはリポジトリ、パス、差分、作業ツリーを対象にした標準スキャンで使用できます。コンポーネントの標準スキャンでは、scan.validation_file をプロジェクト設定で指定します。詳細スキャンではカスタム検証は指定できません。
新しいスキャンのコマンドに --validate を追加すると、報告された各検出結果について、ソースだけに基づく評価を別途実行します。検出結果がある場合、CLI は評価をスキャンディレクトリ内のレポートに書き込みます。評価によって検出結果や重大度ポリシーの判定は変わりません。--validate は --dry-run、--mock、またはコマンドラインやプロジェクト設定で指定したスキャンのコスト上限と併用できません。
出力とポリシーのオプション
次のオプションを使うと、成果物の保存、以前の結果の保管、機械可読な結果の出力ができます。
| 引数 | 説明 |
|---|---|
--output-dir DIR |
スキャン成果物を、対象を含む Git Worktree の外にある非公開ディレクトリに書き込みます。デフォルトは Codex Security の永続データの保存先です。 |
--archive-existing |
既存の結果を DIR.previous-<timestamp>-<id> に移動し、空の出力ディレクトリで開始します。--output-dir が必要です。 |
--fail-on-severity LEVEL |
完了したスキャンで指定した重大度以上の問題が検出された場合、終了コード 1 を返します。指定できる重大度は critical、high、medium、low です。 |
--patch |
スキャン完了後、選択した検出結果を修正し、修正内容を検証します。 |
--patch-severity LEVEL |
指定した重大度以上の検出結果を修正します。指定できる重大度は critical、high、medium、low で、デフォルトは low です。 |
--create-pr |
検証済みの修正ファイルをコミットし、GitHub のドラフト pull request または GitLab のドラフトマージリクエストを作成します。--patch が必要です。 |
--max-cost USD |
モデルの推定コストが指定額（米ドル）を超えるとスキャンを停止します。 |
--show-cost |
進捗と完了時の出力に推定コストを表示します。 |
--mock |
モデルを呼び出さずに、標準スキャンの模擬検出結果を保存します。 |
--workflow-id ID |
指定したローカルの検出結果ワークフローで完了済みの処理を再利用します。 |
--dry-run |
スキャンを開始せずに、リポジトリ、対象、ナレッジベース、出力ディレクトリ、Codex の設定を確認します。 |
--headless |
対話型のスキャンダッシュボードに代えて、進捗をプレーンテキストで表示します。 |
--verbose |
ライフサイクル、認証、進捗、コストに関する追加の診断情報を標準エラー出力に書き込みます。 |
--json |
マニフェスト、検出結果、レビューの除外対象、パス、ターンのメタデータを 1 つの JSON 文書として出力します。 |
--format FORMAT |
スキャン結果全体を toon、json、yaml、jsonl のいずれかで出力します。 |
--full-output |
デフォルトの構造化出力形式で結果全体を出力します。 |
モックモードはリポジトリ、パス、差分を対象とする標準スキャンに対応しています。--dry-run、--patch、詳細モード、カスタム検証、スキャン後のプロンプトとは併用できません。スキャン用プロンプトやナレッジベースは模擬検出結果に影響しません。模擬結果が通常のスキャン履歴に混在しないように、別の CODEX_SECURITY_STATE_DIR を指定してください。
コスト上限の判定には、短いコンテキストを基準とする estimatedUsd を使います。処理中のリクエストによって見積額が上限を超える場合があります。長いコンテキストに対する料金が適用されると、estimatedUsdRange が上限を超えることもあります。この上限は請求額を制限するものではありません。
詳細スキャンで Codex Security が完了済みのワーカーの結果を集約した後にコスト上限に達した場合、CLI はスキャン結果を完了済みとして確定し、予算に関する警告を表示することがあります。その場合の終了コードは 0 ですが、検出結果が設定した重大度のしきい値に達していれば 1 になります。有効な完了結果を生成できない場合は 2 を返し、得られた出力をディスクに残します。
--output-dir を省略すると、結果は $CODEX_HOME/state/plugins/codex-security/scans/<repository> 以下に永続保存されます。CODEX_HOME のデフォルトは ~/.codex です。CODEX_SECURITY_STATE_DIR を設定すると、保存先を $CODEX_SECURITY_STATE_DIR/scans/<repository> 以下に変更できます。これらのディレクトリにはソースコードの抜粋や脆弱性の詳細が含まれる場合があるため、アクセス権と保存期間を適切に管理してください。
ワークベンチはスキャン履歴を $CODEX_HOME/state/plugins/codex-security/workbench.sqlite3 に保存します。CODEX_SECURITY_STATE_DIR を設定すると、ワークベンチのデータベースの保存先も変わります。
出力ディレクトリは、スキャン対象のディレクトリと、それを含むすべての Git Worktree の外に置く必要があります。--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 の設定値を指定できます。
| 引数 | 説明 |
|---|---|
--auth {auto,chatgpt,api-key} |
スキャンに使用する認証情報を選択します。デフォルトは auto です。 |
--provider {openai,openrouter,fireworks,amazon-bedrock} |
推論プロバイダーを選択します。デフォルトは openai です。 |
--model MODEL |
モデルを選択します。デフォルトは gpt-5.6-sol です。OpenRouter、Fireworks、Amazon Bedrock では指定が必須です。 |
--effort EFFORT |
モデルの推論強度を選択します。デフォルトは xhigh です。指定できる値はモデルとプロバイダーによって異なります。 |
--plugin-path PATH |
同梱のプラグインの代わりに、指定した Codex Security プラグインのディレクトリまたは ZIP を使います。 |
--python PATH |
プラグインのランタイムに使う Python インタープリターを選択します。 |
--codex KEY=VALUE |
スキャン専用に分離された Codex の設定値を上書きします。値は TOML 構文で指定します。複数の値を指定するにはフラグを繰り返します。 |
Codex Security はモデル ID と推論強度の値を文字列として受け取ります。利用できる組み合わせは、モデル、プロバイダー、Codex のバージョン、認証情報によって異なります。
スキャン専用の Codex 設定でプロファイルを選択している場合、そのプロファイルの model と model_reasoning_effort の値が --model と --effort より優先されます。通常の Codex 設定は読み込まれません。スキャンを始める前に実際に適用されるモデルと推論強度を確認するには、スキャンコマンドに --dry-run --verbose を追加します。
モデルと推論強度を指定するには、自分のアカウントで利用できる Codex モデルを選びます。
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 に渡されます。未対応の組み合わせを指定した場合は、別のモデルや推論強度に切り替えず、Codex またはプロバイダーのエラーを返します。
codex-security scan import
セキュリティ分析やモデル呼び出しを行わずに、既存の検出結果を完了済みのスキャンとしてローカル履歴に保存します。インポートにモデルの認証は不要です。
usage: codex-security scan import (--csv FILE | --json FILE)
[--output-dir DIR] [--archive-existing]
[--dry-run] [--format json]入力は必ず 1 つだけ指定します。CSV には Codex Security のエクスポートと同じ列を使います。JSON では、完全な codex-security.findings 文書か、検出結果のスキーマに合致する findings 配列を含むオブジェクトを指定できます。任意のスキャナーの JSON や GitHub アラートの未加工の配列を、そのまま検出結果として保存することはできません。
次の模擬データを findings.csv として保存します。
occurrence_id,finding_id,title,summary,severity,confidence,status,close_reason,note,remediation,path,start_line,end_line
occ_000000000000000000000001,csf_000000000000000000000001,Missing authorization check,The route reads a record without checking ownership,high,high,open,,,Check record ownership before returning data,src/routes.ts,18,18ファイルを検証してからインポートします。
npx @openai/codex-security scan import --csv findings.csv --dry-run --format json
npx @openai/codex-security scan import --csv findings.csv --format jsonドライランではスキャンを保存せずに dryRun: true と findingCount: 1 を返します。インポートを実行すると、保存したスキャンの ID と結果のパスが返されます。JSON をインポートする場合は次のように指定します。
npx @openai/codex-security scan import --json findings.json --format jsonこのコマンドでは、--json FILE で入力ファイルを指定します。JSON 形式で出力するには --format json を使います。
| オプション | 動作 |
|---|---|
--csv FILE |
Codex Security の CSV エクスポート形式の検出結果を読み込みます。 |
--json FILE |
検出結果の文書または findings 配列を持つオブジェクトを読み込みます。 |
--dry-run |
スキャンを保存せずに入力を検証します。 |
--output-dir DIR |
成果物のディレクトリを指定します。デフォルトは Codex Security の永続データの保存先です。 |
--archive-existing |
インポート前に既存の結果をアーカイブします。--output-dir が必要です。 |
入力には、パスにシンボリックリンクやディレクトリジャンクションを含まない通常のファイルを使ってください。インポートでは、重複を含めて個々の検出記録を保持し、入力を artifacts/import/ 以下に保存します。元の識別子は extensions.import に保存されます。完了ステータスが示すのはインポートの完了であり、ソースのレビューが済んでいることではありません。scans rerun SCAN_ID を実行すると、保存された入力を再度インポートします。
import という名前のリポジトリをスキャンするには、scan ./import を使います。
codex-security import github
GitHub に変更を加えたりコードをチェックアウトしたりせずに、GitHub のコードスキャンアラートを読み込みます。
npx @openai/codex-security import github example/repository --format json > /path/outside/repository/alerts.json
npx @openai/codex-security import github example/repository \
--github-alert 12 --github-alert 18 --format jsonexample/repository を自分のリポジトリに置き換えます。コードスキャンの読み取り権限を持つ GitHub CLI の認証情報で認証してください。デフォルトでは、サードパーティーからアップロードされた SARIF に由来するものを含め、デフォルトブランチの未解決アラートを読み込みます。
| オプション | 動作 |
|---|---|
--github-alert NUMBER |
状態にかかわらず、番号でアラートを指定します。複数のアラートを指定するには繰り返します。 |
--github-ref REF |
デフォルトブランチの代わりに Git の参照を指定します。 |
--github-state STATE |
open、closed、dismissed、fixed、all のいずれかを指定してアラートを一覧表示します。デフォルトは open です。 |
アラート番号を指定する場合、open 以外の状態と併用しないでください。コマンドが返すのは GitHub から取得したアラートの配列であり、スキャンとしては保存されません。評価するには、対応するローカルリポジトリで codex-security validate /path/outside/repository/alerts.json を実行します。検証用の入力を保存する際は、出力フィルターやトークン数の制限を使わず、JSON 全体を保存してください。すでに Codex Security のスキーマに従っている検出結果には scan import を使います。Dependabot アラートをインポートするには、publish findings を使います。
codex-security install-hook
リポジトリの外に CLI をインストールし、リポジトリの既存の pre-commit フックを確認してから、チェックアウトの外でインストール済みの CLI を実行します。
git -C /path/to/repository rev-parse --git-path hooks/pre-commit
codex-security install-hook /path/to/repositoryフックは各コミットの前にステージ済みおよび未ステージの変更をスキャンし、重大度が「高」または「重大」の問題を検出した場合やスキャンエラーが発生した場合にコミットをブロックします。ローカルフックの使用は任意です。チェックを強制するには CI の必須チェックを使ってください。カスタムフック、リンクされたフック、共有フック、およびそれらのフックディレクトリの管理は所有者に任せてください。インストーラーは無関係な pre-commit スクリプトを置き換えません。必要に応じて、重大度のしきい値を変更できます。
codex-security install-hook /path/to/repository --fail-on-severity mediumcodex-security policy
プロジェクトのセキュリティ境界と、何を問題として報告すべきかを定める SECURITY.md ポリシーの草案を作成します。
npx @openai/codex-security policy .
npx @openai/codex-security policy . --headless --jsonこのコマンドは草案をリポジトリの外に保存し、既存のファイルには変更を加えません。草案、差分、レビューメモを確認し、レビュー済みの SECURITY.md だけを表示されたポリシーの配置先にコピーしてください。ヘッドレスモードでは、未回答の質問はレビューメモに残ります。ポリシーの生成は任意です。既存のポリシーを使ってスキャンすることも、ポリシーなしでスキャンすることもできます。対象パスの範囲とオプションについては、ポリシーガイドを参照してください。
codex-security scan-components
scan-components を使うと、1 つのリポジトリ内のサービスやパッケージを個別にスキャンできます。計画だけを生成する場合も含め、実行ごとに、対象を含む Git Worktree の外に新規または空の出力ディレクトリが必要です。--output-dir またはプロジェクト設定の output.directory で指定します。
次の例では 2 つのサービスを並列にスキャンします。
npx @openai/codex-security scan-components . \
--component apps/api --component apps/web \
--output-dir /path/outside/repository/manual-componentsscan --path と異なり、このコマンドはコンポーネントごとにスキャンを実行し、その後、検出結果を集約して照合します。デフォルトでは最大 4 つのコンポーネントを同時にスキャンできます。この上限は --workers N で変更できます。--max-cost USD はコンポーネントごとのスキャンコストを制限します。自動計画とコンポーネント間の照合のコストは対象外です。
Codex に分割案を作成させるには、スキャンの前にレビュー用の計画を保存します。
npx @openai/codex-security scan-components . --auto --plan-only \
--output-dir /path/outside/repository/component-plancomponents.json のコンポーネント名とパスを確認してから、新しい出力ディレクトリを指定して保存済みの計画を実行します。
npx @openai/codex-security scan-components . \
--components-file /path/outside/repository/component-plan/components.json \
--output-dir /path/outside/repository/components出力ディレクトリの report.md を開き、集約された検出結果を確認します。一部のコンポーネントで失敗した場合は、保存された再試行計画を使って失敗したコンポーネントだけを再実行できます。
npx @openai/codex-security scan-components . \
--components-file /path/outside/repository/components/retry-components.json \
--output-dir /path/outside/repository/retry-results再試行のレポートには、再試行したコンポーネントだけが含まれます。初回に完了したコンポーネントの検出結果を確認できるように、元のレポートも保管してください。
スキャンまたは照合に失敗すると 2 を返します。重大度ポリシーに違反した場合は 1 を返します。計画の構文と再試行の詳細は、コンポーネントスキャンガイドを参照してください。
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 EFFORT]
[--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 へのサインインが必要です。
対話形式で検索する場合は、自分のアカウントで利用できる Codex モデルを選びます。
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 4CSV には 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、スキャンが完了して重大度ポリシーに違反した場合は 1 を返します。
同じコマンドを再実行すると、既存の出力ディレクトリを使って再開します。CLI は完了済みのスキャンをスキップします。条件が一致するキャンペーンで失敗または中断した処理を再試行するには、--recover を使います。
コンテナでのキャンペーンについては、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再実行すると、保存された設定と認証方式、現在のチェックアウト、現在のコンテキストファイルを使って新しいスキャンを作成します。プロジェクト設定ファイルの再読み込みや、保存済みの認証情報の再利用は行いません。元のスキャンでスキャン用またはカスタム検証用のプロンプトを使った場合は、--scan-prompt-file と --validation-prompt-file で該当するファイルを再度指定してください。
再実行には元のスキャンに記録されたバージョンのプラグインが必要です。インストール済みのバージョンが異なる場合は停止します。
保存済みスキャンログの確認
スキャンとそのワーカーについて、保存されたセッションイベントをすべて読み取れます。ログにはマスキングが施されておらず、ソースコードや認証情報が含まれる可能性があるため、共有前に内容を確認してください。
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
Codex の起動や認証情報の読み込みを行わずに、保存済みの検出結果または脅威モデルをエクスポートします。検出結果を CSV、JSON、SARIF、ServiceNow AVIT 用 CSV としてエクスポートできるのは、完了して成果物が確定したスキャンだけです。脅威モデルの形式は Markdown です。
usage: codex-security export [scan_dir | --scan SCAN_ID]
[--artifact {findings,threat-model}]
[--export-format {csv,json,sarif,md,servicenow-avit}]
[--avit-template FILE]
[--output FILE|-] [--source-root PATH]
[--python PATH]scan_dir と --scan を省略すると、現在のリポジトリで最後に完了したスキャンを使います。それ以外の場合は、保存済みの結果ディレクトリを指定するか、ID または 8 文字以上の一意の先頭文字列を --scan に指定します。この 2 つの指定方法は併用できません。
| 引数 | 説明 |
|---|---|
--artifact {findings,threat-model} |
保存済みの成果物を選択します。デフォルトは findings です。 |
--scan SCAN_ID |
ID、8 文字以上の一意の先頭文字列、または latest で保存済みのスキャンを選択します。 |
--export-format FORMAT |
csv、json、sarif、md、servicenow-avit から選択します。検出結果のデフォルトは sarif です。脅威モデルは md にのみ対応しています。 |
--avit-template FILE |
servicenow-avit に必須の CSV テンプレートを指定します。この形式でのみ指定できます。 |
--output FILE|- |
選択した形式でファイルまたは標準出力に書き込みます。デフォルトはカレントディレクトリ内のファイルです。 |
--source-root PATH |
リポジトリのチェックアウトを使って、ソース行のフィンガープリントを SARIF に追加します。 |
--python PATH |
同梱のエクスポーターが使う Python インタープリターを選択します。 |
--source-root は検出結果を SARIF でエクスポートする場合にのみ使用できます。JSON では確定済みの検出結果文書をそのまま保持します。CSV にはほかの環境でも使える検出結果の列が含まれますが、ローカルのワークベンチでのトリアージ状態は含まれません。
--output を省略すると、CLI はカレントディレクトリに、SARIF を results.sarif、JSON を findings.json、CSV を findings.csv、ServiceNow AVIT 用 CSV を servicenow-avit.csv、Markdown を threatmodel.md として書き込みます。エクスポートにはソースコードの抜粋や脆弱性の詳細が含まれる場合があります。--output にはチェックアウトの外にある非公開のパスを指定してください。リポジトリの外で実行する場合は、結果ディレクトリまたは --scan も指定します。
検出結果のエクスポート
SARIF をファイルに書き込みます。
npx @openai/codex-security export /path/to/scan \
--export-format sarif \
--source-root /path/to/repository \
--output /path/outside/repository/exports/results.sarifSARIF を標準出力に書き込みます。
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.csvServiceNow 向けの検出結果のエクスポート
ServiceNow では Ethical Hacker ロール（sn_vul.app_pen_tester）が必要です。All > Manual AVIT Ingestion > Upload File UI を開き、CSV テンプレートをダウンロードします。元のヘッダーを保持し、データ行は必ず 1 行だけにします。ServiceNow に登録されている正確なアプリケーション名を使ってください。目的、機密データの種類、コンプライアンスプログラム、技術スタック、アプリケーション担当チーム、テスト対象の URL を入力します。Requested by、Assigned to、Assignment group を設定し、検出結果のフィールドは空欄にします。スキャン対象のリポジトリの外にある非公開ディレクトリに、テンプレートを app.csv として保存してください。同じアプリケーションのスキャンではこのテンプレートを再利用できます。
スキャン対象のリポジトリで、このテンプレートを使って最新の検出結果をエクスポートします。出力も非公開ディレクトリに保存してください。
npx @openai/codex-security export --scan latest \
--export-format servicenow-avit \
--avit-template /path/outside/repository/exports/app.csv \
--output /path/outside/repository/exports/findings-avit.csvCLI は検出結果ごとに 1 行を書き込み、攻撃経路が記録されていれば、その情報から Steps to reproduce を入力します。手順を確認し、エクスポートした CSV の空欄を埋めてください。Upload File UI に戻り、Import File を選択して CSV をアップロードし、Submit を選択します。アップロードするたびに、そのアプリケーションのペネトレーションテストフォームが新規作成されます。ServiceNow のアップロード手順を参照してください。
保存済みの脅威モデルのエクスポート
モデルを再度呼び出さずに、最後に完了したスキャンの保存済み脅威モデルを標準出力に書き込みます。
npx @openai/codex-security export --artifact threat-model --output -スキャンを選択し、その脅威モデルをファイルに保存することもできます。
npx @openai/codex-security export --scan SCAN_ID \
--artifact threat-model \
--output /path/outside/repository/exports/threatmodel.mdID またはディレクトリでスキャンを選択すると、未完了または失敗したスキャンからも保存済みのモデルをエクスポートできます。モデルが保存されていない場合、コマンドはエラーを返します。文書内で暫定または復元済みと示されている内容は、再利用する前に確認してください。
エクスポートしたモデルを別のスキャンのコンテキストとして使うには、そのパスを --knowledge-base に渡します。
codex-security publish scan
完了済みのスキャンから選んだ検出結果を、Linear またはカスタムの検出結果サービスに公開します。以下は 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 には、完了して成果物が確定したスキャンが必要です。対話型ターミナルでは、省略するとローカルのスキャン履歴から完了済みのスキャンを選択できます。課題を作成するには、スキャンとその検出結果がローカル履歴にも存在する必要があります。ドライランでは、履歴への保存状況を確認せずに確定済みの成果物を検証します。
ディレクトリの代わりに --scan SCAN_ID または --scan latest で保存済みのスキャンを選択できます。Linear に公開する検出結果を絞り込むには、--finding-id ID を繰り返し指定します。publish check SCAN_DIR に Linear の公開先オプションを指定すると、成果物と記録済みの公開状況を確認できます。API キーを指定した場合は、認証と公開先へのアクセスも確認します。接続済みアプリによるアクセスは not-checked と表示されます。
| 引数 | 説明 |
|---|---|
--to linear |
Linear に公開します。この引数は必須です。 |
--linear-team TEAM_ID |
Linear チームを指定します。省略すると CODEX_SECURITY_LINEAR_TEAM を使います。どちらかの指定が必要です。 |
--project PROJECT_ID |
Linear プロジェクトを指定します。省略すると CODEX_SECURITY_LINEAR_PROJECT を使います。どちらも指定しない場合はチームに直接課題を作成します。 |
--linear-api-key KEY |
Linear の個人 API キーを使って直接公開します。省略すると CODEX_SECURITY_LINEAR_API_KEY を使います。 |
--linear-assignee EMAIL_OR_USER_ID |
メールアドレスまたは Linear ユーザー ID で、作成する課題の担当者を指定します。--linear-api-key または CODEX_SECURITY_LINEAR_API_KEY が必要です。省略すると担当者は未割り当てになります。 |
--dry-run |
Codex の起動、Linear への接続、課題の作成、公開状態の書き込みを行わず、課題のペイロードを準備します。 |
--skip-existing |
同じ検出記録、Linear チーム、プロジェクトの組み合わせで公開成功の記録がある検出結果をスキップします。ローカル履歴が必要です。 |
--json |
構造化した公開結果を標準出力に書き込みます。進捗は標準エラー出力に書き込みます。 |
Linear の課題の説明やドライランの出力には、ソースコードの抜粋や脆弱性の詳細が含まれる場合があります。公開前に、公開先のチームやプロジェクトを誰が閲覧できるか確認してください。
ドライラン以外では、実行のたびに選択した検出結果ごとに新しい課題の作成を試みます。ただし、--skip-existing で該当する検出記録、チーム、プロジェクトの組み合わせについて過去の公開成功が確認できた場合はスキップします。このオプションはリモートの課題を確認せず、記録のない公開や同時に進行中の公開も対象にしません。一部の検出結果を公開できなかった場合、作成に成功した課題は保持し、終了コード 2 を返します。重複を避けるため、--json を使う場合は再試行の前に created と failed の結果を確認してください。
公開する前に、課題のペイロードをプレビューします。
npx @openai/codex-security publish scan /path/to/completed-scan \
--to linear \
--linear-team TEAM_ID \
--dry-run \
--json接続済みの Linear アプリを使った公開
Linear API キーを指定しない場合、コマンドは既存の設定と接続済みの 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_IDLinear API キーを使った公開
--linear-api-key または CODEX_SECURITY_LINEAR_API_KEY を指定すると、Codex を起動せずに Linear API 経由で直接公開します。直接公開では、担当者を指定しない限り課題は未割り当てになります。
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 キーには CODEX_SECURITY_LINEAR_API_KEY を使い、--linear-api-key での指定は避けてください。
カスタムの検出結果サービスへの公開
既存の検出結果サービスを使う場合は、URL を明示的に指定します。
npx @openai/codex-security publish scan --scan latest \
--to custom --findings-url http://localhost:3000公開時には、確定済みの検出結果全体と対象リポジトリの ID を送信します。検出結果にはソースコードの抜粋、根拠、脆弱性の詳細が含まれる場合があります。ローカルマシンの外にあるサービスには HTTPS を使い、送信前に --dry-run --json を追加してペイロードを確認してください。
CLI はカスタムサービスにモデルの認証情報を送信しません。必要な認証は CLI の外で処理してください。デプロイとプロトコルの詳細は、検出結果サービスガイドを参照してください。
codex-security publish findings
インポートした検出結果を自分のマシンに保存するには、--to local を使います。--to cloud を指定すると、プレビューだけでもサービスに接続します。ファイルに保存された ChatGPT のサインイン情報と、既存のクラウド環境に対応する、アクセス権のあるリポジトリの ID または URL が必要です。クラウドへのインポートでは、サービスが一部のレコードを拒否すると、部分的な結果が返ることがあります。両方の手順については、GitHub インポートガイドを参照してください。
ローカルのチェックアウトに Dependabot アラートをインポートするには、同じ GitHub リポジトリからエクスポートしたファイルが必要です。Dependabot エクスポートガイドに従い、Dependabot アラートの読み取り権限を持つトークンを使って、すべてのページをチェックアウトの外に保存してください。
エクスポートスクリプトの末尾に echo "$out/dependabot.jsonl" を追加してから実行します。新しいシェルを開き、スクリプトが出力したパスを使ってファイルをプレビューします。./project と OWNER/REPO は、それぞれ自分のチェックアウトのパスとリポジトリ名に置き換えてください。チェックアウトにネットワーク経由のリモートが設定されている場合は、そのうち少なくとも 1 つがアラートの取得元リポジトリと一致している必要があります。ネットワーク経由のリモートがない場合は、エクスポートしたファイルがそのチェックアウトに対応することを確認してください。
export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
npx @openai/codex-security publish findings /path/to/dependabot.jsonl \
--to local --repository ./project --provider github \
--source-key github.com/OWNER/REPO/dependabot --dry-run --format jsonプレビューで保存先と除外対象を確認します。ドライランでは、除外されたアラートが表示されても終了コードは 0 です。受け入れられたアラートを保存するには、--dry-run を外して再実行し、確認を求められたら続行するか、--dry-run を --yes に置き換えて実行します。インポート時に 1 件でもアラートが除外された場合、受け入れられたアラートは保存され、終了コードは 1 になります。同じシェルで、保存されたアラートを確認します。
npx @openai/codex-security findings imported ./project --format jsonインポートしたアラートの初期評価ステータスは not_assessed です。同じソースキーで再度インポートすると、ファイルに含まれるアラートの保存済みレコードが更新されます。ファイルに含まれないアラートは、最後にインポートした時点の状態を保持します。同じアドバイザリに関連するアラートも、それぞれ別のレコードとして保持されます。
検出結果のレビュー用コマンド
次のコマンドは既存の検出結果を対象にします。
| コマンド | 例 | 動作 |
|---|---|---|
classify-severity |
codex-security classify-severity --scan latest --rubric policy.md --json |
探索の再実行や元の検出結果の書き換えを行わずに評価基準を適用します。--rubric を省略すると、モデルを呼び出さずに既存の重大度を引き継ぎます。重大度がない検出結果には評価基準が必要です。 |
suggest-owners |
codex-security suggest-owners findings.json --source-root /path/to/repository --json |
コミット済みのソース、CODEOWNERS、blame 情報、Git の履歴を読み取り、担当者を提案します。チケットの割り当ては行いません。 |
dedupe |
codex-security dedupe --scan SCAN_ID --json |
ローカルの SQLite で重複する検出結果を特定します。埋め込みがない場合や古い場合は埋め込み用の API キーが必要です。新たにレビューするにはモデルへのアクセスが必要です。 |
verify-fix |
codex-security verify-fix --scan SCAN_ID --json |
読み取り専用のサンドボックスで既存の修正を確認します。検出結果の ID、説明、Linear の選択条件を指定できます。 |
verify-fix は、判定不能または失敗したチェックが 1 つでもあれば 2 を返します。それ以外の場合、脆弱性が 1 件でも残っていれば 1、すべて修正済みなら 0 を返します。選択条件、モデル設定、出力オプションは各コマンドの --help で確認してください。
codex-security feedback
問題の説明を OpenAI に送信し、サポートに共有できる ID を取得します。
npx @openai/codex-security feedback SCAN_ID \
--reason "The scan stopped before it finished" --jsonスキャン ID を省略すると、実行中や失敗したスキャンも含め、現在のリポジトリで最後に開始したスキャンが選ばれます。スキャンがない場合は一般的な問題報告を送信します。報告には説明、バージョン、選択されたスキャンとセッションの ID が含まれます。デフォルトではログは含まれません。ログに含まれるソース、プロンプト、検出結果、ツールの出力を OpenAI と共有できる場合にのみ、--include-logs を追加してください。
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 は読み取り専用のサンドボックスでソースコードに基づく根拠を評価します。対象のビルド、アプリケーションコードの実行、テストや概念実証コードの実行、サービスへの接続は行いません。標準スキャン、詳細スキャン、差分スキャンにはそれぞれ独自の検証ワークフローがあり、patch は引き続き検出された問題の修正と検証を行います。
修正後や、その後のスキャンで問題が報告されなくなったときは、validate で検出結果を再評価してください。スキャンの比較だけでは修正が有効だったことを証明できません。実行時の根拠を得るには、別途再現手順を実行してください。
このコマンドはレポートを保存せず、評価を標準出力に書き込みます。保存するには標準出力をリダイレクトします。
npx @openai/codex-security validate findings.json > /path/outside/repository/assessment.mdセキュリティコンテキストを渡すには、--context TEXT、--context-file FILE、または繰り返し指定できる --knowledge-base PATH を追加します。構造化出力には、--output-schema FILE で、使用するモデルとプロバイダーが対応する自己完結型の JSON Schema を指定します。CLI は標準出力に書き込む前に、生成された JSON がスキーマに適合するか確認します。出力が無効な場合、CLI は 2 で終了し、評価を書き込みません。validate は --json に対応していません。
どちらのコマンドでも --effort で推論強度を選択できます。
npx @openai/codex-security validate "Possible SQL injection" --effort highスキャン後の検出結果の修正
scan --patch を使うと、スキャン完了後に、そのスキャンで検出された問題を修正できます。重大度のしきい値のデフォルトは low です。次のコマンドでは重大度が「高」または「重大」の検出結果を選択します。
npx @openai/codex-security scan . --patch --patch-severity high --json修正が検証済みの検出結果と、すでに修正されていた検出結果は、--fail-on-severity による失敗判定の対象になりません。
保存済みの検出結果の修正
検出結果 ID または個々の検出記録の 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 は現在のリポジトリで最後に完了したスキャンを選択します。patch は、保存済みの検出結果、直接指定したテキスト、ファイル入力のいずれでも --json に対応しています。
--create-pr を追加すると、検証済みの修正ファイルだけをコミットし、対応する CLI で GitHub のドラフト pull request または GitLab のドラフトマージリクエストを作成します。
npx @openai/codex-security patch --scan SCAN_ID --severity high --create-prプッシュまたは pull request の作成に失敗した場合は、表示された patch --resume-pr BRANCH コマンドを同じリポジトリから実行して再試行します。
Linear の課題に対する修正
個人 API キーには CODEX_SECURITY_LINEAR_API_KEY または LINEAR_API_KEY、OAuth トークンには LINEAR_ACCESS_TOKEN を設定します。キーがシェル履歴に残らないように、--linear-api-key KEY より環境変数を優先してください。
ID または URL で課題をインポートします。複数の課題を選択するには、--linear-issue を繰り返し指定します。
npx @openai/codex-security patch --linear-issue SEC-123 --linear-issue SEC-124--linear-project を使うと、プロジェクトの未解決の課題を選択できます。--linear-filter で対象を絞り込めます。
npx @openai/codex-security patch --linear-project "Security backlog" \
--linear-filter '{"labels":{"name":{"eq":"security"}}}'フィルターで state を指定しない限り、CLI は完了またはキャンセルされた課題を除外します。Linear の課題自体は変更しません。
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標準入力から API キーを渡して保存します。
printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key企業向けアクセストークンを保存します。
printenv CODEX_ACCESS_TOKEN | npx @openai/codex-security login --with-access-tokenSDK と同梱プラグインの読み取り専用メタデータを確認します。
npx @openai/codex-security info --jsonスキャン出力の確認
デフォルトでは、スキャンは進捗、完了時のサマリー、エラーを標準エラー出力に書き込み、スキャン結果全体を標準出力には書き込みません。構造化したスキャン結果を標準出力に書き込むには、--json、--format、--full-output のいずれかを指定します。
対話型ターミナルでは、現在のスキャン段階、ファイル一覧、アクティビティ、トークン使用量、推定コストがダッシュボードにリアルタイムで表示されます。CI や出力をリダイレクトした場合は、進捗をプレーンテキストで出力します。対話型ターミナルでも進捗をプレーンテキストで表示するには、--headless を追加します。
npx @openai/codex-security scan . --headlessダッシュボードには進行中のセッションの詳細も表示されます。マスキングは施されておらず、ソースコードや認証情報が含まれる可能性があります。共有前に内容を確認してください。
詳細な診断情報
--verbose を追加すると、ライフサイクル、認証、進捗、コストに関する診断情報を標準エラー出力に書き込みます。
npx @openai/codex-security scan . --verboseフラグを使わずに同じ診断情報を有効にするには、CODEX_SECURITY_LOG_LEVEL=debug を設定します。LOG_LEVEL=debug でも、CODEX_SECURITY_LOG_LEVEL が未設定または空の場合は診断情報が有効になります。
Codex Security は診断テキストをそのまま保持します。診断情報にはソースコードや認証情報が含まれる場合があるため、共有前に内容を確認してください。
完了時のサマリー
スキャンが完了すると、リポジトリの未解決の検出件数、重大度別の内訳、経過時間、レポートのパス、結果ディレクトリを標準エラー出力に書き込みます。取得できる場合はトークン使用量も報告します。--show-cost または --max-cost を指定した場合は推定コストも表示します。出力例を示します。
REPORT /path/to/scan/report.md
FINDINGS 4 (3 confirmed this scan; 1 previously found; 1 critical, 2 high, 1 informational)
SCOPE repository: .
ELAPSED 1s
RESULTS /path/to/scan参考情報に分類された検出結果もサマリーの合計に含まれます。重大度ポリシーが評価するのは、今回のスキャンで報告された critical、high、medium、low の検出結果だけです。リポジトリ全体の合計に含まれる以前の検出結果は評価しません。
JSON 出力
scan --json は 1 つの JSON 文書を標準出力に書き込みます。状態と対象範囲は manifest.scan、今回のスキャンの検出結果は findings で確認できます。repositoryFindings がある場合は、今回の検出結果と以前の未解決の検出結果が含まれます。review.excludedPaths には、スキャンがレビュー対象外として記録したパスパターンが列挙されます。scanDir、reportPath、artifactsDir は保存済みの結果の場所を示します。
threatModel には保存済みのモデルが構造化データまたは Markdown として格納されます。threatModelPath は保存した文書のパスを示します。どちらの値も null になる場合があります。文書の書き込みに失敗しても、モデルはエクスポートできます。
スキャン後に修正を適用する場合、JSON 出力には修正結果と、作成された pull request も含まれます。
進捗、完了時のサマリー、アーカイブの通知、診断情報は標準エラー出力に書き込まれます。完了したスキャンは、重大度ポリシーによって終了コード 1 を返す場合も JSON の結果を出力します。
JSON を正常に解析できた場合も、必ずプロセスの終了コードを確認してください。実行に失敗してスキャン結果を返せない場合、status、code、message を含む構造化エラーが --json、--format json、--format jsonl で出力されます。対象の変更後など、有効なスキャン結果が保持されている場合は、代わりに通常のスキャン結果と warnings が含まれることがあります。--json、--format json、--format jsonl に --full-output を追加すると、ok: false を持つラッパーオブジェクトが返されます。error にエラーが格納され、保持されている有効な確定済みの結果があれば data に格納されます。ほかの形式では、--full-output を指定しても失敗は標準エラー出力にのみ報告されます。これらの規則は scans rerun と scans resume にも適用されます。
codex-security scan --json は 1 つの JSON 文書を出力します。codex exec --json は JSON Lines 形式のイベントストリームを出力します。
スキャン成果物
完了したスキャンでは、人が読めるレポートと構造化された成果物が一緒に保存されます。確定済みのマニフェストには成果物のハッシュが記録されているため、後からファイルが変更されていないことを確認できます。
<scan-directory>/
├── scan-manifest.json
├── findings.json
├── report.md
├── threatmodel.md # when available
├── artifacts/
└── exports/
└── results.sarif # when produced各ファイルの内容は次のとおりです。
| ファイル | 内容 |
|---|---|
scan-manifest.json |
スキャンの識別情報、状態、対象、範囲、生成元、確定済みの成果物の記録です。 |
findings.json |
検出結果の識別子、重大度、確信度、分類、場所、根拠、検証、データフロー、到達可能性、修正方法です。 |
report.md |
人が読める形式のスキャンレポートです。 |
threatmodel.md |
保存された脅威モデルです（利用可能な場合）。 |
artifacts/ |
スキャンの補足資料です。 |
exports/results.sarif |
スキャン中に生成された SARIF です（生成された場合）。 |
完了状態とレビュー範囲
scan.status を scan-manifest.json で確認すると、スキャンが完了したかどうかがわかります。設定された対象範囲は scan.scope、レビュー中に記録された除外対象は scan.review.excludedPaths で確認できます。スキャンの比較でもこれらの除外対象を使います。スキャンが完了していても、対象範囲内に未レビューのファイルが残る場合があります。
未完了の作業がある場合は、scans show SCAN_ID と scans logs SCAN_ID で得られた根拠を確認してください。中断した詳細スキャンが再開条件を満たしていれば、scans resume SCAN_ID で続行できます。起動手順が保存されている場合は、scans rerun SCAN_ID で保存済みの設定を使って新しいレビューを開始できます。プラグインによるスキャンには、再実行可能な起動手順がない場合があります。その場合は、目的のパスとコンテキストを指定して新しいスキャンを開始してください。
終了コードとシグナル
CLI は次の終了コードを使います。
| 終了コード | 条件 |
|---|---|
0 |
スキャンまたは一括スキャンのキャンペーンが完了して重大度ポリシーを満たした場合、公開が失敗なく完了した場合、またはその他のコマンドが成功した場合です。 |
1 |
スキャンまたは一括スキャンのキャンペーンで設定した重大度以上の問題が見つかった場合、verify-fix が判定不能な結果を出さずに未修正の問題を報告した場合、または確認後に実行したインポートでローカルへの取り込みからレコードが除外されたり、クラウドから部分的な結果が返されたりした場合です。 |
2 |
入力、実行、結果の整合性、必須の出力、エクスポートのいずれかに問題が発生した場合、publish scan で 1 件以上の検出結果の公開に失敗した場合、または verify-fix が判定不能な結果を報告した場合です。 |
130 |
Ctrl-C でスキャンまたは公開が中断された場合です。 |
143 |
SIGTERM でスキャンまたは公開が終了した場合です。 |
レビューできなかった範囲があっても、完了したスキャンの終了コードは変わらず、重大度ポリシーも適用されます。終了コード 0 は、すべてのファイルをレビューしたことを意味しません。構造化出力を指定した場合、完了したスキャンや一部だけ成功した公開でも、得られた結果を標準出力に書き込みます。中断またはランタイムエラーの後、部分的な出力があれば CLI はその場所を表示します。
ローカルスキャンの権限
CLI と SDK のスキャンは、ユーザーのローカル OS 権限で実行されます。スキャンプロファイルでは、ローカルファイルシステムの読み取りとワークスペースルートへの書き込みが許可されます。操作の実行に関する承認リクエストは自動レビューの対象となり、その結果に応じて、その操作に追加の権限が付与される場合があります。権限リクエストを拒否するには、--codex 'approval_policy="never"' を指定するか、SDK で codexOverrides.approval_policy: "never" を設定します。ホストとネットワークの制限は引き続き適用されます。
スキャンとワークベンチのプロセスは、スキャンとは無関係の API トークンやクラウド認証情報を含め、ユーザーの環境変数を継承する場合があります。スキャンの開始前に、不要な認証情報を環境から削除してください。
認証と前提条件
OPENAI_API_KEY または CODEX_API_KEY を設定するか、npx @openai/codex-security login でサインインするか、ファイルに保存された既存の Codex サインイン情報を使います。OpenRouter または Fireworks では、プロバイダーの API キーを設定し、モデルを選択します。Amazon Bedrock では、代わりに Bedrock API キーまたは標準の AWS 認証情報チェーンを使います。
認証情報の選択については、スキャンの認証方式の選択を参照してください。
CI では、API キーをスキャンのステップだけで使用できるようにし、信頼できるワークフローを使ってください。
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 を設定します。
圧縮された Codex セッション（.jsonl.zst）の読み取りや再開には、Node.js 22.x では 22.15.0 以降、または Node.js 24 か 26 を使ってください。非圧縮の .jsonl セッションは、対応するすべての Node.js バージョンで利用できます。
続いて、CLI クイックスタート、一括スキャンガイド、CLI のよくある質問、CI ガイド、TypeScript SDK ガイドを参照してください。