Threat modeling

Threat Modeling Skill

Analyze a project's architecture and produce a security reference document that describes assets, trust boundaries, applicable threat categories, and the security guarantees the project must uphold.

When to Use

• New project kickoff or initial architecture review
• A new feature introduces authentication, data storage, network exposure, or third-party integrations
• Pre-deploy or pre-launch security review
• The user explicitly asks for a threat model or security analysis
• After a significant architectural change (new microservice, new database, new external API)

When NOT to Use

• Cosmetic or UI-only changes with no security surface
• Pure refactors that do not change trust boundaries, data flows, or access control
• One-off bug fixes unrelated to security

Methodology

Use a lightweight STRIDE-inspired approach. Work through these steps in order:

Step 1: Understand the System

Read the codebase, replit.md, and any existing threat_model.md. Identify:

• What the application does and who its users are
• The tech stack (language, framework, database, hosting)
• External services and integrations (payment providers, auth providers, APIs, object storage)

Step 2: Enumerate Assets

Assets are anything worth protecting. Common examples:

• User credentials -- passwords, tokens, session cookies, API keys
• Personal data -- email addresses, names, payment info, uploaded files
• Application secrets -- database connection strings, signing keys, third-party API keys
• Business data -- orders, invoices, analytics, proprietary content

Step 3: Map Trust Boundaries

A trust boundary exists wherever data crosses between different levels of trust. Identify:

• Client / Server boundary -- browser or mobile app to backend API
• Server / Database boundary -- application code to data store
• Server / External Service boundary -- your backend calling third-party APIs
• Public / Authenticated boundary -- routes or resources that require auth vs. those that don't
• User / Admin boundary -- privilege separation between roles
• Internal / Production boundary -- dev/staging environments vs. production

Step 4: Walk Through Threat Categories

For each asset and trust boundary, consider these STRIDE categories:

Spoofing -- Can an attacker impersonate a legitimate user or service?

• Weak or missing authentication on API endpoints
• Predictable session tokens or JWTs with no signature verification
• No origin validation on webhooks or callbacks

Tampering -- Can an attacker modify data they shouldn't?

• Missing input validation on form fields, query params, or request bodies
• Client-side-only enforcement of business rules (price, quantity, permissions)
• Unsigned or unverified data passed between services

Repudiation -- Can a user deny performing an action with no way to prove otherwise?

• Missing audit logs for sensitive operations (payments, account changes, data deletion)
• Logs that don't capture the acting user or timestamp
• No integrity protection on log storage

Information Disclosure -- Can an attacker access data they shouldn't see?

• PII or secrets appearing in logs, error messages, or API responses
• Overly broad database queries returned directly to the client
• Directory listings, stack traces, or debug endpoints exposed in production
• Missing encryption at rest or in transit

Denial of Service -- Can an attacker degrade or disrupt the service?

• No rate limiting on authentication or public API endpoints
• Unbounded file uploads or request body sizes
• Resource-intensive operations triggered by unauthenticated users
• Missing timeouts on external service calls

Elevation of Privilege -- Can an attacker gain access beyond their authorized level?

• Missing authorization checks after authentication (IDOR, broken function-level access control)
• Role checks only on the frontend, not enforced server-side
• SQL injection, command injection, or template injection leading to arbitrary code execution
• Path traversal allowing file system access outside intended directories
• Insecure deserialization allowing object manipulation

Step 5: Describe Required Guarantees

For each relevant threat, describe the security guarantee the project must uphold. Write these as declarative statements:

• "All API endpoints that access user data MUST require a valid session token."
• "User passwords MUST be hashed with bcrypt (cost >= 12) and MUST NOT appear in logs."
• "File uploads MUST be validated for type and size, and MUST be stored outside the web root."
• "All database queries MUST use parameterized statements."

What to Look Out For

These are the most common and dangerous patterns. Flag them whenever you encounter them:

