Collaboration - Faction

Overview

Faction provides comprehensive collaboration capabilities enabling distributed security teams to work together efficiently on assessments. Features include real-time event streaming, multi-assessor workflows, concurrent editing protection, and Burp Suite integration for live findings submission.

Team-Based Assessments

Multiple assessors can collaborate on the same assessment simultaneously:

// Assessment.java:45 - Multiple assessors per assessment
@OneToMany(fetch = FetchType.LAZY)
private List<User> assessor;

Collaboration Roles

Assessors

Active testers performing security evaluation

Engagement Manager

Coordinator managing client communications

Remediation Contact

Developer or security team receiving findings

Each role has specific permissions and responsibilities within the assessment workflow.

Real-Time Event Streaming

Faction implements Server-Side Events (SSE) for real-time collaboration through the EventStreamServlet (src/com/fuse/servlets/EventStreamServlet.java).

Event Stream Architecture

/**
 * Server-Side Events (SSE) Servlet
 * 
 * Handles SSE connections using Servlet 3.0+ async support.
 */
public class EventStreamServlet extends HttpServlet {
    // Thread-safe map to store all connected SSE clients by session ID
    private static final Map<String, AsyncContext> CLIENTS = 
        new ConcurrentHashMap<>();
}

Event Types

The event stream broadcasts updates for:

Vulnerability additions: New findings added by assessors
Assessment updates: Changes to summary, risk analysis, or metadata
Lock notifications: When sections are locked/unlocked for editing
Status changes: Workflow state transitions
Custom messages: Application-specific events

Connection Management

// Establishing SSE connection
response.setContentType("text/event-stream");
response.setCharacterEncoding("UTF-8");
response.setHeader("Cache-Control", "no-cache");
response.setHeader("Connection", "keep-alive");

// Track connected clients
String sessionId = request.getSession().getId();
CLIENTS.put(sessionId, asyncContext);

SSE provides a persistent HTTP connection that allows the server to push updates to clients immediately, without polling.

Broadcasting Events

The system broadcasts events to all connected clients or specific assessments:

// EventStreamServlet broadcasting (from api/assessments.java:1804)
EventStreamServlet.broadcastEvent(
    "message",           // Event type
    messageJson,         // Event data (JSON)
    null,                // Session ID (null = all sessions)
    String.valueOf(assessmentId)  // Assessment filter
);

Event Filtering

Events can be targeted to:

Specific assessment: Only users viewing that assessment
Specific session: Only a particular user
All clients: Broadcast to everyone (system-wide notifications)

Example: Vulnerability Creation

// AddVulnerability.java:686 - Broadcasting new vulnerability
EventStreamServlet.broadcastEvent(
    "message", 
    messageJson,
    sessionId, 
    "" + assessmentId
);

When one assessor adds a vulnerability, all other assessors viewing that assessment receive an instant notification.

Concurrent Editing Protection

Faction prevents data loss through section-level locking:

Assessment-Level Locks

// Assessment.java:97-116 - Section locks
private Boolean notesLock = false;
private User notes_locked_by;
private Date notes_lock_time;

private Boolean summary_lock = false;
private User summary_locked_by;
private Date summary_lock_time;

private Boolean risk_lock = false;
private User risk_locked_by;
private Date risk_lock_time;

Vulnerability-Level Locks

// Vulnerability.java:69-80 - Field-level locks
private Boolean desc_lock = false;
private User desc_locked_by;
private Date desc_lock_time;

private Boolean rec_lock = false;
private User rec_locked_by;
private Date rec_lock_time;

private Boolean detail_lock = false;
private User detail_locked_by;
private Date detail_lock_time;

Lock Behavior

User Begins Editing

Section lock acquired, stored with user ID and timestamp

Other Users Notified

SSE event broadcasts lock status to other connected users

Editing Prevented

UI prevents other users from editing locked sections

Lock Released

User saves or cancels, lock removed, others can now edit

Locks are automatically released if a user’s session expires or they navigate away, preventing permanent lock situations.

Burp Suite Integration

The Faction Burp Extension enables real-time collaboration between Burp Suite and Faction.

Live Findings Submission

Direct from Burp

Send findings directly from Burp Suite to Faction assessments

Instant Availability

Vulnerabilities appear in Faction immediately for all team members

Context Preserved

HTTP requests, responses, and notes transferred automatically

Reduce Manual Entry

Eliminate copy-paste between tools, focus on testing

Workflow Integration

Assessor discovers vulnerability in Burp Suite during testing
Right-click → Send to Faction from Burp context menu
Burp extension calls Faction API to create vulnerability
SSE broadcasts vulnerability addition to all connected users
Team members see finding instantly in their browsers
Collaborative editing begins immediately on the new finding

Multiple assessors can use Burp Suite simultaneously, all feeding findings into the same assessment in real-time.

Notebook Collaboration

Assessors can maintain separate notes or collaborate on shared notes:

// Assessment.java:58 - Multiple notes per assessment
@OneToMany(fetch = FetchType.LAZY, cascade = CascadeType.ALL, orphanRemoval = true)
private List<Note> notebook = new ArrayList<>();

