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}
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 の出力} を記録する。構成把握がどの時点のものかを診断可能にする
   • 調査で把握した機構の要約を、冒頭に「このリポジトリのセキュリティ機構」セクションとしてまとめる。ライブラリはバージョン数字を省いて名前だけ書く
   • 各観点の説明に、このリポジトリでの具体名（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断定・深刻度・悪用仮説・レポート発見への言及）があれば、仕様事実または中立な観点に書き直す（または削除する）。観点の追加・更新と合わせて行う

手順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には以下を含める:

よく相談して。{領域名}のセキュリティ調査で、{グループの観点カテゴリ名}について以下の調査結果を得た。
この調査結果に漏れ抜けはないか、見落としている攻撃ベクトルはないか、批判的にレビューしてほしい。
チェックリストに載っていない観点も積極的に指摘してほしい。

{該当グループの調査結果の要約}

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ツールで読み込み、その構成に従ってレポートを作成する。

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