incu-way-threat-model

威胁建模流程

一个由关卡驱动的工作流，用于针对当前工作——计划中的功能、模块、API 或当前分支上的更改——通过对系统数据流和信任边界进行轻量级 STRIDE 分析，生成一份小巧且聚焦的威胁模型。目标是创建实用且可追溯的模型，以推动缓解措施，而不是编制详尽的企业级文档。 输出保存在 docs/security/threat-models/{slug}/THREAT-MODEL.md。

两种调用模式：

• 独立运行（对某个组件或更改进行威胁建模）： 使用独立分支 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 项目。

保持小巧。根据更改范围调整模型规模：一个新端点只需要一个数据流图和少量威胁，不需要 40 页的文档。深度应与风险相匹配。

---

仓库资格检查（先于其他所有操作）

在 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、定时任务。
• 信任边界 — 数据跨越权限/所有权变更的位置（互联网→服务、服务→数据库、服务→第三方、租户→租户）。
• 数据流 — 数据如何跨越这些边界，在参与者、进程和存储之间流动。

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 worktree？

严格按照用户的回答执行。 询问后停止；在用户选择之前，不要创建分支或 worktree。

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

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

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

选项 B — 创建单独的 worktree

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

# 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 后，分享 PR URL。停止。在用户批准前不要合并。

---

快速参考 — 关卡

关卡	触发条件	要说什么	暂停，直到
1	提出范围和分解方案	“这是针对 {target} 的威胁建模范围和分解方案。请确认后，我再列举威胁。”	用户确认
2	模型已编写	“威胁模型已就绪，位于 docs/security/threat-models/{slug}/THREAT-MODEL.md。请审阅。”	用户审阅
3	（独立模式）已审阅	建议使用 incu-way-prepare-pr，为 assess/threat-{slug} → develop 创建 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}。