threat-model-spec

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 │  │  Attack  │  │ Security │
  │ Diagram │   │  Chain   │  │ Diagram  │  │   Tree   │  │ Metadata │
  └────┬────┘   └─────┬────┘  └─────┬────┘  └─────┬────┘  └─────┬────┘
       │              │             │             │             │
       └──────────────┴─────────────┴─────────────┴─────────────┘
                                    │
                    ┌───────────────┼──────────────┐
                    │               │              │
                    ▼               ▼              ▼
               ┌──────────┐   ┌──────────┐   ┌──────────┐
               │    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

• Design-Time Threat Modeling — Proactive security analysis during SDLC with STRIDE/LINDDUN
• Risk Assessment — Structured likelihood × impact scoring with categorical risk levels
• Asset Inventory — Sensitivity classification and compliance mapping
• Scenario Modeling — What-if attack scenarios with preconditions and attack paths
• Diagrams-as-Code — Define threat models in JSON, render to D2/SVG
• Multiple Diagram Types — DFD, Attack Chain, Sequence, Attack Tree diagrams
• Framework Mappings — MITRE ATT&CK, MITRE ATLAS, OWASP Top 10, STRIDE, LINDDUN, CWE, CVSS, CVE
• Control Frameworks — NIST CSF, CIS Controls v8, ISO 27001 mappings
• Compliance Frameworks — SOC 2, PCI-DSS, HIPAA, GDPR, FedRAMP, and more
• Mitigations — Track countermeasures with status (implemented, planned, accepted)
• Threat Actors — Document adversary profiles with sophistication and motivation
• Network Topology — Map elements to hosts, ports, protocols, and cloud infrastructure
• Detection & Response — Define detection capabilities and response actions
• STIX 2.1 Export — Share threat intelligence in standard format
• D2 Styles — Color-coded STRIDE/LINDDUN annotations, trust boundaries, attack flows
• Validation — Type-specific field validation with strict mode
• AI Agents — Claude Code plugin for AI-assisted diagram creation

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

Framework Mappings

Threat Frameworks

Control Frameworks

Compliance Frameworks

D2 Style Reference

STRIDE Threat Annotations

LINDDUN Privacy Threats

Trust Boundaries

Mitigation Status

Security Lifecycle

Mitigations

Track countermeasures for identified threats:

{
  "mitigations": [
    {
      "id": "mit-1",
      "title": "Implement Origin Validation",
      "status": "implemented",
      "threatIds": ["threat-1"],
      "owner": "security-team"
    }
  ]
}

Threat Actors

Document adversary profiles:

{
  "threatActors": [
    {
      "id": "actor-1",
      "name": "External Attacker",
      "type": "criminal",
      "sophistication": "medium",
      "motivations": ["financial"]
    }
  ]
}

Detection & Response

Define detection capabilities:

{
  "detections": [
    {
      "id": "det-1",
      "title": "WebSocket Origin Anomaly",
      "coverage": "full",
      "dataSources": ["logs", "waf"]
    }
  ]
}

AI Agents

The agents/ directory contains specifications for AI-assisted threat model diagram creation:

Claude Code Plugin

Install the Claude Code plugin for AI-assisted diagram creation:

claude plugins add ./agents/plugins/claude

Use the /create-dfd command to generate diagrams interactively.

Specification

The Threat Model Specification follows a versioned schema approach similar to OpenAPI.

Schema URLs

https://github.com/grokify/threat-model-spec/docs/versions/v0.5.0/threat-model.schema.json
https://github.com/grokify/threat-model-spec/docs/versions/v0.5.0/diagram.schema.json

Using the Schema

Reference the schema in your threat model JSON:

{
  "$schema": "https://github.com/grokify/threat-model-spec/docs/versions/v0.5.0/threat-model.schema.json",
  "id": "my-threat-model",
  "title": "My Application Threat Model",
  "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