Metadata-Version: 2.1
Name: pyHIBP
Version: 2.1.0
Summary: An interface to Troy Hunt's 'Have I Been Pwned' public API
Home-page: https://gitlab.com/kitsunix/pyHIBP/pyHIBP
Author: Kyra F. Kitsune
License: UNKNOWN
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Provides-Extra: dev
Requires-Dist: requests (>=2.18.4)
Requires-Dist: six (>=1.11.0)
Provides-Extra: dev
Requires-Dist: check-manifest; extra == 'dev'
Requires-Dist: tox; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: check-manifest; extra == 'dev'
Requires-Dist: flake8; extra == 'dev'
Requires-Dist: vcversioner; extra == 'dev'

pyHIBP (pyHave I Been Pwned)
============================

.. image:: https://mybinder.org/badge.svg
    :target: https://mybinder.org/v2/gl/kitsunix%2FpyHIBP%2FpyHIBP-binder/master

-----------------


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
----------

.. code::

    pip install pyHIBP

Example usage
-------------

.. code-block:: python

    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:

.. code:: python

    # 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.

.. _HIBP API Reference: https://haveibeenpwned.com/API/v2
.. _Pwned Passwords: https://haveibeenpwned.com/Passwords


