Collaborative Threat Modeling

Collaborative Threat Modeling

Work with your team in real-time on threat models.

Overview

TMI supports real-time collaborative threat modeling, allowing multiple team members to work on the same threat model simultaneously. This page covers the collaboration features, session management, access control, and the underlying technical architecture.

Real-Time Features

Simultaneous Editing

• Multiple users can edit the same threat model at once.
• Changes appear immediately for all connected users.
• WebSocket-based synchronization keeps all clients in sync.
• No need to refresh or manually save.

Visual Indicators

• See who else is viewing or editing the threat model.
• View the presenter's cursor position in diagrams (presenter mode only).
• See the active participants list with each user's permissions and role.
• Receive real-time notifications when participants join or leave the session.

Conflict Prevention

• Server-authoritative state with operation rejection for conflicts.
• Coordinated updates via WebSocket with sequence numbering.
• Update-vector-based conflict detection.
• Optimistic local updates with automatic resynchronization when the server rejects an operation.

Session Participant List

The collaboration dialog displays a list of all participants in the current session. Each participant row shows five columns of information.

Column Layout

Column	Purpose	Details
User Type	Identifies host vs. participant	Host shows a co-present icon; participants show a person icon. Tooltip displays the localized role name.
Permissions	Shows edit access level	Writer shows an edit icon; reader shows an edit-off icon. Tooltip displays the permission level.
Username	Displays participant name	Shows the user's display name with email in the tooltip for disambiguation.
Presenter	Presenter mode controls	Context-sensitive icon and controls based on the user's presenter state.
Remove	Session management	Host can remove participants from the session.

Presenter Mode States

The presenter column displays different controls based on the user's role and presenter status.

For the Host:

• When presenter: Podium icon (active) with "Presenter" tooltip.
• When not presenter: Podium icon (inactive) with no action.

For Participants:

• Hand Down: Shows a "Person Raised Hand" icon. Clicking it sends a presenter request to the host.
• Hand Raised: Shows a "Person Raised Hand" icon in green, indicating the participant is waiting for host approval.
• Presenter: Shows a "Podium" icon, indicating the participant is the active presenter.

Host Controls for Participants:

• When a participant is the presenter, the host sees a podium icon with a close overlay to revoke presenter privileges.
• When a participant has a pending request, the host can approve or deny the request via a context menu.

State Transitions

Presenter state transitions are managed via WebSocket messages:

1. Requesting: The participant clicks the hand icon, which sends a presenter_request message and transitions to the hand-raised state. The server forwards a presenter_request_event to the host.
2. Approved: The host approves the request, which sends a change_presenter_request message. The server broadcasts an updated participants_update with the current_presenter field set, and the participant transitions to the presenter state.
3. Denied: The host denies the request, which sends a presenter_denied_request message. The server sends a presenter_denied_event to the requester, and the participant returns to the hand-down state.
4. Revoked: The host revokes presenter privileges by sending a change_presenter_request with the host's own ID or null. The server broadcasts an updated participants_update, and the former presenter returns to the hand-down state.

Session Roles

Role	Icon	Description
Host	Co-present icon	Session creator with full management permissions.
Participant	Person icon	Session member with permissions based on their threat model access level.
Presenter	Podium icon	Current presenter who can guide the session view for all participants.

Sharing Threat Models

Managing Access

Access to threat models is managed through the authorization list on the threat model itself. To grant access:

1. Open your threat model in the Understanding-the-User-Interface.
2. Edit the authorization list to add users by their identity provider and provider ID.
3. Assign a permission level (owner, writer, or reader) to each user.

Permission Levels

Owner:

• Full control over the threat model.
• Can delete the threat model.
• Can manage the authorization list.
• Can transfer ownership.

Writer:

• Can edit all content.
• Can add and modify diagrams, threats, notes, and other resources.
• Cannot manage the authorization list or delete the threat model.

Reader:

• View-only access.
• Can view all content.
• Cannot make edits.

Note: In collaboration sessions, participants' WebSocket permissions are mapped to writer or reader based on their threat model authorization. The owner role is treated as writer for WebSocket collaboration purposes.

Collaboration Workflows

Design Review Sessions

1. Grant team members access via the authorization list.
2. Join a video or voice call.
3. Collaboratively edit Working-with-Data-Flow-Diagrams.
4. Identify threats together.
5. Document decisions in Using-Notes-and-Documentation.

Asynchronous Collaboration

1. Grant access to the threat model via the authorization list.
2. Team members review and add Managing-Threats asynchronously.
3. Use Using-Notes-and-Documentation for discussion and documentation.
4. The owner reviews and consolidates contributions.
5. Track changes via the #audit-trail.

Security Review

1. The development team creates an initial threat model.
2. The security team reviews the model as a reader or writer.
3. Security team members add threats and notes with their findings.
4. The development team addresses the findings.
5. Iterate until the security team approves the model.

Best Practices

Communication

• Coordinate major changes with your team before making them.
• Use external chat or video calls for complex discussions.
• Use presenter mode to guide collaborators through the diagram.

Organization

• Assign sections to individual team members.
• Use consistent naming conventions across the threat model.
• Document assumptions in Using-Notes-and-Documentation.
• Schedule regular synchronization points to review progress.

Etiquette

