MarryTheHash

  __  __                         _____ _          _   _           _
 |  \/  | __ _ _ __ _ __ _   _  |_   _| |__   ___| | | | __ _ ___| |__
 | |\/| |/ _` | '__| '__| | | |   | | | '_ \ / _ \ |_| |/ _` / __| '_ \
 | |  | | (_| | |  | |  | |_| |   | | | | | |  __/  _  | (_| \__ \ | | |
 |_|  |_|\__,_|_|  |_|   \__, |   |_| |_| |_|\___|_| |_|\__,_|___/_| |_|
                         |___/

MarryTheHash is a CTF-focused CLI toolkit for hash identification, John/Hashcat command suggestions, hashdump scanning, and ranked wordlist generation from fictional challenge context.

It is built for authorized labs, CTFs, training boxes, and personal password-recovery practice. It does not include leaked password databases.

Features

• Identify common CTF/lab hash formats and rank likely candidates.
• Suggest John the Ripper and Hashcat commands.
• Scan mixed hash files, Windows pwdump-style dumps, and Linux shadow-style samples.
• Export grouped cracking files for cleaner workflows.
• Suggest converters for archives and encrypted files such as ZIP, RAR, 7z, SSH keys, Office, PDF, KeePass, and related John formats.
• Match fictional CTF context against password-behavior profiles.
• Generate controlled wordlist tiers: top, balanced, aggressive, and all.
• Run built-in wordlist quality checks to reduce procedural/AI-generated garbage.
• Optional AI provider support through your own API key or a local Ollama setup.

Allowed use

• CTF challenges
• Lab environments
• Personal password recovery
• Authorized security audits
• Security education and defensive research

Not allowed

• Targeting real people
• Attacking real accounts
• Unauthorized password guessing
• Using leaked password dumps against real services

Install

Linux/macOS:

git clone https://github.com/Kenasz/MarryTheHash.git
cd MarryTheHash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .

Windows PowerShell:

git clone https://github.com/Kenasz/MarryTheHash.git
cd MarryTheHash
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .

Check the CLI:

marry --help
marry doctor

Quick demo

Identify a hash:

marry identify 5f4dcc3b5aa765d61d8327deb882cf99

Suggest cracking commands:

marry suggest 5f4dcc3b5aa765d61d8327deb882cf99 --wordlist generated/wordlist_top.txt

Scan included demo files:

marry scan examples/hash_samples.txt
marry scan --windows examples/windows_hashdump.txt
marry scan --linux examples/linux_shadow_samples.txt

Build a ranked CTF wordlist from the included demo plan:

marry build-wordlist --plan examples/raven_ctf_plan.json --out-dir generated

The output folder contains:

generated/wordlist_top.txt
generated/wordlist_balanced.txt
generated/wordlist_aggressive.txt
generated/wordlist_all.txt
generated/wordlist_report.json
generated/README.txt

Example John workflow for a local test hash:

echo -n "Raven04" | md5sum | awk '{print $1}' > test.hash

marry build-wordlist --plan examples/raven_ctf_plan.json --out-dir generated

john --format=Raw-MD5 --wordlist=generated/wordlist_top.txt test.hash
john --show --format=Raw-MD5 test.hash

Expected result:

Raven04

Common commands

marry --help
marry doctor

marry identify <hash-or-file>
marry suggest <hash-or-file>
marry scan hashes.txt --source auto --export exported_hashes

marry convert archive.zip

marry profiles
marry profile-suggest "fictional CTF forum admin Raven born 2004"

marry build-wordlist --plan examples/raven_ctf_plan.json

Use --no-banner for cleaner script-friendly output:

marry --no-banner identify 5f4dcc3b5aa765d61d8327deb882cf99

Supported hash coverage

The detector includes common CTF and lab formats such as:

• Raw MD5, SHA1, SHA224, SHA256, SHA384, SHA512
• NTLM, LM, NetNTLMv1, NetNTLMv2
• MySQL old/MySQL323 and MySQL 4.1+/MySQL5
• Unix crypt: descrypt, md5crypt, sha256crypt, sha512crypt, bcrypt, yescrypt, Argon2
• WordPress/phpass, Drupal7, Joomla old md5:salt
• Django PBKDF2-SHA256, old Django SHA1/MD5
• JWT-like token hints
• Kerberos AS-REP/TGS hash hints
• WPA/WPA2 22000 style
• John converter outputs: ZIP, RAR, 7z, PDF, Office, KeePass, SSH private keys, GPG, Bitcoin wallet

Hash identification is pattern-based. Ambiguous raw hashes can match multiple algorithms, so CTF context still matters.

Tests

Install pytest:

python -m pip install pytest

Run the smoke tests:

python -m pytest -q

Current smoke test coverage checks:

• CLI help
• hash sample scan
• Windows pwdump-style scan
• Linux shadow-style scan
• MD5 identify/suggest
• demo wordlist generation

Optional AI mode

AI support is optional. The core pipeline works without it.

marry api-key set openrouter
marry ai-plan --context "fictional CTF user: Warcraft modding forum admin Raven born 2004"
marry ai-send --provider openrouter --prompt ai_plan_prompt.txt --out ai_plan.json
marry build-wordlist --plan ai_plan.json

Local Ollama can be used as an experimental provider, but small VMs may not have enough memory for stable local inference.

Project hygiene

Runtime files are intentionally ignored by Git:

.env
ai_plan.json
ai_plan_prompt.txt
ai_profile_package.json
ai_plan_raw.txt
ai_wordgen_raw.txt
wordlist.txt
wordlist_*.txt
generated/
generated_demo/
*.hash
*.pot
*.egg-info/
__pycache__/

Run:

marry doctor

to check local tools, mappings, profiles, wordlists, and common accidental runtime files.

Roadmap

• More hash format hints and converter recommendations.
• More demo scenarios.
• Optional light AI harvest mode for tiny local models.
• GitHub Actions CI for automated test runs.
• Cleaner packaged release.

Disclaimer

This project is for CTFs, authorized labs, education, and defensive security practice only.