Threat Modeling

Systematic identification, documentation, and mitigation of security threats.

Triggers

Phrase	Context
`threat model`	Starting or updating a threat model
`attack surface analysis`	Identifying exposure points
`security architecture review`	Reviewing design for vulnerabilities
`STRIDE analysis`	Applying STRIDE methodology
`what can go wrong`	Brainstorming security concerns

Quick Reference

Input	Output	Destination
Architecture diagram or description	Threat matrix with STRIDE categories	`.agents/security/threat-models/`
Component list	Trust boundary analysis	`.agents/security/threat-models/`
Data flow description	Data flow diagram threats	`.agents/security/threat-models/`
Prior threat model	Updated model with delta analysis	`.agents/security/threat-models/`

Process Overview

                         OWASP Four-Question Framework
                         =============================

          Q1: What are we        Q2: What can         Q3: What do we      Q4: Did we do
          working on?            go wrong?            do about it?        a good job?
               |                      |                    |                   |
               v                      v                    v                   v
        +-----------+          +------------+        +-----------+       +----------+
        | Phase 1   |          | Phase 2    |        | Phase 3   |       | Phase 4  |
        | Scope &   |  ----->  | Threat     | -----> | Mitigation| ----> | Validate |
        | Decompose |          | Identify   |        | Strategy  |       | Model    |
        +-----------+          +------------+        +-----------+       +----------+
              |                      |                    |                   |
              v                      v                    v                   v
        Trust Boundaries       STRIDE Matrix         Prioritized         Threat Model
        Data Flows             Kill Chains           Mitigations         Document
        Assets                 Attack Trees          Risk Ratings

When to Use

Use this skill when:

Designing new features that handle sensitive data or authentication
Reviewing architecture for security vulnerabilities
After a security incident to identify additional attack vectors
Before a security audit to prepare documentation

Use security-detection instead when:

Detecting security-critical file changes in a PR (automated scanning)

Use pre-mortem instead when:

Identifying general project risks, not specifically security threats

Phase 1: Scope and Decompose

OWASP Q1: What are we working on?

1.1 Define Scope

Determine what you are threat modeling:

Scope Level	Examples	Typical Depth
Sprint	Single feature, API endpoint	1-2 hours
Component	Auth module, payment service	Half day
System	Entire application	1-2 days
Enterprise	Multiple systems	Multi-day workshop

Document scope in the threat model header:

## Scope

- **Subject**: [Feature/Component/System name]
- **Boundaries**: [What is IN scope and OUT of scope]
- **Stakeholders**: [Who requested, who will review]
- **Date**: [When analysis performed]
- **Version**: [Model version for tracking changes]

1.2 Create Architecture Model

Choose appropriate diagram type:

Diagram Type	Best For	Tools
Data Flow Diagram (DFD)	Most threat models	Mermaid, draw.io
Component Diagram	Service boundaries	Mermaid, PlantUML
Sequence Diagram	Auth/data flows	Mermaid
Deployment Diagram	Infrastructure threats	Mermaid

Required DFD Elements:

+----------+     HTTPS      +----------+     SQL       +----------+
| External | -------------> |  Process | ------------> |  Data    |
|  Entity  |                |          |               |  Store   |
+----------+                +----------+               +----------+
     |                           |
     |     Trust Boundary        |
     +---------------------------+

External Entities: Users, third-party systems (outside your control)
Processes: Code that transforms data (your application)
Data Stores: Databases, files, caches (where data persists)
Data Flows: Arrows showing data movement (labeled with protocol)
Trust Boundaries: Dashed lines showing privilege changes

1.3 Identify Assets

List what attackers want:

Asset Category	Examples
Data	PII, credentials, financial, health
Compute	CPU cycles, storage, network bandwidth
Access	Admin privileges, API keys, tokens
Reputation	Brand trust, user confidence
Availability	Service uptime, response time

1.4 Map Trust Boundaries

Identify where privilege levels change:

Network boundaries (internet to internal)
Process boundaries (user to kernel)
Authentication boundaries (anonymous to authenticated)
Authorization boundaries (user to admin)

