threat-modeler

name

threat-modeler

description

Build a threat model for a feature or system BEFORE it is implemented — assets, actors, trust boundaries, data flows, STRIDE-style threat enumeration per boundary, abuse cases written from attacker behavior, risks ranked with concrete exploit paths, mitigations mapped to each threat, and a validation test plan with negative tests per mitigation. Use when designing a security-sensitive feature (auth, uploads, payments, integrations, admin/support tooling), when asked to "threat model" something, before exposing a new external surface, or after an incident to enumerate sibling attack paths. Consumes tenant-modeler and authorization-matrix-designer outputs as inputs when present rather than re-deriving them. Do NOT use to review an implemented diff (security-pr-reviewer), audit existing tenant isolation (tenant-isolation-reviewer), or triage scanner output (static-analysis-reviewer).

Threat Modeler

Purpose

Produce a threat model a team can build and test against: what we are building, what can go wrong, what we will do about it, and how we will prove the defenses work. The deliverables are an asset/actor/trust-boundary map, per-boundary threat enumeration, abuse cases written as attacker behavior, risks ranked by concrete exploit path (not gut feeling), mitigations mapped one-to-one to threats, and a validation test plan where every mitigation gets a negative test. A threat without an exploit path is a hypothesis and is labeled as one; a mitigation without a test is a wish.

Use When

• Use when: designing a security-sensitive feature — authentication, file upload, payment flow, third-party integration, webhook receiver, admin or support tooling, data export.
• Use when: asked to "threat model" a system, feature, or design doc.
• Use when: a new externally reachable surface is about to ship and nobody has enumerated how it can be abused.
• Use when: after an incident, to enumerate sibling attack paths the incident class implies (the found hole is rarely the only one).
• Do NOT use when: reviewing an implemented diff for security — that is security-pr-reviewer; this skill works on designs and systems, not hunks.
• Do NOT use when: auditing an existing system for cross-tenant leakage — that is tenant-isolation-reviewer.
• Do NOT use when: triaging SAST/scanner findings — static-analysis-reviewer.
• Do NOT use when: the threats are AI/LLM-specific (prompt injection, RAG authorization, excessive agency) — that is the Phase 7 pack; note the gap rather than improvising coverage here.

Inputs to Inspect

1. The design artifact under threat: design doc, ADR, issue, or the existing code and schema of the surface being extended. No artifact → Stop Conditions.
2. Prior security context: tenant model (tenant-modeler output), the authorization matrix (authorization-matrix-designer output), audit taxonomy — consume these as inputs; do not re-derive tenant semantics or role definitions inside the threat model.
3. Entry points and data flows: routes, webhooks, jobs, imports, file handling, third-party callbacks — where untrusted data enters and where trust levels change.
4. The assets at stake: which data or capability an attacker would want (credentials, tenant business data, money movement, admin capability).
5. Existing mitigations already in the codebase (middleware, validators, policies) so the model records real posture, not assumed posture.
6. Prior incidents and pen-test findings for this system, if any.

Workflow

