esp_sdk 2.5.0 → 2.6.0

data/lib/esp/resources/alert.rb

@@ -1,60 +1,64 @@
 module ESP
   class Alert < ESP::Resource
-    ##
     # Returns the external account associated with this alert.
+    # @return [ESP::ExternalAccount]
     belongs_to :external_account, class_name: 'ESP::ExternalAccount'
 
-    ##
     # Returns the region associated with this alert.
+    # @return [ESP::Region]
     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.
+    # @return [ESP::Signature]
     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.
+    # @return [ESP::CustomSignature]
     belongs_to :custom_signature, class_name: 'ESP::CustomSignature'
 
-    ##
     # Returns the suppression associated with this alert.  If present the alert was suppressed.
+    # @return [ESP::Suppression]
     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
+    # @return [ActiveResource::PaginatedCollection<ESP::CloudTrailEvent>]
     has_many :cloud_trail_events, class_name: 'ESP::CloudTrailEvent'
 
-    ##
     # Returns the tags associated with this alert.
+    # @return [ActiveResource::PaginatedCollection<ESP::Tag>]
     has_many :tags, class_name: 'ESP::Tag'
 
-    ##
     # Returns the metadata associated with this alert.
+    #
+    # @return [ESP::Metadata]
     def metadata
       ESP::Metadata.for_alert(id)
     end
 
     # Not Implemented. You cannot create or update an Alert.
+    #
+    # @return [void]
     def save
       fail ESP::NotImplementedError
     end
 
-    # Not Implemented. You cannot destroy a an Alert.
+    # Not Implemented. You cannot destroy an Alert.
+    #
+    # @return [void]
     def destroy
       fail ESP::NotImplementedError
     end
 
-    # Returns a paginated collection of alerts for the given report_id
+    # Returns alerts for the given report_id
     #
-    # ==== Parameters
+    # *call-seq* -> +super.where(clauses)+
     #
-    # +clauses+ | Required | Hash of attributes with appended predicates to search, sort and include.
+    # @param clauses [Hash] Required hash of attributes with appended predicates to search, sort and include.
+    #   ===== Valid Clauses
     #
-    # ===== Valid Clauses
-    #
-    # See {API documentation}[http://api-docs.evident.io?ruby#searching-alerts] for valid arguments
-    #
-    # ==== Example
+    #   See {API documentation}[http://api-docs.evident.io?ruby#searching-alerts] for valid arguments
+    # @return [ActiveResource::PaginatedCollection<ESP::Alert>]
+    # @example
     #   alerts = ESP::Alert.where(report_id: 54, status_eq: 'fail', signature_risk_level_in: ['High'], include: 'signature')
     def self.where(clauses = {})
       clauses = clauses.with_indifferent_access
@@ -65,25 +69,30 @@ module ESP
 
     # Find an Alert by id
     #
-    # ==== Parameter
-    #
-    # +id+ | Required | The ID of the alert 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#searching-alerts] for valid arguments
-    #
-    # ==== Example
-    # alert = ESP::Alert.find(1, include: 'tags,external_account.team')
+    # @overload find(id)
+    #   @param id [Integer, Numeric, #to_i] Required ID of the alert to retrieve.
+    # @overload find(id, options)
+    #   @param id [Integer, Numeric, #to_i] Required ID of the alert to retrieve.
+    #   @param options [Hash]
+    #     ===== 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#searching-alerts] for valid arguments
+    # @overload find(scope, options)
+    #   *call-seq* -> +super.all(options)+
+    #   @api private
+    #   @param scope [Object] *Example:* +:all+
+    #   @param options [Hash] +{ params: { report_id: Integer } }+
+    #   @raise [ArgumentError] if no +report_id+ is supplied.
+    # @return [ESP::Alert]
+    # @example
+    #   alert = ESP::Alert.find(1)
+    #   alert = ESP::Alert.find(1, include: 'tags,external_account.team')
+    #   alert = ESP::Alert.find(:all, params: { report_id: 5 })
     #
-    # :call-seq:
-    #  find(id, options = {})
     def self.find(*arguments)
       scope = arguments.slice!(0)
       options = (arguments.slice!(0) || {}).with_indifferent_access
@@ -93,31 +102,33 @@ module ESP
       all(from: "#{from}.json", params: params)
     end
 
