Metadata-Version: 2.1
Name: quinto
Version: 0.1.0
Summary: Automated hash cracking CLI — identify, orchestrate, and crack hashes using hashcat and john
Author: Levente Farkas
License: MIT
Project-URL: Repository, https://github.com/Farkas-Levente/Quinto
Keywords: hashcat,john,hash,cracking,ctf,security,password,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: name-that-hash
Requires-Dist: hashid
Requires-Dist: platformdirs>=3.0
Requires-Dist: tomli>=2.0; python_version < "3.11"

# Quinto

> *"I'm not a thief. I'm a locksmith." — Quinto, master safecracker*

Quinto is a CLI tool that automates hash cracking. Give it a hash string or a password-protected file — it figures out the hash type, selects an attack plan, and runs hashcat and John the Ripper so you don't have to.

Designed for CTF competitions, authorized penetration testing, and security research.

---

## How it works

1. **Identifies** the hash type using prefix matching, [name-that-hash](https://github.com/HashPals/Name-That-Hash), and hashid
2. **Detects GPU** availability via nvidia-smi, falls back to CPU mode
3. **Selects an attack plan** based on whether the hash is fast or slow (key-stretching algorithms like bcrypt get a reduced plan) and your `--patience` level
4. **Runs attacks** in sequence: wordlist → wordlist + rules → masks → EFF diceware passphrases
5. **Saves session state** after each attack so you can `--resume` if interrupted

For password-protected files (.zip, .pdf, Office docs, etc.), it first extracts the hash using John's `*2john` tools, then cracks it with wordlists.

---

## Prerequisites

Quinto orchestrates external tools — you need to install these separately before it will work.

### Required

**hashcat** (v6+) — the primary cracking engine:
```bash
# Option A: GitHub release (recommended — always up to date)
wget https://github.com/hashcat/hashcat/releases/latest/download/hashcat-7.1.2.7z
7z x hashcat-7.1.2.7z && sudo mv hashcat-7.1.2 /opt/hashcat
sudo ln -sf /opt/hashcat/hashcat.bin /usr/local/bin/hashcat

# Option B: package manager (may be outdated)
sudo apt install hashcat
```

**John the Ripper** (Jumbo build) — handles formats hashcat doesn't support, and extracts hashes from protected files:
```bash
sudo apt install -y build-essential libssl-dev zlib1g-dev yasm libgmp-dev libpcap-dev
git clone --depth 1 https://github.com/openwall/john.git ~/john-build
cd ~/john-build/src && ./configure && make -sj$(nproc) && cd ~

# Create wrapper scripts (symlinks break John's config lookup):
for f in ~/john-build/run/john ~/john-build/run/*2john*; do
    name=$(basename "$f")
    printf '#!/bin/sh\nexec "%s" "$@"\n' "$f" | sudo tee "/usr/local/bin/$name" > /dev/null
    sudo chmod +x "/usr/local/bin/$name"
done
```

**rockyou.txt** — the baseline wordlist (required for basic functionality):
```bash
sudo mkdir -p /usr/share/wordlists
sudo wget -q https://github.com/brannondorsey/naive-hashcat/releases/download/data/rockyou.txt \
     -O /usr/share/wordlists/rockyou.txt
```

### Recommended

**SecLists** — additional wordlists (darkweb2017, xato, probable, NCSC, Pwdb):
```bash
sudo git clone --depth 1 https://github.com/danielmiessler/SecLists /usr/share/seclists
```

**crackstation.txt** — massive 15GB wordlist:
Download from [crackstation.net](https://crackstation.net/crackstation-wordlist-password-cracking-dictionary.htm) and place at `/usr/share/wordlists/crackstation.txt`

**OneRuleToRuleThemAll** — powerful external rule file:
```bash
sudo wget -q https://raw.githubusercontent.com/NotSoSecure/password_cracking_rules/master/OneRuleToRuleThemAll.rule \
     -O /usr/share/hashcat/rules/OneRuleToRuleThemAll.rule
```

**EFF diceware wordlist** — for passphrase attacks:
```bash
sudo wget -q https://www.eff.org/files/2016/07/18/eff_large_wordlist.txt \
     -O /usr/share/wordlists/eff-diceware.txt
```

---

## Installation

```bash
pip install quinto
```

On first run, Quinto checks your environment and reports what's available:

```
quinto --deps
```

This also generates a config file at `~/.config/quinto/config.toml` (Linux) that you can edit to point to custom wordlist/rule paths.

---

## Usage

```
quinto <hash_string>
quinto <protected_file>
quinto --resume
quinto --patience=quick|normal|patient <hash>
```

### Crack a raw hash

```bash
quinto 5f4dcc3b5aa765d61d8327deb882cf99
```

Quinto identifies the type (MD5 here), then runs through wordlists, rules, and masks until it finds the plaintext or exhausts the plan.

### Crack a password-protected file

```bash
quinto archive.zip
quinto document.pdf
quinto database.kdbx
```

Supported file types: `.zip`, `.rar`, `.7z`, `.pdf`, `.kdbx` (KeePass), `.doc/.docx`, `.xls/.xlsx`, `.ppt/.pptx`, SSH private keys.

### Patience levels

```bash
quinto --patience=quick   hash   # rockyou only — fast, lower coverage
quinto --patience=normal  hash   # rockyou + crackstation (default)
quinto --patience=patient hash   # everything: all wordlists x all rules + extended masks
```

| Level | Wordlists | Rules | Masks | Passphrases |
|-------|-----------|-------|-------|-------------|
| `quick` | rockyou | all | tier 1 | — |
| `normal` | rockyou, crackstation | all | tier 1–2 | 2-word |
| `patient` | all | all | tier 1–3 | 3-word |

### Resume an interrupted session

Sessions are saved after each completed attack. If a crack is interrupted (Ctrl+C, timeout, system sleep), resume where you left off:

```bash
quinto --resume
```

Sessions expire after 24 hours.

---

## Attack strategy

### Fast hashes (MD5, SHA1, SHA256, NTLM, ...)

1. Wordlist straight
2. Wordlist + best64 rules
3. Wordlist + OneRuleToRuleThemAll
4. Wordlist + dive rules
5. Smart mask files (`.hcmask` — pattern-based brute force)
6. EFF diceware passphrase combinator (1-word, 2-word, 3-word)

### Slow hashes (bcrypt, scrypt, Argon2, yescrypt, phpass, ...)

Reduced plan — brute force is not practical:

1. rockyou straight
2. rockyou + best64 (normal+)
3. crackstation + best64 (patient)
4. EFF diceware passphrase (1-word, 2-word)

Argon2 variants are routed directly to John the Ripper (hashcat doesn't support them).

---

## Supported hash types

Quinto maps to hashcat modes for 70+ algorithm names including:

| Category | Algorithms |
|----------|-----------|
| General | MD5, MD4, SHA1, SHA224, SHA256, SHA384, SHA512, SHA3-256, SHA3-512 |
| Windows | NTLM, Net-NTLMv1, Net-NTLMv2, LM |
| Unix | md5crypt, sha256crypt, sha512crypt, yescrypt, scrypt |
| KDF | bcrypt, Argon2i/d/id, PBKDF2-SHA256/SHA512, scrypt |
| Web/CMS | phpass (WordPress/phpBB), Django PBKDF2, LastPass |
| Database | MySQL 3.2.3, MySQL 4.1/5.x |
| Network | WPA/WPA2, WPA-PMKID, Cisco Type 8/9 |
| Crypto | Whirlpool, RIPEMD-160, BLAKE2, Tiger, Snefru, CRC32 |
| Other | KeePass, 1Password, VeraCrypt, Android FDE, LUKS |

Prefixed/salted formats (e.g., `$2b$`, `$6$`, `$argon2id$`, `$P$`) are identified from the hash string directly with 100% confidence.

---

## Configuration

On first run, Quinto auto-generates a config template at:

- **Linux**: `~/.config/quinto/config.toml`
- **macOS**: `~/Library/Preferences/quinto/config.toml`
- **Windows**: `%APPDATA%\quinto\config.toml`

All values are optional — Quinto auto-discovers tools and wordlists from common install locations. Uncomment any line to override:

```toml
[wordlists]
rockyou = "/data/wordlists/rockyou.txt"
crackstation = "/data/wordlists/crackstation.txt"

[rules]
onetorule = "/opt/hashcat/rules/OneRuleToRuleThemAll.rule"

[paths]
mask_dir = "/opt/hashcat/masks"
```

---

## Ethical use

Quinto is intended for:

- CTF competitions
- Authorized penetration testing engagements
- Security research on hashes you own or have explicit permission to test
- Recovering your own passwords

Only use this tool against systems and data you own or have written authorization to test. Unauthorized access to computer systems is illegal in most jurisdictions.

---

## License

MIT
