Package: pyhibp
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 theHIBP 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 thepwnedpasswordsAPI 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 thePwned Passwordspage.Installing$pipinstallpyhibpExample usageFor an interactive example, check out the Jupyter Notebook forpyhibp,
as well aspyhibp.pwnedpasswords.importpyhibpfrompyhibpimportpwnedpasswordsaspw# Required: A descriptive user agent must be set describing the application consuming#   the HIBP APIpyhibp.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 corpusresp=pw.is_password_breached(password="secret")ifresp:print("Password breached!")print("This password was used{0}time(s) before.".format(resp))# Get data classes in the HIBP systemresp=pyhibp.get_data_classes()# Get all breach informationresp=pyhibp.get_all_breaches()# Get a single breachresp=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=NoneifHIBP_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 addressresp=pyhibp.get_pastes(email_address="test@example.com")# Get breaches that affect a given accountresp=pyhibp.get_account_breaches(account="test@example.com",truncate_response=True)DevelopingIn order to ensure we have a consistent and repeatable development environment
we use a virtual environment, namelypipenv.
To develop or test, execute the following:# Install the prerequisite virtual environment provider$pipinstallpipenv# Initialize the pipenv environment and install the module within it$makedev# To run PEP8, tests, and check the manifest$maketoxOther commands can be found in theMakefile.GoalsSynchronize 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 checkingFor 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.