KrakenHashes System Architecture¶

Table of Contents¶

1. Overview
2. High-Level Architecture
3. Backend Architecture
4. Frontend Architecture
5. Agent Architecture
6. Communication Protocols
7. Database Schema
8. Security Architecture
9. File Storage Architecture
10. Deployment Architecture

Overview¶

KrakenHashes is a distributed password cracking management system designed to orchestrate and manage hashcat operations across multiple compute agents. The system follows a client-server architecture with a centralized backend, web-based frontend, and distributed agent nodes.

Key Components¶

• Backend Server (Go): REST API server managing job orchestration, user authentication, and agent coordination
• Frontend (React/TypeScript): Web UI for system management and monitoring
• Agent (Go): Distributed compute nodes executing hashcat jobs
• PostgreSQL Database: Persistent storage for system data
• File Storage: Centralized storage for binaries, wordlists, rules, and hashlists

High-Level Architecture¶

┌─────────────────────────────────────────────────────────────────────────┐
│                            Frontend (React)                              │
│                         Material-UI Components                           │
│                      React Query + TypeScript                            │
└────────────────────────────────┬────────────────────────────────────────┘
                                 │ HTTPS/REST API
                                 │ WebSocket
┌────────────────────────────────▼────────────────────────────────────────┐
│                          Backend Server (Go)                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌────────────┐ │
│  │   Handlers   │  │   Services   │  │ Repositories │  │ Middleware │ │
│  │  (HTTP/WS)   │  │ (Business)   │  │   (Data)     │  │   (Auth)   │ │
│  └──────────────┘  └──────────────┘  └──────────────┘  └────────────┘ │
└────────────────────────────────┬────────────────────────────────────────┘
                                 │ SQL
                                 │
┌────────────────────────────────▼────────────────────────────────────────┐
│                         PostgreSQL Database                              │
│                    (Users, Agents, Jobs, Hashlists)                     │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────┐
│                          Agent Nodes (Go)                                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌────────────┐ │
│  │   Hardware   │  │     Job      │  │     Sync     │  │ Heartbeat  │ │
│  │  Detection   │  │  Execution   │  │   Manager    │  │  Manager   │ │
│  └──────────────┘  └──────────────┘  └──────────────┘  └────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘

Backend Architecture¶

Layered Architecture¶

The backend follows a clean layered architecture with clear separation of concerns:

1. Presentation Layer (internal/handlers/)¶

• HTTP request handlers organized by domain
• WebSocket handlers for real-time communication
• Request validation and response formatting

Key Packages: - admin/ - Administrative functions (users, clients, settings) - agent/ - Agent management and registration - auth/ - Authentication and authorization - hashlist/ - Hashlist management - jobs/ - Job execution and monitoring - websocket/ - WebSocket connection handling

2. Service Layer (internal/services/)¶

• Business logic implementation
• Transaction management
• Cross-cutting concerns (scheduling, monitoring)

Key Services: - AgentService - Agent lifecycle management - JobExecutionService - Job orchestration - JobSchedulingService - Task distribution - ClientService - Customer management - RetentionService - Data retention policies - WebSocketService - Real-time communication hub

3. Repository Layer (internal/repository/)¶

• Database access abstraction
• SQL query execution
• Data mapping

Key Repositories: - UserRepository - User account management - AgentRepository - Agent registration and status - HashlistRepository - Hashlist storage - JobExecutionRepository - Job tracking - JobTaskRepository - Task management

4. Infrastructure Layer¶

• Database connections (internal/database/)
• File storage (internal/binary/, internal/wordlist/, internal/rule/)
• External integrations (email providers)
• TLS/SSL management (internal/tls/)

Design Patterns¶

1. Repository Pattern: All database operations go through repository interfaces
2. Service Layer Pattern: Business logic separated from data access
3. Middleware Pattern: Cross-cutting concerns (auth, logging, CORS)
4. Hub Pattern: Central WebSocket hub for agent connections
5. Factory Pattern: TLS provider creation, GPU detector creation

Key Backend Features¶

• JWT Authentication: Access/refresh token pattern
• Multi-Factor Authentication: TOTP, email, backup codes
• Role-Based Access Control: user, admin, agent, system roles
• Job Scheduling: Dynamic task distribution with chunking
• File Synchronization: Agent-backend file sync
• Monitoring: System metrics and heartbeat management
• Data Retention: Configurable retention policies

Frontend Architecture¶

Component Structure¶

The frontend uses React with TypeScript and follows a component-based architecture:

1. Pages (src/pages/)¶

• Top-level route components
• Page-specific business logic
• Component composition