1. Scope the model. One feature/surface per pass. State what is in and out of scope; an unbounded threat model converges on generic advice.
2. Map the system: assets (what's worth stealing/breaking), actors (legitimate roles from the authorization matrix, plus attacker personas: anonymous, authenticated wrong-tenant, malicious insider, compromised dependency), entry points, and data flows.
3. Draw trust boundaries — every place data crosses a privilege or trust level (client→server, server→DB, tenant→tenant, app→third party, CI→production). Number them; threats attach to boundaries.
4. Enumerate threats per boundary using the STRIDE prompts in references/threat-catalog.md. For SaaS paths, tenant isolation and object-level authorization threats are mandatory rows at every data-access boundary, never optional.
5. Write abuse cases for the credible threats: attacker persona, concrete steps, and payoff ("wrong-tenant authenticated user calls export with a guessed id and receives tenant B's ledger"). An abuse case must be specific enough to become a test later.
6. Rank risks. High severity REQUIRES a stated exploit path — who, from where, doing what, getting what. No exploit path → cap at medium and label what would confirm it. Rank by exploitability × asset impact, including tenant blast radius (one tenant vs all tenants).
7. Map mitigations one-to-one to ranked threats: the control, where it lives (which boundary), and who builds it. Unmitigated threats are explicitly accepted (needs the human's written rationale — route via human-approval-boundary) or explicitly deferred with an owner.
8. Write the validation test plan: for every mitigation, at least one negative test executing the abuse case and observing denial/failure. Hand implementable tenant/authz tests to multi-tenant-security-tester; control implementation goes to appsec-implementer.
9. Deliver the model in the output format; keep it versionable next to the design doc so it can be re-run when the design changes.

Output Format

THREAT MODEL — <feature/system> (scope: <in / out>)
Assets: <asset — why an attacker wants it>
Actors: <legitimate roles (from authz matrix) + attacker personas>
Trust boundaries: B1..Bn <boundary — trust change at it>
Data flows: <entry point → boundary → store/exit>
Threats (per boundary, STRIDE-tagged):
  T<n> [B<x>] <threat> — <abuse case: persona, steps, payoff>
Risk ranking:
  [HIGH]   T<n> — exploit path: <who, from where, doing what, getting what>
  [MEDIUM] T<n> — <path or "hypothesis — confirmed by: <what>">
  [LOW]    ...
Mitigations: T<n> → <control> at <boundary> — owner: <who>
Accepted/deferred threats: <threat — written rationale or owner + date>
Validation test plan: T<n> → <negative test: attempt + expected failure>
Handoffs: <appsec-implementer: controls | multi-tenant-security-tester: tests>
Not modeled: <explicitly out-of-scope areas + why>

Validation Checklist

• Scope stated; every threat attaches to a numbered trust boundary.
• Attacker personas include anonymous, wrong-tenant authenticated, and privileged insider — not just "hacker".
• Every SaaS data-access boundary has tenant-isolation and object-level authorization threat rows.
• Every HIGH risk has a concrete exploit path; path-less highs were downgraded and labeled hypotheses.
• Every credible threat maps to a mitigation, a written acceptance, or a deferral with an owner — none silently dropped.
• Every mitigation has a negative test in the validation plan.
• Existing mitigations were verified in code, not assumed present.
• Nothing was implemented — this skill models; building is a handoff.

Security Rules

• High-severity claims without an exploit path are forbidden — rank them medium as hypotheses and name what would confirm them.
• Threats are never deleted from the model without written rationale; "unlikely" is a ranking, not a removal.
• Tenant isolation and object-level authorization are mandatory analysis rows on every SaaS data path (master-prompt §6), even when the requester did not ask about tenancy.
• Absence of a mitigation in scope is recorded as accepted risk requiring human sign-off, never silently normalized.

Gotchas

• Threat models that skip actor definition produce generic STRIDE noise — the wrong-tenant authenticated user is the persona most SaaS models miss, and the most common real attacker.
• Trust boundaries inside the backend (job runner with service credentials, support console, internal admin API) get skipped because "it's internal"; privilege boundaries count even with no network hop.
• Modeling the happy-path dataflow only: file uploads, error paths, retries, and webhook redelivery all carry attacker-controlled data too.
• A mitigation that exists in middleware can be bypassed by a second route to the same data (GraphQL next to REST, RPC next to ORM) — enumerate routes to the asset, not routes you were told about.
• Re-deriving tenant semantics or role definitions here drifts from the canonical tenant-modeler / authorization-matrix-designer outputs — consume them and cite them instead.

Stop Conditions

• No design artifact, code, or schema exists to model — stop; ask for the design input rather than modeling from imagination.
• The tenant model or authorization semantics are undefined and the feature is tenant-facing → stop; run tenant-modeler / authorization-matrix-designer first, then model against their output.
• Modeling reveals an apparently exploitable hole in the LIVE system (not the design) → report it immediately as a finding with its exploit path; containment is the human's call via human-approval-boundary.
• The requester asks to skip or delete threats to make the model look clean → refuse; record the threat and route acceptance through written rationale.

Supporting Files

• references/threat-catalog.md — STRIDE prompts per boundary type, SaaS-specific threat rows, and abuse-case patterns with payoff templates.
• evals/evals.json — trigger + behavior cases.
• evals/trigger-evals.json — discrimination against appsec-implementer and secrets-identity-hardener (threat & hardening cluster) and against security-pr-reviewer / tenant-isolation-reviewer.