fmway-threat-model

脅威モデリングのプロセス

現在の作業（計画中の機能、モジュール、API、または現在のブランチの変更）を対象に、システムのデータフローと信頼境界を軽量な STRIDE で確認し、小規模で範囲を絞った脅威モデルを作成する、ゲート方式のガイド付きワークフローです。目的は、企業向けの網羅的な成果物ではなく、緩和策につながる、実用的で追跡可能なモデルです。成果物は docs/security/threat-models/{slug}/THREAT-MODEL.md に保存されます。

呼び出し方法は2つあります。

• 単独実行（コンポーネントまたは変更をモデル化する）： 専用ブランチ assess/threat-{slug} → develop への PR。
• 別のワークフローに組み込む： 呼び出し元のブランチまたは worktreeに書き込みます。モデルはそのワークフローの PR に含まれます。別のブランチや PR は作成しません。例：fmway-dev が Gate 2 の PLAN 直後に脅威モデルを作成し（緩和策を計画のタスクにできるようにする）、fmway-bugs がセキュリティに影響する修正をモデル化する場合。

これは評価ワークフローです。fmway-docs と同様に、.ways/state.json は保持しません。脅威を特定して緩和策を提案します。緩和策の実装は、呼び出し元のワークフロー、または後続の fmway-dev や fmway-bugs の項目です。

小規模に保ってください。 変更の規模に合わせてモデルを調整します。新しいエンドポイントには、データフロー図と少数の脅威があればよく、40ページの文書は必要ありません。リスクに応じて深さを調整します。

---

フェーズ 0 — 範囲と分解

目標： 脅威について検討できるよう、システムの対象部分を十分に理解します。読み取り専用です。

初期調査

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

対象の分解

コードまたは設計を根拠に、以下を特定します。

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

フェーズ 0 の完了条件

Gate 1 の前に、Claude は以下を説明できなければなりません。

• 対象と、対象に含まれるシステムの範囲
• 主要な資産とアクター
• 対象範囲に含まれるエントリーポイントと信頼境界
• それらの境界を越える主要なデータフロー
• 不明確な領域と、推測せず未解決の質問として残す項目

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

---

Gate 1 — 範囲と分解

変更の規模に合わせて、モデルの範囲と分解を提案します。

## Modelo de amenazas propuesto

- **Objetivo:** {feature X | módulo | API | diff de la rama actual}
- **Activos:** {qué estamos protegiendo}
- **Actores:** {quiénes, con su nivel de privilegio}
- **Puntos de entrada:** {rutas / consumidores / tareas en alcance}
- **Fronteras de confianza:** {los cruces a modelar}
- **Método:** STRIDE por elemento del flujo de datos
- **Fuera de alcance:** {lo que este modelo no va a cubrir}
- **Preguntas abiertas:** {lo ambiguo}

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

---

分離の設定（単独モードのみ）

別のワークフローに組み込まれて実行されている場合は、この手順を省略してください。既存のブランチまたは worktree に書き込んでください。

単独で実行されている場合は、書き込む前に、作業をどのように分離するかユーザーに尋ねてください。

現在の checkout に新しいブランチを作成して作業しますか？それとも、別の git worktree を作成しますか？

回答をそのまま使用してください。質問した後は停止し、ユーザーが選択するまでブランチも worktree も作成しないでください。

現在の checkout に未コミットの変更がある場合は、ブランチを切り替えたり worktree を作成したりする前に停止して確認してください。

オプション A — 現在の checkout にブランチを作成

git switch develop && git pull --ff-only && git switch -c assess/threat-{slug}

オプション B — 別の worktree を作成

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

git fetch origin develop && mkdir -p .worktrees && git worktree add .worktrees/assess-threat-{slug} -b assess/threat-{slug} origin/develop

{slug} は kebab-case の対象名です（例：pago-por-link、api-exportar-contactos）。すべての出力は、選択した作業場所に書き込まれます。

---

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

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

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

• 要素ごとの STRIDE。 各フロー、プロセス、ストレージ、境界について、なりすまし（Spoofing）、改ざん（Tampering）、否認（Repudiation）、情報漏えい（Information disclosure）、サービス拒否（Denial of service）、権限昇格（Elevation of privilege）を検討してください。実際に該当するものを記録し、該当しない項目で表を埋めないでください。
• 追跡可能であること。 各脅威には、対象となる要素またはフローを記載し、該当する場合はコードまたは設計上の箇所（ruta:línea、HTTP ルート、境界）も記載してください。既存の各緩和策には、その実装箇所を記載してください。提案する各緩和策は具体的にしてください。
• リスクを評価すること。 各脅威に発生可能性 × 影響度（または低／中／高のリスク）を割り当ててください。これに基づいて緩和策の優先順位を決めます。
• 推測しないこと。 緩和策が存在するか不明な場合は、脅威の状態を Sin verificar とし、未解決の質問を追加してください。防御策が導入済みだと決めつけないでください。
• 残留リスクを明示すること。 提案した緩和策を実施した後に何が残り、何を受容するのかを記載してください。

THREAT-MODEL.md の構成

# Modelo de amenazas — {objetivo}

## Alcance
- Objetivo: {feature | módulo | API | diff de rama}
- Fecha: {AAAA-MM-DD}
- Método: STRIDE
- Activos / actores / fronteras de confianza: {resumen corto del Gate 1}

