Codepatrol

セキュリティ調査スキル手順書

リポジトリのソースコードを領域ごとにセキュリティ観点で調査し、レポートを出力する。 複数sessionにまたがる長期作業を前提とし、実行するたびに現状を確認して続きの作業を行う。

ファイル構成

{このSKILL.mdがあるディレクトリ}/
  SKILL.md               ← この手順書
  CHECKLIST.md           ← 汎用の観点リスト（マスターコピー）
  REPORT-TEMPLATE.md     ← レポートテンプレート
  checklist-vs-report.md ← checklistとレポートの責任境界（何を書き何を書かないか。手順2/4/5が参照）

.dev/codepatrol/
  config.md            ← レポートの書き出し先設定（手順2で生成）
  checklist.md         ← 観点リストの作業用コピー（CHECKLIST.md を元にリポジトリに合わせて生成）
  targets.md           ← 調査対象リスト（自動生成、手動編集可）
  {領域名}.md          ← 領域ごとの調査レポート（書き出し先がローカルの場合）

手順

手順1: 状態確認

以下の存在を確認する:

1. .dev/codepatrol/ ディレクトリ
2. .dev/codepatrol/targets.md（調査対象リスト）
3. .dev/codepatrol/config.md（レポートの書き出し先設定）
4. .dev/codepatrol/checklist.md（観点リストの作業用コピー）

手順2: 初期セットアップ

targets.md がない場合、または「調査対象リストを更新しろ」と指示された場合

サーバー側のエントリポイントを走査して調査対象リストを自動生成する。 自動検出の対象はサーバー側に限定している。 client/config/infraなど他の領域が必要な場合は、ユーザーがtargets.mdに手動で追加する。

Bashツールで以下を実行してメタデータを取得する:

git rev-parse --short HEAD

次に、リポジトリの構成を調査して調査領域を検出する:

1. package.json、Gemfile、go.mod等からフレームワークとサーバー側コードの位置を把握する
2. サーバー側のエントリポイント、つまり外部からの入力を受け付ける箇所を列挙する。リポジトリに存在するものだけでよい:
   • HTTPルーティングと、それが参照するcontroller・ハンドラ群
   • WebSocket等のリアルタイム通信のハンドラ群
   • 認証・認可・CSRF・rate limit等の横断的なmiddleware・フィルタ
   • webhook受信、バッチ・ジョブ等、上記に含まれない外部入力の入口

検出した領域を .dev/codepatrol/targets.md に書き出す。フォーマット:

# Codepatrol Investigation Targets

Generated at: {YYYY-MM-DD HH:mm:ss}
Generated by: {Agent名 (model名)}, with {外部Agentの実行環境}
Source commit: {short hash}

各H2見出しが調査領域名。この名前がそのままレポート名になる。
領域を追加・分割・統合する場合はこのファイルを手動で編集する。

## {領域名}

{対象ディレクトリ/ファイルのパス}
{主なファイルの列挙}

領域のグルーピング指針:

• controller・ハンドラを収めたディレクトリは原則1ディレクトリ = 1領域
• 単体ファイルのcontrollerは関連するものをまとめてよい
• 認証・認可等の横断的なmiddleware・フィルタは1領域にする
• WebSocket等のリアルタイム通信は1領域にする
• 領域名はファイル名やページタイトルの一部になるため、英数字・ハイフン・アンダースコアに収め、パス区切りや空白を含めない

targets.md の更新時: 既存のtargets.mdが存在する場合は、Readツールで読み込み、新しい走査結果と比較する。

• 既存のH2見出し（領域名）は保持する。ユーザーが手動で分割・統合した結果を壊さない
• 既存のH2見出し配下の説明文は、走査結果に基づいて最新化してよい
• 新たに検出された領域はH2見出しを末尾に追加する
• 走査結果に該当しなくなった領域（ディレクトリ削除等）は削除せず残す。ユーザーが判断して削除する

config.md がない場合

レポートの書き出し先を決めて .dev/codepatrol/config.md に記録する。

1. AskUserQuestionツールで書き出し先をユーザーに確認する:
   • Cosenseに集約する — レポートをCosenseのページとして作成し、hubページに被リンクで集約する。チームでの共有・議論に向く
   • ローカルファイル — .dev/codepatrol/{領域名}.md に書き出す
2. Cosenseの場合は、project URLとhubページ名（例: {プロダクト名} セキュリティレポート）をユーザーに確認する
3. config.mdに記録する。フォーマット:

# Codepatrol Report Destination

レポートの書き出し先設定。SKILL.mdの手順3（進捗確認）と手順6（レポート出力）が参照する。

