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 with modular architecture (v1.1+) - Modular Components: - job_scheduling_service.go (600+ lines) - Main scheduling coordinator - job_scheduling_benchmark_planning.go (684 lines) - Parallel benchmark planning and execution - job_scheduling_task_assignment.go (710 lines) - Parallel task assignment with two-phase execution - Performance Characteristics: - Parallel benchmarking: 96% improvement (15 agents: 450s → 12s) - Parallel task assignment: 95% improvement (15 agents: 450s → 20s) - Goroutine-based concurrent operations for scalability - Key Features: - Priority-based allocation with overflow control (FIFO/round-robin modes) - Round-robin benchmark distribution - Two-phase task planning (sequential planning, parallel execution) - Forced benchmark agent prioritization - JobProgressCalculationService - Polling-based progress calculation - Recalculates job progress every 2 seconds from task data - Ensures accurate processed/dispatched keyspace tracking - ClientService - Customer management - RetentionService - Automated data purging with secure deletion - WebSocketService - Real-time communication hub - HashlistSyncService - File synchronization to agents - MetricsCleanupService - Agent metrics pruning - PotfileService - Manages both global and client potfile staging and batch processing. Unified background worker handles password routing via three-level cascade. Includes per-client LRU bloom filter cache (max 50) - ClientPotfileService - Thin compatibility wrapper that delegates operations to the unified PotfileService for client potfile paths, info, deletion, and regeneration - ClientWordlistManager - Upload, validation, storage, counting, MD5 hashing, and deletion of client-specific wordlists. Sanitizes filenames, rejects reserved name potfile.txt

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 - ClientPotfileRepository - CRUD for client_potfiles table; queries unique plaintexts for potfile regeneration - ClientWordlistRepository - CRUD for client_wordlists table; manages file paths and metadata

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
• Accurate Keyspace Tracking: Captures real keyspace from hashcat progress[1] values and recalculates progress every 2 seconds for precise, self-healing progress reporting
• Client Potfile Cascade: Three-level (System/Client/Hashlist) exclusion controls for password routing to global and client potfiles, with per-client LRU bloom filter cache and surgical removal on hashlist delete

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
• client_potfiles - Client-specific potfile metadata (file_path, file_size, line_count, md5_hash, one per client)
• client_wordlists - Client-specific wordlists (file_path, file_name, file_size, line_count, md5_hash)
• potfile_staging - Temporary storage for cracked passwords (includes client_id, exclude_from_global, exclude_from_client for routing)

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. Session-token binding with CASCADE delete for security

6. Multi-Factor Authentication

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

10. Configurable MFA policies

11. Agent Authentication

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

Session Security Architecture¶

KrakenHashes implements a database-backed session-token relationship to ensure true session termination:

• Foreign Key Binding: active_sessions.token_id → tokens.id with ON DELETE CASCADE
• Atomic Revocation: Deleting a token automatically removes associated sessions
• True Logout: Session termination immediately invalidates JWT authentication
• Security Enforcement: Auth middleware validates both token existence and session validity
• No Orphaned Tokens: Database constraints prevent tokens from persisting after logout

This architecture prevents a critical vulnerability where session termination would only remove UI state but leave JWT tokens active in the database.

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 (includes global potfile.txt)
│   └── clients/      # Client-specific files (auto-managed, excluded from directory monitor)
│       └── {client_uuid}/
│           ├── potfile.txt    # Auto-generated client potfile
│           └── *.txt          # Uploaded client wordlists
├── rules/            # Mutation rules
│   ├── hashcat/      # Hashcat rules
│   ├── john/         # John rules
│   └── custom/       # Custom rules
└── hashlists/        # Hash files
    └── {client_id}/  # Per-client storage

Storage Management¶

• Upload Processing: Files are uploaded to temporary storage, processed, then moved to permanent locations
• Deduplication: Files are tracked by MD5 hash to prevent duplicates
• Synchronization: Agent sync service ensures agents have required files
• Cleanup: Automated retention policies remove expired data

Data Lifecycle Management¶

Retention System¶

The system implements comprehensive data lifecycle management with automated retention policies:

Backend Retention Service¶

• Automatic Purging: Runs daily at midnight and on startup
• Client-Specific Policies: Each client can have custom retention periods
• Secure Deletion Process:
• Transaction-based database cleanup
• Secure file overwriting with random data
• PostgreSQL VACUUM to prevent recovery
• Comprehensive audit logging

Agent Cleanup Service¶

• 3-Day Retention: Temporary files removed after 3 days
• Automatic Cleanup: Runs every 6 hours
• File Types Managed:
• Hashlist files (after inactivity)
• Rule chunks (temporary segments)
• Chunk ID tracking files
• Preserved Files: Base rules, wordlists, and binaries

Potfile Exclusion¶

Data Security¶

Secure Deletion¶

• Files overwritten with random data before removal
• VACUUM ANALYZE on PostgreSQL tables
• Prevention of WAL (Write-Ahead Log) recovery
• Transaction safety for atomic operations

Audit Trail¶

• All deletion operations logged
• Retention compliance tracking

• Last purge timestamp recording

• File Organization

• Client-based isolation
• Category-based grouping

• Version tracking

• Synchronization

• Delta-based updates
• Checksum verification

• Compression support

• Retention Policies

• Configurable retention periods
• Automatic cleanup
• 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.