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


Release history Release notifications

This version
History Node

2.1.0

History Node

2.0.2

History Node

2.0.1

History Node

2.0.0

Download files

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

Filename, size & hash SHA256 hash help File type Python version Upload date
pyHIBP-2.1.0-py2.py3-none-any.whl (7.1 kB) Copy SHA256 hash SHA256 Wheel py2.py3 Jul 21, 2018
pyHIBP-2.1.0.tar.gz (25.2 kB) Copy SHA256 hash SHA256 Source None Jul 21, 2018

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page