<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
<!-- NERF is a trademark of defconxt. -->
---
name: building-threat-model-documentation
description: >-
  Generate structured threat model documentation with diagrams and reports.
domain: cybersecurity
subdomain: threat-modeling
tags:
  - documentation
  - threat-reports
  - dfd
  - risk-matrix
  - mitigation-tracking
  - templates
version: "1.0"
author: defconxt
license: AGPL-3.0
metadata:
  mitre-attack:
  - "T1190"
  - "T1078"
---

# Building Threat Model Documentation

## Overview

Effective threat model documentation serves multiple audiences — developers need actionable
findings, architects need design context, and executives need risk summaries. This technique
covers creating structured, version-controlled threat model documents with data flow diagrams,
threat tables, risk matrices, and audience-appropriate report formats.

Mode: `[MODE: ARCHITECT]` — Documentation standards for maintainable threat models.

## Prerequisites

- Completed threat analysis (STRIDE, attack trees, or similar)
- Graphviz or Mermaid for diagram generation
- Python 3.10+
- Markdown rendering tool

## Key Concepts

### Documentation Structure

| Section | Content | Audience |
|---------|---------|----------|
| **Executive Summary** | Risk overview, top findings | Leadership |
| **System Description** | Architecture, components, data flows | All |
| **Data Flow Diagrams** | Visual DFDs with trust boundaries | Architects |
| **Threat Table** | Enumerated threats with STRIDE/DREAD | Security team |
| **Risk Matrix** | Likelihood x Impact grid | All |
| **Mitigation Plan** | Controls, owners, timelines | Developers, PM |
| **Appendix** | Assumptions, methodology, glossary | Audit |

### Quality Criteria

- **Traceable** — every threat links to a component and mitigation
- **Versioned** — tracked in Git with change history
- **Current** — reviewed and updated on architecture changes
- **Actionable** — mitigations are specific with clear owners
- **Auditable** — assumptions, scope, and methodology documented

## Workflow

### Step 1: Generate Document Structure

```bash
node scripts/agent.js --action init --query "My Application v2.0"
node scripts/agent.js --action import --input threats.json
```

### Step 2: Generate Diagrams and Tables

```bash
node scripts/agent.js --action diagram --input components.json
node scripts/agent.js --action matrix --input threats.json
```

### Step 3: Export Report

```bash
node scripts/agent.js --action report --input document.json --output report.json
```

## Verification

- [ ] Document follows standardized template with all required sections
- [ ] DFDs accurately reflect current architecture
- [ ] Every threat has a unique ID, category, severity, and linked mitigation
- [ ] Risk matrix shows likelihood x impact for all high-severity threats
- [ ] Mitigation plan includes owners, deadlines, and verification criteria
- [ ] Document is version-controlled and review-dated

## References

- [OWASP Threat Modeling Documentation](https://owasp.org/www-community/Threat_Modeling)
- [Threat Modeling Manifesto](https://www.threatmodelingmanifesto.org/)
- [SAFECode — Tactical Threat Modeling](https://safecode.org/resource-secure-development-practices/tactical-threat-modeling/)
- [NIST SP 800-30 — Risk Assessment Documentation](https://csrc.nist.gov/publications/detail/sp/800-30/rev-1/final)
