esp_sdk 1.1.0 → 2.0.0.rc1

data/Rakefile

@@ -1,9 +1,22 @@
 require 'bundler/gem_tasks'
 require 'rake/testtask'
+load 'lib/tasks/rubocop.rake'
+load 'lib/tasks/testing.rake'
+require 'rdoc/task'
 
 Rake::TestTask.new do |task|
   task.libs << 'test'
   task.test_files = FileList['test/*_test.rb', 'test/**/*_test.rb']
 end
 
-task default: [:test]
+task default: [:test]
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'ESPSDK'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/esp/resources/**/*.rb')
+  rdoc.rdoc_files.include('lib/esp/extensions/active_resource/paginated_collection.rb')
+  rdoc.rdoc_files.include('lib/esp.rb')
+end

data/bin/esp_console

@@ -0,0 +1,71 @@
+#!/usr/bin/env ruby
+# https://www.fedux.org/articles/2015/08/26/creating-an-irb-based-repl-console-for-your-project.html
+
+ENV['ESP_ENV'] = ARGV[0]
+require 'irb'
+require_relative '../lib/esp_sdk'
+
+module ESP
+  class Console
+    def start
+      ARGV.clear
+      IRB.setup nil
+
+      IRB.conf[:PROMPT] = {}
+      IRB.conf[:IRB_NAME] = 'espsdk'
+      IRB.conf[:PROMPT][:ESPSDK] = {
+        :PROMPT_I => '%N:%03n:%i> ',
+        :PROMPT_N => '%N:%03n:%i> ',
+        :PROMPT_S => '%N:%03n:%i%l ',
+        :PROMPT_C => '%N:%03n:%i* ',
+        :RETURN => "# => %s\n"
+      }
+      IRB.conf[:PROMPT_MODE] = :ESPSDK
+
+      IRB.conf[:RC] = false
+
+      require 'irb/completion'
+      require 'irb/ext/save-history'
+      IRB.conf[:READLINE] = true
+      IRB.conf[:SAVE_HISTORY] = 1000
+      IRB.conf[:HISTORY_FILE] = '~/.esp_sdk_history'
+
+      context = Class.new do
+        include ESP
+      end
+
+      irb = IRB::Irb.new(IRB::WorkSpace.new(context.new))
+      IRB.conf[:MAIN_CONTEXT] = irb.context
+
+      trap("SIGINT") do
+        irb.signal_handle
+      end
+
+      begin
+        catch(:IRB_EXIT) do
+          irb.eval_input
+        end
+      ensure
+        IRB.irb_at_exit
+      end
+    end
+  end
+end
+
+begin
+  require 'catpix'
+  logo = File.expand_path(File.dirname(__FILE__) + '/../assets/logo.png')
+  Catpix::print_image logo
+rescue
+  require 'artii'
+  artii = Artii::Base.new(font: 'slant')
+  print artii.asciify('E.S.P')
+end
+print <<-banner
+
+Evident Security Platform Console #{ESP::VERSION}
+Copyright (c) 2013-#{Time.now.year} Evident Security, All Rights Reserved.
+http://www.evident.io
+banner
+ESP::Console.new.start
+

data/esp_sdk.gemspec

@@ -1,15 +1,15 @@
 # coding: utf-8
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'esp_sdk/version'
+require 'esp/version'
 
 Gem::Specification.new do |spec|
   spec.name          = 'esp_sdk'
-  spec.version       = EspSdk::VERSION
+  spec.version       = ESP::VERSION
   spec.authors       = ['Evident.io']
   spec.email         = ['support@evident.io']
-  spec.summary       = %q{SDK for interacting with the ESP API.}
-  spec.homepage      = ''
+  spec.summary       = "SDK for interacting with the ESP API."
+  spec.homepage      = 'https://github.com/EvidentSecurity/esp_sdk'
   spec.license       = 'MIT'
 
   spec.files         = `git ls-files -z`.split("\x0")
