esp_sdk 2.5.0 → 2.6.0

data/lib/esp/resources/organization.rb

@@ -1,85 +1,95 @@
 module ESP
   class Organization < ESP::Resource
-    ##
     # The collection of teams that belong to the organization.
+    #
+    # @return [ActiveResource::PaginatedCollection<ESP::Team>]
     has_many :teams, class_name: 'ESP::Team'
 
-    ##
     # The collection of sub_organizations that belong to the organization.
+    #
+    # @return [ActiveResource::PaginatedCollection<ESP::SubOrganization>]
     has_many :sub_organizations, class_name: 'ESP::SubOrganization'
 
-    ##
     # The collection of users that belong to the organization.
+    #
+    # @return [ActiveResource::PaginatedCollection<ESP::User>]
     has_many :users, class_name: 'ESP::User'
 
-    ##
     # The collection of reports that belong to the organization.
+    #
+    # @return [ActiveResource::PaginatedCollection<ESP::Report>]
     has_many :reports, class_name: 'ESP::Report'
 
-    ##
     # The collection of external_accounts that belong to the organization.
+    #
+    # @return [ActiveResource::PaginatedCollection<ESP::ExternalAccount>]
     has_many :external_accounts, class_name: 'ESP::ExternalAccount'
 
-    ##
     # The collection of organizations that belong to the organization.
+    #
+    # @return [ActiveResource::PaginatedCollection<ESP::CustomSignature>]
     has_many :custom_signatures, class_name: 'ESP::CustomSignature'
 
     # Not Implemented. You cannot create an Organization.
-    def create # :nodoc:
+    #
+    # @private
+    def create
       fail ESP::NotImplementedError
     end
 
     # Not Implemented. You cannot destroy an Organization.
+    #
+    # @return [void]
     def destroy
       fail ESP::NotImplementedError
     end
 
-    # :singleton-method: where
-    # Return a paginated Organization list filtered by search parameters
+    # @!method self.where(clauses = {})
+    #   Return a paginated 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#organization-attributes] for valid arguments
-    #
-    # :call-seq:
-    #  where(clauses = {})
+    #     See {API documentation}[http://api-docs.evident.io?ruby#organization-attributes] for valid arguments
+    #   @return [ActiveResource::PaginatedCollection<ESP::Organization>]
 
-    ##
-    # :singleton-method: find
-    # Find a Organization by id
-    #
-    # ==== Parameter
-    #
-    # +id+ | Required | The ID of the organization to retrieve
+    # @!method self.find(id)
+    #   Find an Organization by id
     #
-    # +options+ | Optional | A hash of options
+    #   *call-seq* -> +super.find(id, options = {})+
     #
-    # ===== Valid Options
+    #   @overload find(id)
+    #   @overload find(id, options = {})
+    #     @param options [Hash] Optional hash of 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#organization-attributes] for valid arguments
-    #
-    # :call-seq:
-    #  find(id, options = {})
+    #       See {API documentation}[http://api-docs.evident.io?ruby#organization-attributes] for valid arguments
+    #   @param id [Integer, Numeric, #to_i] Required ID of the organization to retrieve.
+    #   @return [ESP::Organization]
 
-    # :singleton-method: all
-    # Return a paginated Organization list
+    # @!method self.all
+    #   Return a paginated list.
+    #
+    #   @return [ActiveResource::PaginatedCollection<ESP::Organization>]
 
-    # :singleton-method: create
+    # @!method self.create
     # Not Implemented. You cannot create an Organization.
+    #
+    # @return [void]
 
-    # :method: save
-    # Update an Organization.
+    # @!method save
+    #   Update an Organization.
+    #
+    #   ===== Valid Attributes
     #
-    # ===== Valid Attributes
+    #   See {API documentation}[http://api-docs.evident.io?ruby#organization-update] for valid arguments
     #
-    # See {API documentation}[http://api-docs.evident.io?ruby#organization-update] for valid arguments
+    #   @return [Boolean]
   end
 end

data/lib/esp/resources/region.rb

@@ -1,58 +1,55 @@
 module ESP
   class Region < ESP::Resource
     # Not Implemented. You cannot create or update a CloudTrailEvent.
+    #
+    # @return [void]
     def save
       fail ESP::NotImplementedError
     end
 
     # Not Implemented. You cannot destroy a an CloudTrailEvent.
+    #
+    # @return [void]
     def destroy
       fail ESP::NotImplementedError
     end
 
     # Create a suppression for this region.
     #
-    # ==== Parameter
-    #
-    # +arguments+ | Required | A hash of region suppression attributes
-    #
-    # ===== Valid Arguments
-    #
-    # See {API documentation}[http://api-docs.evident.io?ruby#suppression-create] for valid arguments
+    # @param arguments [Hash] Required hash of region suppression attributes.
+    #   ===== Valid Arguments
     #
