Codex で実装を進めるチームが増えると、次に詰まるのは「作らせた差分をどう安全に受け入れるか」です。通常のレビューでは仕様漏れやテスト不足は拾えても、認可、入力検証、secret、filesystem、network request のようなセキュリティ観点は後回しになりがちです。
この記事では、Codex Security plugin をどの作業に使い、どこでは使わないかを整理します。Codex の実行権限そのものは Codex sandbox / approvals 設計ガイド、agent phase の外部通信は Codex internet access 安全運用ガイド、Codex が出した差分を受け入れる最終確認は Codex レビュー完了ゲート設計ガイド、組織ルール化は AIコーディングツールの社内ガイドライン に分けています。
今回の論点は、脆弱性を探す・検証する・優先順位を付ける・修正する流れを、Codex の普段の開発フローへどう接続するかです。
先に結論: 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したのかで、残るリスクが違うからです。
通常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確認に回せます。
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 が明確なら、外部監査や社内レビューへ渡す説明資料として使いやすくなります。
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判断へ分岐させます。
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判定の責任を消すものではありません。
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 や自動修正を広げる価値があります。