threat-model

threat-model

A threat model answers "what could go wrong with this system, who would do it, and what should we do about it?" independently of whether any specific bug has been found yet. It is the map; vulnerability discovery is the metal detector. A good threat model tells the pipeline where to look and tells triage which findings matter.

Litmus test: If patching one line of code makes an entry disappear, it was a vulnerability, not a threat. A threat ("attacker achieves RCE via untrusted media parsing") still stands after every known bug is fixed; a vulnerability ("dr_wav.h:412 doesn't bounds-check chunk_size") does not. This skill produces threats. Vulnerabilities appear only as evidence that raises a threat's likelihood score.

Invocation: /threat-model [bootstrap-then-interview|bootstrap|interview] <target-dir> [flags]

---

Step 0 — Safety preamble (always runs first)

This skill performs static analysis only. It reads source, git history, and any vulnerability reports the user supplies, and writes a single output file (<target-dir>/THREAT_MODEL.md). It does not build, execute, fuzz, or modify the target, and does not make network requests against the target's infrastructure.

Before proceeding, confirm and state in your first response:

1. The target directory exists and is a local checkout you can read.
2. You will not execute any code from the target directory.
3. If --vulns points at a URL or you are asked to "fetch CVEs", you will query only public advisory databases (NVD, GitHub Security Advisories, the project's own issue tracker) and never the target's live deployment.

If the user asks you to validate a threat by running an exploit, decline and point them at the vuln-pipeline (README Step 2) instead.

---

Step 1 — Route to a mode

Parse $ARGUMENTS:

First token	Route to
interview	Read interview.md in this directory and follow it.
bootstrap	Read bootstrap.md in this directory and follow it.
bootstrap-then-interview	Bootstrap first, then interview seeded from the draft. See below.
anything else, or empty	Ask the user: "Is someone who owns or built this system available to answer questions in this session?" Yes and the codebase is checked out → recommend bootstrap-then-interview. Yes but no codebase → interview.md. No → bootstrap.md.

All modes write the same artifact (THREAT_MODEL.md, schema in schema.md) so downstream consumers (pipeline recon/judge, verifier agents) do not need to know which mode produced it.

	interview	bootstrap
Needs	An application owner present in the session	A local checkout; optionally past vulns
Method	Four-question framework: conversational walk through what are we working on → what can go wrong → what are we going to do about it → did we do a good job	Five stages: parallel research swarm → synthesize sections 1-3 + vuln table → generalize vulns into threat classes → STRIDE gap-fill → emit
Best for	New systems, design reviews, systems where the risk lives in business logic the code doesn't show	Inherited systems, third-party code, OSS dependencies, anything with a CVE history
Provenance tag	interview	bootstrap

Context durability. Interview mode is multi-turn; tool results from early reads may be evicted before you need them. To stay resilient:

• Do not read interview.md or bootstrap.md in full up front. Read the mode file (or the relevant section of it) at the point you need it, one question or stage at a time.
• If a re-read via the Read tool is refused as "file unchanged", the prior result was evicted; reload with cat <path> via Bash instead.

Interview backbone (so you can proceed even if interview.md is unavailable mid-session):

Q	Question	Fills schema sections
Q1	What are we working on?	section 1 context, section 2 assets, section 3 entry points
Q2	What can go wrong?	section 4 threat rows (id, threat, actor, surface, asset)
Q3	What are we going to do about it?	section 4 impact/likelihood/status/controls; section 5 deprioritized; section 8 recommended mitigations
Q4	Did we do a good job?	validate ranking, coverage check, section 6 open questions

bootstrap-then-interview mode

When the owner is available and the codebase is checked out, this is the recommended path: the owner's time goes to refining a code-grounded draft instead of describing the system from scratch.

1. Tell the owner: "I'll read the code first and come back with a draft (about 5-10 min), then we'll walk it together. Want that, or would you rather start cold?" Only proceed if they opt in; otherwise fall back to interview.md.
2. Read bootstrap.md and follow it end-to-end. Write <target-dir>/THREAT_MODEL.md.
3. Immediately continue into interview mode: read interview.md and follow it with --seed <target-dir>/THREAT_MODEL.md in effect. The section 6 open questions from bootstrap become your Q1-Q4 prompts; the owner confirms, corrects, and adds rather than starting from nothing.
4. Overwrite <target-dir>/THREAT_MODEL.md with the refined model. Set provenance mode: bootstrap-then-interview.

The same flow is available manually: run bootstrap first, then interview --seed <THREAT_MODEL.md> in a later session.

---

Step 2 — Shared output contract

All modes MUST emit <target-dir>/THREAT_MODEL.md conforming to schema.md in this directory. Read schema.md immediately before you write the file, not at routing time; in interview mode the gap between routing and emit can be many turns, and an early read will be evicted before it's used.

After writing the file, print to the user:

1. The path to THREAT_MODEL.md.
2. The top 5 threats by likelihood × impact (id, one-line description, L×I).
3. For bootstrap: any open questions the code could not answer (these seed a later interview pass).
4. For interview: any owner statements that could not be verified in code (these seed follow-up code review).

---

References

• docs/security.md and docs/prompting.md for the engagement-context and authorization framing this skill inherits.

---

threat-model

A Claude Code skill that builds a threat model for a target codebase. Three modes: bootstrap derives the threat model from the target itself (source tree, git history, public advisories, an optional past-vulns file); interview discovers the threat model by walking an application owner through the four-question framework; bootstrap-then-interview chains the two. All modes write THREAT_MODEL.md in a shared schema.

Why a threat model

Vulnerability scanners find instances; a threat model is the map of where instances are likely to be and which ones matter. Hand the pipeline a threat model and it knows where to look. Hand triage a threat model and it knows which findings to escalate. Use the output's focus areas to seed the vuln-pipeline recon partition and to inform how you prioritize /triage results.

Model selection

The skill has no model: frontmatter pin; it runs on whatever model your session uses (or --model if you pass one). It is designed for reasoning-capable Claude models — use the same model you run the rest of the pipeline with. If you want the skill itself to request a model, add a model: line to SKILL.md frontmatter. It overrides the session model (however set, /model or --model) only for the turn the skill is invoked in — fine for bootstrap, but the multi-turn interview reverts to the session model on your next reply, so to hold a model across an interview, set it at the session level instead.

Installation

Project-scoped (already done if you cloned this repo):

ls .claude/skills/threat-model/

User-scoped:

cp -r .claude/skills/threat-model ~/.claude/skills/

Usage

Bootstrap (derive from target, git history, advisories)

Use when no application owner is available. Point it at a checkout and, optionally, a list of past vulnerabilities:

/threat-model bootstrap targets/drlibs
/threat-model bootstrap targets/drlibs --vulns targets/drlibs/vulns.txt

Without --vulns the skill mines git log, CHANGELOG, and GitHub Security Advisories itself; with it, it ingests your supplied list first.

The skill spawns a parallel research swarm (docs reader, surface mapper, asset finder, git-history miner, advisory fetcher, vuln-file parser), synthesizes their returns into the system-context / assets / entry-points sections, generalizes the collected vulns into threat classes, gap-fills with STRIDE for surfaces the vuln history didn't cover, and writes targets/drlibs/THREAT_MODEL.md. On small targets (<50 source files) it runs the same briefs sequentially instead of spawning.

Interview (discover via owner conversation)

Use when an application owner is in the session.

/threat-model interview targets/alsa
/threat-model interview targets/alsa --design-doc targets/alsa/README.md

Without --design-doc the interview opens cold by asking the owner to describe the system; with it, the skill reads the doc first and summarizes it back for confirmation.

The skill will walk the owner through the four questions ("what are we working on?", "what can go wrong?", "what are we going to do about it?", "did we do a good job?"), grounding answers in the code as it goes, and write targets/alsa/THREAT_MODEL.md.

Bootstrap then Interview (bootstrap a draft, then refine via interview)

Use when an owner is available but their time is limited: bootstrap produces the draft unattended, then the interview spends owner time only on what the code couldn't answer.

/threat-model bootstrap-then-interview targets/drlibs/

The interview will focus on the bootstrap's open questions instead of starting cold. If the bootstrap already ran in an earlier session, seed the interview with its output instead of re-running it:

/threat-model interview targets/drlibs/ --seed targets/drlibs/THREAT_MODEL.md

Checkpointing and resume (bootstrap mode)

Bootstrap writes per-stage checkpoints to ./.threat-model-state/ in the current working directory (cwd-confined by checkpoint.py). If a run is interrupted, re-invoking /threat-model bootstrap <target-dir> from the same working directory resumes from the last completed stage — the research swarm is not re-spawned if Stage 1 already landed. Pass --fresh to start over. The state directory is scratch; add it to .gitignore.

Output

<target-dir>/THREAT_MODEL.md with seven sections: system context, assets, entry points & trust boundaries, threats (the table), deprioritized, open questions, provenance. See schema.md for the full contract; a worked example lives at targets/drlibs/THREAT_MODEL.md.

Notes

• The skill is read-only — it does not build, run, or probe the target — and is safe to point at any local checkout.
• The output is a starting point for human review, not a substitute for it.

References

• Shostack, The Four Question Framework for Threat Modeling (2024) — https://shostack.org/files/papers/The_Four_Question_Framework.pdf
• OWASP Threat Modeling Cheat Sheet — https://cheatsheetseries.owasp.org/cheatsheets/Threat_Modeling_Cheat_Sheet.html
• This repo's docs/security.md and docs/prompting.md.