threat-modeling

威胁建模 — 实施前安全设计

针对拟议的功能、系统或架构开展结构化威胁建模。这是一项设计阶段的安全技能，与审查现有代码的审计不同。当有设计文档、功能规格或架构图，但尚未编写代码时，使用此技能。

适用场景：

• 新功能涉及身份验证、支付、多租户数据或敏感个人身份信息（PII）
• 新增外部集成（第三方 API、OAuth 提供商、Webhook 接收器）
• 在架构中新增服务／微服务
• 对安全敏感组件进行重大重构
• 在敲定重大架构决策之前（事件驱动还是请求／响应、拆分单体、引入 AI 功能）

交叉参考：owasp-audit（与此处发现的威胁相对应的代码级检查清单）、api-audit（API 专属类别映射）、iam-audit（身份决策会影响每个威胁模型）。

授权

针对用户拥有、构建或获准评估的系统，基于其提供的设计、图表和代码进行建模。威胁建模属于设计分析，不会进行任何测试。未经授权，不要为他人的产品构建攻击树。

四个问题

Adam Shostack 的表述——每个威胁模型都要回答以下四个问题：

1. 我们正在做什么？（范围和模型）
2. 可能出什么问题？（威胁）
3. 我们打算如何应对？（缓解措施）
4. 我们做得好吗？（验证）

本技能的其余部分将依次介绍每个问题。

步骤 1 — 我们正在做什么？

绘制三个级别之一的数据流图（DFD）：

• 级别 0 — 上下文图。用一个气泡表示系统，并用线连接每个外部实体（用户、第三方 API、内部管理工具）。当问题是“这个系统究竟会接触什么？”时使用。
• 级别 1 — 主要流程。身份验证服务、API 网关、主数据存储、支付集成等。大多数功能级威胁模型都使用此级别。
• 级别 2 — 详细组件模型。具体端点、具体表、具体队列。仅用于最复杂的部分。

实用的 DFD 包含：

• 外部实体（矩形）——用户、第三方服务、管理员
• 流程（圆形）——你的服务、函数、处理程序
• 数据存储（平行线／圆柱体）——数据库、缓存、Blob 存储、队列
• 数据流（带标签的箭头，标明流经的数据）——请求正文、令牌、文件、事件
• 信任边界（虚线）——每处跨越边界的位置都是验证、身份验证或过滤数据的地方

信任边界是最有用的元素。如果你能画出一张图，展示功能中的每个信任边界，就已经完成了 60% 的工作。

在纯文本环境中，使用 Mermaid 绘制 DFD：

flowchart LR
  User[User] -- HTTPS --> WAF[WAF / CDN]
  WAF -- request --> API[API Gateway]
  API -- JWT --> Service[Service]
  Service -- SQL --> DB[(Postgres)]
  Service -- HTTPS --> Stripe[Stripe]

  classDef trust fill:#fff,stroke:#f00,stroke-dasharray:4 4
  class API,Service trust

步骤 2 — 可能出什么问题？（STRIDE）

针对每个流程、数据存储和数据流，逐项检查 STRIDE——每个字母代表一种威胁类别。并非每个类别都适用于每个元素，这没关系。

字母	威胁	违反的属性	示例
S	欺骗	身份验证	令牌被盗、JWT 伪造、重放攻击、冒充服务
T	篡改	完整性	在请求传输过程中修改请求、篡改参数、修改存储的数据
R	抵赖	不可抵赖性	用户否认执行过某项操作；日志无法证明操作由其执行
I	信息泄露	机密性	通过错误消息泄露信息、IDOR 暴露其他用户的数据、S3 存储桶暴露
D	拒绝服务	可用性	资源耗尽、高成本查询攻击、通过付费下游 API 耗尽账单额度
E	权限提升	授权	通过批量赋值让用户变为管理员、BFLA、逃逸沙箱

每个元素的 STRIDE 分析

一个实用的威胁建模习惯：为 DFD 中的每个元素写一张简短的表格。

**Element:** API Gateway

| STRIDE | Threat | Likelihood | Impact |
|---|---|---|---|
| S | Forged JWT — symmetric secret in env, leaks if .env exposed | M | H |
| T | Request body modified between gateway and upstream service | L | M |
| R | Gateway access logs deleted by attacker post-breach | L | H |
| I | Verbose error responses expose internal hostnames | M | L |
| D | No rate limit at the gateway → upstream services overwhelmed | H | H |
| E | "X-Admin: true" header pass-through from external requests | L | C |

可能性和影响：L / M / H / C（严重）——定性评估即可；对大多数项目来说，定量评分只是做做样子。

滥用案例（STRIDE 的姊妹方法）

对于涉及业务流程的功能，也要梳理滥用案例。格式如下：

As a malicious actor, I want to [goal] so that I can [outcome].

示例：

• 作为恶意客户，我想重复兑换同一个优惠券代码 100 次，以耗尽折扣预算
• 作为竞争对手，我想批量抓取所有产品详情，以克隆你的产品目录
• 作为拥有读取权限的内部人员，我想在一年内提取所有客户的个人身份信息，以便出售这些信息而不触发 DLP 警报

