Breach Check Agent

A production-quality password breach checker that uses the Have I Been Pwned (HIBP) Pwned Passwords API with the k-anonymity model to ensure your passwords are never exposed.

What It Does

Breach Check Agent checks whether a given password has appeared in known data breaches. It provides:

• CLI tool — Check passwords from the terminal with hidden input
• REST API — FastAPI service with rate limiting and CORS
• Web UI — Clean frontend for non-technical users
• Agent skill — SKILL.md for AI coding/security agents

How k-Anonymity Protects Your Password

Traditional password-checking services require sending the full password (or its hash) to a server. This creates a privacy risk: the server operator could potentially record or abuse that data.

Breach Check Agent uses the HIBP k-anonymity model to eliminate this risk:

1. Local hashing: Your password is hashed with SHA-1 on your machine. The raw password never leaves your device.
2. Partial transmission: Only the first 5 characters of the SHA-1 hash are sent to the HIBP API. This is a tiny, irreversible fragment that cannot be used to reconstruct the password.
3. Local matching: HIBP returns ALL password hash suffixes that match those 5 characters (typically 400-600 results). The actual comparison happens locally — the HIBP server never knows which specific suffix you're looking for.
4. No storage: Passwords are never stored, logged, or cached anywhere.

Result: Even if someone monitors all network traffic or compromises the HIBP server, they cannot determine which password was checked. The 5-character prefix is shared by hundreds of other passwords.

Installation

From source

# Clone the repository
git clone https://github.com/rksharma-owg/breach-check-agent.git
cd breach-check-agent

# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate   # Windows

# Install dependencies
pip install -e ".[dev]"

With Docker

# Build and run with Docker Compose
docker compose up --build -d

# The API + frontend is available at http://localhost:8000

CLI Usage

Interactive mode (recommended)

breach-check password
# Prompts for hidden input — password never appears on screen

JSON output (for automation)

breach-check password --json
# Output:
# {
#   "pwned": true,
#   "count": 57632146,
#   "recommendation": "This password appeared 57,632,146 time(s)..."
# }

Read from stdin

echo "your_password" | breach-check password --stdin --json

Verbose logging

breach-check password --verbose

API Usage

Start the server

# From source
uvicorn breach_check_agent.api:app --host 0.0.0.0 --port 8000

# Or with Docker
docker compose up

Check a password

curl -X POST http://localhost:8000/check-password \
  -H "Content-Type: application/json" \
  -d '{"password": "your_password_here"}'

Response (pwned):

{
  "pwned": true,
  "count": 57632146,
  "recommendation": "This password appeared 57,632,146 time(s) in data breaches. It is one of the most commonly leaked passwords. Change it NOW and use a password manager."
}

Response (safe):

{
  "pwned": false,
  "count": 0,
  "recommendation": "This password was NOT found in known data breaches. However, always use a unique, strong password for each account."
}

Health check

curl http://localhost:8000/health
# {"status": "ok", "version": "1.0.0"}

API documentation

When the server is running, interactive API docs are available at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Rate limiting

By default, the API allows 5 requests per 60 seconds per IP address. Configure via environment variables:

export RATE_LIMIT_REQUESTS=10
export RATE_LIMIT_WINDOW=60

Docker Usage

# Build and start
docker compose up --build -d

# View logs
docker compose logs -f

# Stop
docker compose down

# Rebuild after changes
docker compose up --build -d

Environment configuration

Copy .env.example to .env and adjust:

cp .env.example .env

Variable	Default	Description
HIBP_API_URL	https://api.pwnedpasswords.com	HIBP API base URL
API_HOST	0.0.0.0	Bind host
API_PORT	8000	Bind port
RATE_LIMIT_REQUESTS	5	Max requests per window
RATE_LIMIT_WINDOW	60	Rate limit window (seconds)
CORS_ORIGINS	http://localhost:3000	Allowed CORS origins
LOG_LEVEL	INFO	Logging level

Running Tests

# Install test dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run specific test file
pytest tests/test_security.py -v

Project Structure

breach-check-agent/
├── README.md              # This file
├── SKILL.md               # Agent skill documentation
├── .gitignore             # Git ignore rules
├── .env.example           # Environment variable template
├── docker-compose.yml     # Docker Compose configuration
├── Dockerfile             # Multi-stage Docker build
├── pyproject.toml         # Python project configuration
├── src/
│   └── breach_check_agent/
│       ├── __init__.py    # Package init
│       ├── security.py   # SHA-1 hashing, prefix/suffix, redaction
│       ├── hibp_client.py # HIBP API client (k-anonymity)
│       ├── cli.py         # Command-line interface
│       └── api.py         # FastAPI REST service
├── frontend/
│   ├── index.html         # Web UI
│   ├── style.css          # Styles
│   └── app.js             # Frontend logic
└── tests/
    ├── test_security.py   # Security module tests
    ├── test_hibp_client.py # HIBP client tests (mocked)
    └── test_api.py        # API endpoint tests

Security Limitations

1. SHA-1 weaknesses: This tool uses SHA-1 for hashing because that is what the HIBP Pwned Passwords database uses. SHA-1 is cryptographically broken for collision resistance, but preimage resistance remains adequate for this use case (mapping a password to a fixed identifier).

2. Network exposure: While only a 5-character hash prefix is sent, a network observer can see that a breach check was performed. They cannot determine which password was checked.

3. Not a password manager: This tool only checks passwords against known breaches. It does not store, generate, or manage passwords.

4. HIBP API availability: The service depends on the HIBP API being available and accurate. If the API is down, checks will fail gracefully.

5. False negatives: A password that hasn't appeared in a breach YET is not necessarily safe. New breaches are discovered regularly.

6. API endpoint: When using the web UI or API, passwords are sent from the browser to the local backend over HTTP. In production, always use HTTPS (via a reverse proxy like nginx or Caddy).

Important

Do NOT use this tool to collect, log, or store user passwords. The code is designed to prevent password leakage, but the responsibility for ethical use lies with the operator. Deploy only with informed consent from users whose passwords you are checking.

License

MIT License — see LICENSE for details.