- 書き出し先: {Cosense または ローカル}
- project URL: {https://scrapbox.io/プロジェクト名}
- hubページ: {hubページ名}
- レポートページのタイトル規則: `{hubページ名} {YYYY/M} ({領域名})`
  - 年月はレポート作成時点、月はゼロ埋めなし（例: 2026/7）
- 前提: cosense CLI（`npm install -g @helpfeel/cosense-cli`）のインストールとログイン

ローカルの場合は「書き出し先: ローカル」だけを記録する。

checklist.md がない場合

このSKILL.mdと同じディレクトリにある CHECKLIST.md は、特定のリポジトリに依存しない汎用の観点リストである。 そのままコピーせず、リポジトリの実装に合わせてカスタマイズした作業用コピーを生成する:

1. CHECKLIST.md をReadツールで読み込む
2. リポジトリのセキュリティ機構を調査する。認可middlewareとロール階層の具体名、テナント境界の単位（プロジェクト・チーム・組織等）、認証・session管理の方式、テンプレートエンジンとクライアント描画の方式、DBアクセス層、ファイルストレージ、外部にリクエストを送る箇所、rate limitの実装、課金等のビジネスロジック
   • この調査の目的は観点に具体名を補うことであり、脆弱性の発見自体は手順4で行う。個々の実装の深追いはしない
   • 既存の領域レポート（書き出し先のレポートページ、またはローカルの .dev/codepatrol/{領域名}.md）があれば情報源として活用する
3. 調査結果に基づいて各観点をカスタマイズし、Writeツールで .dev/codepatrol/checklist.md に書き出す:
   • 冒頭に Source commit: {git rev-parse --short HEAD の出力} と Generated by: {Agent名 (model名)}, with {外部Agentの実行環境} を記録する。構成把握がどの時点・どのmodelによるものかを診断可能にする
   • 調査で把握した機構の要約を、冒頭に「このリポジトリのセキュリティ機構」セクションとしてまとめる。ライブラリはバージョン数字を省いて名前だけ書く
   • 各観点の説明に、このリポジトリでの具体名（middleware名、関数名、ディレクトリ等）を補う
   • リポジトリに存在しない仕組みに関する観点は削除する（例: WebSocketを使っていなければA5・E2を削除）
   • リポジトリ固有の仕組みに対する観点は、該当カテゴリの末尾に番号を続けて追加する
   • カテゴリの構造（記号+番号）は維持する。レポートの見出しと手順5のグループ分けがこの構造を参照する

checklistの領分: checklistに書くこと・書かないことは checklist-vs-report.md に従う（要点: 仕様・機構の説明と中立な観点だけを書く。特定のbugの断定・深刻度・悪用仮説・レポート発見への言及は書かず、レポートへ）。生成時にこの境界を守る。

checklist.md が既にある場合（更新）

「観点リスト（チェックリスト）を更新しろ」と指示された時、または既存の .dev/codepatrol/checklist.md を調査で使う前に、次を行う:

1. Readツールで既存の .dev/codepatrol/checklist.md を読み込む
2. リポジトリの機構を再走査し、観点の追加・更新を行う（手順は上の「checklist.md がない場合」に準じる）
3. checklist-vs-report.md の責任境界に照らし、境界に合わない記述（既に入り込んだbug断定・深刻度・悪用仮説・レポート発見への言及）があれば、仕様事実または中立な観点に書き直す（または削除する）。観点の追加・更新と合わせて行う

生成したリストの外部Agentレビュー

targets.mdまたはchecklist.mdを生成・更新したら、両方をファイルに書き出した上で、2つまとめて外部Agentにレビューさせる。 一方だけを更新した場合も、両方を渡す。

Skill toolで codex-consultation を呼び出す。Argsには以下を含める:

よく相談して。このリポジトリの開発チームが、自分たちのコードの不具合を見つけて修正するためにセキュリティ調査をしている。その調査に使う調査対象リストと観点リストを作成した。以下の2つのファイルをレビューしてほしい。

- 調査対象リスト: .dev/codepatrol/targets.md — 見落としているエントリポイント、領域の分け方と粒度
- 観点リスト: .dev/codepatrol/checklist.md — 見落としている観点、このリポジトリに該当しない観点、観点に補った具体名の誤り

codex-consultationが利用できない場合は、Skill toolで subagent-consultation にフォールバックする。 両方利用できない場合は、レビューを実施できなかった事をユーザーに報告する。

指摘を受けたら自分でコードを読んで検証し、妥当な指摘をファイルに反映する。反映しなかった指摘は、その理由と共にユーザーに報告する。 checklist.mdへの反映は checklist-vs-report.md の境界に従い、bug寄りの指摘は取り込まない。

Generated by には自分のAgent名とmodel名を記入し、レビューを行った場合はconsultation skillが取得した外部Agentの実行環境を併記する。

手順3: 進捗確認と調査対象の選択

1. .dev/codepatrol/targets.md をReadツールで読み込む
2. H2見出しを解析して全領域名のリストを取得する
3. config.mdの書き出し先に応じて、領域ごとの調査状況を把握する
4. 調査済み・未調査の状況をユーザーに報告する

書き出し先がCosenseの場合: hubページに集約された既存レポート（タイトル規則にマッチするページ）から、領域ごとの最新の調査時期を把握する。hubページやマッチするレポートが無ければ全領域を未調査として扱う。

書き出し先がローカルの場合: Globツールで .dev/codepatrol/*.md を検索し、config.md・targets.md・checklist.md を除いた .md ファイルが存在する領域を「調査済み」と判定する。ローカルモードは調査時期を保持しないため、調査済み・未調査の区別のみを報告する。

進捗判定はレポートの存在（Cosenseでは加えて年月）のみで行う。コードの変更内容から再調査の要否を推定しない。

ユーザーが調査対象の領域を明示指定している場合: 調査済み・未調査を問わずその領域を調査する。以下の選択フローはスキップする。

全領域にレポートがある場合: Cosenseモードでは、最終調査が最も古い領域を再調査候補として提案し、ユーザーに確認する。ローカルモードでは調査時期が分からないため、どの領域を再調査するかユーザーに尋ねる。

未調査の領域がある場合: AskUserQuestionツールで調査対象を選ばせる。認可・認証・外部通信に関わる領域を優先して提案する。未調査領域が多くAskUserQuestionの選択肢（2-4個）に収まらない場合は、まず選び方（次を提案してほしい / 領域名を直接指定 / targets.mdを見直す）を聞いてから絞り込む。

手順4: 調査の実行

1. .dev/codepatrol/checklist.md をReadツールで読み込む
2. 選択された領域のコードを読む:
   • targets.md に記載されたファイルパスを起点にする
   • 必要に応じてGlob/Grepツールで関連ファイルを探索する
   • エントリポイント → 内部ロジック → データ層の順にデータフローを追う
3. チェックリストの各観点を当てる:
   • 該当する観点のみ調査する（全観点が全領域に該当するわけではない）
   • 各観点について、問題の有無と根拠を記録する
   • 問題を発見した場合は、具体的なコード箇所（ファイルパス:行番号）を特定する
   • 作業用checklist.mdの記述（機構の要約・具体名）と実装の齟齬を見つけたら、その場でchecklist.mdを修正する。ただし修正は機構・仕様の事実レベルに留め、発見したbug自体はchecklistに書かずレポートへ書く（checklist-vs-report.md 参照）

調査の深さ:

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

手順5: 外部Agentによる批判的レビュー

手順4の調査結果を外部Agentに批判させ、漏れ抜けを検出する。 批判的思考の連鎖により、単独調査では見落とす脆弱性を発見できる。

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

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

各グループについて、Skill toolで codex-consultation を呼び出す。Argsには以下を含める:

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

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

チェックリストに載っていない観点も積極的に指摘してほしい。
検証でコードを動かす場合は、リポジトリ外の一時ディレクトリで行い、外部サービスには接続しないでほしい。

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

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

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

codex-consultationが利用できない場合は、Skill toolで subagent-consultation にフォールバックする。 両方利用できない場合はこの手順をスキップし、レポートの総合評価にその旨を記載する。

外部Agentの指摘を受けたら:

• 指摘内容を自分でコードを読んで検証する
• 妥当な指摘は手順4の調査結果（＝レポートに書く発見）に反映する。外部Agentの指摘はbug寄りなので、checklistには取り込まない（取り込むとchecklistが発見リスト化し、次回以降の調査を特定箇所へ誘導してしまう。checklist-vs-report.md 参照）
• 異なる見解がある場合は両方の理由をレポートに記載する

手順6: レポートの出力

Bashツールで以下を実行してメタデータを取得する:

git rev-parse --short HEAD

このSKILL.mdと同じディレクトリにある REPORT-TEMPLATE.md をReadツールで読み込み、その構成に従ってレポートを作成する。 Investigatorには自分のAgent名とmodel名を記入し、手順5で外部Agentを使った場合はconsultation skillが取得した実行環境を併記する。

書き出し先がCosenseの場合:

タイトル規則と同名のページが既にないか確認する。ある場合（同月の再調査等）は上書きせずユーザーに対応を確認し、確認できなければ作成を保留して報告する。

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

• 1行目: タイトル規則に従うページ名（現在の年月を使う。月はゼロ埋めなし）
• 2行目: [{hubページ名}] — hubページへのリンク。これで被リンクとして集約される
• 3行目以降: REPORT-TEMPLATEの構成を、見出しをインデント階層で表したCosense記法の本文（記法はcosense skillに従う）。テンプレート内のHTMLコメントや {プレースホルダ} は出力せず、Investigated at はタイトルの年月とページのメタデータが持つので書かない

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

cosense CLIが使えない、または書き込みに失敗した場合は、ローカルに書き出してその旨を報告する。

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

Writeツールで .dev/codepatrol/{領域名}.md に書き出す。

いずれの場合も、レポート出力後に発見事項の要約をユーザーに報告する。

関連スキル

• codex-consultation: Codex CLIと相談するスキル。手順2のリストレビューと手順5の批判的レビューで使用する
• subagent-consultation: Agentツールと相談するスキル。codex-consultationが利用できない場合のフォールバック先
• sanity-review: PRのレビュー報告書を作成するスキル。セキュリティ調査で発見した問題の修正PRをレビューする際に使用できる
• conversation-context-export: 対話コンテキストを書き出すスキル。レポートのヘッダー形式を参考にした