OpenAI Codex Securityの使い方｜CLI・SDK・CI導入手順

OpenAI は製品文脈の Codex Security / Patch the Planet とは別に、開発者が clone して CI に載せられる OSS の CLI（コマンドラインから実行するツール）と TypeScript SDK（アプリに組み込むライブラリ） を公開しています。

📑目次

1. 何が公開されたか — CLI/SDK と製品・プラグインの切り分け
2. インストールから最初のスキャンまで（公式 Quick start）
3. CI・SDK・export で日常パイプラインに載せる
4. 導入前に決めること — アクセス・コスト・信頼境界
5. よくある質問（FAQ）
6. まとめと次のアクション

公開物と公式ドキュメント

• GitHub: openai/codex-security（Apache-2.0）
• npm: @openai/codex-security
• CLI docs: developers.openai.com/codex/security/cli

---

本記事の焦点

ルールベース SAST（静的アプリケーションセキュリティテスト）だけでは拾いにくい「意味判断が要る脆弱性」と、エディタ内プラグインだけでは回しにくい「複数リポジトリ・履歴・予算・CI ゲート」の両方を、同じスキャナー系統でつなぐ開発者向け面が今回のニュース性です。

本記事では次を、公式 README/docs と独立ハンズオン・実装解析で整理します。

• (1) 公開物の範囲と製品・プラグインとの差分
• (2) 公式 Quick start・前提・成果物
• (3) CI/SDK 接続と exit セマンティクス
• (4) アクセス・コスト・サプライチェーン境界

読み終えれば、dry-run と小規模スキャンで試すか、プラグイン継続で足りるか、導入を保留するかを判断できます。

---

この記事で学べること

---

何が公開されたか — CLI/SDK と製品・プラグインの切り分け

公開物とできること

OpenAI が公開したのは、リポジトリの脆弱性を find / validate / fix するための CLI と TypeScript SDK です。

README 時点の能力には次が含まれます。

• リポジトリ・path・diff・working-tree のスキャン
• findings 履歴
• CI チェック
• SARIF/CSV/JSON export

Cyber Security News も 2026-07-29 付で、CLI と TypeScript SDK の Apache-2.0 公開と @openai/codex-security を独立に報じています。

出典

---

製品イニシアチブとの差分

一方、Patch the Planet はメンテナー支援や人レビュー込みの製品・イニシアチブ文脈です。一次 URL が異なるため、本記事の焦点は 開発者が clone して日常パイプラインに載せる OSS 面 に置きます。

---

プラグインと CLI/SDK の役割

独立整理（note の南翔伍氏、Hacker News）では、次のように位置づけます。

• 対話プラグイン: 単一リポジトリの調査・Finding 読解向け
• 専用 CLI/SDK: シェル / CI / 複数リポジトリ / Docker から同じ能力を再現する運用レイヤー

---

agentic AppSec harness としての読み方

wasnotwas や Zenn（catatsuy）の実装解析では、parser/taint/signature 中心のクラシック SAST ではなく、skills・candidate ledger・validation・attack-path・成果物を持つ agentic AppSec harness（AIエージェントを使うアプリケーションセキュリティの実行基盤）として読むのが適切です。

---

面ごとの比較

面	主な入口	向く用途	注意
エディタ/プラグイン	対話的 Codex Security	単一 repo の調査・Finding 読解・修正対話	multi-repo 履歴・予算制御は弱い
CLI @openai/codex-security	shell / CI	path/diff/working-tree、fail-on-severity、export	出力は repo 外、アクセスは beta の場合あり
TypeScript SDK	CodexSecurity.run	社内ツール・自動化組み込み	1.0 未満で API 変更の可能性
Patch the Planet 製品文脈	メンテナー支援イニシアチブ	人レビュー込みの発見〜パッチ	本記事の一次 URL とは別

---

出典と隣接トピック

出典:

• openai/codex-security
• Codex Security CLI docs
• note.com/gtminami
• wasnotwas
• Patch the Planet
• 時点: 2026年7月

隣接トピックとして、Claude Code 向けの Claude Security プラグイン や、Claude Code / Codex のサンドボックス境界 も、エージェント系セキュリティ運用の比較軸になります。

---

インストールから最初のスキャンまで（公式 Quick start）

前提

前提は次のとおりです。

