CipherSwarm is a distributed hash cracking system designed for efficiency and scalability and built on Ruby on Rails. Inspired by the principles of Hashtopolis, CipherSwarm leverages the power of collaborative computing to tackle complex cryptographic challenges, offering a web-based interface for managing and distributing hash-cracking tasks across multiple nodes.

CipherSwarm is currently undergoing a comprehensive V2 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 Experience: Real-time dashboards, guided workflows, and intuitive interfaces
• Advanced Collaboration: Multi-user coordination with role-based access controls
• Intelligent Automation: Smart task distribution and dependency management
• Enterprise Features: Production-ready deployment, comprehensive monitoring, and analytics

For detailed information about the V2 upgrade, see the V2 Upgrade Overview.

• CipherSwarm
  • 🚀 CipherSwarm V2 Upgrade
  • Table of Contents
  • Features
  • Getting Started
  • Usage
  • Architecture
  • Documentation
  • Contributing
  • Acknowledgments

• Distributed hash-cracking tasks managed through a web interface
• Scalable architecture to efficiently distribute workloads across multiple agents
• Integration with hashcat for versatile hash cracking capabilities
• Campaign and attack management with priority-based execution
• Project-based multi-tenancy with role-based access control

• Real-time Operations Dashboard: Live agent monitoring, campaign progress, and crack result feeds
• Enhanced Campaign Management: Guided wizard with DAG-based attack dependencies
• Advanced Agent Management: Intelligent task distribution based on agent capabilities
• Comprehensive Analytics: Password pattern analysis and security insights
• Team Collaboration: Activity feeds, commenting, and project coordination
• Production-Ready Deployment: Containerized deployment with monitoring and scaling

See the V2 Upgrade Overview for complete feature details.

• Ruby 3.4.5 (managed with rbenv)
• Rails 8.0+
• PostgreSQL 17+ (primary database)
• Redis 7.2+ (for Solid Cache and Sidekiq job processing)
• Just task runner (optional but recommended)

1. Clone the repository to your local machine:

   git clone https://github.com/unclesp1d3r/CipherSwarm.git
   cd CipherSwarm

2. Install dependencies and setup the database:

   Using Just (recommended):

   just install
   just setup

   Or manually:

   bundle install
   yarn install
   rails db:create
   rails db:migrate

3. Start the development server:

   Using Just:

   just dev

   Or manually:

   bin/dev

   This starts Rails, asset compilation, and Sidekiq workers.

4. Access the application at http://localhost:3000

CipherSwarm includes a justfile for common development tasks. See all available commands:

just --list

Common commands:

• just install - Install all dependencies
• just setup - Setup database and configuration
• just dev - Start full development environment
• just test - Run all tests with coverage
• just check - Run linters and security checks
• just db-reset - Reset database

See .kiro/steering/justfile.md for complete command documentation.

The quickest way to get CipherSwarm up and running is to use Docker. The following steps will guide you through the process:

1. Clone the repository to your local machine:

   git clone https://github.com/unclesp1d3r/CipherSwarm.git
   cd CipherSwarm

2. Deploy the Docker containers:

   docker compose -f docker-compose-production.yml up

3. Access the CipherSwarm web interface at http://localhost:3000.

4. Log in with the default admin credentials (username: admin, password: password) and change the password immediately.

CipherSwarm, while performing functions similar to Hashtopolis, is not a reiteration of the latter. It is a unique project, conceived with a specific target audience in mind and shaped by several guiding assumptions:

1. Cracking Tool: CipherSwarm exclusively supports Hashcat as the cracking tool.

2. Connectivity: All clients connected to CipherSwarm are assumed to use a reliable, high-speed connection, typically found in a Local Area Network (LAN) environment.

3. Trust Level: CipherSwarm operates under the assumption that all client machines are trustworthy and are under the direct control and management of the user utilizing CipherSwarm.

4. User Base: The system assumes that users, though having different levels of administrative access, belong to the same organization or project team, ensuring a level of trust and common purpose.

