Threat Model

When to Apply

• User asks to threat model, security review, or map attack surfaces for a codebase
• Starting work on security-sensitive features (auth, crypto, file I/O, networking, native bridges)
• Evaluating a new codebase or major architectural change for security implications
• Reviewing a PR or recent commits for security regressions (incremental/diff mode)
• After a security incident to reassess the threat landscape

Workflow Overview

Phase 0 (conditional): Diff Analysis — if git range provided, scope to changed code
Phase 1:  Codebase Survey        → Understand what the project is and does
Phase 2:  Component Mapping      → Identify components, data flows, and language bridges
Phase 3:  Asset Identification   → Determine what needs protecting
Phase 4:  Trust Boundaries       → Classify inputs by trust level, inventory entry points
Phase 5:  Data Flow Tracing      → Follow untrusted values from entry to sink ← key technique
Phase 6:  Attack Surface Enum    → Document surfaces with traced evidence
Phase 7:  Pattern Clustering     → Group 3+ similar findings by root cause
Phase 8:  Exploit Chains         → Combine findings into multi-step attack paths
Phase 9:  Calibration            → Rate with chain-adjusted and systemic severity
Phase 10: Output                 → Write structured THREAT-MODEL.md

How to Use

1. Read methodology for the detailed approach at each phase
2. Read output format for the document structure (6 sections)
3. Consult attack patterns for technology-specific patterns
4. Run

   scripts/trace-data-flows.sh <project-root>

   to inventory entry points and sinks
5. Optionally run

   scripts/scan-patterns.sh <project-root>

   for security-relevant code patterns

Analytical Techniques

Key Principles

• Evidence over speculation: Every finding should include a data flow trace showing how untrusted input reaches the vulnerable operation. "XSS is possible" is speculation. "RFC markdown → marked.parse() → innerHTML at line 917 with no sanitizer" is evidence.
• Systemic over individual: When 3+ findings share a root cause, the systemic finding is more important than any individual finding. Fix the root cause, not the symptoms.
• Chains over singletons: Rate combined attack paths by their terminal impact. Three medium findings that chain into critical impact are a critical finding.
• Existing mitigations matter: Document what's already protected, not just what's missing.
• Context-aware calibration: Severity depends on deployment context. Always include scope notes.

Output

• findings.json

  — Structured, machine-readable findings. Source of truth. Consumed by

  threat-patch

  for automated remediation. Tracks finding state across runs (open → patched → verified → closed).

• THREAT-MODEL.md

  — Human-readable view generated from findings.json. 6 sections: Overview, Trust Boundaries, Attack Surfaces, Systemic Findings, Exploit Chains, Criticality Calibration.

Pipeline Integration

threat-model → findings.json → threat-patch (consumes findings, generates fixes)
     ↑                                          ↓
     └── threat-model --diff (re-analyzes, updates finding status) ←── git commits

findings.json

• Track which findings are still open vs patched
• Calibrate severity against prior ratings
• Detect regressions (fixed findings that reappeared)

Two Modes

References