• Node.js 22+
• scan/export に Python 3.10+（3.10 では tomli）
• macOS / Linux / Windows
• Codex Security 本体へのアクセスが別途必要な場合あり

公式 Quick start は、次の4段階です。

1. パッケージをインストールする
2. ログインする
3. --dry-run で対象と出力先を確認する
4. 本スキャンを実行する

npm install @openai/codex-security
npx codex-security login
npx codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --dry-run
npx codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR"

---

認証と状態ディレクトリ

認証の選択肢は次です。

• ローカルの ChatGPT サインイン
• headless の login --device-auth
• CI の OPENAI_API_KEY / CODEX_API_KEY
• stdin の --with-api-key
• --auth chatgpt|api-key|auto

環境の API キーは、既定では保存済みサインインより優先されます。

状態と出力の約束は次です。

• workbench 状態は CODEX_SECURITY_STATE_DIR でリポジトリ外へ置ける
• 出力ディレクトリは対象 repo / worktree の外が必須
• Unix では既存出力 dir に chmod 700 が求められる

---

dry-run と成果物

--dry-run（preflight）はネットワークと認証なしで repo / target / output を検証します。

成果物の例は次です。

• report.md
• findings.json
• coverage.json
• scan-manifest.json
• 条件により exports/results.sarif

coverage は complete / partial / unknown で示されます。

---

独立ハンズオンのコスト感

独立ハンズオン（note.com/nobel）では、次の実測があります。

• install: 92 packages / 約 15 秒
• node_modules: 約 408MB
• info --json: CLI 0.1.1 / plugin 0.1.14 / runtime 0.144.6 / 既定モデル gpt-5.6-sol（effort xhigh）
• --max-cost 3: 途中停止
• 下位モデル + $6 上限: 約 17 分・複数 Finding

ChatGPT サインイン経路では API 換算とサブスク枠の解釈が異なる点に注意してください。

出典:

• GitHub README
• npm @openai/codex-security
• CLI docs
• note.com/nobel
• 時点: 2026年7月時点

---

CI・SDK・export で日常パイプラインに載せる

CI ポリシーと exit コード

CI では OPENAI_API_KEY を secret に置き、非対話では API キーが優先されます。必要なら --auth api-key を明示します。

• 既定は report-only
• --fail-on-severity high などを付けると、completed かつ閾値以上の Finding で exit 1
• 不完全 coverage やランタイムエラーは exit 2（パスと誤認しない）

---

ターゲット・export・hook

ターゲットの例は次です。

• --path
• --diff origin/main
• --working-tree
• --mode deep

追加制御は次です。

• --max-cost: 推定 USD 上限
• --knowledge-base: 設計書・脅威モデルを追加

export は sarif / csv / json です。install-hook は pre-commit で high-severity や失敗をブロックし、既存 hook を置換しません。

---

TypeScript SDK と bulk-scan

TypeScript SDK の流れは次です。

1. new CodexSecurity()
2. run(repo, { outputDir, auth })
3. reportPath / findings を取得
4. close()

AbortSignal や onWorkerStatus にも対応します。bulk-scan は対話または CSV + workers です。Docker compose 経路は公式 docs の hardened 構成を参照してください。

---

実装解析で見る責務分割

Zenn の解析では、次のように整理されています。

• LLM が意味判断を担う
• 形式・ID・seal・report 描画は決定論的 finalizer が担う
• fix は Generate / Apply / Verify を分離する

---

CI コマンド早見

コマンド/面	主な用途	CI での典型
scan --dry-run	入力検証	PR 前の設定チェック
scan --diff / --working-tree	変更点レビュー	PR ゲート
scan --fail-on-severity	ポリシー違反で fail	main 保護
export --export-format sarif	既存 SARIF ビューア連携	アーティファクト保存
CodexSecurity.run	社内オーケストレーション	カスタムワークフロー

---

出典（CI・SDK）

• CLI docs
• npm
• Zenn catatsuy
• Cyber Security News
• 時点: 2026年7月時点

---

導入前に決めること — アクセス・コスト・信頼境界

アクセス境界

コードが Apache-2.0 で読めることと、スキャナー本体が limited beta / 承認顧客・パートナー限定であることは別問題です。独立 note と wasnotwas がこの境界を強調しています。

フルリポジトリスキャンには Trusted Access for Cyber が別途必要な場合があり、login だけでは付与されません（公式 docs）。

