threat-model-spec

README

Threat Model Spec

Threat Model Spec is an open-source library for creating security threat modeling diagrams as code. It provides a JSON-based intermediate representation (IR) that can be rendered to D2 diagrams and STIX 2.1 for threat intelligence sharing.

Architecture

                         ┌──────────────────────┐
                         │     ThreatModel      │
                         │  (Canonical Source)  │
                         └──────────┬───────────┘
                                    │
              ┌─────────────────────┼─────────────────────┐
              │                     │                     │
              ▼                     ▼                     ▼
       ┌────────────┐        ┌────────────┐        ┌────────────┐
       │    DFD     │        │  Attack    │        │  Sequence  │
       │  Diagram   │        │   Chain    │        │  Diagram   │
       └─────┬──────┘        └─────┬──────┘        └─────┬──────┘
             │                     │                     │
             └─────────────────────┼─────────────────────┘
                                   │
                    ┌──────────────┼──────────────┐
                    │              │              │
                    ▼              ▼              ▼
             ┌──────────┐   ┌──────────┐   ┌──────────┐
             │    D2    │   │   STIX   │   │ Validate │
             │ Renderer │   │ Exporter │   │          │
             └────┬─────┘   └────┬─────┘   └────┬─────┘
                  │              │              │
                  ▼              ▼              ▼
             ┌──────────┐   ┌──────────┐   ┌──────────┐
             │   .d2    │   │  .json   │   │  pass/   │
             │  → .svg  │   │  STIX    │   │  fail    │
             └──────────┘   │  Bundle  │   └──────────┘
                            └──────────┘

Input: ThreatModel JSON with shared metadata, framework mappings, and multiple diagram views

Outputs:

• D2 Diagrams → SVG/PNG via D2 CLI (one per diagram view)
• STIX 2.1 Bundles → Threat intelligence sharing
• Validation Results → Schema and reference checking

Features

• 💻 Diagrams-as-Code — Define threat models in JSON, render to D2/SVG
• 📊 Multiple Diagram Types — DFD, Attack Chain, Sequence diagrams
• 🗺️ Framework Mappings — MITRE ATT&CK, MITRE ATLAS, OWASP Top 10, STRIDE, CWE, CVSS
• 📤 STIX 2.1 Export — Share threat intelligence in standard format
• 🎨 D2 Styles — Color-coded STRIDE annotations, trust boundaries, attack flows
• ✅ Validation — Type-specific field validation

Installation

Go Library

go get github.com/grokify/threat-model-spec

CLI Tool

go install github.com/grokify/threat-model-spec/cmd/tms@latest

Quick Start

Define a Threat Model (JSON)

A ThreatModel is the canonical format containing shared metadata and multiple diagram views:

{
  "id": "websocket-localhost-takeover",
  "title": "WebSocket Localhost Takeover",
  "description": "Attack exploiting missing origin validation",
  "mappings": {
    "mitreAttack": [
      {"tacticId": "TA0001", "techniqueId": "T1189", "techniqueName": "Drive-by Compromise"}
    ],
    "owasp": [
      {"category": "api", "id": "API2:2023", "name": "Broken Authentication"}
    ]
  },
  "diagrams": [
    {
      "type": "attack-chain",
      "title": "Attack Chain",
      "elements": [
        {"id": "attacker", "label": "Attacker", "type": "external-entity"},
        {"id": "victim", "label": "Victim", "type": "process"}
      ],
      "attacks": [
        {"step": 1, "from": "attacker", "to": "victim", "label": "WebSocket to localhost"}
      ]
    }
  ]
}

Single-diagram files (DiagramIR format) are also supported for simpler use cases.

Generate Diagrams

# Generate D2 diagram from ThreatModel
tms generate threat-model.json -o diagram.d2

# Also render to SVG
tms generate threat-model.json -o diagram.d2 --svg

# Export to STIX 2.1
tms generate threat-model.json --stix -o threat-model.stix.json

# Validate only
tms validate threat-model.json

Diagram Types

Type	Description	Key Fields
dfd	Data Flow Diagram	elements, boundaries, flows
attack-chain	Attack sequence	elements, attacks, targets
sequence	Time-ordered messages	actors, messages, phases

Framework Mappings

Framework	Field	Example
MITRE ATT&CK	mitreAttack	{"tacticId": "TA0001", "techniqueId": "T1189"}
MITRE ATLAS	mitreAtlas	{"tacticId": "AML.TA0002", "techniqueId": "AML.T0024"}
OWASP	owasp	{"category": "api", "id": "API2:2023"}
STRIDE	stride	{"category": "S", "name": "Spoofing"}
CWE	cwe	{"id": "CWE-346", "name": "Origin Validation Error"}
CVSS	cvss	{"version": "3.1", "vector": "CVSS:3.1/..."}

D2 Style Reference

STRIDE Threat Annotations

Category	Color	Description
S - Spoofing	Red	Identity spoofing
T - Tampering	Yellow	Data tampering
R - Repudiation	Purple	Non-repudiation failures
I - Information Disclosure	Blue	Information leakage
D - Denial of Service	Orange	Availability attacks
E - Elevation of Privilege	Green	Privilege escalation

Trust Boundaries

Type	Color	Use For
browser	Blue	Browser sandbox
localhost	Purple	Localhost implicit trust
network	Green	Network zones
breached	Dark red	Compromised boundaries

Examples

See examples/openclaw/ for a complete threat model of the OpenClaw WebSocket vulnerability:

• openclaw.json — Canonical ThreatModel with all diagram views
• Data Flow Diagram (DFD) — System architecture and trust boundaries
• Attack Chain — Attack steps with MITRE ATT&CK mapping
• Attack Sequence — Time-ordered interactions
• HTML article with rendered diagrams

Requirements

• Go 1.24+
• D2 v0.6+ for SVG rendering

License

MIT License - see LICENSE

References

• D2 Language
• MITRE ATT&CK
• MITRE ATLAS
• OWASP Top 10
• STRIDE Threat Model
• STIX 2.1