Phase 2: Threat Identification

OWASP Q2: What can go wrong?

2.1 Apply STRIDE per Element

For each element in your diagram, apply STRIDE:

Category	Definition	Applies To	Example Questions
Spoofing	Pretending to be someone else	External entities, data flows	Can an attacker impersonate a user?
Tampering	Modifying data or code	Processes, data stores, data flows	Can data be modified in transit/at rest?
Repudiation	Denying an action	Processes	Can users deny performing actions?
Info Disclosure	Exposing information	Data stores, data flows	Can sensitive data leak?
Denial of Service	Making service unavailable	Processes, data stores	Can resources be exhausted?
Elevation of Privilege	Gaining unauthorized access	Processes	Can users escalate privileges?

STRIDE Applicability Matrix:

Element Type	S	T	R	I	D	E
External Entity	X
Process	X	X	X	X	X	X
Data Store		X		X	X
Data Flow		X		X	X

2.2 Build Threat Matrix

Use the generate script to create a structured matrix:

python .claude/skills/threat-modeling/scripts/generate_threat_matrix.py \
    --scope "Authentication Service" \
    --output .agents/security/threat-models/auth-threats.md

Manual Format:

## Threat Matrix

| ID | Element | STRIDE | Threat | Likelihood | Impact | Risk |
|----|---------|--------|--------|------------|--------|------|
| T001 | Login API | S | Credential stuffing | High | High | Critical |
| T002 | Session Store | T | Session fixation | Medium | High | High |
| T003 | Audit Log | R | Log tampering | Low | Medium | Medium |

2.3 Advanced Analysis (Optional)

For complex threats, use advanced techniques like attack trees and kill chains. See references/advanced-analysis.md.

Phase 3: Mitigation Strategy

OWASP Q3: What are we going to do about it?

3.1 Risk Rating

Calculate risk for prioritization:

Risk = Likelihood x Impact

Likelihood Scale:
  High (3)   = Exploitable with public tools, no auth required
  Medium (2) = Requires some skill or access
  Low (1)    = Requires significant effort or insider access

Impact Scale:
  High (3)   = Data breach, system compromise, regulatory violation
  Medium (2) = Limited data exposure, service degradation
  Low (1)    = Minor inconvenience, no sensitive data

Risk Matrix:

	Impact: Low	Impact: Medium	Impact: High
High Likelihood	Medium	High	Critical
Medium Likelihood	Low	Medium	High
Low Likelihood	Low	Low	Medium

3.2 Select Mitigation Strategy

Strategy	When to Use	Example
Mitigate	Risk can be reduced to acceptable level	Add input validation
Accept	Cost of mitigation exceeds risk	Low-impact, unlikely threat
Transfer	Someone else can manage risk better	Cyber insurance, third-party service
Eliminate	Remove the vulnerable component	Drop unused feature

3.3 Document Mitigations

For each threat, document:

### T001: Credential Stuffing on Login API

**Risk**: Critical (High Likelihood x High Impact)

**Mitigations**:

1. **Implement rate limiting** (Mitigate)
   - Max 5 attempts per IP per minute
   - Progressive delays after failures
   - Status: Planned for Sprint 23

2. **Add CAPTCHA after failures** (Mitigate)
   - Trigger after 3 failed attempts
   - Status: In progress

3. **Enable MFA** (Mitigate)
   - TOTP or WebAuthn
   - Status: Blocked on product decision

**Residual Risk**: Medium (after mitigations applied)

3.4 Generate Mitigation Roadmap

python .claude/skills/threat-modeling/scripts/generate_mitigation_roadmap.py \
    --input .agents/security/threat-models/auth-threats.md \
    --output .agents/security/threat-models/auth-roadmap.md

Phase 4: Validation

OWASP Q4: Did we do a good job?

4.1 Model Validation

Run the validation script:

python .claude/skills/threat-modeling/scripts/validate_threat_model.py \
    .agents/security/threat-models/auth-threats.md

Validation Checks:

