Codex Security CLI reference

概要

@openai/codex-security が提供するセキュリティスキャン用 CLI。リポジトリ・パス・コミット差分・作業ツリーを対象に脆弱性スキャンを実行し、結果の保存・比較・エクスポート・Linear への登録までを扱う。パッケージは公開されているが、スキャンの実行には Codex Security へのアクセス権が要る。

npx @openai/codex-security で実行する。

仕様

コマンド一覧

コマンド	用途
`codex-security scan`	スキャンを実行する
`codex-security install-hook`	Git の pre-commit スキャンを導入する
`codex-security bulk-scan`	リポジトリを探索し、再開可能な一括スキャンを実行する
`codex-security scans`	保存済みスキャンの一覧・詳細・比較・ログ取得
`codex-security findings`	保存された検出結果の確認と更新
`codex-security export`	完了した検出結果を CSV / JSON / SARIF で出力する
`codex-security publish`	完了したスキャン結果を Linear へ登録する
`codex-security validate`	検出結果の候補を検査する
`codex-security patch`	検出された問題を修正する
`codex-security login` / `logout`	サインイン・認証情報の保存・削除
`codex-security info`	SDK と同梱プラグインのメタデータを表示する（読み取り専用）

統合用コマンド:

コマンド	用途
`codex-security completions`	シェル補完スクリプトを生成する
`codex-security mcp`	CLI を MCP サーバーとして登録する
`codex-security skills`	Codex Security の skill をエージェントへ同期する

--version は導入済みバージョンを表示して終了する
info --json は SDK と同梱プラグインのバージョンを返す。--version と info はいずれも Python を必要としない
--llms はエージェント可読のコマンドマニフェストを出力する
scan --schema --format json はスキャン引数のスキーマを JSON で返す

`scan` — スキャン対象の選択

対象は1スキャンにつき1種類だけ選ぶ。

引数	説明
`--path PATH`	リポジトリからの相対パスを対象にする。複数回指定可
`--diff BASE`	`BASE` から `--head` までのコミット差分を対象にする。head の既定は `HEAD`
`--head HEAD`	`--diff` の head リビジョンを指定する
`--working-tree`	`--base` に対するステージ済み・未ステージの変更を対象にする。base の既定は `HEAD`
`--base BASE`	`--working-tree` の base リビジョンを指定する
`--mode {standard,deep}`	スキャンモード。既定は `standard`

--path / --diff / --working-tree は排他。--head は --diff を、--base は --working-tree を要求する
deep モードはリポジトリ全体とパス指定を対象にできる
--diff と --working-tree は、リポジトリ引数が Git worktree のルートであることを要求する。指定した ref はそのチェックアウトに存在している必要がある
repository 引数の既定はカレントディレクトリ

`scan` — deep モードの制御

--mode deep と併用する。standard スキャンでは使えない。

引数	説明	既定
`--workers N`	同時に動く discovery worker の上限	自動選択
`--subagents N`	各 worker が使える subagent 数	`3`
`--stop-after-no-new N`	新規検出が無い実行が N 回続いたら停止する	`6`
`--max-discovery-runs N`	discovery の総実行回数の上限	`60`
`--max-time-hours HOURS`	discovery の時間上限（時間、小数可）	`96`

--subagents は 0 以上の整数。--max-time-hours は 96 以下の正の数。その他は正の整数
時間上限は discovery にのみ適用される。超過時は未完了の discovery を打ち切り、完了分を保持したまま検証と報告へ進む
ソースレビューが1件も完了しなかった場合、カバレッジを partial として記録し終了コード 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

コマンドラインオプションが TOML の既定値を上書きする
stop_after_consecutive_errors は TOML でのみ設定する。既定は 3
scan --workers は1スキャン内の discovery worker 数、bulk-scan --workers は同時に走るリポジトリ数を制御する

`scan` — 文脈と指示の追加

