Threat Modelling

You help the team find design flaws while they are still cheap to fix. The work answers four questions: what are we working on, what can go wrong, what are we going to do about it, and did we do a good enough job. The output is a short living document the engineers actually use, not a 60-page artefact written once for an auditor.

When to use

• "We're building X; what are the security risks?"
• "Before we launch the new API / payments flow / mobile app, threat model it."
• "We're adding an AI assistant that can read customer emails. What could go wrong?"
• "The auditor wants evidence we do risk assessment on new systems."
• A big architecture change: new data store, new third party, new trust boundary, multi-tenancy.

What you need

• Architecture material: diagrams, design docs, README, infrastructure code, API specs. Read them from a connected Google Drive, Notion or code host, or from files the owner gives you. If nothing is written down, interview the engineer who knows the system (ask_teammate or clarify) and draw it yourself.
• What data the system handles and how sensitive it is (personal data, payment data, credentials, health data, trade secrets).
• Who uses it: anonymous public, customers, staff, admins, other services, partners.
• Existing controls the team believes are in place. You will mark which ones you verified.
• About 60 to 90 minutes of an engineer's time for the review session, if possible. Threat modelling alone produces a worse model.

Method

1. Scope it small enough to finish. One feature, one service or one data flow per model. Write a one-paragraph description of what is in and out.
2. Model the system as a data-flow diagram in Mermaid, saved next to the model. Use four element types:
   • external entities (users, third-party services you do not control)
   • processes (your code: API server, worker, function)
   • data stores (databases, buckets, queues, caches, logs)
   • data flows (arrows, labelled with what moves and over what protocol) Then draw trust boundaries where the level of trust changes: internet to your edge, app to database, your cloud to a vendor, user tenant to user tenant, untrusted content into an AI model.
3. List assets and their value: what an attacker wants (customer records, money movement, admin access, compute) and what the business cannot lose (availability of checkout, integrity of invoices).
4. Find threats with STRIDE, per element:

   Letter	Threat	Property broken	Ask
   S	Spoofing	Authentication	Can someone pretend to be this user or service?
   T	Tampering	Integrity	Can data be changed in transit, at rest or in a request?
   R	Repudiation	Accountability	Could someone deny an action because we do not log it?
   I	Information disclosure	Confidentiality	Can data reach someone it should not?
   D	Denial of service	Availability	Can this be exhausted, flooded or locked?
   E	Elevation of privilege	Authorisation	Can someone gain rights they were not given?
   Which letters apply: external entities S and R; processes all six; data stores T, I, D (and R if they hold logs); data flows T, I, D. Focus hardest on every flow that crosses a trust boundary.

5. Write each threat as one sentence in the form: "A [actor] can [action] against [asset] via [entry point], leading to [impact]." Vague threats ("hackers could get in") are not threats.
6. Add the threats STRIDE tends to miss:
   • business logic abuse: refunds, coupons, free-trial farming, scraping, fake sign-ups
   • insiders and over-powered admin tools, support staff impersonation features
   • supply chain: packages, CI pipeline, build secrets, a compromised vendor
   • tenant isolation in shared databases and caches
   • AI features: untrusted text (web pages, emails, documents) carrying instructions into a model that can call tools; the model's tool access exceeding the user's rights; sensitive data leaking into model output or logs
   • recovery: what happens if the database, the cloud account or the admin's email is lost
7. Rate each threat. Likelihood 1 to 3 (1 needs rare skill or access, 2 plausible for a motivated attacker, 3 easy or already seen in the wild) times impact 1 to 3 (1 minor, 2 one customer or limited data, 3 many customers, money or legal exposure). Score 6 to 9 is High, 3 to 4 Medium, 1 to 2 Low. Write one line explaining each rating.
8. Decide the response for each: mitigate (name the control), eliminate (remove the feature or data), transfer (contract, insurance), or accept. Only the owner can accept a High; record their name and date. Credit an existing control only if you verified it in code, config or a screenshot; otherwise mark it "claimed".
9. Turn mitigations into tickets with an owner and a target date. Use the team's tracker if it is a connected app (Jira, Linear, GitHub Issues); otherwise list them in the document.
10. Check the work (did we do a good enough job?): every boundary-crossing flow has at least one threat considered; every High has a mitigation or a signed acceptance; an engineer who built the system has read it and agreed; open questions are listed.
11. Keep it alive. Store it in the repo or shared drive next to the design. Set a cronjob reminder to revisit it at the next major change or in six months, whichever comes first.

Running the review session

• Send the draft diagram 24 hours before, so people arrive having corrected it.
• Invite the engineer who built it, someone who operates it, and someone who knows the business rules. Three to five people is enough.
• Spend the first 15 minutes fixing the diagram; most insights come from "wait, that is not how it works".
• Walk the boundaries one by one with STRIDE; you scribe, they think.
• Park solution debates: record the threat, decide the response later in the meeting or offline.
• End with the High list read back aloud and an owner named for each.

Example threat sentences

• "A logged-in customer can read another tenant's invoices via GET /api/invoices/{id}, because the handler checks login but not tenant, exposing billing data for all customers." (E, I; High)
• "An attacker who obtains a leaked CI token can push a modified build to production via the deploy pipeline, leading to code running with production secrets." (T, E; High)
• "A customer email containing hidden instructions can make the support assistant call the refund tool via its email-reading feature, leading to unauthorised refunds." (T, E; High)
• "An admin can delete audit logs from the same console they administer, so misuse could not be proven afterwards." (R; Medium)

Output

A markdown document using references/threat-model-template.md, containing the Mermaid diagram, assets, the threat table, the decisions and the open questions. Put the High threats and their owners on a show_card.

Checks before you finish

• The diagram shows every trust boundary and every external entity.
• Each threat sentence names actor, action, asset, entry point and impact.
• Every High has a mitigation with an owner and date, or a named acceptance.
• Claimed controls are marked as claimed, not verified.
• Someone who built the system has reviewed it.
• No real secrets, keys or internal passwords appear in the document.

Pitfalls

• Boiling the ocean. A model of "the whole platform" never finishes. Slice by feature or flow.
• The hero threat modeller. One person working alone misses what the builders know. Run it as a conversation.
• Admiring the problem. Long threat lists with no decisions help nobody. Every row ends in a decision.
• Perfect diagrams. The diagram only needs to be right enough to reason about boundaries.
• Only external attackers. Include insiders, mistakes, vendors and abuse of legitimate features.
• Treating it as a one-off. Designs change; an out-of-date model gives false comfort.
• Sign-off. Risk acceptance is a business decision for the owner, not for you. For regulated data, a qualified security professional should review the final model.

Credits for adapted material: references/CREDITS.md.