esp_sdk 2.0.0 → 2.1.0

data/lib/esp/resources/region.rb

@@ -18,9 +18,7 @@ module ESP
     #
     # ===== Valid Arguments
     #
-    # +external_account_ids+ | Required | An Array of the external accounts identified by +external_account_id+ to suppress the signature or custom signature on.
-    #
-    # +reason+ | Required | The reason for creating the suppression.
+    # See {API documentation}[http://api-docs.evident.io?ruby#suppression-create] for valid arguments
     #
     # ==== Example
     #   suppress(external_account_ids: [5], reason: 'My very good reason for creating this suppression')
@@ -29,6 +27,20 @@ module ESP
       ESP::Suppression::Region.create(regions: [code], external_account_ids: Array(arguments[:external_account_ids]), reason: arguments[:reason])
     end
 
+    # :singleton-method: where
+    # Return a paginated Region list filtered by search parameters
+    #
+    # ==== Parameters
+    #
+    # +clauses+ | Hash of attributes with appended predicates to search and sort by.
+    #
+    # ===== Valid Clauses
+    #
+    # See {API documentation}[http://api-docs.evident.io?ruby#region-attributes] for valid arguments
+    #
+    # :call-seq:
+    #  where(clauses = {})
+
     ##
     # :singleton-method: find
     # Find a Region by id

data/lib/esp/resources/report.rb

@@ -26,7 +26,7 @@ module ESP
     # Returns a Report object with a status of 'queued' and an id
     # ==== Attribute
     #
-    # +team_id+ | Required | The ID of the team to create a report for
+    # See {API documentation}[http://api-docs.evident.io?ruby#report-create] for valid arguments
     #
     # Periodically check the API
     #   ESP::Report.find(<id>)
@@ -48,34 +48,14 @@ module ESP
     #
     # ===== 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.
+    # See {API documentation}[http://api-docs.evident.io?ruby#alert-attributes] for valid arguments
     #
     # ==== Example
     #
     #   report = ESP::Report.find(345)
     #   alerts = report.alerts(status: 'fail', signature_severity: 'High')
     def alerts(arguments = {})
-      ESP::Alert.for_report(id, arguments)
+      ESP::Alert.where(arguments.merge(report_id: id))
     end
 
     # Returns the stats for this report
@@ -83,6 +63,20 @@ module ESP
       ESP::Stat.for_report(id)
     end
 
+    # :singleton-method: where
+    # Return a paginated Report list filtered by search parameters
+    #
+    # ==== Parameters
+    #
+    # +clauses+ | Hash of attributes with appended predicates to search, sort and include.
+    #
+    # ===== Valid Clauses
+    #
+    # See {API documentation}[http://api-docs.evident.io?ruby#report-attributes] for valid arguments
+    #
+    # :call-seq:
+    #  where(clauses = {})
+
     ##
     # :singleton-method: find
     # Find a Report by id
@@ -91,8 +85,18 @@ module ESP
     #
     # +id+ | Required | The ID of the report to retrieve
     #
+    # +options+ | Optional | A hash of options
+    #
+    # ===== Valid Options
+    #
+    # +include+ | The list of associated objects to return on the initial request.
+    #
+    # ===== Valid Includable Associations
+    #
+    # See {API documentation}[http://api-docs.evident.io?ruby#report-attributes] for valid arguments
+    #
     # :call-seq:
-    #  find(id)
+    #  find(id, options = {})
 
     # :singleton-method: all
     # Return a paginated Report list

data/lib/esp/resources/resource.rb

@@ -1,6 +1,7 @@
 module ESP
   class Resource < ActiveResource::Base # :nodoc:
     self.site = ESP.site
+    self.proxy = ESP.http_proxy
     self.format = ActiveResource::Formats::JsonAPIFormat
     with_api_auth(ESP.access_key_id, ESP.secret_access_key)
     headers["Content-Type"] = format.mime_type
@@ -8,9 +9,8 @@ module ESP
 
     self.collection_parser = ActiveResource::PaginatedCollection
 
-    def self.where(*)
-      fail ESP::NotImplementedError
-    end
+    # List of predicates that can be used for searching
+    PREDICATES = %w(sorts m eq eq_any eq_all not_eq not_eq_any not_eq_all matches matches_any matches_all does_not_match does_not_match_any does_not_match_all lt lt_any lt_all lteq lteq_any lteq_all gt gt_any gt_all gteq gteq_any gteq_all in in_any in_all not_in not_in_any not_in_all cont cont_any cont_all not_cont not_cont_any not_cont_all start start_any start_all not_start not_start_any not_start_all end end_any end_all not_end not_end_any not_end_all true false present blank null not_null).join('|').freeze
 
     # Pass a json api compliant hash to the api.
     def serializable_hash(*)
