Binary Management¶

KrakenHashes provides a comprehensive binary management system for hashcat and other password cracking tools. This document explains how to manage binaries, track versions, and ensure secure distribution to agents.

Overview¶

The binary management system allows administrators to: - Upload and manage multiple versions of hashcat binaries - Track different binary types and compression formats - Verify binary integrity with MD5 checksums - Automatically extract and prepare binaries for server-side execution - Distribute binaries securely to agents - Maintain an audit trail of all binary operations

Understanding Binary Management¶

Architecture¶

The binary management system consists of several components:

1. Binary Storage: Files are stored in <data_dir>/binaries/<version_id>/
2. Local Extraction: Server-side binaries are extracted to <data_dir>/binaries/local/<version_id>/
3. Version Tracking: Database tracks all binary versions with metadata
4. Distribution: Agents download binaries via secure API endpoints
5. Verification: Automatic integrity checking with MD5 hashes

Binary Types¶

Currently supported binary types: - hashcat - Hashcat password cracking tool - john - John the Ripper (future support)

Compression Types¶

Supported compression formats: - 7z - 7-Zip archive format - zip - ZIP archive format - tar.gz - Gzip-compressed TAR archive - tar.xz - XZ-compressed TAR archive

Uploading New Binaries¶

Via Admin API¶

To add a new binary version, use the admin API endpoint:

POST /api/admin/binary
Authorization: Bearer <admin_token>
Content-Type: application/json

{
  "binary_type": "hashcat",
  "compression_type": "7z",
  "source_url": "https://github.com/hashcat/hashcat/releases/download/v6.2.6/hashcat-6.2.6.7z",
  "file_name": "hashcat-6.2.6.7z"
}

The system will: 1. Download the binary from the specified URL 2. Calculate and store the MD5 hash 3. Verify the download integrity 4. Extract the binary for server-side use 5. Mark the version as active and verified

Upload Process¶

When a binary is uploaded:

1. Download Phase: The system downloads the binary with retry logic (up to 3 attempts)
2. Verification Phase: MD5 hash is calculated and stored
3. Storage Phase: Binary is saved to <data_dir>/binaries/<version_id>/
4. Extraction Phase: Archive is extracted to <data_dir>/binaries/local/<version_id>/
5. Status Update: Version status is set to verified

Version Management and Tracking¶

Database Schema¶

Binary versions are tracked in the binary_versions table with the following fields:

Verification Status¶

Binary versions can have the following statuses: - pending - Initial state, download/verification in progress - verified - Successfully downloaded and verified - failed - Download or verification failed - deleted - Binary has been deleted

Listing Versions¶

To list all binary versions:

GET /api/admin/binary?type=hashcat&active=true
Authorization: Bearer <admin_token>

Query parameters: - type - Filter by binary type - active - Filter by active status (true/false) - status - Filter by verification status

Getting Latest Version¶

Agents can retrieve the latest active version:

GET /api/binary/latest?type=hashcat
X-API-Key: <agent_api_key>

Platform-Specific Considerations¶

Linux¶

The system automatically handles Linux-specific binary names: - Checks for both hashcat and hashcat.bin - Sets executable permissions (0750) on extracted binaries

Windows¶

• Looks for hashcat.exe in extracted archives
• Handles Windows-specific path separators

Archive Extraction¶

The extraction process intelligently handles common archive structures: - Single directory archives: Contents are moved to the target directory - Multi-file archives: All files are extracted as-is - Nested structures: Properly flattened during extraction

Binary Synchronization to Agents¶

Agent Download Process¶

Agents download binaries through the following process:

1. Version Check: Agent queries for the latest active version
2. Download Request: Agent requests binary download by version ID
3. Authentication: API key authentication is required
4. Streaming Download: Binary is streamed to the agent
5. Local Verification: Agent verifies MD5 hash after download

API Endpoints for Agents¶

# Get latest version metadata
GET /api/binary/latest?type=hashcat
X-API-Key: <agent_api_key>

# Download specific version
GET /api/binary/download/{version_id}
X-API-Key: <agent_api_key>

Synchronization Protocol¶

The agent file sync system (agent/internal/sync/sync.go) handles: - Concurrent downloads with configurable limits - Retry logic for failed downloads - Local caching to avoid re-downloads - Integrity verification with MD5 hashes

Updating and Replacing Binaries¶