All components have at least one threat identified
All trust boundaries are crossed by at least one data flow
All STRIDE categories considered for applicable elements
All Critical/High risks have mitigations planned
No orphaned threats (threats without parent component)

4.2 Peer Review

Request review from:

Security team member
Architect familiar with the system
Developer implementing mitigations

4.3 Schedule Updates

Threat models are living documents. Update when:

New features added
Architecture changes
Security incident occurs
During regular security reviews (quarterly recommended)

Scripts

Script	Purpose	Usage
`generate_threat_matrix.py`	Create structured threat matrix	`python scripts/generate_threat_matrix.py --scope "Name" --output path.md`
`generate_mitigation_roadmap.py`	Create prioritized roadmap	`python scripts/generate_mitigation_roadmap.py --input threats.md --output roadmap.md`
`validate_threat_model.py`	Validate model completeness	`python scripts/validate_threat_model.py <model.md>`

Exit Codes

Code	Meaning
0	Success / Validation passed
1	General failure
10	Validation failed (missing required elements)

Templates

Threat Model Document

Use the template at: templates/threat-model-template.md

Threat Entry

### T{NNN}: {Threat Title}

**Element**: {Component name from DFD}
**STRIDE**: {S/T/R/I/D/E}
**Description**: {What the threat is}

**Attack Scenario**:
1. Attacker does X
2. System responds with Y
3. Attacker achieves Z

**Likelihood**: {High/Medium/Low} - {Justification}
**Impact**: {High/Medium/Low} - {Justification}
**Risk**: {Critical/High/Medium/Low}

**Mitigations**:
- [ ] {Mitigation 1} - {Status}
- [ ] {Mitigation 2} - {Status}

**Residual Risk**: {After mitigations}
**References**: {CVEs, OWASP links, etc.}

Integration with Agent System

Related Agents

Agent	Relationship
security	Invoke for detailed vulnerability analysis
architect	Review threat model during design
analyst	Research specific attack patterns
qa	Include threat scenarios in test strategy

Memory Integration

Query Forgetful memory for prior threat models:

mcp__forgetful__execute_forgetful_tool("query_memory", {
    "query": "threat model authentication",
    "query_context": "Finding prior security analysis"
})

Store threat model summaries:

mcp__forgetful__execute_forgetful_tool("create_memory", {
    "title": "Auth Service Threat Model Summary",
    "content": "Key threats: credential stuffing, session hijacking...",
    "context": "Security analysis Q1 2026",
    "keywords": ["threat-model", "authentication", "STRIDE"],
    "tags": ["security"],
    "importance": 8,
    "project_ids": [1]
})

Anti-Patterns

Avoid	Why	Instead
Threat model once and forget	Security landscape evolves	Schedule regular updates
Skip trust boundary analysis	Miss privilege escalation paths	Always map boundaries first
Generic threats only	Not actionable	Be specific to your system
No risk ratings	Cannot prioritize	Rate every threat
Mitigations without owners	Never implemented	Assign owners and deadlines
Copy-paste from templates	Miss system-specific threats	Use templates as starting points

References

Verification

Success Criteria

Criterion	Verification
All components have threats	Validation script check
All STRIDE categories considered	Validation script check
All Critical/High risks have mitigations	Validation script check
Risk ratings consistent	Manual review
Peer review completed	Stakeholder sign-off

Verification Command

python .claude/skills/threat-modeling/scripts/validate_threat_model.py <model.md>

Exit code 0 indicates a valid, complete threat model.

Extension Points

Extension	How to Add
Custom STRIDE questions	Add to `references/stride-methodology.md`
New risk rating methodology	Add to `references/risk-rating-guide.md`
Additional threat categories	Extend STRIDE sections in template
Custom validation rules	Modify `validate_threat_model.py`
Integration with SAST tools	Add script in `scripts/`

Related Skills

Skill	Relationship
`security-detection`	Triggers threat model review on sensitive file changes
`codeql-scan`	Validates code against identified threats
`adr-review`	Security agent reviews architecture decisions

threat-modeling