TMDD - Threat Modeling Driven Development

When to Use

Activate when the user asks to:

• Create, initialize, or scaffold a threat model
• Add a feature to an existing threat model
• Threat-model a codebase, service, or feature
• Run or fix tmdd lint errors
• Generate implementation prompts from a threat model

Also auto-activates when editing .tmdd/**/*.yaml files.

Core Principle: Architecture-First Threat Modeling

Every threat model MUST be grounded in the actual codebase. Never produce generic/textbook threats. Before writing any YAML, analyze the code to discover real components, data flows, technologies, and attack surface.

Phase 1 — Codebase Architecture Analysis

Before touching any .tmdd/ file, perform these steps:

1.1 Discover Project Structure

Scan the repository to identify:

• Language & framework (package.json, requirements.txt, go.mod, Cargo.toml, pom.xml, etc.)
• Entry points (main files, route definitions, CLI commands)
• Directory layout (src/, api/, lib/, services/, models/, controllers/, etc.)

1.2 Identify Architectural Components

Search the codebase for real building blocks. Map each to a TMDD component:

For each component, record:

• The actual technology (e.g., "Express.js", "PostgreSQL via Prisma", "Redis")
• The trust boundary (public if internet-facing, internal if behind auth/VPN, external if third-party)
• Key source files/directories it lives in

1.3 Trace Real Data Flows

Follow how data actually moves through the code:

• HTTP requests from clients to API handlers
• Database reads/writes from handlers to ORM/query layer
• Inter-service calls (REST, gRPC, message queues)
• External API calls (payment providers, email services, OAuth providers)
• File uploads, websocket connections, SSE streams

For each flow, note:

• What data is transmitted (credentials, PII, tokens, user content)
• Authentication mechanism (JWT, session cookie, API key, mTLS, none)
• Protocol (HTTPS, gRPC, WebSocket, AMQP)

1.4 Identify Security-Relevant Code Patterns

Scan for patterns that inform threats directly:

• Authentication: How are users authenticated? (JWT, sessions, OAuth, API keys)
• Authorization: Is there RBAC/ABAC? Where are permission checks?
• Input validation: Is there schema validation (Zod, Joi, Pydantic)? Where?
• SQL/ORM usage: Raw queries vs parameterized? Which ORM?
• File handling: Uploads, path traversal risks, temp files?
• Secrets management: Env vars, vault, hardcoded?
• Serialization: JSON parsing, XML, YAML (deserialization attacks)?
• Cryptography: Hashing algorithms, encryption at rest/in transit?
• Error handling: Do errors leak stack traces or internal details?
• Logging: What is logged? Are secrets filtered?
• Rate limiting: Is there any? Where?
• CORS/CSP: What's the policy?

Phase 2 — Threat Model Creation

IMPORTANT — Before editing any YAML file:

1. Check if .tmdd/ already exists and contains populated YAML files
2. If YES: you are in incremental mode — read each file first, then append new entries or edit existing ones. NEVER rewrite a file from scratch. Skip tmdd init. Go directly to Phase 3 if adding a feature, or follow Phase 2.2 in append mode.
3. If NO: you are in creation mode — run tmdd init, then populate files per Phase 2.2

2.1 New Project (no .tmdd/ directory)

bash
1tmdd init .tmdd --template <template> -n "System Name" -d "Description"

Templates: minimal (blank), web-app (7 web threats), api (OWASP API Top 10).

After init, replace the template content with architecture-specific data from Phase 1.

2.2 Populate YAML Files (in order)

YOU MUST EDIT THE FILES DIRECTLY. DO NOT JUST OUTPUT YAML.

NEVER overwrite existing content. Before editing any YAML file:

1. Read the file first to see what entries already exist
2. Append new entries — do not remove or rewrite existing ones unless the user explicitly asks for changes to specific entries
3. When adding threats/mitigations, continue the existing ID sequence (e.g., if T005 exists, start new threats at T006)

Edit these files using the analysis from Phase 1:

1. components.yaml — Map real code to components