Adding a New Version¶

To add a new version of hashcat:

1. Upload the new version via the admin API
2. The system automatically downloads and verifies it
3. Previous versions remain available but can be deactivated

Deactivating Old Versions¶

DELETE /api/admin/binary/{version_id}
Authorization: Bearer <admin_token>

This will: - Mark the version as inactive (is_active = false) - Set verification status to deleted - Remove the binary file from disk - Preserve the database record for audit purposes

Version Verification¶

To manually verify a binary's integrity:

POST /api/admin/binary/{version_id}/verify
Authorization: Bearer <admin_token>

This will: - Check if the file exists on disk - Recalculate the MD5 hash - Compare with stored hash - Update verification status and timestamp

Best Practices and Security¶

Security Considerations¶

1. Source URLs: Only download binaries from trusted sources
2. Official hashcat releases: https://github.com/hashcat/hashcat/releases

3. Verify SSL certificates for download sources

4. Hash Verification: Always verify MD5 hashes after download

5. The system automatically calculates and stores hashes

6. Manual verification can be triggered via API

7. Access Control: Binary management requires admin privileges

8. Only administrators can add/remove binaries

9. Agents have read-only access for downloads

10. File Permissions: Extracted binaries have restricted permissions (0750)

11. Only the application user can execute binaries
12. Group members have read access

Operational Best Practices¶

1. Version Testing: Test new binary versions before deployment
2. Upload to a test environment first
3. Verify extraction and execution work correctly

4. Check compatibility with existing jobs

5. Retention Policy: Maintain a reasonable number of versions

6. Keep at least 2-3 recent versions for rollback
7. Delete very old versions to save storage space

8. Archive important versions externally

9. Monitoring: Regular verification of binary integrity

10. Schedule periodic verification checks
11. Monitor download failures in logs

12. Track agent synchronization success rates

13. Documentation: Document version changes

14. Note any breaking changes between versions
15. Track performance improvements
16. Document known issues with specific versions

Storage Management¶

1. Disk Space: Monitor available disk space
2. Binary archives can be large (100MB+)
3. Extracted binaries double the storage requirement

4. Plan for growth with multiple versions

5. Cleanup: Regular cleanup of old versions

6. Delete inactive versions after confirming they're not needed
7. Remove failed download attempts
8. Clean up orphaned extraction directories

Troubleshooting¶

Common Issues¶

1. Download Failures
2. Check network connectivity to source URL
3. Verify SSL/TLS certificates are valid
4. Check firewall rules for outbound HTTPS

5. Review logs for specific error messages

6. Extraction Failures

7. Ensure required tools are installed (7z, unzip, tar)
8. Check disk space for extraction
9. Verify archive isn't corrupted

10. Check file permissions on data directory

11. Verification Failures

12. File may be corrupted during download
13. Source file may have changed
14. Disk errors could cause corruption
15. Try re-downloading the binary

Log Locations¶

Binary management logs are written to: - Backend logs: Check for [Binary Manager] entries - Download attempts: Look for HTTP client errors - Extraction logs: Command output is logged - Verification results: Hash comparison details

Manual Recovery¶

If automated processes fail:

1. Manual Download: Download binary to a temporary location
2. Manual Upload: Place in <data_dir>/binaries/<version_id>/
3. Update Database: Set correct hash and file size
4. Manual Extraction: Extract to local directory
5. Verify Permissions: Ensure correct file permissions

Version.json File¶

The versions.json file in the repository root tracks component versions:

{
    "backend": "0.1.0",
    "frontend": "0.1.0",
    "agent": "0.1.0",
    "api": "0.1.0",
    "database": "0.1.0"
}

This file is used for: - Build-time version embedding - API version compatibility checks - Component version tracking - Release management

Note: This tracks KrakenHashes component versions, not binary tool versions.

API Reference¶

Admin Endpoints¶

Agent Endpoints¶

Future Enhancements¶

Planned improvements to the binary management system:

1. Automatic Updates: Check for new releases periodically
2. Version Channels: Support for stable/beta/nightly channels
3. Platform Detection: Automatic platform-specific binary selection
4. Signature Verification: GPG signature verification for downloads
5. Delta Updates: Differential updates for minor versions
6. Binary Caching: CDN integration for faster agent downloads
7. Performance Metrics: Track binary performance across versions