class Hibp::Client

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

Constants

CORE_API_HOST
CORE_API_SERVICES
PASSWORD_API_HOST

Attributes

authorization_header[R]

Public Class Methods

new(api_key = '') click to toggle source

@param api_key [String] - (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 haveibeenpwned.com/API/Key

# File lib/hibp/client.rb, line 37
def initialize(api_key = '')
  @authorization_header = { 'hibp-api-key' => api_key }
end

Public Instance Methods

account_breaches(account) click to toggle source

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

@param account [String] - The email address to be searched for.

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

@return [Hibp::Query]

# File lib/hibp/client.rb, line 75
def account_breaches(account)
  configure_core_query(:account_breaches, CGI.escape(account))
end
breach(name) click to toggle source

Find a single breached site

@param name [String] - Breach name

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

@return [Hibp::Query]

# File lib/hibp/client.rb, line 49
def breach(name)
  configure_core_query(:breach, name)
end
breaches() click to toggle source

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

@note Collection is sorted alphabetically by the title of the breach.

@return [Hibp::Query]

# File lib/hibp/client.rb, line 60
def breaches
  configure_core_query(:breaches)
end
data_classes() click to toggle source

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.

@return [Hibp::Query]

# File lib/hibp/client.rb, line 88
def data_classes
  configure_core_query(:data_classes)
end
passwords(password, add_padding: false) click to toggle source

Search pwned passwords

@param password [String] -

The value of the source password being searched for

@param add_padding [Boolean] -

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.

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

@return [Hibp::Query]

# File lib/hibp/client.rb, line 128
def passwords(password, add_padding: false)
  configure_password_query(password, add_padding)
end
pastes(account) click to toggle source

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.

@param account [String] - The email address to be searched for.

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

@return [Hibp::Query]

# File lib/hibp/client.rb, line 108
def pastes(account)
  configure_core_query(:pastes, CGI.escape(account))
end

Private Instance Methods

configure_core_query(service, parameter = nil) click to toggle source
# File lib/hibp/client.rb, line 142
def configure_core_query(service, parameter = nil)
  endpoint = resolve_endpoint(service, parameter)
  parser = resolve_parser(service)

  Query.new(endpoint: endpoint, parser: parser, headers: @authorization_header)
end
configure_password_query(password, add_padding) click to toggle source
# File lib/hibp/client.rb, line 134
def configure_password_query(password, add_padding)
  pwd_hash = ::Digest::SHA1.hexdigest(password).upcase
  endpoint = "#{PASSWORD_API_HOST}/#{pwd_hash[0..4]}"
  headers = add_padding ? {'Add-Padding' => 'true'} : {}

  Query.new(endpoint: endpoint, headers: headers, parser: Parsers::Password.new)
end
resolve_endpoint(service, parameter) click to toggle source
# File lib/hibp/client.rb, line 149
def resolve_endpoint(service, parameter)
  endpoint = "#{CORE_API_HOST}/#{CORE_API_SERVICES[service]}"

  parameter ? "#{endpoint}/#{parameter}" : endpoint
end
resolve_parser(service) click to toggle source
# File lib/hibp/client.rb, line 155
def resolve_parser(service)
  breach_services = %i[breach breaches account_breaches]

  case service
  when ->(n) { breach_services.include?(n) }
    Parsers::Breach.new
  when :pastes
    Parsers::Paste.new
  when :data_classes
    Parsers::Json.new
  end
end