Web Interface Guide#

The CipherSwarm v2 web interface provides a modern, responsive dashboard for managing your password cracking operations with real-time updates and project-based organization.

Table of Contents#

Web Interface Guide

Authentication & Project Context#

Navigate to the CipherSwarm web interface
Enter your email and password
Click "Sign In"
If you have access to multiple projects, select your active project from the project selector

Project Context#

CipherSwarm v2 introduces project-based organization:

Project Selector: Located in the header, allows switching between projects you have access to
Project Scoping: All campaigns, hash lists, and resources are scoped to the selected project
Multi-tenancy: Data is isolated between projects for security

<div class="project-selector">
 <select class="form-select">
  <option value="project1">
   Project Alpha
  </option>
  <option value="project2">
   Project Beta
  </option>
 </select>
</div>

Dashboard Overview#

The main dashboard provides real-time operational awareness with live updates via streaming connections.

Status Cards#

The top of the dashboard displays four key metrics:

Active Agents
- Shows online agents vs total registered
- Click to open Agent Status Sheet
- Real-time updates via streaming
Running Tasks
- Active campaigns and task breakdown
- Percentage of running vs completed tasks
- Links to campaign details
Recently Cracked Hashes
- Hashes cracked in the last 24 hours
- Scoped to accessible projects
- Links to results view
Resource Usage
- Aggregate hash rate across all agents
- Sparkline chart showing 8-hour trend
- Real-time performance metrics

Campaign Overview#

The main content area shows all campaigns with:

Accordion Layout: Expandable campaign rows
Live Progress: Real-time progress bars with streaming updates via Turbo Streams
State Indicators: Color-coded badges (Running=purple, Completed=green, Error=red, Paused=gray, Quarantined=red)
Quarantine Badge: Red "Quarantined" badge displayed on quarantined campaign rows
Attack Stepper: Visual progression through configured attacks (completed, running, pending)
ETA Display: Estimated time to completion based on current hash rate
Recent Cracks Feed: Live feed of newly cracked hashes
Attack Details: Expandable view showing individual attacks with progress and task breakdown
Quarantine Filter: Filter button in toolbar to show only quarantined campaigns

For detailed campaign management documentation, see Campaign Management.

<div class="campaign-row">
 <div class="campaign-header">
  <h3>
   Campaign Name
  </h3>
  <div class="progress-bar">
   <div class="progress-fill" style="width: 45%">
   </div>
  </div>
  <span class="badge badge-running">
   ⚡ 3 attacks / 1 running / ETA 3h
  </span>
 </div>
</div>

Live Toast Notifications#

Real-time notifications appear when hashes are cracked:

Individual Toasts: For single hash cracks
Batch Toasts: For multiple cracks (e.g., "5 new hashes cracked")
Rate Limiting: Prevents notification spam
Contextual Info: Shows plaintext, attack used, timestamp
Auto-dismiss Behavior: Success and info toasts auto-dismiss after 5 seconds; danger/error toasts persist and require manual dismissal to ensure important error messages are not missed

Campaign Management#

Creating a Campaign#

Navigate to "Campaigns" → "New Campaign"

Fill in campaign details:

Name: Descriptive campaign name
Description: Optional description
Hash List: Select existing or create new
Project: Automatically set to current context

Configure initial attacks (optional)
Click "Create Campaign"

Campaign States#

Campaigns have the following states:

Draft: Newly created, not yet started
Active: Running with active attacks
Paused: Temporarily stopped
Completed: All attacks finished
Archived: Completed and archived
Quarantined: Campaign has encountered unrecoverable errors and is excluded from task assignment

Campaign Actions#

Start/Stop: Toggle campaign execution
Add Attack: Configure new attacks within the campaign
Reorder Attacks: Drag-and-drop or use move buttons
Export/Import: Save campaign configuration as JSON
Archive: Mark campaign as completed

Quarantine Actions#

Campaigns may be automatically quarantined when unrecoverable errors occur (such as hash format issues or critical parameter errors). Quarantined campaigns are excluded from task assignment until the quarantine is cleared.

Viewing Quarantine Status#

