CipherSwarm V2 Upgrade Overview#

CipherSwarm V2 Upgrade Overview

Introduction#

CipherSwarm V2 represents a comprehensive upgrade that transforms the platform from a functional tool into a modern, user-friendly distributed password cracking platform. The upgrade maintains the existing Ruby on Rails + Hotwire technology stack while delivering enhanced user experiences, improved real-time capabilities, and better operational management.

Upgrade Philosophy#

The V2 upgrade embodies a fundamental shift in approach:

From Tool to Platform: Evolving from basic functionality to comprehensive workflow management
From Manual to Guided: Replacing complex forms with intuitive wizards and workflows
From Static to Real-time: Implementing live monitoring and instant feedback
From Single-user to Collaborative: Adding multi-user coordination and team features
From Basic to Enterprise: Scaling to production-ready deployment and operations

Target Users & Personas#

Red Team Operators#

Primary Need: Efficient campaign creation and attack orchestration
Key Features: Campaign wizard, DAG-based attack dependencies, real-time progress monitoring
Pain Points Addressed: Complex attack configuration, poor campaign visibility

Blue Team Analysts#

Primary Need: Comprehensive reporting and password pattern analysis
Key Features: Advanced analytics, trend visualization, automated reporting
Pain Points Addressed: Limited analysis capabilities, manual report generation

Infrastructure Administrators#

Primary Need: Intelligent resource management and system monitoring
Key Features: Agent capability detection, task distribution optimization, system metrics
Pain Points Addressed: Manual task assignment, poor resource utilization

Project Managers#

Primary Need: Team coordination and project oversight
Key Features: Activity feeds, collaboration tools, project context management
Pain Points Addressed: Limited visibility into team activities, poor coordination tools

Core Requirements#

1. Enhanced Authentication & Project Context Management#

Objective: Seamless project switching with role-based access controls

Key Capabilities:

Project selector interface with session persistence
Persona-specific permissions (Red Team, Blue Team, Infrastructure, Project Manager)
Project-scoped data filtering throughout the application
Real-time UI updates without page reloads

Technical Implementation:

ProjectContextService for session-based project management
Enhanced CanCanCan abilities with persona support
Turbo-powered project switching interface
Project-scoped authorization throughout controllers

2. Real-Time Operations Dashboard#

Objective: Live monitoring of agents, campaigns, and system health

Key Capabilities:

Real-time agent health status with 5-second update frequency
Live campaign progress with streaming crack results
8-hour rolling hash rate trends and performance metrics
Personalized updates based on project context

Technical Implementation:

ActionCable channels with Solid Cable backend
Turbo Streams for live DOM updates
Background jobs for metrics collection and aggregation
Throttled updates to prevent performance degradation

3. Enhanced Campaign Management with DAG Support#

Objective: Guided campaign creation with intelligent attack orchestration

Key Capabilities:

Multi-step campaign wizard with progress tracking
Direct file uploads with ActiveStorage integration
DAG-based attack dependencies with visual editor
Drag-and-drop attack reordering and validation

Technical Implementation:

CampaignWizardService for step-by-step workflow
AttackDependency model for DAG relationships
Stimulus controllers for interactive UI elements
Comprehensive validation and error handling

4. Advanced Agent Management & Task Distribution#

Objective: Intelligent resource utilization and automated task assignment

Key Capabilities:

Agent capability detection and hardware profiling
Intelligent task matching based on agent capabilities
Priority-based scheduling with automatic reassignment
Real-time performance monitoring and optimization

Technical Implementation:

Enhanced agent API with capability reporting
TaskSchedulingService for intelligent distribution
Agent performance tracking and analytics
Automated task reassignment for failed agents

5. Comprehensive Reporting & Analytics#

Objective: Deep insights into password patterns and cracking effectiveness

Key Capabilities:

Password pattern analysis with security insights
Historical trend visualization with configurable time ranges
Multi-format exports (CSV, JSON, PDF)
Automated report generation and delivery

Technical Implementation:

ReportingService for data analysis and aggregation
Background jobs for scheduled report generation
Chart.js integration for data visualization
Role-based report access controls

6. Enhanced Collaboration Features#

Objective: Team coordination and comprehensive activity tracking

Key Capabilities:

Real-time project activity feeds with live updates
Campaign commenting and team notifications
Activity filtering by user, date, and type
Comprehensive audit reports and history export

Technical Implementation:

ProjectActivity model for activity tracking
ActionCable channels for real-time collaboration
ActivityTrackingService for event logging
Notification system with project-scoped broadcasting

7. Production-Ready Deployment & Operations#

Objective: Enterprise-scale deployment with comprehensive monitoring

Key Capabilities:

Docker containers with health checks and scaling
Prometheus/Grafana metrics integration
Structured logging with alerting capabilities
Zero-downtime deployments with rollback support

Technical Implementation:

Kamal 2 deployment configuration
Health check endpoints and monitoring
Structured logging with tagged context
Automated backup and disaster recovery

8. API Compatibility & Extension#

Objective: Backward compatibility with enhanced capabilities

Key Capabilities:

Full v1 API backward compatibility maintenance
Extended configuration endpoints for new features
Capability-aware task assignment algorithms
Comprehensive OpenAPI documentation

Technical Implementation:

Versioned API controllers with contract testing
Enhanced agent configuration endpoints
Rswag integration for API documentation
Comprehensive test coverage for compatibility

Technology Stack Enhancements#

Core Platform Upgrades#

Rails 8.0+: Modern framework with Propshaft asset pipeline
Ruby 3.4.5: Latest stable runtime with performance improvements
PostgreSQL 17+: Advanced database features and JSON handling
Bootstrap 5 with Catppuccin Macchiato theme: Dark-first theme via SCSS variable overrides with self-hosted fonts (Space Grotesk, IBM Plex Sans, JetBrains Mono)
Hotwire (Turbo 8 + Stimulus 3.2+): Enhanced real-time capabilities

