Back to updates
New releaseAug 1, 2026

hate_crack v2.23.0

A tool for automating cracking methodologies through Hashcat from the TrustedSec team.

Share
  ___ ___         __             _________                       __
 /   |   \_____ _/  |_  ____     \_   ___ \____________    ____ |  | __
/    ~    \__  \\   __\/ __ \    /    \  \/\_  __ \__  \ _/ ___\|  |/ /
\    Y    // __ \|  | \  ___/    \     \____|  | \// __ \\  \___|    <
 \___|_  /(____  /__|  \___  >____\______  /|__|  (____  /\___  >__|_ \
       \/      \/          \/_____/      \/            \/     \/     \/

Installation

Installing from source is the only supported path. hate_crack is not distributed on PyPI: pip install hate-crack resolves to a 0.0.0 placeholder that fails on purpose and points back here. The name is held only so nobody else can publish a lookalike under it — see packaging/pypi-placeholder/.

1. Install hashcat

Hashcat must be installed and available in your PATH:

Ubuntu/Kali:

sudo apt-get install -y hashcat

macOS (Homebrew):

brew install hashcat

Or download a pre-built binary from https://hashcat.net/hashcat/ and set hcatPath in config.json to its location.

2. Download hate_crack

Clone with submodules (required for hashcat-utils, princeprocessor, pcfg_cracker, Corporate_Masks, and optionally omen):

git clone --recurse-submodules https://github.com/trustedsec/hate_crack.git
cd hate_crack

If you cloned without submodules, initialize them:

git submodule update --init --recursive

Then customize configuration if needed. hate_crack uses two config files, each owning a distinct set of settings:

  • config.json — wordlist paths, masks, rules, tuning, potfile, hashcat path, candidate limits, notification toggles, CLI preference defaults (35 settings).
  • .env — third-party integration settings only: Hashview and Hashmob credentials, Pushover credentials, Ollama, and pipal (14 settings). Not tracked by git, created at mode 0600.

The line falls there for one reason: .env is the file that can hold secrets. Credentials for, and configuration of, third-party services go in the untracked, 0600 file; everything hate_crack does locally stays in config.json, which is safe to share, diff and check into your own notes. That is also why the Pushover credentials are in .env while the Pushover on/off toggles are in config.json — the toggles are local preferences, not secrets.

Each key has exactly one home. A key placed in the other file is ignored, and hate_crack prints a warning naming the file it belongs in. Any key can still be overridden for a single run by exporting its environment variable. Most users can skip this step as default paths work out-of-the-box.

config.json is permanent and first-class — it is not deprecated and there is no removal timeline for it. Only the integration settings moved.

Upgrading from a single config.json? hate_crack migrates it for you on first run: the integration settings are copied into a new 0600 .env, then removed from config.json so the two files do not both claim them. It prints which keys moved (never their values), and saves your original as config.json.pre-split.bak before touching it. Everything else in config.json is left exactly as it was, key order included.

First run: hate_crack creates both files for you, so there is nothing to do. To set up .env by hand instead, copy the tracked template:

cp .env.example .env
chmod 600 .env

.env.example is committed and ships with every credential key empty. .env itself must never be committed — it is gitignored, along with its usual backup spellings, and hate_crack always creates it at mode 0600 (owner read/write only). .env.example is generated from the schema; regenerate it after changing hate_crack/config_schema.py with uv run python -m hate_crack.config_writer.

3. Install dependencies and hate_crack

The easiest way is to run make (or make install), which auto-detects your OS and installs:

  • External dependencies (p7zip, transmission-daemon / transmission-remote)
  • Builds submodules (hashcat-utils, princeprocessor, pcfg_cracker, and optionally omen) and checks out the data-only Corporate_Masks mask set
  • Python dependencies via uv and a CLI shim at ~/.local/bin/hate_crack
make

This is idempotent - it skips tools already installed. To force a clean reinstall:

make reinstall

Or install dependencies manually:

External Dependencies

These are required for certain download/extraction flows:

  • 7z/7za (p7zip) — used to extract .7z archives.
  • transmission-daemon / transmission-remote — used to download Weakpass torrents.

Manual install commands:

Ubuntu/Kali:

sudo apt-get update
sudo apt-get install -y p7zip-full transmission-daemon

macOS (Homebrew):

brew install p7zip transmission-cli  # provides transmission-daemon and transmission-remote

Then install the Python dependencies and CLI shim:

uv sync
mkdir -p ~/.local/bin
printf '#!/usr/bin/env bash\nset -euo pipefail\nexec uv run --directory %s python -m hate_crack "$@"\n' "$(pwd)" > ~/.local/bin/hate_crack
chmod +x ~/.local/bin/hate_crack

Project Structure

Core logic is now split into modules under hate_crack/:

  • hate_crack/cli.py: argparse helpers and config overrides.
  • hate_crack/api.py: Hashview, Weakpass, and Hashmob integrations (downloads/menus/helpers).
  • hate_crack/attacks.py: menu attack handlers.
  • hate_crack/corpus_stats.py: whole-corpus password statistics used to describe a corpus to the LLM.
  • hate_crack/plaintext.py: recovers the password from a corpus line (hash-prefix stripping, $HEX[...] decoding); shared by the LLM modes, corpus_stats, and rulegen.
  • hate_crack/llm.py: structured (JSON) LLM candidate generation via Atomic Agents.
  • hate_crack/menu.py: shared menu renderer, including optional arrow-key navigation.
  • hate_crack/noninteractive.py: dispatcher for the scripted attack subcommands.
  • hate_crack/notify/: notification package (Pushover backend, per-crack tailer).
  • hate_crack/username_detect.py: detects username:hash input files to decide on hashcat's --username.
  • hate_crack/formatting.py, hate_crack/progress.py: output formatting and progress display helpers.
  • hate_crack/main.py: main CLI implementation.

The top-level hate_crack.py remains the main entry point and orchestrates these modules.

References and Thanks

This project depends on and is inspired by a number of external projects and services. Thanks to:

Usage

After installing with make, run hate_crack from anywhere:

hate_crack
# or with arguments:
hate_crack <hash_file> <hash_type> [options]

Alternatively, run via uv:

uv run hate_crack.py <hash_file> <hash_type>

Install using make from the repository root - this builds submodules and bundles assets:

cd /path/to/hate_crack
make
hate_crack

The make install command creates a bash shim at ~/.local/bin/hate_crack that runs from the repo directory, so config and assets are always found regardless of your current working directory.

Config is also searched in:

  • The repo root and package directory
  • ~/.hate_crack

Note: The hcatPath in config.json is for the hashcat binary location only (optional if hashcat is in PATH). Hate_crack assets (hashcat-utils, princeprocessor, pcfg_cracker, Corporate_Masks, omen) are loaded from the repository directory and bundled automatically by make install.

Run as a script

The script uses a uv shebang. Make it executable and run:

Read more

Categories

Password CrackingPassword AttacksHash AnalysisPenetration Testing