breach-check

---
description: HIBP k-anonymity check on a password wordlist. Enriches each password with its breach count, ranks DESC. Free API (no key), only first 5 chars of SHA-1 sent. Output -> <input>-ranked.txt. Usage /breach-check <wordlist> [--min-count N] [--max-count N] [--with-counts]
---

# /breach-check

Rank a password wordlist by HaveIBeenPwned breach count. Used between `/wordlist-gen` and spray to surface which candidates have **proven human use**.

## Usage

```
/breach-check recon/target.com/wordlists/ranked.txt
/breach-check ranked.txt --with-counts                              # also dump TSV
/breach-check ranked.txt --max-count 1000000                        # drop generic passwords (>1M)
/breach-check ranked.txt --min-count 1                              # only keep proven-real passwords
/breach-check ranked.txt --limit 5000                               # test/preview first 5k (lex-sorted slice)
/breach-check ranked.txt --limit 5000 --shuffle                     # random 5k sample (avoid ASCII-sort bias)
```

## What this does

For each password in the wordlist:
1. Compute SHA-1 hash
2. Send only the **first 5 chars** to `api.pwnedpasswords.com/range/{prefix}` (k-anonymity)
3. HIBP returns ~500 candidate suffix-count pairs
4. Match locally to get exact breach count for your password

**Privacy**: HIBP never sees the full password. Add-Padding header is used to obscure prefix distribution from network observers.

## Why rank by breach count

| Range | Meaning | Spray strategy |
|---|---|---|
| **0** | Never leaked | Could be company-specific OR truly random — context-dependent |
| **1–1000** | "Sweet spot" — proven human use but not yet in every spray list | **Prioritize** — high signal/cost ratio |
| **1k–1M** | Mainstream password | Usually already tried by previous attackers |
| **>1M** | Generic ("password", "123456") | Skip — every WAF expects these, lockout risk |

## Example (real HIBP results)

```
209,972,844    123456                ← generic, drop
 52,256,179    password              ← generic, drop
 30,799,395    qwerty                ← generic, drop
  1,505,362    Password123           ← generic-ish
  1,406,394    letmein               ← generic-ish
        180    flexdemo              ← SWEET SPOT — real but rare
          0    twilio2025            ← company-specific, untested
          0    xpkqwmnvbzabc12345    ← random, untested
```

`flexdemo` = 180 means real humans have used this exact password 180 times across known breaches. It's a real password pattern, but not generic enough to be in every spray list. Highest value for spray.

## Pipeline position

```
/wordlist-gen target.com           -> ranked.txt (cewler+hashcat, 100k-300k candidates)
/osint-employees target.com        -> usernames.txt + personal-passwords.txt
/breach-check ranked.txt           -> ranked-ranked.txt (HIBP-enriched, sorted by breach count)
                                       └─ filter --max-count 1000000 to drop boring generic
[PR #5] /spray <login> -u users -p ranked-ranked.txt
```

## Output

- **`<input>-ranked.txt`** — passwords sorted by breach count DESC (most-leaked first; one per line)
- **`<input>-ranked-counts.tsv`** *(with `--with-counts`)* — `count\tpassword` for analysis

## Performance

HIBP allows ~25 req/sec; default 20 concurrent threads ~= 1500 req/min.

- 1,000 passwords  → ~50 seconds
- 10,000           → ~5 minutes
- 100,000          → ~50 minutes
- 300,000+         → consider `--limit` or pre-shrink with `/wordlist-gen --mode minimal`

Grouping by SHA-1 prefix reduces API calls. For a 300k wordlist, expect ~270k unique prefixes (10% collision typical).

## Dependencies

Pure Python 3.9+, no external deps (uses urllib + hashlib + ThreadPoolExecutor from stdlib).

## Underlying tool

`tools/breach_checker.py <wordlist> [flags]` — call directly if you prefer a non-slash interface.