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
  • Table of Contents
  • Authentication & Project Context
  • Dashboard Overview
  • Campaign Management
  • Attack Management
  • Hash List Management
  • Resource Management
  • Agent Management
  • Live Updates & Real-time Features
  • Settings & Administration
  • Keyboard Shortcuts
  • Dark Mode & Theming
  • Accessibility
  • Troubleshooting

Authentication & Project Context#

Login Process#

1. Navigate to the CipherSwarm web interface
2. Enter your email and password
3. Click "Sign In"
4. 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:

1. Active Agents

   • Shows online agents vs total registered
   • Click to open Agent Status Sheet
   • Real-time updates via streaming

2. Running Tasks

   • Active campaigns and task breakdown
   • Percentage of running vs completed tasks
   • Links to campaign details

3. Recently Cracked Hashes

   • Hashes cracked in the last 24 hours
   • Scoped to accessible projects
   • Links to results view

4. 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#

1. Navigate to "Campaigns" → "New Campaign"

2. Fill in campaign details:

   ⧉

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

3. Configure initial attacks (optional)

4. 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#

1. Manual Creation: Create empty hash list and add hashes
2. File Upload: Upload hash files in various formats
3. 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#

1. Upload/Paste: Drag files or paste hash text
2. Auto-detection: System detects hash types automatically
3. Preview: Review detected hashes and types
4. Confirmation: Approve campaign creation
5. 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:

1. Click "Register Agent" in agent management
2. Enter agent label and description
3. Select project assignments
4. Copy the generated token (shown only once)
5. 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:

1. PostgreSQL

   • Connection status (connected/disconnected)
   • Connection pool utilization
   • Response time metrics
   • Database version and configuration

2. Redis

   • Connection status
   • Memory usage and limits
   • Connected client count
   • Used for caching, sessions, and Action Cable

3. MinIO (Object Storage)

   • Connection status
   • Storage capacity and available space
   • Bucket accessibility
   • Used for wordlists, rules, hash lists, and other file storage

4. 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#

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:

Keyboard Navigation#

• 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#

1. Streaming Connection Failed

   • Check browser console for errors
   • Verify network connectivity
   • System falls back to polling automatically

2. Project Context Issues

   • Ensure you have access to the selected project
   • Try switching projects and back
   • Contact admin for project access

3. 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)

4. Agent Not Appearing

   • Verify agent token is correct
   • Check agent logs for connection errors
   • Ensure agent has project access

5. 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