A Python wrapper for Troy Hunt's Pwned Passwords API.
Project description
Python Library and CLI for the Pwned Password v2 API
About
From https://haveibeenpwned.com/API/v2#PwnedPasswords:
Pwned Passwords are more than half a billion passwords which have previously been exposed in data breaches. The service is detailed in the launch blog post then further expanded on with the release of version 2. The entire data set is both downloadable and searchable online via the Pwned Passwords page.
pwnedpasswords is a small Python wrapper and command line utility that exposes the functionality of the Pwned Passwords API.
Installation
pwnedpasswords is available for download through PyPi. You can install it right away using pip.
pip install pwnedpasswordsUsage
import pwnedpasswords
# Return the number of times `testing 123` appears in the Pwned Passwords database.
pwnedpasswords.check("testing 123")And that’s it! :tada:
Notes
pwnedpasswords will automatically check to see if your provided input looks like a SHA-1 hash. If it looks like plain text, it’ll automatically hash it before sending it to the Pwned Passwords API.
If you’d like to provide an already-hashed password as input, you don’t need to do anything special–pwnedpasswords will detect that it looks like a SHA-1 hash and won’t hash it again.
pwnedpasswords.check("b8dfb080bc33fb564249e34252bf143d88fc018f")Likewise, if a password looks like a SHA-1 hash, but is actually a user-provided password, set plain_text to True, so that the library knows to hash it before checking it against the database.
pwnedpasswords.check("1231231231231231231231231231231231231231", plain_text=True)Details
check
This is the preferred method. By default, the check method uses the https://api.pwnedpasswords.com/range/ endpoint, which is k-anonymous.
pwnedpasswords.check("mypassword")
# 8340If you’d like to force pwnedpasswords to use the search endpoint instead (https://api.pwnedpasswords.com/pwnedpassword/), set the anonymous parameter to False.
pwnedpasswords.check("password", anonymous=False)
# 3303003You might want to do this if you’d prefer faster response times, and aren’t that worried about leaking passwords you’re searching for over the network.
If you’d like direct access to the search and range endpoints, you can also call them directly.
search
pwnedpasswords.search("testing 123")
# outputs 1range
pwnedpasswords.range("098765")
# outputs a dictionary mapping SHA-1 hash suffixes to frequency countsCommand Line Utility
pwnedpasswords comes bundled with a handy command line utility. Usage is pretty straightforward–just provide the password in question as the first argument:
$ pwnedpasswords 123456password
240The output is simply the number of entries found in the Pwned Passwords database.
For help, just provide -h as a command-line argument.
$ pwnedpasswords -h
usage: pwnedpasswords [-h] [--plain-text] [--verbose] password
positional arguments:
password The password or hashed password to search for.
optional arguments:
-h, --help show this help message and exit
--plain-text Specify that the provided input is plain text, even if it
looks like a SHA-1 hash.
--verbose Display verbose output.Note
The CLI returns an exit code equal to the base-10 log of the result count, plus 1. If there are no matches in the API, the exit status will be 0. While returning the base-10 log might seem odd, note that most systems require exit status codes to be in the range 0-127, and I wanted the status code to provide some indication for severity. log(N) seemed to be a good tradeoff. The exit status is log(N)+1 since there are plenty of matches in the database with 1 match.
If you’d like to take a look under the hood to make sure things are working as they should, set the --verbose flag.
$ pwnedpasswords 123456password --verbose
INFO:pwnedpasswords.pwnedpasswords:https://api.pwnedpasswords.com/range/5052C
INFO:pwnedpasswords.pwnedpasswords:Entry found
240Thanks
Special thanks to Troy Hunt for collecting this data and providing this service.
License
Apache License, Version 2.0. See LICENSE for details.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
Hashes for pwnedpasswords-1.1.0-py2.py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | dde9be953f6966cf428eb77b3d3a6b59a9be1336b2216674db8449a38fd8cc65 |
|
| MD5 | a4d40cd1c9afe3189e18aa13c596fb1a |
|
| BLAKE2b-256 | 948380184fdefd559198f4768f4192c037525760b6ae6927844da4b2c971b3ad |