Each note tracks:

Creator: Original author (assessor)
Last editor: Most recent modifier
Timestamps: Creation and update times
Name: Note identifier for organization

Note Management

// Assessment.java:529-544 - Note operations
public Note getNoteById(Long noteId) {
    return this.notebook.stream()
        .filter(note -> note.getId().equals(noteId))
        .findFirst()
        .orElse(null);
}

public Note updateNoteById(Long noteId, String name, String noteStr, User updatedBy) {
    Note note = this.getNoteById(noteId);
    note.setName(name);
    note.setNote(noteStr);
    note.setUpdatedBy(updatedBy);
    note.setUpdated(new Date());
    return note;
}

Event Monitoring

Administrators can monitor collaboration activity:

// Events.java:111-112 - System metrics
int connectedClients = EventStreamServlet.getConnectedClientsCount();
int totalEvents = EventStreamServlet.getTotalEventsCount();

Metrics Available

Connected clients: Number of active SSE connections
Total events: Cumulative events broadcast
Events per assessment: Activity level per assessment
Active users: Who is currently working

Assessments support file attachments for sharing evidence:

// Assessment.java:81 - Image attachments
@OneToMany(fetch = FetchType.LAZY, cascade = CascadeType.ALL, orphanRemoval=true)
private List<Image> images = new ArrayList<>();

Team members can:

Upload screenshots and evidence
Attach supporting documents
Share POC code or scripts
Maintain assessment-specific resources

Distribution Lists

Manage stakeholder communications:

// Assessment.java:59 - Email distribution
private String DistributionList;

Distribution lists enable:

Automated report delivery
Status update notifications
Stakeholder communications
Escalation paths

Access Management

Control who can access assessment data:

// Assessment.java:60 - Access documentation
private String AccessNotes;

Use for:

VPN credentials
Application URLs
Test account credentials
Access restrictions and requirements

Store sensitive credentials securely. Consider using a password manager integration for production environments.

Campaign Coordination

Coordinate related assessments across teams:

// Assessment.java:72 - Campaign grouping
@ManyToOne
private Campaign campaign;

Campaigns enable:

Multi-team coordination
Related assessment tracking
Program-level reporting
Historical trend analysis

Best Practices

Establish Communication Norms

Define when to use SSE notifications vs. external communication (Slack, Teams) for different event types.

Lock Management

Edit sections in small chunks and release locks promptly to avoid blocking teammates.

Notebook Organization

Use consistent naming for notes (e.g., “Web App - Authentication”, “Network - DMZ”) to help team members find information.

Burp Suite Workflow

Agree on when to submit findings from Burp (immediately vs. after validation) to maintain quality.

Time Zone Awareness

For distributed teams, include time zone context in notes and scheduling to avoid confusion.

Troubleshooting

SSE Connection Issues

If real-time updates aren’t working:

Check browser console for SSE connection errors
Verify proxy/firewall settings allow long-lived HTTP connections
Review load balancer configuration for sticky sessions
Monitor server logs for EventStreamServlet errors

Lock Conflicts

If sections remain locked:

Check lock timestamp - may indicate abandoned session
Admin override - manually release stuck locks
Session timeout - locks auto-release on session expiration

Next Steps

Peer Review

Collaborative quality assurance workflow

Burp Extension

Install the Burp Suite integration

API Reference

Build custom integrations

Development

Extend collaboration features

Getting Started

Core Features

User Guides

Integrations

Extensions

​Overview

​Team-Based Assessments

​Collaboration Roles

Assessors

Engagement Manager

Remediation Contact

​Real-Time Event Streaming

​Event Stream Architecture

​Event Types

​Connection Management

​Broadcasting Events

​Event Filtering

​Example: Vulnerability Creation

​Concurrent Editing Protection

​Assessment-Level Locks

​Vulnerability-Level Locks

​Lock Behavior

​Burp Suite Integration

​Live Findings Submission

Direct from Burp

Instant Availability

Context Preserved

Reduce Manual Entry

​Workflow Integration

​Notebook Collaboration

​Note Management

​Event Monitoring

​Metrics Available

​File Sharing

​Distribution Lists

​Access Management

​Campaign Coordination

​Best Practices

​Troubleshooting

​SSE Connection Issues

​Lock Conflicts

​Next Steps

Peer Review

Burp Extension

API Reference

Development

Build docs developers (and LLMs) love

Overview

Team-Based Assessments

Collaboration Roles

Real-Time Event Streaming

Event Stream Architecture

Event Types

Connection Management

Broadcasting Events

Event Filtering

Example: Vulnerability Creation

Concurrent Editing Protection

Assessment-Level Locks

Vulnerability-Level Locks

Lock Behavior

Burp Suite Integration

Live Findings Submission

Workflow Integration

Notebook Collaboration

Note Management

Event Monitoring

Metrics Available

File Sharing

Distribution Lists

Access Management

Campaign Coordination

Best Practices

Troubleshooting

SSE Connection Issues

Lock Conflicts

Next Steps