---

コストと出力の機微性

コスト面では既定モデルが高コストになり得ます。独立ハンズオンでは max-cost $3 で途中停止、下位モデル + $6 で約 17 分・複数 Finding でした。

結果にはソース抜粋や再現手順が含まれるため、次が前提になります。

• repo 外への出力
• 認可レビュア限定
• retention ポリシー

---

サプライチェーンとエコシステム文脈

サプライチェーン文脈では、Check Point Research が OpenAI Codex CLI の CVE-2025-61260 を独立開示しています。

要点は次のとおりです。

• project-local .env による CODEX_HOME リダイレクトと未承認 MCP 実行
• 2025-08-20 の 0.23.0 で修正済み
• agentic ツールがリポジトリ内容を信頼するときの境界設計の独立証拠

Codex Security 本体の代替評価ではなく、同エコシステム導入時の防御前提として読んでください。

出典

---

隣接するプラットフォーム動向

GitHub が第三者コーディングエージェント向けセキュリティ検証を GA 化した動き（GitHub の第三者コーディングエージェント向けセキュリティ検証 GA）とあわせ、生成コードとローカルエージェント実行の両方を見る必要があります。

---

導入前チェックリスト

1. 対象 repo の評価権限と出力 dir（repo 外・0700）を確保する
2. npx codex-security info --json と --dry-run で版と設定を確認する
3. 小 fixture または単一 path で --max-cost 付き試験スキャンし、coverage / proof gap を読む
4. CI では report-only → fail-on-severity の順に上げ、exit 1 と exit 2 を分けて監視する
5. プラグイン継続で足りる単一 repo 調査か、CLI/SDK の multi-repo harness が必要かを決める
6. agentic ツールの project-local 設定・秘密情報・結果 dir の信頼境界をレビューする

---

出典（導入前）

• CLI docs
• note.com/nobel
• note.com/gtminami
• Check Point Research
• HN item 49089755
• 時点: 2026年7月時点

---

関連記事:

• fzf・ripgrep・ghで作る高速ターミナル開発環境
• Perplexity CLI（pplx）公開 — コーディングエージェント向け JSON 検索・ページ取得 CLI
• wmux — Claude Code / Codex / Gemini を1ウィンドウで並列運用するワークスペース多重化（MIT）

よくある質問（FAQ）

Q1. Codex Security プラグインと CLI/SDK のどちらを使うべきか？

単一 repo を対話的に読むならプラグインで足りることが多いです。CI・複数 repo・履歴比較・予算上限・社内ツール組み込みなら CLI/SDK です（出典: note gtminami / HN）。

---

Q2. GitHub にコードがあるだけでスキャンできるか？

いいえ。Node/Python 前提に加え、Codex Security アクセス（場合により Trusted Access for Cyber / limited beta）が別です。コード公開は利用権とイコールではありません（出典: 公式 docs / wasnotwas / note gtminami）。

---

Q3. CI で失敗させたいのにいつも緑になるのはなぜか？

既定は report-only です。--fail-on-severity を付けないと findings があっても exit 0 になり得ます。不完全 coverage は exit 2 です（出典: 公式 docs / npm）。

---

Q4. 従来の Semgrep/CodeQL を置き換えられるか？

独立解析は「ルールベース SAST の置換」ではなく、人間 AppSec レビューの補完・agentic harness と位置づけます。併用前提で設計してください（出典: Zenn catatsuy / wasnotwas）。

---

Q5. 最初に何から試すのが安全か？

次の順が安全です。

1. dry-run
2. 小 path + max-cost
3. report の proof gap / coverage 確認
4. 段階的に CI

全 commit をいきなり重い AI スキャンで止めないでください（出典: note gtminami / nobel / 公式 docs）。

---

まとめと次のアクション

OSS 化されたのは、開発者が clone してパイプラインに載せる CLI/SDK 面 です。製品イニシアチブやエディタプラグインと同一次元で語らないことが、導入判断を誤らない第一歩です。

公式 Quick start と成果物契約（repo 外出力、auth、exit code）を軸に、独立ハンズオンのコスト感と実装解析の harness 像で差分価値を補ってください。

次の一手は、上のチェックリスト 1–6 を自チームの権限・予算・信頼境界に当て、dry-run と小規模スキャンの結果だけで go / no-go を決めることです。