0X6C7879/threat-modeling

<!-- Threat Modeling Skill | Version 3.1.0 (20260313a) | https://github.com/fr33d3m0n/threat-modeling | License: BSD-3-Clause -->

Note: All relative paths in this skill are relative to SKILL_PATH (the directory containing this SKILL.md file).

Threat Modeling Skill v3.1.0 (20260313a)

AI-native automated software risk analysis skill. LLM-driven, Code-First approach for comprehensive security risk assessment, threat modeling, security testing, penetration testing, and compliance checking.

Version Banner

━━━ 🛡️ Threat Modeling Skill v3.1.0 (20260313a) ━━━

Command Line Flags

| Flag | Description | Default | |------|-------------|---------| | --debug | Publish internal YAML data files, KB queries, coverage validation, and evaluation report | OFF | | --lang=xx | Set output language (en, zh, ja, ko, es, fr, de, pt, ru) | Auto-detect | | --detailed | Auto-trigger P8R (detailed per-VR analysis reports) after P8 completes | OFF |

Usage Examples:

# Default mode - 11 deliverable files only
/threat-model @my-project

# Debug mode - all internal files published
/threat-model @my-project --debug

# Chinese output with debug
/threat-model @my-project --lang=zh --debug

# Generate detailed per-VR analysis reports after P8
/threat-model @my-project --detailed

# Full options
/threat-model @my-project --detailed --debug --lang=zh

---

⚠️ CRITICAL: Data vs Report Separation

PRINCIPLE: Markdown is for reports (human-readable), YAML is for data (machine-readable). They MUST be separated!

┌─────────────────────────────────────────────────────────────────────┐
│  DUAL OUTPUT MODEL - Each phase produces TWO files:                 │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  1. DATA FILE (.yaml) - PRIMARY                                     │
│     • Written FIRST                                                  │
│     • Structured, machine-readable                                   │
│     • Used by NEXT phase as input                                    │
│     • Path: .phase_working/{SESSION_ID}/data/P{N}_*.yaml            │
│                                                                      │
│  2. REPORT FILE (.md) - SECONDARY                                   │
│     • Written AFTER data file                                        │
│     • Human-readable, formatted                                      │
│     • For review and documentation                                   │
│     • Path: .phase_working/{SESSION_ID}/reports/P{N}-*.md           │
│                                                                      │
│  ❌ FORBIDDEN: Reading .md files for data extraction                │
│  ❌ FORBIDDEN: Embedding data as yaml blocks inside .md AS SOURCE   │
│  ✅ ALLOWED: YAML blocks in .md for schema documentation/examples   │
│  ✅ REQUIRED: Data flows via .yaml files only                       │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

---

§1 Execution Model

Mode: Full Assessment Only - All 8 phases executed sequentially.

Phase 1 ──► Phase 2 ──► Phase 3 ──► Phase 4 ──► Phase 5 ──► Phase 6 ──► Phase 7 ──► Phase 8
   │            │            │            │            │            │            │
   ▼            ▼            ▼            ▼            ▼            ▼            ▼
P1.yaml ──► P2.yaml ──► P3.yaml ──► P4.yaml ──► P5.yaml ──► P6.yaml ──► P7.yaml ──► P8.yaml

Rules:

1. Phases execute strictly in order (1→8)
2. Each phase reads previous phase's YAML, writes its own YAML
3. Each phase also writes a human-readable .md report
4. Validation runs on YAML files, not .md files
5. Phase 6 = Risk Validation (NOT mitigation)
6. Phase 7 = Mitigation Planning (AFTER validation)

Phase Gate Protocol:

FOR each phase N in [1..8]:
    1. Read: @phases/P{N}-*.md (instructions)
    2. Read: .phase_working/{SESSION_ID}/data/P{N-1}_*.yaml (input, except P1)
    3. Execute analysis per phase instructions
    4. Write: .phase_working/{SESSION_ID}/data/P{N}_*.yaml (PRIMARY output)
    5. Write: .phase_working/{SESSION_ID}/reports/P{N}-*.md (SECONDARY output)
    6. Hook validates YAML file
    7. IF exit != 0: Fix YAML and rewrite
    8. IF exit == 0: Update session meta, continue to N+1

