hibp-client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b0cfa93448ab5ba699ccf06ac4ca9804fcaa5effd45eb2f76c8a44002efd37f8
+  data.tar.gz: 4e62ca0302d615f411069604503823bc45224090ae6dd8c9ddce49b9a4181e22
+SHA512:
+  metadata.gz: d3dd01fbe7202f178cd86927e17d5f54b1b6976b9afbaaa3432c0c1989c405fe58ff836ee1daab0a810bbf38bc18f85ec3da7ba19a90fd5d90fd73bb99a21ede
+  data.tar.gz: 52460687b7e9c93413bc2397827adcac2cbd23af7b7d99173e8a43cd34aeae26f0bee47c8d5603d31def57b1ad78e632f6ed4a9aee094cede44a30018f9512d0

data/.gitignore

@@ -0,0 +1,66 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+# Ignore Byebug command history file.
+.byebug_history
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# IDE files
+.idea
+
+# rspec failure tracking
+.rspec_status
+
+# For those using rbenv
+.ruby-version
+
+# Don't checkin Gemfile.lock
+# See: http://yehudakatz.com/2010/12/16/clarifying-the-roles-of-the-gemspec-and-gemfile/
+Gemfile.lock

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,13 @@
+---
+sudo: false
+language: ruby
+
+cache: bundler
+
+before_install: gem install bundler
+
+rvm:
+  - 2.6
+  - 2.5
+  - 2.4
+  - 2.3

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in hibp.gemspec
+
+group :development, :test do
+  gem 'webmock', '~>1.24.0'
+end
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 warshavski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,189 @@
+# Hibp
+
+[![Build Status](https://travis-ci.com/Warshavski/hibp.svg?branch=master)](https://travis-ci.com/Warshavski/hibp)
+
+A simple Ruby client for interacting with [Have I Been Pwned](https://haveibeenpwned.com/) REST API.
+
+This gem based on [API v3](https://haveibeenpwned.com/API/v3)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'hibp'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install hibp
+
+## Usage
+
+This gem incapsulates all API requests and data transformation. 
+
+The top-level object needed for gem functionality is the `Hibp::Client` object. 
+A client may require your API key in case if you want to use services such as:
+
+ - Getting all breaches for an account.
+ - Getting all pastes for an account.
+
+The API of the SDK is manipulated using `Hibp::Query` queries return different entities, but the mapping is not one to one.
+
+Some of the methods support adding filters to them. The filters are created using the `Hibp::Query` class. After instantiating the class, you can invoke methods in the form of comparison(field, value).
+
+
+### Authorization
+
+An authorization 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 authorized call and can be obtained on the API [key page](https://haveibeenpwned.com/API/Key). 
+The key is then passed as a client constructor argument:
+
+```ruby
+client = Hibp::Client.new('api-key')
+```
+
+### Breaches
+
+#### Getting all breached sites in the system
+
+```ruby
+client = Hibp::Client.new
+ 
+# Return the details of each breach in the system.
+#
+# => Array<Hibp::Breach> 
+# 
+client.breaches.fetch
+
+# Return the details of each breach associated with a specific domain.
+# 
+# => Array<Hibp::Breach> 
+client.breaches.where(domain: 'adobe.com').fetch
+```
+
+#### Getting a single breached site
+
+```ruby
+client = Hibp::Client.new
+
+# Return the details of a single breach, by breach name.
+#
+# => Hibp::Breach
+# 
+client.breach('000webhost').fetch
+```
+
+#### Getting all data classes in the system
+
+```ruby
+client = Hibp::Client.new
+
+# Return the different types of data classes that are associated with a record in a breach. E.G, Email addresses and passwords
+#
+# => Array<String>
+#
+client.data_classes.fetch
+```
+
+#### Getting all breaches for an account
+
+NOTE : 
+ - By default, only the name of the breach is returned rather than the complete breach data.
+ - By default, both verified and unverified breaches are returned when performing a search.
+
+```ruby
+# API Key is required
+client = Hibp::Client.new('api-key')
+
+# Get all breaches for an account across all domains. 
+#
+# => Array<Hibp::Breach>
+# 
+client.account_breaches('example@email.com').fetch
+
+# Get all breaches for an account across a specific domain. 
+#
+# => Array<Hibp::Breach> 
+# 
+client.account_breaches('example@email.com').where(domain: 'adobe.com').fetch
+
+# Get all breaches info for an account with detailed information. 
+#
+# => Array<Hibp::Breach> 
+# 
+client.account_breaches('example@email.com').where(truncate: false).fetch
+
+# Returns breaches that have been flagged as "unverified"
+#
+# => Array<Hibp::Breach> 
+#
+client.account_breaches('example@email.com').where(unverified: true).fetch
+```
+
+### Pastes
+
+#### Getting all pastes for an account
+
+```ruby
+# API Key is required
+client = Hibp::Client.new('api-key')
+
+# Return any pastes that contain the given email address
+#
+# => Array<Hibp::Paste>
+# 
+client.pastes('example@email.com').fetch
+```
+
+### Passwords
+
+#### Getting passwords suffixes by range
+
+```ruby
+client = Hibp::Client.new
+
+# Get all suffixes of every hash beginning with the specified prefix, and a count of how many times it appears in the data set.
+#
+# => Array<Hibp::Password>
+# 
+client.passwords('password').fetch
+
+```
+
+### Errors
+
+This gem will throw custom exception if an API error occurred.
+
+All service errors are wrapped in `Hibp::ServiceError`
+
+| Code |                   Description                                                                   |
+|------|-------------------------------------------------------------------------------------------------|
+| 400  | Bad request — The account does not comply with an acceptable format (i.e. it's an empty string) |
+| 401  | Unauthorized - Access denied due to missing hibp-api-key.                                       |
+| 403  | Forbidden — No user agent has been specified in the request                                     |
+| 404  | Not found — The account could not be found and has therefore not been pwned                     |
+| 429  | Too many requests — The rate limit has been exceeded                                            |
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/warshavski/hibp. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Hibp project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/hibp/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'hibp'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/hibp.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'hibp/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'hibp-client'
+  spec.version       = Hibp::VERSION
+  spec.authors       = ['Warshavski']
+  spec.email         = ['p.warshavski@gmail.com']
+
+  spec.summary       = 'A simple tool to check if an account(email address and username) has been compromised in a data breach'
+  spec.description   = 'A simple tool to check if an account(email address and username) has been compromised in a data breach'
+  spec.homepage      = 'https://github.com/Warshavski/hibp'
+  spec.license       = 'MIT'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/Warshavski/hibp'
+  # spec.metadata['changelog_uri'] = "TODO: Put your gem's CHANGELOG.md URL here."
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency('faraday', '>= 0.9.1')
+  spec.add_dependency('oj', '>= 3.6.13')
+
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+end

data/lib/hibp.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'faraday'
+require 'oj'
+
+require 'hibp/helpers/attribute_assignment'
+require 'hibp/helpers/json_conversion'
+
+require 'hibp/models/breach'
+require 'hibp/models/paste'
+require 'hibp/models/password'
+
+require 'hibp/parsers/json'
+require 'hibp/parsers/breach'
+require 'hibp/parsers/password'
+require 'hibp/parsers/paste'
+
+require 'hibp/client'
+require 'hibp/request'
+require 'hibp/query'
+
+require 'hibp/service_error'
+
+require 'hibp/version'
+
+module Hibp
+  class Error < StandardError; end
+  # Your code goes here...
+end

data/lib/hibp/client.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Hibp
+  # 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
+  #
+  class Client
+    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
+
+    attr_reader :authorization_header
+
+    # @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 https://haveibeenpwned.com/API/Key
+    #
+    def initialize(api_key = '')
+      @authorization_header = { 'hibp-api-key' => api_key }
+    end
+
+    # 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]
+    #
+    def breach(name)
+      configure_core_query(:breach, name)
+    end
+
+    # Fetch all breached sites in the system
+    # Available filters(domain)
+    #
+    # @note Collection is sorted alphabetically by the title of the breach.
+    #
+    # @return [Hibp::Query]
+    #
+    def breaches
+      configure_core_query(:breaches)
+    end
+
+    # 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]
+    #
+    def account_breaches(account)
+      configure_core_query(:account_breaches, CGI.escape(account))
+    end
+
+    # 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]
+    #
+    def data_classes
+      configure_core_query(:data_classes)
+    end
+
+    # 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]
+    #
+    def pastes(account)
+      configure_core_query(:pastes, CGI.escape(account))
+    end
+
+    # Search pwned passwords
+    #
+    # @param password [String] -
+    #   The value of the source password being searched for
+    #
+    # @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]
+    #
+    def passwords(password)
+      configure_password_query(password)
+    end
+
+    private
+
+    def configure_password_query(password)
+      pwd_hash = ::Digest::SHA1.hexdigest(password).upcase
+      endpoint = "#{PASSWORD_API_HOST}/#{pwd_hash[0..4]}"
+
+      Query.new(endpoint: endpoint, parser: Parsers::Password.new)
+    end
+
+    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
+
+    def resolve_endpoint(service, parameter)
+      endpoint = "#{CORE_API_HOST}/#{CORE_API_SERVICES[service]}"
+
+      parameter ? "#{endpoint}/#{parameter}" : endpoint
+    end
+
+    def resolve_parser(service)
+      breach_services = %i[breach breaches account_bereaches]
+
+      case service
+      when ->(n) { breach_services.include?(n) }
+        Parsers::Breach.new
+      when :pastes
+        Parsers::Paste.new
+      when :data_classes
+        Parsers::Json.new
+      end
+    end
+  end
+end