pyhibp 4.2.0

Description:

pyhibp 4.2.0

pyHIBP (pyHave I Been Pwned)



A Python interface to Troy Hunt's 'Have I Been Pwned?' (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, or when another API-defined error condition is encountered based on the submitted data. When
data is found from a call, the data returned will be in the format as retrieved from the endpoint, documented
in the return-type information for the relevant function.
Note that the pwnedpasswords API backend does not have a rate limit. If you are intending to bulk-query passwords or
hashes, you should consider downloading the raw data files accessible via the Pwned Passwords page.
Installing
$ pip install pyhibp

Example usage
For an interactive example, check out the Jupyter Notebook for pyhibp,
as well as pyhibp.pwnedpasswords.
import pyhibp
from pyhibp import pwnedpasswords as pw

# Required: A descriptive user agent must be set describing the application consuming
# the HIBP API
pyhibp.set_user_agent(ua="Awesome application/0.0.1 (An awesome description)")

# 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 {0} time(s) before.".format(resp))

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

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

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

# An API key is required for calls which search by email address
# (so get_pastes/get_account_breaches)
# See <https://haveibeenpwned.com/API/Key>
HIBP_API_KEY = None

if HIBP_API_KEY:
# Set the API key prior to using the functions which require it.
pyhibp.set_api_key(key=HIBP_API_KEY)

# Get pastes affecting a given email address
resp = pyhibp.get_pastes(email_address="[email protected]")

# Get breaches that affect a given account
resp = pyhibp.get_account_breaches(account="[email protected]", truncate_response=True)

Developing
In order to ensure we have a consistent and repeatable development environment
we use a virtual environment, namely pipenv.
To develop or test, execute the following:
# Install the prerequisite 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.