HIBP Email Breach Checker

A Python home lab tool for checking email addresses against the Have I Been Pwned (HIBP) v3 API. Supports single and bulk email lookups with rate-limit-safe delays and formatted console output.

Author: Aaron Dutton
License: MIT
API Docs: https://haveibeenpwned.com/API/v3

• Single email check with full breach details (domain, date, affected accounts, data types, verified/sensitive flags)
• Bulk email check for multiple addresses via CLI or direct function call
• Rate-limit-safe delay between requests (1.6s default, under HIBP's 10 RPM limit)
• Clear error messaging that distinguishes test API key limitations from real auth failures
• Test mode using HIBP's official integration test addresses — no paid key required to get started

• Python 3.10+
• python-dotenv

pip install python-dotenv

See requirements.txt for the full dependency list.

1. Clone or copy Hibp_email_checker.py into your project directory.
2. Create a .env file in the same directory:

HIBP_API_KEY=your_api_key_here

To get started without a paid key, leave the value as the test key:

HIBP_API_KEY=00000000000000000000000000000000

The test key only works with HIBP's official test addresses (see Test Mode below).
To query real email addresses, sign up for a paid key at https://haveibeenpwned.com/API/Key.

python Hibp_email_checker.py youraddress@gmail.com

python Hibp_email_checker.py email1@example.com email2@example.com email3@example.com

python Hibp_email_checker.py

Single check returns full breach detail per result:

============================================================
  Email : example@gmail.com
============================================================
  Result: ⚠️  Found in 2 breaches.

  [ 1] Adobe
       Domain    : adobe.com
       Breached  : 2013-10-04
       Accounts  : 152,445,165
       Verified  : Yes  |  Sensitive: No
       Data Types: Email addresses, Password hints, Passwords, Usernames

Bulk check returns breach names only (truncated for speed):

Bulk checking 3 email(s) — 1.6s delay between requests.

  Email : example@gmail.com
  Result: ⚠️  Found in 2 breaches.
  [ 1] Adobe
  [ 2] LinkedIn

HIBP provides official test addresses for use with the test API key. Running the script with no arguments will bulk check all three:

Note: The test key (00000000000000000000000000000000) only works with @hibp-integration-tests.com addresses. Querying any other address with the test key will return a 401 error.

This tool sends the full email address to the HIBP API. It does not use the K-anonymity / hash prefix feature, which keeps email addresses private by only sending a partial hash. That feature requires a higher-tier paid account and is not implemented here.

With a standard paid account you can check whether an email appears in a public breach without proving ownership of that address. To check sensitive breaches (e.g. adult websites, illicit forums), HIBP requires you to verify ownership by clicking a verification link sent to that inbox.

If an email address appears in a known breach:

• Change the password on the affected site if you haven't done so since the breach date
• Enable MFA on the affected site if available
• If the breach is recent, check whether the vendor provides user login/activity logs you can review for unauthorized access

Note: check_email() and check_single() use opposite parameter naming conventions (truncate vs full_details). See inline docstrings for details.

• REST API integration using Python standard library (urllib) — no requests dependency
• API key management via .env and python-dotenv
• HTTP error handling with specific messaging per status code (401, 403, 404, 429)
• Rate limiting with configurable delay to respect third-party API constraints
• CLI argument routing for single vs. bulk execution modes
• GRC-framed tooling: breach awareness, MFA remediation guidance, log review recommendations