hackerone-client 0.1.0

data/fixtures/vcr_cassettes/report_list.yml

@@ -0,0 +1,240 @@
+---
+http_interactions:
+- request:
+    method: get
+    uri: https://api.hackerone.com/v1/reports?filter%5Bcreated_at__gt%5D=2017-02-11T16:00:44-10:00&filter%5Bprogram%5D%5B0%5D=github&filter%5Bstate%5D%5B0%5D=new
+    body:
+      encoding: US-ASCII
+      string: ''
+    headers:
+      Authorization:
+      - Basic nope=
+      User-Agent:
+      - Faraday v0.11.0
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+      Accept:
+      - "*/*"
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Date:
+      - Sat, 18 Feb 2017 19:16:35 GMT
+      Content-Type:
+      - application/json; charset=utf-8
+      Transfer-Encoding:
+      - chunked
+      Connection:
+      - keep-alive
+      Set-Cookie:
+      - __cfduid=123; expires=Sun, 18-Feb-18
+        19:16:35 GMT; path=/; Domain=api.hackerone.com; HttpOnly
+      X-Request-Id:
+      - 123
+      Etag:
+      - W/"e337505dbc57f7e1f85685911c939b6e"
+      Cache-Control:
+      - max-age=0, private, must-revalidate
+      Strict-Transport-Security:
+      - max-age=31536000; includeSubDomains; preload
+      Content-Security-Policy:
+      - default-src 'none'; connect-src 'self' www.google-analytics.com errors.hackerone.net;
+        font-src 'self'; img-src 'self' data:; script-src 'self'; style-src 'self'
+        'unsafe-inline'; form-action 'self'; frame-ancestors 'none'; report-uri https://errors.hackerone.net/api/30/csp-report/?sentry_key=61c1e2f50d21487c97a071737701f598
+      X-Content-Type-Options:
+      - nosniff
+      X-Download-Options:
+      - noopen
+      X-Frame-Options:
+      - DENY
+      X-Permitted-Cross-Domain-Policies:
+      - none
+      X-Xss-Protection:
+      - 1; mode=block
+      Public-Key-Pins-Report-Only:
+      - pin-sha256="WoiWRyIOVNa9ihaBciRSC7XHjliYS9VwUGOIud4PB18="; pin-sha256="r/mIkG3eEpVdm+u/ko/cwxzOMo1bk4TyHIlByibiA5E=";
+        pin-sha256="K87oWBWM9UZfyddvDfoxL+8lpNyoUB2ptGtn0fv6G2Q="; pin-sha256="iie1VXtL7HzAMF+/PVPR9xzT80kQxdZeJ+zduCB3uj0=";
+        pin-sha256="cGuxAXyFXFkWm61cF4HPWX8S0srS9j0aSqN0k4AP+4A="; pin-sha256="bIlWcjiKq1mftH/xd7Hw1JO77Cr+Gv+XYcGUQWwO+A4=";
+        pin-sha256="tXD+dGAP8rGY4PW1be90cOYEwg7pZ4G+yPZmIZWPTSg="; max-age=600; includeSubDomains;
+        report-uri="https://hackerone.report-uri.io/r/default/hpkp/reportOnly"
+      Server:
+      - cloudflare-nginx
+      Cf-Ray:
+      - 3333d0794c920d4f-LAX
+    body:
+      encoding: ASCII-8BIT
+      string: '{
+  "data": [
+    {
+      "id": "207385",
+      "type": "report",
+      "attributes": {
+        "title": "What is my purpose",
+        "state": "new",
+        "created_at": "2017-02-18T18:26:13.283Z",
+        "vulnerability_information": "You pass the butter",
+        "triaged_at": null,
+        "closed_at": null,
+        "last_reporter_activity_at": "2017-02-18T18:26:13.387Z",
+        "first_program_activity_at": null,
+        "last_program_activity_at": null,
+        "bounty_awarded_at": null,
+        "swag_awarded_at": null,
+        "disclosed_at": null,
+        "last_activity_at": "2017-02-18T18:26:13.387Z"
+      },
+      "relationships": {
+        "reporter": {
+          "data": {
+            "id": "123",
+            "type": "user",
+            "attributes": {
+              "username": "rickestofallthericks",
+              "name": "Rick Sanchez",
+              "disabled": false,
+              "created_at": "2017-02-18T18:21:28.638Z",
+              "profile_picture": {
+                "62x62": "/assets/avatars/default-123.png",
+                "82x82": "/assets/avatars/default-123.png",
+                "110x110": "/assets/avatars/default-123.png",
+                "260x260": "/assets/avatars/default-123.png"
+              }
+            }
+          }
+        },
+        "program": {
+          "data": {
+            "id": "1894",
+            "type": "program",
+            "attributes": {
+              "handle": "github",
+              "created_at": "2015-05-29T20:12:03.091Z",
+              "updated_at": "2017-02-17T15:18:04.114Z"
+            }
+          }
+        },
+        "severity": {
+          "data": {
+            "id": "26662",
+            "type": "severity",
+            "attributes": {
+              "rating": "critical",
+              "author_type": "User",
+              "user_id": 123,
+              "created_at": "2017-02-18T18:26:13.373Z",
+              "score": 9.1,
+              "attack_complexity": "low",
+              "attack_vector": "network",
+              "availability": "none",
+              "confidentiality": "high",
+              "integrity": "high",
+              "privileges_required": "none",
+              "user_interaction": "none",
+              "scope": "unchanged"
+            }
+          }
+        },
+        "vulnerability_types": {
+          "data": [
+            {
+              "id": "25110",
+              "type": "vulnerability-type",
+              "attributes": {
+                "name": "Information Disclosure",
+                "description": "nope",
+                "created_at": "2016-01-28T13:34:08.945Z"
+              }
+            }
+          ]
+        },
+        "bounties": {
+          "data": []
+        }
+      }
+    },
+    {
+      "id": "207228",
+      "type": "report",
+      "attributes": {
+        "title": "Take 2 Strokes off of Jerry''s swing",
+        "state": "new",
+        "created_at": "2017-02-17T21:51:00.916Z",
+        "vulnerability_information": "Hai",
+        "triaged_at": null,
+        "closed_at": null,
+        "last_reporter_activity_at": "2017-02-17T21:51:01.110Z",
+        "first_program_activity_at": null,
+        "last_program_activity_at": null,
+        "bounty_awarded_at": null,
+        "swag_awarded_at": null,
+        "disclosed_at": null,
+        "last_activity_at": "2017-02-17T21:51:01.110Z"
+      },
+      "relationships": {
+        "reporter": {
+          "data": {
+            "id": "1234",
+            "type": "user",
+            "attributes": {
+              "username": "ImMrMeeseeks",
+              "name": "Mr Meeseeks",
+              "disabled": false,
+              "created_at": "2017-02-17T20:52:56.666Z",
+              "profile_picture": {
+                "62x62": "/assets/avatars/default-123.png",
+                "82x82": "/assets/avatars/default-123.png",
+                "110x110": "/assets/avatars/default-123.png",
+                "260x260": "/assets/avatars/default-123.png"
+              }
+            }
+          }
+        },
+        "program": {
+          "data": {
+            "id": "1894",
+            "type": "program",
+            "attributes": {
+              "handle": "github",
+              "created_at": "2015-05-29T20:12:03.091Z",
+              "updated_at": "2017-02-17T15:18:04.114Z"
+            }
+          }
+        },
+        "severity": {
+          "data": {
+            "id": "26541",
+            "type": "severity",
+            "attributes": {
+              "rating": "low",
+              "author_type": "User",
+              "user_id": 144214,
+              "created_at": "2017-02-17T21:51:01.093Z"
+            }
+          }
+        },
+        "vulnerability_types": {
+          "data": [
+            {
+              "id": "25110",
+              "type": "vulnerability-type",
+              "attributes": {
+                "name": "Information Disclosure",
+                "description": "Exposure of system information, sensitive or private information, fingerprinting, etc.\n",
+                "created_at": "2016-01-28T13:34:08.945Z"
+              }
+            }
+          ]
+        },
+        "bounties": {
+          "data": []
+        }
+      }
+    }
+  ],
+  "links": {}
+}'
+    http_version:
+  recorded_at: Sat, 18 Feb 2017 19:16:35 GMT
+recorded_with: VCR 3.0.3

