1つの領域のセキュリティ調査

codepatrol skillの指揮役から任されて、指定された1つの領域を調査し、レポートを出力する。

ファイル構成

{このSKILL.mdがあるディレクトリ}/
  SKILL.md               ← この手順書
  REPORT-TEMPLATE.md     ← レポートテンプレート
  reinvestigation.md     ← 既存のレポートがある領域を再調査した時のレポートの書き方

.dev/codepatrol/
  config.md            ← レポートの書き出し先設定
  checklist.md         ← リポジトリ固有の機構と観点の補足。マスターのCHECKLIST.mdと一緒に読む
  targets.md           ← 調査対象リスト
  {領域名}-{YYYY-MM-DD}.md  ← 領域ごとの調査レポート（書き出し先がローカルの場合）

checklistとレポートの責任境界は checklist-vs-report.md にある。

このskillを実行する時の前提

• 実行環境の条件は codepatrol skill の「実行環境の確認」と同じである。調査に入る前に自分でも確認し、満たさなければ調査もレポートの出力も行わず、満たさない条件を報告して終了する
• ユーザーに質問できない。判断がつかない事は、最後の報告に書く
• リポジトリごとのコードを読む場所と、.dev/codepatrol/ の場所は、指揮役の指示に従う。branchの切り替え・pull・commitはしない
• 他の領域を調査するsubagentが、同じ作業ツリーで並走している事がある

既存の問題を調査から離す

調査とcodex-consultationによるレビューは、既存の問題を知らない状態で行う。先に読むと、調査が既存の問題の箇所へ誘導され、前回見逃した問題を再び見逃す。checklistに問題を書かないのと同じ理由である。

• レビューが終わるまで、既存のレポートの本文、問題の名前の一覧、問題を直した修正PR、問題をまとめたページを読まない。調査する領域の物に限らない。他の領域のレポートにも、この領域の問題が申し送りとして書かれている
• 相談先のCodexにも、既存のレポートを読まないよう依頼する
• 既存のレポートがある領域も、初めて見る領域として調査する。既存の問題を1件ずつ再確認する作業はしない
• 既存のレポートは、レポートを組み立てる時に読む

手順

手順1: 調査の実行

1. マスターの CHECKLIST.md と、.dev/codepatrol/checklist.md を読む。観点はマスターの番号で指し、リポジトリ固有の観点は {カテゴリ記号}+{番号} で指す
2. 指定された領域のコードを読む:
   • targets.md に記載されたファイルパスを起点にする。パスは、その領域のリポジトリのrootからの相対である。関連リポジトリがある時は、lifecycle-* 領域のパスにリポジトリ名が添えてある
   • 必要に応じて関連ファイルを探索する。対になる別のリポジトリの領域のように、データフローを追うのに要るなら他のリポジトリも読む。読んだリポジトリ全てのcommitを、レポートのSource commitに書く
   • エントリポイント → 内部ロジック → データ層の順にデータフローを追う
3. チェックリストの各観点を当てる:
   • 該当する観点のみ調査する（全観点が全領域に該当するわけではない）
   • 各観点について、問題の有無と根拠を記録する
   • 問題を検出した場合は、具体的なコード箇所（ファイルパス:行番号）を特定する

利用終了イベント起点の領域の調査:

lifecycle- で始まる領域では、入口からデータフローを追う代わりに、起点イベント × 資産の対応表を作り、空欄を埋める形で調査する。観点はJ3〜J5が中心で、他のカテゴリは起点イベントの入口に当てる。対応表はREPORT-TEMPLATEの節としてレポートに残す。

• 対応表の行は、checklistの「利用終了時に残りうる資産」節を出発点にし、単位の識別子と、そこから所有関係や生成経路で辿れる間接的な資産を探して補う。一覧を信じると、忘れられた資産は対応表からも漏れる。補った資産は、下の「誤りを見つけた時」の規則に従い、事実としてchecklistに足す
• 処理が無いと判断する時は、探した語と場所を記録する。無い事はコードの行を指せないので、探索の記録が根拠になる