@@ -17,19 +17,28 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'bundler', '~> 1.6'
-  spec.add_development_dependency 'rake', '~> 10.3.2'
-  spec.add_development_dependency 'rubocop', '~> 0.27.1'
-  spec.add_development_dependency 'minitest', '~> 5.4.2'
-  spec.add_development_dependency 'minitest-reporters', '~> 1.0.7'
-  spec.add_development_dependency 'shoulda', '~> 3.5.0'
-  spec.add_development_dependency 'codeclimate-test-reporter', '~> 0.4.1'
-  spec.add_development_dependency 'mocha', '~> 1.1.0'
-  spec.add_development_dependency 'fakeweb', '~> 1.3'
+  spec.required_ruby_version = '>= 2.0.0'
 
-  spec.add_runtime_dependency 'activesupport', '>= 3.0.0'
-  spec.add_runtime_dependency 'rest_client', '~> 1.7.3'
-  spec.add_runtime_dependency 'pry', '~> 0.10.1'
-  spec.add_runtime_dependency 'awesome_print', '~> 1.2.0'
-  spec.add_runtime_dependency 'artii', '~> 2.1.1'
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'guard'
+  spec.add_development_dependency 'guard-minitest'
+  spec.add_development_dependency 'guard-rubocop'
+  spec.add_development_dependency 'minitest'
+  spec.add_development_dependency 'minitest-reporters'
+  spec.add_development_dependency 'shoulda'
+  spec.add_development_dependency 'mocha'
+  spec.add_development_dependency 'bourne'
+  spec.add_development_dependency 'webmock'
+  spec.add_development_dependency 'coveralls'
+  spec.add_development_dependency 'factory_girl'
+  spec.add_development_dependency 'rdoc'
+
+  spec.add_dependency 'activeresource', '~> 4.0.0'
+  spec.add_dependency 'api-auth'
+  spec.add_dependency 'rack'
+  spec.add_dependency 'awesome_print'
+  spec.add_dependency 'artii'
+  spec.add_dependency 'catpix'
 end

data/lib/esp/exceptions.rb

@@ -0,0 +1,3 @@
+module ESP
+  class NotImplementedError < StandardError; end
+end

data/lib/esp/extensions/active_resource/formats/json_api_format.rb

@@ -0,0 +1,105 @@
+require 'active_support/json'
+
+module ActiveResource
+  class ConnectionError
+    def initialize(response)
+      @response = if response.respond_to?(:response)
+                    message = decoded_errors(response.response.body)
+                    Struct.new(:body, :code, :message).new(response.response.body, response.code, message)
+                  else
+                    response
+                  end
+    end
+
+    private
+
+    def decoded_errors(json)
+      Array((Hash(ActiveSupport::JSON.decode(json)))['errors'].map { |e| e['title'] }).join(" ")
+    rescue
+      []
+    end
+  end
+
+  module Formats
+    module JsonAPIFormat
+      module_function
+
+      def extension
+        "json".freeze
+      end
+
+      def mime_type
+        "application/vnd.api+json".freeze
+      end
+
+      def encode(hash, options = nil)
+        ActiveSupport::JSON.encode(hash, options)
+      end
+
+      def decode(json)
+        # ap ActiveSupport::JSON.decode(json), index: false, indent: -2
+        Formats.remove_root(parse_json_api(ActiveSupport::JSON.decode(json)))
+      end
+
+      private
+
+      def self.parse_json_api(elements)
+        included = elements.delete('included')
+        elements.tap do |e|
+          Array.wrap(e.fetch('data', {})).each do |object|
+            parse_object!(object, included)
+          end
+        end
+      end
+
+      def self.parse_object!(object, included = nil)
+        return object unless object.respond_to?(:each)
+        merge_attributes!(object)
+        parse_elements(object)
+        parse_relationships!(object, included)
+        object
+      end
+
+      def self.parse_elements(object)
+        object.each_value do |value|
+          if value.is_a? Hash
+            parse_object!(value)
+          elsif value.is_a? Array
+            value.map! { |o| parse_object!(o) }
+          end
+        end
+      end
+
+      def self.parse_relationships!(object, included)
+        object.fetch('relationships', {}).each do |assoc, details|
+          extract_foreign_keys!(object, assoc, details['data'])
+          merge_included_objects!(object, assoc, details['data'], included)
+        end
+      end
+
+      def self.merge_attributes!(object)
+        return unless object.is_a? Hash
+        object.merge! object.delete('attributes') unless object['attributes'].blank?
+      end
+
+      def self.extract_foreign_keys!(object, assoc, data)
+        return if data.blank?
+        if data.is_a? Array
+          object["#{assoc.singularize}_ids"] = data.map { |d| d['id'] }
+        else
+          object["#{assoc}_id"] = data['id']
+        end
+      end
+
+      def self.merge_included_objects!(object, assoc, data, included)
+        return if included.blank?
+        object[assoc] = case data
+                        when Array
+                          included.select { |i| data.include?(parse_object!(i).slice('type', 'id')) }
+                        when Hash
+                          included.detect { |i| data == parse_object!(i).slice('type', 'id') }
+                        end
+      end
+    end
+  end
+end

