model

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Threat Modeling

威胁建模

Full architecture-level threat modeling with automated discovery, data flow mapping, STRIDE-per-component analysis, and attack tree generation. Produces persistent, incremental threat models stored in

.appsec/model/

that evolve as the codebase changes.

全架构级威胁建模，包含自动发现、数据流映射、逐组件STRIDE分析和攻击树生成。生成的持久化增量威胁模型存储在

.appsec/model/

目录中，会随代码库变更而演进。

Supported Flags

支持的参数

Read

../../shared/schemas/flags.md

for the full flag specification.

Flag	Model Behavior
`--scope`	Default `full` . Threat models benefit from whole-system visibility. Narrow scopes produce partial models with a warning.
`--depth quick`	Component inventory and trust boundary identification only.
`--depth standard`	Full threat model: components, data flows, STRIDE analysis, mitigations.
`--depth deep`	Standard + attack trees, cross-component threat chains, external dependency threats.
`--depth expert`	Deep + DREAD scoring, attack simulation narratives, compliance mapping.
`--severity`	Filter reported threats by severity in output.
`--format`	Default `md` . Use `json` for structured model data.
`--diff`	Incremental mode: only analyze changes since last model. Compare against `.appsec/model/current.json` .

完整参数规范请阅读

../../shared/schemas/flags.md

。

参数	模型行为
`--scope`	默认值为 `full` 。威胁模型受益于全系统可见性，缩小范围会生成部分模型并发出警告。
`--depth quick`	仅识别组件清单和信任边界。
`--depth standard`	完整威胁模型：包含组件、数据流、STRIDE分析及缓解措施。
`--depth deep`	标准模型 + 攻击树、跨组件威胁链、外部依赖威胁分析。
`--depth expert`	深度模型 + DREAD评分、攻击模拟场景、合规映射。
`--severity`	按严重程度过滤输出中的威胁。
`--format`	默认值为 `md` 。使用 `json` 可输出结构化模型数据。
`--diff`	增量模式：仅分析自上次模型以来的变更内容，与 `.appsec/model/current.json` 进行对比。

Workflow

工作流程

Step 1: Discovery

步骤1：自动发现

Automatically discover the application architecture by analyzing the codebase:

通过分析代码库自动发现应用架构：

Component Discovery

组件发现

Identify all significant components:

Services: Separate processes, microservices (from docker-compose, k8s manifests, service configs).
APIs: REST controllers, GraphQL resolvers, gRPC services.
Data stores: Databases, caches, file storage, message queues.
External dependencies: Third-party APIs, SaaS integrations, CDNs, auth providers.
Background workers: Job processors, cron tasks, event consumers.
Client applications: Web frontends, mobile apps, CLI tools.
Infrastructure: Load balancers, reverse proxies, API gateways (from config files).

识别所有重要组件：

服务：独立进程、微服务（来自docker-compose、k8s清单、服务配置）。
API：REST控制器、GraphQL解析器、gRPC服务。
数据存储：数据库、缓存、文件存储、消息队列。
外部依赖：第三方API、SaaS集成、CDN、认证提供商。
后台工作者：任务处理器、定时任务、事件消费者。
客户端应用：Web前端、移动应用、CLI工具。
基础设施：负载均衡器、反向代理、API网关（来自配置文件）。

Trust Boundary Discovery

信任边界发现

Identify boundaries where trust levels change:

Network boundaries: Internet to DMZ, DMZ to internal, internal to database tier.
Authentication boundaries: Public vs authenticated, user vs admin.
Process boundaries: Between services, between containers.
Data classification boundaries: Where PII/secrets move between storage/transit.

识别信任级别发生变化的边界：

网络边界：互联网到DMZ、DMZ到内部网络、内部网络到数据库层。
认证边界：公共区域 vs 已认证区域、普通用户 vs 管理员。
进程边界：服务之间、容器之间。
数据分类边界：PII/敏感数据在存储/传输过程中的流转边界。

Step 2: Data Flow Mapping

步骤2：数据流映射

Generate Mermaid data flow diagrams (DFDs) at two levels:

Generate Mermaid DFDs at two levels: Level 0 (system context -- actors, application, external systems) and Level 1 (component detail with trust boundary subgraphs showing internal services, data stores, and message queues).

