Class: Hibp::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/hibp/client.rb

Overview

Hibp::Client

Used to fetch data from haveibeenpwned API

Public methods return `Hibp::Query` instance,
  which can be configured by applying filters

Data will only be returned if the `#fetch` method is called on the `Hibp::Query` instance.

@see https://haveibeenpwned.com/API/v3

Constant Summary collapse

CORE_API_HOST = 
'https://haveibeenpwned.com/api/v3'
PASSWORD_API_HOST = 
'https://api.pwnedpasswords.com/range'
CORE_API_SERVICES = 
{
  breach: 'breach',
  breaches: 'breaches',
  account_breaches: 'breachedaccount',
  data_classes: 'dataclasses',
  pastes: 'pasteaccount'
}.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key = '') ⇒ Client

Returns a new instance of Client.

Parameters:

  • api_key (String) (defaults to: '') —

    • (optional, default: ”)

    Authorisation is required for all APIs that enable searching HIBP by email address, namely retrieving all breaches for an account and retrieving all pastes for an account. An HIBP subscription key is required to make an authorised call and can be obtained on the API key page. The key is then passed in a “hibp-api-key” header:

See Also:



37
38
39
 
# File 'lib/hibp/client.rb', line 37

def initialize(api_key = '')
  @authorization_header = { 'hibp-api-key' => api_key }
end

Instance Attribute Details

#authorization_header ⇒ Object (readonly)

Returns the value of attribute authorization_header.



27
28
29
 
# File 'lib/hibp/client.rb', line 27

def authorization_header
  @authorization_header
end

Instance Method Details

#account_breaches(account) ⇒ Hibp::Query

Note:

This method requires authorization. HIBP API key must be used.

Note:

By default, only the name of the breach is returned rather than the complete breach data.

Note:

By default, both verified and unverified breaches are returned when performing a search.

Fetch a list of all breaches a particular account has been involved in. Available filters(truncate, unverified, domain)

Parameters:

  • account (String) —

    • The email address to be searched for.

Returns:



75
76
77
 
# File 'lib/hibp/client.rb', line 75

def ()
  configure_core_query(:account_breaches, CGI.escape())
end

#breach(name) ⇒ Hibp::Query

Note:

This is the stable value which may or may not be the same as the breach “title” (which can change).

Find a single breached site

Parameters:

  • name (String) —

    • Breach name

Returns:



49
50
51
 
# File 'lib/hibp/client.rb', line 49

def breach(name)
  configure_core_query(:breach, name)
end

#breaches ⇒ Hibp::Query

Note:

Collection is sorted alphabetically by the title of the breach.

Fetch all breached sites in the system Available filters(domain)

Returns:



60
61
62
 
# File 'lib/hibp/client.rb', line 60

def breaches
  configure_core_query(:breaches)
end

#data_classes ⇒ Hibp::Query

Fetch all data classes in the system

A “data class” is an attribute of a record compromised in a breach. For example, many breaches expose data classes such as “Email addresses” and “Passwords”. The values returned by this service are ordered alphabetically in a string array and will expand over time as new breaches expose previously unseen classes of data.

Returns:



88
89
90
 
# File 'lib/hibp/client.rb', line 88

def data_classes
  configure_core_query(:data_classes)
end

#passwords(password, add_padding: false) ⇒ Hibp::Query

Note:

The API will respond with include the suffix of every hash beginning with the specified password prefix(five first chars of the password hash), and with a count of how many times it appears in the data set.

Search pwned passwords

Parameters:

  • password (String) —

    - The value of the source password being searched for

  • add_padding (Boolean) (defaults to: false) —

    - Pads out the response with a random number of fake requests, to prevent anyone looking at the responses from guessing what the hash prefix was.

Returns:



128
129
130
 
# File 'lib/hibp/client.rb', line 128

def passwords(password, add_padding: false)
  configure_password_query(password, add_padding)
end

#pastes(account) ⇒ Hibp::Query

Note:

This is an authenticated API and an HIBP API key must be passed with the request.

Note:

The collection is sorted chronologically with the newest paste first.

Search an account for pastes.

HIBP searches through pastes that are broadcast by the @dumpmon Twitter account and reported as having emails that are a potential indicator of a breach.

Finding an email address in a paste does not immediately mean it has been disclosed as the result of a breach. Review the paste and determine if your account has been compromised then take appropriate action such as changing passwords.

Parameters:

  • account (String) —

    • The email address to be searched for.

Returns:



108
109
110
 
# File 'lib/hibp/client.rb', line 108

def pastes()
  configure_core_query(:pastes, CGI.escape())
end