Email / Domain Breach Monitor

Watches the email addresses you care about — individual accounts and/or every address on a domain you own — and tells you the moment one of them turns up in a new data breach, with the breach name, date, scale, and exactly what data was exposed.

This is the account half of breach monitoring. Its companion, leaked-password-scan, is the password half:

Why a monitor, not a one-shot

Running an account through HIBP once tells you its history. The value is in the new events. This workflow keeps a small JSON state file of the breaches it has already reported per account. Each run it reports only what's new since last time, then updates the state.

So on a weekly schedule you get nothing in your inbox — until the week one of your addresses shows up in a freshly disclosed breach, and then you get one specific, actionable alert. The first run establishes the baseline (it reports everything once).

What it does

1. monitor — a runtimeenv task runs a Python script (stdlib only — urllib + json, no curl/jq/pip). For each account it calls GET /breachedaccount/{account}?truncateResponse=false; for a verified domain it calls GET /breacheddomain/{domain}. It diffs the results against the state file and prints a report of only the new exposures. Rate-limited and 429-aware.
2. notify — the report is sent to you on your InTouch channel.

No AI, no per-run token cost — fully deterministic.

Example output

============================================================
  EMAIL / DOMAIN BREACH MONITOR  —  Have I Been Pwned
============================================================
Monitoring: 3 account(s), domain blueisle.com
New breach exposures this run: 2   Errors: 0

  [email protected]
      - SomeService  (2026-05-30, 8,200,000 accounts)
          exposed: Email addresses, Passwords, Names

  [email protected]
      - NewsletterCo  (2026-05-22, 410,000 accounts)
          exposed: Email addresses, IP addresses

ACTION: for each exposed account, change the password there
and anywhere it was reused, and enable MFA. Run
leaked-password-scan on the affected passwords.

Source: Have I Been Pwned v3 API (authenticated).

Setup

1. Get an HIBP API key

The account and domain endpoints require a key — get one at https://haveibeenpwned.com/API/Key. (The password endpoint used by leaked-password-scan does not — only this account/domain workflow needs a key.)

2. Store the key on a runtime environment

The key goes in a Runtime Environment, not in the workflow file:

1. Runtime Environments view → create a python runtime env (command python3, e.g. named hibp).
2. Add an environment variable: HIBP_API_KEY = your key.
3. (optional) HIBP_DELAY = 1.7 — seconds between account lookups. Raise it if your key tier allows fewer than ~10 requests/minute (the script also auto-backs-off on HTTP 429).

The script is Python stdlib-only — nothing to install.

3. Placeholders in workflow.yaml

You can run in account mode (accounts file only), domain mode (verified domain only), or both. At least one is required.

Schedule

Weekly is the sweet spot — HIBP loads breaches in batches, not continuously, so more frequent runs just burn API quota. The first run reports all existing exposures as the baseline; subsequent runs are quiet until something new lands.

The workflow exits non-zero (code 2) when new exposures are found, so you can branch downstream automation on the result.

Notes & limits

• Domain search requires domain verification. /breacheddomain only works for domains you've proven you control in your HIBP dashboard. Account search works for any address.
• Rate limits are per key tier. The default 1.7s spacing suits the entry tier (~10 req/min). For large account lists on a slow tier, raise HIBP_DELAY or upgrade the key — the script honors Retry-After on 429 either way.
• 404 is good news — it means the account is not in any breach; the script treats it as "clean," not an error.
• Pair it with leaked-password-scan. When this workflow flags an account, run the password scanner on that account's password to see if the specific credential is also circulating.

Credits

Powered by Have I Been Pwned by Troy Hunt. Breach data licensed under the Open Data Commons Attribution License.