data/hackerone-client.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'hackerone/client/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "hackerone-client"
+  spec.version       = Hackerone::Client::VERSION
+  spec.authors       = ["Neil Matatall"]
+  spec.email         = ["neil.matatall@gmail.com"]
+
+  spec.summary       = %q{A limited client for the HackerOne API}
+  spec.homepage      = "https://github.com/oreoshake/hackerone-client"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |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_development_dependency "bundler", "~> 1.14"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "vcr", "~> 3.0"
+  spec.add_development_dependency "webmock", "~> 2.3"
+  spec.add_runtime_dependency "faraday"
+  spec.add_runtime_dependency 'activesupport', '~> 3.0', '> 3.0'
+end

data/lib/hackerone/client.rb

@@ -0,0 +1,113 @@
+require "faraday"
+require 'active_support/time'
+require_relative "client/version"
+require_relative "client/report"
+
+module HackerOne
+  module Client
+    class NotConfiguredError < StandardError; end
+
+    DEFAULT_LOW_RANGE = 1...999
+    DEFAULT_MEDIUM_RANGE = 1000...2499
+    DEFAULT_HIGH_RANGE = 2500...4999
+    DEFAULT_CRITICAL_RANGE = 5000...100_000_000
+
+    class << self
+      ATTRS = [:low_range, :medium_range, :high_range, :critical_range].freeze
+      attr_accessor :program
+      attr_reader *ATTRS
+
+      ATTRS.each do |attr|
+        define_method "#{attr}=" do |value|
+          raise ArgumentError, "value must be a range object" unless value.is_a?(Range)
+          instance_variable_set :"@#{attr}", value
+        end
+      end
+    end
+
+    class Api
+      def initialize(program = nil)
+        @program = program
+      end
+
+      def program
+        @program || HackerOne::Client.program
+      end
+
+      ## Returns all open reports, optionally with a time bound
+      #
+      # program: the HackerOne program to search on (configure globally with Hackerone::Client.program=)
+      # since (optional): a time bound, don't include reports earlier than +since+. Must be a DateTime object.
+      #
+      # returns all open reports or an empty array
+      def reports(since: 3.days.ago)
+        raise ArgumentError, "Program cannot be nil" unless program
+        response = self.class.hackerone_api_connection.get do |req|
+          options = {
+            "filter[state][]" => "new",
+            "filter[program][]" => program,
+            "filter[created_at__gt]" => since.iso8601
+          }
+          req.url "reports", options
+        end
+
+        data = JSON.parse(response.body, :symbolize_names => true)[:data]
+        if data.nil?
+          raise RuntimeError, "Expected data attribute in response: #{response.body}"
+        end
+
+        data.map do |report|
+          Report.new(report)
+        end
+      end
+
+      ## Public: retrieve a report
+      #
+      # id: the ID of a specific report
+      #
+      # returns an HackerOne::Client::Report object or raises an error if
+      # no report is found.
+      def report(id)
+        response = with_retry do
+          self.class.hackerone_api_connection.get do |req|
+            req.url "reports/#{id}"
+          end
+        end
+
+        if response.success?
+          Report.new(JSON.parse(response.body, :symbolize_names => true)[:data])
+        else
+          raise ArgumentError, "Could not retrieve HackerOne report ##{id}: #{response.body}"
+        end
+      end
+
+      private
+      def self.hackerone_api_connection
+        unless ENV["HACKERONE_TOKEN_NAME"] && ENV["HACKERONE_TOKEN"]
+          raise NotConfiguredError, "HACKERONE_TOKEN_NAME HACKERONE_TOKEN environment variables must be set"
+        end
+
+        @connection ||= Faraday.new(:url => "https://api.hackerone.com/v1") do |faraday|
+          faraday.basic_auth(ENV["HACKERONE_TOKEN_NAME"], ENV["HACKERONE_TOKEN"])
+          faraday.adapter Faraday.default_adapter
+        end
+      end
+
+      def with_retry(attempts=3, &block)
+        attempts_remaining = attempts
+
+        begin
+          yield
+        rescue StandardError
+          if attempts_remaining > 0
+            attempts_remaining -= 1
+            sleep (attempts - attempts_remaining)
+            retry
+          else
+            raise
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hackerone/client/report.rb