Broken access control -- Missing auth checks on routes, IDOR (guessable IDs granting access to other users' data), privilege escalation through parameter manipulation, admin functionality reachable by regular users.

Injection -- SQL queries built with string concatenation, shell commands constructed from user input, template injection through unsanitized variables, path traversal via user-supplied file names, unsafe deserialization of user-controlled data.

Cryptographic failures -- Hardcoded secrets or API keys in source code, secrets committed to git, weak hashing algorithms (MD5, SHA1 for passwords), plaintext storage or logging of PII, missing HTTPS enforcement.

Security misconfiguration -- Debug mode enabled in production, CORS set to * or overly permissive, default credentials left in place, verbose error messages exposing internals, permissive Content Security Policy.

SSRF and open redirects -- User-controlled URLs fetched server-side without allowlist validation, redirect targets taken from query parameters without validation.

Dependency vulnerabilities -- Outdated packages with known CVEs, no lockfile or pinned versions, dependencies pulled from untrusted registries.

Data exposure -- PII in application logs, overly broad API responses returning fields the client doesn't need, missing rate limiting allowing data scraping, no encryption at rest for sensitive data.

Output: threat_model.md

You MUST write the completed threat model to threat_model.md in the project root. If the file already exists, update it in place rather than overwriting unrelated sections.

threat_model.md is a project-level security reference document, not a tracker. It describes the system, its security-relevant architecture, and the guarantees it must uphold. Another agent will read this file to inform its security decisions -- write it for that audience.

Use the following structure:

# Threat Model

## Project Overview

Brief description of what the application does, its tech stack, and its users.

## Assets

What is worth protecting in this project. Describe each asset category and why it matters.

## Trust Boundaries

Where data crosses between different trust levels. Describe each boundary and what it separates.

## Threat Categories

For each STRIDE category that is relevant to this project, write a short narrative:
- What the threat is in the context of this specific project
- Why it matters here (what could go wrong)
- What guarantees are required to address it

Omit categories that genuinely do not apply. Do not pad with generic boilerplate.

Example: E-commerce App

# Threat Model

## Project Overview

A Node.js/Express e-commerce application with a React frontend, PostgreSQL database,
and Stripe integration for payments. Users can browse products, create accounts,
and purchase items. Deployed on Replit with Replit Auth for user authentication.

## Assets

- **User accounts and sessions** -- email addresses, hashed passwords, session tokens.
  Compromise allows impersonation and access to order history and saved payment methods.
- **Payment data** -- Stripe customer IDs and tokenized payment references. The app never
  stores raw card numbers, but Stripe tokens could be used to initiate charges.
- **Order data** -- order history, shipping addresses, item quantities and prices.
  Contains PII and business-sensitive pricing information.
- **Application secrets** -- Stripe API keys, database connection string, session signing key.
  Compromise of Stripe secret key allows arbitrary charges.

## Trust Boundaries

- **Browser to API** -- all client requests cross this boundary. The API must authenticate
  and authorize every request; the client is untrusted.
- **API to PostgreSQL** -- the API server has direct database access. SQL injection at the
  API layer would give an attacker full database access.
- **API to Stripe** -- the server calls Stripe's API with a secret key. SSRF or key leakage
  would allow unauthorized payment operations.
- **Authenticated to Unauthenticated** -- product browsing is public; cart, checkout, and
  account pages require authentication. The boundary must be enforced server-side.

## Threat Categories

### Spoofing

Users authenticate via Replit Auth. The application must validate the authentication
token on every request to protected endpoints. Session tokens must be unpredictable
and expire within a reasonable window. Webhooks from Stripe must be verified using
Stripe's webhook signature mechanism.

### Tampering

Product prices and order totals must be calculated server-side. The client sends a cart
(product IDs and quantities) but the server must look up current prices from the database.
Accepting client-supplied prices would allow purchasing items for arbitrary amounts.

### Information Disclosure

API responses for order history must be scoped to the authenticated user. The /api/orders
endpoint must filter by user ID server-side. Error responses must not include stack traces
or database error details. Stripe API keys must never appear in client-side code or logs.

### Elevation of Privilege

Admin routes (product management, order fulfillment) must check for an admin role
server-side. All database queries must use parameterized statements to prevent SQL
injection. File upload endpoints (product images) must validate file type and size.

Key Principles

• Be specific to the project. Generic boilerplate like "use HTTPS" is not useful unless the project is actually missing it.
• Write declaratively. Describe what the system is, what its threats are, and what guarantees it requires.
• Omit irrelevant categories. If the project has no file uploads, do not write about file upload threats.
• Keep it concise. This is a reference document, not an essay. A smart agent will reason from it.