incu-way-threat-model

脅威モデリングプロセス

現在の作業（計画中の機能、モジュール、API、または現在のブランチの変更）を対象に、システムのデータフローと信頼境界に対して軽量な STRIDE 評価を行い、小規模で焦点を絞った脅威モデルを作成する、ゲート駆動型のワークフローです。目的は、網羅的なエンタープライズ向け成果物ではなく、緩和策につながる実用的で追跡可能なモデルを作成することです。出力先は docs/security/threat-models/{slug}/THREAT-MODEL.md です。

呼び出し方法は 2 通りです。

• 単独（コンポーネントや変更の脅威モデルを作成）： 独自のブランチ assess/threat-{slug} → develop への PR。
• 別のフローに組み込む場合： 呼び出し元の現在のブランチ／ワークツリーに書き込みます。モデルは、そのフローの PR に含まれます。別のブランチや PR は作成しません。例：incu-way-development が Gate 2 で PLAN の直後に脅威モデルを作成し（その結果、緩和策が計画タスクになります）、incu-way-bugs がセキュリティに関連する修正をモデル化する場合。

これは評価フローです。incu-way-docs と同様に、.ways/state.json は管理しません。脅威を特定して緩和策を提案します。緩和策の実装は、呼び出し元のフロー内のタスク、または後続の incu-way-development ／ incu-way-bugs の項目となります。

小規模に保ちます。 変更の規模に合わせてモデルを調整します。新しいエンドポイントが 1 つだけなら、40 ページの文書ではなく、データフロー図 1 つと少数の脅威で十分です。深さはリスクに応じて決めます。

---

リポジトリの適格性チェック（最初に実施）

Phase 0 の前に、現在のリポジトリが ~/.ways/config.yaml の blacklist に含まれているか確認します（形式は incu-base の global-config ルールに従い、常時有効です）。該当する場合、このリポジトリは incu-way のブラックリストに登録されていることをユーザーに伝え、このまま進める（一度限りの例外）か、中止するかを確認します。ユーザーが回答するまで、いずれのフェーズも実行しないでください。ファイルが存在しない場合、または該当しない場合は、通常どおり進めます。

---

Phase 0 — スコープと分解

目標： 脅威を検討するのに十分な程度に、システムの対象部分を理解します。読み取り専用です。

インテーク

1. 対象を確認します。計画中の機能（PRD／PLAN に記載）、モジュール／サービス、API、または現在のブランチの差分（新しいコード）のいずれかです。
2. まず関連するコンテキストを読みます。開発フローに組み込まれている場合は PRD／PLAN、既存の docs/architecture/、過去の脅威モデル、CLAUDE.md のセキュリティセクション、および存在する場合は VALIDATION.md（incu-way-security-validation を参照）です。

対象の分解

コード／設計を根拠として、以下を特定します。

• 資産 — 保護する価値のあるもの（PII、認証情報、決済データ、トークン、資金移動、記録の完全性、フローの可用性）。
• アクター — 関与するユーザー（エンドユーザー、管理者、匿名の呼び出し元、内部サービス、サードパーティ）と、その権限レベル。
• エントリーポイント — ルート、エンドポイント、メッセージコンシューマー、ファイル／アップロード、CLI、スケジュールされたジョブ。
• 信頼境界 — データが権限や所有者の変更をまたいで移動する箇所（インターネット→サービス、サービス→DB、サービス→サードパーティ、テナント→テナント）。
• データフロー — それらの境界を越えて、アクター、プロセス、ストア間でデータがどのように移動するか。

Phase 0 の終了基準

Gate 1 の前に、Claude が以下を説明できるようにします。

• 対象と、システムのどの部分をカバーするか
• 主要な資産とアクター
• 対象範囲内のエントリーポイントと信頼境界
• それらの境界を越える主なデータフロー
• 不明点と、推測せず未解決の質問として記載する領域

名前から制御や境界を推測しないでください。設計上フローが明確でない場合は、推測せず未解決の質問とします。

---

Gate 1 — スコープと分解

変更の規模に合わせて、モデルのスコープと分解案を提示します。

## Proposed threat model