引数	説明
`--knowledge-base PATH`	アーキテクチャ文書・脅威モデル・セキュリティポリシーを渡す。複数回指定可
`--scan-prompt-file FILE`	スキャンへの追加指示をテキストまたは Markdown で渡す
`--post-scan-prompt-file FILE`	スキャン成功後に同じ認証セッションで走る後続指示

--knowledge-base が扱うのは .md / .markdown / .txt / .pdf / .docx。ディレクトリは再帰的に探索し、リンクされた入力パスは拒否、リンクされたディレクトリ項目は読み飛ばす。抽出した文書内容は保存されるスキャン結果の外に置かれる
--post-scan-prompt-file はカバレッジ不完全やエラーを伴うスキャンの後にも走る。ただし中断時とコスト上限到達時は走らない
後続指示が失敗した場合、警告を出して完了済みのスキャン結果は保持する

`scan` — 出力とポリシー

引数	説明
`--output-dir DIR`	スキャン成果物を、外側の Git worktree の外にある専用ディレクトリへ書く
`--archive-existing`	既存結果を `DIR.previous-<timestamp>-<id>` へ退避し、空の出力ディレクトリで開始する。`--output-dir` が必要
`--fail-on-severity LEVEL`	`critical` / `high` / `medium` / `low` 以上の検出があれば終了コード `1` を返す
`--max-cost USD`	推定モデルコストが指定額を超えたらスキャンを止める
`--dry-run`	リポジトリ・対象・knowledge base・出力先・Codex 設定を検査し、スキャンは開始しない
`--headless`	対話ダッシュボードの代わりにプレーンテキストで進捗を出す
`--verbose`	秘匿処理済みのライフサイクル・認証・進捗・コスト診断を stderr へ出す
`--json`	manifest・findings・coverage・paths・turn メタデータを1つの JSON 文書として出力する
`--format {toon,json,yaml,jsonl}`	スキャン結果全体を指定形式で出力する
`--full-output`	既定の構造化形式で結果全体を出力する

コスト上限は推定値であり、厳密な上限ではない。実行中のリクエストは上限をわずかに超えて完了しうる
deep スキャンが discovery 完了後に上限へ達した場合、利用可能な結果を封印しカバレッジを partial として終了コード 2 を返す。それ以外の場合も 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 の外でなければならない
スキャンは既定では報告のみを行う。CI で重大度ポリシーを評価するには --fail-on-severity を付ける
dry run は認証情報の読み込み・Codex の起動・プラグインの Python インタプリタ検査を行わない

`scan` — ランタイム

引数	説明	既定
`--auth {auto,chatgpt,api-key}`	スキャンに使う認証情報	`auto`
`--provider {openai,openrouter,fireworks,amazon-bedrock}`	推論プロバイダ	`openai`
`--model MODEL`	モデル。OpenRouter / Fireworks / Amazon Bedrock では必須	`gpt-5.6-sol`
`--effort {minimal,low,medium,high,xhigh}`	推論の effort	`xhigh`
`--plugin-path PATH`	同梱プラグインを上書きするディレクトリまたは ZIP
`--python PATH`	プラグインランタイムの Python インタプリタ
`--codex KEY=VALUE`	Codex の設定値を渡す

認証の選択:

--auth auto は認証情報を自動選択する。ChatGPT サインインと OPENAI_API_KEY / CODEX_API_KEY の両方がある場合、テキスト出力の対話スキャンではどちらを使うか尋ねる
CI、JSON / JSONL スキャン、対話端末を持たないスキャンは環境変数の API キーを使う
dry run は尋ねず、認証情報も読み込まない
保存済み認証情報を既定にするには unset OPENAI_API_KEY CODEX_API_KEY を実行する

プロバイダ別の要件:

