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.
v0.1.0 -- Initial scaffold. Core architecture is in place; hashcat integration is functional but not yet battle-tested.
- Zero
unsafecode (unsafe_code = "forbid"enforced project-wide) - Zero warnings with strict pedantic clippy linting
- Cross-platform: Linux, macOS, Windows
- 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
- Rust 1.85+ (install via rustup)
- hashcat installed and on your
PATH - A running HashHive server with an agent token
git clone https://github.com/EvilBit-Labs/hash_hive_agent.git
cd hash_hive_agent
cargo install --path .Download from releases for Linux (amd64, arm64), macOS (Intel, Apple Silicon), and Windows (amd64).
# 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 debugThe agent loads configuration in this order (later sources override earlier ones):
- Config file (YAML/TOML, via
--config) - Environment variables (
HASH_HIVE_*) - CLI flags
| Setting | CLI Flag | Environment Variable | Default |
|---|---|---|---|
| Server URL | --server-url |
HASH_HIVE_SERVER_URL |
http://localhost:3001/api/v1/agent |
| Agent token | --agent-token |
HASH_HIVE_AGENT_TOKEN |
(required) |
| Hashcat binary | --hashcat-path |
HASH_HIVE_HASHCAT_PATH |
hashcat (on PATH) |
| Log level | --log-level |
HASH_HIVE_LOG_LEVEL |
info |
| JSON logs | --json-logs |
-- | false |
| Heartbeat interval | -- | HASH_HIVE_HEARTBEAT_INTERVAL |
30s |
| Poll interval | -- | HASH_HIVE_POLL_INTERVAL |
10s |
graph TD
Server["HashHive Server API"]
Server <-->|REST| Agent["Agent Run Loop"]
Agent --> HB["Heartbeat"]
Agent --> Poll["Task Polling"]
Agent --> Bench["Benchmarks"]
Poll -->|task assigned| DL["Download Resources"]
DL -->|streaming I/O| HC["Run Hashcat Session"]
HC -->|cracks & progress| Report["Report Results"]
Report -->|POST /tasks/id/report| Server
HB -->|POST /heartbeat| Server
Bench -->|POST /benchmark| Server
style Server fill:#1e2030,stroke:#f5a97f,color:#cad3f5
style Agent fill:#1e2030,stroke:#8aadf4,color:#cad3f5
style HB fill:#24273a,stroke:#a6da95,color:#cad3f5
style Poll fill:#24273a,stroke:#a6da95,color:#cad3f5
style Bench fill:#24273a,stroke:#a6da95,color:#cad3f5
style DL fill:#24273a,stroke:#eed49f,color:#cad3f5
style HC fill:#24273a,stroke:#eed49f,color:#cad3f5
style Report fill:#24273a,stroke:#eed49f,color:#cad3f5
| Module | Purpose |
|---|---|
api/ |
Typed HTTP client for the HashHive Agent API (reqwest + serde) |
agent/ |
Lifecycle orchestration: heartbeat, polling, graceful shutdown |
hashcat/ |
Session management, stdout/stderr parsing, exit code classification |
task/ |
Resource downloads (streaming), hashcat execution, progress reporting |
benchmark/ |
Benchmark execution and disk caching |
config/ |
Configuration from env, file, and CLI with typed defaults |
platform/ |
Cross-platform system metrics (CPU, memory, GPU temperature) |
- 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;
opensslis banned indeny.toml - Supply chain: Daily
cargo auditandcargo denychecks in CI - No telemetry: Zero data collection or external communication beyond the configured server
For security vulnerabilities, see our security policy.
| Milestone | Focus |
|---|---|
| v0.1.x (current) | Core scaffold: API client, task lifecycle, hashcat integration |
| v0.2.0 | Zap list support, retry with exponential backoff, benchmark execution |
| v0.3.0 | Restore file management, partial result caching, GPU temperature monitoring |
| v1.0.0 | Production-ready: full HashHive API coverage, comprehensive test suite |
# 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-reportSee CONTRIBUTING.md for the full development setup and submission process.
Contributions are welcome. See CONTRIBUTING.md for development setup, coding guidelines, and the submission process.
Licensed under the Apache License 2.0 -- see LICENSE for details.
- 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.