data/lib/esp/extensions/active_resource/paginated_collection.rb

@@ -0,0 +1,198 @@
+require 'rack'
+
+module ActiveResource
+  # Provides a mean to call the Evident.io API to easily retrieve paginated data
+  class PaginatedCollection < ActiveResource::Collection
+    attr_reader :next_page_params, :previous_page_params, :last_page_params #:nodoc:
+    attr_accessor :from #:nodoc:
+
+    def initialize(elements = []) #:nodoc:
+      # If a collection is sent without the pagination links, then elements will just be an array.
+      if elements.is_a? Hash
+        super(elements['data'])
+        parse_pagination_links(elements['links'])
+      else
+        super(elements)
+      end
+    end
+
+    # Returns a new PaginatedCollection with the first page of results.
+    #
+    # Returns self when on the first page and no API call is made.
+    #
+    # ==== Example
+    #   alerts.current_page_number # => 5
+    #   first_page = alerts.first_page
+    #   alerts.current_page_number # => 5
+    #   first_page.current_page_number # => 1
+    def first_page
+      previous_page? ? resource_class.all(from: from, params: { page: { number: 1 } }) : self
+    end
+
+    # Updates the existing PaginatedCollection object with the first page of data when not on the first page.
+    #
+    # ==== Example
+    #   alerts.current_page_number # => 5
+    #   alerts.first_page!
+    #   alerts.current_page_number # => 1
+    def first_page!
+      first_page.tap { |page| update_self(page) }
+    end
+
+    # Returns a new PaginatedCollection with the previous page of results.
+    #
+    # Returns self when on the first page and no API call is made.
+    #
+    # ==== Example
+    #   alerts.current_page_number # => 5
+    #   previous_page = alerts.previous_page
+    #   alerts.current_page_number # => 5
+    #   previous_page.current_page_number # => 4
+    def previous_page
+      previous_page? ? resource_class.all(from: from, params: previous_page_params) : self
+    end
+
+    # Updates the existing PaginatedCollection object with the previous page of data when not on the first page.
+    #
+    # ==== Example
+    #   alerts.current_page_number # => 5
+    #   alerts.previous_page!
+    #   alerts.current_page_number # => 4
+    def previous_page!
+      previous_page.tap { |page| update_self(page) }
+    end
+
+    # Returns a new PaginatedCollection with the next page of results.
+    #
+    # Returns self when on the last page and no API call is made.
+    #
+    # ==== Example
+    #   alerts.current_page_number # => 5
+    #   next_page = alerts.next_page
+    #   alerts.current_page_number # => 5
+    #   next_page.current_page_number # => 6
+    def next_page
+      next_page? ? resource_class.all(from: from, params: next_page_params) : self
+    end
+
+    # Updates the existing PaginatedCollection object with the last page of data when not on the last page.
+    #
+    # ==== Example
+    #   alerts.current_page_number # => 5
+    #   alerts.next_page!
+    #   alerts.current_page_number # => 6
+    def next_page!
+      next_page.tap { |page| update_self(page) }
+    end
+
+    # Returns a new PaginatedCollection with the last page of results.
+    #
+    # Returns self when on the last page and no API call is made.
+    #
+    # ==== Example
+    #   alerts.current_page_number # => 5
+    #   last_page = alerts.last_page
+    #   alerts.current_page_number # => 5
+    #   last_page.current_page_number # => 25
+    def last_page
+      !last_page? ? resource_class.all(from: from, params: last_page_params) : self
+    end
+
+    # Updates the existing PaginatedCollection object with the last page of data when not on the last page.
+    #
+    # ==== Example
+    #   alerts.current_page_number # => 5
+    #   alerts.last_page!
+    #   alerts.current_page_number # => 25
+    def last_page!
+      last_page.tap { |page| update_self(page) }
+    end
+
+    # Returns a new PaginatedCollection with the +page_number+ page of data.
+    #
+    # Returns self when +page_number+ == #current_page_number
+    #
+    # ==== Attribute
+    #
+    # +page_number+ - The page number of the data wanted.  +page_number+ must be between 1 and #last_page_number.
+    #
+    # ==== Example
+    #   alerts.current_page_number # => 5
+    #   page = alerts.page(2)
+    #   alerts.current_page_number # => 5
+    #   page.current_page_number # => 2
+    def page(page_number = nil)
+      fail ArgumentError, "You must supply a page number." unless page_number.present?
+      fail ArgumentError, "Page number cannot be less than 1." if page_number.to_i < 1
+      fail ArgumentError, "Page number cannot be greater than the last page number." if page_number.to_i > last_page_number.to_i
+      page_number.to_i != current_page_number.to_i ? resource_class.all(from: from, params: { page: { number: page_number, size: (next_page_params || previous_page_params)['page']['size'] } }) : self
+    end
+
+    # Returns a new PaginatedCollection with the +page_number+ page of data when not already on page +page_number+.
+    #
+    # ==== Attribute
+    #
+    # +page_number+ - The page number of the data wanted.  +page_number+ must be between 1 and #last_page_number.
+    #
+    # ==== Example
+    #   alerts.current_page_number # => 5
+    #   alerts.page!(2)
+    #   alerts.current_page_number # => 2
+    def page!(page_number)
+      page(page_number).tap { |page| update_self(page) }
+    end
+
+    # The current page number of data.
+    def current_page_number
+      (previous_page_number.to_i + 1).to_s
+    end
+
+    # The previous page number of data.
+    def previous_page_number
+      Hash(previous_page_params).fetch('page', {}).fetch('number', nil)
+    end
+
+    # The next page number of data.
+    def next_page_number
+      Hash(next_page_params).fetch('page', {}).fetch('number', nil)
+    end
+
+    # The last page number of data.
+    def last_page_number
+      Hash(last_page_params).fetch('page', {}).fetch('number', nil)
+    end
+
+    # Returns whether or not there is a previous page of data in the collection.
+    def previous_page?
+      !previous_page_number.nil?
+    end
+
+    # Returns whether or not there is a next page of data in the collection.
+    def next_page?
+      !next_page_number.nil?
+    end
+
+    # Returns whether or not the collection is on the last page.
+    def last_page?
+      last_page_number.nil?
+    end
+
+    private
+
+    def update_self(page)
+      @elements = page.elements
+      @next_page_params = page.next_page_params
+      @previous_page_params = page.previous_page_params
+      @last_page_params = page.last_page_params
+    end
+
+    def parse_pagination_links(links)
+      @next_page_params = links['next'] ? Rack::Utils.parse_nested_query(CGI.unescape(URI.parse(links['next']).query)) : {}
+      @previous_page_params = links['prev'] ? Rack::Utils.parse_nested_query(CGI.unescape(URI.parse(links['prev']).query)) : {}
+      @last_page_params = links['last'] ? Rack::Utils.parse_nested_query(CGI.unescape(URI.parse(links['last']).query)) : {}
+      # The last page may not contain the full per page number of records, and will therefore come back with an incorrect size since the
+      # size is based on the collection size.  This will mess up further calls to previous_page or first page so remove the size so it will bring back the default size.
+      previous_page_params['page'].delete('size') if last_page? && previous_page_params['page']
+    end
+  end
+end