Key Pages: - Dashboard - System overview - AgentManagement - Agent monitoring - Jobs/ - Job execution interface - AdminSettings/ - System configuration - Login - Authentication

2. Components (src/components/)¶

• Reusable UI components
• Domain-specific components
• Common UI patterns

Component Categories: - admin/ - Administrative UI components - agent/ - Agent-related components - auth/ - Authentication components - common/ - Shared components - hashlist/ - Hashlist management UI

3. Services (src/services/)¶

• API communication layer
• HTTP request handling
• Response transformation

Key Services: - api.ts - Base API configuration - auth.ts - Authentication API - jobSettings.ts - Job configuration - systemSettings.ts - System settings

4. State Management¶

• React Context: Authentication state (AuthContext)
• React Query: Server state management with caching
• Local State: Component-specific state with hooks

5. Type System (src/types/)¶

• TypeScript interfaces and types
• API response types
• Domain models

Frontend Technologies¶

• React 18: Component framework
• TypeScript: Type safety
• Material-UI: Component library
• React Query: Data fetching and caching
• React Router: Client-side routing
• Axios: HTTP client

Agent Architecture¶

Core Modules¶

1. Agent Core (internal/agent/)¶

• WebSocket connection management
• Registration with claim codes
• Heartbeat maintenance
• Message routing

2. Hardware Detection (internal/hardware/)¶

• GPU detection (NVIDIA, AMD, Intel)
• System resource monitoring
• Hashcat availability checking
• Device capability reporting

GPU Detectors: - gpu/nvidia.go - NVIDIA GPU detection - gpu/amd.go - AMD GPU detection - gpu/intel.go - Intel GPU detection - gpu/detector.go - Detection orchestration

3. Job Execution (internal/jobs/)¶

• Hashcat process management
• Job progress tracking
• Output parsing
• Error handling

4. File Synchronization (internal/sync/)¶

• Binary synchronization
• Wordlist management
• Rule file handling
• Hashlist retrieval

5. Metrics Collection (internal/metrics/)¶

• System resource monitoring
• GPU utilization tracking
• Performance metrics reporting

Agent Lifecycle¶

1. Registration Phase
2. Claim code validation
3. API key generation
4. Certificate exchange

5. Initial synchronization

6. Active Phase

7. Heartbeat maintenance
8. Job reception and execution
9. Progress reporting

10. File synchronization

11. Execution Phase

12. Task assignment reception
13. Hashcat process spawning
14. Progress monitoring
15. Result reporting

Communication Protocols¶

REST API¶

The system uses RESTful APIs for standard CRUD operations:

Endpoint Structure:

/api/v1/auth/*         - Authentication endpoints
/api/v1/admin/*        - Administrative functions
/api/v1/agents/*       - Agent management
/api/v1/hashlists/*    - Hashlist operations
/api/v1/jobs/*         - Job management
/api/v1/wordlists/*    - Wordlist management
/api/v1/rules/*        - Rule file management

Authentication: - JWT Bearer tokens - API key authentication (agents) - Refresh token rotation

WebSocket Protocol¶

Real-time communication uses WebSocket with JSON message format:

Message Structure:

{
  "type": "message_type",
  "payload": { ... },
  "timestamp": "2025-01-01T00:00:00Z"
}

Agent → Server Messages: - heartbeat - Keep-alive signal - task_status - Task execution status - job_progress - Job progress updates - benchmark_result - Benchmark results - hardware_info - Hardware capabilities - hashcat_output - Hashcat output streams - device_update - Device status changes

Server → Agent Messages: - task_assignment - New task assignment - job_stop - Stop job execution - benchmark_request - Request benchmark - config_update - Configuration changes - file_sync_request - File sync command - force_cleanup - Force cleanup command

File Transfer Protocol¶

File synchronization uses HTTP(S) with the following endpoints:

• GET /api/v1/sync/binaries/:name - Download binaries
• GET /api/v1/sync/wordlists/:id - Download wordlists
• GET /api/v1/sync/rules/:id - Download rules
• GET /api/v1/sync/hashlists/:id - Download hashlists

Database Schema¶

Core Tables¶

User Management¶

• users - User accounts with roles and preferences
• auth_tokens - JWT refresh tokens
• mfa_methods - Multi-factor authentication settings
• mfa_backup_codes - MFA recovery codes

Agent Management¶

• agents - Registered compute agents
• agent_devices - GPU/compute devices per agent
• agent_schedules - Agent availability schedules
• agent_hashlists - Agent-hashlist assignments

Job Management¶

• job_workflows - Attack strategy definitions
• preset_jobs - Predefined job templates
• job_executions - Active job instances
• job_tasks - Individual task assignments
• performance_metrics - Task performance data

Data Management¶

• hashlists - Password hash collections
• hashes - Individual password hashes
• clients - Customer/engagement tracking
• wordlists - Dictionary files
• rules - Rule files for mutations

System Management¶

• vouchers - Agent registration codes
• binary_versions - Hashcat binary versions
• system_settings - Global configuration
• client_settings - Per-client settings

Key Relationships¶

users ─────────┬──── agents (owner_id)
               ├──── hashlists (created_by)
               └──── job_executions (created_by)

agents ────────┬──── agent_devices
               ├──── agent_schedules
               └──── job_tasks

hashlists ─────┬──── hashes
               ├──── job_executions
               └──── clients

job_workflows ──┬─── preset_jobs
                └─── job_executions ──── job_tasks

Security Architecture¶

Authentication & Authorization¶

Multi-Layer Authentication¶

1. User Authentication
2. Username/password with bcrypt hashing
3. JWT access/refresh token pattern

4. Session management with token rotation

5. Multi-Factor Authentication

6. TOTP (Time-based One-Time Passwords)
7. Email-based verification
8. Backup codes for recovery

9. Configurable MFA policies

10. Agent Authentication

11. Claim code registration
12. API key authentication
13. Certificate-based trust

Role-Based Access Control (RBAC)¶

Roles: - user - Standard user access - admin - Administrative privileges - agent - Agent-specific operations - system - System-level operations

Middleware Chain:

AuthMiddleware → RoleMiddleware → ResourceMiddleware → Handler

Transport Security¶

TLS/SSL Configuration¶

Supported Modes: 1. Self-Signed Certificates - Automatic generation with CA - Configurable validity periods - SAN extension support

1. Provided Certificates
2. Custom certificate installation

3. Certificate chain validation

4. Let's Encrypt (Certbot)

5. Automatic certificate renewal
6. ACME protocol support

Certificate Features: - RSA 2048/4096 bit keys - Multiple DNS names and IP addresses - Proper certificate chain delivery - Browser-compatible extensions

Data Security¶

1. Password Storage
2. bcrypt with configurable cost factor

3. No plaintext storage

4. Token Security

5. Short-lived access tokens (15 minutes)
6. Refresh token rotation

7. Secure token storage

8. File Access Control

9. Path sanitization
10. Directory restrictions

11. User-based access control

12. API Security

13. Rate limiting
14. Request validation
15. CORS configuration

File Storage Architecture¶

Directory Structure¶

/data/krakenhashes/
├── binaries/         # Hashcat binaries
│   ├── hashcat-linux-x64/
│   ├── hashcat-windows-x64/
│   └── hashcat-darwin-x64/
├── wordlists/        # Dictionary files
│   ├── general/      # Common wordlists
│   ├── specialized/  # Domain-specific
│   ├── targeted/     # Custom lists
│   └── custom/       # User uploads
├── rules/            # Mutation rules
│   ├── hashcat/      # Hashcat rules
│   ├── john/         # John rules
│   └── custom/       # Custom rules
└── hashlists/        # Hash files
    └── {client_id}/  # Per-client storage

Storage Management¶

1. File Organization
2. Client-based isolation
3. Category-based grouping

4. Version tracking

5. Synchronization

6. Delta-based updates
7. Checksum verification

8. Compression support

9. Retention Policies

10. Configurable retention periods
11. Automatic cleanup
12. Archive support

Deployment Architecture¶

Docker-Based Deployment¶

Services:
- backend    # Go backend server
- postgres   # PostgreSQL database
- app        # Nginx + React frontend

Networks:
- krakenhashes_default # Internal network

Volumes:
- postgres_data     # Database persistence
- kh_config        # Configuration files
- kh_data          # Application data
- kh_logs          # Log files

Production Considerations¶

1. Scalability
2. Horizontal agent scaling
3. Database connection pooling

4. Load balancer ready

5. Monitoring

6. Health check endpoints
7. Metrics collection

8. Log aggregation

9. Backup & Recovery

10. Database backups
11. File system snapshots

12. Configuration backup

13. High Availability

14. Database replication support
15. Stateless backend design
16. Agent failover handling

Environment Configuration¶

Key Environment Variables:

# Database
DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME

# Security
JWT_SECRET, JWT_REFRESH_SECRET

# TLS/SSL
KH_TLS_MODE, KH_CERT_KEY_SIZE

# Directories
KH_CONFIG_DIR, KH_DATA_DIR

# Ports
KH_HTTP_PORT, KH_HTTPS_PORT

Conclusion¶

KrakenHashes implements a robust distributed architecture designed for scalability, security, and maintainability. The system's modular design allows for independent scaling of components while maintaining clear separation of concerns throughout the stack.