Diagram Types

Threat Model Spec supports four diagram types, each suited for different threat modeling scenarios.

Overview

Type	Use Case	Key Fields
dfd	Data Flow Diagrams	elements, boundaries, flows
attack-chain	Attack sequences	elements, attacks, targets
sequence	Time-ordered messages	actors, messages, phases
attack-tree	Hierarchical threat decomposition	attackTree (root, nodes, gates)

Data Flow Diagram (DFD)

Data Flow Diagrams visualize how data moves through a system, highlighting trust boundaries and potential attack surfaces.

When to Use

• System architecture documentation
• Identifying trust boundaries
• Analyzing data flows between components
• Security review of new features

Structure

{
  "type": "dfd",
  "title": "System Architecture",
  "elements": [
    {"id": "user", "label": "User", "type": "external-entity"},
    {"id": "web", "label": "Web Server", "type": "process"},
    {"id": "db", "label": "Database", "type": "datastore"}
  ],
  "boundaries": [
    {
      "id": "dmz",
      "label": "DMZ",
      "type": "network",
      "elements": ["web"]
    }
  ],
  "flows": [
    {"from": "user", "to": "web", "label": "HTTPS Request"},
    {"from": "web", "to": "db", "label": "SQL Query"}
  ]
}

Key Fields

Field	Description
elements	Processes, data stores, and external entities
boundaries	Trust boundaries containing elements
flows	Data flows between elements

Attack Chain

Attack Chain diagrams show the sequence of steps an attacker takes to compromise a system, mapping to frameworks like MITRE ATT&CK.

When to Use

• Documenting known attack vectors
• Incident response analysis
• Red team planning
• Security training

Structure

{
  "type": "attack-chain",
  "title": "Credential Theft Attack",
  "elements": [
    {"id": "attacker", "label": "Threat Actor", "type": "external-entity"},
    {"id": "phishing", "label": "Phishing Email", "type": "process"},
    {"id": "creds", "label": "Credentials", "type": "datastore"}
  ],
  "attacks": [
    {
      "step": 1,
      "from": "attacker",
      "to": "phishing",
      "label": "Send phishing email",
      "mitreTechnique": "T1566"
    },
    {
      "step": 2,
      "from": "phishing",
      "to": "creds",
      "label": "Harvest credentials",
      "mitreTechnique": "T1110"
    }
  ],
  "targets": [
    {
      "elementId": "creds",
      "impact": "Credential compromise leading to unauthorized access"
    }
  ]
}

Key Fields

Field	Description
elements	Components involved in the attack
attacks	Ordered attack steps with techniques
targets	Final targets and impact

Sequence Diagram

Sequence diagrams show time-ordered interactions between actors, useful for visualizing attack timelines and protocol flows.

When to Use

• Protocol analysis
• Attack timeline documentation
• Authentication flow review
• API security analysis

Structure

{
  "type": "sequence",
  "title": "Authentication Bypass",
  "actors": [
    {"id": "attacker", "label": "Attacker", "malicious": true},
    {"id": "server", "label": "Server"},
    {"id": "db", "label": "Database"}
  ],
  "messages": [
    {
      "from": "attacker",
      "to": "server",
      "label": "Malformed auth request",
      "type": "attack"
    },
    {
      "from": "server",
      "to": "db",
      "label": "Bypass query"
    },
    {
      "from": "db",
      "to": "attacker",
      "label": "Sensitive data",
      "type": "exfil"
    }
  ],
  "phases": [
    {"name": "Initial Access", "startMessage": 0},
    {"name": "Data Exfiltration", "startMessage": 2}
  ]
}

Key Fields

Field	Description
actors	Participants in the sequence
messages	Ordered messages between actors
phases	Optional grouping of attack phases

Attack Tree

Attack Trees provide hierarchical decomposition of attack goals, showing how an attacker might achieve objectives through different paths using AND/OR logic gates.

When to Use

• Risk analysis and prioritization
• Identifying all paths to a security goal
• Evaluating attack feasibility
• Security investment decisions

Structure

{
  "type": "attack-tree",
  "title": "Compromise User Account",
  "attackTree": {
    "goal": "Gain unauthorized access to user account",
    "root": {
      "id": "root",
      "label": "Compromise Account",
      "gate": "OR",
      "children": [
        {
          "id": "steal-creds",
          "label": "Steal Credentials",
          "gate": "OR",
          "children": [
            {"id": "phishing", "label": "Phishing Attack"},
            {"id": "keylogger", "label": "Install Keylogger"}
          ]
        },
        {
          "id": "bypass-auth",
          "label": "Bypass Authentication",
          "gate": "AND",
          "children": [
            {"id": "find-vuln", "label": "Find Auth Vulnerability"},
            {"id": "exploit", "label": "Develop Exploit"}
          ]
        }
      ]
    }
  }
}

Key Fields

Field	Description
attackTree.goal	High-level attack objective
attackTree.root	Root node of the tree
node.gate	Logic gate: AND (all children required) or OR (any child sufficient)
node.children	Child attack nodes

Gate Types

Gate	Meaning	D2 Rendering
OR	Any child path achieves the goal	Oval node
AND	All child paths required	Rectangle node

Choosing a Diagram Type

graph TD
    A[What do you want to show?] --> B{System architecture?}
    B -->|Yes| C[Use DFD]
    B -->|No| D{Attack sequence?}
    D -->|Yes| E[Use Attack Chain]
    D -->|No| F{Time-ordered messages?}
    F -->|Yes| G[Use Sequence]
    F -->|No| H{Hierarchical threat analysis?}
    H -->|Yes| I[Use Attack Tree]
    H -->|No| J[Consider combining types]

Combining Diagrams

For comprehensive threat models, use multiple diagram types:

1. DFD — Document system architecture and trust boundaries
2. Attack Tree — Analyze all possible attack paths with AND/OR logic
3. Attack Chain — Map specific attack vectors with MITRE ATT&CK
4. Sequence — Detail the timeline of critical attacks