調査の深さ:

• 各観点について、実際にコードを読んで確認する。推測で「問題なし」としない
• ただし、網羅性と深さのバランスを取る。1つの観点に過度に時間をかけず、全観点を一通り見ることを優先する
• 簡単な問題（エスケープ追加、middleware追加等、修正方法が明らか）は、レポートに修正内容を具体的に記載する
• 設計変更が必要な問題は、その旨をレポートに記載し、別途検討を推奨する

checklist.md と targets.md の誤りを見つけた時:

担当する領域に関する記述と実装の齟齬を見つけたら、その場で直す。

• 直すのは機構・仕様の事実だけにする。検出した問題はchecklistに書かず、レポートへ書く（checklist-vs-report.md 参照）
• 並走するsubagentも同じファイルを編集する。編集の直前に読み直し、最小限の置換で直す。ファイル全体を書き直さない
• 足すべき観点や領域に気づいても、自分では足さず、最後の報告に書く

手順2: codex-consultationによる批判的レビュー

手順1の調査結果を、codex-consultationを通じてCodexに批判させ、漏れ抜けを検出する。 批判的思考の連鎖により、単独調査では見落とす問題を検出できる。 この手順は省略も代替もできない。codex-consultationでのレビューを経ていない調査結果はレポートにしない。

Codexに相談する時は、必ずSkill toolで codex-consultation を呼び出す。codex exec の直接実行で済ませない。

観点のカテゴリを2〜4グループに分け、グループごとにcodex-consultationを呼び出す。調査対象が小さく該当観点が少ない領域では、1グループにまとめて1回で相談してよい。グループ分けの目安:

• 権限系: 認可、トークン・共有URL、認証・セッション等
• 入出力検証系: SSRF、XSS、インジェクション等
• その他: ファイル、DoS、情報漏洩、ビジネスロジック、設定等

lifecycle-* 領域では、観点のカテゴリではなく、対応表のイベントや資産の区分で分けてよい。

Argsには以下を含める:

Args: よく相談して。このリポジトリの開発チームが、自分たちのコードの問題を検出して修正するために{領域名}のセキュリティ調査をしている。
{グループの観点カテゴリ名}について以下の調査結果と修正案を得た。防御側のレビューとして次の点を批判的に見てほしい。

- 調査結果に漏れ抜けはないか、修正案は十分か
- 修正によって壊れる正規の利用フローはないか
- 追加すべき回帰テストは何か。テストフレームワークのテストケース単位で挙げてほしい

観点はマスター {CHECKLIST.mdの絶対パス} と、リポジトリ固有の層 {.dev/codepatrol/ の絶対パス}/checklist.md にある。載っていない観点も積極的に指摘してほしい。
コードは {リポジトリごとの絶対パス} にある。
既存の調査レポートは読まずにレビューしてほしい。
検証でコードを動かす場合は、リポジトリ外の一時ディレクトリで行い、外部サービスには接続しないでほしい。

{該当グループの調査結果と修正案の要約}

依頼の枠組み: Codexの提供元のセキュリティフィルタは、依頼の語彙で判定する。「見落としている攻撃ベクトルはないか」のように攻撃側の語彙で依頼すると、Codexが調査を拒否したり、調査を終えた後の最終回答の生成だけがブロックされて異常終了したりする。 上のテンプレートのとおり、調査の目的が自分たちのコードの修正である事を最初に説明し、修正案のレビューと回帰テスト案を問う形で依頼する。調査結果の要約でも「攻撃」「悪用」「偽造」といった語を避け、問題とその修正として記述する。 codex-consultationが組み立てるプロンプトや2往復目のプロンプトにも、この枠組みを引き継ぐ。

それでも最終回答がブロックされた場合は、Codexの実行ログに残った検証コマンドとその出力から指摘を拾う。その上で、防御側の枠組みをより明確にして再依頼する。

