Email Breach Checker CLI

Where it came from

During the live penetration test I supported through Evolve Security Academy, we needed to check whether the client's email addresses appeared in known breaches. Doing that one address at a time in a browser does not scale, and ad-hoc scripts rarely produce clean artifacts for a report. I wrote the first version of this tool to automate those checks. The output went into the engagement report.

Afterward I rebuilt it as Email Breach Checker, a packaged Python CLI with tests, CI, and a real release structure.

What it does

• Reads emails from .txt files or extracts them from any .csv with pattern matching, and deduplicates as it goes
• Queries the Have I Been Pwned API with rate limiting so the tool stays a good API citizen
• Writes a grouped summary CSV with breach counts, titles, domains, dates, verification status, and compromised data types
• Logs failed lookups separately with the HTTP status and error detail, so retries are easy
• Returns meaningful exit codes so it can run unattended in scripts

Usage sketch

export HIBP_API_KEY=your_api_key
email-breach-checker examples/emails.txt --output results.csv

Why it matters

Breach exposure shows up in phishing work, user education, and incident triage. Automating the lookup keeps the analyst on interpretation: which accounts matter, which services leaked, and what remediation looks like. The copy-paste part is the part a script should own.

It was also my first real lesson in the difference between a script that works and a tool other people can use. Packaging, input validation, failure logging, and tests turned a one-off engagement helper into something I would hand to a teammate.