用途
Threat Model 用于对任意代码库产出结构化、有证据支撑的安全威胁模型。它超出表层枚举，沿实际代码路径追踪不可信数据，将发现按根因聚类，并构建把单个问题组合成更高严重度攻击路径的利用链。
适用时机
- 用户要求对某代码库做威胁建模、安全评审或攻击面映射
- 开始开发安全敏感功能（认证、加密、文件 I/O、网络、原生桥接）
- 评估新代码库或重大架构变更的安全影响
- 审查 PR 或近期提交的安全回归（增量/差异模式）
- 安全事件后重新评估威胁态势
工作流概览
- 阶段 0（条件性）：差异分析——若提供 git 范围，则将范围限定到变更代码
- 阶段 1：代码库调查——理解项目是什么、做什么
- 阶段 2：组件映射——识别组件、数据流和语言桥接
- 阶段 3：资产识别——确定需要保护的对象
- 阶段 4：信任边界——按信任级别分类输入，盘点入口点
- 阶段 5：数据流追踪——从入口到汇点跟踪不可信值（关键技术）
- 阶段 6：攻击面枚举——记录带追踪证据的攻击面
- 阶段 7：模式聚类——将 3 个以上相似发现按根因分组
- 阶段 8：利用链——将发现组合成多步攻击路径
- 阶段 9：校准——按链条调整后与系统性严重度评级
- 阶段 10：输出——写出结构化的 THREAT-MODEL.md
使用方式
- 阅读 methodology 了解各阶段的详细方法
- 阅读 output format 了解文档结构（6 个部分）
- 查阅 attack patterns 了解特定技术的模式
- 运行
scripts/trace-data-flows.sh <project-root>盘点入口点和汇点 - 可选运行
scripts/scan-patterns.sh <project-root>扫描与安全相关的代码模式
分析技术
这些技术是该技能的核心价值，编码了仅凭通用知识无法得出的分析方法。
- 数据流追踪：阶段 5，始终使用。通过实际代码从入口到汇点追踪不可信输入，产出有证据支撑的发现而非理论风险
- 模式聚类：阶段 7，枚举之后。按根因对相关发现分组，建议系统性修复而非逐个打补丁
- 利用链：阶段 8，聚类之后。将发现组合成多步攻击路径，按最终影响评级
- 桥接分析：阶段 6，发现 FFI/桥接时。针对跨语言边界（Swift↔C、Rust↔C、Rails↔NGINX）的系统化检查清单
- 差异分析：阶段 0，用于增量审查。将分析范围限定到变更代码，识别回归
关键原则
- 证据胜于推测：每个发现都应包含数据流追踪，展示不可信输入如何到达脆弱操作。“可能存在 XSS”是推测；“RFC markdown → marked.parse() → 第 917 行的 innerHTML，无净化器”才是证据
- 系统性胜于个体：当 3 个以上发现共享根因时，系统性发现比任何单个发现更重要。修根因，不修症状
- 链条胜于单点：按最终影响评级组合攻击路径。三个中等发现串联成严重影响的，就是一个严重发现
- 已有缓解措施很重要：记录已受保护的部分，而非仅缺失的部分
- 结合上下文的校准：严重度取决于部署上下文，始终包含范围说明
输出
产出两个文件（可通过 config.json 配置）：
- findings.json——结构化、机器可读的发现，是事实来源，被 threat-patch 消费用于自动修复，并跨多次运行跟踪发现状态（open → patched → verified → closed）
- THREAT-MODEL.md——由 findings.json 生成的人类可读视图，含 6 个部分：概览、信任边界、攻击面、系统性发现、利用链、严重性校准
流水线集成
threat-model → findings.json → threat-patch（消费发现，生成修复），再由 threat-model --diff 重新分析并更新发现状态。
当存在来自先前运行的 findings.json 时，该技能会读取它以：跟踪哪些发现仍然开放、哪些已打补丁；参照先前评级校准严重度；检测回归（已修复发现重新出现）。
两种模式
- 全量分析：触发语如“threat model this codebase”，分析整个代码库，产出全新的 findings.json + THREAT-MODEL.md
- 差异分析：触发语如“what changed since last review”或提供 git 范围，将范围限定到变更代码，用新增/已解决/回归的发现更新现有 findings.json
差异模式是持续项目的日常使用方式；全量模式运行一次（或定期运行）。
参考资料
- references/methodology.md：开始前阅读，10 阶段工作流
- references/output-format.md：写输出时阅读，6 部分模板
- references/findings-schema.md：写 findings.json 时阅读，结构化 schema
- references/attack-patterns.md：枚举攻击面时阅读，技术模式
- references/techniques/：特定阶段阅读，分析技术