data/lib/esp/extensions/active_resource/validations.rb

@@ -0,0 +1,45 @@
+module ActiveResource
+  module Validations
+    # Loads the set of remote errors into the object's Errors based on the
+    # content-type of the error-block received.
+    def load_remote_errors(remote_errors, save_cache = false) #:nodoc:
+      if self.class.format == ActiveResource::Formats::JsonAPIFormat
+        errors.from_json_api(remote_errors.response.body, save_cache)
+      elsif self.class.format == ActiveResource::Formats[:json]
+        super
+      end
+    end
+  end
+
+  class Errors
+    def from_json_api(json, save_cache = false)
+      raw_errors = decoded_errors(json)
+      errors = meta_errors(raw_errors)
+      if errors.present?
+        from_hash errors, save_cache
+      else
+        from_array raw_errors.map { |e| e['title'] }
+      end
+    end
+
+    private
+
+    def decoded_errors(json)
+      Array((Hash(ActiveSupport::JSON.decode(json)))['errors'])
+    rescue
+      []
+    end
+
+    def meta_errors(raw_errors)
+      {}.tap do |errors|
+        raw_errors.each do |error|
+          next unless error['meta']
+          error['meta'].map do |attr, message|
+            errors[attr] ||= []
+            errors[attr] << message
+          end
+        end
+      end
+    end
+  end
+end

