fmway-threat-model

威胁建模流程

通过关卡驱动的流程，为当前工作生成一个规模小、范围明确的威胁模型——可以是计划中的功能、模块、API，或当前分支的变更——并针对系统的数据流和信任边界进行轻量级 STRIDE 分析。目标是产出实用且可追溯的模型，用于推动缓解措施，而不是一份面面俱到的企业级文档。输出位于 docs/security/threat-models/{slug}/THREAT-MODEL.md。

两种调用模式：

• 独立运行（为组件或变更建模）： 使用独立分支 assess/threat-{slug} → 向 develop 提交 PR。
• 嵌入其他流程： 写入调用方的分支或 worktree；模型随该流程的 PR 一同提交。不另建分支或 PR。例如：fmway-dev 在 Gate 2 的 PLAN 之后立即运行威胁模型（以便将缓解措施转化为计划任务）；fmway-bugs 为有安全影响的修复建模。

这是一个评估流程。与 fmway-docs 一样，不维护 .ways/state.json。 它用于识别威胁并提出缓解措施；实施缓解措施属于调用流程的任务，或是后续 fmway-dev 或 fmway-bugs 的事项。

保持模型精简。 根据变更调整模型规模：新增一个 endpoint，只需要数据流图和少量威胁，不需要一份 40 页的文档。分析深度应与风险相称。

---

阶段 0 — 范围界定与分解

目标： 充分了解系统的相关部分，以便分析威胁。只读。

初步调研

1. 确认目标：计划中的功能（依据其 PRD 或 PLAN）、模块或服务、API，或当前分支的 diff（新代码）。
2. 首先阅读相关背景：PRD 和 PLAN（如果嵌入开发流程）、docs/architecture/ 中的文档、任何已有的威胁模型、CLAUDE.md 中的安全部分，以及 VALIDATION.md（如存在，参见 fmway-security）。

分解目标

以代码或设计为依据，识别：

• 资产 — 值得保护的对象（个人数据、凭据、支付数据、令牌、资金转移、记录完整性、流程可用性）。
• 参与者 — 交互方（最终用户、管理员、匿名调用方、内部服务、第三方）及其权限级别。
• 入口点 — 路由、endpoint、消息消费者、文件上传、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}

• 询问：“这是针对 {objetivo} 的威胁模型范围和分解方案。请确认后，我再列出威胁。”
• 暂停。在用户确认范围和分解方案之前，不要列出威胁。

---

隔离配置（仅限独立模式）

如果你嵌入在其他工作流中运行，请跳过此步骤：在现有分支或 worktree 中编写。

如果你单独运行，请先询问用户希望如何隔离工作，再开始编写：

你想让我在当前 checkout 中创建一个新分支，还是创建一个单独的 git worktree？

请原样使用用户的回答。提问后暂停；在用户做出选择之前，不要创建分支或 worktree。

如果当前 checkout 有未提交的更改，请暂停，并在切换分支或创建 worktree 之前询问。

选项 A — 在当前 checkout 中创建分支

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

选项 B — 创建单独的 worktree

仅在 .worktrees/ 下创建 worktree。不要向用户询问路径。

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）。记录确实适用的威胁；不要填入不适用的条目。
• 可追溯。 每项威胁都要引用其指向的元素或流，以及（如果存在）代码或设计位置（路径:行号、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 中，每项待处理的高风险或中风险缓解措施都必须在开始编写代码之前转化为一项计划任务
  • 否则，根据情况将其转交给 fmway-dev、fmway-bugs 或 fmway-vuln 的后续事项
• 清楚说明剩余风险，让用户了解并接受自己所接受的风险。

---

Gate 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 正文必须包含：

• **范围：**目标、资产、参与者、信任边界。
• **摘要：**高风险威胁及其状态。
• **缓解措施：**优先级列表，以及每项措施的流转去向。
• **残余风险：**剩余风险及已接受的风险。
• **待解决问题：**尚未解决、需要团队明确的事项。

PR 创建后，分享 URL。停止。未经用户批准，不要合并。

---

快速参考 — 检查点

检查点	触发条件	应说的话	阻塞条件
1	提出范围和分解方案	“这是针对 {目标} 的模型范围。请确认。”	用户确认
2	模型已编写	“模型已准备好，位于 docs/security/threat-models/{slug}/THREAT-MODEL.md。请审阅。”	用户审阅
3	（自主模式）已审阅	建议使用 fmway-pr 创建 PR assess/threat-{slug} → develop；分享 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}。