Working with Data Flow Diagrams

Working with Data Flow Diagrams

Comprehensive guide to creating and editing data flow diagrams (DFDs) in TMI.

Overview

Data flow diagrams are visual representations of how data moves through your system. They help identify trust boundaries, data flows, and potential threat surfaces.

Diagram Basics

What is a Data Flow Diagram?

A DFD shows:

• Components that process or store data
• Data flows between components
• Trust boundaries that separate security zones
• External entities that interact with the system

When to Use DFDs

• Threat modeling applications and systems
• Security architecture reviews
• Identifying attack surfaces
• Documenting data handling

Creating a Diagram

Starting a New Diagram

1. Open your threat model
2. Click "New Diagram" or "Add Diagram"
3. Give it a descriptive name
4. Start adding components

Component Types

Process

Represents a component that transforms or processes data.

Visual: Oval/Circle

Examples:

• Web Server
• Authentication Service
• Payment Processor
• Data Transformer

Data Store

Represents a system or component where data is stored.

Visual: Parallel horizontal lines

Examples:

• Database
• File System
• Cache
• Message Queue
• Log Storage
• Cloud Storage Bucket

Actor (official DFD term: "External Entity")

An actor is used to represents external users or systems.

Visual: Rectangle/Square

Examples:

• End Users
• Third-party APIs
• External services dependent on a system, or that the system depends on
• Administrators

Data Flow

Represents data moving between components.

Visual: Arrow

Examples:

• API Request
• Database Query
• File Transfer
• Event Message

Trust Boundary

Represents security or trust zone boundaries.

Visual: Dashed line or box

Examples:

• Internet to DMZ
• DMZ to Internal Network
• Application tier to Data tier
• Authenticated vs Unauthenticated

Text box

Not an official DFD component. Used to add descriptive text anywhere on the diagram.

Visual: Transparent/invisible rectangle with visible label

Adding and Editing Components

1. Click the "Add " button in the toolbar - a new component of the specified type will be added to the diagram.
2. Place the component - while the component is selected, drag the component to the desired location on the diagram.
3. Size the component - while the component is selected, use the drag handles at the corners to change the size of the component.
4. Label the component - double click the component, or right click the component and select "Edit Text" from the context menu, to edit the component's label. Pro tip: if you want to move the label inside a component, create a separate text box, and embed the text box in the component. Use the text box as the component's label, and optionally delete the text in the original label in the component.
5. Delete a component - while the component is selected, either click the delete button in the toolbar, or click the red "X" delete button in the selection tool in the component, or press the delete or backspace key.
6. Edit metadata - using the "manage metadata" button in the toolbar, edit the metadata for the component to add structured detail about the component.

Be Specific With Labels and Metadata:

Good labels:

• "Web Application Server" (example metadata: {"key":"framework", "value":"nodejs"})
• "User Data Store" (example metadata: {"key":"database-type", "value":"postgresql"})
• "Log Collector" (example metadata: {"key":"agent", "value":"promtail", "key":"collector", "value":"grafana"})

Poor labels:

• "Server"
• "Database"
• "System"

Embedding Components

TMI has the ability to embed components in other components, to unambiguously represent a "contains" relationship. For example, if you drag a component into a trust boundary, the component will be embedded into that trust boundary. The underlying representation of the diagram will indicate that the trust boundary is the "parent" of the component, and that the component is a "child" of the trust boundary. This allows automated analysis to easily understand the relationship between components.

To Embed a Component in Another Component

1. Select the new "child" component. For example, if you want to embed a process in a security boundary, then select the process.
2. Drag the child component, into the component that you want to embed it into. In the example above, you would drag the process into the security boundary.
3. **During the drag operation, the new "parent" component will display a bold orange boundary if it is the embedding target. This will allow you to clearly discern which component you are embedding into.
4. Release the mouse button to end the drag and complete the embedding. TMI will adjust the properties of the underling components to reflect the new parent/child relationship, and will alter z-ordering (layering) so that the child component appears in front of the parent component, and will subtly alter the shading of the child component to be slightly darker to visually distinguish it from the parent and to show that it is embedded.

To Un-Embed a Component

1. Select the "child" component - the component that is embedded.
2. Drag the child component out of its parent. Ensure to drag it to an empty place on the graph, or you might accidentally embed it into a different component.

Embedding Note

Not all components can be embedded - you cannot embed components into text boxes, and you cannot embed flows or embed into flows. These would not make sense.

Connecting Components

Creating Data Flows

1. Hover over the source component - the connection ports will appear on that component
2. Click and hold on the port that you want to connect from - available ports on other components will appear
3. Without releasing the left mouse button, drag to the desired port on a destination component - the arrow will follow the mouse
4. Release the mouse button to complete creation of the flow

Editing Data Flows