Authentication & Authorization#

Rails 8 Authentication: Simplified session-based auth
CanCanCan + Rolify: Enhanced persona-based permissions
Project Context Management: Session-based active project selection

Real-time & Background Processing#

ActionCable with Solid Cable: Scalable WebSocket connections
Turbo Streams: Live DOM updates without JavaScript complexity
Sidekiq 7.2+: Enhanced background job processing
Solid Cache: High-performance caching with database backend

UI & Component Architecture#

ViewComponent 4.0+: Reusable, testable UI components rendering plain ERB with Bootstrap classes
Stimulus Controllers: Progressive enhancement for interactions
Bootstrap 5 Component Patterns: Plain HTML with utility classes (Railsboot abstraction layer removed)
Catppuccin Macchiato Theme: Production dark theme implemented via _catppuccin.scss with Bootstrap variable overrides
- Primary accent: $ctp-violet: #a855f7 (lightened DarkViolet, distinct from Catppuccin Mauve)
- Surface hierarchy: Crust (navbar) → Mantle (sidebar) → Base (body) → Surface0 (cards/inputs) for visual depth
- Self-hosted fonts via @fontsource for air-gap deployment: Space Grotesk (headings), IBM Plex Sans (body), JetBrains Mono (code)
WCAG 2.1 AA Compliance: Full accessibility support with semantic HTML and proper ARIA attributes

For design philosophy, user personas, and aesthetic direction, see DESIGN.md. For frontend development considerations and common pitfalls, see GOTCHAS.md § Frontend & Accessibility.

Implementation Approach#

Development Methodology#

Test-Driven Development: Write tests before implementing features
Incremental Delivery: Each milestone delivers working functionality
Backward Compatibility: Maintain v1 agent API compatibility throughout
Performance Focus: Monitor and optimize performance at each milestone

Quality Assurance#

Code Coverage: Maintain 90%+ test coverage for new code
API Contract Testing: Use Rswag for documentation and validation
System Testing: Comprehensive end-to-end workflow validation
Performance Testing: Load testing for real-time features

Risk Mitigation#

Feature Flags: Gradual rollout of new functionality
Rollback Procedures: Safe rollback capabilities for all changes
Monitoring: Comprehensive monitoring for early issue detection
Documentation: Up-to-date documentation throughout development

Implementation Timeline#

The V2 upgrade is organized into 6 major milestones spanning approximately 26 weeks:

Platform Modernization & Foundation (Weeks 1-6)
- Rails 8 & dependency upgrades
- Bootstrap 5 with Catppuccin Macchiato theme implementation
- Authentication system modernization
Enhanced Authentication & Project Context (Weeks 7-11)
- Project context management system
- Enhanced role-based access control
- User management enhancement
Real-Time Dashboard & Monitoring (Weeks 9-14)
- ActionCable infrastructure setup
- Live agent monitoring dashboard
- Campaign progress dashboard
- System metrics and performance dashboard
Campaign Management & Attack Editor Overhaul (Weeks 12-18)
- Campaign creation wizard
- Redesigned attack editor
- DAG-based campaign execution
- Campaign lifecycle management
Agent Management & Task Distribution (Weeks 16-22)
- Enhanced agent API and configuration
- Advanced agent control and monitoring
- Task management and distribution
Resource Management & Advanced Features (Weeks 20-26)
- Enhanced resource management system
- Template system and import/export
- Reporting and analytics system
- Production deployment and operations
- Final integration and testing

Success Metrics#

User Experience Metrics#

Campaign Creation Time: Reduce from 30+ minutes to under 10 minutes
Agent Monitoring Visibility: Real-time updates within 5 seconds
Task Distribution Efficiency: 90%+ optimal agent utilization
User Satisfaction: Positive feedback on guided workflows

Technical Performance Metrics#

API Compatibility: 100% backward compatibility with v1 agents
System Reliability: 99.9% uptime with zero-downtime deployments
Real-time Performance: Sub-second UI updates for dashboard components
Test Coverage: 90%+ code coverage for all new functionality

Operational Metrics#

Deployment Time: Reduce deployment complexity by 80%
Monitoring Coverage: Comprehensive metrics for all system components
Error Resolution: Automated error detection and recovery
Documentation Quality: Complete API documentation and user guides

Migration Strategy#

Backward Compatibility#

Agent API v1: Full compatibility maintained throughout upgrade
Database Schema: Incremental migrations with rollback support
User Data: Preserve all existing user accounts and project data
Configuration: Migrate existing settings to new format

Deployment Strategy#

Staged Rollout: Feature flags for gradual feature activation
Blue-Green Deployment: Zero-downtime deployment with instant rollback
Health Monitoring: Comprehensive health checks during deployment
Rollback Procedures: Automated rollback on failure detection

Training & Documentation#

User Guides: Comprehensive documentation for new features
Migration Guides: Step-by-step upgrade procedures
API Documentation: Complete OpenAPI specifications
Troubleshooting: Common issues and resolution procedures

Conclusion#

The CipherSwarm V2 upgrade represents a significant evolution of the platform, transforming it from a functional tool into a comprehensive, user-friendly distributed password cracking platform. By maintaining the existing Rails technology stack while implementing modern UI patterns, real-time capabilities, and enterprise-grade features, V2 delivers enhanced user experiences while preserving the stability and compatibility that users depend on.

The structured implementation approach, comprehensive testing strategy, and focus on backward compatibility ensure a smooth transition that delivers immediate value while building a foundation for future growth and enhancement.