data/lib/esp/resources/alert.rb

@@ -0,0 +1,135 @@
+module ESP
+  class Alert < ESP::Resource
+    ##
+    # Returns the external account associated with this alert.
+    belongs_to :external_account, class_name: 'ESP::ExternalAccount'
+
+    ##
+    # Returns the region associated with this alert.
+    belongs_to :region, class_name: 'ESP::Region'
+
+    ##
+    # Returns the region associated with this alert.  Either a signature or custom signature but not both will be present.
+    belongs_to :signature, class_name: 'ESP::Signature'
+
+    ##
+    # Returns the custom signature associated with this alert.  Either a signature or custom signature but not both will be present.
+    belongs_to :custom_signature, class_name: 'ESP::CustomSignature'
+
+    ##
+    # Returns the suppression associated with this alert.  If present the alert was suppressed.
+    belongs_to :suppression, class_name: 'ESP::Suppression'
+
+    ##
+    # Returns the cloud trail events associated with this alert.  These may be added up to 10 minutes after the alert was created
+    has_many :cloud_trail_events, class_name: 'ESP::CloudTrailEvent'
+
+    ##
+    # Returns the tags associated with this alert.
+    has_many :tags, class_name: 'ESP::Tag'
+
+    # Not Implemented. You cannot create or update an Alert.
+    def save
+      fail ESP::NotImplementedError
+    end
+
+    # Not Implemented. You cannot destroy a an Alert.
+    def destroy
+      fail ESP::NotImplementedError
+    end
+
+    # Returns a paginated collection of alerts for the given report_id
+    # Convenience method to use instead of ::find since a report_id is required to return alerts.
+    #
+    # ==== Parameters
+    #
+    # +report_id+ | Required | The ID of the report to retrieve alerts for
+    #
+    # +arguments+ | Not Required | An optional hash of search criteria to filter the returned collection
+    #
+    # ===== Valid Arguments
+    #
+    # +region_id+ | Not Required | Return only alerts for this region.
+    #
+    # +status+ | Not Required | Return only alerts for the give status(es).  Valid values are fail, warn, error, pass, info
+    #
+    # +first_seen+ | Not Required | Return only alerts that have started within a number of hours of the report. For example, first_seen of 3 will return alerts that started showing up within the last 3 hours of the report.
+    #
+    # +suppressed+ | Not Required | Return only suppressed alerts
+    #
+    # +team_id+ | Not Required | Return only alerts for the given team.
+    #
+    # +external_account_id+ | Not Required | Return only alerts for the given external id.
+    #
+    # +service_id+ | Not Required | Return only alerts on signatures with the given service.
+    #
+    # +signature_severity+ | Not Required | Return only alerts for signatures with the given risk_level.  Valid values are Low, Medium, High
+    #
+    # +signature_name+ | Not Required | Return only alerts for signatures with the given name.
+    #
+    # +resource+ | Not Required | Return only alerts for the given resource or tag.
+    #
+    # +signature_identifier+ | Not Required | Return only alerts for signatures with the given identifier.
+    #
+    # ==== Example
+    #   alerts = ESP::Alert.for_report(54, status: 'fail', signature_severity: 'High')
+    def self.for_report(report_id = nil, arguments = {})
+      fail ArgumentError, "You must supply a report id." unless report_id.present?
+      from = "#{prefix}reports/#{report_id}/alerts.json"
+      all(from: from, params: arguments)
+    end
+
+    # Find an Alert by id
+    #
+    # ==== Parameter
+    #
+    # +id+ | Required | The ID of the alert to retrieve
+    #
+    # :call-seq:
+    #  find(id)
+    def self.find(*arguments)
+      scope = arguments.slice!(0)
+      options = (arguments.slice!(0) || {}).with_indifferent_access
+      return super(scope, options) if scope.is_a?(Numeric) || options[:from].present?
+      params = options.fetch(:params, {}).with_indifferent_access
+      report_id = params.delete(:report_id)
+      for_report(report_id, params)
+    end
+
+    # Suppress the signature associated with this alert.
+    # ==== Parameter
+    #
+    # +reason+ | Required | The reason for creating the suppression.
+    def suppress_signature(reason = nil)
+      suppress(Suppression::Signature, reason)
+    end
+
+    # Suppress the region associated with this alert.
+    # ==== Parameter
+    #
+    # +reason+ | Required | The reason for creating the suppression.
+    def suppress_region(reason = nil)
+      suppress(Suppression::Region, reason)
+    end
+
+    # Suppress the unique identifier associated with this alert.
+    # ==== Parameter
+    #
+    # +reason+ | Required | The reason for creating the suppression.
+    def suppress_unique_identifier(reason = nil)
+      suppress(Suppression::UniqueIdentifier, reason)
+    end
+
+    private
+
+    # Overridden because alerts does not use ransack for searching
+    def self.filters(params)
+      { filter: params }
+    end
+
+    def suppress(klass, reason)
+      fail ArgumentError, "You must specify the reason.".freeze unless reason.present?
+      klass.create(alert_id: id, reason: reason)
+    end
+  end
+end

