Codex Security plugin の使い方を調べていると、codex security plugin、codex security plugin quickstart、security-diff-scan、codex deep security scan、codex security deep scan のように入口は分かれて見えます。ですが実際に止まりやすいのは同じ地点です。Codex で実装を進めるチームが増えると、次に詰まるのは「作らせた差分をどう安全に受け入れるか」です。通常のレビューでは仕様漏れやテスト不足は拾えても、認可、入力検証、secret、filesystem、network request のようなセキュリティ観点は後回しになりがちです。特に codex security plugin quickstart を流した直後は、PR差分だけ security-diff-scan で見ればよいのか、重い codex deep security scan をいつ使うべきか、通常の Codex code review や approvals_reviewer = "auto_review" とどこで役割分担するかに加え、Codex Security CLI の terminal / CI lane とどう分けるかで止まりやすいです。
この記事では、Codex Security plugin をどの作業に使い、どこでは使わないかを整理します。quickstart で全体scanを流すべき場面と、PR差分だけを security-diff-scan で見るべき場面、重要箇所だけを deep security scan で掘る場面を分けて、Codex Security plugin の使い方 を実務の review lane に落とし込みます。GitHub PR の通常レビュー運用は Codex code review 実践ガイド、approval queue の reviewer 差し替えや approvals_reviewer = "auto_review" の境界は Codex auto-review ガイド、Codex の実行権限そのものは Codex sandbox / approvals 設計ガイド、agent phase の外部通信は Codex internet access 安全運用ガイド、Codex が出した差分を受け入れる最終確認は Codex レビュー完了ゲート設計ガイド、組織ルール化は AIコーディングツールの社内ガイドライン に分けています。
Codex Security CLI を探していて local scan、PR差分CI、SARIF 出力、severity policy を知りたい人は、Codex Security CLI 実践ガイド へ進んでください。このページは plugin を使った security review lane に絞り、terminal / CI で再現可能な scan を回す責務は CLI 記事に分けます。
approvals_reviewer = "auto_review" の request routing や reviewer 差し替えそのものを決めたい人は Codex auto-review ガイド、どの作業 profile で approvals_reviewer = "user" と approvals_reviewer = "auto_review" を切り替えるか先に固めたい人は Codex approvals_reviewer / config profile 設計ガイド、merge 前の受け入れ条件を固定したい人は Codex レビュー完了ゲート設計ガイド を先に見てください。この記事は、その後段で security-diff-scan をどの PR に使うか に限定します。
今回の論点は、脆弱性を探す・検証する・優先順位を付ける・修正する流れを、Codex の普段の開発フローへどう接続するかです。先に一言で言うと、Security plugin は「Codex にレビューさせる機能の強化版」ではなく、PR差分・定期棚卸し・backlog整理を security 専用レーンへ分離するための道具です。
先に結論: plugin は「scanする道具」ではなく review lane として設計する
Codex Security plugin を入れたら毎回全部 deep scan すればよい、という運用は重すぎます。私なら、最初に次の5レーンへ分けます。
| レーン | 使う workflow | 向いている場面 | レビュー観点 |
|---|---|---|---|
| 初回棚卸し | standard scan | repository 全体の主要リスクを掴む | coverage、threat model、findings |
| PR差分確認 | security-diff-scan | feature branch / uncommitted diff / PR | 変更で増えた regression |
| 深掘り | deep-security-scan | 重要領域の定期・節目review | proof gap、deferred surface |
| backlog整理 | triage-finding | SAST、Dependabot、社内ticketの山 | confirmed / needs_review / not_actionable |
| 修正検証 | fix-finding | accepted finding の最小修正 | patch、regression test、verification |
この分け方にしておくと、「セキュリティを見た」という雑な報告を避けられます。標準scanで見たのか、PR差分だけ見たのか、既存findingをtriageしたのかで、残るリスクが違うからです。
最初の10分で決めること
codex security plugin quickstart を見つけた直後に迷うなら、まず次の4問だけで十分です。
| いまの状況 | 最初に使うもの | その理由 |
|---|---|---|
| repository 全体の危ない場所を把握したい | standard scan | coverage と threat model の地図を先に作る |
| この PR が危険な差分を増やしたか見たい | security-diff-scan | 既存負債を混ぜず、今回の変更だけに絞れる |
| 認証や課金の節目改修を深く洗いたい | deep security scan | 重要 surface の proof gap を詰めやすい |
| 既存の SAST / Dependabot backlog が山積み | triage-finding | 修正優先度を決める前に信頼度を揃えられる |
逆に、次の目的なら最初に Security plugin へ行かない方が早いです。
| やりたいこと | 先に見る記事 |
|---|---|
| GitHub PR に通常レビューコメントを付けたい | Codex code review 実践ガイド |
| approval request を自動 reviewer に回したい | Codex auto-review ガイド |
| Codex 自体の権限境界を決めたい | Codex sandbox / approvals 設計ガイド |
| merge 前の最終確認項目を固定したい | Codex レビュー完了ゲート設計ガイド |
通常scanは初回の地図作りに使う
Codex Security plugin の quickstart は、ローカル repository に対する read-only な通常scanから始める流れです。完了すると report.md、findings/、hardening/、findings.json、coverage.json などの成果物が作られます。
私は最初のscanを「脆弱性を全部見つける作業」とは見ません。むしろ、次の3点を確認するための地図作りとして扱います。
- plugin が repository の構造をどう理解したか
- どの surface が見られ、どの surface が deferred になったか
- findings の根拠が、実際の trust boundary と合っているか
たとえば Web API、admin console、batch job、MCP server が同じ repository にある場合、全部を同じ重みで見るとレビューの焦点がぼやけます。初回scanでは、coverage.json と report.md を見て、「次は auth middleware を深掘りする」「admin write API は別scanにする」のように対象を切る方が現実的です。
PRには deep scan ではなく diff scan を使う
PRやfeature branchを見るときは、repository全体のdeep scanではなく security-diff-scan を使います。公式docsでも、pull request、commit、branch range、working-tree patch のようなGit-backedな変更セットには、diff-focused workflowを使う前提です。
たとえば CI なら、概念的には次のように分けます。
BASE_REVISION = pull request の merge base
HEAD_REVISION = pull request head
Use $codex-security:security-diff-scan to review changes from BASE_REVISION to HEAD_REVISION for security regressions. Do not modify the checkout.ここで見たいのは「このPRが新しい脆弱性を増やしたか」です。既存の大きな設計問題まで同じPRコメントに混ぜると、作業者は修正範囲を見失います。
私なら、PR差分scanでは focus を明示します。
Focus on authentication, authorization, input handling, filesystem access, network requests, and secrets.
Do not modify the checkout.
Return findings, evidence, proof gaps, and recommended next actions.この prompt にしておくと、reviewer は confirmed だけでなく needs_review も扱いやすくなります。たとえば「runtime config がないと判断できない」「deployment policy 次第で危険度が変わる」という結果は、コード修正ではなくowner確認に回せます。
PRでそのまま使える最小テンプレート
security-diff-scan は、対象差分と見る観点を短く固定しておくとぶれません。私なら最初は次で十分です。
Use $codex-security:security-diff-scan to review changes from BASE_REVISION to HEAD_REVISION.
Focus on authentication, authorization, input handling, filesystem access, network requests, and secrets.
Do not modify the checkout.
Return confirmed findings, proof gaps, and concrete next actions.このテンプレートの狙いは、PR review を security lane へ寄せつつ、通常の設計議論や lint 指摘を混ぜないことです。通常の PR comment や @codex review は Codex code review 実践ガイド に戻し、Security plugin には「今回の変更で危険が増えたか」だけを見せる方が運用が安定します。
deep scan は節目の精査に残す
deep scan は標準scanより遅く、より包括的に見るためのworkflowです。通常のPRごとに使うものではありません。公式docsでも、pull request や diff は change-review workflow を使い、deep scan は repository や folder のより徹底した確認に使うと整理されています。
私は deep scan を次の場面に絞ります。
| 場面 | deep scan を使う理由 |
|---|---|
| 認証・課金・権限まわりの大改修後 | 通常reviewでは見落としやすい trust boundary を見直す |
| 新しいMCP serverを公開する前 | tool、resource、prompt、OAuth、session の境界が増える |
| 外部監査前の内部棚卸し | 既知の proof gap と hardening 候補を整理する |
| インシデント後の再発防止 | local fix で足りるか、構造的hardeningが必要かを見る |
deep scan の結果は、findings だけでなく coverage summary から見ます。どれだけ時間をかけても、見られていない surface があるなら「問題なし」とは言えません。逆に、coverage が明確なら、外部監査や社内レビューへ渡す説明資料として使いやすくなります。
deep security scan を毎回使わない理由
codex deep security scan で検索して辿り着く読者は、deep scan の方が上位互換に見えがちです。ですが実務では、重い scan を毎回回すほど判断が速くなるわけではありません。
- PR差分 review で既存負債まで混ざる
- findings は増えるが、今回の merge 可否が見えにくくなる
- deferred surface が残ると「深く見たのに未確定」が増える
- 開発フローに常設すると、team が結果を読み切れなくなる
deep security scan は「重要領域を丁寧に見る日」に残し、普段の PR は diff scan を標準化した方が、CTR だけでなく読者の実務再現性も上げやすいです。
backlog triage は「修正するかどうか」を決める前段に置く
既に SAST、Dependabot、GitHub code scanning、社内ticket、外部報告が溜まっている場合、いきなり修正へ進むと失敗します。古いversion、到達不能path、test fixture、未出荷surface まで同じ優先度で扱うと、重要なfindingが埋もれます。
Codex Security plugin の triage-finding は、既存findingを未証明の主張として扱い、repository evidence から confirmed、needs_review、not_actionable に分けるworkflowです。ここが通常scanと違います。新しい脆弱性を探すのではなく、既存backlogの信頼度と優先順位を整理します。
私なら、backlog triage の出力を次のように扱います。
| verdict | 次の扱い |
|---|---|
| confirmed | owner が受け入れたら fix-finding へ進める |
| needs_review | runtime evidence、product policy、deployment context を確認する |
| not_actionable | 根拠をticketへ残し、同じfindingが戻らないようにする |
大事なのは、needs_review を放置しないことです。これは「危険ではない」ではなく、「静的証拠だけでは決められない」です。実行証拠が必要なら bounded validation、仕様判断が必要ならowner判断へ分岐させます。
backlog を詰まらせない運用メモ
backlog triage は地味ですが、Security plugin を運用に乗せるうえで最も詰まりにくい入口です。私なら次の順番にします。
- 同じ rule 由来の finding を束ねる
confirmedだけを remediation queue に送るneeds_reviewは owner と必要証拠を 1 行で残すnot_actionableは根拠ごと close して再燃を防ぐ
この整理を先にやっておくと、fix-finding を呼ぶときに「何を直す task なのか」が濁りません。
fix-finding は1件ずつ小さく流す
修正workflowは便利ですが、複数findingをまとめて直すとレビュー不能になりやすいです。Codex Security plugin の fix workflow は、accepted finding に対して、issue の検証、focused patch、regression coverage、verification を返す設計です。
私なら、次の条件を満たすまで Apply patch locally やPR化に進めません。
- finding が本当に accepted になっている
- patch がそのfindingだけを直している
- regression test が exploit path か近い不変条件を見ている
- verification command が成功している
- 残る proof gap がPR本文に書ける
特に避けたいのは、security fix の名目で大きなリファクタを混ぜることです。脆弱性修正は「小さいほど安全」です。構造変更が必要なら、fix-finding のpatchではなく hardening proposal として別の設計reviewに回します。
CIに入れるなら「読むだけ」と「直す」を分ける
CIでいきなり自動修正まで走らせるより、最初は diff scan を read-only にします。
security-review:
on: pull_request
behavior:
- checkout base and head
- run security-diff-scan
- upload report.md / findings.json
- comment summary
- do not modify checkoutこの段階では、CIの役割は「merge前にreviewerへ証拠を渡すこと」です。patch生成は、人間がfindingをacceptedにしてから別taskで流します。
自動修正まで組み込む場合も、次の境界を残します。
| 境界 | 理由 |
|---|---|
| findingごとに別task | patchを小さく保つ |
| checkoutを汚す前にdiff artifactを保存 | 生成patchと適用後差分を比較する |
| regression test必須 | 直った理由を説明できるようにする |
| normal review processへ戻す | security plugin の結果だけでmergeしない |
Codex Security はレビューを速くしますが、merge判定の責任を消すものではありません。
Security plugin と隣接記事の役割分担
主戦場クラスター内で混ざりやすいので、役割を先に固定しておきます。
| テーマ | この記事が担当する範囲 | 別記事へ逃がす範囲 |
|---|---|---|
| Security plugin | security-diff-scan、deep security scan、triage、fix | Codex code review 実践ガイド の通常 PR review |
| auto-review | approval request の reviewer 差し替えではない | Codex auto-review ガイド の runtime reviewer 境界 |
| sandbox / approvals | scan 実行時の最小権限の考え方だけ触れる | Codex sandbox / approvals 設計ガイド の権限設計本体 |
| merge 前確認 | findings の扱いまでは触れる | Codex レビュー完了ゲート設計ガイド の受け入れ判定 |
この役割分担を冒頭で明示しておくと、codex security plugin で来た読者が approval や code review の総論へ流されにくくなります。
sandbox / approvals と混ぜて考えない
Codex Security plugin は脆弱性レビューの道具です。Codex の sandbox、approval、network allowlist の代替ではありません。
たとえば、次のように分けます。
| 論点 | 見る場所 |
|---|---|
| Codex がどこへ書けるか | sandbox / permissions profile |
| 外部通信を許すか | agent internet access |
| PR差分に脆弱性が増えたか | security-diff-scan |
| 既存findingが本当に有効か | triage-finding / validation |
| 修正patchが妥当か | fix-finding + code review |
ここを混ぜると、「Codex Security を通したから full access でよい」のような誤解が起きます。逆です。セキュリティscanをする作業ほど、checkout、secret、network、external issue tracker への書き込み権限は狭く始めるべきです。
最小運用テンプレート
小さなチームなら、最初はこの程度で十分です。
weekly:
- standard scan for one important repository or folder
- review report.md and coverage.json
- accept at most 3 findings for remediation
pull_request:
- run security-diff-scan from merge-base to head
- comment confirmed and needs_review findings
- do not auto-apply patches
backlog:
- triage old SAST / Dependabot / advisory items
- close not_actionable with evidence
- escalate needs_review with explicit proof gaps
remediation:
- one accepted finding per Codex task
- require focused regression coverage
- merge through normal PR reviewこのテンプレートの目的は、完璧なセキュリティ体制を作ることではありません。AIエージェントが作る差分を、少なくとも「何を見たか」「何を見ていないか」「どのfindingを本当に直したか」まで説明できる状態にすることです。
まとめ
Codex Security plugin は、通常の実装agentとは別の review lane として使う方が安定します。
通常scanで地図を作り、PRでは diff scan に絞り、重要領域だけ deep scan する。既存backlogは triage で優先順位を付け、accepted finding だけを小さく fix-finding に流す。この順番なら、セキュリティレビューを開発フローに入れても、PRが巨大化しにくく、説明責任も残せます。
私なら、最初の導入目標は「全脆弱性を見つける」ではなく、「PR差分と既存backlogを、根拠付きで分類できる状態にする」に置きます。そこまでできて初めて、deep scan や自動修正を広げる価値があります。