_   _           _               _   ____                _   _        
| | | | __ _ ___| |__   ___ __ _| |_|  _ \ ___  ___  ___| |_| |_ __ _ 
| |_| |/ _` / __| '_ \ / __/ _` | __| |_) / _ \/ __|/ _ \ __| __/ _` |
|  _  | (_| \__ \ | | | (_| (_| | |_|  _ < (_) \__ \  __/ |_| || (_| |
|_| |_|\__,_|___/_| |_|\___\__,_|\__|_| \_\___/|___/\___|\__|\__\__,_|
                                                                  
    Decode the Rosetta Stone of Password Cracking Rules

HashcatRosetta

A Python project designed to analyze hashcat debug mode 4 and mode 5 output files to identify the most efficient rules and track baseword frequency patterns used during password cracking attacks.

Features

• Parse hashcat debug files (--debug-mode 4 and --debug-mode 5) with automatic baseword and rule extraction
• Attribute candidates to source wordlists (mode 5) for per-wordlist statistics
• Track rule efficiency by multiple metrics:
  • Application frequency (most commonly applied rules)
  • Baseword spread (rules applied to most unique basewords)
  • Candidate generation (rules producing most unique candidates)
• Monitor baseword patterns with detailed occurrence logs and statistics
• Generate detailed reports with rule and baseword analytics
• Export analysis to JSON or CSV formats for further processing
• Command-line interface for easy analysis and reporting

Installation

Using with uv (recommended)

If you're using uv, you can run without installation:

# Clone the repository
git clone https://github.com/bandrel/HashcatRosetta.git
cd HashcatRosetta

# Run as a module (recommended)
uv run python -m hashcat_rosetta --help

# Or use the installed command
uv run hashcat-rosetta --help

From source

uv tool install git+https://github.com/bandrel/HashcatRosetta.git

With development dependencies

The dev tools live in the dev dependency group.

# With uv (installs the dev group by default)
uv sync

# With pip (25.1+)
pip install -e . --group dev

Quick Start

Analyzing Debug Files

Analyze a hashcat debug file (shows summary by default):

hashcat-rosetta debug_output.txt

Show top rules by frequency:

hashcat-rosetta debug_output.txt --rules --top 10 --metric frequency

Show top rules by other metrics:

hashcat-rosetta debug_output.txt --rules --metric basewords
hashcat-rosetta debug_output.txt --rules --metric candidates

Show basewords appearing multiple times:

hashcat-rosetta debug_output.txt --basewords --top 10

Show top wordlists (debug mode 5 only):

hashcat-rosetta debug_output.txt --wordlists --top 10

Show detailed per-wordlist statistics (unique basewords, candidates, and rules):

hashcat-rosetta debug_output.txt --wordlists --top 10 --detail

The --wordlists output mirrors --rules: a Top N Wordlists header followed by numbered Wordlist: <name> (<count>) lines. When a mode-5 file is analyzed without any output flags, the default summary also includes a Wordlist Statistics section.

Force a specific debug mode instead of auto-detecting it:

hashcat-rosetta debug_output.txt --debug-mode 5 --wordlists

Show detailed baseword analysis:

hashcat-rosetta debug_output.txt --basewords --top 10 --detail --min-occurrences 2

Export complete analysis report:

hashcat-rosetta debug_output.txt --export report.json --format json
hashcat-rosetta debug_output.txt --export report.csv --format csv

Explaining Rules

Explain what a hashcat rule does step-by-step:

hashcat-rosetta --explain "c$1" --baseword admin
hashcat-rosetta --explain "u$!" --baseword myword

Generating Masks with Natural Language

Generate hashcat masks from English descriptions using a local LLM:

hashcat-rosetta --mask "The word 'Summer' followed by six digits."

Output:

Mask Suggestions for: 'The word 'Summer' followed by six digits.'
======================================================================

1. Summer?d?d?d?d?d?d
   literal "Summer", then 6 × digit → 1,000,000 candidates
   Why: matches the literal word followed by a 6-digit number

Save the generated mask to a file:

hashcat-rosetta --mask "The word 'Summer' followed by six digits." -o masks.hcmask

Generate masks from other descriptions:

hashcat-rosetta --mask "a capitalized season, two digits, and a special char"
hashcat-rosetta --mask "year 2020-2025 followed by exclamation or question mark"

The mask generation feature uses a local Ollama server running an OpenAI-compatible chat endpoint. By default, it connects to http://localhost:11434 and uses the model gemma3:27b (see below). These can be configured via environment variables or CLI flags:

# Using environment variables
OLLAMA_HOST=http://192.168.1.100:11434 OLLAMA_MODEL=llama2:70b \
  hashcat-rosetta --mask "your description here"

# Using CLI flags (override environment variables)
hashcat-rosetta --mask "your description" --ollama-host http://custom.host:11434 --model llama2

Security note: Mask descriptions are sent only to the Ollama endpoint you configure (localhost by default, or wherever --ollama-host/OLLAMA_HOST points) — never to a cloud provider. The OpenAI SDK is used purely as an HTTP client against that endpoint; no data or API key is ever transmitted to api.openai.com.

Why gemma3:27b?

The default is chosen by scripts/benchmark_mask_models.py, which runs a fixed set of 14 --mask-style prompts — including custom-charset back-references and category-recall prompts (Bible books, Bible verse references, European capital cities) — against every locally-installed candidate model and grades each response three ways:

• Deterministic gate. Each prompt has a hand-written checker (correct keyspace, correct token counts, no duplicate suggestions, etc). A hard fail means the model's response couldn't even be parsed into a valid mask (bad JSON, an unresponsive server); a soft fail means it parsed fine but didn't satisfy the request (wrong digit count, non-vowel custom charset, ...). Soft-failed prompts still get judged, not silently excluded.
• Keyspace cross-check. Every validated suggestion's keyspace is independently verified against hashcat-utils' mp64 (maskprocessor), when installed — this is the same check generate_masks() itself runs on every suggestion in production, so a benchmark hard fail here also means real --mask usage would have rejected it.
• LLM judge. A model on a separate host (gemma3:12b on a second machine, chosen specifically because it isn't itself a candidate — avoids self-grading bias) scores every response 1-5 for how well it satisfies the original request. Requests are sent with thinking enabled, since a slow model already costs the round-trip time either way.

The recommended default is the smallest model with zero hard fails and a mean judge score ≥ 4. The three finalists carried forward from earlier rounds, re-run against the full 14-prompt set:

model	size	hard fails	mean score	time
gemma3:27b	16.2 GB	0	4.1	180s
dengcao/Qwen3-30B-A3B-Instruct-2507:latest	17.4 GB	1	4.5	176s
laguna-xs-2.1:latest	18.9 GB	2	4.7	730s

gemma3:27b is the only one of the three with zero hard fails, so it's the pick despite not having the highest raw score — dengcao and laguna-xs-2.1:latest scored higher but each failed at least one prompt outright (and laguna-xs-2.1:latest is also far slower, 730s vs ~180s, driven by its own very large native context window).