Codex を GitHub PR のレビューに入れると、次に迷うのは「通常の @codex review と Security Review をどう分けるか」です。どちらも PR にコメントを返します。どちらも差分を読みます。けれど、目的を混ぜると、通常レビューに脆弱性診断の深さを期待したり、Security Review の finding をただの参考コメントとして流したりします。
この記事では、Codex Security Review を PR 上の security-specific review lane として設計する方法に絞ります。通常の @codex review と AGENTS.md review guidelines は Codex code review 実践ガイド、Codex Security plugin / scan workflow は Codex Security plugin 実践ガイド、terminal / CI で scan を再現する話は Codex Security CLI 実践ガイド、最終的に差分を受け入れる gate は Codex レビュー完了ゲート設計ガイド に分けています。
今回扱うのは、2026年8月30日時点の OpenAI 公式ドキュメントを前提に、@codex security review、Security Report tab、threat model、reporting threshold、finding triage、人間の merge 判断 をどうつなぐかです。
先に結論: Security Reviewは通常レビューの強化版ではない
Codex Security Review は、通常の Code Review より「強いレビュー」を常に回すための機能ではありません。PR 差分を、security-specific risk に寄せて見るための別 lane です。
私なら、最初に次のように分けます。
| 目的 | 使うもの | 見るもの |
|---|---|---|
| 回帰、missing test、危険な仕様変更を見る | @codex review | PR diff、AGENTS.md review guidelines |
| 認可、secret、攻撃経路、trust boundary を見る | @codex security review | PR diff、repo context、threat model |
| 手元やCIで scan artifact を残す | Codex Security CLI | report、findings、coverage、SARIF |
| Codex内のsecurity workflowを使う | Codex Security plugin | scan、triage、fix workflow |
Security Review を入れるべき PR は限られます。auth、permission、billing、CI、secret、MCP、外部 API write、data migration のように、見落とすと事故の影響が大きい差分です。
逆に、docs-only、copy 修正、formatter 差分、小さな CSS 調整に毎回 Security Review を走らせると、レビュー待ちと通知だけが増えます。Security Review は広く薄くではなく、危険な差分へ狭く深く使います。
@codex security review で手動起動から始める
OpenAI の GitHub integration docs では、PR コメントに次を置くと Security Review を手動起動できると説明されています。
@codex security reviewCodex は実行中に反応し、manual reporting threshold を満たす finding を PR に投稿します。詳細は関連する Codex task の Security Report tab で確認します。PR コメントだけで判断せず、full report 側の severity、attack path、supporting evidence、validation、remediation guidance まで見ます。
最初は automatic ではなく manual から始める方がよいです。手動で 5 本ほど通すと、どの PR で有効か、どの finding が noise になりやすいか、どの threat model 情報が足りないかが見えます。
@codex security review
Focus on:
- authorization bypass
- token or secret exposure
- unsafe CI workflow permissions
- user-controlled input reaching external writesこのように一回限りの focus を添えてもよいです。ただし、毎回長い指示を書く運用は続きません。安定してきたら threat model と repository guidance に寄せます。
threat model を置かないと shallow review になりやすい
Security Review の価値は、差分を単体で眺めることではありません。どの asset が重要で、どの trust boundary を越えると危険で、どの attacker input が現実的かを踏まえて見ることです。
OpenAI の Security Review docs では、application assets、trust boundaries、security assumptions、repository-specific risks を Codex に渡す threat model context を設定できると説明されています。既に Codex Security scan configuration があればその threat model を使い、なければ repository 内の threat model file を指定できます。指定しない場合、review ごとに threat model を再生成します。
私なら、最初の threat model は短く作ります。
# Threat Model
## Assets
- User account data
- OAuth tokens and refresh tokens
- Billing records
- Admin-only operations
## Trust Boundaries
- Public web request -> application server
- Application server -> database
- GitHub Actions runner -> deployment environment
- MCP tool call -> external SaaS API
## Security Assumptions
- Browser input and PR comments are untrusted.
- Pull requests from forks must not receive write tokens.
- Admin actions require server-side role checks.
- Payment and permission changes require audit logs.
## High-Risk Paths
- Auth middleware
- Webhook verification
- CI workflow permissions
- Token storage and redaction
- External write toolsきれいな図より、review が使える前提の方が重要です。Security Review は「このコードは危ないか」だけでなく、「このシステムではどの危なさが本当に痛いか」を見る必要があります。
reporting threshold はPRの可視性込みで決める
Security Review で見落としがちな設定が reporting threshold です。OpenAI docs では、automatic review は既定で High / Critical finding を報告し、manual review は Medium / High / Critical finding を報告すると説明されています。閾値は automatic と manual で別々に変更でき、path-based override も設定できます。
ここで大事なのは、PR に投稿された finding はその PR の GitHub visibility を引き継ぐことです。public repository や外部 contributor が見える PR では、詳細な attack path をそのまま広く出すと、修正前の情報を公開することになります。
私なら、最初はこう分けます。
| repository | manual threshold | automatic threshold | 理由 |
|---|---|---|---|
| private production repo | Medium | High | 手動では広く見て、常時投稿は絞る |
| public repo | High | Critical | 公開PRへ詳細を出しすぎない |
| security-sensitive package | Medium | High | path override で対象を限定する |
| docs / marketing repo | High | Critical | noise を抑える |
threshold は「どの finding を存在させるか」ではなく、「どの finding を GitHub に投稿するか」の設定です。full report にはより多くの情報が残るため、PR コメントだけを見て「問題なし」と言い切らない方が安全です。
automatic review は3段階で広げる
OpenAI docs では、Security Review を PR open、every push、code review と同時実行などのタイミングで構成できます。ただし、導入初日から every push にする必要はありません。
私は次の順で広げます。
| 段階 | 設定 | 目的 |
|---|---|---|
| week 1 | manual only | finding の質と threat model の不足を見る |
| week 2 | on PR open for selected repos | 初回差分で高リスクを早めに浮かせる |
| week 3+ | whenever code review runs for risky paths | 通常 review と security review を並走させる |
every push は便利ですが、PR が活発に更新されるほど finding の重複や費用、通知量が増えます。最初は PR open か manual で十分です。auth や CI workflow の path だけ override する方が、全体に広げるより定着しやすいです。
finding はPRコメントだけで処理しない
Security Review の finding は、通常の code review comment と同じ扱いにしない方がよいです。PR 上では短い指摘に見えても、Security Report tab には attack path、evidence、validation、remediation guidance が含まれます。
私なら、finding を次の状態へ必ず分類します。
| 状態 | 意味 | 次の動き |
|---|---|---|
| confirmed | 実際に修正が必要 | このPRで直すか、緊急別PRへ切る |
| needs_context | deployment や設定次第で変わる | owner に前提確認を戻す |
| false_positive | 前提が違う | 根拠を残し、threat model を直す |
| accepted_risk | 仕様上受け入れる | 期限、owner、再確認日を残す |
| split_out | このPRで直さない | issue / follow-up PR に分離する |
たとえば、CI workflow の token scope が広いという finding が出たとします。すぐ修正できるなら confirmed として直します。fork PR では走らない設計なら false positive にできます。ただし、その根拠を残さないと次の review で同じ指摘が戻ります。
@codex fix に渡す前にscopeを切る
OpenAI docs では、Codex が review を投稿した後、PR コメントで fix を依頼できると説明されています。Security Review の finding でも、修正案や remediation guidance を見て対応できます。
ただし、security finding をまとめて直させるのは危険です。修正が大きくなり、別の regression を作るからです。
悪い依頼はこうです。
@codex fix all security review findings良い依頼は、finding と範囲を1つに絞ります。
@codex fix the High finding about missing webhook signature validation only.
Keep the patch limited to webhook verification and tests.
Do not change billing calculation or retry behavior.Security fix は小さいほどレビューしやすいです。修正後は、通常の code review、CI、必要なら再度 Security Review を通します。Codex Security の patch は自動 merge ではなく、人間の通常 workflow に戻します。
通常のCode Reviewと併用する
OpenAI の Codex Security docs では、Codex Security が提案した patch PR も通常の review process で見ること、remediation が regression を入れないよう Codex Code Review の利用も推奨されています。
この考え方は Security Review でも同じです。Security Review は「脆弱性を見た」証拠にはなりますが、「その修正が仕様を壊していない」証拠にはなりません。
私なら、security finding 修正後の PR では次を通します。
post_security_fix_gate:
required:
- unit_or_integration_test
- normal_code_review
- security_finding_status
- human_owner_decision
optional:
- rerun_security_review
- targeted_manual_reproduction特に auth、billing、data migration は、security patch で正常系を壊しやすい領域です。Security Review と通常 Code Review は、競合ではなく補完です。
public repository ではコメント内容を絞る
Security Review の PR コメントは便利ですが、public repository では扱いが難しくなります。詳細な attack path、証拠、修正前の条件がそのまま外部に見える可能性があるからです。
公開 repo では、私は次の方針にします。
public_repo_security_review:
automatic_threshold: "critical"
manual_threshold: "high"
comment_policy:
- "avoid detailed exploit steps in public PR comments"
- "move sensitive details to private task or maintainer channel"
- "summarize impact without exposing reproduction details"
maintainer_action:
- "open private advisory if needed"
- "prepare patch before detailed disclosure"これはセキュリティ情報を隠すためではありません。修正前の攻撃手順を不要に広げないためです。Open source では透明性も大事ですが、公開タイミングを間違えると利用者に不利益が出ます。
導入時の最小ポリシー
最初に AGENTS.md や repository policy へ置くなら、この程度で十分です。
## Codex Security Review Policy
- Use `@codex security review` for auth, permission, secret, CI, MCP, external write, billing, and migration changes.
- Do not use Security Review as a substitute for tests, branch protection, or human approval.
- Configure a threat model for assets, trust boundaries, and high-risk paths.
- Keep automatic GitHub reporting thresholds conservative on public repositories.
- Classify every finding as confirmed, needs_context, false_positive, accepted_risk, or split_out.
- Scope `@codex fix` requests to one finding at a time.
- Review generated patches through the normal PR process before merge.長いルールより、運用で守れる短いルールを先に置きます。finding が増えたら、path-based override や team-specific threshold を足します。
よくある失敗
通常の @codex review と同じ扱いにする
Security Review は security-specific lane です。通常の readability、test coverage、設計レビューまで期待すると役割が濁ります。
threat model を毎回再生成に任せる
再生成は便利ですが、deployment assumption や社内の risk appetite までは自動で安定しません。asset、trust boundary、high-risk path は repository 側に置いた方がよいです。
public PR に詳細を出しすぎる
finding の visibility は PR の visibility に従います。公開 repo では threshold とコメント内容を慎重に決めます。
automatic review を広げすぎる
every push から始めると、指摘重複と通知量が先に問題になります。manual から始め、対象 repo と path を絞って広げます。
fix 依頼をまとめる
security fix をまとめると、修正差分が膨らみます。1 finding、1 scope、1 verification に切ります。
まとめ
Codex Security Review は、通常の @codex review を少し強くする機能ではありません。PR 差分を security-specific risk と threat model に照らして見るための別 lane です。
最初は manual @codex security review から始める。threat model を短く置く。reporting threshold を PR の可視性込みで決める。finding は Security Report tab まで見て分類する。修正は1件ずつ小さく流し、通常の review process に戻す。
この運用にすると、Codex Security Review は「AIがセキュリティも見た」という曖昧な安心材料ではなく、PR merge 前に本当に見るべき security risk を浮かせる実務的な gate になります。