Drawing threat models

A .drawio data flow diagram for threat modelling, in the same visual language as the other drawing-* skills. Four element kinds, trust boundaries, and a numbered threat table under the picture.

Build it with dfd_drawio.py (this directory). Check it with check_routing.py. Look at it with preview.py.

Where the files go

Everything this skill produces lives in one folder, never loose in the project root:

docs/diagrams/
  api-threat-model.py             # the script that builds it
  api-threat-model.drawio         # the diagram
  api-threat-model.preview.svg    # what you looked at

Use the folder the user names. Otherwise put it under docs/diagrams/ when the project has a docs/ directory, and diagrams/ at the project root when it does not — the build script, the .drawio, and any preview or PNG together. write() creates the folder if it is missing, so f.write("docs/diagrams/api-threat-model.drawio") is all it takes, and preview.py writes the SVG beside its input.

Never leave a build script, a .drawio or a preview in the project root, and never write outside the project you were pointed at. One folder, named files — a diagram whose script sits next to it can be regenerated; one scattered across a repository root cannot be found again.

The elements

Every element takes an optional icon_name= — the same diagrams library the architecture skill uses. Find one with:

python3 ~/.claude/skills/drawing-threat-models/dfd_drawio.py bigquery

A process is an ellipse, which is narrowest exactly where a label is widest, so it keeps 30px at the sides against a box's 12. With an icon the label reads from the left of what is left; without one it is centred.

The output contract

1. Every flow says what data moves. flow() requires a label. "session cookie" and "card number" crossing the same boundary are not the same risk, and an unlabelled arrow cannot be threat-modelled at all.
2. At least one trust boundary. A DFD with no boundary is a data flow diagram, not a threat model — the boundaries are what turn it into one.
3. Every flow that crosses a boundary is examined. Mark it crosses=; it turns red, which is a prompt, not a verdict. STRIDE is applied per element, and a crossing is where the interesting ones live.
4. check_routing.py reporting 0 FAIL.

The pieces

from dfd_drawio import Model, L, R, T, B

m = Model("Checkout", "STRIDE · v2")
user = m.entity("Shopper", "browser", col=0, row=0)
api  = m.process("Orders API", "Cloud Run", col=1, row=0)
db   = m.store("Cloud SQL", "orders, PII", col=1, row=1)

net = m.boundary("Internet | DMZ", cols=[0, 0], rows=[0, 1])
gcp = m.boundary("Google Cloud project", cols=[1, 2], rows=[0, 1])

f1 = m.flow(user, api, "credentials + cart", exit=R(), entry=L(),
            direct=True, crosses=net)
m.threat(f1, "S", "Credential stuffing against the login endpoint",
         mitigation="Device check + per-identity rate limit")

threat() takes a STRIDE letter, numbers itself, puts a red disc on the flow and writes the row in the table underneath. The letter alone is a quiz, so the table spells it out: Spoofing · credentials + cart — …, with the mitigation in green where there is one. A threat with no mitigation stays black, which is the point of writing it down.

Geometry

The page measures itself, and leaves room under the picture for the table.

Before handing it over

S=~/.claude/skills/drawing-threat-models
python3 "$S/check_routing.py" docs/diagrams/model.drawio        # must report 0 FAIL
python3 "$S/preview.py" docs/diagrams/model.drawio              # writes docs/diagrams/model.preview.svg
rsvg-convert -w 1400 -o docs/diagrams/model.png docs/diagrams/model.preview.svg

Then read it for what a checker cannot see: a store nothing writes to, a process with no inputs, a boundary drawn where no trust actually changes, a flow crossing a boundary with no threat listed against it.

Common mistakes

preview.py writes a plain SVG — open it in any browser if you have no rsvg-convert. The PNG step is for pasting into a document, not for looking at it.