-    # ==== Example
+    #   See {API documentation}[http://api-docs.evident.io?ruby#suppression-create] for valid arguments
+    # @return [ESP::Suppression::Region]
+    # @example
     #   suppress(external_account_ids: [5], reason: 'My very good reason for creating this suppression')
     def suppress(arguments = {})
       arguments = arguments.with_indifferent_access
       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
+    # @!method self.where(clauses = {})
+    #   Return a paginated Region list filtered by search parameters
     #
-    # ==== Parameters
+    #   *call-seq* -> +super.where(clauses = {})+
     #
-    # +clauses+ | Hash of attributes with appended predicates to search and sort by.
+    #   @param clauses [Hash] A hash of attributes with appended predicates to search and sort by.
+    #     ===== Valid Clauses
     #
-    # ===== Valid Clauses
-    #
-    # See {API documentation}[http://api-docs.evident.io?ruby#region-attributes] for valid arguments
-    #
-    # :call-seq:
-    #  where(clauses = {})
+    #     See {API documentation}[http://api-docs.evident.io?ruby#region-attributes] for valid arguments
+    #   @return [ActiveResource::PaginatedCollection<ESP::Region>]
 
-    ##
-    # :singleton-method: find
-    # Find a Region by id
+    # @!method self.find(id)
+    #   Find a Region by id
     #
-    # ==== Parameter
+    #   *call-seq* -> +super.find(id)+
     #
-    # +id+ | Required | The ID of the region to retrieve
-    #
-    # :call-seq:
-    #  find(id)
+    #   @param id [Integer, Numeric, #to_i] Required ID of the region to retrieve.
+    #   @return [ESP::Region]
 
-    # :singleton-method: all
-    # Return a paginated Region list
+    # @!method self.all
+    #   Return a paginated list.
+    #
+    #   @return [ActiveResource::PaginatedCollection<ESP::Region>]
   end
 end

data/lib/esp/resources/report.rb

@@ -4,43 +4,52 @@ module ESP
       autoload :Integration, File.expand_path(File.dirname(__FILE__) + '/reports/export/integration')
     end
 
-    ##
     # The organization the report belongs to.
+    #
+    # @return [ESP::Organization]
     belongs_to :organization, class_name: 'ESP::Organization'
 
-    ##
     # The sub_organization the report belongs to.
+    #
+    # @return [ESP::SubOrganization]
     belongs_to :sub_organization, class_name: 'ESP::SubOrganization'
 
-    ##
     # The team the report belongs to.
+    #
+    # @return [ESP::Team]
     belongs_to :team, class_name: 'ESP::Team'
 
-    ##
     # The external_account the report belongs to.
+    #
+    # @return [ESP::ExternalAccount]
     belongs_to :external_account, class_name: 'ESP::ExternalAccount'
 
     # Not Implemented. You cannot update a Report.
+    #
+    # @return [void]
     def update
       fail ESP::NotImplementedError
     end
 
     # Not Implemented. You cannot destroy a Report.
+    #
+    # @return [void]
     def destroy
       fail ESP::NotImplementedError
     end
 
     # Enqueue a report to be run for the given team.
     # Returns a Report object with a status of 'queued' and an id
-    # ==== Attribute
-    #
-    # See {API documentation}[http://api-docs.evident.io?ruby#report-create] for valid arguments
     #
     # Periodically check the API
     #   ESP::Report.find(<id>)
     # until status is 'complete'.
     #
     # If not successful, returns a Report object with the errors object populated.
+    #
+    # @param arguments [Hash] See {API documentation}[http://api-docs.evident.io?ruby#report-create] for valid arguments
+    # @return [ESP::Report]
+    # @raise [ArgumentError] if +team_id: Integer+ is not supplied.
     def self.create(arguments = {})
       fail ArgumentError, "You must supply a team id." unless arguments.with_indifferent_access[:team_id].present?
       super
@@ -50,16 +59,12 @@ module ESP
 
     # Returns a paginated collection of alerts for the report
     #
-    # ==== Parameters
-    #
-    # +arguments+ | Not Required | An optional hash of search criteria to filter the returned collection
-    #
-    # ===== Valid Arguments
-    #
-    # See {API documentation}[http://api-docs.evident.io?ruby#alert-attributes] for valid arguments
-    #
-    # ==== Example
-    #
+    # @overload alerts()
+    # @overload alerts(arguments = {})
+    # @param arguments [Hash] An optional hash of search criteria to filter the returned collection.
+    #   See {API documentation}[http://api-docs.evident.io?ruby#alert-attributes] for valid arguments.
+    # @return [ActiveResource::PaginatedCollection<ESP::Alert>]
+    # @example
     #   report = ESP::Report.find(345)
     #   alerts = report.alerts(status_eq: 'fail', signature_risk_level_in: ['High'])
     def alerts(arguments = {})