Quarantine Alert Banner: When viewing a quarantined campaign, a dismissible red alert banner appears at the top of the campaign detail page
Quarantine Reason: The alert displays the specific error message that triggered the quarantine
Campaign Index Badge: Quarantined campaigns show a red "Quarantined" badge in the campaign list
Quarantine Filter: Use the "Quarantined" filter button in the campaigns index toolbar to view only quarantined campaigns

Clearing Quarantine (Admin Only)#

Clear Quarantine Button: Available in the quarantine alert banner on the campaign show page (admin-only)
Manual Clear: Click "Clear Quarantine" to remove the quarantine flag, making the campaign eligible for task assignment again
Automatic Clear: Fixing the underlying issue (such as correcting hash list parameters or attack configuration) automatically clears the quarantine
Confirmation: The system prompts for confirmation before clearing the quarantine

Attack Management#

Attack Types#

CipherSwarm v2 supports multiple attack types with enhanced configuration:

Dictionary Attacks#

Modern dictionary attack editor with:

Wordlist Selection: Searchable dropdown with entry counts
Length Constraints: Min/max password length
Modifiers: User-friendly rule presets
- Change Case (uppercase, lowercase, capitalize, toggle)
- Change Order (duplicate, reverse)
- Substitute Characters (leetspeak, combinator)
Previous Passwords: Dynamic wordlist from project's cracked passwords
Ephemeral Wordlists: Add custom words directly in the editor

<div class="attack-editor">
 <select class="wordlist-selector">
  <option value="rockyou">
   rockyou.txt (14,344,391 words)
  </option>
  <option value="common">
   common-passwords.txt (10,000 words)
  </option>
 </select>
 <div class="modifiers">
  <button class="modifier-btn">
   + Change Case
  </button>
  <button class="modifier-btn">
   + Substitute Characters
  </button>
 </div>
 <div class="ephemeral-wordlist">
  <input placeholder="Add custom word" type="text"/>
  <button>
   +
  </button>
 </div>
</div>

Mask Attacks#

Enhanced mask attack configuration:

Inline Mask Editor: Add/remove mask patterns directly
Real-time Validation: Syntax checking as you type
Ephemeral Masks: Store masks with the attack
Custom Charsets: Define character sets for mask tokens

Brute Force Attacks#

Simplified brute force interface:

Charset Selection: Checkboxes for character types
- Lowercase (a-z)
- Uppercase (A-Z)
- Numbers (0-9)
- Symbols (!@#$...)
- Space ( )
Length Range: Min/max length slider
Auto-generation: Automatically creates appropriate masks

Attack Features#

Real-time Estimation#

Keyspace Calculation: Live updates as you configure
Complexity Score: 1-5 scale based on estimated difficulty
Time Estimates: Projected completion time

Attack Lifecycle#

Edit Protection: Warnings when editing running/completed attacks
State Reset: Editing resets attack to pending state
Progress Tracking: Real-time progress updates via SSE

Hash List Management#

Creating Hash Lists#

Manual Creation: Create empty hash list and add hashes
File Upload: Upload hash files in various formats
Crackable Upload: Automated hash extraction and campaign creation

Hash List Features#

Project Scoping: Hash lists are strictly project-scoped
Search & Filter: Find hashes by value, plaintext, or status
Export Options: TSV and CSV export formats
Status Tracking: Cracked vs uncracked hash counts

Upload Progress Feedback#

When uploading files through the web interface, a progress bar provides visual feedback during the upload process. Uploads use the tus resumable upload protocol, which supports files of any size (including 100+ GB) with automatic resume on network failure.

Upload Progress#

File uploads display a progress bar with percentage indicator:

"Uploading... X%" — displays during file transfer with real-time progress
"Upload complete. Ready to submit." — file uploaded, form ready for submission
Files are uploaded in 50 MB chunks for reliable transfer of large files
If the connection drops, the upload resumes automatically where it left off

Background Verification#

After upload completes, a background job (VerifyChecksumJob) computes a server-side checksum for integrity verification:

Resources show checksum_verified: false until verification completes
On success, checksum_verified is set to true and the checksum is stored
On failure (checksum mismatch), the resource remains checksum_verified: false and an error is logged — the resource can still be used but re-uploading is recommended
Verification status is visible in the resource detail view

Error Handling#

If an upload error occurs:

The progress bar is hidden
An inline error message appears with actionable guidance
The submit button is re-enabled to allow retry
Tus protocol automatically retries transient network errors before surfacing the failure

Affected Upload Forms#

This progress feedback appears when uploading:

Mask Lists: Mask pattern file uploads
Attack Resources: Word lists and rule lists

<div class="progress mt-2 d-none" data-direct-upload-target="progress">
 <div aria-valuemax="100" aria-valuemin="0" aria-valuenow="0" class="progress-bar progress-bar-striped progress-bar-animated" role="progressbar" style="width: 0%">
 </div>
</div>
<p class="form-text mt-1" data-direct-upload-target="status">
</p>

Crackable Uploads#

Streamlined workflow for non-technical users:

Supported Formats#

File Uploads: .zip, .pdf, .docx, .kdbx files
Text Input: Paste hashes from various sources
Shadow Files: Linux /etc/shadow format
NTLM Dumps: Windows hash dumps

Upload Process#

Upload/Paste: Drag files or paste hash text
Auto-detection: System detects hash types automatically
Preview: Review detected hashes and types
Confirmation: Approve campaign creation
Processing: Background processing with status updates

<div class="upload-area">
 <div class="drop-zone">
  <p>
   Drag files here or click to browse
  </p>
  <input accept=".zip,.pdf,.txt" type="file"/>
 </div>
 <div class="text-input">
  <textarea placeholder="Or paste hashes here..."></textarea>
 </div>
</div>

Processing Status#

Real-time Updates: Live status via streaming
Error Reporting: Line-by-line error details
Preview Results: Sample of detected hashes
Auto-campaign: Automatic campaign and attack creation

Resource Management#

Resource Types#

CipherSwarm manages several resource types:

Wordlists: Dictionary files for attacks
Rule Lists: Hashcat rule files
Mask Lists: Collections of mask patterns
Charsets: Custom character set definitions

Resource Features#

Upload & Management#

Presigned URLs: Secure direct-to-storage uploads
Metadata Tracking: Size, line count, usage statistics
Project Linking: Resources can be project-specific or global

Checksum Verification Monitoring (Admin Only)#

After uploading wordlists, rule lists, or mask lists through the admin interface, the system performs background checksum verification to ensure file integrity. Administrators can monitor this process:

Verification Status Field: The checksum_verified field appears in the index and detail views for WordLists, RuleLists, and MaskLists in the admin dashboard
- true: File uploaded successfully and checksum verified
- false: Verification pending or failed
Unverified Filter: Click the "unverified" collection filter in any resource dashboard to show only resources with pending or failed verification
Automatic Recovery: Resources stuck in unverified state are automatically re-queued for verification on a configurable sweep interval (default: every 6 hours), so transient failures (I/O errors, temporary storage issues) should self-resolve
Manual Intervention: If a resource remains unverified beyond the configured retry threshold and at least one subsequent requeue cycle, check system logs for persistent errors and consider re-uploading the file

This visibility helps administrators identify and resolve issues with uploaded resources in air-gapped deployments where external monitoring is unavailable.

Line-Level Editing#

For smaller resources (under configured size limits):

Inline Editor: Edit resources directly in browser
Line Validation: Real-time syntax checking
Add/Remove Lines: Interactive line management
Batch Operations: Multiple line edits

<div class="resource-editor">
 <div class="line-editor">
  <input type="text" value="?d?d?d?d"/>
  <button class="delete-line">
   ×
  </button>
 </div>
 <button class="add-line">
  + Add Line
 </button>
</div>

Agent Management#

Agent Overview#

The Agent Status Sheet (accessible from dashboard) shows:

Agent Cards: Individual agent status with real-time status badges (Active=green, Pending=gray, Stopped=gray, Error=red)
Performance Metrics: Current hash rates, 8-hour trend charts, and performance history
Task Assignment: Current campaign/attack assignments with live progress
Hardware Status: Temperature, utilization, and error count badges
Error Monitoring: Error badges on agent cards with quick access to error details

For comprehensive agent monitoring documentation, see Agent Setup - Agent Monitoring.

Agent Registration#

Administrators can register new agents:

Click "Register Agent" in agent management
Enter agent label and description
Select project assignments
Copy the generated token (shown only once)
Configure agent with token

Agent Configuration#

Basic Settings#

Display Name: Custom label or hostname fallback
Enable/Disable: Toggle agent availability
Update Interval: Heartbeat frequency (1-15 seconds)
Project Assignment: Multi-project access control

Hardware Management#

Device Toggles: Enable/disable individual GPUs/CPUs
Backend Selection: CUDA, OpenCL, HIP, Metal
Temperature Limits: Abort thresholds (default 90°C)
Performance Monitoring: Real-time utilization tracking

Capabilities#

Benchmark Results: Hash type performance data
Device Information: Hardware specifications
Performance History: 8-hour performance trends

Live Updates & Real-time Features#

Real-time Streaming#

CipherSwarm v2 uses streaming connections for real-time updates:

Campaign Feed: Attack progress and state changes
Agent Feed: Agent status and performance updates
Toast Feed: New crack results and notifications

Connection Status#

Live Indicator: Shows streaming connection status
Fallback Polling: Automatic fallback if streaming unavailable
Stale Data Warning: Alerts when data is >30 seconds old

Settings & Administration#

User Management (Admin Only)#

User Creation: Add new users with role assignment
Role Management: Admin, User, Power User roles
Project Assignment: Multi-project user access
Password Policies: Complexity requirements and rotation

System Health Dashboard#

CipherSwarm V2 includes a dedicated System Health Dashboard accessible from Admin > System Health. This provides real-time monitoring of all critical infrastructure components.

Service Status Cards#

The health dashboard displays four service status cards:

PostgreSQL
- Connection status (connected/disconnected)
- Connection pool utilization
- Response time metrics
- Database version and configuration
Redis
- Connection status
- Memory usage and limits
- Connected client count
- Used for caching, sessions, and Action Cable
MinIO (Object Storage)
- Connection status
- Storage capacity and available space
- Bucket accessibility
- Used for wordlists, rules, hash lists, and other file storage
Application
- Running status (running/degraded/error)
- Uptime since last restart
- Memory usage
- Sidekiq job queue depth
- Ruby and Rails version information
- Boot time

Real-Time Health Monitoring#

Auto-refresh: Health data refreshes automatically at configurable intervals
Manual Refresh: Click the refresh button for immediate status updates
Diagnostics Detail: Each card expands to show detailed diagnostic information
Error Display: When a service is unhealthy, the specific error message is shown

Using the Health Dashboard#

The health dashboard is the first place to check when issues arise:

All services green: System is healthy, issue is likely user-specific
PostgreSQL red: Database connectivity lost, all operations affected
Redis red: Live updates and caching disabled, sessions may expire
MinIO red: File uploads and downloads will fail, agents cannot get resources
Application degraded: Check memory and job queue for bottlenecks

Using the Dashboard for Troubleshooting:

The System Health Dashboard is your first stop when agents report connection issues or circuit breaker activation. If agent logs show "circuit breaker open" messages, check this dashboard to verify all services are operational. Green indicators mean services are healthy; red indicators require immediate attention. For detailed troubleshooting of agent network issues, see Agent Network and Connection Issues.

Legacy Health Overview#

The dashboard also shows aggregate health metrics:

Agent Status: Online/offline counts
System Performance: Database latency, task backlog
Error Monitoring: Recent errors and warnings

Performance Settings#

# Task Distribution:
max_tasks_per_agent: 5
adaptive_distribution: true

# Resource Management:
cache_wordlists: true
cleanup_interval: 3600

# Upload Limits:
max_file_size: 100MB
allowed_extensions: [.txt, .zip, .pdf]

Keyboard Shortcuts#

Action	Shortcut
New Campaign	`Ctrl+N`
Refresh	`F5`
Search	`Ctrl+/`
Toggle Dark Mode	`Ctrl+D`
Help	`?`

Dark Mode & Theming#

CipherSwarm v2 uses a dark-first design with the Catppuccin Macchiato theme and DarkViolet accents:

Theme Palette#

Catppuccin Macchiato: Professional dark color palette designed for extended viewing
Primary Accent: DarkViolet (#a855f7) for interactive elements and primary actions
Surface Hierarchy: Layered depth using Catppuccin's surface system
- Crust (navbar, darkest)
- Mantle (sidebar)
- Base (main content background)
- Surface0 (cards, inputs, elevated elements)

Typography#

CipherSwarm uses self-hosted fonts for air-gapped deployment compatibility:

Space Grotesk (variable, 300-700): Geometric headings with technical character
IBM Plex Sans (400, 500, 600, 700): Technical heritage body text for readability
JetBrains Mono (variable, 100-800): Monospace for hashes, masks, and technical data

All fonts load via font-display: swap with system fallbacks to prevent blocking.

Theme Control#

System Preference Detection: Automatically respects prefers-color-scheme
Manual Toggle: Theme switcher available in navigation
Persistent Setting: User preference stored across sessions

<button class="theme-toggle" onclick="toggleTheme()">
 <svg class="sun-icon hidden dark:block">
  ...
 </svg>
 <svg class="moon-icon block dark:hidden">
  ...
 </svg>
</button>

Accessibility#

CipherSwarm v2 is designed to meet WCAG 2.1 AA compliance standards for accessibility:

Skip Links: Press Tab at page load to reveal "Skip to main content" link, bypassing navigation to reach primary content
Full Keyboard Support: All interactive elements accessible via keyboard (Tab, Enter, Space)
Tab Panels: Use arrow keys (Left/Right) to navigate between tabs, Home/End to jump to first/last tab
Dropdown Menus: Navigate with arrow keys, close with Escape

Semantic HTML & ARIA#

Proper Landmarks: <nav>, <main>, <aside> elements structure page regions
ARIA Labels: Navigation regions and interactive elements include descriptive aria-label attributes
Button Semantics: Navbar dropdowns use <button type="button"> instead of anchor links for correct screen reader behavior
Focus Management: Visible focus indicators on all interactive elements

Visual Accessibility#

Contrast Ratios: All text meets WCAG AA 4.5:1 minimum contrast requirements
Semantic Colors: Bootstrap utility classes (e.g., text-body-secondary) ensure theme-aware accessible contrast
No Inline Sizing: CSS classes replace inline style="font-size:..." attributes for consistent scaling
Motion Preferences: Respects prefers-reduced-motion system setting

Testing#

Accessibility features are verified through:

Automated Testing: Playwright browser automation for keyboard navigation flows
Manual Verification: Screen reader testing and keyboard-only navigation
Component Tests: Focus management and ARIA attribute specs

Troubleshooting#

Common Issues#

Streaming Connection Failed
- Check browser console for errors
- Verify network connectivity
- System falls back to polling automatically
Project Context Issues
- Ensure you have access to the selected project
- Try switching projects and back
- Contact admin for project access
Upload Processing Stuck
- Check upload status endpoint
- Review error logs for failed lines
- Verify file format compatibility
- If the progress bar appears stuck during the "Preparing" phase for very large files, this may indicate a browser timeout. Contact your administrator about the large file threshold setting (default 1 GB)
Agent Not Appearing
- Verify agent token is correct
- Check agent logs for connection errors
- Ensure agent has project access
Agent Circuit Breaker Activation
- Symptom: Agent logs show "circuit breaker open" messages
- Meaning: The agent is protecting itself from repeated server connection failures
- Check: Verify all services are green on the System Health Dashboard
- Action: The agent will automatically attempt recovery after 60 seconds. If the circuit remains open for more than 5 minutes, investigate server availability and network connectivity.
- Details: See Circuit Breaker Recovery

For comprehensive agent troubleshooting including network resilience, automatic retry behavior, and detailed recovery procedures, see the Agent Troubleshooting Guide.

Performance Tips#

Use targeted wordlists for faster attacks
Monitor agent temperatures to prevent throttling
Batch similar attacks in campaigns for efficiency
Regular cleanup of completed campaigns and unused resources