Frequently Asked Questions (FAQ)#

This FAQ covers common questions about CipherSwarm v2.

Table of Contents#

Frequently Asked Questions (FAQ)

General Questions#

What's new in CipherSwarm v2?#

CipherSwarm v2 introduces several major improvements:

Project-based Organization: Multi-tenant architecture with project isolation
Enhanced Authentication: JWT-based authentication with role-based access control
Modern Web Interface: Complete UI redesign with real-time updates
Advanced Attack Types: New brute force attacks and enhanced dictionary/mask attacks
Resource Management: Line-level editing, ephemeral resources, and MinIO integration
Live Updates: Server-Sent Events (SSE) for real-time dashboard updates
Hash List Management: Improved hash management with crackable uploads
Agent Enhancements: Better hardware management and performance monitoring

Is CipherSwarm v2 compatible with v1 agents?#

Yes, CipherSwarm v2 maintains backward compatibility with v1 agents through the Agent API v1. However, some new features (like enhanced hardware management) require agent updates.

How do I migrate from CipherSwarm v1?#

Migration involves:

Data Migration: Existing campaigns, attacks, and resources are preserved
User Accounts: User accounts are migrated with appropriate project assignments
Agent Re-registration: Agents need new tokens and may require configuration updates
Project Assignment: Existing data is assigned to a default project

Contact your administrator for migration assistance.

Authentication and Access#

How do I log into CipherSwarm v2?#

Navigate to the CipherSwarm web interface
Enter your username and password
Select your active project (if assigned to multiple projects)
Access the dashboard and features

What are the different user roles?#

CipherSwarm v2 has three user roles:

User: Basic access, can view campaigns and results
Power User: Can create and manage campaigns, attacks, and resources
Admin: Full system access, user management, and system configuration

How do projects work?#

Projects provide multi-tenant organization:

Isolation: Each project has separate campaigns, attacks, hash lists, and resources
Access Control: Users are assigned to specific projects
Security: No data sharing between projects without explicit export
Management: Administrators control project membership and permissions

Can I access multiple projects?#

Yes, users can be assigned to multiple projects. Use the project selector in the header to switch between projects. Your current project context determines what data you can see and modify.

I can't see any campaigns or resources. What's wrong?#

This usually indicates a project access issue:

Check Project Assignment: Verify you're assigned to projects with data
Contact Administrator: Request access to appropriate projects
Verify Project Context: Ensure you've selected the correct project
Check Role: Verify you have appropriate permissions

Agents and Hardware#

How do I register a new agent?#

Agent registration is now done through the web interface:

Administrator Access: Only administrators can register agents
Web Registration: Use the "Register New Agent" button in the Agents section
Project Assignment: Select which projects the agent can access
Token Generation: Copy the generated token (shown only once)
Agent Configuration: Configure the agent with the token and restart

Why isn't my agent appearing online?#

Common causes:

Authentication Issues: Verify the agent token is correct and not expired
Network Connectivity: Ensure the agent can reach the server via HTTPS
Project Assignment: Verify the agent is assigned to at least one project
Configuration Errors: Check agent configuration and logs

How do I manage agent hardware settings?#

CipherSwarm v2 provides enhanced hardware management:

Device Toggles: Enable/disable individual GPUs and CPUs
Backend Selection: Choose CUDA, OpenCL, HIP, or Metal backends
Temperature Limits: Set thermal abort thresholds
Workload Settings: Adjust GPU utilization levels (1-4)
Performance Monitoring: View real-time performance metrics

Can agents work on multiple projects simultaneously?#

Yes, agents can be assigned to multiple projects and will receive tasks from any assigned project. Task distribution is automatic based on agent capabilities and project priorities.

How do I benchmark agent performance?#

Automatic Benchmarks: Agents automatically benchmark on first connection
Manual Triggers: Use the "Trigger Benchmark" button in agent details
Performance Monitoring: View live performance charts and metrics
Capabilities View: See detailed hash type performance data

Campaigns and Attacks#

What attack types are available?#

CipherSwarm v2 supports:

Dictionary Attacks: Wordlist-based attacks with optional rules
Mask Attacks: Pattern-based attacks using character masks
Brute Force Attacks: Exhaustive attacks with configurable character sets
Hybrid Attacks: Combinations of dictionary and mask attacks

How do I create a campaign?#

Navigate to Campaigns: Click "Campaigns" in the main navigation
Create Campaign: Click "New Campaign" button
Configure Details: Set name, description, and select hash list
Add Attacks: Configure one or more attacks for the campaign
Review and Start: Review configuration and start the campaign

What are ephemeral resources?#

Ephemeral resources are temporary resources created within attacks:

Lifecycle: Created with attack, deleted when attack is removed
Usage: Single-attack only, not reusable across campaigns
Types: Custom wordlists, mask lists, and character sets
Storage: Stored in database, not in external storage
Export: Included inline when exporting attack configurations

How do I use previous passwords in attacks?#

CipherSwarm v2 can automatically generate wordlists from previously cracked passwords:

Dictionary Attack: Select "Use Previous Passwords" option
Automatic Generation: System creates wordlist from project's cracked passwords
Dynamic Updates: Wordlist updates as new passwords are cracked
Project Scope: Only includes passwords from the current project

Can I edit attacks while they're running?#

Yes, but with restrictions:

Warning Prompt: System warns about resetting attack progress
State Reset: Editing resets attack to "pending" state
Confirmation Required: Must confirm understanding of impact
Resource Updates: Linked resource changes trigger automatic restarts

Resources and Storage#

How do I upload resources?#

Navigate to Resources: Click "Resources" in main navigation
Upload Button: Click "Upload Resource" or drag-and-drop files
File Selection: Choose file and resource type (auto-detected)
Configuration: Set name, description, and project scope
Validation: System validates format and content

What file formats are supported?#

Wordlists: .txt, .lst, .dict (UTF-8 or ASCII)
Rule Lists: .rule, .rules (ASCII, hashcat syntax)
Mask Lists: .mask, .masks (ASCII, hashcat mask syntax)
Charsets: .charset, .hchr (ASCII, custom charset definitions)

Can I edit resources online?#

Yes, for smaller resources:

Size Limits: Resources under 5MB or 10,000 lines
Line Editing: Add, edit, or remove individual lines
Real-time Validation: Syntax checking for rules and masks
Larger Files: Must download, edit offline, and reupload

How does project scoping work for resources?#

Resources can be:

Project-Specific: Only accessible within assigned projects
Global: Available to all projects (admin-created only)
Automatic Assignment: Based on user's current project context

What happens to resources when I delete an attack?#

Ephemeral Resources: Deleted automatically with the attack
Regular Resources: Unlinked but preserved for reuse
Usage Tracking: System tracks which resources are in use

Live Updates and Real-time Features#

How do live updates work?#

CipherSwarm v2 uses Server-Sent Events (SSE) for real-time updates:

Automatic Updates: Dashboard and campaign views update automatically
No Refresh Needed: Changes appear without page reloads
Selective Updates: Only relevant data is refreshed
Browser Support: Works with modern browsers supporting EventSource

Why aren't my live updates working?#

Common issues:

Browser Compatibility: Ensure browser supports EventSource
Network Issues: Check for proxy/firewall blocking SSE connections
Connection Drops: Verify stable network connectivity
JavaScript Errors: Check browser console for errors

Can I disable live updates?#

Yes, live updates can be disabled:

Per-View Basis: Toggle updates for specific views
Browser Setting: Disable in browser preferences
Manual Refresh: Use refresh buttons when updates are disabled

Hash Lists and Crackable Uploads#

How do I create a hash list?#

Manual Creation: Create empty hash list and add hashes individually
File Upload: Upload file containing hashes (various formats supported)
Crackable Upload: Upload files or paste hashes for automatic processing
Import: Import from other systems or previous campaigns

What is the crackable upload feature?#

Crackable uploads automate hash extraction and campaign creation:

File Support: Upload .zip, .pdf, .docx, .kdbx files for hash extraction
Text Parsing: Paste raw hash data from various sources
Auto-Detection: Automatically detect hash types and formats
Campaign Generation: Create campaigns with appropriate attacks automatically

How does hash type detection work?#

CipherSwarm v2 includes intelligent hash type detection:

Pattern Matching: Analyzes hash format and length
Confidence Scoring: Provides confidence levels for detected types
Manual Override: Allows manual hash type selection
Validation: Verifies compatibility with hashcat

Can I edit hash lists after creation?#

Yes, hash lists support various editing operations:

Add Hashes: Add individual hashes or import additional files
Remove Hashes: Delete specific hashes or clear entire lists
Export: Export to various formats (TSV, CSV, hashcat format)
Search and Filter: Find specific hashes or filter by status

Performance and Optimization#

How can I improve cracking performance?#

Hardware Optimization:
- Use high-end GPUs with sufficient memory
- Ensure proper cooling and power supply
- Optimize agent workload settings
Attack Strategy:
- Start with targeted wordlists and rules
- Use complexity scoring to prioritize attacks
- Leverage previous passwords for targeted attacks
Resource Management:
- Use appropriate resource sizes
- Cache frequently used resources
- Monitor agent performance and adjust settings

Why are my attacks running slowly?#

Common causes:

Large Keyspace: Attacks with huge keyspaces take longer
Hardware Limitations: Insufficient GPU memory or processing power
Network Issues: Slow resource downloads or connectivity problems
Configuration: Suboptimal workload or performance settings

How do I monitor system performance?#

CipherSwarm v2 provides comprehensive monitoring:

Dashboard Metrics: Real-time system overview
Agent Performance: Individual agent performance charts
Campaign Progress: Detailed progress tracking and estimates
Health Status: System component health monitoring

Security and Best Practices#

How secure is CipherSwarm v2?#

CipherSwarm v2 includes multiple security features:

