Architecture diagram guidance¶
Types of diagrams required¶
This page provides guidance on architecture diagrams for threat analysis, a template for architecture documentation is available at <link>.
Two types of diagrams are required for threat analysis:
A service architecture diagram
One or more information flow diagrams (either data flow diagrams, sequence diagrams, or both)
Examples of each of these are given below. There are no firm diagramming toolchain requirements, but the tool used must be able to draw the diagrams discussed. It is generally preferable to use a text-based diagram generator so diagrams can be managed with gerrit. Some options for tools include:
draw.io (proprietary XML files, but very easy to use)
Google drawing (no XML/text output, but can be used collaboratively)
blockdiag (non-WYSIWYG with a steeper learning curve, suitable for very simple diagrams)
When drawing architecture diagrams, it may be beneficial to draw the diagram on paper or a whiteboard before attempting to draw it with a diagramming tool.
When you have completed the diagram, export both a text version (if available) and a Portable Network Graphic (.png) file to be committed to the repository with the architecture page.
Service architecture diagram requirements¶
Service Architecture diagrams contain these elements:
A rectangle containing a unique name is used to depict each component
Components may be servers, clusters, or individual processes
Standard component shapes should be used to illustrate component types
A vertical cylinder indicates storage or a database
A horizontal cylinder (a “pipe” shape) indicates a message queue (use an elongated rectangle if horizontal cylinders are unavailable)
A dashed rectangle indicates a future component
Multi-instances of a component should be indicated by a quantity after the component name, for example (100), and if possible layered component boxes
Component shapes don’t need to be all the same size. Some component shapes may be shrunk to allow application layers to be easily recognized, without creating a maze of crossed interface lines
User access over the internet can be indicated by a cloud-shaped component, but where multiple connections or external parties are connected via the internet, a separate internet trust domain should be shown
An arrow connecting two components is used to depict an interface
Each interface has a unique number and name; listing the network protocol (in parenthesis) is strongly recommended
Direction of interface arrow is from the component initiating the connection; the arrowhead points to the listening/receiving component
A future interface is indicated as a dashed arrow
Boundaries between trust domains must be shown
Trust boundaries based on networks are indicated as a dashed line (preferably with rounded corners), with the Network name listed at the upper or lower boundary
Trust boundaries based on groups of components (such as server pairs, clusters, processes, or collections of related components) are indicated by a dotted box
When a third party network boundary is used to illustrate a trust domain, use that third party’s name as the network boundary label
Service architecture diagram template¶
This template illustrates the elements of a service architecture diagram.
Information flow diagram requirements¶
Information flow diagrams depict the flow of data between entities to illustrate the steps in a process or procedure. Often, multiple diagrams are created to illustrate individual use cases.
Each information flow diagram must be in the form of either a data flow diagram (DFD) or a sequence diagram. The architect may select either type of diagram (or both) for illustrating information flows within the service.
Information flow diagrams contain the following elements:
An entity may be a single process, multiple processes within a trust domain, a data store, or an external entity.
Each entity has a unique name which should match a name on the architecture diagram
The number of entities on a flow diagram often matches the number of components on a service architecture diagram.
Arrows indicate data flows between entities; the direction of the arrow indicates the direction of data movement
Any pair of entities may have multiple sets of arrows to illustrate a multi-step exchange of data between the entities
Typically every interface on a service architecture diagram has one or more corresponding data flows on a flow diagram
Groups of entities with the same level of privilege form a trust domain, the boundaries of which are indicated by a dashed line in DFDs and by a shallow rectangle on sequence diagrams
Optional supplementary information
Textual notes on the diagram can provide clarification on data types sent and received, changes in privilege, or steps forming a use case
Data flow diagram template¶
This template illustrates the elements of a data flow diagram.
Sequence diagram template¶
The following template illustrates the elements of a sequence diagram.
Sequence diagrams can be quickly and easily generated from text using WebSequenceDiagrams . Enter a specification using a simple scripting language, as follows. Be sure to include authentication steps in your diagram.
title Issue Certificate
Admin->GUI: 1. Login
GUI->Controller: 2. List(pending)
Controller->DB: 3. Fetch DB
DB->Controller: 4. Cert DB
Controller->Controller: 5. Filter(pending)
Controller->GUI: 6. Show pending certs
Admin->GUI: 7. Issue(ID)
GUI->Controller: 8. Issue(ID)
Controller->Controller: 9. Get CSR(ID)
Controller->CA: 9. Sign(CSR)
CA->Controller: 10. Cert
Controller->DB: 11. Update DB (ID, Issued, Cert)
Controller->User: 12. Email Notification
The tool creates a sequence diagram as follows: