Why keep a threat model as code in pytm or threagile instead of a drawn diagram?

## What threat model as code means A threat model as code is a system model written as a source file that a program reads. The elements, the flows between them, the trust boundaries and the data those flows carry are **declared** by a human, and a tool **derives** the diagram and the threat list from that declaration. Two open-source projects define the category. **pytm** (an OWASP project) is a Python framework. You write a script that instantiates objects — a `TM` for the model itself, `Actor`, `Server`, `Process` and `Datastore` for elements, `Boundary` for trust boundaries, `Dataflow` for each link, `Data` for the payloads — and set attributes on them (what protocol a flow uses, whether it is authenticated, whether a store is encrypted at rest). Running the script emits the output. **threagile** is a Go tool driven by a single YAML file. The file declares `technical_assets`, the `communication_links` between them, `data_assets` with their confidentiality and integrity ratings, `trust_boundaries` and `shared_runtimes`. You run the tool over that file and it emits its output. ## Declared versus generated This distinction is the whole subject, and it is where candidates most often go wrong. **Nothing is discovered.** Neither tool inspects your source code, your infrastructure or your running system. Every element, every link and every security attribute is something a person typed. What the tool generates from it: - **A data-flow diagram**, laid out from the declared elements, links and boundaries. - **A threat or risk list**, produced by matching a shipped rule set against the declared attributes. pytm ships a threat library whose entries carry conditions over element attributes; threagile ships a set of risk rules. A rule fires when the model shows the shape it looks for — a link crossing a trust boundary without authentication, a datastore holding high-confidentiality data without encryption at rest, an asset reachable from the internet. - **A report** in a readable format, plus machine-readable output. The decisive property is that the output is a **pure function of the model file**. Run it twice on the same file and you get the same diagram and the same risk list, in the same order. That determinism is what makes the rest work. ## What that buys you over a drawing **1. The diff is the signal.** A drawn diagram changes as an opaque image; a model file changes line by line. On a mortgage-application service, a pull request that adds one `communication_link` from the underwriting service to an external credit bureau is a small, visible block in the diff. A reviewer can immediately ask the questions that matter: which data assets ride that link, does it carry applicant personal and financial data, what protocol and authentication are declared, does it leave the trust boundary the rest of the service sits inside. A new third-party egress of personal financial data has become a reviewable event rather than something discovered a year later. **2. The artifact cannot lag the model.** An e-scooter fleet's telemetry ingest changes constantly — new brokers, new regional endpoints, new consumers of the location stream. If the model regenerates on every merge, the diagram and the report that describe the fleet's availability risks are always the ones the current model produces. Nobody has to remember to re-export a picture. Note the careful wording: regeneration keeps the output true to the **model**, not to reality — that gap is a separate problem. **3. It lives where the change lives.** Same repository, same review, same history, same ownership rules. You can check out the commit that shipped an incident and see the model as it stood. **4. It runs unattended.** The model can be evaluated on every commit, so a report exists continuously rather than for the one quarter someone held a workshop. (The mechanics of the pipeline that runs it, and any decision to fail a build on the result, belong to the delivery and policy layers, not to the model.) **5. Consistency.** Ten teams using one rule set and one vocabulary produce comparable output; ten teams with whiteboards do not. ## What it costs - **Truth is manual.** The file records assertions. If an engineer writes that a link is encrypted, the report believes it. - **The rule sets are generic.** They find the shapes they encode, from declarations; the judgment about business impact and about assumptions that were never true is human work. - **Text is not a whiteboard.** Engineers who reason visually contribute less to a file than to a drawing, and the model can quietly become one person's property. - **Someone must maintain the dialect.** Reviewers have to be able to read the model, or the diff stops being reviewed and becomes noise scrolled past. ## The shape of a model file Roughly, in either tool: trust boundaries: internet | fleet-backend | third-party technical assets: scooter-telemetry-gateway, ingest-service, telemetry-store, underwriting-service communication links: gateway -> ingest-service (protocol, auth, data carried) ingest-service -> telemetry-store data assets: location-stream (confidentiality, integrity, availability ratings) Everything the report says is derived from those four kinds of statement. A threat model as code is best understood as a durable, machine-readable record of a design conversation — not a replacement for having one.