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

macOS (Homebrew):```bash
brew install hashcat

Wenn Sie ohne Submodule geklont haben, initialisieren Sie diese:```bash
git submodule update --init --recursive

`.env.example` ist eingecheckt und wird mit jedem leeren Credential-Schlüssel ausgeliefert. `.env` selbst darf **niemals** eingecheckt werden — sie ist gitignored, zusammen mit ihren üblichen Backup-Schreibweisen, und hate_crack erstellt sie immer mit Modus `0600` (nur Lese-/Schreibzugriff für den Eigentümer). `.env.example` wird aus dem Schema generiert; regeneriere sie nach Änderungen an `hate_crack/config_schema.py` mit `uv run python -m hate_crack.config_writer`.

### 3. Abhängigkeiten und hate_crack installieren

Der einfachste Weg ist, `make` (oder `make install`) auszuführen, was dein Betriebssystem automatisch erkennt und installiert:
- Externe Abhängigkeiten (p7zip, transmission-daemon / transmission-remote)
- Baut Submodule (hashcat-utils, princeprocessor, pcfg_cracker und optional omen) und checkt das datenreine Corporate_Masks-Maskenset aus
- Python-Abhängigkeiten über uv und ein CLI-Shim unter `~/.local/bin/hate_crack````bash
make

**Oder Abhängigkeiten manuell installieren:**

### Externe Abhängigkeiten
Diese werden für bestimmte Download-/Extraktionsabläufe benötigt:

- `7z`/`7za` (p7zip) — wird zum Entpacken von `.7z`-Archiven verwendet.
- `transmission-daemon` / `transmission-remote` — wird zum Herunterladen von Weakpass-Torrents verwendet.

Manuelle Installationsbefehle:

Ubuntu/Kali:```bash
sudo apt-get update
sudo apt-get install -y p7zip-full transmission-daemon

Dann installiere die Python-Abhängigkeiten und den CLI-Shim:```bash
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

Alternativ dazu über `uv` ausführen:```bash
uv run hate_crack.py <hash_file> <hash_type>

Der Befehl `make install` erstellt einen Bash-Shim unter `~/.local/bin/hate_crack`, der aus dem Repo-Verzeichnis heraus ausgeführt wird, sodass Konfiguration und Assets unabhängig von Ihrem aktuellen Arbeitsverzeichnis immer gefunden werden.

Die Konfiguration wird auch gesucht in:
- Dem Repo-Stammverzeichnis und dem Paketverzeichnis
- `~/.hate_crack`

**Hinweis:** Der `hcatPath` in `config.json` ist nur für den Speicherort der hashcat-Binary (optional, wenn hashcat im PATH ist). Hate_crack-Assets (hashcat-utils, princeprocessor, pcfg_cracker, Corporate_Masks, omen) werden aus dem Repository-Verzeichnis geladen und automatisch durch `make install` mitgeliefert.

### Als Skript ausführen
Das Skript verwendet einen `uv`-Shebang. Machen Sie es ausführbar und führen Sie es aus:```bash
chmod +x hate_crack.py
./hate_crack.py

### Nicht-interaktive / skriptgesteuerte Nutzung

Für die Automatisierung können Sie einen einzelnen Angriff direkt starten und dabei das Menü umgehen. Der Angriffsname ist das erste Argument, gefolgt von der Hash-Datei und dem Hashcat-Hash-Typ. Vorverarbeitungsaufforderungen (Filterung von Computerkonten, LM-First-Brute-Force, Deduplizierung von Doppelkonten) akzeptieren in diesem Modus automatisch ihre Standardwerte. Der Prozess beendet sich mit `0` bei Erfolg und mit einem Wert ungleich null bei einem Fehler (fehlende Hash-Datei, nicht numerischer Hash-Typ, fehlende Wortliste oder ein unbekannter Regeldateiname).```bash
# Quick crack: one wordlist + optional rule(s) from the rules directory
hate_crack quick hashes.txt 1000 --wordlist rockyou.txt --rules best64.rule

# Chain two rules in a single run
hate_crack quick hashes.txt 1000 --wordlist rockyou.txt --rules best64.rule+d3ad0ne.rule

# Run two rules as two separate passes
hate_crack quick hashes.txt 1000 --wordlist rockyou.txt --rules best64.rule d3ad0ne.rule

# Canned dictionary methodology (uses your configured wordlists)
hate_crack dict hashes.txt 1000

# Brute force lengths 1-8
hate_crack brute hashes.txt 1000 --min 1 --max 8

# Top-mask attack targeting ~4 hours
hate_crack topmask hashes.txt 1000 --target-time 4

Dies betrifft Klone, die vor Juli 2026 erstellt wurden. Die veröffentlichte Historie wurde
damals umgeschrieben, um einige Dateien zu entfernen, die niemals hätten committet werden dürfen, wodurch
jeder Commit eine neue ID erhielt; die Tags eines älteren Klons zeigen daher auf Objekte, die dieses
Repository nicht mehr enthält, und git weigert sich, ein Tag zu verschieben, das es bereits hat.
Mit deinem Checkout ist nichts falsch und es sind keine Cracking-Daten gefährdet.

Stelle es mit einem einmaligen Reset wieder her. Dies verwirft lokale Commits und Änderungen im
Checkout. Wenn du also etwas angepasst hast, das von git verfolgt wird (im Gegensatz zu
`config.json`, das nicht verfolgt wird), committe es zuerst in einen Branch:```bash
cd /path/to/hate_crack
git fetch --tags --force origin
git checkout -B main origin/main
make install

Das bedeutet, dass die hate_crack-Assets nicht in das installierte Paket aufgenommen wurden.

**Die Pfade verstehen:**
- `hcatPath` in config.json → verweist auf den **Speicherort der hashcat-Binärdatei** (optional, kann im PATH sein)
- `hashcat-utils/` und `princeprocessor/` → werden durch `make install` in das Paket aufgenommen

**Lösung:**
Neuinstallation mit dem Makefile, das Submodule baut und das Tool installiert:```bash
cd /path/to/hate_crack  # the repository checkout
make install

**Konfigurationsladen:**
- Rangfolge für jeden Schlüssel: `os.environ` > die eigene Home-Datei des Schlüssels (`.env` oder `config.json`) > integrierter Standardwert
- Fehlende Schlüssel fallen auf die integrierten Standardwerte zurück; `config.json.example` dokumentiert jeden `config.json`-Schlüssel
- Beide Dateien werden unabhängig voneinander in dieser Reihenfolge durchsucht: **Repo-Wurzelverzeichnis**, dann das **installierte Paketverzeichnis**, dann **`~/.hate_crack`**. Der erste Treffer gewinnt; es ist normal, dass die beiden Dateien aus unterschiedlichen Verzeichnissen stammen.
- Beim ersten Lauf werden beide erstellt — `config.json` aus `config.json.example`, `.env` aus den integrierten Standardwerten. Wenn eine ältere `config.json` noch Integrationsschlüssel enthält, werden diese in die neue `.env` kopiert und hate_crack teilt Ihnen mit, welche davon aus `config.json` gelöscht werden sollen; die Datei selbst wird niemals bearbeitet.
- Bei jedem Lauf gibt hate_crack die beiden Dateien aus, die tatsächlich geladen wurden:  ```
  [*] config.json: /home/you/.hate_crack/config.json
  [*] .env:        /home/you/.hate_crack/.env

Der Standardbranch wurde von `master` in `main` umbenannt. Behebe das mit:```bash
git remote set-head origin -a
git branch -m master main
git branch --set-upstream-to=origin/main main
git pull

Dies ist idempotent - bereits installierte Tools werden übersprungen.

**Erzwungene saubere Neuinstallation:**```bash
make reinstall

**Deinstallieren** – entfernt Betriebssystem-Abhängigkeiten und das Tool:```bash
make uninstall

**Tests ausführen** – behandelt HATE_CRACK_SKIP_INIT bei Bedarf automatisch:```bash
make test

**Bereinigen von Build-/Test-Artefakten:**```bash
make clean

### Linter und Typprüfungen ausführen

Bevor Sie Änderungen pushen, führen Sie diese Prüfungen lokal aus. Verwenden Sie `make lint` für alles oder führen Sie einzelne Prüfungen aus:

**Ruff (Linting und Formatierung):**```bash
make ruff
# or manually:
uv run ruff check hate_crack tests tools packaging hate_crack.py

**ty (Typüberprüfung):**```bash
make ty
# or manually:
uv run ty check hate_crack

### Tests ausführen

Tests erkennen automatisch, wenn Submodule nicht gebaut wurden, und setzen `HATE_CRACK_SKIP_INIT=1` automatisch.```bash
make test

Mit Abdeckung:```bash
make coverage

### Git Hooks (prek)