-    def self.for_report(report_id) # :nodoc:
+    # @private
+    def self.for_report(report_id)
       fail ArgumentError, "You must supply a report id." unless report_id.present?
       "#{prefix}reports/#{report_id}/alerts"
     end
 
     # Suppress the signature associated with this alert.
-    # ==== Parameter
     #
-    # +reason+ | Required | The reason for creating the suppression.
+    # @param reason [String] Required reason for creating the suppression.
+    # @return [ESP::Suppression::Signature]
     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.
+    # @param reason [String] Required reason for creating the suppression.
+    # @return [ESP::Suppression::Region]
     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.
+    # @param reason [String] Required reason for creating the suppression.
+    # @return [ESP::Suppression::UniqueIdentifier]
+    # @raise [ArgumentError] if no +reason+ is supplied.
     def suppress_unique_identifier(reason = nil)
       suppress(Suppression::UniqueIdentifier, reason)
     end

data/lib/esp/resources/cloud_trail_event.rb

@@ -1,28 +1,33 @@
 module ESP
   class CloudTrailEvent < ESP::Resource
     # Not Implemented. You cannot search for a CloudTrailEvent.
+    #
+    # @return [void]
     def self.where(*)
       fail ESP::NotImplementedError
     end
 
     # Not Implemented. You cannot create or update a CloudTrailEvent.
+    #
+    # @return [void]
     def save
       fail ESP::NotImplementedError
     end
 
     # Not Implemented. You cannot destroy a CloudTrailEvent.
+    #
+    # @return [void]
     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.
+    # Returns 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
+    # @param alert_id [Integer, Numeric, #to_i] Required ID of the alert to retrieve cloud trail events for.
+    # @return [ActiveResource::PaginatedCollection<ESP::CloudTrailEvent>]
+    # @raise [ArgumentError] if no +alert_id+ is provided.
+    # @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?
@@ -32,12 +37,13 @@ module ESP
 
     # Find a CloudTrailEvent by id
     #
-    # ==== Parameter
-    #
-    # +id+ | Required | The ID of the cloud trail event to retrieve
+    # *call-seq* -> +super.find(id)+
     #
-    # :call-seq:
-    #  find(id)
+    # @overload find(id)
+    #   @param id [Integer, Numeric, #to_i] Required ID of the cloud trail event to retrieve
+    # @return [ESP::CloudTrailEvent]
+    # @example
+    #   alert = ESP::CloudTrailEvent.find(1)
     def self.find(*arguments)
       scope = arguments.slice!(0)
       options = (arguments.slice!(0) || {}).with_indifferent_access

data/lib/esp/resources/concerns/stat_totals.rb

@@ -1,79 +1,82 @@
-module ESP::StatTotals # :nodoc:
-  # Not Implemented. You cannot create or update a Stat.
-  def save
-    fail ESP::NotImplementedError
-  end
-
-  # Not Implemented. You cannot delete a Stat.
-  def destroy
-    fail ESP::NotImplementedError
-  end
+module ESP
+  # @private
+  module StatTotals
+    # Not Implemented. You cannot create or update a Stat.
+    def save
+      fail ESP::NotImplementedError
+    end
 
-  # We only add new_1w* and old* fields as the new_1w field includes the counts from new_1h and new_1d.
-  def total
-    attributes.select { |a, _v| a.match(/new_1w|old/) }.values.reduce(:+)
-  end
+    # Not Implemented. You cannot delete a Stat.
+    def destroy
+      fail ESP::NotImplementedError
+    end
 
-  def total_suppressed
-    attributes.select { |a, _v| a.match(/suppressed_/) }.values.reduce(:+)
-  end
+    # We only add new_1w* and old* fields as the new_1w field includes the counts from new_1h and new_1d.
+    def total
+      attributes.select { |a, _v| a.match(/new_1w|old/) }.values.reduce(:+)
+    end
 