Annotate each data flow with:

Protocol (HTTPS, gRPC, TCP, etc.)
Authentication method
Data classification (public, internal, confidential, restricted)
Encryption status (in transit, at rest)

生成两个层级的Mermaid数据流图（DFD）：

生成两个层级的Mermaid DFD：Level 0（系统上下文——参与者、应用、外部系统）和Level 1（组件细节，包含显示内部服务、数据存储和消息队列的信任边界子图）。

为每个数据流添加以下注解：

协议（HTTPS、gRPC、TCP等）
认证方式
数据分类（公开、内部、机密、受限）
加密状态（传输中、静止时）

Step 3: STRIDE-per-Component Analysis

步骤3：逐组件STRIDE分析

Apply STRIDE to each component and data flow:

STRIDE	Question
Spoofing	Can an attacker impersonate this component or a user of it?
Tampering	Can data in transit or at rest be modified without detection?
Repudiation	Can actions be performed without an audit trail?
Information Disclosure	Can sensitive data leak from this component?
Denial of Service	Can this component be made unavailable?
Elevation of Privilege	Can an attacker gain higher access through this component?

For each component, generate a threat table:

For each component, produce a table with columns: #, STRIDE category, Threat description, Severity, Mitigation, Status (Mitigated/Partial/Gap/Accepted).

对每个组件和数据流应用STRIDE分析：

STRIDE	问题
Spoofing（冒充）	攻击者能否冒充此组件或其用户？
Tampering（篡改）	传输中或静止状态下的数据能否被无检测修改？
Repudiation（抵赖）	能否在无审计痕迹的情况下执行操作？
Information Disclosure（信息泄露）	敏感数据能否从此组件泄露？
Denial of Service（拒绝服务）	能否使此组件不可用？
Elevation of Privilege（权限提升）	攻击者能否通过此组件获得更高权限？

为每个组件生成威胁表格：

为每个组件生成包含以下列的表格：序号、STRIDE类别、威胁描述、严重程度、缓解措施、状态（已缓解/部分缓解/存在缺口/已接受）。

Step 4: Attack Tree Generation

步骤4：攻击树生成

--depth deep

and above, generate attack trees for high-value targets:

For each high-value target (e.g., "Exfiltrate User PII"), produce a numbered attack tree with branches for direct access, application-layer attacks, and infrastructure attacks. Each leaf node references severity and mitigation status from the STRIDE analysis.

当使用

--depth deep

及以上级别时，为高价值目标生成攻击树：

针对每个高价值目标（例如“窃取用户PII”），生成带编号的攻击树，包含直接访问、应用层攻击和基础设施攻击分支。每个叶节点关联STRIDE分析中的严重程度和缓解状态。

Step 5: Identify Mitigations and Gaps

步骤5：识别缓解措施与缺口

For each threat identified:

Check if mitigated: Search the codebase for security controls that address the threat.
Assess mitigation quality: Is the control properly implemented? Complete? Tested?
Mark status:
- ```
Mitigated
```
  : Security control exists and is properly implemented.
- ```
Partial
```
  : Control exists but is incomplete or has known weaknesses.
- ```
Gap
```
  : No mitigation found. This becomes a finding.
- ```
Accepted
```
  : Risk acknowledged and accepted (noted in threat model).

针对每个识别出的威胁：

检查是否已缓解：在代码库中搜索可应对该威胁的安全控制措施。
评估缓解措施质量：控制措施是否正确实现？是否完整？是否经过测试？
标记状态：
- ```
Mitigated
```
  （已缓解）：安全控制措施存在且已正确实现。
- ```
Partial
```
  （部分缓解）：控制措施存在但不完整或已知存在弱点。
- ```
Gap
```
  （存在缺口）：未找到缓解措施，此为待处理问题。
- ```
Accepted
```
  （已接受）：风险已被确认并接受（会在威胁模型中注明）。

Step 6: Incremental Mode (--diff)

步骤6：增量模式（--diff）

When

--diff

flag is set:

Load the previous model from
```
.appsec/model/current.json
```
.
Detect changes:
- New components added.
- Components removed.
- Data flows added or changed.
- Trust boundaries modified.
Run STRIDE analysis only on new/changed components and flows.
Merge results into the existing model.
Highlight what changed in the output.

