Threat Modeling

# stride-worksheet.yaml - Fill out one per component/trust boundary crossing
component:
  name: "API Gateway"
  owner: "Platform Team"
  data_classification: "Confidential"
  trust_boundary: "External -> Internal"

threats:
  - id: T001
    category: Spoofing
    description: "Attacker forges JWT tokens to impersonate users"
    attack_vector: "Stolen signing key or weak algorithm (HS256 with guessable secret)"
    likelihood: Medium
    impact: Critical
    risk_score: 15  # likelihood(3) x impact(5)
    existing_controls:
      - "JWT validation on every request"
      - "RS256 algorithm with rotated keys"
    gaps:
      - "No token binding to device/IP"
    recommended_mitigations:
      - "Add token binding claims"
      - "Implement short-lived tokens (15 min) with refresh"
      - "Monitor for token reuse from different IPs"
    status: "Mitigated (partial)"
    owner: "Auth Team"

  - id: T002
    category: Tampering
    description: "Man-in-the-middle modifies API requests"
    attack_vector: "Compromised network between client and gateway"
    likelihood: Low
    impact: High
    risk_score: 8
    existing_controls:
      - "TLS 1.3 enforced"
      - "HSTS enabled"
    gaps: []
    recommended_mitigations:
      - "Certificate pinning for mobile clients"
    status: "Mitigated"
    owner: "Platform Team"

  - id: T003
    category: Information Disclosure
    description: "Verbose error messages leak internal details"
    attack_vector: "Triggering errors returns stack traces, internal IPs, DB schema"
    likelihood: High
    impact: Medium
    risk_score: 12
    existing_controls:
      - "Generic error pages in production"
    gaps:
      - "Some microservices return raw exceptions"
    recommended_mitigations:
      - "Centralized error handling middleware"
      - "Error response schema validation"
    status: "Open"
    owner: "Backend Team"

  - id: T004
    category: Denial of Service
    description: "API rate limiting bypass through distributed requests"
    attack_vector: "Botnet sending requests below per-IP threshold"
    likelihood: Medium
    impact: High
    risk_score: 12
    existing_controls:
      - "Per-IP rate limiting at WAF"
    gaps:
      - "No aggregate rate limiting"
      - "No bot detection"
    recommended_mitigations:
      - "Add aggregate rate limiting per endpoint"
      - "Deploy bot detection (Cloudflare Bot Management)"
      - "Implement circuit breaker pattern"
    status: "Open"
    owner: "Platform Team"

  - id: T005
    category: Elevation of Privilege
    description: "IDOR allows accessing other users' data"
    attack_vector: "Manipulating resource IDs in API calls"
    likelihood: Medium
    impact: Critical
    risk_score: 15
    existing_controls:
      - "Authentication required"
    gaps:
      - "Authorization checks inconsistent across endpoints"
    recommended_mitigations:
      - "Enforce ownership checks on all resource access"
      - "Use opaque IDs instead of sequential integers"
      - "Add authorization integration tests"
    status: "Open"
    owner: "Backend Team"

                    Trust Boundary: Internet
                    ==========================
                           |
                    [External User]
                           |
                      HTTPS/443
                           |
                    ==========================
                    Trust Boundary: DMZ
                    ==========================
                           |
                    (WAF / CDN)
                           |
                    [API Gateway]---->[Auth Service]--->[Identity DB]
                           |
                    ==========================
                    Trust Boundary: Internal
                    ==========================
                           |
                    [App Service]
                       /       \
                      /         \
               [Cache]       [Message Queue]
                                  |
                           [Worker Service]
                                  |
                    ==========================
                    Trust Boundary: Data
                    ==========================
                                  |
                           [Primary DB]--->[Replica DB]
                                  |
                           [Object Store]

Legend:
  [Box]     = Process
  (Parens)  = External entity / proxy
  ====      = Trust boundary
  --->      = Data flow

{
  "summary": {
    "title": "E-Commerce Platform",
    "owner": "Security Team",
    "description": "Threat model for the e-commerce API platform"
  },
  "detail": {
    "diagrams": [
      {
        "title": "API Data Flow",
        "diagramType": "STRIDE",
        "cells": [
          {
            "type": "tm.Actor",
            "name": "Web Client",
            "threats": []
          },
          {
            "type": "tm.Process",
            "name": "API Gateway",
            "threats": ["T001", "T002", "T003", "T004"]
          },
          {
            "type": "tm.Process",
            "name": "Order Service",
            "threats": ["T005"]
          },
          {
            "type": "tm.Store",
            "name": "Orders Database",
            "threats": ["T006"]
          },
          {
            "type": "tm.Boundary",
            "name": "DMZ"
          },
          {
            "type": "tm.Boundary",
            "name": "Internal Network"
          }
        ]
      }
    ]
  }
}