1. Click on the data flow to select it
2. To move an endpoint to a different port or component drag either the source endpoint (a teal circle on the end of the flow without an arrowhead) or the destination endpoint (an orange circle on the end of the flow with the arrowhead) to a port on a desired component.
3. To re-shape or route a flow click on any vertex (black circle) on the flow and drag it to a new location, or click on part of the flow without a vertex to create a new vertex, and drag it to a new location. The flow will automatically adjust its path to pass through all vertices. To delete a vertex, drag it onto another existing vertex.

Labeling Flows

You can select a flow by clicking it, and then right-click to access the context menu. The context menu will have an item to edit the text of the flow label. Additionally, the context menu has an item to associate the flow with a data typed asset from your threat model, if you have defined any. Finally, flow cells themselves have metadata, and you can add metadata (key, value) pairs to add structured information to the flow. This can make it easier for automated analysis tools to reason about your model.

Be Specific With Labels and Metadata:

Good labels:

• "OAuth User Identity" (example metadata: {"key":"claim", "value":"sub"})
• "Authentication Token" (example metadata: {"key":"key":"type", "value":"JWT"})
• "Payment Information" (example metadata: {"key":"payment-type", "value":"card", "key":"payment-data", "value":"card-number, exp-date, cvv"})
• "Database Query" (example metadata: {"key":"language", "value":"SQL", "key":"database-type", "value":"postgresql"})

Poor labels:

• "Data"
• "Request"
• "Info"

Two Notes On Flows

1. Flows in TMI are unidirectional. This is intentional to aid automated directed graph analysis in future TMI tools and features. If you need a bidirectional flow, either create a separate flow in the opposite direction, or select the flow and use the "Add Inverse Connection" tool in the right-click context menu in the flow to automatically create a flow in the opposite direction from the same ports, copying labels and metadata.
2. Flow labels can be moved. If you carefully click on a flow's label, you can drag it to a new position relative to the flow.

Trust Boundaries

Why Trust Boundaries Matter

Trust boundaries are generally used to express the enforcement limits of security controls. For example, an application might be expressed as a security boundary, because the application cannot enforce authorization policy on data outside the application; or a virtual cloud network might be expressed as a boundary, because security ACLs and groups cannot be used to limit access on data that has not entered, or that has already left, the network.

Security boundaries can also be used to express:

• Security context changes
• Authentication level changes
• Data sensitivity changes
• Changes in threat landscape

Common Trust Boundaries

• Internet to DMZ: Public to semi-trusted
• DMZ to Internal: Semi-trusted to trusted
• Process isolation: Between different security contexts
• Network segmentation: Between network zones

Best Practices

Start Simple

• Begin with high-level view
• Add detail incrementally
• Create multiple diagrams for complex systems

Clear Naming

• Use descriptive, consistent names
• Avoid abbreviations unless well-known
• Include role/function in name

Show All Data Flows

• Document all data movement
• Include error flows
• Show authentication/authorization flows

Mark Trust Boundaries

• Identify all security zone changes
• Show where authentication occurs
• Mark where data sensitivity changes

Keep Diagrams Focused

• One diagram per system/subsystem
• Don't overcrowd a single diagram
• Link related diagrams

Use Consistent Style

• Similar components get similar shapes
• Consistent naming conventions
• Uniform level of detail

Editing Diagrams

Selecting Components

• Click to select
• Shift+Click for multiple selection
• Drag box to select multiple

Moving Components

• Drag selected component
• Arrow keys for precise movement

Resizing Components

• Drag corner handles to resize
• Maintain aspect ratio
• Size to fit label

Deleting Components

• Select component
• Press the Delete or Backspace key
• Or click the red "X" delete tool in the selected component
• Or click delete button in toolbar

Copying Components

• Select component
• Ctrl/Cmd+C to copy
• Ctrl/Cmd+V to paste

Linking Threats to Diagrams

Why Link Threats?

• Visual representation of threat locations
• Easy identification of affected components
• Better understanding of threat context

Creating Linked Threats

1. Create or edit a threat
2. Find "Linked Components" section
3. Select diagram components affected by threat
4. Save

Note: if you select a component or flow, and create a threat from within the diagram editor using the "create threat" button, the threat will automatically be linked to the selected component in the current diagram.

Collaboration on Diagrams

Real-Time Editing

• Multiple users can edit simultaneously
• Changes appear immediately
• Automatic conflict resolution

Presenter Mode

Presenter mode, indicated by a podium icon, is a collaboration mode where one participant (the presenter) shares their cursor and selection with all participants. It's designed to let the presenter point out aspects of the diagram. While you're actively presenting, other participants will see your cursor on their graphs, and when you select or hover over components, other participants will see visual changes on their graph as if they moved their cursor to the same position.

The host, who is the person who initiated the collaboration session, is the default presenter, but anyone can be assigned the presenter role in a session. The current presenter always has a podium icon next to their name in the list of participants.