Git-Hooks werden von [prek](https://github.com/j178/prek) (v0.3.3+) verwaltet. Hooks installieren mit:```bash
prek install --hook-type pre-push --hook-type pre-commit

Menüoptionen:
- **(1) Upload Cracked Hashes** - Hochgeladene geknackte Ergebnisse aus der aktuellen Sitzung zu Hashview hochladen
- **(2) Upload Wordlist** - Eine Wordlist-Datei zu Hashview hochladen
- **(3) Download Wordlist** - Eine Wordlist von Hashview herunterladen
- **Download Rule** - Eine Regeldatei von Hashview herunterladen (dekomprimiert zu Klartext, bereit für `hashcat -r`). Geben Sie `a` (oder `all`) an der Regel-ID-Eingabeaufforderung ein, um jede aufgelistete Regel statt einer einzelnen herunterzuladen
- **Download All Rules** - Jede von Hashview aufgelistete Regeldatei in einem Durchgang herunterladen; Fehler bei einzelnen Regeln werden gemeldet, ohne den Rest abzubrechen
- **(4) Download Left Hashes** - Verbleibende ungeknackte Hashes herunterladen (fragt nach, um zum Knacken zu wechseln)
- **(5) Download Found Hashes** - Bereits geknackte Hashes mit Klartext-Passwörtern herunterladen (zur Referenz/Analyse)
- **(6) Upload Hashfile and Create Job** - Neue Hashdatei hochladen und einen Knack-Job erstellen
- **(99) Back to Main Menu** - Zum Hauptmenü zurückkehren

**Wichtig: Download Found vs Download Left**
- **Download Left Hashes (4)**: Lädt ungeknackte Hashes herunter, die geknackt werden müssen. Führt automatisch eine Zusammenführung mit allen gefundenen Hashes durch, falls verfügbar, und fragt nach, um zu dieser Hashdatei zum Knacken zu wechseln.
- **Download Found Hashes (5)**: Lädt bereits geknackte Hashes im Format hash:cleartext herunter. Diese dienen als Referenz und können nicht weiter geknackt werden. Es wird keine Wechselaufforderung angezeigt.

#### Kommandozeilenschnittstelle

Hashview-Operationen können auch über die Kommandozeile ausgeführt werden:

Geknackte Hashes hochladen:```bash
hate_crack.py --hashview upload-cracked --file <output_file>.out --hash-type 1000

Laden Sie eine Regeldatei herunter (dekomprimiert gespeichert, bereit für `hashcat -r`):```bash
hate_crack.py --hashview download-rules --rules-id 4 --output best64.rule

Heruntergeladene gefundene Hashes (bereits geknackte Hashes mit Klartext):```bash
hate_crack.py --hashview download-found --customer-id 1 --hashfile-id 123

#### Konfiguration

Legen Sie die Hashview-Anmeldedaten in `.env` fest (es handelt sich um Integrationseinstellungen, daher befinden sie sich nicht in `config.json`):```
HASHVIEW_URL=https://hashview.example.com
HASHVIEW_API_KEY=your-api-key-here
HASHVIEW_VERIFY_TLS=true

**Die unten aufgeführten `OLLAMA_*`-Schlüssel gelten für jedes Backend, nicht nur für Ollama.** Sie behalten dieses Präfix, weil `OLLAMA_HOST` dieselbe Variable ist, die auch Ollamas eigene CLI liest, und eine Umbenennung jedes bestehende `.env` ohne funktionalen Gewinn brechen würde — ein vLLM- oder OpenAI-kompatibler Server möchte denselben Host, dasselbe Modell, denselben Timeout, Kontext und dieselben Sampling-Parameter unter denselben Namen. `LLM_BACKEND` wählt lediglich aus, wie die Anfrage geformt wird.

- **`OLLAMA_MODEL`** — Das Ollama-Modell, das für die Kandidatengenerierung verwendet wird (Standard: `qwen3:4b-instruct`). Der LLM-Angriff verwendet strukturierte (JSON-)Ausgabe, wählen Sie daher ein Modell mit guter Tool-/JSON-Unterstützung.
- **`OLLAMA_NUM_CTX`** — Größe des Kontextfensters für das Modell (Standard: `8192`). Dies war `2048`, bevor die Korpus-Statistiken eingeführt wurden, was zu klein war, um den Prompt aufzunehmen, der ihm übergeben wurde: 500 gesampelte Klartexte umfassen grob 2.000–3.500 Token vor dem System-Prompt und der Antwort, sodass Ollama stillschweigend einen Teil der Stichprobe abschnitt, die der Sampler sorgfältig über die Datei verteilt hatte.
- **`OLLAMA_TIMEOUT`** — Sekunden, die auf eine Generierungsantwort gewartet wird, bevor aufgegeben wird (Standard: `300`). Erhöhen Sie diesen Wert, wenn ein großes Modell bei der ersten Anfrage noch in den VRAM geladen wird, was andernfalls den Timeout überschreiten kann; hate_crack gibt den verstrichenen Timeout und den Namen dieser Einstellung aus, wenn er ausgelöst wird.
- **`OLLAMA_MAX_SAMPLE_LINES`** — Der Schwellenwert, unterhalb dessen die LLM-Modi auch die wörtlichen Klartexte in den Prompt einfügen (Standard: `500`). Werte ≤ 0 werden als 500 behandelt.

  Korpus-abgeleitete Modi (**Wordlist**, **Cracked passwords**, **Pattern rules**) beschreiben den *gesamten* Korpus stets statistisch — Basiswort-Anteile, Masken, Groß-/Kleinschreibung, Längen, nachgestellte Ziffern und Symbole, Jahre — anstatt einen Ausschnitt davon einzufügen. Die Aggregation ist begrenzt, sodass ein Dump mit 120.000 Passwörtern etwa denselben Prompt-Platz beansprucht wie einer mit 500 Zeilen. Wenn der gesamte Korpus unter diesen Schwellenwert passt, werden die Roh-Klartexte ebenfalls einbezogen, da nichts gewonnen wird, wenn man dem Modell einen kleinen Korpus vorenthält.

  Dies ersetzt das vorherige Verhalten, eine gleichmäßig verteilte Stichprobe von bis zu `ollamaMaxSampleLines` Passwörtern einzufügen. Eine Stichprobe eines großen Dumps vermittelte überhaupt keine Häufigkeitsinformationen: Das Modell konnte ein Basiswort, das von 8 % der Organisation verwendet wird, nicht von einem unterscheiden, das von einer einzigen Person verwendet wird — genau das Signal, das einen Rateversuch wert macht.
- **`OLLAMA_NO_CLOUD`** — Wenn `true`, wird verweigert, irgendetwas von diesem Host zu senden, für jedes der drei LLM-Backends (Ollama, vLLM oder einen generischen OpenAI-kompatiblen Server). Zwei Prüfungen werden durch diese eine Einstellung gesteuert: Ollama leitet ein mit `-cloud` gekennzeichnetes Modell (`gpt-oss:120b-cloud`, `deepseek-v3.1:671b-cloud`) über denselben lokalen Endpunkt, den ein lokales Modell verwendet, an ollama.com weiter, sodass an der Anfrage nichts anders aussieht — dies wird anhand des Modellnamens verweigert. Die konfigurierte Backend-URL wird ebenfalls geprüft: Ein Ziel, das nicht Loopback, privat oder Link-Local ist (und nicht `localhost` oder ein `.local`/`.internal`/`.lan`/`.localdomain`-Name ist), wird anhand des Ziels verweigert, und ein Hostname, den diese Prüfung nicht auflösen kann, wird ebenfalls verweigert, fail-closed, anstatt ein nicht verifizierbares Ziel durchzulassen. Die Prompts von hate_crack enthalten wiederhergestellte Klartexte, Korpus-Statistiken sowie den Namen, die Branche und den Standort des Kunden, sodass bei Auslösung einer der beiden Prüfungen die Anfrage verweigert wird, bevor sie erstellt wird. Standardmäßig `false`, sodass ein bewusst konfiguriertes Cloud-Modell oder ein Remote-Server weiterhin funktioniert; aktivieren Sie es für Engagements, bei denen Kundendaten den Host nicht verlassen dürfen.
- **`OLLAMA_AUTO_RESEARCH`** — Wenn `true` (Standard), bittet der Modus **Target info** das lokale Modell, die Branche, den Standort und die Muttergesellschaft / Übernahmehistorie vorzuschlagen, sobald Sie den Firmennamen eingegeben haben, und bietet sie als bearbeitbare Prompt-Standardwerte an. Auf `false` setzen, um immer leere Prompts zu erhalten (nützlich bei einem langsamen Modell, da die Recherche einen zusätzlichen Round-Trip kostet, bevor der Angriff beginnt).
- **`OLLAMA_HOST`** — Wo das konfigurierte Backend lauscht. Akzeptiert ein bloßes `host:port` (`theplague.lan:11434`) oder eine vollständige URL mit Schema (`https://ollama.example.com`); in beiden Fällen wird die Basis-URL vor der Verwendung normalisiert. Standardmäßig `localhost:11434`, was Ollamas Port ist — ein vLLM- oder OpenAI-kompatibler Server benötigt hier seinen eigenen (vLLM lauscht üblicherweise auf `:8000`). Legen Sie ihn in `.env` fest oder exportieren Sie ihn als echte Umgebungsvariable, um das für einen einzelnen Lauf zu überschreiben — es ist derselbe Variablenname, den Ollamas eigene CLI liest.
- **`LLM_BACKEND`** — Mit welchem OpenAI-kompatiblen Server gesprochen wird: `ollama` (Standard), `vllm` oder `openai` für einen generischen. Jedes Backend spricht dieselbe `/v1`-Chat-Completions-API, sodass dies nur die beiden Details der Anfrageformung auswählt, in denen sie sich unterscheiden: `ollama` erhält `options.num_ctx`, und `vllm` erhält `chat_template_kwargs={"thinking": false}` — ohne das ein vLLM-Server, der einen Reasoning-Parser ausführt, die gesamte strukturierte Antwort in `message.reasoning` leitet, `message.content` leer lässt und die JSON-Analyse bricht. `openai` sendet keines von beiden, da `num_ctx` dort kein Äquivalent hat. Es ändert **nicht**, woher die Host-, Modell-, Timeout-, Kontext- oder Sampling-Einstellungen stammen — das sind die obigen `OLLAMA_*`-Schlüssel für alle drei.
- **`LLM_API_KEY`** — Die Anmeldedaten, die an das konfigurierte Backend gesendet werden. Standardmäßig der Literalwert `ollama`, der Platzhalter, den Ollamas eigener Server ignoriert, sodass die Anfragen einer bestehenden Installation unverändert bleiben; ein leerer Wert fällt auf denselben Platzhalter zurück, weil das OpenAI SDK `api_key=""` verweigert. Legen Sie ihn auf den echten Wert fest, wenn der Server einen erzwingt — ein mit `--api-key` gestarteter vLLM-Server gibt andernfalls 401 zurück.
- Stellen Sie sicher, dass Ollama läuft und das Modell heruntergeladen ist (`ollama pull qwen3:4b-instruct`), bevor Sie den LLM Attack verwenden — hate_crack lädt fehlende Modelle nicht mehr automatisch herunter.

Der Angriff bietet drei Generierungsmodi:

1. **Target info** — Firma / Branche / Standort / Muttergesellschaft; das Modell leitet Kandidaten aus diesen Angaben ab.

   Nachdem Sie den Firmennamen eingegeben haben, fragt hate_crack dasselbe lokale Modell, was es bereits über diese Organisation weiß, und füllt die Prompts **Industry**, **Location** und **Parent Company** mit den Antworten vor, die in Klammern angezeigt werden:   ```
   Company name: Acme Rail Services

   [!] The values in parentheses below are the local model's GUESSES, not verified OSINT.
       Press Enter to accept, or type your own value to override.
   Industry (freight rail maintenance):
   Location (Omaha, Nebraska):
   Parent company / acquired by:

Ein Recherchefehler — Timeout, Ollama läuft nicht, leere Antwort — blockiert den Angriff nie; er fällt einfach auf leere Prompts zurück. Setze `ollamaAutoResearch` auf `false`, um die Recherche vollständig zu überspringen.
2. **Wortliste** — Basiswörter aus einer Beispiel-Wortliste ableiten.
3. **Geknackte Passwörter** — die in dieser Sitzung bereits wiederhergestellten Klartexte (`<hashfile>.out`) zurück an das Modell geben, damit es die eigenen Passwortkonventionen der Zielorganisation (Basiswörter, Jahreszeiten, Jahre, Suffixe, Leetspeak) ableiten und *neue* Kandidaten im selben Stil generieren kann. Diese Option wird erst aufgeführt, sobald mindestens ein Hash geknackt wurde; die gesamte Datei wird statistisch genau wie im Wortlisten-Modus analysiert (siehe `ollamaMaxSampleLines` oben).

#### PCFG-Konfiguration

Der PCFG-Angriff (Option 20) und der PRINCE-LING-Angriff (Option 21) verwenden das `pcfg_cracker`-Submodul. Konfiguriere sie in `config.json`:```json
{
"pcfgRuleset": "DEFAULT",
"pcfgMaxCandidates": 50000000,
"pcfgPrinceLingMaxCandidates": 10000000
}

Antworte `Y` und hate_crack erstellt eine temporäre Regeldatei, die nur die noch nicht versuchten Einträge enthält; antworte `n`, um trotzdem alles auszuführen. Wenn *jeder* Eintrag eine Wiederholung ist, wirst du gefragt, ob der Angriff ganz übersprungen werden soll, sodass ein absichtliches erneutes Ausführen bereits abgedeckter Bereiche niemals einen Neustart des Tools erfordert.

Angriffe, die niemals gefiltert werden, werden dennoch als ausgeführt erfasst, was dir die Frage „Habe ich PRINCE bereits gegen dieses Ziel ausgeführt?" beantworten lässt.

Ein Angriff, der mehrere Regeldateien gleichzeitig auswählt (Quick Crack, Loopback), stellt die Überspringfrage **einmal für den gesamten Stapel, im Voraus**, bevor irgendein hashcat-Aufruf erfolgt. Diese Frage ist bewusst günstig — sie liest oder hasht keine der ausgewählten Regeldateien, da ein YOLO-Stapel Millionen von Zeilen umfassen kann und du nicht darauf warten solltest, um ein Ja/Nein zu beantworten. Sie fragt den Speicher nur, ob dieser Angriff bereits gegen diese Hash-Datei **mit einer dieser Wortlisten** ausgeführt wurde; der Diff pro Eintrag erfolgt weiterhin verzögert, eine Regeldatei nach der anderen, und entscheidet, was tatsächlich übersprungen wird. Ein frischer Korpus wird also nie markiert, selbst wenn die Regeln darauf alle gegen einen anderen ausgeführt wurden.

Drei bewusste Einschränkungen:

- **Die Abdeckung wird nur erfasst, wenn hashcat den Keyspace erschöpft** (Exit 1). Ein Strg-C oder ein Fehler erfasst nichts, und Exit 0 ebenso wenig — das bedeutet, dass jeder Hash geknackt wurde, was hashcat *ohne* Abschluss des Keyspace meldet, und im degenerierten Fall „alle Hashes als Potfile-Einträge gefunden" ohne einen einzigen Kandidaten zu versuchen. Eine Untererfassung kostet nur einen redundanten Lauf später.
- **Dynamische Kandidatengeneratoren werden niemals gefiltert.** PRINCE, PCFG, OMEN, Markov-Brute-Force und die LLM-Modi haben keine feste Menge zum Diffen, also werden sie als ausgeführt protokolliert und ansonsten in Ruhe gelassen. Verkettete Regeldateien (`-r a -r b`) werden als eine Einheit verfolgt statt pro Eintrag, weil hashcat das *kartesische Produkt* der beiden Dateien anwendet und das Weglassen einer einzelnen Zeile stillschweigend jede Kombination entfernen würde, an der sie beteiligt war.
- **`--loopback`-Läufe werden erfasst, aber niemals gefiltert.** hashcat speist frisch geknackte Klartexte als *zusätzliche* Kandidaten wieder ein, sodass ein solcher Lauf die vollständige Wortliste und den vollständigen Regelsatz plus alles, was diese recycelten Klartexte erreichen, versucht. Das macht die beiden Richtungen asymmetrisch: Ihn zu erfassen ist korrekt, sodass ein späterer gewöhnlicher Lauf derselben Wortliste und Regeln korrekt als Wiederholung erkannt wird, aber ein zweiter Loopback-Lauf hat mehr Cracks zum Recyceln und wird niemals übersprungen.

Setze `coverage_enabled` in `config.json` auf `false`, um dies abzuschalten, oder übergib `--no-coverage` für einen einzelnen Lauf — was den Speicher weder konsultiert noch aktualisiert.

#### Abdeckung inspizieren und zurücksetzen

Die Hauptmenü-Option **85 — Attack Coverage** zeigt, was gegen die geladene Hash-Datei ausgeführt wurde, ihre Ausführungshistorie, und kann sie löschen. Dieselben drei Aktionen sind skriptbar:```bash
# What has already been run against this hash file?
hate_crack coverage status --hashfile hashes.txt

# Every attack that has run against it, oldest first
hate_crack coverage history --hashfile hashes.txt

# Start over for this hash file only (prompts unless --yes)
hate_crack coverage forget --hashfile hashes.txt --yes

Exit 3 bedeutet, dass *nichts* ausgeführt wurde. Ein Durchlauf, der teilweise gefiltert wurde — einige Einträge übersprungen, einige versucht — beendet sich trotzdem mit `0`, weil der Angriff tatsächlich Arbeit verrichtet hat.

### hashcat-Brain-Unterstützung (`brain_enabled`)

hashcat selbst bringt ein „Brain" mit — einen kleinen Server, an den eine laufende hashcat-Instanz Kandidatenpasswörter streamt, sodass ein zweiter Durchlauf gegen dasselbe Ziel Kandidaten überspringen kann, die der erste bereits versucht hat. hate_crack aktiviert es automatisch, ohne dass ein Menüschritt erforderlich ist: Wann immer es einen Angriff gegen einen Hash-Modus starten will, den hashcat als langsam meldet (bcrypt, scrypt und andere KDF-gestützte Modi, bei denen der Hash selbst der Engpass ist und nicht die Kandidatengenerierung), startet oder verwendet es einen lokalen Brain-Server wieder und fügt die `--brain-*`-Flags für Sie zur hashcat-Aufrufzeile hinzu. Ein schneller Modus bleibt unangetastet, es sei denn, seine Modusnummer ist in `brain_modes_force` aufgeführt, und ein in `brain_modes_exclude` aufgeführter Modus aktiviert niemals Brain, unabhängig vom Urteil von hashcat selbst — exclude gewinnt immer.

**Brain ist nicht dasselbe wie Angriffsabdeckung, und die beiden sind komplementär statt redundant.** Die Abdeckung (oben) dedupliziert auf der Ebene ganzer Regeln, Maskenzeilen und Wortlisten — sie entscheidet, was überhaupt gestartet wird, bevor hashcat jemals läuft. Brain dedupliziert auf der Ebene einzelner Kandidatenpasswörter, und zwar über einen persistenten Server, der jede einzelne hashcat-Ausführung überlebt, sodass es Überschneidungen erfasst, die die Abdeckung nicht sehen kann: einen Kandidaten, der über zwei verschiedene Regeln oder zwei verschiedene Wortlisten innerhalb desselben Durchlaufs erreichbar ist, und — wie der Roundtrip in `tests/e2e/test_brain_e2e.py` demonstriert — dieselben Kandidaten, die in einem zweiten, separaten hashcat-Durchlauf gegen dasselbe Ziel erneut gesendet werden. Beide können gleichzeitig ohne Konflikt aktiviert werden.

Sieben Schlüssel in `config.json` steuern es, alle unter dem Präfix `brain_*`: `brain_enabled` (Hauptschalter, standardmäßig an), `brain_host` (leer bedeutet, hate_crack verwaltet einen lokalen Server auf Loopback; ein Wert bedeutet, nur mit diesem Host zu verbinden — hate_crack startet niemals einen Server, dessen Verwaltung ihm nicht aufgetragen wurde), `brain_port` (Standard `6863`), `brain_client_features` (`1` gehashte Passwörter, `2` Angriffspositionen, `3` beides — `3` dedupliziert am meisten, kostet den Server aber etwa 12 Byte RAM pro gesehenem Kandidaten), `brain_server_timer` (hashcats eigene Einstellung dafür, wie oft der Server seinen `.ldmp`/`.admp`-Dump auf die Festplatte schreibt, Minimum 60 Sekunden, Standard `300`) und `brain_modes_force` / `brain_modes_exclude` (kommagetrennte Hash-Modus-Nummern, die hashcats eigenes Langsam/Schnell-Urteil überschreiben, wobei exclude Vorrang hat).

**Der automatisch gestartete Server hat überhaupt keinen Idle-Timeout.** `brain_server_timer` steuert nicht, wie lange er läuft — nichts tut das; er läuft für die Lebensdauer des Prozesses, der ihn gestartet hat (oder bis `shutdown()`/`atexit` ihn stoppt) und wird über jeden Angriff in der Sitzung hinweg wiederverwendet. Beim Standardwert `300` bedeutet das einen Dump-Schreibvorgang nach `~/.hate_crack/brain/` alle fünf Minuten, solange hate_crack läuft.

Ein achter Schlüssel, `BRAIN_PASSWORD`, liegt in `.env` statt in `config.json`, weil er ein gemeinsames Geheimnis ist, nicht weil Brain eine Drittanbieter-Integration wäre — er wird nur beim Verbinden mit einem entfernten Brain-Server verwendet, den Sie bereits betreiben; der automatisch gestartete lokale Server generiert sein eigenes zufälliges Passwort pro Sitzung und benötigt keine Konfiguration.

**Das Brain-Passwort ist für `ps` während der gesamten Laufzeit des hashcat-Durchlaufs sichtbar,** weil hashcat es nur als Kommandozeilenargument akzeptiert — es gibt keine Umgebungsvariablen-Form. Für den lokalen automatisch gestarteten Server ist dies ein kleines Zeitfenster: Das Passwort ist zufällig und auf diese eine Sitzung beschränkt, sodass ein anderer lokaler Benutzer es nur sehen kann, während tatsächlich ein Angriff läuft, und es ist nutzlos, sobald die Sitzung endet. Das Passwort eines gemeinsam genutzten entfernten Brain-Servers hat keine solche Abschwächung — es ist bei jedem Aufruf derselbe Wert, sichtbar für jeden anderen lokalen Benutzer auf dem Rechner, solange ein hate_crack-Durchlauf gegen diesen Server läuft. Behandeln Sie es entsprechend auf gemeinsam genutzter oder Multi-Tenant-Hardware.

Übergeben Sie `--no-brain`, um Brain für einen einzelnen Durchlauf unabhängig von `brain_enabled` zu deaktivieren, oder setzen Sie `brain_enabled` in `config.json` auf `false`, um es überall auszuschalten.

**Brain hält seinen Zustand in `~/.hate_crack/brain/`** — ein kleiner `slow_modes.json`-Cache von hashcats eigenem Langsam/Schnell-Urteil pro hashcat-Version, plus, für den automatisch gestarteten Server, dessen `.ldmp`/`.admp`-Dump-Dateien. Diese Dumps sind kandidatenabgeleitetes Material: Sie ermöglichen es einem frischen Server fortzusetzen, wissend, was bereits gegen ein Ziel versucht wurde, was bei einem Engagement bedeutet, dass client-abgeleitete Daten im Home-Verzeichnis des Operators akkumulieren, solange Brain dort jemals gelaufen ist. Wie beim Abdeckungsspeicher oben setzt das Löschen des Verzeichnisses Brain zurück — ein zuvor abgelehnter Kandidat wird nicht mehr erinnert, auf Kosten des Verlusts der Deduplizierung, die dieser Dump darstellte. Wenn Brain Arbeit zu überspringen scheint, die es nicht überspringen sollte (ein veralteter Dump aus einem früheren, anders abgegrenzten Durchlauf), ist dies die Lösung.

**Das Löschen von `~/.hate_crack/brain/` beseitigt keinen verwaisten Server.** Der automatisch gestartete Server läuft in seiner eigenen Sitzung (`start_new_session=True`), sodass er ein geschlossenes Terminal oder ein SIGHUP überlebt — nur ein expliziter Kill oder das saubere Beenden des Prozesses, der ihn gestartet hat, und die Ausführung seines `atexit`-Handlers stoppt ihn. Ein Waise hält weiterhin den Loopback-Port. Mit dem standardmäßig leeren `BRAIN_PASSWORD` werden Sie es als `"[!] ... no brain server could be reached; running without candidate de-duplication"` bei jedem Langsam-Modus-Angriff bemerken: Das Passwort des Waisen war flüchtig und starb mit dem Prozess, der es generiert hat, sodass hate_crack sich weigert, den Port zu übernehmen, auf dem er sitzt, anstatt ein Passwort zu raten, das nicht verifiziert werden kann. Finden und stoppen Sie ihn mit:```bash
pgrep -f 'hashcat --brain-server'
kill <pid>

- **`check_for_updates`** — Aktiviert automatische Versionsprüfungen beim Start (Standard: `true`).
- Wenn aktiviert, ruft hate_crack die neuesten Release-Informationen von GitHub ab und zeigt einen Hinweis an, wenn ein Update verfügbar ist.
- Die Prüfung läuft asynchron und blockiert den Start nicht. Netzwerkfehler werden stillschweigend ignoriert.

##### Update-Kanäle

| Kanal | Flag | Quelle | Was Sie erhalten |
|---------|------|--------|--------------|
| Release | `--update` | `main` | Das neueste veröffentlichte Release. Dies ist der Standard und das, was die Startprüfung anbietet. |
| Nightly | `--nightly` | `nightly-dev` | Arbeit, die CI bestanden hat, aber noch nicht veröffentlicht wurde. |

Versionen folgen dem üblichen Semver, wobei die Erhöhung davon abgeleitet wird, was tatsächlich im
Batch enthalten ist. Die zweite Komponente ändert sich **nur bei Features**: Ein Zyklus, der
einen `feat`-Commit enthält, steuert auf `X.(Y+1).0` zu, und ein Zyklus, der nur aus Fixes,
Docs und Chores besteht, steuert auf `X.Y.(Z+1)` zu.

`nightly-dev` taggt Release-Kandidaten für die Version, auf die der Batch zusteuert
— `v2.20.1rc1`, `v2.20.1rc2`, … — und das Mergen nach `main` befördert dasselbe
Ziel zu seiner finalen Veröffentlichung. Kandidaten sind echte PEP 440 Pre-Releases, sodass
sie an beiden Enden korrekt sortiert werden:

    2.20.0  <  2.20.1rc1  <  2.20.1rc2  <  2.20.1  <  2.21.0rc1  <  2.21.0

Das Ziel kann sich mitten im Zyklus ändern: Das erste `feat`, das landet, verschiebt es von
`X.Y.(Z+1)` zu `X.(Y+1).0`, und die Kandidatennummerierung beginnt für das neue Ziel neu.
Die Nummer benennt immer, was der Batch heute veröffentlichen würde.

Die Hauptkomponente wird niemals automatisch erhöht — ein `!`-Subject oder ein
`BREAKING CHANGE:`-Footer zählt als Feature, denn ein automatischer Major ist nur
eine falsch eingegebene Subject-Zeile von einer irreversiblen veröffentlichten Version entfernt. Ein Major ist ein
expliziter menschlicher Akt: Tag und Push von Hand.

Die Richtlinie lebt in `tools/next_version.py`, wird von beiden Tagging-Workflows geteilt und
in `tests/test_next_version.py` unit-getestet.

Die Startprüfung bietet nur Releases an, da Nightly-Builds überhaupt kein
GitHub-Release veröffentlichen und die Prüfung den "latest release"-Endpunkt von GitHub liest — also
wird das Aktivieren von `check_for_updates` Sie niemals auf ein Nightly ziehen. Zwei Dinge halten
die Kanäle jetzt auseinander: das, und die Tatsache, dass ein Kandidat ein echtes PEP 440
Pre-Release ist, sodass ein Tool, das rohe Versionsnummern vergleicht, es ebenfalls als älter behandelt als
das Release, zu dem es wird.

Beide Flags wechseln zuerst Ihren Checkout zum entsprechenden Branch (und
verweigern dies, wenn Sie nicht committete Änderungen haben). Wenn Sie ein Nightly ausführen
und zum veröffentlichten Code zurückkehren möchten, bringt Sie `--update` zurück zu `main`.

#### Automatisches Zusammenführen gefundener Hashes (nur Download Left)

Beim Herunterladen von Left-Hashes (ungeknackte Hashes) führt hate_crack automatisch Folgendes aus:
1. Versucht, alle gefundenen (geknackten) Hashes von Hashview als Hilfsoperation herunterzuladen
2. Führt gefundene Hashes mit lokalen `.out`-Dateien zusammen (z. B. `left_1_123.txt.out` oder `left_1_123.nt.txt.out` für das pwdump-Format)
3. Entfernt doppelte Einträge
4. Bereinigt temporäre Split-Dateien nach dem Zusammenführen

Dies stellt sicher, dass Ihre lokalen Knack-Ergebnisse mit der zentralisierten Datenbank von Hashview synchronisiert bleiben, wenn Sie mit ungeknackten Hashes arbeiten.

**Hinweis:** Die Download-Found-Option lädt bereits geknackte Hashes separat zu Referenzzwecken herunter und führt weder ein Zusammenführen durch noch fordert sie zum Knacken auf.

Der <hash_type> wird durch Ausführen von `hashcat --help` ermittelt.

Beispiel-Hashes: http://hashcat.net/wiki/doku.php?id=example_hashes```
$ hashcat --help |grep -i ntlm
   5500 | NetNTLMv1                                        | Network protocols
   5500 | NetNTLMv1 + ESS                                  | Network protocols
   5600 | NetNTLMv2                                        | Network protocols
   1000 | NTLM                                             | Operating-Systems

-------------------------------------------------------------------
## Tests

Die Testsuite ist größtenteils offline und verwendet Mocks/Fixtures. Live-Netzwerkprüfungen und Prüfungen der Systemabhängigkeiten sind optional über Umgebungsvariablen aktivierbar.

### Tests lokal ausführen```bash
# Run all tests
uv run pytest -v

# Run specific test
uv run pytest tests/test_hashview.py -v

### Live-Hashview-Tests gegen einen lokalen Docker-Stack

Anstatt die Live-Tests auf einen entfernten Hashview-Server zu richten, können Sie
die Suite einen lokalen [Hashview](https://github.com/hashview/hashview)
Docker-Stack hochfahren, ihn befüllen, die Live-Tests dagegen ausführen und ihn
wieder abbauen lassen. Setzen Sie
`HASHVIEW_TEST_LOCAL=1` und richten Sie `HASHVIEW_REPO` auf einen Hashview-Checkout:```bash
HASHVIEW_TEST_LOCAL=1 HASHVIEW_REPO=~/projects/hashview \
  HATE_CRACK_SKIP_INIT=1 uv run pytest tests/test_hashview_cli_subcommands_subprocess.py -v

Docker-basierte End-to-End-Installation/Ausführung (gecacht über `Dockerfile.test`):```bash
HATE_CRACK_RUN_DOCKER_TESTS=1 uv run pytest tests/test_docker_script_install.py -v

Die Test-VM wird automatisch mit allen Linux-Abhängigkeiten bereitgestellt (hashcat, build-essential, curl, git, gzip, p7zip-full, transmission-daemon, ocl-icd-libopencl1, pocl-opencl-icd, uv).```bash
HATE_CRACK_RUN_LIMA_TESTS=1 uv run pytest tests/test_lima_vm_install.py -v

Welche Regel(n) möchtest du ausführen?
(1) best64.rule
(2) d3ad0ne.rule
(3) T0XlC.rule
(4) dive.rule
(99) YOLO...alle Regeln ausführen
Gib eine kommagetrennte Liste der Regeln ein, die du ausführen möchtest. Um Regeln verkettet auszuführen, verwende das +-Symbol.
Zum Beispiel führt 1+1 best64.rule zweimal verkettet aus und 1,2 würde best64.rule und dann d3ad0ne.rule nacheinander ausführen.
Wähle mit Bedacht:```




#### Extensive Pure_Hate Methodology Crack
Runs several attack methods provided by Martin Bos (formerly known as pure_hate):
  * Brute Force Attack (7 characters)
  * Dictionary Attack
    * All wordlists in `hcatWordlists` with `best64.rule`
    * `rockyou.txt` with `d3ad0ne.rule`
    * `rockyou.txt` with `T0XlC.rule`
  * Top Mask Attack (Target Time = 4 Hours)
  * Fingerprint Attack
  * Smart Mask Attack
  * Combinator Attack
  * Hybrid Attack
  * Extra - Just For Good Measure
    - Runs a dictionary attack using `rockyou.txt` with chained `combinator.rule` and `InsidePro-PasswordsPro.rule` rules

#### Brute Force Attack
Brute forces all characters with the choice of a minimum and maximum password length.

#### Top Mask Attack
Uses StatsGen and MaskGen from PACK (https://thesprawl.org/projects/pack/) to perform a top mask attack using passwords already cracked for the current session.
Presents the user a choice of target cracking time to spend (default 4 hours).

#### Fingerprint Attack
https://hashcat.net/wiki/doku.php?id=fingerprint_attack

Runs a fingerprint attack using passwords already cracked for the current session. Expander substring length escalates automatically (7, 14, 21, ... up to the chosen ceiling), and an optional wordlist can be combined against the expanded fragments in addition to self-combination. Set `hcatFingerprintWordlist` in `config.json` to a default wordlist path so the prompt offers it instead of asking for a path every time; leave it as `""` to always ask (or skip).

#### Smart Mask Attack
Looks for literal "skeleton" patterns shared by 3+ already-cracked passwords for the current session -- e.g. a fixed stem like `CrawlingHorse` followed by a run of digits, or `ChangeMe2day` followed by digits and symbols drawn from a consistent charset. Every qualifying pattern runs against the full remaining hash list, so other accounts sharing a stem get swept up even though brute-forcing the stem itself was never tried.

Patterns with a fixed run at either end -- nearly all of them -- are grouped by mask and run as hybrid attacks (`-a 6` when the mask trails the stem, `-a 7` when it leads), with every pattern's literal stem a line in that group's wordlist. Dozens of patterns that vary the same way therefore become one hashcat pass over one wordlist rather than one mask line each. Whatever cannot be grouped that way -- variation at *both* ends, which leaves no fixed run to seed a wordlist with -- falls back to a single `-a 3` mask file, and has its charsets widened (up to `?a`) to compensate, as far as the guardrail below allows.

Prompts once, before the attack starts, for an optional per-pattern candidate-count guardrail (default 50,000,000,000; 0 disables it) that excludes any individual pattern whose keyspace is too large without blocking the rest.

#### Combinator Attack
https://hashcat.net/wiki/doku.php?id=combinator_attack

Runs a combinator attack using the "rockyou.txt" wordlist.

#### Hybrid Attack
https://hashcat.net/wiki/doku.php?id=hybrid_attack

* Runs sixteen hybrid passes per wordlist, cheapest first. Each mask length
  from 1 to 4 is tried appended and then prepended, first over `?s?d` and then
  over `?a`, and a single ctrl-C abandons the whole attack rather than only the
  current pass.
  - Hybrid Wordlist + Mask - ?s?d wordlists/rockyou.txt ?1
  - Hybrid Mask + Wordlist - ?s?d ?1 wordlists/rockyou.txt
  - ... the same for ?1?1, ?1?1?1 and ?1?1?1?1
  - Hybrid Wordlist + Mask - wordlists/rockyou.txt ?a
  - Hybrid Mask + Wordlist - ?a wordlists/rockyou.txt
  - ... the same for ?a?a, ?a?a?a and ?a?a?a?a

  `?a` is every printable character, so the second group is a superset of the
  first plus letters and roughly 24x the work at the longest mask — over
  rockyou.txt those passes alone are ~1.2e15 candidates, about ten hours for
  NTLM on hardware doing 32 GH/s. That is why the cheap `?s?d` group runs first
  and why the attack as a whole is time-bounded:

  - `hcatHybridMaxRuntime` in `config.json`, in seconds, default `3600`, is the
    time the **whole attack** may spend — not the time one pass may spend. All
    sixteen passes share one deadline, and each is handed whatever is left of it
    as hashcat's `--runtime`. Any pass the budget does not reach is reported
    rather than skipped quietly. Set it to `0` for no limit, which runs every
    pass to exhaustion.

  Within each group the order is by mask length across every wordlist rather
  than all lengths of one wordlist and then the next, so a budget that runs out
  has still given every wordlist its cheap passes.

  Each pass declares what it covers to the attack-coverage store, so a repeat
  hybrid against the same hash file offers to skip the passes already run. A
  pass that runs out of budget is not recorded, so it will be retried.
  Wordlist entries may be glob patterns or directories; both are expanded
  before hashcat runs, a directory into the wordlists directly inside it.
  Subdirectories are not searched, matching hashcat's own behaviour, and
  dot-files and `.7z`/`.torrent`/`.out` files are skipped — a Weakpass
  download leaves archives in the wordlists directory and hashcat would
  otherwise try to read them.

#### Pathwell Top 100 Mask Brute Force Crack
Runs a brute force attack using the top 100 masks from KoreLogic:
https://blog.korelogic.com/blog/2014/04/04/pathwell_topologies

#### PRINCE Attack
https://hashcat.net/events/p14-trondheim/prince-attack.pdf

Runs a PRINCE attack using wordlists/rockyou.txt

#### YOLO Combinator Attack
Runs a continuous combinator attack using random wordlists from the configured wordlists directory for the left and right sides.

#### Middle Combinator Attack
https://jeffh.net/2018/04/26/combinator_methods/

Runs a modified combinator attack adding a middle character mask:
wordlists/rockyou.txt + masks + worklists/rockyou.txt

Where the masks are some of the most commonly used separator characters:
2 4 <space> - _ , + . &

#### Thorough Combinator Attack
https://jeffh.net/2018/04/26/combinator_methods/

* Runs many rounds of different combinator attacks with the rockyou list.
  - Standard Combinator attack: rockyou.txt + rockyou.txt
  - Middle Combinator attack: rockyou.txt + ?n + rockyou.txt
  - Middle Combinator attack: rockyou.txt + ?s + rockyou.txt
  - End Combinator attack: rockyou.txt + rockyou.txt + ?n
  - End Combinator attack: rockyou.txt + rockyou.txt + ?s
  - Hybrid middle/end attack: rockyou.txt + ?n + rockyou.txt + ?n
  - Hybrid middle/end attack: rockyou.txt + ?s + rockyou.txt + ?s


#### Bandrel Methodology

Prompts for comma-separated names and creates a pseudo hybrid attack by capitalizing the first letter and adding up to six additional characters at the end. Each word is limited to a total of five minutes.

  - Built-in common words (seasons, months) included as a customizable `config.json` entry (`bandrel_common_basedwords`)
  - The default five-minute time limit is customizable via `bandrelmaxruntime` in `config.json`

#### Loopback Attack
https://hashcat.net/wiki/doku.php?id=loopback_attack

Uses hashcat's loopback mode to feed cracked passwords from the current session back into the attack pipeline with rules applied. This generates new password candidates based on variations of already-cracked passwords, which is particularly effective for finding related passwords that follow similar patterns.

* Prompts for rule selection to apply to the loopback candidates
* Uses an empty wordlist with the --loopback flag to process previously cracked passwords
* Automatically downloads Hashmob rules if no rules are available locally

#### LLM Attack
Uses a local LLM — Ollama by default, or a vLLM / OpenAI-compatible server via `LLM_BACKEND` — to generate password candidates for a capture-the-flag scenario. Prompts for the fake company name, industry, location, and parent company / acquisition history, then sends these details to the configured LLM model to produce likely password candidates using industry terms and company name permutations. The generated candidates are fed into a hashcat wordlist+rules attack.

* Requires a running server at `OLLAMA_HOST` (default: `http://localhost:11434`, Ollama's port; override in `.env` or the environment) already serving the model — hate_crack does not auto-pull
* Candidate generation uses structured (JSON) output via Atomic Agents, so pick a model with good schema adherence (default: `qwen3:4b-instruct`)
* Configurable backend, model, context window, request timeout, and sample size via `.env` (see [LLM Configuration](#llm-configuration))
* Prompts for target company name, industry, location, and parent company / acquisition history. The industry, location, and parent company prompts are pre-filled with the local model's guesses about the named organization (editable, and clearly labelled as guesses rather than verified OSINT); disable with `ollamaAutoResearch: false`
* Alternatively derives basewords from a sample **wordlist**, or from the **cracked passwords** of the current session (`<hashfile>.out`) so the model mirrors the target organization's own password conventions and produces new candidates in that style (only offered once something has been cracked)
* A live spinner with an elapsed-seconds counter runs during generation, and requests are bounded by `ollamaTimeout` so a model stuck loading into VRAM reports a timeout instead of hanging

**Pattern rules mode** (option 4 in the LLM submenu) takes the same shape as the [Spoonman Attack](#spoonman-attack) — a baseword list run through a rule file, both derived from one corpus — but infers each side with the model instead of extracting it. Spoonman is exact and therefore bounded: its basewords all appear in the corpus and its rules only reproduce transformations the corpus already shows. This asks the model to generalize on both axes, so it can name the *word families* behind a sample (the company and its products, site names, local sports teams, seasons, mascots) and write decorations the corpus does not contain.

* Pattern source is either the current session's cracked passwords (offered first, and only once something has been cracked, since those reveal the target's real conventions) or a sample wordlist
* **You are not asked to pick a rule file.** The model writes one, from the same corpus statistics — a stock rule file encodes the internet's habits, and the point of spending a model round trip is to encode *this* organization's
* Basewords are normalized to lowercase letters only, discarding anything under 3 characters, so the generated rules supply case, digits, and punctuation exactly once
* Generated rules are validated before hashcat sees them, and anything using an op hashcat does not have, a position argument outside `0-9A-Z`, more than 31 functions, or a stray comment or non-ASCII character is discarded. hashcat drops an invalid rule *silently* when valid rules share the file, so an unscreened line would become missing coverage rather than an error. The op table was established by testing hashcat itself, not from its rule documentation, which lists ops hashcat will not actually run
* Local-model yield varies a lot run to run, so a thin answer is asked again once and the two rounds are merged — a handful of rules would waste the pass they are spent on
* If no rule survives validation the basewords still run, unmutated, rather than throwing away the expensive half of the run
* Output lands in `<hashfile>.llm_patterns/` as `basewords.txt` and `rules.rule` — per-run scratch, laid out like `.spoonman/` and removed on exit

#### OMEN Attack
Uses the Ordered Markov ENumerator (OMEN) to train a statistical password model from a wordlist and generate password candidates. This attack learns patterns from known passwords and generates new candidates based on those patterns.

* Requires OMEN binaries (createNG and enumNG) to be built from the omen submodule
* Interactive menu: use existing model, train new model, or cancel
* Training wordlist picker shows available wordlists from configured directory or accepts a custom path
* Validates all 5 required model files (createConfig, CP/IP/EP/LN.level) before running
* Captures and reports enumNG errors instead of failing silently
* Generates up to a specified number of password candidates (configurable via `omenMaxCandidates`)
* Pipes generated candidates directly into hashcat for cracking
* Model files and metadata are stored in `~/.hate_crack/omen/` for persistence across sessions

#### Combinator Attacks Submenu
Opens an interactive submenu with six combinator attack variants (formerly at menu keys 10-12). Consolidates related attacks for cleaner menu organization:
- Combinator Attack - combines two wordlists
- YOLO Combinator Attack - combines all permutations of multiple wordlists
- Middle Combinator Attack - combines wordlists with an extra word in the middle
- Thorough Combinator Attack - comprehensive combination of wordlists with rules
- Combinator3 Attack - combines exactly 3 wordlists using `combinator3.bin`, generating all `word1+word2+word3` combinations piped to hashcat
- CombinatorX Attack - combines 2-8 wordlists using `combinatorX.bin` with optional `--sepFill` separator character between word segments

#### Ad-hoc Mask Attack
Runs hashcat mask attack (mode 3) with a user-specified custom mask string. Allows fine-grained control over character-set brute forcing.

* Opens with a choice between typing a mask and selecting a mask file
* Prompts for a hashcat mask (e.g., `?u?l?l?l?d?d` for uppercase + lowercase + lowercase + lowercase + digit + digit)
* Supports custom character sets for specialized character combinations: `-1` through `-4` on any hashcat, plus `-5` through `-8` on hashcat 7 and newer. A mask using `?5`–`?8` against an older hashcat is flagged before the run rather than failing inside it; if the version cannot be read, the mask is passed through and hashcat decides
* Only prompts for the custom slots the mask actually references — `?1?3?d` asks about `-1` and `-3` and nothing else, and a mask with no custom tokens is never asked at all. Detection is token-aware, so the escaped `??1` is a literal `?1` and prompts for nothing. A slot left blank is still skipped, with a warning that hashcat will reject a mask whose charset is undefined
* Mask files (`.hcmask`) can be selected with tab completion, defaulting to the bundled `masks/` directory; hashcat runs every mask in the file in order. Because a mask file defines its own charsets inline, the `-1` through `-4` prompts are skipped when one is chosen
* Optionally runs the mask incrementally (`--increment`), trying shorter lengths before the full mask. Answering yes prompts for an increment minimum and maximum; either can be left blank, and leaving both blank increments over the mask's full keyspace with hashcat choosing the bounds. Offered for typed masks and mask files alike
* Useful for targeted brute forcing when you know password structure patterns

#### Markov Brute Force Attack
Generates password candidates using Markov chain statistical models. Similar to OMEN but simpler and faster.

* Checks for existing `.hcstat2` Markov table from previous sessions (with option to reuse, regenerate, or cancel)
* Generates table from training source if needed:
  - Can use cracked passwords from current session (`.out` file) as training data
  - Or select any wordlist from configured directory or custom path
* Interactive menu: choose minimum and maximum password length
* Uses `--increment` flag to test lengths in sequence
* Markov table persists with hash file (filename.out.hcstat2) for fast subsequent runs
* Faster than OMEN for general-purpose brute forcing

#### N-gram Attack
Generates n-gram candidates from a corpus file using `ngramX.bin` from hashcat-utils and pipes them into hashcat.

* Prompts for a corpus file with tab completion, defaulting to the configured wordlist directory
* Prompts for an n-gram group size (default 3)
* Gzip-compressed corpus files are auto-detected and decompressed on the fly
* Useful when you have target-relevant prose (scraped site copy, leaked documents, internal wiki exports) rather than a password list

#### Permutation Attack
Generates all character permutations of each word in a targeted wordlist and pipes them to hashcat via `permute.bin` from hashcat-utils.

* Prompts for a single wordlist file (not a directory)
* Effective against short targeted wordlists where the character set is known but the order is not (company abbreviations, name fragments, known tokens)
* WARNING: Scales as N! per word - an 8-character word produces 40,320 permutations. Only practical for words up to ~8 characters.
* Uses `permute.bin < wordlist | hashcat` pipeline pattern

#### Random Rules Attack
Generates a set of random hashcat mutation rules using `generate-rules.bin`, writes them to a temporary file, then runs hashcat against a chosen wordlist with those rules.

* Prompts for rule count (default 65536)
* Prompts for wordlist path with tab-completion and numbered selection
* Temporary rules file is cleaned up after the run regardless of outcome
* Useful when known rule sets are exhausted - explores random rule-space for additional cracks

#### Combipow Passphrase Attack
Generates all unique non-empty subset combinations from a short wordlist using `combipow.bin` and pipes them into hashcat. Designed for passphrase cracking when you know the pool of words a password was built from.

* Prompts for a wordlist file (max 63 lines - combipow generates up to 2^n-1 combinations)
* Optional space separator (`-s` flag) to insert spaces between words in each combination
* Warns if the wordlist exceeds 20 lines (output volume may be large)
* Aborts with a clear message if the wordlist exceeds 63 lines (hard limit)
* Candidates are piped directly to hashcat stdin

#### PCFG Attack
Uses [pcfg_cracker](https://github.com/lakiw/pcfg_cracker) to generate candidates from a Probabilistic Context-Free Grammar, piping `pcfg_guesser.py` output directly into hashcat's stdin mode. A PCFG models password *structure* (baseword + digits + symbol, capitalization habits, keyboard walks) with learned probabilities, so candidates come out roughly in descending likelihood order.

* Requires the `pcfg_cracker` submodule. Presence is checked at startup and reported non-fatally: if it is missing, the PCFG attacks are simply unavailable. Run `make` to fetch it.
* Uses the trained grammar named by `pcfgRuleset` in `config.json` (default `DEFAULT`), read from `pcfg_cracker/Rules/<name>/`
* Candidate count is capped by `pcfgMaxCandidates` (default 50,000,000)
* hate_crack does not wrap grammar training. To build a grammar from a target-specific password set, run pcfg_cracker's own `trainer.py` and point `pcfgRuleset` at the resulting ruleset name

#### PRINCE-LING Attack
Uses pcfg_cracker's `prince_ling.py` to derive an optimized PRINCE base wordlist from a trained grammar, then hands it to the existing PRINCE attack. PRINCE-LING picks base words the grammar says are actually productive, so the PRINCE combination space is far less wasteful than pointing PRINCE at a generic wordlist.

* Requires the `pcfg_cracker` submodule and a trained ruleset directory, same as the PCFG attack
* The generated wordlist is cached at `<hcatOptimizedWordlists>/pcfg_prince_ling_<ruleset>.txt` and reused across sessions
* Regenerates only when the ruleset directory is newer than the cached wordlist, so retraining a grammar invalidates the cache automatically
* Generation is written to a temporary file and atomically moved into place; a failed or interrupted run cleans up its partial file and leaves any existing cache intact
* Base wordlist size is capped by `pcfgPrinceLingMaxCandidates` (default 10,000,000)

#### Spoonman Attack
Derives a baseword list and a hashcat rule file from a corpus of known plaintext passwords — a previous engagement's cracked output, a leak dump, or any password list — such that the baseword x rule cross product reconstructs the corpus exactly (see the memory bound below for the one case where it does not). Contributed as issue #169 by @Spoonman1091.

Each password is split into its letters-only lowercased core (the baseword) plus a rule that rebuilds the original from it, using `l`/`u`/`c` for casing, `T{p}` toggles, `${x}`/`^{x}` for trailing and leading characters, and `i{p}{x}` for interior ones.

* When the current session already has cracked plaintexts (`<hash file>.out` exists and is non-empty), a picker offers those as the corpus ahead of a free-form path — the target's own recovered passwords derive rules describing that target's actual conventions, which is exactly what you want to fire back at the remaining uncracked hashes. Deriving from `.out` and then cracking the same hash file appends new plaintexts to that same file, growing the corpus for the next run; that is the intended feedback loop, not corruption. Sessions with no cracked output yet see no picker at all — just today's path prompt
* Prompts for the corpus, then for how much of the rule file to run: top 50% coverage (listed first and recommended), top 75%, top 95%, top 99%, or the full set
* Rules are sorted by how many passwords each one rebuilds, so a truncated file keeps the most productive rules. Coverage is extremely long-tailed: on a 98.2M-password sample, 50% coverage needed 4,120 rules while 95% needed 16,119,661 and 100% needed 21,029,696 — the last few percent typically costs orders of magnitude more rules than the first half, which is why the smallest tier is listed first and is usually the right choice
* Output is written beside the hash file in `<hash file>.spoonman/`, alongside the other ephemeral wordlists: `basewords.txt`, `rules.full.rule`, the capped rule files, and `coverage.txt` with per-milestone rule counts. Derivation is skipped on later runs of the same hash file unless the corpus has been modified since, and the directory is removed on exit by the temp-file cleanup
* Derivation is bounded in memory. Both counters would otherwise grow for the whole read with nothing written until the end, so a corpus large enough to exhaust RAM lost the entire pass to an OOM kill and produced no output; a measured run against a 31 GB corpus reached 14.1 GB resident at 11% of the file and was still accelerating. Each counter is now capped at 20 million distinct keys (about 1.6 GB apiece), and the lowest-frequency keys are discarded once it is exceeded. If that happens, the run says so on the console and in `coverage.txt`, the output reconstructs the retained keys rather than 100% of the corpus, and the coverage percentages are relative to those. Corpora below the cap are unaffected
* Passwords that cannot be expressed as a rule are written verbatim as their own baseword with a `:` no-op, so coverage stays complete. This covers two hashcat limits: rule positions cannot address past index 35, and hashcat rejects any rule with more than 31 functions — silently, when valid rules share the file
* A password carrying a literal CR or LF (which arrives hex-wrapped, as `$HEX[...0a]`) cannot go in a baseword at all, because a wordlist line has no escape syntax for one. The break is lifted out into an insert op instead, spelled `\x0a`/`\x0d` in the rule, which hashcat decodes to the byte. When the break sits past addressable index 35 the rule reverses the word first, inserts from the other end, and reverses back. One frame has to hold every break in the password, so what is still skipped is a password with one break outside the first 36 characters *and* another outside the last 36, or one needing more inserts than the 31-function cap leaves room for. Those are counted as `unwritable basewords` in `coverage.txt` and reported, never dropped silently
* The derivation self-checks every password by reconstructing it in-process, and reports any failures rather than reporting success
* Corpus lines may carry a hash in front of the password, as cracked output does. A leading field is dropped only when it has the shape of a hash (a hex digest at a known length, or a crypt-style `$id$` string), so `hash:salt:plain` is handled while a plaintext or wordlist entry containing a colon survives intact. `$HEX[...]` plaintexts are decoded. If most lines look like an uncracked dump rather than cracked output, `coverage.txt` records the count and the attack warns — the derived basewords and rules would otherwise be meaningless without any error being raised

#### Rosetta Attack
Mines hashcat `--debug-mode 5` logs for the basewords and rules that already cracked something, then runs their full cross product. Powered by [HashcatRosetta](https://github.com/bandrel/HashcatRosetta), the same library behind [Analyze Hashcat Rules](#analyze-hashcat-rules-rule-file-tools-option-5).

No setup is needed to feed it: `_add_debug_mode_for_rules` appends `--debug-mode 5 --debug-file` to every rule-based hashcat invocation hate_crack makes, so the logs accumulate in `hcatDebugLogPath` (`~/.hate_crack/hashcat_debug` by default, one file per session) as a side effect of normal use. A mode 5 log records only candidates that cracked a hash, in the form `baseword:rule:candidate:wordlist`, which is what makes both halves known-productive against this target population; the trailing wordlist field also shows which list is earning its keep on a multi-wordlist run. HashcatRosetta parses mode 4 and mode 5 alike, so logs written before the switch are still read.

The value is in the cross product rather than the recorded pairs. A pair present in a log has already cracked its hash and will not crack another, but a rule that worked on one baseword has usually never been tried against the others — so N basewords and M rules yield close to N x M untried candidates.

The menu first asks how to rank rules — choices 1-3 below, plus a fourth, unrelated mode:

* Rules can be ranked by application frequency, by how many distinct basewords each one worked on, or by how many unique candidates each one generated. Frequency is the default; baseword spread is the better choice when the goal is a rule set that generalizes past the specific words it was learned from
* Only after one of those three is picked does hate_crack list the logs found in `hcatDebugLogPath` newest-first with their sizes; pick one, pick all of them (up to 20), or type a path to a log from elsewhere
* Prompts for how many top rules to keep and how many top basewords. Both default to all — a blank answer keeps every winning rule the logs contain, and zero means the same thing. Enter a number to cap either. The keyspace is the product of the two and is printed before hashcat starts
* Output is written beside the hash file in `<hash file>.rosetta/` as `basewords.txt` and `rules.rule`, alongside the other ephemeral wordlists, and the directory is removed on exit by the temp-file cleanup
* Reading stops at 1,000,000 debug lines, since the analyzer needs the whole batch in memory at once. Truncation is reported on the console rather than assumed harmless — logs from a long run routinely exceed this, in which case the newest log is the one worth selecting
* **LLM Mask Attack** (4) - a different mode entirely, and the only one that needs no debug logs. Prompts for a natural-language description of the passwords you expect (length, character patterns, symbols, etc.), sends it to the locally configured Ollama model, writes the returned masks to `<hash file>.hcmask`, and runs a `-a 3` hashcat mask attack against them

#### Corporate Masks Brute Force
Statistical masks (8-14 characters) derived from analysis of 3.2M NTLM hashes cracked on real engagements. Powered by [Corporate_Masks](https://github.com/golem445/Corporate_Masks), these masks encode realistic password patterns from successful penetration tests.

* Prompts for minimum and maximum mask length (default 8-10)
* Longer lengths cost exponentially more keyspace—start with 8-10 for speed, or 8-12 for thoroughness
* Each mask file is run as a separate hashcat invocation in ascending length order
* Gracefully handles missing mask files (skips them) and absent submodule (prints warning and returns)
* Supports optimized kernels (`-O` flag) for faster cracking
* Ctrl-C during one length aborts remaining lengths

#### Wordlist Tools (option 80)
A submenu of wordlist preprocessing utilities using hashcat-utils binaries. All tools read from and write to files on disk. All file and directory path prompts support tab completion.

| Key | Tool | Description |
|-----|------|-------------|
| 1 | Filter by Length | Keep only words between a min and max length (`len.bin`) |
| 2 | Require Char Classes | Keep words that include all char classes in mask (`req-include.bin`). Mask: 1=lower, 2=upper, 4=digit, 8=symbol (additive) |
| 3 | Exclude Char Classes | Remove words containing any char class in mask (`req-exclude.bin`). Same mask encoding |
| 4 | Extract Substring | Cut bytes from each word at a given offset and optional length (`cutb.bin`) |
| 5 | Split by Length | Create per-length files in an output directory (`splitlen.bin`) |
| 6 | Subtract Wordlist | Remove lines from a wordlist that appear in one or more remove files. Mode 1 uses `rli2.bin` (single file); mode 2 uses `rli.bin` (multiple files) |
| 7 | Shard Wordlist | Split a wordlist into N equal, interleaved parts in one run, written as `base.001`…`base.00N` for distributed cracking (`gate.bin`) |
| 8 | Optimize Wordlists | Dedupe and split the selected wordlists into per-length files under an output directory |
| 9 | Download from Hashmob.net | Browse and download wordlists from Hashmob.net into the configured wordlist directory |
| 10 | Download from Weakpass | Browse and download Weakpass wordlist torrents, with automatic extraction |
| 11 | Hashmob Downloads | Access a submenu for downloading Hashmob archives (yearly full-found corpora) and combined-left lists (per-mode uncracked hashes) |

All binaries are in `hate_crack/hashcat-utils/bin/`.

#### Rule File Tools (option 81)
Preprocesses hashcat rule files using `cleanup-rules.bin` and `rules_optimize.bin` from hashcat-utils, and downloads rule files from Hashmob.net.

* **Clean** (1) - removes invalid syntax and duplicate rules using `cleanup-rules.bin`. Useful after combining rule files or downloading rules from external sources.
* **Optimize** (2) - consolidates redundant operations using `rules_optimize.bin`. Reduces rule file size and improves cracking speed.
* **Clean and optimize** (3) - runs both operations in sequence via a temporary file, then writes the final result.
* **Download rules from Hashmob.net** (4) - fetches rule files into the configured `rulesDirectory`.
* **Analyze Hashcat rules** (5) - opcode frequency analysis of a rule file, powered by HashcatRosetta.

The three preprocessing operations read from an input file and write to a separate output file (original is never modified).

#### Download Rules from Hashmob.net (Rule File Tools option 4)
Downloads the latest rule files from Hashmob.net's rule repository. These rules are curated and optimized for password cracking and can be used with the Quick Crack and Loopback Attack modes.

* Downloads rule sets in parallel using a thread pool (up to 4 concurrent downloads)
* Skips rules already downloaded locally
* Reports download summary with success/failure counts
* Stores rules in the configured rules directory

#### Analyze Hashcat Rules (Rule File Tools option 5)
Powered by HashcatRosetta (https://github.com/bandrel/HashcatRosetta), this feature analyzes hashcat rule files to provide detailed insights into rule composition and complexity.

* Prompts for a rule file path
* Displays frequency analysis of rule opcodes (operations)
* Helps understand what transformations a rule set performs
* Useful for rule debugging and optimization

#### Mask Tools (option 83)
Downloads mask files from Hashmob.net. This is a minimal submenu today — masks
have no local file-tooling counterpart to the rule/wordlist cleanup and
optimization utilities, only a download capability.

* **Download masks from Hashmob.net** (1) - fetches mask files into the hate_crack masks directory.

#### Download Masks from Hashmob.net (Mask Tools option 1)
Downloads mask files from Hashmob.net's mask repository into the hate_crack masks directory for use with mask-based attacks.

* Downloads mask sets in parallel using a thread pool (up to 4 concurrent downloads)
* Skips masks already downloaded locally
* Reports download summary with success/failure counts
* Stores masks in the configured masks directory used by the Ad-hoc Mask Attack
* Supports interactive listing, range selection, and browsing of available mask files

#### Download Wordlists from Hashmob.net (Wordlist Tools option 9)
Downloads wordlists from Hashmob.net's collection of cracked passwords and commonly used wordlists.

* Interactive menu for browsing available wordlists
* Progress tracking for large downloads
* Stores wordlists in configured wordlist directory

#### Weakpass Wordlist Menu (Wordlist Tools option 10)
Interactive menu for downloading and managing wordlists from Weakpass.com via BitTorrent.

* Browse available Weakpass wordlist torrents
* Download specific wordlists or entire collections
* Automatic extraction of compressed archives
* Progress tracking for torrent downloads

#### Hashmob Downloads (Wordlist Tools option 11)
Access a submenu for downloading large-scale password corpora and specialized wordlists from Hashmob.net.

**Archives** - Downloads yearly full-found password corpora (multi-GB archives containing all cracked passwords from a given year)
* Requires confirmation before downloading -- these archives are large (the listing may show "(unknown size)" since Hashmob's API doesn't currently report a file size per archive)
* Lists all available archives across every year as one globally-numbered list to browse and pick from by index, rather than a per-year picker
* Accepts `a` (or `all`) at the selection prompt to download every listed archive, one at a time. A single confirmation naming the archive count and the summed size covers the whole batch; an archive already on disk at its listed size is skipped, one whose size does not match is re-downloaded, and a failure is counted rather than aborting the rest
* Stores archives in the configured wordlist directory for extraction and use

**Combined Left Lists** - Downloads per-hashcat-mode combined lists of uncracked ("left") hashes from Hashmob.net
* Each list is a set of hashes, not plaintexts, still awaiting a crack for that hashcat mode
* Useful for spotting overlap between your own hash list and hashes the community hasn't cracked yet
* Supports mode selection from the listed hash counts per algorithm

-------------------------------------------------------------------
### Version History

The full, per-release changelog now lives in [CHANGELOG.md](https://github.com/trustedsec/hate_crack/blob/main/CHANGELOG.md).