threat-model

威胁模型

为任何代码库生成结构化、有证据支持的安全威胁模型。它不止于表面枚举，还会追踪不可信数据在实际代码路径中的流转，按根本原因对发现的问题进行归类，并构建由单个发现的问题组合而成、严重性更高的攻击路径。

适用场景

• 用户要求为代码库建立威胁模型、进行安全审查或绘制攻击面
• 开始开发对安全敏感的功能（身份验证、密码学、文件 I/O、网络、本机桥接）
• 评估新代码库或重大架构变更带来的安全影响
• 审查 PR 或近期提交中的安全回归（增量／差异模式）
• 安全事件发生后重新评估威胁态势

工作流概览

Phase 0 (conditional): Diff Analysis — if git range provided, scope to changed code
Phase 1:  Codebase Survey        → Understand what the project is and does
Phase 2:  Component Mapping      → Identify components, data flows, and language bridges
Phase 3:  Asset Identification   → Determine what needs protecting
Phase 4:  Trust Boundaries       → Classify inputs by trust level, inventory entry points
Phase 5:  Data Flow Tracing      → Follow untrusted values from entry to sink ← key technique
Phase 6:  Attack Surface Enum    → Document surfaces with traced evidence
Phase 7:  Pattern Clustering     → Group 3+ similar findings by root cause
Phase 8:  Exploit Chains         → Combine findings into multi-step attack paths
Phase 9:  Calibration            → Rate with chain-adjusted and systemic severity
Phase 10: Output                 → Write structured THREAT-MODEL.md

使用方法

1. 阅读方法论，了解各阶段的详细方法
2. 阅读输出格式，了解文档结构（6 个部分）
3. 参考攻击模式，了解针对特定技术的模式
4. 运行 scripts/trace-data-flows.sh <project-root>，盘点入口点和接收端
5. 可选择运行 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 项以上发现有相同根本原因时，系统性发现比任何单项发现都更重要。修复根本原因，而非表面症状。
• 重攻击链，轻孤立问题：根据组合攻击路径的最终影响进行评级。3 项中危发现若能串联成造成严重影响的攻击链，就属于严重发现。
• 考虑现有缓解措施：记录已有的保护措施，而不只关注缺失之处。
• 结合上下文校准：严重性取决于部署上下文。始终附上范围说明。

输出

生成两个文件（可通过 config.json 配置）：

• findings.json——结构化、机器可读的发现记录，是权威数据源。供 threat-patch 自动修复使用，并在多次运行间跟踪发现状态（未处理 → 已修补 → 已验证 → 已关闭）。
• THREAT-MODEL.md——根据 findings.json 生成的易读版本，包含 6 个部分：概览、信任边界、攻击面、系统性发现、攻击链、严重性校准。

流水线集成

threat-model → findings.json → threat-patch (consumes findings, generates fixes)
     ↑                                          ↓
     └── threat-model --diff (re-analyzes, updates finding status) ←── git commits

如果此前运行已生成 findings.json，此技能会读取该文件，以便：

• 跟踪哪些发现仍未处理，哪些已修补
• 根据此前的评级校准严重性
• 检测回归（已修复的发现再次出现）

两种模式

模式	触发条件	功能
完整分析	“对这个代码库进行威胁建模”	分析整个代码库，生成新的 findings.json 和 THREAT-MODEL.md
差异分析	“自上次审查以来有哪些变更”／提供了 git 范围	仅分析变更的代码，并使用新增、已解决和回归的问题更新现有的 findings.json

差异模式适用于日常持续开发项目。完整模式运行一次（或定期运行）。

参考资料

文件	阅读时机
references/methodology.md	开始前——10 阶段工作流
references/output-format.md	编写输出时——6 部分模板
references/findings-schema.md	编写 findings.json 时——结构化架构
references/attack-patterns.md	枚举攻击面时——技术模式
references/techniques/	执行特定阶段时——分析技术