A Python wrapper for Troy Hunt's Pwned Passwords API.
Project description
.. raw:: html
<!-- <p align="center">
<img width="344" height="225" src="meta/repo-banner-small.png" />
</p> -->
|image0| |image1|
|CI Status| |Version| |Python Versions|
``pwnedpasswords`` is a small Python wrapper and command line utility
that lets you check if a passphrase has been pwned using the `Pwned
Passwords v2 API <https://haveibeenpwned.com/API/v2#PwnedPasswords>`_.
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 <https://www.troyhunt.com/introducing-306-million-freely-downloadable-pwned-passwords/>`_
then `further expanded on with the release of version
2 <https://www.troyhunt.com/ive-just-launched-pwned-passwords-version-2>`_.
The entire data set is `both downloadable and searchable online via
the Pwned Passwords page <https://haveibeenpwned.com/Passwords>`_.
Installation
------------
pwnedpasswords is available for download through
`PyPi <https://pypi.python.org/pypi/pwnedpasswords>`_. You can install
it right away using pip.
.. code:: bash
pip install pwnedpasswords
Usage
~~~~~
.. code:: python
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.
.. code:: python
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.
.. code:: python
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 <https://en.wikipedia.org/wiki/K-anonymity>`_.
.. code:: python
pwnedpasswords.check("mypassword")
# 34729
If you’d like to force pwnedpasswords to use the search endpoint instead
(https://api.pwnedpasswords.com/pwnedpassword/), set the ``anonymous``
parameter to ``False``.
.. code:: python
pwnedpasswords.check("password", anonymous=False)
# 3303003
You 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``
~~~~~~~~~~
.. code:: python
pwnedpasswords.search("testing 123")
# outputs 1
``range``
~~~~~~~~~
.. code:: python
pwnedpasswords.range("098765")
# outputs a dictionary mapping SHA-1 hash suffixes to frequency counts
Command 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:
.. code:: bash
$ pwnedpasswords 123456password
240
The output is simply the number of entries found in the Pwned Passwords
database.
For help, just provide ``-h`` as a command-line argument.
.. code:: bash
$ 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.
.. code:: bash
$ pwnedpasswords 123456password --verbose
INFO:pwnedpasswords.pwnedpasswords:https://api.pwnedpasswords.com/range/5052C
INFO:pwnedpasswords.pwnedpasswords:Entry found
240
Thanks
------
Special thanks to `Troy Hunt <https://www.troyhunt.com>`_ for
collecting this data and providing this service.
Authors
-------
Dan Loewenherz / ([@dlo](https://github.com/dlo))
License
-------
Apache License, Version 2.0. See `LICENSE <https://github.com/lionheart/pwnedpasswords/blob/master/LICENSE>`_ for details.
.. |image0| image:: meta/repo-banner.png
.. |image1| image:: meta/repo-banner-bottom.png
:target: https://github.com/lionheart/pwnedpasswords/blob/master/https://lionheartsw.com/
.. |CI Status| image:: https://img.shields.io/travis/lionheart/pwnedpasswords.svg?style=flat
:target: https://github.com/lionheart/pwnedpasswords/blob/master/https://travis-ci.org/lionheart/pwnedpasswords
.. |Version| image:: https://img.shields.io/pypi/v/pwnedpasswords.svg?style=flat
:target: https://github.com/lionheart/pwnedpasswords/blob/master/https://pypi.python.org/pypi/pwnedpasswords
.. |Python Versions| image:: https://img.shields.io/pypi/pyversions/pwnedpasswords.svg?style=flat
:target: https://github.com/lionheart/pwnedpasswords/blob/master/https://pypi.python.org/pypi/pwnedpasswords
<!-- <p align="center">
<img width="344" height="225" src="meta/repo-banner-small.png" />
</p> -->
|image0| |image1|
|CI Status| |Version| |Python Versions|
``pwnedpasswords`` is a small Python wrapper and command line utility
that lets you check if a passphrase has been pwned using the `Pwned
Passwords v2 API <https://haveibeenpwned.com/API/v2#PwnedPasswords>`_.
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 <https://www.troyhunt.com/introducing-306-million-freely-downloadable-pwned-passwords/>`_
then `further expanded on with the release of version
2 <https://www.troyhunt.com/ive-just-launched-pwned-passwords-version-2>`_.
The entire data set is `both downloadable and searchable online via
the Pwned Passwords page <https://haveibeenpwned.com/Passwords>`_.
Installation
------------
pwnedpasswords is available for download through
`PyPi <https://pypi.python.org/pypi/pwnedpasswords>`_. You can install
it right away using pip.
.. code:: bash
pip install pwnedpasswords
Usage
~~~~~
.. code:: python
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.
.. code:: python
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.
.. code:: python
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 <https://en.wikipedia.org/wiki/K-anonymity>`_.
.. code:: python
pwnedpasswords.check("mypassword")
# 34729
If you’d like to force pwnedpasswords to use the search endpoint instead
(https://api.pwnedpasswords.com/pwnedpassword/), set the ``anonymous``
parameter to ``False``.
.. code:: python
pwnedpasswords.check("password", anonymous=False)
# 3303003
You 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``
~~~~~~~~~~
.. code:: python
pwnedpasswords.search("testing 123")
# outputs 1
``range``
~~~~~~~~~
.. code:: python
pwnedpasswords.range("098765")
# outputs a dictionary mapping SHA-1 hash suffixes to frequency counts
Command 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:
.. code:: bash
$ pwnedpasswords 123456password
240
The output is simply the number of entries found in the Pwned Passwords
database.
For help, just provide ``-h`` as a command-line argument.
.. code:: bash
$ 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.
.. code:: bash
$ pwnedpasswords 123456password --verbose
INFO:pwnedpasswords.pwnedpasswords:https://api.pwnedpasswords.com/range/5052C
INFO:pwnedpasswords.pwnedpasswords:Entry found
240
Thanks
------
Special thanks to `Troy Hunt <https://www.troyhunt.com>`_ for
collecting this data and providing this service.
Authors
-------
Dan Loewenherz / ([@dlo](https://github.com/dlo))
License
-------
Apache License, Version 2.0. See `LICENSE <https://github.com/lionheart/pwnedpasswords/blob/master/LICENSE>`_ for details.
.. |image0| image:: meta/repo-banner.png
.. |image1| image:: meta/repo-banner-bottom.png
:target: https://github.com/lionheart/pwnedpasswords/blob/master/https://lionheartsw.com/
.. |CI Status| image:: https://img.shields.io/travis/lionheart/pwnedpasswords.svg?style=flat
:target: https://github.com/lionheart/pwnedpasswords/blob/master/https://travis-ci.org/lionheart/pwnedpasswords
.. |Version| image:: https://img.shields.io/pypi/v/pwnedpasswords.svg?style=flat
:target: https://github.com/lionheart/pwnedpasswords/blob/master/https://pypi.python.org/pypi/pwnedpasswords
.. |Python Versions| image:: https://img.shields.io/pypi/pyversions/pwnedpasswords.svg?style=flat
:target: https://github.com/lionheart/pwnedpasswords/blob/master/https://pypi.python.org/pypi/pwnedpasswords
Project 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
No source distribution files available for this release.See tutorial on generating distribution archives.
Built Distribution
Close
Hashes for pwnedpasswords-1.1.1-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 574599c9964978815593456372f5f10ef5437415f8c99ebcf00156be300008ad |
|
MD5 | 0a7193e942ade745e6d69b0ce1700b46 |
|
BLAKE2b-256 | 2eb78cdb669bb3b2879dfe264e483e4e820937815972a25c7a3169de72e19db2 |