OpenRouter: OPENROUTER_API_KEY と明示的な --model
Fireworks: FIREWORKS_API_KEY と明示的な --model
Amazon Bedrock: AWS_REGION と、AWS_BEARER_TOKEN_BEDROCK / AWS アクセスキー / AWS プロファイル / web identity / コンテナ認証情報 / 既定の AWS 認証チェーンのいずれか。Bedrock スキャンは --auth・ChatGPT サインイン・OpenAI API キーではなく AWS 認証情報を使う
--provider は scan と bulk-scan の両方が対応する

`install-hook`

カレントリポジトリに pre-commit のセキュリティ検査を導入する
ステージ済みと未ステージの変更をコミット前にスキャンし、high 以上の検出とスキャンエラーをブロックする
core.hooksPath を尊重し、既存の pre-commit スクリプトを置き換えない
--fail-on-severity で閾値を変更できる

`bulk-scan`

引数なしで実行すると対話的にリポジトリを選択する。この経路は GitHub CLI のサインインを要求する
準備済みのリストを使う場合は CSV と --output-dir を渡す
CSV は id / repository / revision 列が必須。リビジョンは完全なコミットハッシュ。任意の scope / mode / prompt 列でリポジトリ個別の設定ができる
--knowledge-base は全リポジトリで共有される。--scan-prompt-file の共有指示の後に、CSV の prompt 列がリポジトリ固有の指示として続く
--workers は同時スキャン数の上限で既定は 4。--mode の既定は standard、--max-attempts の既定は 1
--max-attempts はリポジトリエラー・スキャンエラーの再試行に使う。カバレッジ不完全で完了したスキャンは再試行されず、結果は保持され終了コード 2 を返す
同じコマンドを再実行すると既存の出力ディレクトリから再開する。完了済みスキャン（カバレッジ不完全を含む）は読み飛ばされる

`scans`

サブコマンド	説明
`scans` / `scans list`	保存済みスキャンを一覧する。`--scan-root` で出力ディレクトリを指定できる
`scans show SCAN_ID`	結果と設定を表示する。`--show-linked-findings` で過去スキャンからのリンクを含める
`scans rerun SCAN_ID`	元の設定で現在のチェックアウトに対して再実行する
`scans logs SCAN_ID`	保存されたセッションイベントを読む。`--json` で機械可読形式
`scans compare PREV CURRENT`	新規・継続・再発・解決・不明の検出を比較する
`scans match PREV CURRENT`	一致を明示的に保存する。`--force` で再計算、`--all` で全完了スキャンを対象にする

rerun は元のスキャンが記録したプラグインバージョンを要求する。導入済みバージョンが異なる場合、別バージョンで実行せずに停止する
scans logs の出力は秘匿処理されておらず、ソースコードや認証情報を含みうる
比較は同じ根本原因を共有する検出を自動的に対応付け、保存済みの一致を再利用する
後のスキャンがカバレッジ不完全、または検出の元位置を対象にしていない場合、その検出は unknown になる
同じ設定で再実行しても結果は変わりうる。一致と比較は変化を追跡するものであり、結果を決定的にしたり脆弱性の消滅を証明したりはしない

`findings`

findings list はカレントリポジトリのスキャン横断で未解決の検出を一覧する。リポジトリパスを渡すと別のチェックアウトを見る。--json で構造化出力
一覧は、最新スキャンで見つかった検出と、最新スキャンでは確認されなかった過去の検出を区別する
過去の検出は解決または却下されるまで未解決のまま残る。最新スキャンに出てこないことは修正済みの証拠として扱われない
findings false-positive OCCURRENCE_ID --reason REASON で誤検出として記録する。--reason は空にできない
記録した判断はリポジトリに保存され、以後のスキャンへ文脈として渡される。ただし各スキャンは現在のソース・制御・到達可能性を独立に再検査する。過去の判断がルール・パス・脆弱性クラスを抑制することはない

`export`

完了して封印されたスキャンから CSV / JSON / SARIF を出力する。出力前にスキャン成果物を検証し、Codex ランタイムと認証情報には触れない。