If you are not the presenter, you can request to be the presenter by clicking the "Request Presenter" (raise hand) button. The current presenter will be asked if they want to transfer presenter mode to you.

If you are the host, you can also take back presenter mode at any time from the participants list.

If you are the presenter, you will see the podium icon in your collaboration toolbar instead of the raise hand icon. Clicking the podium button toggles presenter mode; when presenter mode is active the podium will be highlighted in green. Click the podium icon again to toggle presenter mode off; your cursor location will no longer be broadcasting to participants. As a best practice, you should only run with presenter mode on while you are actively presenting.

Collaboration Best Practices

• Review together: Use for design sessions - you can use TMI as a virtual whiteboard
• Communicate: Let others know if you're going to make a change
• Slow down: Changes take a small time to go to the server, be stored, be propagated to all participants, and be drawn on participants screens
• One at a time: If multiple people make changes at the same time, the server will calculate the diagram state first-in-first-out, but that means that you might be surprised at the outcome if you and another person made conflicting changes - somebody's change will be over-written

Exporting Diagrams

Export Formats

Potential export options:

• PNG image
• SVG vector
• PDF document

Embedding in Documentation

• Screenshot for presentations
• Link directly in threat model notes
• Reference in external documentation

Tips for Effective Diagrams

Focus on Data

• Emphasize data flows over implementation details
• Show what data moves, not how - use metadata to describe the communication channel for later analysis
• Associate flows with a data asset, or use metadata to capture data classification & sensitivity

Identify Assets

• Highlight valuable data stores
• Show where credentials are handled
• Mark PII and sensitive data

Show Authentication Points

• Where authentication occurs
• Where authorization is checked
• Session management points

Document Assumptions

• Use notes to document what's included/excluded
• Clarify trust assumptions
• Note out-of-scope items

Next Steps

• Learn about Managing Threats and linking them to diagrams
• Explore Collaborative Threat Modeling
• Review Creating Your First Threat Model

Advanced Interactions

This section covers detailed interaction behaviors and visual feedback for power users.

Visual Feedback

The DFD editor provides visual feedback for various interaction states:

State	Visual Effect
Hover	Subtle red glow around component
Selected	Strong red glow around component
Creating	Blue glow that fades over 500ms (green for remote/collaborative changes)
Embedding Target	Orange border (3px, #ff6b00) when dragging over valid parent
Invalid Embedding	Red flash (300ms) when attempting invalid embedding

Embedding Rules

Not all embedding combinations are valid:

Scenario	Allowed?	Notes
Process into Security Boundary	Yes	Common pattern
Security Boundary into Security Boundary	Yes	Nested boundaries
Process into Process	Yes	Nested processes
Any into Text Box	No	Text boxes cannot contain components
Text Box into Any	No	Text boxes cannot be embedded
Security Boundary into Process	No	Security boundaries can only be embedded into other security boundaries
Circular (A into B into A)	No	Circular embedding prevented

When an invalid embedding is attempted:

• No orange highlight appears during drag
• On release, a red flash appears on the dragged component
• A notification explains why the embedding failed

Z-Order (Layering)

Components have a z-order that determines which appears in front:

Element Type	Default Z-Index
Security Boundary (unembedded)	1 (always behind)
Regular Nodes	10
Text Box	20 (always in front)
Embedded child	Parent z-index + 1
Edges	Max of source/target z-index

You can adjust z-order via right-click context menu:

• Move Forward/Backward: Adjust by one layer
• Move to Front/Back: Move to extreme position within category

Keyboard Shortcuts

Shortcut	Action
Delete / Backspace	Delete selected components
Ctrl+Z / Cmd+Z	Undo
Ctrl+Y / Cmd+Shift+Z	Redo
Shift + Mouse Drag	Pan the canvas
Shift + Mouse Wheel	Zoom in/out

Graph Navigation

Zooming:

• Hold Shift + scroll mouse wheel
• Zoom factor: 1.1x per scroll
• Range: 20% to 300%
• Zooms centered on mouse cursor

Panning:

• Hold Shift + drag with left mouse button

Grid:

• 10px grid spacing
• Snap-to-grid enabled by default
• Hold Shift while dragging to temporarily disable snap

Connection Ports

When hovering over a component, four connection ports appear (top, right, bottom, left). When creating a new connection:

• All available ports on all components become visible
• Valid target ports show green highlight
• Connections snap to nearby ports (within 20px)

Edge (Data Flow) Management

When an edge is selected, tools appear:

• Blue circle at source end: drag to reconnect source
• Orange circle at target end: drag to reconnect target
• Red X button: delete edge
• Vertices: Click on edge to add bend points; drag vertices to reshape; drag onto another vertex to remove

Related Topics

• Understanding the User Interface
• Using Notes and Documentation
• Architecture and Design
• DFD Graphing Library Reference