hash_hive_agent#

A distributed hashcat agent for the HashHive platform, written in Rust. Connects to a HashHive server, receives hash-cracking tasks, orchestrates hashcat, and reports results -- all with zero unsafe code and streaming I/O for 100 GB+ resource files.

Built for air-gapped lab environments with 10+ cracking nodes and dozens of GPUs.

Project Status#

v0.1.0 -- Initial scaffold. Core architecture is in place; hashcat integration is functional but not yet battle-tested.

• Zero unsafe code (unsafe_code = "forbid" enforced project-wide)
• Zero warnings with strict pedantic clippy linting
• Cross-platform: Linux, macOS, Windows

Features#

• Automatic task lifecycle -- Authenticate, poll for work, download resources, run hashcat, report results
• Streaming downloads -- 100 GB+ wordlists and rulelists streamed to disk, never buffered in memory
• Hashcat output parsing -- Classifies stdout/stderr lines, handles v6 and v7 format differences, colon-aware parsing for complex hash types
• Exit code normalization -- Converts unsigned 8-bit Unix exit codes back to hashcat's signed values
• Benchmark caching -- Run once, submit cached results on subsequent startups
• Graceful shutdown -- SIGINT/SIGTERM triggers cooperative cancellation; in-flight work is reported before exit
• Structured logging -- Human-readable or JSON output via tracing
• Flexible configuration -- Environment variables (HASH_HIVE_*), config file, or CLI flags

Quick Start#

Prerequisites#

• Rust 1.85+ (install via rustup)
• hashcat installed and on your PATH
• A running HashHive server with an agent token

Installation#

From source#

git clone https://github.com/EvilBit-Labs/hash_hive_agent.git
cd hash_hive_agent
cargo install --path .

Pre-built binaries#

Download from releases for Linux (amd64, arm64), macOS (Intel, Apple Silicon), and Windows (amd64).

Usage#

# Minimal -- server URL and token are required
hash-hive-agent --server-url http://server:3001/api/v1/agent --agent-token <token>

# Or set via environment variables
export HASH_HIVE_SERVER_URL=http://server:3001/api/v1/agent
export HASH_HIVE_AGENT_TOKEN=<token>
hash-hive-agent

# With explicit hashcat path and JSON logs
hash-hive-agent --hashcat-path /opt/hashcat/hashcat --json-logs

# Debug logging
hash-hive-agent --log-level debug

Configuration#

The agent loads configuration in this order (later sources override earlier ones):

1. Config file (YAML/TOML, via --config)
2. Environment variables (HASH_HIVE_*)
3. CLI flags

Architecture#

Security#

• Memory safety: unsafe_code = "forbid" enforced at the workspace level
• No panics in production: unwrap_used = "deny", panic = "deny" via clippy
• TLS via rustls: No OpenSSL dependency; openssl is banned in deny.toml
• Supply chain: Daily cargo audit and cargo deny checks in CI
• No telemetry: Zero data collection or external communication beyond the configured server

For security vulnerabilities, see our security policy.

Roadmap#

Development#

# Install dev tools via mise
mise install

# Run tests
just test

# Lint
just lint-rust

# Full CI check (lint + test + build + audit + coverage)
just ci-check

# Generate coverage report
just coverage-report

See CONTRIBUTING.md for the full development setup and submission process.

Contributing#

Contributions are welcome. See CONTRIBUTING.md for development setup, coding guidelines, and the submission process.

License#

Licensed under the Apache License 2.0 -- see LICENSE for details.

Support#

• GitHub Issues
• GitHub Discussions

Acknowledgments#

• HashHive server platform
• CipherSwarm and CipherSwarmAgent -- the original Go-based architecture this project succeeds
• hashcat -- the engine that does the actual cracking
• The Rust community for excellent tooling and ecosystem

Built for security labs and cracking rigs.