-  %w(fail warn error pass info).each do |status|
-    # Defines the following methods:
-    #   Stat#total_pass
-    #   Stat#total_fail
-    #   Stat#total_warn
-    #   Stat#total_error
-    #   Stat#total_info
-    define_method "total_#{status}" do
-      attributes.select { |a, _v| a.match(/new_1w|old/) && a.match(/#{status}/) }.values.reduce(:+)
+    def total_suppressed
+      attributes.select { |a, _v| a.match(/suppressed_/) }.values.reduce(:+)
     end
 
-    # Defines the following methods:
-    #   Stat#total_new_1h_pass
-    #   Stat#total_new_1h_fail
-    #   Stat#total_new_1h_warn
-    #   Stat#total_new_1h_error
-    #   Stat#total_new_1h_info
-    #   Stat#total_new_1d_pass
-    #   Stat#total_new_1d_fail
-    #   Stat#total_new_1d_warn
-    #   Stat#total_new_1d_error
-    #   Stat#total_new_1d_info
-    #   Stat#total_new_1w_pass
-    #   Stat#total_new_1w_fail
-    #   Stat#total_new_1w_error
-    #   Stat#total_new_1w_info
-    #   Stat#total_new_1w_warn
-    #   Stat#total_old_fail
-    #   Stat#total_old_pass
-    #   Stat#total_old_warn
-    #   Stat#total_old_error
-    #   Stat#total_old_info
-    %w(new_1h new_1d new_1w old).each do |time|
-      define_method "total_#{time}_#{status}" do
-        attributes.select { |a| a.match(/#{time}/) && a.match(/#{status}/) }.values.reduce(:+)
+    %w(fail warn error pass info).each do |status|
+      # Defines the following methods:
+      #   Stat#total_pass
+      #   Stat#total_fail
+      #   Stat#total_warn
+      #   Stat#total_error
+      #   Stat#total_info
+      define_method "total_#{status}" do
+        attributes.select { |a, _v| a.match(/new_1w|old/) && a.match(/#{status}/) }.values.reduce(:+)
       end
-    end
 
-    # Defines the following methods:
-    #   Stat#total_suppressed_pass
-    #   Stat#total_suppressed_fail
-    #   Stat#total_suppressed_warn
-    #   Stat#total_suppressed_error
-    define_method "total_suppressed_#{status}" do
-      attributes.select { |a| a.match(/suppressed_/) && a.match(/#{status}/) }.values.reduce(:+)
+      # Defines the following methods:
+      #   Stat#total_new_1h_pass
+      #   Stat#total_new_1h_fail
+      #   Stat#total_new_1h_warn
+      #   Stat#total_new_1h_error
+      #   Stat#total_new_1h_info
+      #   Stat#total_new_1d_pass
+      #   Stat#total_new_1d_fail
+      #   Stat#total_new_1d_warn
+      #   Stat#total_new_1d_error
+      #   Stat#total_new_1d_info
+      #   Stat#total_new_1w_pass
+      #   Stat#total_new_1w_fail
+      #   Stat#total_new_1w_error
+      #   Stat#total_new_1w_info
+      #   Stat#total_new_1w_warn
+      #   Stat#total_old_fail
+      #   Stat#total_old_pass
+      #   Stat#total_old_warn
+      #   Stat#total_old_error
+      #   Stat#total_old_info
+      %w(new_1h new_1d new_1w old).each do |time|
+        define_method "total_#{time}_#{status}" do
+          attributes.select { |a| a.match(/#{time}/) && a.match(/#{status}/) }.values.reduce(:+)
+        end
+      end
+
+      # Defines the following methods:
+      #   Stat#total_suppressed_pass
+      #   Stat#total_suppressed_fail
+      #   Stat#total_suppressed_warn
+      #   Stat#total_suppressed_error
+      define_method "total_suppressed_#{status}" do
+        attributes.select { |a| a.match(/suppressed_/) && a.match(/#{status}/) }.values.reduce(:+)
+      end
     end
-  end
 
-  # Defines the following methods:
-  #   Stat#total_new_1h
-  #   Stat#total_new_1d
-  #   Stat#total_new_1w
-  #   Stat#total_old
-  %w(new_1h new_1d new_1w old).each do |time|
-    define_method "total_#{time}" do
-      attributes.select { |a| a.match(/#{time}/) }.values.reduce(:+)
+    # Defines the following methods:
+    #   Stat#total_new_1h
+    #   Stat#total_new_1d
+    #   Stat#total_new_1w
+    #   Stat#total_old
+    %w(new_1h new_1d new_1w old).each do |time|
+      define_method "total_#{time}" do
+        attributes.select { |a| a.match(/#{time}/) }.values.reduce(:+)
+      end
     end
   end
 end

data/lib/esp/resources/contact_request.rb

@@ -2,42 +2,45 @@ module ESP
   # Use contact requests to send a support or feature request to Evident.io.
   class ContactRequest < ESP::Resource
     # Not Implemented. You cannot search for ContactRequest.
+    #
+    # @return [void]
     def self.find(*)
       fail ESP::NotImplementedError
     end
 
     # Not Implemented. You cannot search for ContactRequest.
+    #
+    # @return [void]
     def self.where(*)
       fail ESP::NotImplementedError
     end
 
     # Not Implemented. You cannot update a ContactRequest.
+    #
+    # @return [void]
     def update
       fail ESP::NotImplementedError
     end
 
     # Not Implemented. You cannot destroy a ContactRequest.
+    #
+    # @return [void]
     def destroy
       fail ESP::NotImplementedError
     end
 
-    # :method: create(attributes={})
-    # Create a contact request.
-    #
-    # ==== Parameter
-    #
-    # +attributes+ | Required | A hash of contact request attributes
-    #
-    # ===== Valid Attributes
-    #
-    # See {API documentation}[http://api-docs.evident.io?ruby#contact-request-create] for valid arguments
+    # @!method self.create(attributes={})
+    #   Create a contact request.
     #
+    #   *call-seq* -> +create(attributes={})+
     #
-    # :call-seq:
-    #  create(attributes={})
+    #   @param attributes [Hash] Required hash of contact request attributes
+    #     ===== Valid Attributes
     #
-    # ==== Example
+    #     See {API documentation}[http://api-docs.evident.io?ruby#contact-request-create] for valid arguments
+    #   @return [ESP::ContactRequest]
+    #   @example
+    #     contact_request = ESP::ContactRequest.create(request_type: 'feature', title: 'My great feature idea', description: 'This is my idea for a really useful feature...')
     #
-    #   contact_request = ESP::ContactRequest.create(request_type: 'feature', title: 'My great feature idea', description: 'This is my idea for a really useful feature...')
   end
 end

data/lib/esp/resources/custom_signature/definition.rb

@@ -6,6 +6,7 @@ module ESP
       belongs_to :custom_signature, class_name: 'ESP::CustomSignature'
       has_many :results, class_name: 'ESP::CustomSignature::Result'
 
+      # @return [Net::HTTPSuccess, false]
       def activate
         patch(:activate).tap do |response|
           load_attributes_from_response(response)
@@ -16,6 +17,7 @@ module ESP
         false
       end
 
+      # @return [Net::HTTPSuccess, false]
       def archive
         patch(:archive).tap do |response|
           load_attributes_from_response(response)
@@ -26,75 +28,68 @@ module ESP
         false
       end
 
-      # :singleton-method: where
-      # Return a paginated CustomSignature::Definition list filtered by search parameters
+      # @!method self.where(clauses = {})
+      #   Return a list filtered by search parameters
       #
-      # ==== Parameters
+      #   *call-seq* -> +super.where(clauses = {})+
       #
-      # +clauses+ | Hash of attributes with appended predicates to search, sort and include.
+      #   @param clauses [Hash] A hash of attributes with appended predicates to search, sort and include.
+      #     ===== Valid Clauses
       #
-      # ===== Valid Clauses
-      #
-      # See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-definition-attributes] for valid arguments
-      #
-      # :call-seq:
-      #  where(clauses = {})
+      #     See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-definition-attributes] for valid arguments
+      #   @return [ActiveResource::PaginatedCollection<ESP::CustomSignature::Definition>]
 
-      ##
-      # :singleton-method: find
-      # Find a CustomSignature::Definition by id
-      #
-      # ==== Parameter
+      # @!method self.find(id)
+      #   Find a CustomSignature::Definition by id
       #
-      # +id+ | Required | The ID of the custom signature definition to retrieve
+      #   *call-seq* -> +find(id, options = {})+
       #
-      # +options+ | Optional | A hash of options
+      #   @overload find(id)
+      #   @overload find(id, options = {})
+      #     @param options | Optional | A hash of options
+      #       ===== Valid Options
       #
-      # ===== Valid Options
+      #       +include+ | The list of associated objects to return on the initial request.
       #
-      # +include+ | The list of associated objects to return on the initial request.
+      #       ===== Valid Includable Associations
       #
-      # ===== Valid Includable Associations
-      #
-      # See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-definition-attributes] for valid arguments
-      #
-      # :call-seq:
-      #  find(id, options = {})
-
-      # :singleton-method: all
-      # Return a paginated CustomSignature::Definition list
+      #       See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-definition-attributes] for valid arguments
+      #   @param id [Integer, Numeric, #to_i] Required ID of the custom signature definition to retrieve
+      #   @return [ESP::CustomSignature::Definition]
 
-      # :singleton-method: create
-      # Create a CustomSignature::Definition
-      # :call-seq:
-      #   create(attributes={})
+      # @!method self.all
+      #   Return a paginated list
       #
-      # ==== Parameter
-      #
-      # +attributes+ | Required | A hash of custom signature definition attributes
-      #
-      # ===== Valid Attributes
-      #
-      # See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-definition-create] for valid arguments
+      #   @return [ActiveResource::PaginatedCollection<ESP::CustomSignature::Definition>]
+
+      # @!method self.create(attributes = {})
+      #   Create a CustomSignature::Definition
+      #   *call-seq* -> +super.create(attributes={})+
       #
-      # ==== Example
+      #   @param attributes [Hash] Required hash of custom signature definition attributes.
+      #     ===== Valid Attributes
       #
-      #  definition = ESP::CustomSignature::Definition.create(custom_signature_id: 1)
+      #     See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-definition-create] for valid arguments
+      #   @return [ESP::CustomSignature::Definition
+      #   @example
+      #     definition = ESP::CustomSignature::Definition.create(custom_signature_id: 1)
 
-      # :method: save
-      # Create or update a CustomSignature::Definition
-      #
-      # ===== Valid Attributes
+      # @!method save
+      #   Create or update a CustomSignature::Definition
       #
-      # See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-definition-create] for valid arguments
+      #   ===== Valid Attributes
       #
-      # ==== Example
+      #   See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-definition-create] for valid arguments
       #
-      #  definition = ESP::CustomSignature::Definition.new(custom_signature_id: 1)
-      #  definition.save
+      #   @return [Boolean]
+      #   @example
+      #    definition = ESP::CustomSignature::Definition.new(custom_signature_id: 1)
+      #    definition.save
 
-      # :method: destroy
-      # Delete a CustomSignature::Definition
+      # @!method destroy
+      #   Delete a CustomSignature::Definition
+      #
+      #   @return [self]
     end
   end
 end

data/lib/esp/resources/custom_signature/result/alert.rb

@@ -8,11 +8,9 @@ module ESP
 
         # Returns all the alerts for a custom signature result identified by the custom_signature_result_id parameter.
         #
-        # ==== Parameters
-        #
-        # +custom_signature_result_id+ | Required | The ID of the custom signature result to retrieve alerts for
-        #
-        # See {API documentation}[http://api-docs.evident.io?ruby#alert-attributes] for valid arguments
+        # @param custom_signature_result_id [Integer, Numeric, #to_i] Required ID of the custom signature result to retrieve alerts for
+        # @return [ActiveResource::PaginatedCollection<ESP::CustomSignature::Result::Alert>]
+        # @raise [ArgumentError] if no +custom_signature_result_id+ is supplied.
         def self.for_result(custom_signature_result_id = nil)
           fail ArgumentError, "You must supply a custom signature result id." unless custom_signature_result_id.present?
           # call find_every directly since find is overriden/not implemented
@@ -22,6 +20,8 @@ module ESP
         # Not Implemented. You cannot search for CustomSignature::Result::Alert.
         #
         # Regular ARELlike methods are disabled.
+        #
+        # @return [void]
         def self.find(*)
           fail ESP::NotImplementedError, 'Regular ARELlike methods are disabled. Use the .for_result method.'
         end
@@ -29,21 +29,29 @@ module ESP
         # Not Implemented. You cannot search for CustomSignature::Result::Alert.
         #
         # Regular ARELlike methods are disabled.
+        #
+        # @return [void]
         def self.where(*)
           fail ESP::NotImplementedError, 'Regular ARELlike methods are disabled. Use the .for_result method.'
         end
 
         # Not Implemented. You cannot create a CustomSignature::Result::Alert.
+        #
+        # @return [void]
         def create
           fail ESP::NotImplementedError
         end
 
         # Not Implemented. You cannot update a CustomSignature::Result::Alert.
+        #
+        # @return [void]
         def update
           fail ESP::NotImplementedError
         end
 
         # Not Implemented. You cannot destroy a CustomSignature::Result::Alert.
+        #
+        # @return [void]
         def destroy
           fail ESP::NotImplementedError
         end