threat-modeling
Threat model, security audit, find vulnerabilities, check security of my app, risk assessment, penetration test prep, analyze attack surface, what could an attacker exploit. Use this skill whenever a user wants holistic security analysis of a codebase, application, or project. MUST be invoked instead of analyzing security yourself — it runs a specialized 8-phase STRIDE workflow producing professional deliverables you cannot generate alone: risk assessment reports, DFD diagrams, threat inventories, attack path validation, mitigation plans, and pentest plans. Trigger on: 威胁建模, 安全评估, 渗透测试, 安全分析, 安全审计, 安全检查, 风险评估. NOT for: fixing one specific bug, adding one security feature (rate limiting, CORS), writing tests, CI/CD setup, or debugging errors.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
Its scripts were only partly scanned.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/fr33d3m0n/threat-modeling with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/fr33d3m0n/threat-modeling'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/fr33d3m0n--threat-modeling)HTML
<a href="/listings/fr33d3m0n--threat-modeling"><img src="/api/listings/fr33d3m0n--threat-modeling/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Option 1: Global Installation (Recommended)
# Clone to global skills directory
git clone https://github.com/fr33d3m0n/threat-modeling.git \
~/.claude/skills/threat-modelingOption 2: Project-Local Installation
# Clone to project's .claude/skills directory
mkdir -p .claude/skills
git clone https://github.com/fr33d3m0n/threat-modeling.git \
.claude/skills/threat-modelingRequirements
- Claude Code CLI - Python 3.10+ - SQLite3 (for knowledge base queries)
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 528 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- ---
- name: threat-modeling
- description: |
- Threat model, security audit, find vulnerabilities, check security of my app, risk
- assessment, penetration test prep, analyze attack surface, what could an attacker exploit.
- Use this skill whenever a user wants holistic security analysis of a codebase, application,
- or project. MUST be invoked instead of analyzing security yourself — it runs a specialized
- 8-phase STRIDE workflow producing professional deliverables you cannot generate alone: risk
- assessment reports, DFD diagrams, threat inventories, attack path validation, mitigation
- plans, and pentest plans.
- Trigger on: 威胁建模, 安全评估, 渗透测试, 安全分析, 安全审计, 安全检查, 风险评估.
- NOT for: fixing one specific bug, adding one security feature (rate limiting, CORS),
- writing tests, CI/CD setup, or debugging errors.
- ---
- <!-- Threat Modeling Skill | Version 3.2.0 (20260512a) | https://github.com/fr33d3m0n/threat-modeling | License: BSD-3-Clause -->
- > **Note**: All relative paths in this skill are relative to `SKILL_PATH` / `CLAUDE_SKILL_DIR` (the directory containing this SKILL.md file). Use `${SKILL_PATH:-$CLAUDE_SKILL_DIR}` in Bash commands for cross-runtime compatibility.
- # Threat Modeling Skill v3.2.0 (20260512a)
- 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.2.0 (20260512a) ━━━
- ```
- ## 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**:
- ```bash
- # 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. Validate: python ${SKILL_PATH:-$CLAUDE_SKILL_DIR}/scripts/phase_data.py --phase-end --phase N --root .
- 7. IF exit != 0: Fix YAML and rewrite, re-run --phase-end
- 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
- ```yaml
- # .phase_working/{SESSION_ID}/_session_meta.yaml
- schema_version: "3.2.0 (20260512a)"
- 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.2.0 (20260512a)"
- 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
- ```bash
- # Resolve skill path (works in Claude Code, Codex CLI, and manual testing)
- SKILL_PATH=${SKILL_PATH:-${CLAUDE_SKILL_DIR:-$(bash skill_path.sh)}}
- # STRIDE queries
- ${SKILL_PATH:-$CLAUDE_SKILL_DIR}/kb --stride spoofing
- ${SKILL_PATH:-$CLAUDE_SKILL_DIR}/kb --stride-controls S
- # CWE queries
- ${SKILL_PATH:-$CLAUDE_SKILL_DIR}/kb --cwe CWE-89
- ${SKILL_PATH:-$CLAUDE_SKILL_DIR}/kb --full-chain CWE-89
- # Attack patterns
- ${SKILL_PATH:-$CLAUDE_SKILL_DIR}/kb --capec CAPEC-89
- ${SKILL_PATH:-$CLAUDE_SKILL_DIR}/kb --attack-technique T1078
- # Verification tests
- ${SKILL_PATH:-$CLAUDE_SKILL_DIR}/kb --stride-tests S
- ${SKILL_PATH:-$CLAUDE_SKILL_DIR}/kb --wstg-category ATHN
- # LLM/AI extensions
- ${SKILL_PATH:-$CLAUDE_SKILL_DIR}/kb --all-llm
- ${SKILL_PATH:-$CLAUDE_SKILL_DIR}/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. Run: python ${SKILL_PATH:-$CLAUDE_SKILL_DIR}/scripts/phase_data.py --phase-end --phase N --root .
- 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
- ```bash
- # 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: phase_data.py --phase-end 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)
README.md · README · 409 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- <!-- Threat Modeling Skill | Version 3.2.0 (20260512a) | https://github.com/fr33d3m0n/threat-modeling | License: BSD-3-Clause -->
- # Threat Modeling Skill v3.2.0
- AI-native automated software risk analysis skill. LLM-driven, Code-First approach for comprehensive security risk assessment, threat modeling, security analysis, security audit, and penetration testing.
- ## What's New in v3.2.0
- - **Tool-assisted analysis**: Integrated Luoshu (14 MCP), Ghidra (18 MCP), CodeQL (65 MCP), Joern (15 CWE queries) for deep code and binary analysis
- - **Complex system support**: DFD auto-generation, CFG/DFG analysis, N-hop call chain tracing, semantic code search
- - **Binary reverse engineering**: Ghidra decompilation, radare2 recon, call graphs and cross-references
- - **Automated vulnerability detection**: Joern CWE queries for C/C++, CodeQL security suites
- - **Attack chain verification**: Luoshu call chains + Ghidra decompilation + Joern taint analysis
- - **Explicit phase validation**: Replaced hook-based validation with portable `--phase-end` calls
- - **Tool capabilities matrix**: New `knowledge/tool-capabilities.yaml` for runtime tool discovery
- - 3 new reference documents in `references/` for on-demand tool guidance
- - agentskills.io multi-agent platform compatibility (Claude Code, Codex CLI, IDE extensions)
- See [CHANGELOG.md](CHANGELOG.md) for full version history.
- ## What's New in v3.0.2
- - Major system architecture refactoring, improved security analysis depth and path coverage
- - Backported SM2 state machine from next-gen AI-Native penetration testing system named "Cobweb" for problem-solving in depth
- - Added multi-version task history and precise structured phase outputs for CI/CD integration
- - Optimized context engineering and data disclosure, ~35% token reduction
- See [CHANGELOG.md](CHANGELOG.md) for full version history.
- ## Installation
- ### Option 1: Global Installation (Recommended)
- ```bash
- # Clone to global skills directory
- git clone https://github.com/fr33d3m0n/threat-modeling.git \
- ~/.claude/skills/threat-modeling
- ```
- ### Option 2: Project-Local Installation
- ```bash
- # Clone to project's .claude/skills directory
- mkdir -p .claude/skills
- git clone https://github.com/fr33d3m0n/threat-modeling.git \
- .claude/skills/threat-modeling
- ```
- ### Requirements
- - Claude Code CLI
- - Python 3.10+
- - SQLite3 (for knowledge base queries)
- ## Quick Start
- 1. **Start Claude Code** in your target project directory:
- ```bash
- cd /path/to/your/project
- claude
- ```
- 2. **Invoke the skill** with a simple prompt:
- ```
- /threat-modeling Perform a complete threat model analysis on @.
- ```
- 3. **Follow the 8-phase workflow** - Claude will guide you through each phase.
- ## Usage Modes
- The skill supports **6 flexible application modes** beyond the standard 8-phase workflow:
- ### Mode 1: Complete Workflow (Standard)
- Full 8-phase threat modeling for codebases.
- ```
- /threat-modeling Perform a complete threat model analysis on @/path/to/project
- Project context:
- - This is an e-commerce platform backend API service
- - Built with Django REST Framework
- - User data includes PII and payment information
- Focus areas: Authentication mechanisms, payment flow, API security
- ```
- ### Mode 2: Knowledge Base Consultation
- Use as security consulting resource without executing complete workflow.
- ```
- Query complete information for CWE-89 (SQL Injection),
- including attack patterns, testing methods, and mitigations
- ```
- **Response includes**: CWE overview, related CAPEC patterns, WSTG testing steps, ASVS requirements, mitigation examples.
- ### Mode 3: Deep Vulnerability Analysis
- In-depth analysis of specific vulnerabilities or code snippets.
- ```
- Analyze SSRF risk in this code, construct attack path and design POC
- [Code snippet]
- ```
- **Response includes**: Vulnerability mechanism, attack path, POC design, CWE/CAPEC/ATT&CK mapping.
- ### Mode 4: Security Test Generation
- Generate test cases based on security standards.
- ```
- Generate WSTG-based security test cases for this API endpoint
- ```
- **Response includes**: Authentication, authorization, input validation, session management test cases with payloads.
- ### Mode 5: Forward Integration (Design Phase)
- Pre-emptive threat modeling during design without waiting for code.
- ```
- Conduct STRIDE threat analysis based on this API specification
- [OpenAPI specification]
- ```
- **Response includes**: DFD from API endpoints, trust boundaries, STRIDE enumeration, design recommendations.
- ### Mode 6: Backward Integration (Penetration Testing)
- Attack path and POC design support for pentesting.
- ```
- I found JWT signature verification bypass in the target system,
- help construct complete attack chain
- ```
- **Response includes**: Vulnerability confirmation, attack chain, POC payload, ATT&CK mapping, report template.
- ## Mode Selection Guide
- | Mode | Input | Output | When to Use |
- |------|-------|--------|-------------|
- | **Complete Workflow** | Codebase | Full threat report | Development / Pre-release |
- | **KB Consultation** | Question | Knowledge response | Any stage |
- | **Vulnerability Analysis** | Code / Description | Attack path + POC | Code review / Pentest |
- | **Test Generation** | Target description | Test checklist | Testing phase |
- | **Forward Integration** | Design docs | Design-phase analysis | Design phase |
- | **Backward Integration** | Found vulnerability | Attack chain + Plan | Penetration testing |
- ## Command Line Flags
- | Flag | Description |
- |------|-------------|
- | `--debug` | Publish internal YAML data files and evaluation reports |
- | `--lang=xx` | Set output language (en, zh, ja, ko, es, fr, de, pt, ru) |
- **Examples**:
- ```bash
- /threat-model @my-project # Default mode
- /threat-model @my-project --debug # With internal data
- /threat-model @my-project --lang=zh --debug # Chinese output with debug
- ```
- ## Advanced Scenarios (Extended Prompts)
- Beyond the standard 8-phase workflow, use these extended prompts for deeper security analysis:
- ### Scenario 1: Complete Interface & Data Flow Discovery
- Comprehensive discovery and risk analysis of all system interfaces.
- ```
- /threat-modeling @/path/to/project
- Perform complete interface and data flow discovery analysis:
- 1. Comprehensive discovery of all system interfaces:
- - User interaction interfaces (Web UI, CLI, Mobile)
- - External APIs (REST, GraphQL, gRPC, WebSocket)
- - System interfaces (File system, Database, Message queue)
- - Internal services (Microservice calls, RPC, Event bus)
- 2. Build complete data flow diagram:
- - Annotate all data entry and exit points
- - Identify sensitive data flow paths
- - Mark trust boundary crossing points
- 3. Risk analysis for each interface:
- - Input validation risks
- - Authentication/authorization risks
- - Data leakage risks
- - Injection attack risks
- Output format: Complete interface inventory sorted by risk level, with CWE mapping and CVSS scores
- ```
- ### Scenario 2: Attack Tree, POC Generation & Pentest Plan
- Deep attack chain analysis with exploit POC generation and penetration testing plan.
- ```
- /threat-modeling @/path/to/project --debug
- Based on discovered security issues, perform deep attack analysis:
- 1. Attack tree construction:
- - Build attack tree for each high-risk threat
- - Analyze attack prerequisites and dependencies
- - Calculate attack success probability and impact scope
- 2. Attack chain analysis:
- - Identify multi-step attack paths (Initial Access → Execution → Persistence → Exfiltration)
- - Map to MITRE ATT&CK tactics and techniques
- - Mark critical pivot points in attack chain
- 3. Exploit POC generation:
- - Generate POC code for each exploitable vulnerability
- - Include payload construction, trigger conditions, expected results
- - Provide safe testing methods (avoid destructive operations)
- 4. Penetration testing plan:
- | Issue ID | Vulnerability | Test Case | Test Steps | POC | Recommended Tools |
- |----------|---------------|-----------|------------|-----|-------------------|
- Output: Complete penetration testing plan document, ready for security testing execution
- ```
- ### Scenario 3: Docker Test Environment & Automated Verification
- Set up isolated test environment and execute penetration testing plan.
- ```
- /threat-modeling @/path/to/project
- Set up test environment and execute penetration test verification:
- 1. Environment analysis:
- - Parse project's docker-compose.yml / Dockerfile
- - Identify required service dependencies (database, cache, message queue)
- - Analyze default configuration and environment variables
- 2. Docker test environment construction:
- - Generate isolated test environment docker-compose.test.yml
- - Configure network isolation and port mapping
- - Prepare test data and initialization scripts
- - Integrate security testing tool containers (OWASP ZAP, Nuclei, SQLMap)
- 3. Automated test execution:
- - Execute generated penetration testing plan
- - Collect test results and evidence screenshots
- - Verify vulnerability exploitability
- 4. Test report:
- - Vulnerability confirmation status (Confirmed / Not Exploitable / False Positive)
- - Actual risk assessment adjustment
- - Reproduction steps and evidence chain
- Output: Test environment config files + Automated test scripts + Test results report
- ```
- ### Scenario 4: Attack Chain Visualization & POC Optimization
- Comprehensive attack chain analysis with visualization and optimized exploitation.
- ```
- /threat-modeling @/path/to/project --debug
- Complete attack chain analysis and visualization:
- 1. Attack graph construction:
- - Build complete system attack graph
- - Nodes: Assets, vulnerabilities, attack techniques
- - Edges: Attack paths, prerequisites, success probability
- 2. Critical path analysis:
- - Identify shortest attack path (from entry to core assets)
- - Identify highest success rate path
- - Identify attack chain with maximum impact scope
- 3. POC optimization combination:
- - Tool chain optimization (Recon → Exploit → Post-Exploit)
- - Automated attack script generation
- - One-click vulnerability verification workflow
- 4. Visualization output:
- - Mermaid format attack tree diagram
- - Attack path heatmap
- - Risk-impact matrix diagram
- - ATT&CK Navigator mapping
- Output format:
- - Attack graph Markdown (with Mermaid diagrams)
- - Optimized POC toolkit
- - Risk visualization dashboard data
- ```
- ### Quick Reference: Extended Prompts
- | Scenario | Focus | Key Output |
- |----------|-------|------------|
- | **Interface Discovery** | All interfaces + Data flows | Risk-ranked interface inventory |
- | **Attack Tree & POC** | Attack chains + Exploits | Pentest plan with POC code |
- | **Docker Test Env** | Isolated testing | Test environment + Auto scripts |
- | **Attack Visualization** | Visual analysis | Attack graphs + Heatmaps |
- ## Output Structure
- ```
- {PROJECT_ROOT}/
- ├── Risk_Assessment_Report/ # Final reports (P8)
- │ ├── {PROJECT}-RISK-ASSESSMENT-REPORT.md
- │ ├── {PROJECT}-RISK-INVENTORY.md
- │ ├── {PROJECT}-PENETRATION-TEST-PLAN.md
- │ └── ...
- └── .phase_working/{SESSION_ID}/ # Working data
- ├── data/ # YAML phase data
- │ ├── P1_project_context.yaml
- │ ├── P2_dfd_elements.yaml
- │ └── ...
- └── reports/ # Markdown reports
- ├── P1-PROJECT-UNDERSTANDING.md
- └── ...
- ```
- ## Script Commands
- ### Knowledge Base Queries
- ```bash
- # STRIDE threat patterns
- python scripts/unified_kb_query.py --stride spoofing
- # Security controls
- python scripts/unified_kb_query.py --control AUTHN
- # CWE information with full chain
- python scripts/unified_kb_query.py --cwe CWE-89 --full-chain
- # CAPEC attack patterns
- python scripts/unified_kb_query.py --capec CAPEC-66 --attack-chain
- # AI/LLM specific threats
- python scripts/unified_kb_query.py --all-llm
- ```
- ### Module Discovery
- ```bash
- python scripts/module_discovery.py /path/to/project --p1-discovery
- ```
- ### Phase Data Management
- ```bash
- # Query previous phase data
- python scripts/phase_data.py --query --phase 1 --root /path/to/project
- # Validate phase output
- python scripts/phase_data.py --validate --phase 2 --root /path/to/project
- # Initialize new session
- python scripts/phase_data.py --init --project "PROJECT-NAME" --path /path/to/project
- ```
- ## 8-Phase Workflow
- ```
- P1 → P2 → P3 → P4 → P5 → P6 → P7 → P8
- │ │ │ │ │ │ │ └── Report Generation
- │ │ │ │ │ │ └── Mitigation Planning
- │ │ │ │ │ └── Risk Validation (POC, attack paths)
- │ │ │ │ └── STRIDE Threat Analysis (threat matrix)
- │ │ │ └── Security Design Review (16 domains)
- │ │ └── Trust Boundary Evaluation
- │ └── Call Flow & DFD Analysis (data flows, call flows)
- └── Project Understanding (modules, entry points)
- ```
- ## Knowledge Base
- | Category | Coverage |
- |----------|----------|
- | Security Controls | 16 domains, 107 controls |
- | Threat Patterns | CWE/CAPEC/ATT&CK (1,900+ patterns) |
- | AI/LLM Threats | 350+ threats |
- | Compliance | OWASP ASVS, WSTG, MASTG |
- | SQLite Index | ~8 MB searchable |
- ## Project Types Supported
- | Type | Example Technologies | Special Focus |
- |------|---------------------|---------------|
- | Web API | Django, FastAPI, Express | Authentication, API Security |
- | Microservices | K8s, Istio, Kafka | Service Mesh, Zero Trust |
- | AI/LLM Application | Claude API, RAG, Vector DB | Prompt Injection, Model Security |
- | Mobile Backend | JWT, OAuth, Firebase | Token Security, Data Privacy |
- | Legacy System | Monolith, SOAP | Technical Debt, Migration Risks |
- ## License
- BSD-3-Clause
- ## Repository
- https://github.com/fr33d3m0n/threat-modeling
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.