Working with Data Flow Diagrams

Working with Data Flow Diagrams

This guide covers how to create, edit, and use data flow diagrams (DFDs) in TMI for threat modeling.

Overview

Data flow diagrams are visual representations of how data moves through your system. They help you 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

Use DFDs when you need to:

• Threat model applications and systems
• Conduct security architecture reviews
• Identify attack surfaces
• Document data handling

Creating a Diagram

Starting a New Diagram

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

Component Types

Process

Represents a component that transforms or processes data.

Visual: Rounded rectangle

Examples:

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

Data Store

Represents a system or component where data is stored.

Visual: Cylinder (drum shape with elliptical top)

Examples:

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

Actor (External Entity)

An actor represents an external user or system. The official DFD term for this component type is "external entity."

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 rounded rectangle

Examples:

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

Text Box

A text box is not an official DFD component. You can use it to add descriptive text anywhere on the diagram.

Visual: Transparent/invisible rectangle with visible label

Adding and Editing Components

1. Click the "Add [component type]" button in the toolbar. A new component of the specified type appears on the diagram.

2. Place the component. While the component is selected, drag it to the desired location on the diagram.

3. Size the component. While the component is selected, use the drag handles at the corners to resize it.

4. Label the component. Double-click the component, or right-click it and select "Edit Text" from the context menu, to edit the label.

   Tip: To reposition a label inside a component, create a separate text box and embed it in the component. Use the text box as the label, and optionally delete the original label text from the component.

5. Delete a component. While the component is selected, click the delete button in the toolbar, click the red "X" delete button in the selection tool, or press the Delete or Backspace key.

6. Edit metadata. Click the "Manage Metadata" button in the toolbar to add structured detail about the component.

7. Style the component. Click the style panel toggle (palette icon) in the toolbar to open the style panel, where you can change colors and formatting for selected components.

8. Manage threats. Click the "Manage Threats" button in the toolbar to view and manage threats linked to the selected component.

9. Zoom to fit. Click the "Zoom to Fit" button in the toolbar to automatically scale and center the diagram to fit the viewport.

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

You can embed components inside other components to represent a "contains" relationship. For example, if you drag a process into a trust boundary, TMI embeds the process as a "child" of that trust boundary "parent." This parent/child relationship is stored in the underlying diagram representation, which allows automated analysis tools to understand how components relate to each other.

To Embed a Component

1. Select the child component. For example, if you want to embed a process in a security boundary, select the process.
2. Drag the child component into the target parent component. In the example above, drag the process into the security boundary.
3. Watch for the orange highlight. During the drag operation, the target parent component displays a bold orange boundary to confirm it is the embedding target.
4. Release the mouse button to complete the embedding. TMI adjusts the component properties to reflect the new parent/child relationship, updates z-ordering (layering) so the child appears in front of the parent, and applies a light bluish tint to the child (progressively darker at deeper nesting levels) to visually indicate embedding.

To Un-Embed a Component

1. Select the embedded child component.
2. Drag it out of its parent. Make sure you drag it to an empty area on the graph to avoid accidentally embedding it into a different component.

Embedding Restrictions

Not all embedding combinations are allowed:

• You cannot embed components into text boxes.
• Security boundaries can only be embedded into other security boundaries.
• You cannot embed flows or embed components into flows.

Text boxes can be embedded into containers such as security boundaries. See the Embedding Rules table in the Advanced Interactions section for the full compatibility matrix.

Connecting Components

Creating Data Flows

1. Hover over the source component. Connection ports appear on the component.
2. Click and hold on the port you want to connect from. Available ports on other components become visible.
3. Drag to the desired port on a destination component without releasing the mouse button. The arrow follows the mouse.
4. Release the mouse button to complete 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 the source endpoint (teal circle, on the end without an arrowhead) or the destination endpoint (orange circle, on the end with the arrowhead) to a port on the desired component.
3. To reshape or reroute a flow, click on any vertex (orange circle) on the flow and drag it to a new location. You can also click on a section of the flow without a vertex to create a new vertex, then drag it into position. The flow automatically adjusts its path through all vertices. To delete a vertex, drag it onto another existing vertex.

