Defensive exposure toolkit for breach metadata, pwned passwords, authorized local combo files and public-source metadata.
BreachLens helps analysts check credential-exposure signals without scraping dark-web sources or collecting plaintext leaked data.
It is designed for defensive use, authorized assessments and lab work. It does not bypass paid APIs, download raw breach dumps, scrape illicit marketplaces or print plaintext passwords.
The tool works in layers:
| Layer | Cost | API key | What it does |
|---|---|---|---|
| Pwned Passwords | Free | No | Checks passwords through k-anonymity; only 5 SHA-1 chars are sent |
| Local combo-scan | Free | No | Parses authorized local email:password files and masks passwords |
| GitHub public metadata | Free tier | Optional | Searches public code metadata without downloading raw file contents |
| DNS / crt.sh | Free | No | Checks domain posture and public certificate transparency hostnames |
| HIBP account/domain metadata | Paid/optional | Yes | Official account/domain breach metadata when HIBP_API_KEY is configured |
- Organized Rich CLI output with risk summary, coverage table, skipped modules and findings table
doctorcommand to validate optional API keys and free modulespasswordcommand using Pwned Passwords k-anonymitycombo-scanfor local authorized combo files with masked passwords- Optional
--check-passwordsfor local combos using k-anonymity only emailcommand combining optional HIBP, GitHub metadata and local filesdomaincommand for DNS, crt.sh, GitHub metadata and optional HIBP domain checksgithubcommand for public metadata search by domain or e-maillocal-scanfor e-mails and secret-like assignments in local authorized files- JSON, HTML and optional TXT reports
.env.exampleincluded- No raw leaked databases, no dark-web scraping, no plaintext password reporting
git clone https://github.com/NeiveZ/BreachLens.git
cd BreachLens
chmod +x breachlens.sh
./breachlens.sh --install
source .venv/bin/activate
breachlens doctorManual install:
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .
cp .env.example .env
breachlens doctorCopy the example environment file:
cp .env.example .env
nano .envOptional values:
HIBP_API_KEY=
GITHUB_TOKEN=
BREACHLENS_TIMEOUT=20
BREACHLENS_REPORT_DIR=reportsHIBP_API_KEY is optional. Without it, official HIBP account/domain breach metadata is skipped, but free/local modules still work.
GITHUB_TOKEN is optional. It improves GitHub API rate limits.
breachlens [command] [options]
Commands:
doctor Check configuration and module readiness
password Check one password via Pwned Passwords k-anonymity
combo-scan Scan authorized local email:password-style files
email Check an e-mail using optional HIBP, GitHub and local files
domain Assess a domain using DNS, crt.sh, GitHub and optional HIBP
github Search public GitHub metadata for a domain or e-mail
local-scan Scan a local text file for e-mails and secret-like assignments
dns DNS posture check
crtsh Certificate Transparency hostname collection
demo Run bundled safe demo data
breachlens doctorbreachlens passwordOr non-interactively for lab/demo only:
breachlens password -p 'Password123!'BreachLens sends only the first 5 SHA-1 hash characters to Pwned Passwords. It does not send the plaintext password or full hash.
breachlens combo-scan examples/sample_combos.txtFilter by e-mail:
breachlens combo-scan combos.txt --email user@example.comFilter by domain:
breachlens combo-scan combos.txt --domain example.comCheck matched local passwords against Pwned Passwords with k-anonymity:
breachlens combo-scan combos.txt --domain example.com --check-passwords --max-password-checks 25Passwords are always masked in output and reports.
breachlens email user@example.com --no-hibpAdd authorized local files:
breachlens email user@example.com --no-hibp --local-file combos.txtIf HIBP_API_KEY is not configured, the HIBP module is skipped and coverage is clearly marked as limited.
breachlens email user@example.comIf .env contains HIBP_API_KEY, official HIBP account/paste metadata is queried. Otherwise, the free/local modules still run.
breachlens domain example.comWith local combo evidence:
breachlens domain example.com --local-file combos.txtWith optional HIBP domain metadata:
breachlens domain example.com --hibpbreachlens github example.com
breachlens github user@example.comBreachLens only collects metadata returned by GitHub Code Search. It does not download raw file contents.
breachlens combo-scan combos.txt --domain example.com --show-evidencebreachlens domain example.com --txtJSON and HTML are saved by default for most commands.
BreachLens uses the same organized output format across modules:
BreachLens
Target: example.com
Scan type: domain
Risk score: 35/100 — MEDIUM
Findings: 5 HIGH+: 1 MEDIUM: 2 LOW: 1 INFO: 1
Coverage
Module Status Notes
DNS posture EXECUTED MX/SPF/DMARC/CAA inventory
GitHub public metadata EXECUTED Metadata only; raw contents not downloaded
HIBP domain SKIPPED HIBP_API_KEY is not configured
Findings
Severity Source Category Title
HIGH Local scan credential_exposure Matching credential-like entries found locally
LOW Coverage coverage_limit Limited coverage mode
- No dark-web scraping
- No bypass of paid APIs
- No raw breach database downloads
- No plaintext passwords in reports
- Pwned Passwords uses k-anonymity
- HIBP account/domain lookup is optional
- Local combo scanning is for authorized files only
Without HIBP_API_KEY, BreachLens cannot honestly confirm whether an e-mail appears in official HIBP breach metadata. It can still check local authorized files, pwned passwords and public-source metadata.
A result like No matching local entries found only means the supplied local files did not contain a match. It does not prove that an account was never exposed.
For use only on accounts, domains and files you own or have explicit written authorization to assess. Unauthorized collection, possession or use of leaked credentials may be illegal.
MIT License.