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

Core Capabilities

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 (API, LLM, Web, ASI/Agentic), 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

v0.6.0 Security Enhancement Features

Role-Based Security Guidance
- Red Team — Exploitation steps, offensive tools, payload patterns, difficulty ratings
- Blue Team — Detection rules (Sigma, YARA, Splunk), IOCs, hunting queries, log sources
- Remediation — Secure code patterns, review checklists, recommended libraries
- Incident Playbooks — Structured response procedures with IR phases and contacts
Risk Quantification
- FAIR Assessment — Factor Analysis of Information Risk with frequency/loss estimates
- Business Impact — Revenue, customer, regulatory, reputation, operational impacts
- EPSS Integration — Exploit Prediction Scoring System data for CVEs
- KEV Catalog — CISA Known Exploited Vulnerabilities tracking
Purple Team
- Atomic Red Team Mapping — Link attacks to atomic tests with validation status
- Detection Coverage Matrix — Track technique coverage across detection capabilities
- Security Metrics — MTTD, MTTR, MTTC, detection rates, false positive tracking
Threat Intelligence
- Enhanced STIX 2.1 Export — IOCs to indicators, actors to threat-actors, detections to course-of-actions
- OWASP ASI Support — Agentic Security Top 10 (2026) mappings for AI agent threats
Supply Chain Security
- SBOM Integration — Link threat models to CycloneDX/SPDX software bills of materials
- VEX Statements — Vulnerability Exploitability eXchange for vulnerability status tracking
- Dependency Risk — Track vulnerable components with severity and remediation guidance
Vulnerability Management
- SSVC Decision Trees — CISA's Stakeholder-Specific Vulnerability Categorization
- Priority Decisions — Automated prioritization (Track, Track*, Attend, Act)
- Exploitation Status — Track active exploitation, PoC availability, and automatable attacks
Attack Path Analysis
- Attack Graphs — Graph-based representation of attack surfaces
- Path Finding — Find all paths, shortest paths (Dijkstra), and critical paths
- Risk Calculation — Path-based risk scoring and reachability analysis
- Graph Construction — Build attack graphs from threat model diagrams

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
`attack-tree`	Hierarchical attack decomposition	attackTree (nodes with AND/OR logic)

Framework Mappings

Threat Frameworks

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"}`
LINDDUN	`linddun`	`{"category": "I", "name": "Identifiability"}`
CWE	`cwe`	`{"id": "CWE-346", "name": "Origin Validation Error"}`
CVE	`cve`	`{"id": "CVE-2024-12345"}`
CVSS	`cvss`	`{"version": "3.1", "vector": "CVSS:3.1/..."}`

OWASP Top 10 Categories

Category	Value	List	Year
API Security	`api`	API Security Top 10	2023
LLM Applications	`llm`	LLM Application Top 10	2025
Web Applications	`web`	Web Application Top 10	2021
Agentic Applications	`agentic`	Agentic Top 10 (ASI)	2026

Attack steps can include asiIds for OWASP Agentic Security mappings:

{
  "step": 6,
  "from": "gateway",
  "to": "agent",
  "label": "Access agent",
  "asiIds": ["ASI02:2026", "ASI03:2026"],
  "owaspIds": ["API8:2023"]
}

Control Frameworks

Framework	Field	Example
NIST CSF	`controls.nistCsf`	`{"function": "Protect", "category": "PR.AC"}`
CIS Controls	`controls.cis`	`{"controlId": "16", "safeguardId": "16.4"}`
ISO 27001	`controls.iso27001`	`{"controlId": "A.9.2.3"}`

Compliance Frameworks

Framework	Value	Description
SOC 2	`soc2`	AICPA Service Organization Controls
PCI-DSS	`pci-dss`	Payment Card Industry Data Security
HIPAA	`hipaa`	Health Insurance Portability
GDPR	`gdpr`	General Data Protection Regulation
FedRAMP	`fedramp`	Federal Risk Authorization
NIST SP 800-53	`nist-sp-800-53`	Security Controls Catalog

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

LINDDUN Privacy Threats

Category	Color	Description
L - Linkability	Indigo	Linking items of interest
I - Identifiability	Blue	Identifying data subjects
N - Non-repudiation	Orange	Unable to deny actions
D - Detectability	Pink	Detecting item existence
Di - Disclosure	Red	Information disclosure
U - Unawareness	Purple	Lack of awareness
Nc - Non-compliance	Brown	Regulatory non-compliance

Trust Boundaries

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

Mitigation Status

Status	Color	Description
`implemented`	Green	Fully implemented
`partial`	Orange	Partially implemented
`planned`	Blue	Planned for future
`accepted`	Gray	Risk accepted
`transferred`	Light blue	Risk transferred

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:

Agent	Description
`dfd-creator`	Creates Data Flow Diagrams with numbered flows and trust boundaries
`attack-flow-visualizer`	Creates attack chain diagrams with MITRE ATT&CK annotations
`diagram-quality-reviewer`	Reviews diagrams for layout quality and legend clarity

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.

Version	Schema	Specification
v0.6.0	threat-model.schema.json	Comprehensive security enhancement
v0.5.0	threat-model.schema.json	specification.md
v0.4.0	threat-model.schema.json	specification.md

Schema URLs

https://github.com/grokify/threat-model-spec/docs/versions/v0.6.0/threat-model.schema.json
https://github.com/grokify/threat-model-spec/docs/versions/v0.6.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.6.0/threat-model.schema.json",
  "id": "my-threat-model",
  "title": "My Application Threat Model",
  "diagrams": [...]
}

Name		Name	Last commit message	Last commit date
Latest commit History 107 Commits
.github		.github
agents		agents
cmd		cmd
d2/styles		d2/styles
demo		demo
diagram		diagram
docs		docs
ir		ir
killchain		killchain
schema		schema
stix		stix
stride		stride
.gitignore		.gitignore
CHANGELOG.json		CHANGELOG.json
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
PRD.md		PRD.md
README.md		README.md
TASKS.md		TASKS.md
go.mod		go.mod
go.sum		go.sum
mkdocs.yml		mkdocs.yml

Folders and files

Latest commit

History

Repository files navigation

Threat Model Spec

Architecture

Features

Core Capabilities

v0.6.0 Security Enhancement Features

Installation

Go Library

CLI Tool

Quick Start

Define a Threat Model (JSON)

Generate Diagrams

Diagram Types

Framework Mappings

Threat Frameworks

OWASP Top 10 Categories

Control Frameworks

Compliance Frameworks

D2 Style Reference

STRIDE Threat Annotations

LINDDUN Privacy Threats

Trust Boundaries

Mitigation Status

Security Lifecycle

Mitigations

Threat Actors

Detection & Response

AI Agents

Claude Code Plugin

Specification

Schema URLs

Using the Schema

Requirements

License

References

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 5

Contributors

Uh oh!

Languages