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 together simultaneously.

Real-Time Features

Simultaneous Editing

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

Visual Indicators

• See who else is viewing/editing
• View collaborator cursors in diagrams
• See active users list
• Real-time change notifications

Conflict Prevention

• Automatic conflict resolution
• Coordinated updates via WebSocket
• Redis-based synchronization
• Optimistic locking where needed

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 co-present icon; participants show person icon. Tooltip displays localized role name.
Permissions	Shows edit access level	Writer shows edit icon; reader shows edit-off icon. Tooltip displays the permission level.
Username	Displays participant name	Shows the user's display name with email in tooltip for disambiguation.
Presenter	Presenter mode controls	Context-sensitive icon and controls based on 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 State: Shows "Person Raised Hand" icon; clicking sends a presenter request
• Hand Raised State: Shows "Person Raised Hand" icon in green; waiting for host approval
• Presenter State: Shows "Podium" icon indicating active presenter role

Host Controls for Participants:

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

State Transitions

Presenter state transitions are managed via WebSocket messages:

1. Requesting: Participant clicks hand icon -> sends presenter_request -> transitions to hand raised state
2. Approved: Host approves -> change_presenter message -> participant transitions to presenter state
3. Denied: Host denies -> presenter_denied message -> participant returns to hand down state
4. Revoked: Host takes back -> change_presenter message -> presenter returns to 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 threat model access
Presenter	Podium icon	Current presenter who can guide the session view

Sharing Threat Models

Managing Access

1. Open your threat model
2. Click "Share" or "Manage Access"
3. Add collaborators by email/username
4. Set permission levels
5. Send invitations

Permission Levels

Owner:

• Full control over threat model
• Can delete threat model
• Can manage all permissions
• Can transfer ownership

Writer:

• Can edit all content
• Can add/modify diagrams, threats, notes
• Can add comments
• Cannot manage permissions or delete

Reader:

• View-only access
• Can view all content
• Can add comments
• Cannot edit

Inviting Collaborators

• Enter email address or username
• Select permission level
• Add optional message
• Send invitation

Collaboration Workflows

Design Review Sessions

1. Share threat model with team
2. Join video/voice call
3. Collaboratively edit diagrams
4. Identify threats together
5. Document decisions in notes

Async Collaboration

1. Share threat model
2. Team members review and add threats
3. Use comments for discussion
4. Owner reviews and consolidates
5. Track changes over time

Security Review

1. Development team creates initial model
2. Security team reviews as Reader
3. Security adds threats and comments
4. Development team addresses findings
5. Iterate until approved

Best Practices

Communication

• Coordinate major changes
• Use comments for questions
• @mention team members
• Use external chat for complex discussions

Organization

• Assign sections to team members
• Use consistent naming conventions
• Document assumptions in notes
• Regular synchronization points

Etiquette

• Small, incremental changes
• Communicate before major edits
• Review others' changes
• Acknowledge contributions

Comments and Discussions

Adding Comments

• Select component, threat, or note
• Click "Add Comment"
• Write your comment
• @mention users to notify them

Comment Threads

• Reply to comments
• Mark as resolved
• Track conversations
• Link to related items

Change Tracking

Activity Feed

• See recent changes
• Who made what changes
• When changes occurred
• Navigate to changed items

Audit Trail

• Complete history
• User attribution
• Timestamps
• Change details

Notifications

Notification Types

• New comments
• @mentions
• Major changes
• Permission changes
• Shared threat models

Notification Preferences

Configure in user settings:

• Email notifications
• In-app notifications
• Notification frequency
• Specific event types

Technical Architecture

Diagram Collaboration Flow

The collaborative diagram editing system uses a server-authoritative architecture:

Starting a Session:

1. User loads a diagram locally
2. User initiates collaboration via the UI (REST API call to create session)
3. Server creates the session and returns WebSocket URL
4. Users with "owner" or "writer" roles can enable collaboration

Joining a Session:

1. User navigates to available collaboration sessions (filtered by permissions)
2. User selects a diagram to collaborate on
3. Server sends complete diagram state via diagram_state_sync message
4. Client initializes the diagram editor with synchronized state

Editing During Collaboration:

1. User makes a change to the diagram
2. Client sends diagram_operation message to server via WebSocket
3. Server updates global state and broadcasts to all collaborating clients
4. On conflict: Server sends state_correction message to resync clients

Conflict Resolution

• Update Vector: Each diagram has a version number for conflict detection
• Server-Authoritative State: Server maintains canonical state
• Optimistic Updates: Changes applied locally, rolled back if rejected
• State Correction: Automatic resynchronization when conflicts detected

WebSocket Message Types

Message Type	Direction	Purpose
join_session	Client -> Server	Join collaboration session
leave_session	Client -> Server	Leave collaboration session
diagram_operation	Bidirectional	Diagram change operations
diagram_state_sync	Server -> Client	Full state synchronization
state_correction	Server -> Client	Conflict resolution
presenter_request	Client -> Server	Request presenter role
change_presenter	Server -> Client	Presenter assignment change
presenter_cursor	Client -> Server	Cursor position for presenter

X6 Integration

The DFD editor uses AntV X6 (v2.x) for graph visualization with:

• Event Tracking: node:added, node:removed, edge:added, edge:removed, position/size changes
• History Management: Custom AppHistoryService for collaborative undo/redo
• Remote Operations: AppRemoteOperationHandlerService applies incoming changes
• Presenter Cursors: ui-presenter-cursor.service.ts for cursor sharing

For detailed X6 API reference, see DFD Graphing Library Reference.

Next Steps

• Review Managing Threats
• Learn about Issue Tracker Integration
• Explore Using Notes and Documentation
• See Architecture and Design for system-wide architecture