@@ -67,46 +72,43 @@ module ESP
     end
 
     # Returns the stats for this report
+    #
+    # @return [ActiveResource::PaginatedCollection<ESP::Stat>]
     def stat
       ESP::Stat.for_report(id)
     end
 
-    # :singleton-method: where
-    # Return a paginated Report list filtered by search parameters
-    #
-    # ==== Parameters
+    # @!method self.where(clauses = {})
+    #   Return a paginated Report list filtered by search parameters
     #
-    # +clauses+ | Hash of attributes with appended predicates to search, sort and include.
+    #   *call-seq* -> +super.where(clauses = {})+
     #
-    # ===== Valid Clauses
-    #
-    # See {API documentation}[http://api-docs.evident.io?ruby#report-attributes] for valid arguments
-    #
-    # :call-seq:
-    #  where(clauses = {})
+    #   @param clauses [Hash] Hash of attributes with appended predicates to search, sort and include.
+    #     See {API documentation}[http://api-docs.evident.io?ruby#report-attributes] for valid arguments
+    #   @return [ActiveResource::PaginatedCollection<ESP::Report>]
 
-    ##
-    # :singleton-method: find
-    # Find a Report by id
-    #
-    # ==== Parameter
+    # @!method self.find(id)
+    #   Find a Report by id
     #
-    # +id+ | Required | The ID of the report to retrieve
+    #   *call-seq* -> +super.find(id, options = {})+
     #
-    # +options+ | Optional | A hash of options
+    #   @overload find(id)
+    #   @overload find(id, options = {})
+    #     @param options [Hash] Optional 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#report-attributes] for valid arguments
     #
-    # See {API documentation}[http://api-docs.evident.io?ruby#report-attributes] for valid arguments
-    #
-    # :call-seq:
-    #  find(id, options = {})
+    #   @param id [Integer, Numeric, #to_i] Required ID of the report to retrieve.
+    #   @return [ESP::Report]
 
-    # :singleton-method: all
-    # Return a paginated Report list
+    # @!method self.all
+    #   Return a paginated Report list
+    #
+    #   @return [ActiveResource::PaginatedCollection<ESP::Report>]
   end
 end

data/lib/esp/resources/reports/export/integration.rb

@@ -3,35 +3,44 @@ module ESP
     module Export
       class Integration < ESP::Resource
         self.prefix += "reports/export/"
-        # Not Implemented. You cannot search for Reports::Export::Integration.
+
+        # @!method self.create(attributes = {})
+        #   Enqueue reports to be exported to the given integration
+        #   Returns a Report::Export::Integration object if successful
+        #
+        #   If not successful, returns a Report::Export::Integration object with the errors object populated.
+        #
+        #   @param attributes [Hash] See {API documentation}[http://api-docs.evident.io?ruby#report-export] for valid arguments
+        #   @return [ESP::Report::Export::Integration]
+
+        # Not Implemented. You cannot search for Report::Export::Integration.
+        #
+        # @return [void]
         def self.where(*)
           fail ESP::NotImplementedError
         end
 
-        # Not Implemented. You cannot search for Reports::Export::Integration.
+        # Not Implemented. You cannot search for Report::Export::Integration.
+        #
+        # @return [void]
         def self.find(*)
           fail ESP::NotImplementedError
         end
 
-        # Not Implemented. You cannot update a Reports::Export::Integration.
+        # Not Implemented. You cannot update a Report::Export::Integration.
+        #
+        # @return [void]
         def update
           fail ESP::NotImplementedError
         end
 
-        # Not Implemented. You cannot destroy a Reports::Export::Integration.
+        # Not Implemented. You cannot destroy a Report::Export::Integration.
+        #
+        # @return [void]
         def destroy
           fail ESP::NotImplementedError
         end
 
-        # :singleton-method: create
-        # Enqueue reports to be exported to the given integration
-        # Returns a Report::Export::Integration object if successful
-        # ==== Attribute
-        #
-        # See {API documentation}[http://api-docs.evident.io?ruby#report-export] for valid arguments
-        #
-        # If not successful, returns a Report::Export::Integration object with the errors object populated.
-
         protected
 
         # A success message gets returned, so just return the response instead of parsing for attributes

data/lib/esp/resources/resource.rb

@@ -1,5 +1,6 @@
 module ESP