- **Target:** {feature X | module | API | current branch diff}
- **Assets:** {what we're protecting}
- **Actors:** {who, with privilege level}
- **Entry points:** {routes / consumers / jobs in scope}
- **Trust boundaries:** {the crossings to model}
- **Method:** STRIDE per data-flow element
- **Out of scope:** {what this model will not cover}
- **Open questions:** {anything ambiguous}

• 次のように尋ねます。「これが {target} の脅威モデルのスコープと分解案です。脅威を列挙する前に確認してください。」
• 停止します。ユーザーがスコープと分解案を確認するまで、脅威を列挙しないでください。

---

分離の設定（スタンドアロンモードのみ）

別のフローに組み込まれて実行している場合は、ここをスキップし、既存のブランチ／ワークツリーに書き込んでください。

スタンドアロンで実行している場合は、書き込みを始める前に、作業をどのように分離するかユーザーに尋ねてください。

現在のチェックアウトに新しいブランチを作成して作業しますか、それとも別の git ワークツリーを作成しますか？

ユーザーの回答どおりに進めてください。 質問したら停止し、ユーザーが選択するまでブランチやワークツリーを作成しないでください。

現在のチェックアウトに未コミットの変更がある場合は、ブランチの切り替えやワークツリーの作成を行う前に停止して確認してください。

オプション A — 現在のチェックアウトにブランチを作成

# Run from the repo root
git switch develop
git pull --ff-only
git switch -c assess/threat-{slug}

オプション B — 別のワークツリー

ワークツリーは .worktrees/ の下にのみ作成してください。パスをユーザーに尋ねないでください。

# Run from the repo root
git fetch origin develop
mkdir -p .worktrees
git worktree add .worktrees/assess-threat-{slug} -b assess/threat-{slug} origin/develop

{slug} は {kebab-target} です（例：pay-by-link、contact-export-api）。すべての出力は、選択した作業場所内に書き込まれ、コミットされます。

---

フェーズ 2 — 脅威の列挙（STRIDE）

目標： THREAT-MODEL.md を作成します。実際の設計に基づき、データフロー図と各要素／境界に対する STRIDE 分析を記載します。

脅威モデリングのルール（必須）

• 要素ごとに STRIDE を適用します。 各データフロー／プロセス／ストア／境界について、なりすまし、改ざん、否認、情報漏えい、サービス拒否、権限昇格を検討します。実際に該当するものを記録し、該当しない項目で水増ししないでください。
• 追跡可能にします。 各脅威には、対象となる要素／フローと、該当する場合はコード／設計上の箇所（path:line、ルート、境界）を記載します。既存の各緩和策にはその所在を記載し、提案する緩和策は具体的に記述します。
• リスクを評価します。 各脅威には、発生可能性 × 影響度（または低／中／高のリスク評価）を付けます。これを基に緩和策の優先順位を決めます。
• 憶測しないでください。 緩和策が実装済みか不明な場合は、脅威のステータスを Unverified とし、未解決の質問を追加してください。防御策が実装済みだと決めつけてはいけません。
• 残存リスクを明示します。 提案する緩和策を適用した後に残るものと、受容するリスクを記載してください。

THREAT-MODEL.md の構成

# Threat Model — {target}

## Scope
- Target: {feature | module | API | branch diff}
- Date: {YYYY-MM-DD}
- Method: STRIDE
- Assets / actors / trust boundaries: {short recap from Gate 1}

## Data-flow diagram
{Mermaid DFD: actors, processes, data stores, and trust boundaries as labeled crossings}

## Threats (STRIDE)
| # | Element / flow | STRIDE | Threat | Likelihood | Impact | Risk | Existing mitigation | Proposed mitigation | Status |
|---|----------------|--------|--------|------------|--------|------|---------------------|---------------------|--------|
| 1 | POST /login | S | Credential stuffing via unthrottled login | High | High | High | none | Rate-limit + lockout + MFA option | Open |
| 2 | service→DB | T | SQLi via unparameterized query | Med | High | High | parameterized queries `src/db/q.ts:20` | — | Mitigated |
| 3 | order read | E | IDOR — no ownership check | Med | High | High | none | Enforce authz on record access | Open |

Status: Mitigated / Open / Accepted / Unverified.

## Prioritized mitigations
Ordered by risk; each tied to its threat number. (These become plan tasks or follow-up items.)

## Residual risk
What remains after the proposed mitigations, and what is explicitly accepted (and by whom).

## Open questions / to verify
- …

完了前に Mermaid DFD がパーサーで検証されていることを確認してください。 レンダリングできない図は、図がない場合よりも問題です。読みやすさを保ち、詰め込みすぎている場合は分割してください。

---

フェーズ 3 — 緩和策と残存リスク

• リスクに基づいて未解決の脅威に優先順位を付け、それぞれを対応する脅威番号に紐付けて緩和策の一覧に記載します。
• 緩和策を明確に引き継ぎます。このフローでは緩和策を実装しません。
  • incu-way-development に組み込まれている場合、コーディングを始める前に、「Open」の高／中リスクの緩和策をそれぞれ PLAN のタスクにします。
  • それ以外の場合は、適切に後続の incu-way-development／incu-way-bugs／snyk-remediation の項目に引き継ぎます。
• ユーザーが理解したうえで受け入れられるよう、残存リスクを明確に記載します。

---

ゲート 2 — レビュー

モデルの作成後：

• ファイルのパス、高リスクの脅威、優先順位付きの緩和策、残存リスク、未解決の質問／確認事項を提示します。
• 次のように伝えます。「脅威モデルの準備ができました：docs/security/threat-models/{slug}/THREAT-MODEL.md。高リスクの脅威と提案する緩和策を記載しました。レビューしてください。」
• 停止し、ユーザーのレビューを待ってから続行します。

組み込まれて実行している場合は、制御を呼び出し元のフローのゲートに戻します。モデルはそこでレビューされ、緩和策はそのフローの計画に組み込まれ、そのフローの PR とともにリリースされます。以下のスタンドアロン PR の手順はスキップします。

フェーズ 4 — PR（単独モードのみ）

incu-way-prepare-pr を呼び出して assess/threat-{slug} をプッシュし、PR を作成するよう提案します。自分でプッシュしたり、gh pr create を実行したりしないでください。

incu-way-prepare-pr で使用する PR タイトル／本文の案：

Title: assess(threat-model): {target}

PR 本文には以下を含めてください：

• スコープ： 対象、アセット、アクター、信頼境界。
• 概要： 高リスクの脅威とそのステータス。
• 緩和策： 優先順位付きのリストと、それぞれの振り分け先。
• 残存リスク： 残っているものと、受容するもの。
• 未解決の質問： チームの意見が必要な未解決項目。

作成したら、PR の URL を共有してください。停止してください。ユーザーの承認があるまでマージしないでください。

---

クイックリファレンス — ゲート

ゲート	トリガー	伝える内容	次に進む前の条件
1	スコープと分解を提案	「これは {target} の脅威モデルのスコープと分解です。脅威を列挙する前に確認してください。」	ユーザーの確認
2	モデルを作成	「脅威モデルを docs/security/threat-models/{slug}/THREAT-MODEL.md に用意しました。レビューしてください。」	ユーザーのレビュー
3	（単独モード）レビュー済み	PR assess/threat-{slug} → develop 用に incu-way-prepare-pr を提案し、ユーザーが実行したら URL を共有	ユーザーの PR 承認

---

作成されるもの

docs/security/threat-models/{slug}/
  THREAT-MODEL.md   # DFD + STRIDE threat table + prioritized mitigations + residual risk

---

やってはいけないこと

• ゲート 1 でスコープと分解が確認される前に、脅威を列挙しないでください。
• STRIDE テーブルを該当しない行で埋めないでください — 実際に該当する脅威を記録してください。
• 緩和策が実施済みだと決めつけないでください — 不明な場合は Unverified と記載し、未解決の質問を追加してください。
• 追跡できない脅威や緩和策を作らないでください — それぞれの要素／フローを参照し、該当する場合はコード／設計上の箇所も参照してください。
• ここで緩和策を実装しないでください — モデル化して優先順位を付け、変更は呼び出し元のフローまたはフォローアップ項目に任せてください。
• パーサーでレンダリングに失敗する Mermaid DFD を残さないでください。
• モデルを肥大化させないでください — 変更の規模に合わせ、深さはリスクに応じて調整してください。
• 別のフローに組み込まれている場合、独立した PR を作成しないでください — モデルは呼び出し元の PR に含めます。
• 単独モードでは develop や main に直接書き込まないでください — assess/threat-{slug} を使用してください。