threat-model

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Threat Model

威胁建模

Produces structured, evidence-backed security threat models for any codebase. Goes beyond surface enumeration by tracing untrusted data through actual code paths, clustering findings by root cause, and constructing exploit chains that combine individual findings into higher-severity attack paths.

可为任意代码库生成结构化、有证据支撑的安全威胁模型。通过追踪不可信数据在实际代码路径中的流转，按根本原因聚类发现的问题，并将单个发现整合成更高严重性的攻击路径，超越了表面枚举的局限。

When to Apply

适用场景

User asks to threat model, security review, or map attack surfaces for a codebase
Starting work on security-sensitive features (auth, crypto, file I/O, networking, native bridges)
Evaluating a new codebase or major architectural change for security implications
Reviewing a PR or recent commits for security regressions (incremental/diff mode)
After a security incident to reassess the threat landscape

用户要求对代码库进行威胁建模、安全审查或攻击面映射
启动安全敏感功能（auth、crypto、文件I/O、网络、原生桥接）的开发工作
评估新代码库或重大架构变更的安全影响
审查PR或最近提交的代码以发现安全退化问题（增量/差异模式）
安全事件发生后重新评估威胁场景

Workflow Overview

工作流概述

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

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

How to Use

使用方法

Read methodology for the detailed approach at each phase
Read output format for the document structure (6 sections)
Consult attack patterns for technology-specific patterns

Run

scripts/trace-data-flows.sh <project-root>

to inventory entry points and sinks

Optionally run
```
scripts/scan-patterns.sh <project-root>
```
for security-relevant code patterns

阅读方法文档了解每个阶段的详细步骤
阅读输出格式文档了解文档结构（6个章节）
参考攻击模式文档获取特定技术的攻击模式
运行
```
scripts/trace-data-flows.sh <project-root>
```
来盘点入口点和数据终点（sink）
可选：运行
```
scripts/scan-patterns.sh <project-root>
```
检测安全相关的代码模式

Analytical Techniques

分析技术

These techniques are the skill's core value — they encode analytical methods that produce findings the model wouldn't generate from general knowledge alone.

Technique	When to Read	What It Adds
Data Flow Tracing	Phase 5 — always	Traces untrusted input from entry to sink through actual code. Produces evidence-backed findings instead of theoretical risks
Pattern Clustering	Phase 7 — after enumeration	Groups related findings by root cause. Recommends systemic fixes instead of individual patches
Exploit Chains	Phase 8 — after clustering	Combines findings into multi-step attack paths rated by terminal impact
Bridge Analysis	Phase 6 — when FFI/bridges found	Systematic checklist for cross-language boundaries (Swift↔C, Rust↔C, Rails↔NGINX)
Diff Analysis	Phase 0 — for incremental review	Scopes analysis to changed code, identifies regressions

这些技术是本Skill的核心价值——它们编码了仅靠通用知识无法生成发现结果的分析方法。

技术	阅读时机	新增价值
数据流追踪	第5阶段——必用	追踪不可信输入从入口到数据终点的实际代码路径。生成有证据支撑的发现结果，而非理论风险
模式聚类	第7阶段——枚举完成后	按根本原因对相关发现结果进行分组。推荐系统性修复方案，而非单个补丁
攻击链构建	第8阶段——聚类完成后	将多个发现整合成多步骤攻击路径，并按最终影响评级
桥接分析	第6阶段——发现FFI/桥接时	跨语言边界（Swift↔C、Rust↔C、Rails↔NGINX）的系统性检查清单
差异分析	第0阶段——增量审查时	将分析范围限定在变更代码，识别退化问题

Key Principles

核心原则

Evidence over speculation: Every finding should include a data flow trace showing how untrusted input reaches the vulnerable operation. "XSS is possible" is speculation. "RFC markdown → marked.parse() → innerHTML at line 917 with no sanitizer" is evidence.
Systemic over individual: When 3+ findings share a root cause, the systemic finding is more important than any individual finding. Fix the root cause, not the symptoms.
Chains over singletons: Rate combined attack paths by their terminal impact. Three medium findings that chain into critical impact are a critical finding.
Existing mitigations matter: Document what's already protected, not just what's missing.
Context-aware calibration: Severity depends on deployment context. Always include scope notes.

证据优先，拒绝推测：每个发现结果都应包含数据流追踪信息，展示不可信输入如何到达易受攻击的操作。“可能存在XSS”是推测，“RFC标记语言→marked.parse()→第917行innerHTML未经过滤”才是有证据的结论。
系统性优先，拒绝单点修复：当3个及以上发现结果共享同一根本原因时，系统性发现比任何单个发现都更重要。修复根本原因，而非症状。
攻击链优先，拒绝单点评级：结合攻击路径的最终影响进行评级。三个中等风险的发现若能构成严重影响的攻击链，则应归为严重风险。
已有的防护措施同样重要：不仅记录缺失的防护，也要记录已有的防护机制。
结合上下文校准风险：风险等级取决于部署环境，务必包含范围说明。

Output

输出

Produces two files (configurable via config.json):

findings.json
— Structured, machine-readable findings. Source of truth. Consumed by
```
threat-patch
```
for automated remediation. Tracks finding state across runs (open → patched → verified → closed).
THREAT-MODEL.md
— Human-readable view generated from findings.json. 6 sections: Overview, Trust Boundaries, Attack Surfaces, Systemic Findings, Exploit Chains, Criticality Calibration.

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

findings.json
— 结构化、机器可读的发现结果，是事实来源。可被
```
threat-patch
```
工具用于自动修复。跨运行追踪发现结果的状态（打开→已修复→已验证→关闭）。
THREAT-MODEL.md
— 基于findings.json生成的人类可读文档，包含6个章节：概述、信任边界、攻击面、系统性发现、攻击链、风险等级校准。

Pipeline Integration

流水线集成

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

When

findings.json

exists from a prior run, the skill reads it to:

Track which findings are still open vs patched
Calibrate severity against prior ratings
Detect regressions (fixed findings that reappeared)

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

当存在之前运行生成的

findings.json

时，本Skill会读取该文件以：

追踪哪些发现结果仍处于打开状态，哪些已被修复
基于之前的评级校准当前风险等级
检测退化问题（已修复的发现结果再次出现）

Two Modes

两种模式

Mode	Trigger	What It Does
Full analysis	"threat model this codebase"	Analyzes entire codebase, produces fresh findings.json + THREAT-MODEL.md
Diff analysis	"what changed since last review" / git range provided	Scopes to changed code, updates existing findings.json with new/resolved/regressed findings

Diff mode is the daily driver for ongoing projects. Full mode runs once (or periodically).

模式	触发条件	功能
全量分析	“threat model this codebase”	分析整个代码库，生成全新的findings.json + THREAT-MODEL.md
差异分析	“what changed since last review” / 提供git范围	将分析范围限定在变更代码，更新现有findings.json，添加新发现、标记已解决或退化的问题

差异模式是持续开发项目的日常使用模式，全量模式仅运行一次（或定期运行）。

References

参考文档

File	When to Read
references/methodology.md	Before starting — the 10-phase workflow
references/output-format.md	When writing output — 6-section template
references/findings-schema.md	When writing findings.json — structured schema
references/attack-patterns.md	When enumerating surfaces — technology patterns
references/techniques/	During specific phases — analytical techniques

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