Codexの出力を残す: Codexの出力は、指揮役から渡された作業用ディレクトリに残す。指揮役が、相談が最後まで完了した事を確かめるのに使う。

Codexが停止した場合: usage limit・spend cap・認証エラー・通信障害等でCodexが最終回答を返さずに終了した場合は、subagent-consultation や自分自身の再検討で代替せず、レポートも出力せずに作業を中断する。

• 通信障害のような一時的なエラーなら、数分待って1〜2回は再試行してよい。usage limitやspend capはすぐには解消しないので再試行しない
• 中断する時は、手順1の調査結果と、完了したグループのCodexの指摘・その検証結果を、作業用ディレクトリに書き出す。どのグループまで終わり、何のエラーで止まったかを報告して終了する
• 再開を任された時は、書き出した調査結果を起点に、残りのグループから続ける

Codexの指摘を受けたら:

• 指摘内容を自分でコードを読んで検証する
• 妥当な指摘は調査結果に反映する。checklistに反映するのは、自分で確かめた機構・資産の事実だけにし、問題の断定は反映しない
• 異なる見解がある場合は両方の理由をレポートに記載する

手順3: レポートの出力

REPORT-TEMPLATE.md を読み込み、その構成に従ってレポートを作成する。 Investigatorには自分のAgent名とmodel名を記入し、codex-consultationが取得したCodexの実行環境を併記する。

既存のレポートとの突き合わせ:

レポートを組み立てる前に、既存のレポートを読み、今回の問題と突き合わせる。

• 他の領域の最新のレポートにある問題の名前を確認する。同じ問題に別の名前を付けないためである。指揮役から問題の名前の一覧を渡されている場合は、それを使う。自分の問題と同じ問題に既に名前が付いていれば、REPORT-TEMPLATEの「他領域の問題への参照」に従って書く
• 担当する領域に既存のレポートがある場合は、reinvestigation.md を読み込み、それに従う

書き出し先がCosenseの場合:

レポート全体を1つのテキストとして組み立てる:

• 1行目: config.md のタイトル規則に従うページ名。日付はページを作る日である。同名のページが既にある時は、上書きせず、日付に時刻を続けて別のページを作る
• 2行目: [{hubページ名}] — hubページへのリンク。これで被リンクとして集約される
• 3行目以降: REPORT-TEMPLATEの構成を、見出しをインデント階層で表したCosense記法の本文（記法はcosense skillに従う）。テンプレート内のHTMLコメントや {プレースホルダ} は出力せず、Investigated at はタイトルの日付とページのメタデータが持つので書かない

組み立てた本文で新規ページを作成する（書き込み操作はcosense skillに従う）。

書き込みに失敗した場合は、レポートを作業用ディレクトリに書き出し、その旨を報告する。

書き出し先がローカルの場合:

.dev/codepatrol/{領域名}-{YYYY-MM-DD}.md に書き出す。日付は、レポートを書き出す日である。同名のファイルが既にある時は、上書きせず、{領域名}-{YYYY-MM-DD}-{HHmm}.md のように日付に時刻を続けて別のファイルを作る。

指揮役への報告

• 作成したレポートの場所とタイトル、読んだリポジトリごとのcommit
• 問題の一覧。深刻度・名前・1行の要約。再調査の場合は、前回も報告された問題か、今回新規の問題か
• 再調査の場合は、前回から修正された物と、今回検出しなかった前回の問題
• 他の領域と重なりそうな問題の名前と、そのファイル
• 実環境の確認が要る項目
• Codexに相談した回数と観点のグループ、採用した指摘と採用しなかった指摘、Codexの出力の場所
• checklist.md と targets.md を直した箇所と、直さなかったが足すべき観点・領域
• 手順や規則で、曖昧だった点とやりにくかった点
• 中断した場合は、中断の理由と途中結果の場所