Output a changelog showing NEW, CHANGED, and REMOVED components with threat counts for each.

当设置

--diff

参数时：

从
```
.appsec/model/current.json
```
加载上一版本的模型。
检测变更：
- 新增的组件。
- 移除的组件。
- 新增或变更的数据流。
- 修改的信任边界。
仅对新增/变更的组件和数据流执行STRIDE分析。
将结果合并到现有模型中。
在输出中高亮显示变更内容。

输出变更日志，展示新增、变更和移除的组件及其对应的威胁数量。

Step 7: Persist Model

步骤7：持久化模型

Save the threat model to

.appsec/model/

File	Contents
`current.json`	Full structured model (components, flows, threats, mitigations)
`threat-model.md`	Human-readable report with Mermaid diagrams
`dfd-level0.mmd`	Level 0 Mermaid DFD source
`dfd-level1.mmd`	Level 1 Mermaid DFD source
`attack-trees.md`	Attack tree documentation
`history/<timestamp>.json`	Snapshot for diffing (incremental mode)

将威胁模型保存到

.appsec/model/

文件	内容
`current.json`	完整结构化模型（组件、数据流、威胁、缓解措施）
`threat-model.md`	带Mermaid图的人类可读报告
`dfd-level0.mmd`	Level 0 Mermaid DFD源文件
`dfd-level1.mmd`	Level 1 Mermaid DFD源文件
`attack-trees.md`	攻击树文档
`history/<timestamp>.json`	用于对比的快照（增量模式）

Step 8: Emit Findings for Gaps

步骤8：输出缺口问题

For each threat with status

Gap

, emit a finding using

../../shared/schemas/findings.md

Map STRIDE category to the appropriate
```
references.stride
```
value.
Severity based on threat analysis (impact and likelihood).
Location points to the component/file most relevant to the gap.

针对每个状态为

Gap

的威胁，使用

../../shared/schemas/findings.md

格式输出问题：

将STRIDE类别映射到对应的
```
references.stride
```
值。
根据威胁分析（影响和可能性）确定严重程度。
位置指向与缺口最相关的组件/文件。

Output Format

输出格式

Findings follow

../../shared/schemas/findings.md

Finding ID prefix: TM (e.g.,

TM-001

```
metadata.tool
```
:
```
"model"
```
```
metadata.framework
```
:
```
"stride"
```
(or specific framework if used)
```
references.stride
```
: The STRIDE category letter

问题遵循

../../shared/schemas/findings.md

规范。

问题ID前缀：TM（例如

TM-001

）。

```
metadata.tool
```
:
```
"model"
```
```
metadata.framework
```
:
```
"stride"
```
（若使用其他框架则为对应框架名称）
```
references.stride
```
: STRIDE类别的首字母

Pragmatism Notes

实用提示

Threat models are living documents. Encourage incremental updates (
```
--diff
```
) rather than full rebuilds.
Not every theoretical threat warrants a finding. Focus on threats that are plausible given the application's deployment context.
A microservice behind a service mesh has different threats than an internet-facing monolith. Adjust analysis accordingly.
Component discovery is heuristic. Label the model as based on code analysis, not authoritative architecture documentation.
DFDs should be useful, not exhaustive. Omit trivial flows (e.g., logging to stdout) unless they carry sensitive data.
If the codebase is a library (not a deployed application), model threats to consumers of the library rather than infrastructure threats.
STRIDE is the default framework. If the user requests PASTA, LINDDUN, or another framework, defer to those specialized skills.

威胁模型是活文档。建议使用增量更新（
```
--diff
```
）而非完全重建。
并非所有理论威胁都需要输出问题。重点关注与应用部署环境相关的可信威胁。
服务网格后的微服务与面向互联网的单体应用面临的威胁不同，需相应调整分析方式。
组件发现基于启发式规则。需标注模型基于代码分析，而非权威架构文档。
DFD应实用而非详尽。除非携带敏感数据，否则可忽略次要数据流（例如输出到stdout的日志）。
如果代码库是类库（而非部署的应用），则针对类库的使用者建模威胁，而非基础设施威胁。
STRIDE是默认框架。若用户要求使用PASTA、LINDDUN或其他框架，则调用对应的专用Skill。