data/lib/esp/resources/cloud_trail_event.rb

@@ -0,0 +1,45 @@
+module ESP
+  class CloudTrailEvent < ESP::Resource
+    # Not Implemented. You cannot create or update a CloudTrailEvent.
+    def save
+      fail ESP::NotImplementedError
+    end
+
+    # Not Implemented. You cannot destroy a CloudTrailEvent.
+    def destroy
+      fail ESP::NotImplementedError
+    end
+
+    # Returns a paginated collection of cloud trail events for the given alert_id
+    # Convenience method to use instead of ::find since an alert_id is required to return cloud trail events.
+    #
+    # ==== Parameter
+    #
+    # +alert_id+ | Required | The ID of the alert to retrieve cloud trail events for
+    #
+    # ==== Example
+    #   alerts = ESP::CloudTrailEvent.for_alert(1194)
+    def self.for_alert(alert_id = nil)
+      fail ArgumentError, "You must supply an alert id." unless alert_id.present?
+      from = "#{prefix}alerts/#{alert_id}/cloud_trail_events.json"
+      find(:all, from: from)
+    end
+
+    # Find a CloudTrailEvent by id
+    #
+    # ==== Parameter
+    #
+    # +id+ | Required | The ID of the cloud trail event to retrieve
+    #
+    # :call-seq:
+    #  find(id)
+    def self.find(*arguments)
+      scope = arguments.slice!(0)
+      options = (arguments.slice!(0) || {}).with_indifferent_access
+      return super(scope, options) if scope.is_a?(Numeric) || options[:from].present?
+      params = options.fetch(:params, {}).with_indifferent_access
+      alert_id = params.delete(:alert_id)
+      for_alert(alert_id)
+    end
+  end
+end