Security Threat Model

intent

Build an actionable AppSec-grade threat model anchored to a specific repository or project path. enumerates trust boundaries, assets, entry points, attacker capabilities, realistic abuse paths, and concrete mitigations. triggers only when the user explicitly asks to threat model a codebase, enumerate threats or abuse paths, or perform appsec threat modeling. does not trigger for general architecture summaries, code review, or non-security design work.

inputs

• repo root path or in-scope subdirectory: absolute or relative path to the repository or subpath to model.
• repository summary or architecture spec (optional): existing docs, README, or architecture diagram. if absent, you will generate one using the prompt template in references/prompt-template.md.
• deployment and usage context (to be confirmed with user):
  • intended runtime (server, CLI, library, worker, batch job).
  • deployment model (cloud, on-prem, hybrid, distributed).
  • internet exposure (public API, internal only, air-gapped).
  • authentication model (OAuth, API key, mTLS, none).
  • multi-tenancy (yes/no).
  • data sensitivity classification (PII, credentials, models, config, audit logs, compute resources).
  • user scale and scale expectations.
• external integrations: list any external services (cloud providers, third-party APIs, identity systems) with security implications.
• existing security controls or architecture notes: any documented auth checks, encryption, rate limiting, sandboxing, or other controls already in place.

procedure

1. Scope and extract the system model

   • Input: repo path, repo summary (or generate one).
   • Identify primary components, data stores, and external integrations from code and docs.
   • Identify runtime behavior (server, CLI, library, worker) and entry points (HTTP endpoints, job queues, CLI args, file upload surfaces, parsers).
   • Separate runtime from CI/build tooling and tests/examples; exclude out-of-scope items explicitly.
   • Output: list of in-scope components, data flows, and identified entry points with code references.

2. Derive trust boundaries, assets, and entry points

   • Input: component map from step 1.
   • Enumerate trust boundaries as concrete edges between components, noting protocol (HTTP, gRPC, file, queue), authentication mechanism, encryption (in-transit, at-rest), input validation, and rate limiting.
   • List assets driving risk: credentials, PII, model/config files, integrity-critical state, availability-critical components, audit logs, build artifacts.
   • Identify all entry points: HTTP/API endpoints, upload surfaces, parsers (JSON, YAML, image, archive), job triggers, admin tooling, logging/monitoring sinks, error handlers.
   • Output: explicit trust boundary diagram or list with control details, asset inventory, entry point catalog.

3. Calibrate attacker capabilities based on exposure and intended usage

   • Input: deployment model, auth model, internet exposure, multi-tenancy flag.
   • Define realistic attacker profiles: unauthenticated external, authenticated user, insider/employee, compromised component or downstream service.
   • Explicitly note what attackers cannot do (e.g., "no physical access", "no zero-day exploits assumed", "no compromise of underlying cloud provider assumed").
   • Output: attacker capability matrix with explicit non-capabilities.

4. Enumerate threats as concrete abuse paths

   • Input: boundaries, assets, entry points, attacker capabilities.
   • For each entry point and boundary, enumerate abuse paths that map to realistic attacker goals: credential or token theft, privilege escalation, cross-tenant access, sensitive data exfiltration, integrity compromise, denial of service.
   • Classify each threat by type (auth bypass, injection, logic flaw, race condition, resource exhaustion, etc.).
   • Tie each threat to impacted assets and affected components.
   • Keep the threat list small and high-quality; discard generic or heavily mitigated risks.
   • Output: threat list with description, affected assets, affected components, and entry point/boundary.

5. Prioritize threats with explicit likelihood and impact reasoning

   • Input: threat list, existing controls, attacker capabilities.
   • For each threat, assign qualitative likelihood (low/medium/high) with 1-2 sentence justification (e.g., "requires valid API key + race condition within 100ms window; possible but narrow").
   • For each threat, assign qualitative impact (low/medium/high) with 1-2 sentence justification (e.g., "exfiltrates PII for 1 user; affects data confidentiality but not integrity").
   • Compute overall priority (critical/high/medium/low) as likelihood x impact, adjusted for existing mitigations (e.g., "high likelihood, high impact, but mitigated by rate limiting on endpoint").
   • Explicitly note which assumptions (e.g., "assumes no insider threat", "assumes OAuth tokens expire within 1 hour") most influence ranking.
   • Output: prioritized threat list with likelihood, impact, priority, and assumption flags.

