Threat Modeling

Threat Modeling

Systematic identification, documentation, and mitigation of security threats.

Triggers

Quick Reference

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:

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:

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:

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:

STRIDE Applicability Matrix:

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:

3.2 Select Mitigation Strategy

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

Exit Codes

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

Memory Integration

Search Serena memory for prior threat models before starting a new one. Use the memory skill, or list and read directly:

mcp__serena__list_memories()

Then read the entries whose names match the component under analysis.

Store the threat model summary as a Serena memory:

mcp__serena__write_memory(
    memory_file_name="security/threat-model-auth-service",
    content="Key threats: credential stuffing, session hijacking. STRIDE categories covered: spoofing, elevation of privilege."
)

Anti-Patterns

References

Supplementary Knowledge

• Defense in Depth - Layered protection architecture for mitigation strategy design
• Zero Trust - Context-based verification model for trust boundary analysis
• OWASP Top 10 - Vulnerability category checklist with STRIDE mapping
• Least Privilege - Permission scoping patterns for mitigation recommendations

External

• OWASP Threat Modeling
• Microsoft STRIDE
• Attack Trees (Schneier)
• Lockheed Martin Cyber Kill Chain

Verification

Success Criteria

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

Related Skills