HIBP Vendor Domain Breach Checker

A GRC-focused command-line tool that reads a CSV of third-party vendors, checks each domain against the Have I Been Pwned free breach metadata API, and writes a structured CSV report suitable for use as audit evidence or vendor risk documentation.

Third-party vendor breach exposure is a core concern in any TPRM program. This tool automates a repeatable, documentable check: given a list of vendor domains, it queries HIBP's public breach metadata endpoint and produces a flat CSV report with breach names, dates, account counts, data classes exposed, and verification flags — one row per breach event, one summary row for clean or errored domains.

Designed to complement SOC 2 vendor risk reviews, HIPAA business associate assessments, and annual TPRM cycles.

• Python 3.10+
• requests

pip install requests

No API key is required. This tool uses the free HIBP breach metadata endpoint (/api/v3/breaches?domain=), which does not require authentication.

A CSV file with at least two columns: vendor name and domain. A header row is auto-detected and skipped if present.

vendor_name,domain
Adobe,adobe.com
LinkedIn,linkedin.com
Dropbox,dropbox.com

Column positions are configurable via --name-col and --domain-col (zero-indexed), so the tool works with exports from TPRM platforms that include leading ID, tier, or category columns.

# Basic — output defaults to hibp_breach_report.csv
python hibp_vendor_check.py --input vendors.csv

# Specify output path
python hibp_vendor_check.py --input vendors.csv --output breach_report.csv

# Timestamped output filename (Linux/macOS)
python hibp_vendor_check.py --input vendors.csv --output "breach_report_$(date +%F).csv"

# Non-standard column order (domain in col 0, name in col 1)
python hibp_vendor_check.py --input vendors.csv --name-col 1 --domain-col 0

# Skip leading columns (e.g. ID, name, tier, domain — domain is col 3)
python hibp_vendor_check.py --input vendors.csv --name-col 1 --domain-col 3

# Single-vendor spot check via stdin (Linux/macOS)
echo "Acme Corp,acme.com" | python hibp_vendor_check.py --input /dev/stdin

A CSV report with one row per breach event. Vendors with no breach history produce a single CLEAN row; API errors produce a single ERROR row.

Vendor Name,Domain,Check Date,Status,Breach Count,Breach Name,Breach Date,Pwned Accounts,...
LinkedIn,linkedin.com,2025-01-15,BREACHED,2,LinkedIn,2012-05-05,164611595,...
Dropbox,dropbox.com,2025-01-15,BREACHED,1,Dropbox,2012-07-01,68648009,...
Acme Corp,acme.com,2025-01-15,CLEAN,0,,,,,...

The HIBP free endpoint enforces approximately one request per 1.5 seconds. This tool uses a 1.6-second delay between requests to stay within limits. If a 429 response is received, the tool reads the retry-after header and waits accordingly before retrying once.

• Evidence use: The output CSV is structured for direct attachment as audit evidence in SOC 2 vendor risk reviews or HIPAA third-party assessments. The Check Date column supports point-in-time documentation.
• Scope: This tool checks breach metadata only — it does not query whether specific email addresses were exposed, which requires a paid HIBP API key and is subject to additional terms of use.
• Remediation workflow: BREACHED results should be triaged against your vendor's existing controls documentation (SOC 2 report, penetration test, breach notification history). A historical breach does not necessarily indicate current risk.
• Scheduling: For ongoing TPRM programs, consider running this tool on a quarterly cadence and storing output CSVs with timestamped filenames for trend tracking.

• Third-party risk management (TPRM) automation
• HIBP API integration with rate limiting and error handling
• GRC evidence generation (structured, audit-ready CSV output)
• Flexible CSV parsing with auto header detection and configurable column mapping
• Python standard library + requests; no heavy dependencies
• CLI design with argparse; stdin support for ad-hoc spot checks

Aaron Dutton License: MIT