---

§2 Output Convention

Output Modes

┌─────────────────────────────────────────────────────────────────────┐
│  OUTPUT MODES - Control what files are generated                    │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  DEFAULT MODE (Production)                                          │
│  ─────────────────────────────────────────────────────────────────  │
│  Only user-deliverable files are published:                         │
│  ✅ 4 Required Reports (RISK-ASSESSMENT, INVENTORY, MITIGATION,    │
│                         PENETRATION-TEST-PLAN)                      │
│  ✅ 7 Phase Reports (P1-P7-*.md) for audit trail                    │
│  ❌ .phase_working/ - NOT published (kept internally)               │
│  ❌ YAML data files - NOT published                                 │
│  ❌ EVALUATION-REPORT.md - NOT published                            │
│                                                                      │
│  DEBUG MODE (--debug flag)                                          │
│  ─────────────────────────────────────────────────────────────────  │
│  All files are published including internal data:                   │
│  ✅ All default mode outputs                                        │
│  ✅ .phase_working/{SESSION_ID}/data/*.yaml - Published             │
│  ✅ P5_knowledge_base_queries.yaml - Published                      │
│  ✅ P8_coverage_validation.yaml - Published                         │
│  ✅ EVALUATION-REPORT.md - Published                                │
│                                                                      │
│  Usage: /threat-model @project --debug                              │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Directory Structure

Default Mode (11 files published):

{PROJECT_ROOT}/
└── Risk_Assessment_Report/
    ├── {PROJECT}-RISK-ASSESSMENT-REPORT.md    ← Required (P8)
    ├── {PROJECT}-RISK-INVENTORY.md            ← Required (P6)
    ├── {PROJECT}-MITIGATION-MEASURES.md       ← Required (P7)
    ├── {PROJECT}-PENETRATION-TEST-PLAN.md     ← Required (P6)
    ├── P1-PROJECT-UNDERSTANDING.md            ← Phase reports
    ├── P2-DFD-ANALYSIS.md
    ├── P3-TRUST-BOUNDARY.md
    ├── P4-SECURITY-DESIGN-REVIEW.md
    ├── P5-STRIDE-THREATS.md
    ├── P6-RISK-VALIDATION.md
    ├── P7-MITIGATION-PLAN.md
    ├── detailed/                              ← P8R only (--detailed flag)
    │   ├── VR-001-{title-slug}.md
    │   └── ...
    └── html/                                  ← HTML output (report_generator.py)
        ├── index.html
        ├── {PROJECT}-RISK-ASSESSMENT-REPORT.html
        ├── ...
        └── detailed/
            └── VR-001-{slug}.html

Debug Mode (--debug, full structure):

{PROJECT_ROOT}/
└── Risk_Assessment_Report/
    ├── {PROJECT}-RISK-ASSESSMENT-REPORT.md    ← Main report (from P8)
    ├── {PROJECT}-RISK-INVENTORY.md            ← From P6 YAML
    ├── {PROJECT}-MITIGATION-MEASURES.md       ← From P7 YAML
    ├── {PROJECT}-PENETRATION-TEST-PLAN.md     ← From P6 YAML
    ├── {PROJECT}-ARCHITECTURE-ANALYSIS.md     ← From P1-P3 YAML
    ├── {PROJECT}-DFD-DIAGRAM.md               ← From P2 YAML
    ├── {PROJECT}-COMPLIANCE-REPORT.md         ← From P4+P7 YAML
    ├── {PROJECT}-ATTACK-PATH-VALIDATION.md    ← From P6 YAML
    ├── P1-PROJECT-UNDERSTANDING.md            ← Published phase reports
    ├── P2-DFD-ANALYSIS.md
    ├── P3-TRUST-BOUNDARY.md
    ├── P4-SECURITY-DESIGN-REVIEW.md
    ├── P5-STRIDE-THREATS.md
    ├── P6-RISK-VALIDATION.md
    ├── EVALUATION-REPORT.md                   ← DEBUG ONLY
    └── .phase_working/                        ← DEBUG ONLY
        ├── _sessions_index.yaml               ← Multi-session index (optional)
        └── {SESSION_ID}/                      ← Session isolated directory
            ├── _session_meta.yaml             ← Session state
            ├── data/                          ← STRUCTURED DATA
            │   ├── P1_project_context.yaml
            │   ├── P2_dfd_elements.yaml
            │   ├── P3_boundary_context.yaml
            │   ├── P4_security_gaps.yaml
            │   ├── P5_threat_inventory.yaml
            │   ├── P5_knowledge_base_queries.yaml  ← KB transparency
            │   ├── P6_validated_risks.yaml
            │   ├── P7_mitigation_plan.yaml
            │   ├── P8_report_manifest.yaml
            │   └── P8_coverage_validation.yaml     ← Coverage metrics
            ├── reports/                       ← WORKING REPORTS
            │   └── (phase reports during execution)
            └── data/P8R_manifest.yaml         ← P8R manifest (--detailed only)

Naming Convention

• PROJECT: Uppercase, max 30 chars, format: ^[A-Z][A-Z0-9-]{0,29}$
• Example: OPEN-WEBUI, MY-PROJECT, STRIDE-DEMO

Session ID Format

• SESSION_ID: {PROJECT_NAME}_{YYYYMMDD_HHMMSS}
• Example: OPEN-WEBUI_20260130_143022

Session Metadata

# .phase_working/{SESSION_ID}/_session_meta.yaml
schema_version: "3.1.0 (20260313a)"
session_id: "OPEN-WEBUI_20260130_143022"  # {PROJECT}_{YYYYMMDD_HHMMSS}
project_name: "OPEN-WEBUI"
project_path: "/path/to/project"
started_at: "ISO8601 timestamp"
language: "en"
skill_version: "3.1.0 (20260313a)"

phases:
  P1:
    status: "completed"
    started_at: "2026-01-30T10:00:00Z"
    completed_at: "2026-01-30T10:30:00Z"
    data_file: "data/P1_project_context.yaml"
    report_file: "reports/P1-PROJECT-UNDERSTANDING.md"
  P2:
    status: "in_progress"
    # ...

---

§3 Core Data Model

See @assets/contracts/data-model.yaml for complete schema definitions.

Entity Types

| Entity | ID Format | Phase | Description | |--------|-----------|-------|-------------| | Module | M-{Seq:03d} | P1 | Code modules/components | | Finding | F-P{N}-{Seq:03d} | P1-P3 | Security observations (factual) | | Gap | GAP-{Seq:03d} | P4 | Security control deficiencies | | Threat | T-{STRIDE}-{Element}-{Seq} | P5 | STRIDE threats | | ValidatedRisk | VR-{Seq:03d} | P6 | Verified risks | | Mitigation | MIT-{Seq:03d} | P7 | Remediation measures | | POC | POC-{Seq:03d} | P6 | Proof of concept | | AttackPath | AP-{Seq:03d} | P6 | Attack vectors (single path) | | AttackChain | AC-{Seq:03d} | P6 | Multi-step attack sequences | | TestCase | TC-{Seq:03d} | P8 | Penetration test cases | | DetailedRiskRpt | (uses VR-{Seq:03d}) | P8R | Per-VR analysis report |

Finding vs Gap Semantic Boundary

• Finding (F-P{N}-xxx): A factual observation from phases 1-3 that MAY have security implications. Findings are objective facts about architecture, data flows, or boundaries. Example: "API endpoint uses HTTP instead of HTTPS"

• Gap (GAP-xxx): A security control deficiency identified in P4 after analyzing findings against security domains. Gaps represent missing or inadequate controls. Example: "Missing TLS enforcement (NETWORK domain)"

Transition Rule: Findings from P1-P3 feed into P4 analysis. P4 evaluates findings against 16 security domains and produces Gaps where controls are deficient.

DFD Element IDs

| Element Type | Prefix | Format | Example | |--------------|--------|--------|---------| | External Interactor | EI | EI-{NNN} | EI-001 | | Process | P | P-{NNN} | P-001 | | Data Store | DS | DS-{NNN} | DS-001 | | Data Flow | DF | DF-{NNN} | DF-001 | | Trust Boundary | TB | TB-{NNN} | TB-001 |

Count Conservation (P5→P6 Threat Accounting)

P5.threat_count = P6.verified + P6.theoretical + P6.pending + P6.excluded

All threats from P5 must be accounted for in P6 (no threat loss).

Semantic Distinction:

• Count Conservation: P5→P6 threat accounting (threats flow from P5 to P6 dispositions)
• Element Coverage Verification: P2→P5 element coverage (every DFD element has STRIDE analysis)

---

§4 Security Knowledge Architecture

See @knowledge/ for complete reference materials (~11 MB, 113 files).

Three Knowledge Sets

1. Security Control Set (What to do)

   • 16 Security Domains (AUTHN, AUTHZ, INPUT, etc.)
   • Control Sets (18 files, 107 controls)
   • OWASP References (74 items)
   • Compliance Frameworks (14 frameworks)

2. Threat Pattern Set (What to know)

   • CWE Weaknesses (974)
   • CAPEC Attack Patterns (615)
   • ATT&CK Techniques (835)
   • CVE/KEV Vulnerabilities (323K+)

3. Verification Set (How to test)

   • WSTG Tests (121)
   • MASTG Tests (206)
   • ASVS Requirements (345)

Security Principles (11)

| Code | Principle | Definition | |------|-----------|------------| | DID | Defense in Depth | Multiple independent security controls | | LP | Least Privilege | Minimum permissions required | | ZT | Zero Trust | Never trust, always verify | | FS | Fail Secure | Default to secure state on error | | SOD | Separation of Duties | Critical ops require multiple parties | | SBD | Secure by Default | Default config is secure | | CM | Complete Mediation | Every access verified | | EOM | Economy of Mechanism | Simple, auditable mechanisms | | OD | Open Design | Security not dependent on secrecy | | IV | Input Validation | All input validated | | LA | Least Agency | Limit AI agent autonomy |

STRIDE Categories

| STRIDE | Name | CWEs | CAPEC | |--------|------|------|-------| | S | Spoofing | CWE-287, 290, 307 | CAPEC-151, 194, 600 | | T | Tampering | CWE-20, 77, 78, 89 | CAPEC-66, 88, 248 | | R | Repudiation | CWE-117, 223, 778 | CAPEC-93 | | I | Information Disclosure | CWE-200, 209, 311 | CAPEC-116, 157 | | D | Denial of Service | CWE-400, 770, 918 | CAPEC-125, 227 | | E | Elevation of Privilege | CWE-269, 284, 862 | CAPEC-122, 233 |

---

§5 Knowledge Base Queries

kb Wrapper Usage

# Get skill path
SKILL_PATH=$(bash skill_path.sh)

# STRIDE queries
$SKILL_PATH/kb --stride spoofing
$SKILL_PATH/kb --stride-controls S

# CWE queries
$SKILL_PATH/kb --cwe CWE-89
$SKILL_PATH/kb --full-chain CWE-89

# Attack patterns
$SKILL_PATH/kb --capec CAPEC-89
$SKILL_PATH/kb --attack-technique T1078

# Verification tests
$SKILL_PATH/kb --stride-tests S
$SKILL_PATH/kb --wstg-category ATHN

# LLM/AI extensions
$SKILL_PATH/kb --all-llm
$SKILL_PATH/kb --ai-component

---

§6 Language Adaptation

Output language follows context language unless --lang=xx specified.

| Context | File Names | Content | |---------|------------|---------| | Chinese | P1-项目理解.md | 中文 | | English | P1-PROJECT-UNDERSTANDING.md | English |

Supported: en, zh, ja, ko, es, fr, de, pt, ru

---

§7 Progressive Context Loading

This skill uses progressive disclosure:

1. Always Loaded: This file (SKILL.md) - ~5.5K tokens
2. Session Start: @WORKFLOW.md - ~4.8K tokens
3. Per Phase: @phases/P{N}-*.md - ~4K-10K tokens each (varies by phase)

Total per-phase context: ~12K-18K tokens per phase (vs 30K monolithic)

Loading Pattern:

Session Start:
  1. Load SKILL.md (global rules)
  2. Load WORKFLOW.md (orchestration)
  3. Create 8 phase todos

Per Phase:
  1. Read @phases/P{N}-*.md
  2. Execute phase instructions
  3. Write to .phase_working/{SESSION_ID}/reports/P{N}-*.md
  4. Hook validates and extracts data

Post-P8 (Optional):
  1. If --detailed flag OR user confirms: Load @phases/P8R-DETAILED-REPORT.md
  2. Generate per-VR detailed analysis reports
  3. Write to Risk_Assessment_Report/detailed/VR-{NNN}-{slug}.md

---

§8 Reference Files

| Path | Purpose | |------|---------| | @WORKFLOW.md | Orchestration contracts, phase gates | | @phases/P{1-8}-*.md | Phase-specific instructions | | @assets/contracts/data-model.yaml | Entity schemas | | @knowledge/security-design.yaml | 16 security domains | | @knowledge/security-principles.yaml | 11 security principles | | @knowledge/sast-rules.yaml | SAST tool configs and STRIDE mappings | | @scripts/module_discovery.py | P1 three-layer module discovery | | @scripts/phase_data.py | Phase validation and extraction | | @scripts/unified_kb_query.py | Knowledge base queries | | @scripts/report_generator.py | MD→HTML batch converter | | @phases/P8R-DETAILED-REPORT.md | Optional per-VR detailed reports | | @docs/REPORT-DESIGN.md | v3.0.3+ report enhancement design | | @skill_path.sh | SKILL_PATH resolution helper |

---

§9 Quick Start

# 1. Start new session (default mode - 11 deliverable files)
/threat-model @my-project

# 2. With debug mode (all internal files published)
/threat-model @my-project --debug

# 3. Session execution:
#    - Claude loads SKILL.md + WORKFLOW.md automatically
#    - For each phase N (1-8): Read → Execute → Write → Validate
#    - Generate final reports in Risk_Assessment_Report/

Output Summary

| Mode | Files Published | Use Case | |------|-----------------|----------| | Default | 11 (4 required + 7 phase reports) | Production delivery | | --detailed | 11 + per-VR detailed reports | Comprehensive assessment | | --debug | 11 + YAML data + evaluation | Development, audit |

---

§10 Core Execution Constraints (Invariants)

PRINCIPLE: The quality of threat modeling depends on execution rigor. The following constraints are INVIOLABLE.

Three Absolute Prohibitions

| Constraint | Description | Violation Consequence | |------------|-------------|----------------------| | ❌ NO MOCK DATA | All analysis must be based on real code evidence | Analysis results invalid | | ❌ NO SIMPLIFIED IMPLEMENTATIONS | Each phase must be fully executed | Coverage requirements not met | | ❌ NO BYPASSING PROBLEMS | Must diagnose root cause when blocked | Data chain broken |

Phase Execution Invariant

∀ Phase N ∈ [1..8]:
  - Input: P{N-1}_*.yaml (except P1)
  - Output: P{N}_*.yaml (PRIMARY) + P{N}-*.md (SECONDARY)
  - Gate: Hook validation must return exit 0
  - Transition: Only proceed to N+1 after gate passes

Execution Protocol Details: See WORKFLOW.md §2 Phase Execution Protocol

---

§11 Phase Isolation Constraints

INVARIANT: Each Phase is an independent execution unit. FSM state transitions MUST follow strict sequential order.

Forbidden State Transitions

| Illegal Transition | Reason | |-------------------|--------| | Pn → Pn+2 (skip) | Violates FSM order invariant (S1) | | Pn → Pn+1 (unvalidated) | Violates data contract completeness (S2) | | Parallel Phase execution | Data dependencies cannot be satisfied |

Complete FSM Specification: See WORKFLOW.md §1 Formal Properties: See docs/SKILL-ARCHITECTURE-DESIGN.md §0.2

---

End of SKILL.md (~540 lines, ~5.5K tokens)