Skip to main content

An interface to Troy Hunt's 'Have I Been Pwned' public API

Project description

An interface to Troy Hunt’s ‘Have I Been Pwned?’ (herein referred to as HIBP) public API. A full reference to the API specification can be found at the HIBP API Reference.

This module detects when the rate limit of the API has been hit, and raises a RuntimeError when the limit is exceeded. pyHIBP._process_response contains the full list of items that will result in a raised exception. In summary, a call to the module returning Boolean True or the object as decoded from the API query (currently, lists), represent a detection that a breached account/paste/password was found; Boolean False means that the item was not found.

Note that the pwnedpasswords module does _not_ have a rate-limit. If you are intending to bulk-query passwords or hashes, you may also consider downloading the raw data files accessible via the Pwned Passwords page.

Installing

pip install pyHIBP

Example usage

import pyHIBP
from pyHIBP import pwnedpasswords as pw

# Check a password to see if it has been disclosed in a public breach corpus
resp = pw.is_password_breached(password="secret")
if resp:
    print("Password breached!")
    print("This password was used " + str(resp) + " time(s) before.")

# Get breaches that affect a given account
resp = pyHIBP.get_account_breaches(account="test@example.com", truncate_response=True)

# Get all breach information
resp = pyHIBP.get_all_breaches()

# Get a single breach
resp = pyHIBP.get_single_breach(breach_name="Adobe")

# Get pastes affecting a given email address
resp = pyHIBP.get_pastes(email_address="test@example.com")

# Get data classes in the HIBP system
resp = pyHIBP.get_data_classes()

Developing

This project is intended to be compatible with Python 2 and Python 3. As such, we use virtual environments via pipenv. To develop or test, execute the following:

# Install the pre-requisite virtual environment provider
pip install pipenv
# Initialize the pipenv environment and install the module within it
make dev
# To run PEP8, tests, and check the manifest
make tox

Other commands can be found in the Makefile.

Goals

  • Synchronize to the latest HIBP API(s), implementing endpoint accessing functions where it makes sense. For instance, in the interest of security, the ability to submit a SHA-1 to the Pwned Passwords endpoint is not implemented. See “Regarding password checking” below for further details.

  • For breaches and pastes, act as an intermediary; return the JSON as received from the service.

Regarding password checking

  • For passwords, the option to supply a plaintext password to check is provided as an implementation convenience.

  • For added security, pwnedpasswords.is_password_breached() only transmits the first five characters of the SHA-1 hash to the Pwned Passwords API endpoint; a secure password will remain secure without disclosing the full hash.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyHIBP-2.0.2.tar.gz (25.3 kB view hashes)

Uploaded Source

Built Distribution

pyHIBP-2.0.2-py2.py3-none-any.whl (7.5 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page