CipherSwarm

CipherSwarm is a distributed password cracking management system designed for efficiency, scalability, and airgapped networks. It coordinates multiple hashcat instances across different machines to efficiently crack password hashes using various attack strategies, with a modern web interface and robust API.

Important

V2 Migration Status

CipherSwarm has migrated to v2 development on the main branch. This is the active development preview with modern FastAPI backend and SvelteKit frontend, but is not yet stable for production use.

• main branch: Active v2 development (unstable, preview)
• v1-archive branch: Stable v1 production version

All new contributions should target the main branch for v2 development.

---

Table of Contents

• CipherSwarm
  • Table of Contents
  • Features
  • Getting Started
    • Prerequisites
    • Installation
    • Docker Installation
    • Project Assumptions and Target Audience
  • Usage
  • Architecture
    • Data Concepts
  • Development Workflow
  • Tech Stack
  • API Documentation
  • Running Tests
    • Test Organization
  • Contributing
  • Acknowledgments
  • License

---

Features

• Distributed hash-cracking tasks managed through a user-friendly web interface
• Scalable architecture to efficiently distribute workloads across a network of computers
• Integration with hashcat for versatile hash cracking capabilities
• Real-time monitoring of task progress and comprehensive result reporting
• Secure, easy-to-use system for both setup and operation
• Modern SvelteKit-powered web UI with Flowbite Svelte and DaisyUI
• RESTful API (OpenAPI 3.0.1)
• Airgap and LAN support

---

Getting Started

Prerequisites

• Python 3.13 or higher
• PostgreSQL 16 or higher
• hashcat
• uv (Python package installer)
• just (recommended for all developer tasks)

Installation

1. Clone the repository:

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

2. Create and activate a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies and set up pre-commit hooks:

   just install

4. Set up the environment variables:

   cp .env.example .env
   # Edit .env with your configuration

5. Initialize the database and start the development server:

   just dev

Docker Installation

The quickest way to get CipherSwarm up and running is to use Docker Compose:

1. Clone the repository:

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

2. Deploy the Docker containers:

   docker compose -f docker-compose.dev.yml up

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

Project Assumptions and Target Audience

CipherSwarm is designed for medium to large-scale cracking infrastructure, interconnected via high-speed networks. It assumes:

1. Cracking Tool: Only Hashcat is currently supported.
2. Connectivity: All clients use reliable, high-speed LAN connections.
3. Trust Level: All client machines are trustworthy and under direct user control.
4. User Base: Users belong to the same organization or project team.
5. Hashlist Management: Handles hash lists from various projects/operations, with access control.
6. Client-Project Affiliation: Clients can be project-specific or shared, with defined priorities.

CipherSwarm is not intended for use over the Internet or with anonymous clients.

---

Usage

1. Access the CipherSwarm web interface at http://localhost:8000.
2. Log in with your credentials (admin user setup required on first run).
3. Add agents/nodes to your network through the interface.
4. Create new cracking campaigns and attacks, specifying hash types and input files.
5. Monitor the progress of your tasks in real-time through the dashboard.

---

Architecture

CipherSwarm is built on a modular architecture that separates task management, agent communication, and hash-cracking processes. This design allows for easy scaling and customization.

Data Concepts

CipherSwarm manages hashcat cracking jobs around several core objects:

• Campaigns: A comprehensive unit of work focused on a single hash list. Each campaign may encompass multiple attacks, each with different strategies or parameters.
• Attacks: A defined unit of hashcat work (mode, wordlist, rules, etc.). Large attacks can be subdivided into tasks for parallel processing across agents.
• Templates: In CipherSwarm, templates are implemented as reusable attack definitions. This is achieved by allowing an Attack to reference another Attack as its template via the template_id field. There is no separate Template model; instead, any attack can serve as a template for others.
• Tasks: The smallest unit of work, representing a segment of an attack assigned to an agent. Tasks enable parallel processing and dynamic load balancing.
• Agents: Registered clients capable of executing tasks, reporting benchmarks, and maintaining a heartbeat.
• HashLists: Sets of hashes targeted by campaigns. Each campaign is linked to one hash list, but a hash list may be reused across campaigns.
• Other Entities: CrackResults, AgentErrors, Sessions, Audits, and Users, each supporting the distributed cracking workflow and security model.

---

Development Workflow

CipherSwarm uses just for all common developer tasks. The most important commands are:

• Setup & Install:
  • just install — Install Python/JS dependencies and pre-commit hooks
• Development Server:
  • just dev — Run DB migrations and start the FastAPI dev server with hot reload
• Linting & Formatting:
  • just check — Run all code and commit checks
  • just format — Auto-format code with ruff
  • just format-check — Check formatting only
• Testing & Coverage:
  • just test — Run the full test suite with coverage
  • just ci-check — Run formatting, lint, and all tests (CI equivalent)
  • just coverage — Show coverage report
• Docs:
  • just docs — Run the local docs server (MkDocs)
  • just docs-test — Build docs for test
• Database (test DB):
  • just db-reset — Drop, recreate, and migrate the test database

Tip: Run just or just --summary to see all available tasks.

---

Tech Stack

• Backend: FastAPI (Python 3.13+)
• Frontend: SvelteKit + JSON API + Shadcn Svelte
• Database: PostgreSQL
• ORM: SQLAlchemy
• Authentication: Bearer Token
• API Documentation: OpenAPI 3.0.1

---

API Documentation

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

---

Running Tests

CipherSwarm has comprehensive test coverage with 712+ tests across unit, integration, and contract testing layers.

To run the full test suite:

just test

To run all checks (formatting, lint, tests — as in CI):

just ci-check

To see a coverage report:

just coverage

Test Organization

• Unit Tests (106 files): Service layer and component testing
• Integration Tests (36 files): API endpoint and cross-component testing
• Contract Tests: Agent API v1 compliance validation against OpenAPI spec
• Coverage: 80%+ across all modules with comprehensive reporting

For detailed testing information, see Testing Guide.

---

Contributing

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

---

Acknowledgments

• Thanks to the Hashtopolis team for inspiration and protocol documentation.
• Thanks to Hashcat for their incredible cracking tool.
• Thanks to the Python, FastAPI, and open source communities.
• Special thanks to all contributors for their valuable input and feedback.

---

License

This project is licensed under the Mozilla Public License Version 2.0 - see the LICENSE file for details.

---

Built with ❤️ by the CipherSwarm team