引数	説明	既定
`--export-format {csv,json,sarif}`	出力形式	`sarif`
`--output FILE\|-`	ファイルまたは標準出力へ書く	カレントディレクトリのファイル
`--source-root PATH`	チェックアウトを使って SARIF にソース行のフィンガープリントを付ける	—
`--python PATH`	同梱エクスポータの Python インタプリタ	—

--source-root は --export-format sarif でのみ機能する
JSON は封印された findings 文書をそのまま保つ。CSV は可搬な列を含み、ローカルのワークベンチのトリアージ状態は含まない
--output を省略した場合、SARIF は results.sarif、JSON は findings.json、CSV は findings.csv としてカレントディレクトリに書かれる

`publish scan`

完了したスキャンの全検出を Linear へ登録する。

引数	説明
`--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`	作成した issue の担当者。API キーが必要。省略時は未割り当て

SCAN_DIR は完了して封印されたスキャンを含む必要がある。対話端末では省略してローカル履歴から選択できる
issue の作成には、スキャンとその検出がローカルのスキャン履歴に存在することも要る。dry run はこの永続性検査を行わずに封印された成果物を検証する

`validate` と `patch`

validate は検出候補が妥当かを検査する。patch は同梱の修正 skill で修正を生成する
各引数はリテラルのテキストでもファイルへのパスでもよい。どちらもカレントディレクトリに対して動作する
修正後、または後のスキャンが検出を報告しなくなったときに、元の検出を直接再検査する用途に validate を使う。スキャンの比較だけでは修正が効いたことを証明できない
両コマンドは --effort に対応する
外部ツールがスキャナを作り直さずにこれらのコマンドを利用できる

`login` / `logout` / `info`

コマンド	説明
`login`	対話的にサインインする
`login --device-auth`	リモートやヘッドレス環境でデバイス認証を使う
`login status`	現在のサインインを確認する
`logout`	保存されたサインインを削除する
`login --with-api-key`	API キーを標準入力から受け取って保存する
`login --with-access-token`	エンタープライズのアクセストークンを保存する
`info --json`	SDK と同梱プラグインのメタデータを表示する

出力

既定では進捗・完了サマリ・エラーを stderr へ出し、スキャン結果全体を stdout へ書かない。構造化結果を stdout へ出すには --json / --format / --full-output を指定する
対話端末ではフェーズ・レビュー済みファイル・アクティビティ・トークン使用量・推定コストを表示するライブダッシュボードが出る。CI とリダイレクト時はプレーンテキスト
CODEX_SECURITY_LOG_LEVEL=debug は --verbose と同じ診断を有効にする。CODEX_SECURITY_LOG_LEVEL が未設定なら LOG_LEVEL=debug でも有効になる
完了サマリは未解決の検出数・重大度の内訳・カバレッジ・経過時間・レポートパス・結果ディレクトリを stderr へ書く。可能な場合はトークン使用量と推定コストも含む
informational の検出はサマリの合計に数えられる。重大度ポリシーが評価するのは今回のスキャンの critical / high / medium / low のみで、リポジトリ合計に含まれる過去の検出は対象外
scan --json は1つの JSON 文書を出力する（codex exec --json の JSON Lines イベントストリームとは異なる）

scan --json のトップレベル構造:

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

重大度ポリシーが終了コード 1 を返す場合も、カバレッジ不完全で 2 を返す場合も、完了したスキャンは JSON 結果全体を出力する

スキャン成果物

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

ファイル	内容
`scan-manifest.json`	スキャンの識別情報・状態・対象・スコープ・生成元・封印された成果物の記録
`findings.json`	検出の識別子・重大度・確信度・分類・位置・根拠・検証・データフロー・到達可能性・修正
`coverage.json`	レビュー対象・除外・保留作業・未解決の問い・カバレッジの完全性
`report.md`	可読のスキャンレポート
`artifacts/`	補助的な成果物
`exports/results.sarif`	スキャン中に生成された SARIF（存在する場合）