## Diagrama de flujo de datos
{DFD en Mermaid: actores, procesos, almacenamientos y las fronteras de confianza como cruces etiquetados}

## Amenazas (STRIDE)
| # | Elemento / flujo | STRIDE | Amenaza | Probabilidad | Impacto | Riesgo | Mitigación existente | Mitigación propuesta | Estado |
|---|------------------|--------|---------|--------------|---------|--------|----------------------|----------------------|--------|
| 1 | POST /login | S | Credential stuffing por login sin límite de intentos | Alta | Alto | Alto | ninguna | Límite de tasa + bloqueo + opción de MFA | Abierta |
| 2 | servicio→base de datos | T | Inyección SQL por consulta sin parametrizar | Media | Alto | Alto | consultas parametrizadas `src/db/q.ts:20` | — | Mitigada |
| 3 | lectura de pedido | E | IDOR — sin chequeo de propiedad | Media | Alto | Alto | ninguna | Exigir autorización al acceder al registro | Abierta |

Estado: Mitigada / Abierta / Aceptada / Sin verificar.

## Mitigaciones priorizadas
Ordenadas por riesgo; cada una atada al número de su amenaza. (Se convierten en tareas del plan o en
ítems de seguimiento.)

## Riesgo residual
Qué queda después de las mitigaciones propuestas, y qué se acepta explícitamente (y quién lo acepta).

## Preguntas abiertas / a verificar
- …

完了前に Mermaid の DFD をパーサーで検証してください。レンダリングできない図は、図がないよりも悪いです。読みやすさを保ち、複雑になりすぎる場合は分割してください。

---

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

• 未解決の脅威をリスク順に並べて緩和策を優先し、それぞれに脅威番号を対応させてください。
• 緩和策を引き継いでください。このワークフローでは実装しません。
  • fmway-dev に組み込まれている場合は、コーディングを始める前に、高リスクまたは中リスクの未解決の緩和策をすべて PLAN のタスクにしてください。
  • それ以外の場合は、該当する fmway-dev、fmway-bugs、または fmway-vuln の後続項目に振り分けてください。
• ユーザーが何を受容するのか理解したうえで判断できるよう、残留リスクを明確に記載してください。

---

ゲート 2 — レビュー

モデルを作成したら、次の内容を提示してください。

• パス、高リスクの脅威、優先する緩和策、残留リスク、未解決／要確認の質問。
• 次のように伝えてください。「脅威モデルを docs/security/threat-models/{slug}/THREAT-MODEL.md に作成しました。高リスクの脅威と提案する緩和策を一覧にしました。レビューしてください。」
• 停止してください。続行する前にユーザーのレビューを待ってください。

組み込まれて実行されている場合は、制御を呼び出し元のワークフローに戻し、そのワークフロー独自のゲートに進んでください。モデルはそこでレビューされ、その緩和策はそのワークフローの計画に統合され、PR に含まれます。単独実行時の PR 手順は省略してください。

---

フェーズ 4 — PR（自律モードのみ）

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

Título: assess(threat-model): {objetivo}

PR の本文には、次の内容を含める必要があります。

• スコープ： 目的、資産、アクター、信頼境界。
• 概要： リスクの高い脅威とその状態。
• 緩和策： 優先順位付きのリストと、それぞれの振り分け先。
• 残存リスク： 残っているものと、受容されるもの。
• 未解決の質問： チームによる定義が必要な未解決項目。

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

---

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

ゲート	トリガー	伝える内容	次に進む条件
1	提案されたスコープと分解	「これが {objetivo} のモデルスコープです。確認してください。」	ユーザーが確認する
2	モデルの作成完了	「モデルを docs/security/threat-models/{slug}/THREAT-MODEL.md に作成しました。確認してください。」	ユーザーによるレビュー
3	（自律モード）レビュー済み	assess/threat-{slug} → develop の PR を作成するため、fmway-pr を提案し、URL を共有する	ユーザーが PR を承認する

---

作成されるもの

docs/security/threat-models/{slug}/
  THREAT-MODEL.md   # DFD + tabla STRIDE + mitigaciones priorizadas + riesgo residual

---

やってはいけないこと

• ゲート 1 でスコープと分解が確定する前に、脅威を列挙しないでください。
• STRIDE テーブルに該当しない行を追加しないでください。実際に該当する脅威を記録してください。
• 緩和策が導入済みだと決めつけないでください。不明な場合は 未検証 と記し、未解決の質問を追加してください。
• 脅威や緩和策の追跡可能性を損なわないでください。それぞれの要素またはフローを参照し、該当する場合はコードまたは設計上の箇所も示してください。
• ここで緩和策を実装しないでください。モデル化して優先順位を付け、呼び出し元のワークフローまたは後続の項目に変更を任せてください。
• レンダリングに失敗する Mermaid の DFD を確定しないでください。
• モデルを肥大化させないでください。変更の範囲に合わせ、リスクに応じた深さにしてください。
• 別のワークフロー内で組み込み実行する場合、別個の PR を作成しないでください。モデルは呼び出し元の PR に含めます。
• 自律モードでは develop または main に直接書き込まないでください。assess/threat-{slug} を使用してください。