滥用案例能发现 STRIDE 遗漏的问题——STRIDE 擅长发现“安全属性遭到违反”的情况；滥用案例擅长发现“业务意图遭到违反”的情况。

步骤 3 — 我们打算如何应对？

对于步骤 2 中发现的每项威胁，选择以下四种应对方式之一：

• 缓解 — 设计一种控制措施，降低可能性或影响
• 转移 — 将风险转给其他人处理（Stripe 负责 PCI 合规，Vercel 负责 DDoS）
• 接受 — 记录残余风险及其理由
• 规避 — 不要按这种方式构建该功能；重新设计

缓解措施应具体明确：

不佳的缓解措施	良好的缓解措施
“添加速率限制”	“为 /api/coupon/redeem 添加每个用户 IP 每分钟 5 次请求的限制，并使用 Redis 计数；将 429 响应加入队列，以便触发警报”
“验证输入”	“拒绝包含控制字符（\t、\n、\0）、反斜杠或百分号编码斜杠的 ?next= URL；通过 new URL(target, ...).pathname 规范化（参见 owasp-audit A01）”
“加密数据”	“使用由 AWS KMS 管理的 CMK 进行应用层加密，按行进行信封加密，每 90 天轮换密钥，并对每次 Decrypt 调用记录审计日志”

常见缓解模式

• 欺骗 → 强身份验证 — 短期令牌、MFA、双向 TLS、签名请求、工作负载身份联合（参见 iam-audit）
• 篡改 → 完整性控制 — HMAC、签名 Cookie、传输加密、预写日志、不可变基础设施
• 抵赖 → 审计日志 — 不可变的仅追加日志、独立的日志记录账号、针对日志篡改尝试的警报
• 信息泄露 → 尽量减少暴露 — 最小权限 IAM、数据分类、静态和传输中的加密、使用 DTO 而非完整记录（参见 api-audit API3）
• 拒绝服务 → 资源限制 — 速率限制、配额、查询深度限制、账单警报、熔断器
• 权限提升 → 授权检查 — 集中式 can(user, action, resource)、默认拒绝、姊妹路由审计（参见 owasp-audit A06 姊妹路由）

步骤 4 — 我们做得好吗？

通过以下三种方式进行验证：

1. 覆盖检查 — DFD 中的每个元素都有 STRIDE 表格；每项威胁都有缓解措施；每项缓解措施都有负责人和截止日期。缺少条目是最常见的失误。
2. 对抗性复查 — 邀请一位未参与最初讨论的人（或在此技能场景中使用另一个模型）参与。明确提示对方找出遗漏，并打破相关的盲点。参见 owasp-audit Second-Opinion Pass。
3. 追溯至测试 — 每项高/严重级别的缓解措施都应有对应测试（单元测试、集成测试或生产监控中的金丝雀测试）。如果你无法编写测试，那你就没有真正的缓解措施，只有一个意向。

何时进行威胁建模（以及何时不必）

值得做：

• 新的身份验证流程／新的支付集成／新的第三方数据交换
• 多租户数据模型
• 涉及管理功能、账单或敏感个人身份信息的任何改动
• 重大架构变更
• AI 功能（参见 prompt-injection）

可能不值得做：

• 针对已有完善数据模型的数据进行内部 CRUD 操作
• 仅涉及 UI 的改动
• 不改变信任边界的重构

判断标准：如果改动引入了新的信任边界、移动了现有边界，或改变了跨越边界的数据，就进行威胁建模。否则，跳过。

输出格式

威胁模型是持续更新的文档，而非一次性的报告。保持简短，便于审阅。

# Threat Model: [Feature / System Name]
## Status: Draft / In Review / Approved
## Owner: [name]
## Date: [date]
## Reviewers: [names]

## 1. Scope
[2-3 sentences — what's in, what's out]

## 2. Data Flow Diagram
[Mermaid diagram or link to image]

## 3. Assumptions and constraints
- [Anything taken as given — e.g. "users authenticate via Okta, MFA enforced"]

## 4. Threats and mitigations
[STRIDE-per-element tables, then abuse cases]

## 5. Open questions
[Things we deferred or couldn't decide]

## 6. Decision log
[Material design decisions and why — including risks accepted]

## 7. Action items
| Item | Owner | Deadline | Status |
|------|-------|----------|--------|

将其与设计文档一同保存在代码仓库中，而不要放在单独的安全跟踪系统里。威胁模型与实现之间的偏差是最常见的失效模式；把它们放在一起有助于减少偏差。

边界

• 此技能用于生成规划材料，而非进行漏洞利用
• 威胁模型用于揭示风险；它们并不授予测试权限——验证时请结合 web-pentest 或 owasp-audit
• 未经授权，不要对他人的产品进行威胁建模（例如，为竞争对手生成攻击树）
• 未经审查和签字确认的威胁模型毫无意义——如果用户正在编写没人会看的模型，请提出反对意见

参考资料

• 《威胁建模：面向安全的设计》——Adam Shostack
• Microsoft STRIDE 方法论
• OWASP 威胁建模备忘单
• OWASP pytm / threatspec（工具）
• 《威胁建模宣言》（threatmodelingmanifesto.org）
• Mozilla 快速风险评估（RRA）框架
• NIST SP 800-154（以数据为中心的系统威胁建模指南）