Labeling Flows

To label a flow, select it by clicking, then right-click to open the context menu. From the context menu you can:

• Edit the flow label text.
• Associate the flow with a data-typed asset from your threat model, if you have defined any.
• Add metadata as key-value pairs to attach structured information to the flow. This makes it easier for automated analysis tools to reason about your model.

Be Specific with Flow Labels and Metadata

Good labels:

• "OAuth User Identity" (example metadata: {"key":"claim", "value":"sub"})
• "Authentication Token" (example metadata: {"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"

Notes on Flows

1. Flows are unidirectional. TMI uses unidirectional flows to support automated directed graph analysis. If you need a bidirectional flow, you have two options: create a separate flow in the opposite direction, or select the existing flow and use the "Add Inverse Connection" tool in the right-click context menu. The inverse connection tool automatically creates a return flow from the same ports, copying labels and metadata.
2. Flow labels can be repositioned. Click carefully on a flow's label, then drag it to a new position relative to the flow.

Trust Boundaries

Why Trust Boundaries Matter

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

You can also use security boundaries 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

Resizing Components

• Drag corner handles to resize

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 the component
• Click the copy button in the toolbar to copy (or click cut to copy and remove the original)
• Click the paste button in the toolbar 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 the "Linked Components" section.
3. Select the diagram components affected by the 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 is automatically 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 feature where one participant shares their cursor and selection with all other participants. It is designed to let the presenter point out aspects of the diagram. While you are actively presenting, other participants see your cursor on their graph. When you select or hover over components, other participants see the same visual changes as if they moved their own cursor to that position.

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

Requesting presenter mode: If you are not the presenter, click the "Request Presenter" (raise hand) button. The current presenter is then asked whether to transfer presenter mode to you.

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

Toggling presenter mode: If you are the presenter, a podium icon appears in your collaboration toolbar instead of the raise hand icon. Click the podium button to toggle presenter mode on (highlighted in green) or off. When presenter mode is off, your cursor location is no longer broadcast to participants. As a best practice, keep presenter mode on only 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 amount of time to reach the server, be stored, propagate to all participants, and render on their screens
• One at a time: If multiple people make changes simultaneously, the server processes them first-in-first-out. This means that conflicting changes may produce unexpected results, and one person's change may be overwritten

Exporting Diagrams

Export Formats

Available export options:

• SVG vector
• PNG image
• JPEG image

Using Exported Diagrams

• Include screenshots in 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 and 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
Text Box into Security Boundary	Yes	Text boxes can be embedded into containers
Any into Text Box	No	Text boxes cannot contain other components
Security Boundary into Process	No	Security boundaries can only be embedded into other security boundaries
Security Boundary into Actor	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
Edges	10
Text Box	20 (always in front of regular nodes)
Embedded child	Parent z-index + 1

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
Ctrl+S / Cmd+S	Save diagram
Ctrl+A / Cmd+A	Select all
Escape	Clear selection
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% (manual zoom); automatic zoom-to-fit caps at 125%
• 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 a node to temporarily disable snap-to-grid

Connection Ports

When you hover over a component, four connection ports appear (top, right, bottom, left). When you create a new connection:

• All available ports on all components become visible.
• Valid target ports show a green highlight. When a connection snaps to a valid target port, the highlight changes to blue.
• Connections snap to nearby ports (within 20px).

Edge (Data Flow) Management

When you select an edge, the following tools appear:

• Teal circle at source end: drag to reconnect the source
• Orange circle at target end: drag to reconnect the target
• Red X button: delete the edge
• Orange vertices: click on the edge to add bend points; drag vertices to reshape; drag a vertex onto another vertex to remove it

Related Topics

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