HTTPS Only: All communication encrypted in transit
JWT Authentication: Secure token-based authentication
Project Isolation: Strict data separation between projects
Role-Based Access: Granular permission controls
Audit Logging: Comprehensive activity logging

What are the password requirements?#

Password requirements are configurable but typically include:

Minimum Length: 8-12 characters
Complexity: Mix of uppercase, lowercase, numbers, symbols
Rotation: Regular password changes recommended
Uniqueness: Cannot reuse recent passwords

How should I organize projects?#

Best practices for project organization:

Purpose-Based: Organize by engagement, client, or objective
Security Boundaries: Separate sensitive and non-sensitive data
Team Access: Assign users based on need-to-know
Resource Sharing: Use global resources for common tools

What should I do if I suspect a security issue?#

Report Immediately: Contact security team or administrator
Document Evidence: Preserve logs and evidence
Isolate Systems: Disconnect affected systems if necessary
Don't Investigate: Let security professionals handle the investigation

Troubleshooting#

Where can I find logs?#

Log locations vary by component:

Web Interface: Browser developer console
Agent Logs: journalctl -u CipherSwarm-agent or /var/log/CipherSwarm/
Server Logs: Contact administrator for access
Application Logs: Available through admin interface

How do I report bugs or issues?#

Collect Information: Gather error messages, logs, and reproduction steps
Check Documentation: Review troubleshooting guide first
Contact Support: Use appropriate support channels
Provide Details: Include environment details and exact error messages

What information should I include in bug reports?#

Essential information:

CipherSwarm Version: System version and build information
Environment: Browser, OS, agent configuration
Error Messages: Exact error text and codes
Reproduction Steps: How to reproduce the issue
Expected Behavior: What should have happened
Logs: Relevant log entries and timestamps

What does "circuit breaker open" mean in my agent logs?#

The circuit breaker is a protective mechanism that activates after repeated connection failures (default: 5 consecutive failures) to prevent cascading failures when the server is unavailable. This is not an error - it's the agent protecting itself. The circuit breaker will automatically attempt recovery after 60 seconds by default. No agent restart is needed. Check server availability and network connectivity if the circuit remains open for more than 5 minutes. See Circuit Breaker Recovery for details.

Why does my agent keep retrying failed requests?#

The agent includes automatic retry logic with exponential backoff for transient network failures and server errors (5xx responses). Failed requests are retried up to 3 times by default with increasing delays (1s, 2s, 4s, ...) capped at 30 seconds. This handles temporary network disruptions automatically without manual intervention. See Agent Network and Connection Issues for more information.

Should I restart my agent when I see "All API request attempts failed"?#

No, usually not. This message indicates that all retry attempts were exhausted, often due to temporary network issues or server downtime. If this happens repeatedly, the circuit breaker will activate and the agent will automatically attempt recovery. Check network connectivity and server health first. The agent only needs restarting if configuration changes are required. See When to Restart an Agent for guidance.

Integration and API#

Does CipherSwarm v2 have an API?#

Yes, CipherSwarm v2 provides multiple APIs:

Agent API v1: For CipherSwarm agents (backward compatible)
Web API v1: For web interface functionality
Control API v1: For command-line tools and automation (partially implemented)
Future APIs: Agent API v2 planned for enhanced features

Can I automate CipherSwarm operations?#

Yes, through various methods:

Control API: RESTful API for automation scripts (basic functionality available)
Command-line Tools: CLI tools for common operations (planned)
Webhooks: Event notifications for external systems (planned)
Export/Import: JSON-based configuration sharing

How do I integrate with external tools?#

Integration options:

API Access: Use RESTful APIs for data access
Export Formats: Export results in various formats
Webhook Notifications: Receive real-time event notifications (planned)
Custom Scripts: Develop custom automation scripts

What Control API features are currently available?#

The Control API is partially implemented with:

Campaign Listing: List campaigns with filtering and pagination
Hash Analysis: Hash type detection and guessing
API Key Authentication: Bearer token authentication for automation
RFC9457 Error Format: Standardized error responses

Note: Full Control API functionality including campaign management, batch operations, and CLI tools are planned for future releases.

Getting Help#

Where can I find more documentation?#

User Guides: Comprehensive guides for all features
API Documentation: Complete API reference
Troubleshooting: Common issues and solutions
Best Practices: Optimization and security guidelines

How do I contact support?#

Support channels depend on your deployment:

Administrator: Contact your local CipherSwarm administrator
Documentation: Check user guides and troubleshooting
Community: Participate in user forums or communities
Professional Support: Contact vendor for commercial support

What training is available?#

Training options may include:

Documentation: Self-paced learning through user guides
Video Tutorials: Step-by-step video demonstrations
Workshops: Hands-on training sessions
Certification: Professional certification programs

For additional information, see:

Web Interface Guide - Complete UI documentation
Agent Setup Guide - Agent installation and configuration
Attack Configuration Guide - Attack types and configuration
Resource Management Guide - Resource handling
Troubleshooting Guide - Common issues and solutions