1. 项目概述与核心价值如果你在应用安全或者软件开发领域待过一段时间肯定会经常听到“威胁建模”这个词。它听起来很高大上像是安全架构师的专属技能但实际操作起来很多团队要么觉得无从下手要么做出来的模型千篇一律脱离实际。我自己在带团队做安全评审时就经常遇到这样的困境大家知道该做威胁建模但手头没有好的、贴近真实场景的例子可以参考最后往往流于形式。这就是 OWASP Threat Model Cookbook 这个项目吸引我的地方。它不是一个教你理论方法的教科书而是一个实实在在的“菜谱”仓库。你可以把它理解为一个开源的安全设计模式库或者一个威胁建模的“案例集”。项目里收集了各种各样的系统模型从简单的登录流程到复杂的微服务架构用不同的工具和表现形式比如流程图、攻击树、代码描述呈现出来。它的核心价值在于提供可复用的参考范例让你能快速理解在特定场景下威胁建模应该关注什么、怎么画图、如何分析。这个项目在2025年10月被归档为只读状态但这丝毫不影响它的实用价值。里面的案例都是经过社区贡献和打磨的反而因为状态稳定更适合作为长期参考的“典籍”。对于安全工程师、开发人员甚至是产品经理无论你是想学习威胁建模的基础还是为手头的新项目寻找分析灵感这个Cookbook都能提供一个扎实的起点。接下来我会带你从零开始把这个“菜谱库”部署到本地并深入解读其内容和使用方法让你能真正把它用起来。2. 环境准备与项目获取虽然项目本身是静态的文档和模型文件集合但为了能方便地查看、编辑甚至基于它进行二次创作我们最好在本地搭建一个便于浏览和管理的环境。这里不涉及复杂的服务部署核心是准备好代码管理和文档查看的工具链。2.1 基础工具链安装与配置首先你需要一个代码版本管理工具。Git是绝对的首选它不仅用于克隆项目后续如果你有自己的分析想贡献比如提交Pull Request到其他活跃分支或你的私有仓库也离不开它。对于Windows用户我推荐直接下载 Git for Windows 的安装包。安装过程中有几个关键选项需要注意选择默认编辑器如果你不熟悉Vim建议选择你常用的编辑器比如VSCode或Notepad避免后续提交信息时陷入Vim的编辑模式。调整PATH环境选择“Git from the command line and also from 3rd-party software”。这会将Git工具添加到系统PATH让你能在任何命令行窗口包括PowerShell、CMD或终端模拟器中直接使用git命令。配置行尾转换选择“Checkout Windows-style, commit Unix-style line endings”。这个设置能很好地处理Windows和Linux/Unix系统之间文本文件换行符的差异避免出现大量不必要的修改提示。安装完成后打开命令行CMD或PowerShell运行git --version来验证安装是否成功。接下来配置你的用户信息这是提交代码时的“签名”git config --global user.name 你的名字 git config --global user.email 你的邮箱接下来是文档查看。项目里包含很多.svg,.png等格式的图片以及Markdown文档。一个强大的文本编辑器是必需的。Visual Studio Code (VSCode)是我的主力推荐它轻量、免费、插件生态丰富。从官网下载安装后我建议安装以下几个对查看和编辑Cookbook项目非常有帮助的插件Markdown All in One提供Markdown语法高亮、预览、目录生成等功能查看README.md、INDEX.md等文件时会非常方便。PlantUML这个项目里大量使用了PlantUML文本描述来生成架构图。安装这个插件后你可以在VSCode里直接编写.plantuml文件并实时预览生成的图表对于学习和修改模型至关重要。Draw.io Integration有些模型是.drawio或.xml格式的这个插件允许你在VSCode内直接编辑Draw.io图表无需切换应用。SVG Preview快速预览SVG图片文件。注意安装PlantUML插件后它可能需要一个Java运行环境JRE来运行本地的PlantUML渲染引擎。如果你本地没有Java插件通常会提示你下载一个轻量级的JRE按照提示操作即可。这是为了获得最佳的本地预览体验不是必须项但强烈建议配置。2.2 克隆项目仓库到本地工具准备好后我们就可以把“菜谱”搬回家了。由于原仓库已被归档我们直接克隆它的只读副本即可。打开你的命令行终端切换到你希望存放项目的目录比如D:\Projects或~/Documents。然后执行克隆命令git clone https://github.com/OWASP/threat-model-cookbook.git这个命令会从GitHub上把整个项目仓库下载到你当前目录下的threat-model-cookbook文件夹里。克隆完成后进入项目目录看一看结构cd threat-model-cookbook ls -la # Linux/Mac # 或 dir # Windows CMD你应该能看到类似这样的顶层结构Attack Tree/ Flow Diagram/ IriusRisk/ Template/ INDEX.md LICENSE.md README.mdINDEX.md是这个项目的总目录和入口文件强烈建议你第一站就打开它。它用图文并茂的方式列出了所有收录的威胁模型案例并附有简短描述是浏览整个Cookbook的最佳地图。实操心得我习惯在克隆项目后立即用VSCode打开整个文件夹code .。这样利用我们刚才安装的插件就可以在侧边栏自由导航点击INDEX.md直接预览遇到.plantuml文件也能自动渲染图表体验非常流畅。这种“一站式”的环境能极大提升你学习和研究这些案例的效率。3. 项目结构与核心内容深度解析把项目克隆到本地只是第一步就像拿到了一本厚厚的菜谱。接下来我们需要搞清楚这本菜谱是怎么编排的每一章都在讲什么这样才能快速找到我们需要的“菜式”。OWASP Threat Model Cookbook 的组织结构非常清晰遵循了“按建模方法分类再按系统案例组织”的原则。3.1 目录架构与建模方法论进入项目根目录你会看到几个主要的文件夹和一个关键的索引文件。我们来逐一拆解Attack Tree/(攻击树)这个目录下存放的是使用攻击树方法进行威胁建模的案例。攻击树是一种层次化的、图形化的方法它以“达成某个恶意目标”树根作为起点通过“与/或”逻辑门将攻击步骤树叶层层分解。这种方法非常适合分析针对某个特定安全属性如“窃取用户会话”的所有可能攻击路径。里面的案例通常是一个文本文件描述结构或一张图片。Flow Diagram/(数据流图)这是最常见、也可能是案例最丰富的目录。它基于数据流图(DFD)方法论这是STRIDE等威胁建模框架的基础。DFD关注系统内的实体、处理过程、数据流和数据存储。这里的案例通常包含.drawio绘图源文件、.png/.svg导出图片或.plantuml文本化描述文件。对于初学者我建议从这里开始因为DFD最直观也最容易与实际的系统架构图对应起来。IriusRisk/(IriusRisk工具)IriusRisk 是一个商业的威胁建模和风险管理系统。这个目录下的案例是以IriusRisk工具特定的格式可能是JSON或XML保存的。如果你或你的团队正在使用IriusRisk这些案例可以直接导入作为模板参考展示了如何在该工具中结构化地定义组件、威胁和应对措施。Template/(模板)这里提供了一些通用的、可复用的模板文件。例如可能包含一个标准的DFD图元库定义了一套绘制威胁建模图的图形规范或者一个记录威胁分析结果的Markdown模板。在你开始为自己的系统创建模型时可以基于这些模板来快速启动保证格式的统一和内容的完整性。INDEX.md(核心索引)这是整个Cookbook的精华所在务必作为你的首要阅读文件。它不是一个简单的文件列表而是一个精心编排的目录页。每个案例都会在这里出现并附有一张缩略图和一个简短的描述说明这个模型是关于什么系统的、用了什么方法。你可以通过浏览INDEX.md来快速了解项目全貌并点击链接跳转到具体的案例文件夹。这种按方法论分类的结构非常聪明。它允许贡献者用自己最熟悉的工具和方法来表达同时也让学习者可以横向对比同一个系统比如一个Web应用用DFD画出来是什么样用攻击树分析又是什么视角这种多角度的呈现能帮助你更立体地理解威胁建模。3.2 典型模型案例解读与学习要点光看结构不够我们得深入“菜品”内部。让我们以Flow Diagram/目录下的一个典型例子来拆解学习。假设我们打开一个名为simple-web-app的案例请注意这是一个假设的通用名称用于说明实际项目中有类似案例。在这个案例文件夹里你可能会看到以下文件simple-web-app.plantuml用PlantUML语法编写的系统数据流图描述。simple-web-app.plantuml.png由PlantUML文件生成的图片。simple-web-app-threats.md一个Markdown文件列出了基于该DFD分析出的威胁清单。README.md关于这个案例的说明可能包括系统背景、建模范围等。学习要点一解读PlantUML DFD打开.plantuml文件你看到的不是图形而是像下面这样的文本代码示例startuml !include tupadr3/common !include awslib/AWSCommon actor Internet User as user boundary Web Browser as browser control Web Server as server database SQL Database as db user - browser : HTTPS Request (1) browser - server : HTTP Request (2) server - db : SQL Query (3) db -- server : Query Results (4) server -- browser : HTTP Response (5) browser -- user : Renders Page (6) enduml这段代码定义了几个元素外部交互者(actor)、处理过程(control)、数据存储(database)和数据流箭头。学习的关键在于理解这些元素如何映射到STRIDE威胁类别Spoofing (假冒)actor用户是否可以被冒充server是否可信Tampering (篡改)数据流箭头上的数据在传输中是否可能被修改Repudiation (抵赖)user的操作能否被日志记录使其无法否认Information Disclosure (信息泄露)db中的敏感数据是否会通过响应泄露Denial of Service (拒绝服务)server或db是否会因大量请求而瘫痪Elevation of Privilege (权限提升)一个普通user能否通过某些操作获得server或db的管理权限通过阅读代码和生成的图片你要练习的是看到图形元素立刻能联想到对应的威胁类型。这是威胁建模的核心思维转换。学习要点二分析威胁清单接着看simple-web-app-threats.md。这里可能会以表格形式列出威胁威胁ID威胁描述受影响组件STRIDE分类潜在缓解措施TM-001攻击者可能窃听用户与浏览器间的HTTPS流量如果存在中间人攻击数据流 (1)Information Disclosure强制使用HSTS使用证书钉扎TM-002Web服务器可能遭受SQL注入攻击导致数据库信息泄露或篡改数据流 (2) - 处理过程 (server)Tampering, Information Disclosure使用参数化查询或ORM实施输入验证你要学习的不是死记硬背这些威胁而是学习它的分析模式它如何将DFD中的元素“数据流(2)”与一个具体的攻击场景“SQL注入”关联起来给出的缓解措施是否具体、可操作“使用参数化查询”就比“加强安全”要好得多。尝试问自己如果这是我的系统我还能想到什么其他威胁这个缓解措施在我的技术栈里如何实现注意事项Cookbook中的案例大多是“不安全的”或简化的教学示例。正如项目免责声明所说它们是为了教学而设计可能故意暴露一些漏洞或者不代表最佳实践。你的任务是学习分析方法而不是照搬设计。在实际项目中你的目标应该是识别并消除这些威胁而不是复制一个不安全的模型。4. 基于Cookbook的本地化实践与扩展掌握了“菜谱”的读法之后我们就要开始学着“做菜”了。OWASP Threat Model Cookbook 最大的价值不是让你欣赏而是让你动手。这里我将分享如何利用这些案例作为起点为你自己的项目开展威胁建模。4.1 创建你自己的威胁模型项目我建议你不要直接在克隆的Cookbook仓库里修改而是把它当作一个参考库然后新建一个你自己的项目目录。例如在你的工作区创建一个my-threat-models文件夹。在这个新项目里你可以借鉴Cookbook的结构来组织你的文件。比如my-threat-models/ ├── my-ecommerce-app/ # 你的电商应用模型 │ ├── architecture.drawio # 系统架构图源文件 │ ├── dfd.plantuml # 数据流图描述 │ ├── dfd.png # 生成的DFD图片 │ ├── threat-list.md # 威胁分析清单 │ └── assumptions.md # 建模假设和范围说明 ├── legacy-payment-service/ # 另一个遗留系统模型 └── templates/ # 你自己的模板库 ├── dfd-template.plantuml └── threat-list-template.md为什么推荐这种结构首先它清晰地将不同系统或组件的模型分开管理。其次保留源文件如.drawio,.plantuml非常重要这意味着你的模型是可维护、可版本控制的。图片.png只是输出物。最后建立一个自己的templates文件夹把你在多次建模中总结出的好用格式固化下来能极大提升后续工作的效率。4.2 应用Cookbook模式进行实际建模现在假设你要为一个内部的用户管理后台做威胁建模。你可以参照以下步骤并随时去Cookbook里寻找灵感定义范围与边界首先明确你要分析什么。是整个后台系统还是新增的“批量用户导入”功能在assumptions.md里写下你的假设比如“不考虑物理安全威胁”、“假设底层操作系统是安全的”。Cookbook里很多案例的README都包含了范围说明这是很好的参考。绘制架构图与数据流图(DFD)先用你熟悉的工具如Draw.io画出系统的组件架构图。这有助于你理解整体。然后绘制0级或1级DFD。参考Flow Diagram/目录下的案例识别出你的系统边界、外部实体如管理员用户、外部API、处理过程如“用户认证”、“密码重置”、数据存储如“用户数据库”、“日志存储”以及它们之间的数据流。技巧从Cookbook中找一个与你系统复杂度类似的案例比如一个带有数据库和外部服务的Web应用。打开它的.plantuml文件看看它是如何定义边界、过程和存储的。直接复制它的代码框架然后替换成你自己的组件名和数据流这是最快的上手方式。识别威胁STRIDE分析拿出你的DFD对着每个元素系统地过一遍STRIDE六个维度。针对每个数据流问自己它是否可能被篡改(T)或泄露(I)它是否需要防抵赖(R)针对每个处理过程问自己它是否可能被拒绝服务(D)它的逻辑是否可能被绕过导致权限提升(E)针对每个外部实体和数据存储问自己它们是否可能被假冒(S)此时去翻阅Cookbook中案例的threat-list.md。看看别人在类似的“Web服务器到数据库”数据流上识别了什么威胁很可能有SQL注入。这能有效触发你的思路避免遗漏常见漏洞。记录与制定缓解措施创建一个类似Cookbook中的威胁清单表格。为每个威胁分配一个ID、简要描述、受影响的DFD元素、STRIDE分类、风险等级如高/中/低以及具体的缓解措施。关键点缓解措施必须具体。不要写“加强安全”要写“对/api/user接口的输入实施严格的JSON Schema验证和长度限制”。Cookbook里的一些案例会给出技术性的缓解建议这是一个很好的学习来源你可以了解针对某种威胁有哪些可行的安全控制手段。评审与迭代威胁建模不是一次性的活动。将你的模型和威胁清单分享给开发、测试、运维的同事进行评审。他们可能会从不同视角发现你遗漏的点。根据反馈更新你的图表和文档。当系统架构发生变化时记得回来更新模型。4.3 利用工具提升效率手动维护PlantUML代码和Markdown表格虽然可行但项目规模大了会有些繁琐。你可以考虑一些工具链的整合版本控制用Git管理你的my-threat-models目录。每次建模或更新后都进行提交信息可以写成“添加用户管理后台DFD初版”或“根据评审更新支付模块威胁清单”。这保留了完整的历史记录。文档化在你的项目根目录创建一个README.md索引你所有的威胁模型并说明每个模型对应的系统版本或时间点。这就像为你自己的项目创建了一个迷你版的INDEX.md。自动化渲染如果你大量使用PlantUML可以将其集成到你的文档流水线中。例如使用plantuml命令行工具批量将.plantuml文件渲染成图片或者使用支持实时预览的编辑器如已配置好的VSCode。实操心得我个人的工作流是在启动一个新项目或新功能的威胁建模时会同时打开三个窗口1我自己的绘图工具Draw.io2Cookbook里一个相关的案例作为参考3一个空白的威胁清单文档。边画图边对照案例思考威胁边记录。这种“三屏联动”的方式能让我保持思维连贯高效地产出质量不错的初版模型。记住完成比完美更重要先基于Cookbook的范例快速搭出一个框架再逐步深化和细化。5. 常见问题、排查技巧与进阶思考即使有了详细的指南和丰富的案例在实际操作中你还是会遇到一些困惑或问题。这里我整理了一些常见的情况和解决思路以及如何超越Cookbook进行更深入的思考。5.1 常见问题速查与解决问题现象可能原因排查与解决思路克隆仓库后无法打开或预览.plantuml文件中的图表。1. 未安装PlantUML插件。2. 插件未正确配置Java环境。3. 文件本身语法错误。1. 在VSCode中确认已安装“PlantUML”插件并启用。2. 检查插件输出窗口是否有Java错误。根据提示安装JRE如Amazon Corretto。3. 尝试打开一个Cookbook中已知正确的.plantuml文件如Flow Diagram/下的简单示例如果仍不行是环境问题如果可以则是目标文件语法问题。在参考案例绘制自己的DFD时不确定某个组件应该归类为“过程”、“存储”还是“外部实体”。对DFD元素定义理解不清晰。过程对数据进行操作或转换的地方如“验证密码”、“生成报表”。存储数据静态留存的地方数据库、文件、缓存。外部实体系统边界外与之交互的人或系统用户、第三方API。技巧问自己“它主动做事情吗”过程“它被动存数据吗”存储“它在我的控制范围外吗”外部实体。多对比Cookbook中类似组件是如何归类的。威胁识别阶段感到无从下手STRIDE每个类别都想不出几个威胁。1. 对系统细节了解不足。2. 缺乏攻击者视角思维。3. 对STRIDE的理解停留在表面。1.深化系统理解与开发、架构师深入讨论数据流细节比如API参数、数据库查询、使用的开源库。2.切换视角扮演一个恶意攻击者你的目标是什么偷数据、搞破坏你会从哪个最薄弱的环节入手3.使用检查清单不要空想。网上有很多基于STRIDE的详细问题检查清单OWASP自己也提供可以对着你的DFD元素逐一提问。Cookbook的威胁清单本身就是一种高级检查清单。感觉Cookbook里的案例技术栈或场景与自己的项目相差太远参考价值不大。只关注了案例的“表面”具体技术而非“内核”分析方法。抽象一层去看一个“物联网设备固件更新”案例其核心DFD模式可能是“不可信源 - 验证过程 - 安全存储”。你的“移动App从CDN下载资源”场景完全可以套用这个“不可信源传输验证”的模式来分析威胁篡改、假冒。学习的是模式和分析思路不是具体的实现。威胁清单列出来了但不知道如何确定优先级或者缓解措施看起来成本很高。缺乏风险评估和成本效益分析。威胁建模的输出是威胁清单但安全决策需要风险分析。可以引入简单的风险评估矩阵根据可能性和影响来对威胁分级高、中、低。对于高风险威胁必须制定缓解措施对于中低风险可以讨论接受、转移或降低优先级。缓解措施也应评估实施成本开发量、性能影响与安全收益。5.2 超越Cookbook从学习到创造Cookbook是一个绝佳的起点但它不应该成为终点。当你熟练之后可以尝试以下进阶实践融合多种方法论不要局限于一种表现形式。尝试为同一个系统既画DFD分析数据流威胁也画攻击树分析达成某个关键攻击目标的路径。例如为“用户账户接管”这个攻击目标画一棵攻击树你会发现它和DFD中“用户认证”、“密码重置”等过程识别出的威胁是相互印证和补充的。建立组织内部的“活”Cookbook鼓励你的团队或公司内部建立自己的威胁模型库。每次做完一个项目的威胁建模都把最终版的模型、威胁清单和评审记录整理好存入一个内部知识库如Wiki、Git仓库。新项目启动时首先在这个内部库中搜索是否有类似场景可以参考。这能极大提升整个组织安全设计的复用性和一致性。与开发流程集成将威胁建模的输出特别是威胁清单转化为具体的安全需求或验收条件纳入到开发团队的迭代 backlog 中。例如针对“TM-002: SQL注入威胁”对应的安全需求可以是“所有数据库查询必须使用参数化查询接口”并在代码审查和测试案例中体现。让威胁建模的成果真正落地而不是一份写完就锁起来的文档。探索自动化工具除了IriusRisk还有很多威胁建模工具如Microsoft Threat Modeling Tool、Threagile等。它们可以通过图形化界面辅助绘制并自动基于模型生成一部分威胁建议。你可以将Cookbook中的案例作为测试用例输入这些工具看看它们能自动识别出多少威胁这既能验证工具的能力也能帮你查漏补缺。威胁建模是一项需要持续练习的技能。OWASP Threat Model Cookbook 就像一本充满经典菜式的烹饪书它能教会你基本功和经典搭配。但真正的厨艺在于你理解这些原理后能根据手边的食材你的项目和食客的口味业务需求与风险承受能力烹饪出恰到好处的安全方案。多练、多思考、多交流你会发现自己对系统安全的理解会越来越深刻和主动。