yaml
1components:
2  - id: api_backend            # REQUIRED, ^[a-z][a-z0-9_]*$
3    description: "Express.js REST API handling user and order endpoints"
4    type: api                  # frontend|api|service|database|queue|external|cache|other
5    technology: "Node.js / Express"
6    trust_boundary: public     # public|internal|external
7    source_paths:              # OPTIONAL - glob patterns mapping to source files
8      - "src/routes/**"
9      - "src/middleware/**"
10      - "src/server.ts"

Rules:

• One component per distinct architectural unit discovered in Phase 1
• description must mention the actual technology and what it does in this project
• trust_boundary must reflect the real deployment (not assumed)
• source_paths (optional) should list glob patterns for source files that belong to this component. This enables deterministic PR-to-component mapping for threat review workflows. Prefer specific globs over overly broad ones (e.g., src/routes/** over src/**).

2. actors.yaml — Real users and external systems

yaml
1actors:
2  - id: end_user               # REQUIRED, ^[a-z][a-z0-9_]*$
3    description: "Authenticated user accessing the web dashboard"

3. data_flows.yaml — Traced from actual code paths

yaml
1data_flows:
2  - id: df_user_to_api             # REQUIRED
3    source: end_user               # must exist in actors or components
4    destination: api_backend       # must exist in actors or components
5    data_description: "Login credentials (email + password) and session tokens"
6    protocol: HTTPS
7    authentication: JWT

Rules:

• Every flow must correspond to a real code path you found in Phase 1.3
• data_description must name the actual data types (not just "API calls")
• Include protocol and auth method from the code

4. threats/catalog.yaml — Threats specific to THIS codebase

yaml
1threats:
2  T001:                              # ^T\d+$
3    name: "SQL Injection via raw query in search endpoint"
4    description: "The /api/search endpoint in src/routes/search.ts uses string concatenation for the WHERE clause instead of parameterized queries"
5    severity: high                   # low|medium|high|critical
6    stride: T                        # S|T|R|I|D|E
7    cwe: CWE-89
8    suggested_mitigations: [M001]    # each must exist in mitigations.yaml

CRITICAL — Threat Quality Rules:

• name must reference the specific component, endpoint, or module affected
• description must describe the concrete vulnerability in this codebase, not a textbook definition. Reference file paths when possible.
• severity must be based on actual exploitability and impact in this system
• Every threat must be traceable to a component or data flow from Phase 1

STRIDE analysis — apply to each component and data flow:

• Spoofing: Can identities be faked? (check auth implementation)
• Tampering: Can data be modified? (check input validation, CSRF protection)
• Repudiation: Can actions be denied? (check audit logging)
• Information Disclosure: Can data leak? (check error handling, logging, CORS)
• Denial of Service: Can availability be impacted? (check rate limiting, resource limits)
• Elevation of Privilege: Can permissions be bypassed? (check authorization checks)

5. threats/mitigations.yaml — Actionable controls with code references

yaml
1mitigations:
2  # Simple format
3  M001: "Use parameterized queries via Prisma ORM for all database access"
4
5  # Rich format with code references (preferred — ties mitigation to implementation)
6  M002:
7    description: "Zod schema validation on all API request bodies"
8    references:
9      - file: "src/middleware/validate.ts"
10        lines: "12-35"
11      - file: "src/schemas/user.ts"

Rules:

• Reference actual files/lines where the mitigation is (or should be) implemented
• If the mitigation doesn't exist yet, describe it concretely enough to implement
• Use the rich format with references whenever a file location is known

6. threats/threat_actors.yaml

yaml
1threat_actors:
2  TA001: "External attacker"    # ^TA\d+$

7. features.yaml — Features with threat-to-mitigation mapping

yaml
1features:
2  - name: "User Login"            # REQUIRED
3    goal: "Authenticate users"    # REQUIRED
4    data_flows: [df_user_to_api]  # must exist in data_flows.yaml
5    threat_actors: [TA001]        # must exist in threat_actors.yaml
6    threats:                      # MUST be a dict, NOT a list
7      T001: default               # inherit suggested_mitigations from catalog
8      T002: [M003, M005]          # explicit mitigation override
9      T003: accepted              # risk deliberately accepted
10    last_updated: "2026-02-22"    # set by agent to today's date
11    reviewed_at: "2000-01-01"     # SENTINEL — forces stale-review lint warning
12    # reviewed_by: — DO NOT SET. Only a human adds this after manual review.

Threat mapping values:

• default — inherit suggested_mitigations from threats/catalog.yaml (preferred when suggestions fit)
• [M001, M002] — explicit mitigation list (override when you need different controls)
• accepted — risk deliberately accepted without mitigation

Review fields (human-only attestation):

• reviewed_by — name/username of the human analyst who verified the threat mappings. AI agents MUST NOT set this field. Only a human adds it after manual review.
• reviewed_at — date of last review (YYYY-MM-DD). AI agents MUST set this to "2000-01-01" as a sentinel so that last_updated > reviewed_at always triggers a stale-review lint warning. The human updates this to the real date when they review.
• last_updated — date the feature was last created or modified (YYYY-MM-DD). AI agents SHOULD set this to today's date.
• Features with accepted threats and no reviewed_by trigger a lint warning

yaml
1# CORRECT
2threats:
3  T001: default
4  T002: [M001, M002]
5  T003: accepted
6
7# WRONG - will fail lint
8threats: [T001, T002, T003]

Phase 3 — Adding a Feature (existing .tmdd/ project)

When adding a feature to an existing threat model:

3.1 Analyze the feature's code impact

Before editing YAML, answer:

1. What new code paths does this feature introduce? (new endpoints, new DB tables, new external calls)
2. What existing components does it touch?
3. What sensitive data does it handle? (PII, credentials, financial data, tokens)
4. What new attack surface does it create?

3.2 Use the tmdd feature workflow

bash
1# Step 1: Generate threat modeling prompt (new feature)
2tmdd feature "Feature Name" -d "What it does"
3
4# Step 2: Read the generated prompt
5# .tmdd/out/<feature_name>.threatmodel.txt
6
7# Step 3: Edit YAML files using findings from 3.1 (follow order in 3.3 below)
8
9# Step 4: Validate
10tmdd lint .tmdd
11
12# Step 5: Generate implementation prompt (feature now exists)
13tmdd feature "Feature Name"

3.3 Edit files in order

1. components.yaml — Add new components if the feature introduces new architectural units
2. actors.yaml — Add new actors if the feature serves new user types
3. data_flows.yaml — Add flows for new data paths the feature creates
4. threats/catalog.yaml — Add threats specific to the feature's code (not generic threats)
5. threats/mitigations.yaml — Add mitigations referencing actual or planned implementation files
6. features.yaml — Add the feature with full threat->mitigation mapping

Phase 4 — Validation & Compilation

bash
1# Validate all cross-references
2tmdd lint .tmdd
3
4# Generate consolidated output
5tmdd compile .tmdd                        # Full system
6tmdd compile .tmdd --feature "Login"      # Single feature

ID Conventions

File Structure

.tmdd/
  system.yaml            # System metadata
  actors.yaml            # Who interacts with the system
  components.yaml        # Architecture building blocks
  data_flows.yaml        # Data movement between actors/components
  features.yaml          # Features with threat->mitigation mappings
  threats/
    catalog.yaml         # Threat definitions (T001, T002...)
    mitigations.yaml     # Security controls (M001, M002...)
    threat_actors.yaml   # Adversary profiles (TA001, TA002...)

Cross-Reference Rules (enforced by lint)

1. data_flows[].source/destination must exist in actors or components
2. features[].data_flows[] must exist in data_flows.yaml
3. features[].threat_actors[] must exist in threat_actors.yaml
4. features[].threats keys must exist in threats/catalog.yaml
5. features[].threats mitigation values must exist in threats/mitigations.yaml
6. catalog[].suggested_mitigations[] must exist in mitigations.yaml

Self-Validation Checklist

Before finishing edits, verify:

• Phase 1 analysis was performed — components and data flows reflect actual code
• All IDs follow naming conventions
• Every ID referenced in features.yaml exists in its source file
• features.yaml threats is a dict (not a list)
• Threat names/descriptions reference specific components, endpoints, or files
• Mitigations reference actual or planned implementation files where possible
• data_flows source/destination exist in actors or components
• Existing entries in all YAML files were preserved (no accidental overwrites)
• Run tmdd lint .tmdd and fix all errors