CipherSwarm Documentation#

Welcome to the CipherSwarm documentation. This directory contains comprehensive documentation for the CipherSwarm distributed password cracking platform.

📚 Documentation Structure#

Getting Started#

• Quick Start Guide - Get CipherSwarm running quickly
• User Guide - Comprehensive user documentation

V2 Upgrade Information#

• V2 Upgrade Overview - Complete overview of the V2 upgrade
• Implementation Plan - Detailed implementation roadmap

User Guides#

• User Guide Index - Complete table of contents and quick navigation
• Getting Started - First-time setup, dashboard overview, and your first campaign
• Campaign Management - Creating, monitoring, and managing campaigns
• Attack Configuration - Configuring dictionary, mask, brute force, and hybrid attacks
• Understanding Results - Viewing, interpreting, and exporting cracking results
• Agent Setup - Installing, registering, and configuring agents
• Agent Troubleshooting - Comprehensive agent troubleshooting including circuit breaker recovery, HTTP resilience settings, task acceptance failure handling, monitoring metrics, and detailed recovery procedures
• Resource Management - Managing wordlists, rules, masks, and charsets
• Web Interface - Complete web interface reference
• Troubleshooting - System diagnostics, agent network troubleshooting (including circuit breaker behavior, automatic retry logic, and configurable timeouts), common issues, and troubleshooting workflows
• Common Issues - Quick fixes for frequently encountered problems
• FAQ - Frequently asked questions
• Performance Optimization - Hardware tuning, attack strategies, and system optimization
• Air-Gapped Deployment - Deploying in isolated environments

Deployment Guides#

• Environment Variables Reference - Comprehensive guide to all environment variables
• Air-Gapped Deployment - Deploying in isolated environments
• Production Load Balancing - Nginx load balancing with horizontal web scaling
• Docker Storage and /tmp Management - Preventing Sidekiq filesystem exhaustion with tmpfs mounts
• Connection Pool Sizing - PostgreSQL connection pool formula and monitoring
• Monitoring Setup - Prometheus + Grafana monitoring stack for air-gapped production

Development Documentation#

• Style Guide - Code style and conventions
• User Journey Flowchart - User workflow visualization

API Documentation#

• Agent API Reference - Agent API reference including client resilience recommendations
• Agent API Complete Reference - Full API documentation with examples

The API documentation is automatically generated using Rswag from RSpec request tests. Use the following commands to generate and update API documentation:

• just docs-api - Generate basic Swagger/OpenAPI documentation
• just docs-api-full - Generate comprehensive documentation with examples
• just docs-generate - Run integration tests and generate API docs

Architecture Documentation#

• Architecture Diagrams - System, domain, and sequence diagrams (Mermaid)
• Architecture Analysis - Detailed architecture review and recommendations

Development Documentation#

• Developer Guide - Comprehensive developer onboarding guide
• Style Guide - Code style and conventions
• Logging Guide - Logging patterns and best practices
• User Journey Flowchart - User workflow visualization

Quick Reference#

• Quick Reference Card - Commands, patterns, and common operations

Technical Reference#

• Current Hashcat Hash Modes - Supported hash types

🔄 V2 Upgrade Status#

CipherSwarm is currently undergoing a comprehensive V2 upgrade. The upgrade maintains the existing Ruby on Rails + Hotwire technology stack while delivering enhanced user experiences, improved real-time capabilities, and better operational management.

Key V2 Improvements#

• Real-time Operations Dashboard with live agent monitoring
• Enhanced Campaign Management with guided wizards and DAG support
• Advanced Agent Management with intelligent task distribution
• Comprehensive Reporting & Analytics for security insights
• Team Collaboration Features with activity feeds and notifications
• Production-Ready Deployment with containerization, nginx load balancing, horizontal scaling, and monitoring

For complete details, see the V2 Upgrade Overview.

🎯 Target Audience#

CipherSwarm is designed for:

• Red Team Operators: Efficient campaign creation and attack orchestration
• Blue Team Analysts: Comprehensive reporting and password pattern analysis
• Infrastructure Administrators: Intelligent resource management and system monitoring
• Project Managers: Team coordination and project oversight

🏗️ Architecture Overview#

CipherSwarm uses a modern Rails 8.1+ architecture with:

• Web Interface Layer: Controllers, Views, and ViewComponents using Hotwire
• Service Layer: Business logic, state management, and validation services
• Model Layer: ActiveRecord models with associations and validations
• Data Layer: PostgreSQL 17+ database with Redis for caching and background jobs

Key Technologies#

• Ruby 3.4.5 with Rails 8.1+
• PostgreSQL 17+ for primary data storage
• Redis 7.2+ for caching, Action Cable, and Sidekiq job processing
• Hotwire (Turbo + Stimulus) for interactive frontend
• ViewComponent for reusable UI components
• Sidekiq for background job processing

📖 Additional Resources#

• Contributing Guidelines - How to contribute to the project
• Code of Conduct - Community guidelines
• License - Project license information
• Changelog - Version history and changes

🆘 Getting Help#

If you need help with CipherSwarm:

1. Check the FAQ for common questions
2. Review the Common Issues troubleshooting guide
3. Search existing GitHub Issues
4. Create a new issue if your problem isn't covered

📝 Contributing to Documentation#

We welcome contributions to improve the documentation! Please see the Contributing Guidelines for information on how to contribute.

When contributing documentation:

• Follow the existing structure and style
• Use clear, concise language
• Include examples where helpful
• Test any code examples
• Update the table of contents if adding new sections