# threat-library.yaml - Reusable threat patterns
categories:
  authentication:
    - id: TL-AUTH-001
      name: "Credential stuffing"
      description: "Attacker uses leaked credential databases to attempt logins"
      applicable_to: ["login endpoints", "API authentication"]
      mitigations: ["MFA", "rate limiting", "credential breach monitoring", "CAPTCHA"]

    - id: TL-AUTH-002
      name: "Session hijacking"
      description: "Attacker steals session tokens via XSS or network sniffing"
      applicable_to: ["web applications", "APIs with session tokens"]
      mitigations: ["HttpOnly cookies", "TLS", "session binding", "short TTL"]

    - id: TL-AUTH-003
      name: "OAuth token theft"
      description: "Access tokens stolen from logs, URLs, or insecure storage"
      applicable_to: ["OAuth/OIDC integrations"]
      mitigations: ["PKCE", "short-lived tokens", "token binding", "secure storage"]

  injection:
    - id: TL-INJ-001
      name: "SQL injection"
      description: "Malicious SQL in user input executes unauthorized queries"
      applicable_to: ["database-backed endpoints", "search functionality"]
      mitigations: ["parameterized queries", "ORM", "input validation", "WAF"]

    - id: TL-INJ-002
      name: "Command injection"
      description: "User input passed to system commands without sanitization"
      applicable_to: ["file processing", "system administration features"]
      mitigations: ["avoid shell commands", "input allowlisting", "sandboxing"]

    - id: TL-INJ-003
      name: "SSRF (Server-Side Request Forgery)"
      description: "Attacker makes server send requests to internal resources"
      applicable_to: ["URL fetching features", "webhook handlers", "PDF generators"]
      mitigations: ["URL allowlisting", "network segmentation", "metadata endpoint blocking"]

  supply_chain:
    - id: TL-SC-001
      name: "Dependency confusion"
      description: "Malicious package with internal name published to public registry"
      applicable_to: ["npm, pip, maven projects using private packages"]
      mitigations: ["namespace scoping", "registry prioritization", "SBOM monitoring"]

    - id: TL-SC-002
      name: "Compromised CI/CD pipeline"
      description: "Attacker injects malicious code through build system compromise"
      applicable_to: ["all software builds"]
      mitigations: ["SLSA compliance", "signed commits", "ephemeral builders", "provenance"]

  data:
    - id: TL-DATA-001
      name: "Unencrypted data at rest"
      description: "Sensitive data stored without encryption on disk or in database"
      applicable_to: ["databases", "object storage", "backups"]
      mitigations: ["AES-256 encryption", "KMS-managed keys", "encrypted volumes"]

    - id: TL-DATA-002
      name: "PII exposure in logs"
      description: "Personal data written to application or infrastructure logs"
      applicable_to: ["all services handling PII"]
      mitigations: ["log sanitization", "structured logging", "PII detection scanning"]

Impact ->     1        2        3        4        5
Likelihood
    5      Medium    High     High   Critical Critical
    4       Low     Medium    High    High   Critical
    3       Low      Low     Medium   High    High
    2      Info      Low      Low    Medium   High
    1      Info     Info      Low     Low    Medium

risk_treatment:
  critical:  # Score >= 20
    action: "Immediate remediation required"
    sla: "24 hours"
    approval: "CISO"
  high:      # Score 12-19
    action: "Remediation in current sprint"
    sla: "1 week"
    approval: "Security Lead"
  medium:    # Score 6-11
    action: "Remediation in next sprint"
    sla: "1 month"
    approval: "Team Lead"
  low:       # Score 2-5
    action: "Track and address in backlog"
    sla: "1 quarter"
    approval: "Team Lead"
  info:      # Score 1
    action: "Accept risk and document"
    sla: "None"
    approval: "Team Lead"

# Run Threat Dragon locally with Docker
docker run -d \
  --name threat-dragon \
  -p 3000:3000 \
  -e ENCRYPTION_KEYS='["threat-dragon-encryption-key-change-me"]' \
  -e NODE_ENV=production \
  owasp/threat-dragon:v2.2.0

# Access at http://localhost:3000

# Or install as desktop application
# Download from: https://github.com/OWASP/threat-dragon/releases

# .github/workflows/threat-model-review.yml
name: Threat Model Review
on:
  pull_request:
    paths:
      - 'docs/threat-model/**'
      - 'architecture/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate threat model files
        run: |
          for model in docs/threat-model/*.yaml; do
            echo "Validating $model..."
            python -c "
          import yaml, sys
          with open('$model') as f:
              data = yaml.safe_load(f)
          required = ['component', 'threats']
          for r in required:
              if r not in data:
                  print(f'ERROR: Missing required field: {r}')
                  sys.exit(1)
          for t in data.get('threats', []):
              if t.get('status') == 'Open' and t.get('risk_score', 0) >= 12:
                  print(f'WARNING: High-risk open threat: {t[\"id\"]} - {t[\"description\"]}')
          print(f'OK: {len(data[\"threats\"])} threats documented')
          "
          done

      - name: Check for unaddressed critical threats
        run: |
          CRITICAL=$(grep -r "risk_score: \(1[5-9]\|2[0-5]\)" docs/threat-model/*.yaml | grep "status: \"Open\"" | wc -l)
          if [ "$CRITICAL" -gt 0 ]; then
            echo "WARNING: $CRITICAL critical/high-risk threats still open"
            echo "Review required before merging architectural changes"
          fi