Diagrams and Common Elements (Threat Model Thursday)
All diagrams should have common elements, and using them consistently is a mark of skill and maturity
Diagrams have a form, such as DFD, swim lane or C4, which is the case even if they deviate from that form’s conventions. They have style (or lack it). But regardless of the form or style of the diagram, they should have a title block and a key (also called a legend). They can also have a convention of how to represent what’s being worked on, and there’s one other common element you should use and I’m not going to make you read the book, but you do have to read this post.
Title blocks
In my post on Diagrams and Clarity, I mentioned titles and title blocks, and here I want to talk about those title blocks.
Title blocks are a requirement for those physical-world systems that require an engineer’s approval, because exactly what the engineer is approving has to be visible; engineers either stamp, seal or sign these documents. A seal of approval was a thing before it was a metaphor. What goes in a title block? That’s an organizational decision, which should be informed by norms. The Chapter on Models and Diagrams lists:
- Title
- Creator, approver
- Client name (ISO 7200 mandates the document’s owner!)
- Date, revision history
- Sheet number and total number of sheets
- Professional seals or stamps (e.g., architect’s license)
- Confidentiality block (typical in technology)
Key or Legend
A legend can remind the creator to tell a consistent story, and a key unlocks the diagram for the viewer. Which name to use? 🤷 Either one can be used to show all the elements in use, or the unusual ones. If your organization uses DFD3, there’s no reason to list those elements, but listing the AWS icons is nice, as is listing conventions like “TLS 1.3 unless starred.” I found no reason to prefer either. Key is shorter and I’d look askance at anyone who brought that up in a review meeting.
What’s fixed and what’s in flux
The first question of threat modeling is “what are we working on?” Most systems have elements being worked on in this sprint/this iteration, and elements which are both fixed and worth showing on a diagram. For example, if you’re working on a front end, it might be worth including a load balancer and a database. Show what’s being worked on with hatch-marks, dots, bold lines, or other conventions. Again, the convention you’re using should be in the key unless you have a strongly enforced organizational norm, and the diagram won’t be shared with customers.
Map grids
The final commonality you can use in a diagram is an old-fashioned map grid. Back when maps were printed on paper, they had grids to help you find a place (“If you’re on page 29, Market street is at F-6.”) As diagrams increase in complexity, a map grid can help people focus on the right part of the diagram. This is most useful as diagrams get bigger, more detailed, or both.
All this and a whole lot more is part of Chapter 3, Diagrams and Models, in the second edition of Threat Modeling.
Map grid from HandtoMind.