Every threat model diagram should tell a story.

Adam Shostack has another threat modeling post up on the SDL blog entitled "Threat Modeling Self Checks and Rules of Thumb".  In it, he talks about threat models and diagrams (and he corrects a mistake in my "rules of thumb" post (thanks Adam)).

There's one thing he mentions that is really important (and has come up a couple of times as I've been doing threat model reviews of various components).  That a threat model diagram should tell a story.

Not surprisingly, I love stories.  I really love stories :).  I love telling stories, I love listening to people telling stories.

I look for stories in the most unlikely of places, including places that you wouldn't necessarily think of.

So when I'm reviewing a threat model, I want to hear the story of your feature.  If you've done a good job of telling your story, I should be able to see what you've drawn and understand  what you're building - it might take a paragraph or two of text to provide surrounding context, but it should be clear from your diagram.

What are the things that help to tell a good story?  Well, your story should be coherent.  Stories have beginnings, middles and ends.  Your diagram should also have a beginning (entrypoint), a middle (where the work is done) and an end (the output of the diagram).  For example, in my PlaySound threat model, the beginning is the application calling PlaySound, the end is the audio engine.  Obviously other diagrams have other inputs and outputs, but your code is always invoked by something, and it always does something.  Your diagram should reflect this.

In addition, it's always a good idea to look for pieces that are missing.  For instance, if you're doing a threat model for a web browser, it's highly likely that the Internet will show up somewhere in the model.  If it doesn't, it just seems "wrong".  Similarly, if your feature name is something like "Mumblefrotz user experience", then I'd hope to find something that looks like a "user" and something that looks like a "Mumblefrotz". 

Adam's post calls out other inconsistencies that interfere with the storytelling, as does my "rules of thumb" post.

I really like the storytelling metaphor for threat model diagrams because if I can understand the story, it really helps me find the omissions - there's almost always something missed in the diagram, and a coherent story really helps to understand that.  In many ways, pictures do a far better job of telling stories than words do.