-  class Resource < ActiveResource::Base # :nodoc:
+  # @private
+  class Resource < ActiveResource::Base
     self.site = ESP.site
     self.proxy = ESP.http_proxy
     self.format = ActiveResource::Formats::JsonAPIFormat
@@ -16,7 +17,7 @@ module ESP
     def serializable_hash(*)
       h = attributes.extract!('included')
       h['data'] = { 'type' => self.class.to_s.underscore.sub('esp/', '').pluralize,
-                    'attributes' => attributes.except('id', 'type', 'created_at', 'updated_at', 'relationships') }
+                    'attributes' => changed_attributes.except('id', 'type', 'created_at', 'updated_at', 'relationships') }
       h['data']['id'] = id if id.present?
       h
     end
@@ -63,7 +64,7 @@ module ESP
       # Need to set from so paginated collection can use it for page calls.
       object.tap do |collection|
         collection.from = options['from']
-        collection.original_params = options['params']
+        collection.original_params = options.fetch('params', {})
       end
     end
 

data/lib/esp/resources/scan_interval.rb

@@ -1,21 +1,28 @@
 module ESP
   class ScanInterval < ESP::Resource
-    ##
     # The external account the scan interval belongs to
+    #
+    # @return [ESP::ExternalAccount]
     belongs_to :external_account, class_name: 'ESP::ExternalAccount'
 
-    ##
     # The service the scan interval belongs to
+    #
+    # @return [ESP::Service]
     belongs_to :service, class_name: 'ESP::Service'
 
     # Find a Scan Interval by id
     #
-    # ==== Parameter
-    #
-    # +id+ | Required | The ID of the scan interval to retrieve
+    # *call-seq* -> +super.find(id)+
     #
-    # :call-seq:
-    #  find(id)
+    # @overload find(id)
+    #   @param id [Integer, Numeric, #to_i] Required ID of the scan interval to retrieve.
+    # @overload find(scope, options)
+    #   *call-seq* -> +super.all(options)+
+    #   @api private
+    #   @param scope [Object] *Example:* +:all+
+    #   @param options [Hash] +params: { external_account_id: Interger }+
+    #   @raise [ArgumentError] if no +external_account_id+ is supplied.
+    # @return [ESP::ScanInterval]
     def self.find(*arguments)
       scope = arguments.slice!(0)
       options = (arguments.slice!(0) || {}).with_indifferent_access
@@ -29,13 +36,12 @@ module ESP
     end
 
     # Returns a collection of scan_intervals for the given external_account_id
-    # Convenience method to use instead of ::find since a external_account_id is required to return alerts.
-    #
-    # ==== Parameters
-    #
-    # +external_account_id+ | Required | The ID of the external account to retrieve scan intervals for
+    # Convenience method to use instead of {.find} since an external_account_id is required to return alerts.
     #
-    # ==== Example
+    # @param external_account_id [Integer, Numeric] Required ID of the external account to retrieve scan intervals for.
+    # @return [ActiveResource::PaginatedCollection<ESP::ScanInterval>]
+    # @raise [ArgumentError] if no +external_account_id+ is supplied.
+    # @example
     #   alerts = ESP::ScanInterval.for_external_account(54)
     def self.for_external_account(external_account_id = nil)
       fail ArgumentError, "You must supply an external account id." unless external_account_id.present?

data/lib/esp/resources/service.rb

@@ -1,36 +1,42 @@
 module ESP
   class Service < ESP::Resource
-    ##
     # The collection of signatures associated with this service.
+    #
+    # @return [ActiveResource::PaginatedCollection<ESP::Signature>]
     has_many :signatures, class_name: 'ESP::Signature'
 
     # Not Implemented. You cannot search for a Tag.
+    #
+    # @return [void]
     def self.where(*)
       fail ESP::NotImplementedError
     end
 
     # Not Implemented. You cannot create or update a Service.
+    #
+    # @return [void]
     def save
       fail ESP::NotImplementedError
     end
 
     # Not Implemented. You cannot destroy a Service.
+    #
+    # @return [void]
     def destroy
       fail ESP::NotImplementedError
     end
 
-    ##
-    # :singleton-method: find
-    # Find a Service by id
-    #
-    # ==== Parameter
+    # @!method self.find(id)
+    #   Find a Service by id
     #
-    # +id+ | Required | The ID of the service to retrieve
+    #   *call-seq* -> +super.find(id)+
     #
-    # :call-seq:
-    #  find(id)
+    #   @param id [Integer, Numeric, #to_i] Required ID of the service to retrieve.
+    #   @return [ESP::Service]
 
-    # :singleton-method: all
-    # Return a paginated Service list
+    # @!method self.all
+    #   Return a paginated Service list
+    #
+    #   @return [ActiveResource::PaginatedCollection<ESP::Service>]
   end
 end