6. Validate service context and assumptions with the user

   • Input: key assumptions from steps 1-5 (deployment, auth, multi-tenancy, data sensitivity, scale, internet exposure).
   • Summarize 3-5 material assumptions that affect threat ranking or scope. ask 1-3 targeted clarification questions.
   • Example questions: "is this service single-tenant or multi-tenant?", "are users authenticated via OAuth or static API keys?", "is this service internet-facing or internal-only?", "who can deploy code to production?".
   • Pause and wait for user feedback before proceeding to step 7.
   • If user declines or cannot answer, state which assumptions remain and how they influence priority (e.g., "if this is internet-facing, threat X priority bumps from medium to high").
   • Output: user responses, or explicit non-responses with stated assumption impact.

7. Recommend mitigations and focus paths

   • Input: prioritized threats, user context from step 6, existing controls.
   • For each high or critical threat, recommend concrete mitigations tied to specific code locations, components, or boundaries.
   • Distinguish existing mitigations (with evidence from code) from recommended mitigations.
   • Prefer specific implementation hints over generic advice. example: "enforce schema validation at the upload handler in api/handlers/upload.py:parse_payload() using jsonschema.validate() before deserialization" vs "validate inputs".
   • For recommended mitigations, specify control type: authentication/authorization check, input validation, schema enforcement, sandboxing, rate limiting, secrets isolation, audit logging, encryption, timeout/resource limits.
   • Base recommendations on validated user context; if assumptions remain unresolved, mark recommendations as conditional (e.g., "if service is internet-facing, add rate limiting").
   • Output: mitigation list with priority, location, control type, and implementation hint.

8. Run a quality check and finalize report

   • Input: threat model, mitigations, user feedback.
   • Confirm all discovered entry points are covered in at least one threat or are explicitly documented as low-risk.
   • Confirm each trust boundary is represented in the threat list.
   • Confirm runtime vs CI/dev separation is clear (e.g., "CI tooling not in-scope; see separate CI/CD threat model").
   • Confirm user clarifications (or explicit non-responses) are documented and reflected in priority adjustments.
   • Confirm all assumptions and open questions are explicit.
   • Confirm the report format matches references/prompt-template.md.
   • Write the final Markdown threat model to a file named <repo-or-dir-name>-threat-model.md using the basename of the repo root or in-scope directory.
   • Output: final threat model file.

decision points

• If repo summary is missing: generate one using the prompt template in references/prompt-template.md. do not proceed without a clear list of components and data flows.
• If user context is unavailable: document all assumptions (e.g., "assumes single-tenant, internal-only, no insider threat") and state how each affects threat priority. offer to re-rank once the user provides clarity.
• If an entry point or boundary cannot be tied to code or docs: mark it as "inferred" or "assumed" and flag for user confirmation. do not claim components or controls without evidence.
• If a threat is heavily mitigated by existing controls: adjust priority downward, but do not drop below medium if the threat is pre-auth or affects critical assets.
• If multiple attacker profiles are relevant: enumerate threats for each profile separately and note which profile applies to each threat.
• If multi-tenancy is in scope: enumerate cross-tenant access threats explicitly; privilege these to high or critical regardless of likelihood.
• If rate limiting or backpressure is mentioned but not quantified: mark the mitigation as partial and recommend concrete limits (e.g., "X requests per minute per user").

output contract

final deliverable is a single Markdown file named <repo-or-dir-name>-threat-model.md written to the repo root (or specified output directory). the file must contain, in order:

1. header: # Threat Model: <service or repo name>
2. executive summary (2-3 sentences): what the service does, what this model covers, top 1-2 risks.
3. scope and assumptions (bulleted list): in-scope components, deployment model, auth model, internet exposure, multi-tenancy, data sensitivity, any out-of-scope items.
4. system architecture (prose and/or diagram): primary components, data flows, external integrations, entry points. anchor to code.
5. trust boundaries and assets (table or list): boundary (component A to component B), protocol, auth, encryption, validation; assets (credential, PII, model, config, audit log) with sensitivity.
6. threat model (table or list): threat ID, name, attacker profile, description, affected assets, affected components, likelihood, impact, priority, existing controls, recommended mitigations.
7. assumptions and open questions (bulleted list): material assumptions (e.g., "assumes OAuth tokens expire within 1 hour"), unresolved context from user feedback.
8. next steps: link to specific mitigations, mention any follow-up threat models (