カバレッジの完全性は3値:

complete: 選択したスコープについて完全なカバレッジを記録した
partial: 保留作業やその他のカバレッジ上の制限を記録した
unknown: カバレッジの完全性を不明として報告した

終了コードとシグナル

終了コード	条件
`0`	スキャンが完全なカバレッジで完了し重大度ポリシーを通過した、一括スキャンや登録が失敗なく完了した、またはその他のコマンドが成功した
`1`	完了したスキャンが設定した重大度以上の検出を報告した
`2`	入力・ランタイム・エクスポートのエラー、カバレッジ不完全、エラーを含むリポジトリのある一括スキャン、失敗した検出を含む登録
`130`	Ctrl-C でスキャンまたは登録が中断された
`143`	SIGTERM でスキャンまたは登録が終了した

partial または unknown のカバレッジを持つスキャンは、重大度ポリシーが無くても 2 を返す
構造化出力を要求した場合、完了したスキャンと部分的な登録も利用可能な結果を stdout へ書く
中断やランタイムエラーの後、部分出力の位置を表示する

制約・注意点

ローカルのスキャン権限

CLI と SDK のスキャンは、実行者のローカル OS 権限で動く
すべてのスキャンが codex_security_scan のファイルシステムプロファイルを使い、approvalPolicy を "never" に設定する。プロファイルはローカルファイルシステムの読み取りと、ワークスペースルートおよび選択したスキャン状態ディレクトリへの書き込みを許可する
スキャンは対話的な承認を求めて停止しない
CLI の --codex や SDK の codexOverrides で渡した設定（approval_policy、sandbox_mode、ファイルシステム権限を含む）は、これらのスキャン制御を置き換えたり制限したりできない。ホストとネットワークの制限は引き続き適用される
スキャンとワークベンチのプロセスは、無関係な API トークンやクラウド認証情報を含む環境を継承しうる。信頼でき、かつ評価する権限のあるリポジトリだけをスキャンし、必要な認証情報だけを渡す

結果の扱い

スキャン結果の保存先はソースの抜粋や脆弱性の詳細を含みうるため、権限と保持期間を管理する
エクスポートも同様にソースの抜粋と脆弱性の詳細を含みうる。リポジトリ外で実行するか、--output にチェックアウト外の非公開パスを指定する
scans logs の出力は秘匿処理されていない。共有前に内容を確認する
カバレッジを安全性の根拠として使う前に、保留された対象・明示的な除外・未解決の問いを確認する

前提条件

Node.js 22（22.13.0 以降）、24、または 26 が必要
スキャン・一括スキャン・エクスポート・スキャン履歴・保存された検出は Python 3.10 以降も要求する。Python 3.10 では tomli も必要
scan / bulk-scan / export では --python、または Python を使う任意のコマンドで環境変数 PYTHON を指定できる
認証は OPENAI_API_KEY または CODEX_API_KEY の設定、login によるサインイン、既存のファイルベースの Codex サインインのいずれか
CI では API キーをスキャンステップに限定し、信頼できるワークフローを使う

MCP としての公開

CLI を MCP サーバーとして公開した場合、利用できるのは読み取り専用の info のみ
スキャン・エクスポート・登録・サインイン・検証・修正は CLI 専用のまま

出力形式

スキャン結果が対応するのは toon / json / yaml / jsonl。グローバルのコマンドヘルプには md も並ぶが、スキャン結果は Markdown 出力に対応しない
フレームワーク階層の --format は、完了したスキャンから成果物を出力する --export-format とは別物

Codex Security CLI reference

概要

仕様

コマンド一覧

scan — スキャン対象の選択

scan — deep モードの制御

scan — 文脈と指示の追加

scan — 出力とポリシー

scan — ランタイム

install-hook

bulk-scan

scans

findings

export

publish scan

validate と patch

login / logout / info

出力