@@ -21,6 +21,17 @@ module ESP
       h
     end
 
+    def self.where(clauses = {})
+      fail ArgumentError, "expected a clauses Hash, got #{clauses.inspect}" unless clauses.is_a? Hash
+      from = clauses.delete(:from) || "#{prefix}#{name.demodulize.pluralize.underscore}"
+      clauses = { params: clauses }
+      arrange_options(clauses)
+      prefix_options, query_options = split_options(clauses)
+      instantiate_collection((format.decode(connection.put("#{from}.json", clauses[:params].to_json).body) || []), query_options, prefix_options).tap do |collection|
+        make_pageable collection, clauses.merge(from: from)
+      end
+    end
+
     def self.find(*arguments)
       scope = arguments.slice!(0)
       options = (arguments.slice!(0) || {}).with_indifferent_access
@@ -30,20 +41,24 @@ module ESP
       end
     end
 
-    def self.filters(params)
+    def self.filters(params) # rubocop:disable Metrics/MethodLength
       h = {}.tap do |filters|
         params.each do |attr, value|
-          if value.is_a? Enumerable
-            filters["#{attr.sub(/_in$/, '')}_in"] = value
-          else
-            filters["#{attr.sub(/_eq$/, '')}_eq"] = value
+          unless attr =~ /(#{PREDICATES})$/
+            attr = if value.is_a? Enumerable
+                     "#{attr}_in"
+                   else
+                     "#{attr}_eq"
+                   end
           end
+          filters[attr] = value
         end
       end
       { filter: h }
     end
 
-    def self.make_pageable(object, options)
+    def self.make_pageable(object, options = {}) # rubocop:disable Style/OptionHash
+      options = options.with_indifferent_access
       return object unless object.is_a? ActiveResource::PaginatedCollection
       # Need to set from so paginated collection can use it for page calls.
       object.tap do |collection|
@@ -55,8 +70,9 @@ module ESP
     def self.arrange_options(options)
       if options[:params].present?
         page = options[:params][:page] ? { page: options[:params].delete(:page) } : {}
+        include = options[:params][:include] ? { include: options[:params].delete(:include) } : {}
         options[:params].merge!(options[:params].delete(:filter)) if options[:params][:filter]
-        options[:params] = filters(options[:params]).merge!(page)
+        options[:params] = filters(options[:params]).merge!(page).merge!(include)
       end
       if options[:include].present?
         options[:params] ||= {}

data/lib/esp/resources/service.rb

@@ -4,6 +4,11 @@ module ESP
     # The collection of signatures associated with this service.
     has_many :signatures, class_name: 'ESP::Signature'
 
+    # Not Implemented. You cannot search for a Tag.
+    def self.where(*)
+      fail ESP::NotImplementedError
+    end
+
     # Not Implemented. You cannot create or update a Service.
     def save
       fail ESP::NotImplementedError

data/lib/esp/resources/signature.rb

@@ -24,9 +24,7 @@ module ESP
     #
     # ===== Valid Arguments
     #
-    # +external_account_id+ | Required | The ID of the external account to run this custom signature against
-    #
-    # +region+ | Required | Region name to run this custom signature against
+    # See {API documentation}[http://api-docs.evident.io?ruby#signature-run] for valid arguments
     #
     # ==== Example
     #   signature = ESP::Signature.find(3)
@@ -48,9 +46,7 @@ module ESP
     #
     # ===== Valid Arguments
     #
-    # +external_account_id+ | Required | The ID of the external account to run this custom signature against
-    #
-    # +region+ | Required | Region name to run this custom signature against
+    # See {API documentation}[http://api-docs.evident.io?ruby#signature-run] for valid arguments
     #
     # ==== Example
     #   signature = ESP::Signature.find(3)
@@ -76,11 +72,7 @@ module ESP
     #
     # ===== Valid Arguments
     #
-    # +regions+ | Required | An array of region names to suppress.
-    #
-    # +external_account_ids+ | Required | An Array of the external accounts identified by +external_account_id+ to suppress the signature or custom signature on.
-    #
-    # +reason+ | Required | The reason for creating the suppression.
+    # See {API documentation}[http://api-docs.evident.io?ruby#suppression-create] for valid arguments
     #
     # ==== Example
     #   suppress(regions: ['us_east_1'], external_account_ids: [5], reason: 'My very good reason for creating this suppression')
@@ -89,6 +81,20 @@ module ESP
       ESP::Suppression::Signature.create(signature_ids: [id], regions: Array(arguments[:regions]), external_account_ids: Array(arguments[:external_account_ids]), reason: arguments[:reason])
     end
 
+    # :singleton-method: where
+    # Return a paginated Signature list filtered by search parameters
+    #
+    # ==== Parameters
+    #
+    # +clauses+ | Hash of attributes with appended predicates to search, sort and include.
+    #
+    # ===== Valid Clauses
+    #
+    # See {API documentation}[http://api-docs.evident.io?ruby#signature-attributes] for valid arguments
+    #
+    # :call-seq:
+    #  where(clauses = {})
+
     ##
     # :singleton-method: find
     # Find a Signature by id
@@ -97,8 +103,18 @@ module ESP
     #
     # +id+ | Required | The ID of the signature to retrieve
     #
+    # +options+ | Optional | A hash of options
+    #
+    # ===== Valid Options
+    #
+    # +include+ | The list of associated objects to return on the initial request.
+    #
+    # ===== Valid Includable Associations
+    #
+    # See {API documentation}[http://api-docs.evident.io?ruby#signature-attributes] for valid arguments
+    #
     # :call-seq:
-    #  find(id)
+    #  find(id, options = {})
 
     # :singleton-method: all
     # Return a paginated Signature list

data/lib/esp/resources/stat.rb

@@ -22,6 +22,11 @@ module ESP
     # The stats for each custom signature associated with this stat object.
     has_many :custom_signatures, class_name: 'ESP::StatCustomSignature'
 
+    # Not Implemented. You cannot search for a Stat.
+    def self.where(*)
+      fail ESP::NotImplementedError
+    end
+
     # Not Implemented. You cannot search for a Stat.
     def self.find(*)
       fail ESP::NotImplementedError, 'Regular ARELlike methods are disabled.  Use either the ESP::Stat.for_report or ESP::Stat.latest_for_teams method.'
@@ -37,10 +42,24 @@ module ESP
     # Not Implemented. You cannot delete a Stat.
 
     # Returns all the stats of all the alerts for a report identified by the report_id parameter. Said report contains all statistics for this alert triggered from signatures contained in all regions for the selected hour.
-    def self.for_report(report_id = nil)
+    #
+    # ==== Parameters
+    #
+    # +report_id+ | Required | The ID of the report to retrieve stats for
+    #
+    # +options+ | Optional | A hash of options
+    #
+    # ===== Valid Options
+    #
+    # +include+ | The list of associated objects to return on the initial request.
+    #
+    # ===== valid Includable Associations
+    #
+    # See {API documentation}[http://api-docs.evident.io?ruby#alert-attributes] for valid arguments
+    def self.for_report(report_id = nil, options = {}) # rubocop:disable Style/OptionHash
       fail ArgumentError, "You must supply a report id." unless report_id.present?
       # call find_one directly since find is overriden/not implemented
-      find_one(from: "#{prefix}reports/#{report_id}/stats.json")
+      find_one(from: "#{prefix}reports/#{report_id}/stats.json", params: options)
     end
 
     # Returns all the stats for the most recent report of each team accessible by the given API key.

data/lib/esp/resources/stat_custom_signature.rb

@@ -2,22 +2,38 @@ module ESP
   class StatCustomSignature < ESP::Resource
     include ESP::StatTotals
 
+    ##
     # The custom_signature these stats are for.
     belongs_to :custom_signature, class_name: 'ESP::CustomSignature'
 
+    # Not Implemented. You cannot search for a StatSignature.
+    def self.where(*)
+      fail ESP::NotImplementedError
+    end
+
     # Returns a paginated collection of custom_signature stats for the given stat_id
     # Convenience method to use instead of ::find since a stat_id is required to return custom_signature stats.
     #
-    # ==== Parameter
+    # ==== Parameters
     #
     # +stat_id+ | Required | The ID of the stat to list custom_signature stats for
     #
+    # +options+ | Optional | A hash of options
+    #
+    # ===== Valid Options
+    #
+    # +include+ | The list of associated objects to return on the initial request.
+    #
+    # ===== valid Includable Associations
+    #
+    # See {API documentation}[http://api-docs.evident.io?ruby#stat-custom-signature-attributes] for valid arguments
+    #
     # ==== Example
     #   stats = ESP::StatCustomSignature.for_stat(1194)
-    def self.for_stat(stat_id = nil)
+    def self.for_stat(stat_id = nil, options = {}) # rubocop:disable Style/OptionHash
       fail ArgumentError, "You must supply a stat id." unless stat_id.present?
       from = "#{prefix}stats/#{stat_id}/custom_signatures.json"
-      find(:all, from: from)
+      find(:all, from: from, params: options)
     end
 
     # Find a StatRegion by id
@@ -26,8 +42,18 @@ module ESP
     #
     # +id+ | Required | The ID of the custom_signature stat to retrieve
     #
+    # +options+ | Optional | A hash of options
+    #
+    # ===== Valid Options
+    #
+    # +include+ | The list of associated objects to return on the initial request.
+    #
+    # ===== valid Includable Associations
+    #
+    # See {API documentation}[http://api-docs.evident.io?ruby#stat-custom-signature-attributes] for valid arguments
+    #
     # :call-seq:
-    #  find(id)
+    #  find(id, options = {})
     def self.find(*arguments)
       scope = arguments.slice!(0)
       options = (arguments.slice!(0) || {}).with_indifferent_access

data/lib/esp/resources/stat_region.rb

@@ -2,9 +2,15 @@ module ESP
   class StatRegion < ESP::Resource
     include ESP::StatTotals
 
+    ##
     # The region these stats are for.
     belongs_to :region, class_name: 'ESP::Region'
 
+    # Not Implemented. You cannot search for a StatSignature.
+    def self.where(*)
+      fail ESP::NotImplementedError
+    end
+
     # Returns a paginated collection of region stats for the given stat_id
     # Convenience method to use instead of ::find since a stat_id is required to return region stats.
     #
@@ -12,12 +18,22 @@ module ESP
     #
     # +stat_id+ | Required | The ID of the stat to list region stats for
     #
+    # +options+ | Optional | A hash of options
+    #
+    # ===== Valid Options
+    #
+    # +include+ | The list of associated objects to return on the initial request.
+    #
+    # ===== valid Includable Associations
+    #
+    # See {API documentation}[http://api-docs.evident.io?ruby#stat-region-attributes] for valid arguments
+    #
     # ==== Example
     #   stats = ESP::StatRegion.for_stat(1194)
-    def self.for_stat(stat_id = nil)
+    def self.for_stat(stat_id = nil, options = {}) # rubocop:disable Style/OptionHash
       fail ArgumentError, "You must supply a stat id." unless stat_id.present?
       from = "#{prefix}stats/#{stat_id}/regions.json"
-      find(:all, from: from)
+      find(:all, from: from, params: options)
     end
 
     # Find a StatRegion by id
@@ -26,8 +42,18 @@ module ESP
     #
     # +id+ | Required | The ID of the region stat to retrieve
     #
+    # +options+ | Optional | A hash of options
+    #
+    # ===== Valid Options
+    #
+    # +include+ | The list of associated objects to return on the initial request.
+    #
+    # ===== valid Includable Associations
+    #
+    # See {API documentation}[http://api-docs.evident.io?ruby#stat-region-attributes] for valid arguments
+    #
     # :call-seq:
-    #  find(id)
+    #  find(id, options = {})
     def self.find(*arguments)
       scope = arguments.slice!(0)
       options = (arguments.slice!(0) || {}).with_indifferent_access

data/lib/esp/resources/stat_service.rb

@@ -2,9 +2,15 @@ module ESP
   class StatService < ESP::Resource
     include ESP::StatTotals
 
+    ##
     # The service these stats are for.
     belongs_to :service, class_name: 'ESP::Service'
 
+    # Not Implemented. You cannot search for a StatSignature.
+    def self.where(*)
+      fail ESP::NotImplementedError
+    end
+
     # Returns a paginated collection of service stats for the given stat_id
     # Convenience method to use instead of ::find since a stat_id is required to return service stats.
     #
@@ -12,12 +18,22 @@ module ESP
     #
     # +stat_id+ | Required | The ID of the stat to list service stats for
     #
+    # +options+ | Optional | A hash of options
+    #
+    # ===== Valid Options
+    #
+    # +include+ | The list of associated objects to return on the initial request.
+    #
+    # ===== valid Includable Associations
+    #
+    # See {API documentation}[http://api-docs.evident.io?ruby#stat-service-attributes] for valid arguments
+    #
     # ==== Example
     #   stats = ESP::StatService.for_stat(1194)
-    def self.for_stat(stat_id = nil)
+    def self.for_stat(stat_id = nil, options = {}) # rubocop:disable Style/OptionHash
       fail ArgumentError, "You must supply a stat id." unless stat_id.present?
       from = "#{prefix}stats/#{stat_id}/services.json"
-      find(:all, from: from)
+      find(:all, from: from, params: options)
     end
 
     # Find a StatService by id
@@ -26,8 +42,18 @@ module ESP
     #
     # +id+ | Required | The ID of the service stat to retrieve
     #
+    # +options+ | Optional | A hash of options
+    #
+    # ===== Valid Options
+    #
+    # +include+ | The list of associated objects to return on the initial request.
+    #
+    # ===== valid Includable Associations
+    #
+    # See {API documentation}[http://api-docs.evident.io?ruby#stat-service-attributes] for valid arguments
+    #
     # :call-seq:
-    #  find(id)
+    #  find(id, options = {})
     def self.find(*arguments)
       scope = arguments.slice!(0)
       options = (arguments.slice!(0) || {}).with_indifferent_access

data/lib/esp/resources/stat_signature.rb

@@ -2,9 +2,15 @@ module ESP
   class StatSignature < ESP::Resource
     include ESP::StatTotals
 
+    ##
     # The signature these stats are for.
     belongs_to :signature, class_name: 'ESP::Signature'
 
+    # Not Implemented. You cannot search for a StatSignature.
+    def self.where(*)
+      fail ESP::NotImplementedError
+    end
+
     # Returns a paginated collection of signature stats for the given stat_id
     # Convenience method to use instead of ::find since a stat_id is required to return signature stats.
     #
@@ -12,12 +18,22 @@ module ESP
     #
     # +stat_id+ | Required | The ID of the stat to list signature stats for
     #
+    # +options+ | Optional | A hash of options
+    #
+    # ===== Valid Options
+    #
+    # +include+ | The list of associated objects to return on the initial request.
+    #
+    # ===== valid Includable Associations
+    #
+    # See {API documentation}[http://api-docs.evident.io?ruby#stat-signature-attributes] for valid arguments
+    #
     # ==== Example
     #   stats = ESP::StatSignature.for_stat(1194)
-    def self.for_stat(stat_id = nil)
+    def self.for_stat(stat_id = nil, options = {}) # rubocop:disable Style/OptionHash
       fail ArgumentError, "You must supply a stat id." unless stat_id.present?
       from = "#{prefix}stats/#{stat_id}/signatures.json"
-      find(:all, from: from)
+      find(:all, from: from, params: options)
     end
 
     # Find a StatRegion by id
@@ -26,8 +42,18 @@ module ESP
     #
     # +id+ | Required | The ID of the signature stat to retrieve
     #
+    # +options+ | Optional | A hash of options
+    #
+    # ===== Valid Options
+    #
+    # +include+ | The list of associated objects to return on the initial request.
+    #
+    # ===== valid Includable Associations
+    #
+    # See {API documentation}[http://api-docs.evident.io?ruby#stat-signature-attributes] for valid arguments
+    #
     # :call-seq:
-    #  find(id)
+    #  find(id, options = {})
     def self.find(*arguments)
       scope = arguments.slice!(0)
       options = (arguments.slice!(0) || {}).with_indifferent_access

data/lib/esp/resources/sub_organization.rb

@@ -16,6 +16,20 @@ module ESP
     # The collection of reports that belong to the sub organization.
     has_many :reports, class_name: 'ESP::Report'
 
+    # :singleton-method: where
+    # Return a paginated SubOrganization list filtered by search parameters
+    #
+    # ==== Parameters
+    #
+    # +clauses+ | Hash of attributes with appended predicates to search, sort and include.
+    #
+    # ===== Valid Clauses
+    #
+    # See {API documentation}[http://api-docs.evident.io?ruby#sub-organization-attributes] for valid arguments
+    #
+    # :call-seq:
+    #  where(clauses = {})
+
     ##
     # :singleton-method: find
     # Find a SubOrganization by id
@@ -24,8 +38,18 @@ module ESP
     #
     # +id+ | Required | The ID of the sub organization to retrieve
     #
+    # +options+ | Optional | A hash of options
+    #
+    # ===== Valid Options
+    #
+    # +include+ | The list of associated objects to return on the initial request.
+    #
+    # ===== Valid Includable Associations
+    #
+    # See {API documentation}[http://api-docs.evident.io?ruby#sub-organization-attributes] for valid arguments
+    #
     # :call-seq:
-    #  find(id)
+    #  find(id, options = {})
 
     # :singleton-method: all
     # Return a paginated SubOrganization list
@@ -41,7 +65,7 @@ module ESP
     #
     # ===== Valid Attributes
     #
-    # +name+ | Required | The name of the sub organization
+    # See {API documentation}[http://api-docs.evident.io?ruby#sub-organization-create] for valid arguments
     #
     # ==== Example
     #
@@ -56,7 +80,7 @@ module ESP
     #
     # ===== Valid Attributes
     #
-    # +name+ | Required | The name of the sub organization
+    # See {API documentation}[http://api-docs.evident.io?ruby#sub-organization-create] for valid arguments
     #
     # ==== Example
     #