@@ -0,0 +1,115 @@
+module HackerOne
+  module Client
+    class Report
+      PAYOUT_ACTIVITY_KEY = "activity-bounty-awarded"
+      CLASSIFICATION_MAPPING = {
+        "None Applicable" => "A0-Other",
+        "Denial of Service" => "A0-Other",
+        "Memory Corruption" => "A0-Other",
+        "Cryptographic Issue" => "A0-Other",
+        "Privilege Escalation" => "A0-Other",
+        "UI Redressing (Clickjacking)" => "A0-Other",
+        "Command Injection" => "A1-Injection",
+        "Remote Code Execution" => "A1-Injection",
+        "SQL Injection" => "A1-Injection",
+        "Authentication" => "A2-AuthSession",
+        "Cross-Site Scripting (XSS)" => "A3-XSS",
+        "Information Disclosure" => "A6-DataExposure",
+        "Cross-Site Request Forgery (CSRF)" => "A8-CSRF",
+        "Unvalidated / Open Redirect" => "A10-Redirects"
+      }
+
+      def initialize(report)
+        @report = report
+      end
+
+      def id
+        @report[:id]
+      end
+
+      def title
+        attributes[:title]
+      end
+
+      def vulnerability_information
+        attributes[:vulnerability_information]
+      end
+
+      def reporter
+        relationships
+          .fetch(:reporter, {})
+          .fetch(:data, {})
+          .fetch(:attributes, {})
+      end
+
+      def payment_total
+        payments.reduce(0) { |total, payment| total + payment_amount(payment) }
+      end
+
+      # Excludes reports where the payout amount is 0 indicating swag-only or no
+      # payout for the issue supplied
+      def risk
+        case payment_total
+        when HackerOne::Client.low_range || DEFAULT_LOW_RANGE
+          "low"
+        when HackerOne::Client.medium_range || DEFAULT_MEDIUM_RANGE
+          "medium"
+        when HackerOne::Client.high_range || DEFAULT_HIGH_RANGE
+          "high"
+        when HackerOne::Client.critical_range || DEFAULT_CRITICAL_RANGE
+          "critical"
+        end
+      end
+
+      def summary
+        summaries = relationships.fetch(:summaries, {}).fetch(:data, []).select {|summary| summary[:type] == "report-summary" }
+        return unless summaries
+
+        summaries.select { |summary| summary[:attributes][:category] == "team" }.map do |summary|
+          summary[:attributes][:content]
+        end.join("\n")
+      end
+
+      # Do our best to map the value that hackerone provides and the reporter sets
+      # to the OWASP Top 10. Take the first match since multiple values can be set.
+      # This is used for the issue label.
+      def classification_label
+        owasp_mapping = vulnerability_types.map do |vuln_type|
+          CLASSIFICATION_MAPPING[vuln_type[:attributes][:name]]
+        end.flatten.first
+
+        owasp_mapping || CLASSIFICATION_MAPPING["None Applicable"]
+      end
+
+      # Bounty writeups just use the key, and not the label value.
+      def writeup_classification
+        classification_label().split("-").first
+      end
+
+      private
+      def payments
+        activities.select { |activity| activity[:type] == PAYOUT_ACTIVITY_KEY }
+      end
+
+      def payment_amount(payment)
+        payment.fetch(:attributes, {}).fetch(:bounty_amount, 0).gsub(/[^\d]/, "").to_i
+      end
+
+      def activities
+        relationships.fetch(:activities, {}).fetch(:data, [])
+      end
+
+      def attributes
+        @report[:attributes]
+      end
+
+      def relationships
+        @report[:relationships]
+      end
+
+      def vulnerability_types
+        relationships.fetch(:vulnerability_types, {}).fetch(:data, [])
+      end
+    end
+  end
+end