5. Hashlist Management: CipherSwarm is designed to handle hash lists derived from various projects or operations. Depending on access privileges, it lets users view results from specific projects or across all projects.

6. Client-Project Affiliation: Cracking clients can be associated with specific projects, executing operations solely for that project. Alternatively, they can perform operations across all projects, with defined priorities for particular projects.

CipherSwarm is crafted explicitly for medium to large-scale cracking infrastructure, interconnected via high-speed networks. It does not support utilization over the Internet or integration with anonymous user systems acting as cracking clients. By focusing on secure, centralized, and high-performance environments, CipherSwarm delivers tailored scalability and efficiency to meet the demands of sophisticated cracking operations.

1. Access the CipherSwarm web interface at http://localhost:3000.
2. Log in with the default admin credentials (username: admin, password: password) and change the password immediately.
3. Add nodes to your network through the interface.
4. Create new cracking tasks, specifying the hash types and input files.
5. Monitor the progress of your tasks in real-time through the dashboard.

CipherSwarm is built on a modern Rails 8.0+ architecture with clear separation of concerns and service-oriented design patterns. The system follows Rails conventions while implementing a distributed password cracking management system.

The application uses a monolithic Rails architecture with the following layers:

• Web Interface Layer: Controllers, Views, and ViewComponents using Hotwire (Turbo + Stimulus)
• 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

• Web UI: Rails 8 built-in authentication with secure session cookies
• Agent API: Bearer token authentication for distributed agents
• Authorization: Project-based multi-tenancy with role-based access control

• Ruby 3.4.5 with Rails 8.0+
• PostgreSQL 17+ for primary data storage
• Redis 7.2+ for Solid Cache and Sidekiq job processing
• Hotwire (Turbo + Stimulus) for interactive frontend
• ViewComponent for reusable UI components
• Sidekiq for background job processing

In the CipherSwarm system, hashcat cracking jobs are managed around four core objects: Campaigns, Attacks, Templates, and Tasks. Understanding these objects and their interrelations is critical to effectively leveraging the system for distributed hash cracking.

Campaigns represent a comprehensive unit of work focused on a single hash list. Each Campaign is designed to achieve a specific goal, such as recovering passwords from a set of hashes. A Campaign may encompass multiple Attacks, each tailored to run against the Campaign's hash list using different strategies or parameters. Campaigns facilitate the organization and prioritization of attacks, allowing for sequential execution based on priority or effectiveness.

An Attack is a defined unit of hashcat work characterized by its attack type and the word list and rules it employs. An attack embodies a specific approach to cracking hashes, such as brute force or dictionary attacks, complete with all necessary parameters. Large attacks can be subdivided into Tasks to distribute the workload across multiple Agents, enabling parallel processing and thus speeding up the cracking process.

A Template serves as a reusable definition of an attack. It specifies the attack type and parameters (such as word lists and rules) but is not bound to a specific hash list. Templates allow for the rapid configuration of new attacks by applying a pre-defined set of strategies to different hash lists and types. This abstraction facilitates the quick adaptation to new cracking challenges without needing reconfiguring from scratch.

The Task is the smallest unit of work within the system, representing a segment of an Attack that an individual Agent is tasked with processing at any given time. Tasks are the fundamental work packets distributed to Agents in the network, allowing for the division of a larger attack into manageable pieces. This division not only enhances efficiency through parallel processing but also allows for dynamic load balancing across the network of Agents.

Comprehensive documentation is available in the docs/ directory:

• V2 Upgrade Overview - Complete overview of the V2 upgrade
• User Guide - How to use CipherSwarm
• Getting Started - Quick start guide
• API Reference - Agent API documentation
• Development Guide - Development and contribution guidelines

We welcome contributions from the community! Please refer to the CONTRIBUTING.md file for guidelines on how to get involved.

• We want to thank the Hashtopolis team for inspiring us and providing us with the Hashtopolis Communication Protocol v2 documentation.
• Our sincere thanks to Hashcat for their incredible cracking tool.
• Thank you to the Ruby on Rails community for their guidance and support.
• Special thanks to our contributors for their valuable input and feedback.