• Make small, incremental changes rather than large bulk edits.
• Communicate before making major structural edits.
• Review changes made by other team members.
• Acknowledge contributions from collaborators.

Change Tracking

Audit Trail

TMI maintains a comprehensive audit trail for each threat model. The audit trail records:

• Object type affected (threat model, diagram, threat, asset, document, note, or repository).
• Change type (created, updated, patched, deleted, rolled back, or restored).
• Actor information (email, provider, provider ID, and display name).
• Change summary and timestamps.
• Version tracking for versioned objects.

The audit trail is accessible via the threat model's audit trail page and supports filtering by object type, change type, actor, and date range.

Notifications

TMI provides server-side notification infrastructure via a WebSocket-based notification hub. Notification types include:

• Threat model created, updated, deleted, or shared.
• Collaboration session started or ended.
• User joined or left a collaboration session.
• System announcements and maintenance notices.

Technical Architecture

The collaborative diagram editing system uses a server-authoritative architecture. For the full WebSocket protocol specification, see the WebSocket-API-Reference.

Diagram Collaboration Flow

Starting a Session

1. A user loads a diagram locally.
2. The user initiates collaboration via the UI, which triggers a REST API call to start or join a session.
3. The server creates the session and returns a WebSocket URL along with session metadata.
4. Only users with "owner" or "writer" threat model permissions can start collaboration sessions.

Joining a Session

1. The user navigates to the list of available collaboration sessions, filtered by their permissions.
2. The user selects a diagram to collaborate on.
3. The client sends a sync_request, and the server responds with a diagram_state message containing the complete diagram state.
4. The client initializes the diagram editor with the synchronized state.

Editing During Collaboration

1. The user makes a change to the diagram.
2. The client sends a diagram_operation_request message to the server via WebSocket, including its current base_vector.
3. The server validates the operation, applies it, updates the update_vector, and broadcasts a diagram_operation_event to all connected clients.
4. On conflict, the server sends an operation_rejected message to the originating client with the rejection reason and the current update_vector. The client then resynchronizes by sending a new sync_request.

Conflict Resolution

• Update Vector: Each diagram has an update_vector (an integer) used for conflict detection. Clients send their base_vector with each operation.
• Server-Authoritative State: The server maintains the canonical state and assigns monotonically increasing sequence numbers to accepted operations.
• Optimistic Updates: Changes are applied locally first and rolled back if the server rejects them via an operation_rejected message.
• Resynchronization: After a rejection, the client sends a sync_request. The server responds with either a diagram_state (full state) or a sync_status_response (if the client is already current).

WebSocket Message Types

For the complete message type reference, see the WebSocket-API-Reference.

Diagram Operations

Message Type	Direction	Purpose
diagram_operation_request	Client to Server	Request a diagram change (add, update, or remove cells).
diagram_operation_event	Server to Client	Broadcast an accepted diagram operation.
operation_rejected	Server to Client	Notify the originator that an operation was rejected.
authorization_denied	Server to Client	Deny an operation due to insufficient permissions.

Synchronization

Message Type	Direction	Purpose
sync_request	Client to Server	Request the full diagram state (conditional on update_vector).
diagram_state	Server to Client	Respond with the full diagram state.
sync_status_request	Client to Server	Perform a lightweight check of the server's update_vector.
sync_status_response	Server to Client	Return the current update_vector from the server.

Presenter Mode

Message Type	Direction	Purpose
presenter_request	Client to Server	Participant requests the presenter role.
presenter_request_event	Server to Host	Notify the host of a pending presenter request.
change_presenter_request	Client to Server	Host assigns or revokes the presenter role.
presenter_denied_request	Client to Server	Host denies a presenter request.
presenter_denied_event	Server to Client	Notify the requester that the request was denied.
presenter_cursor	Bidirectional	Transmit cursor position for the presenter.
presenter_selection	Bidirectional	Transmit selected cell IDs for the presenter.

Session Management

Message Type	Direction	Purpose
participants_update	Server to Client	Broadcast the complete participant list with host and current presenter.
remove_participant_request	Client to Server	Host removes a participant from the session.
undo_request	Client to Server	Request undo of the last operation.
redo_request	Client to Server	Request redo of the last undone operation.
error	Server to Client	Report a general error.

X6 Integration

The DFD editor uses AntV X6 (v2.19.x) for graph visualization. For the full X6 API reference, see DFD-Graphing-Library-Reference.

• Event Tracking: Listens for node:added, node:removed, node:change:position, node:change:size, node:change:parent, node:moved, edge:added, edge:removed, and attribute change events.
• History Management: A custom AppHistoryService provides collaborative undo and redo with per-user operation stacks.
• Remote Operations: AppRemoteOperationHandler converts incoming WebSocket CellOperation messages to the internal GraphOperation format and applies them without triggering history recording or re-broadcasting.
• Presenter Cursor Broadcasting: UiPresenterCursorService tracks and sends the cursor position when the current user is the presenter.
• Presenter Cursor Display: UiPresenterCursorDisplayService renders incoming presenter cursor positions with custom styling and synthetic hover effects.

Next Steps

• Managing-Threats -- Learn how to identify, categorize, and track threats.
• Issue-Tracker-Integration -- Connect threats to your issue tracking system.
• Using-Notes-and-Documentation -- Document decisions and attach supporting materials.
• Architecture-and-Design -- Understand the system-wide architecture.