esp_sdk 2.0.0 → 2.1.0

data/lib/esp/commands/console.rb

@@ -0,0 +1,68 @@
+# https://www.fedux.org/articles/2015/08/26/creating-an-irb-based-repl-console-for-your-project.html
+require 'optparse'
+require 'irb'
+
+ARGV.clone.options do |opts|
+  opts.banner = "Usage: esp console"
+
+  opts.separator ""
+
+  opts.on("-h", "--help",
+          "Show this help message.") do
+    puts opts # rubocop:disable Rails/Output
+    exit
+  end
+
+  opts.separator ""
+  opts.separator "An IRB console you can use if not using it in a Rails app"
+  opts.separator ""
+
+  opts.parse!
+end
+
+module ESP
+  class Console
+    def start # rubocop:disable Metrics/MethodLength
+      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

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

@@ -1,6 +1,6 @@
 require 'active_support/json'
 
-module ActiveResource
+module ActiveResource # :nodoc: all
   class ConnectionError
     def initialize(response)
       @response = if response.respond_to?(:response)
@@ -20,7 +20,7 @@ module ActiveResource
     end
   end
 
-  module Formats
+  module Formats # :nodoc: all
     module JsonAPIFormat
       module_function
 
@@ -114,11 +114,19 @@ module ActiveResource
         return if included.blank?
         object[assoc] = case data
                         when Array
-                          included.select { |i| data.include?(parse_object!(i).slice('type', 'id')) }
+                          merge_nested_included_objects(object, data, included)
                         when Hash
-                          included.detect { |i| data == parse_object!(i).slice('type', 'id') }
+                          merge_nested_included_objects(object, [data], included).first
                         end
       end
+
+      def self.merge_nested_included_objects(object, data, included)
+        assocs = included.select { |i| data.include?((i.slice('type', 'id'))) }
+        # Remove the object from the included array to prevent an infinite loop if one of it's associations relates back to itself.
+        assoc_included = included.dup
+        assoc_included.delete(object)
+        assocs.map { |i| parse_object!(i, assoc_included) }
+      end
     end
   end
 end

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

@@ -26,7 +26,7 @@ module ActiveResource
     #   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
+      previous_page? ? resource_class.where(original_params.merge(from: from, page: { number: 1 })) : self
     end
 
     # Updates the existing PaginatedCollection object with the first page of data when not on the first page.
@@ -49,7 +49,7 @@ module ActiveResource
     #   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
+      previous_page? ? resource_class.where(original_params.merge(previous_page_params.merge(from: from))) : self
     end
 
     # Updates the existing PaginatedCollection object with the previous page of data when not on the first page.
@@ -72,7 +72,7 @@ module ActiveResource
     #   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
+      next_page? ? resource_class.where(original_params.merge(next_page_params.merge(from: from))) : self
     end
 
     # Updates the existing PaginatedCollection object with the last page of data when not on the last page.
@@ -95,7 +95,7 @@ module ActiveResource
     #   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
+      !last_page? ? resource_class.where(original_params.merge(last_page_params.merge(from: from))) : self
     end
 
     # Updates the existing PaginatedCollection object with the last page of data when not on the last page.
@@ -125,7 +125,7 @@ module ActiveResource
       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
+      page_number.to_i != current_page_number.to_i ? resource_class.where(original_params.merge(from: from, 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+.

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

@@ -1,4 +1,4 @@
-module ActiveResource
+module ActiveResource # :nodoc: all
   module Validations
     # Loads the set of remote errors into the object's Errors based on the
     # content-type of the error-block received.

data/lib/esp/external_account_creator.rb

@@ -0,0 +1,77 @@
+module ESP # :nodoc: all
+  class AddExternalAccountError < StandardError
+    EXIT_CODES = {
+      '12 characters'          => 98,
+      'not a number'           => 97,
+      'organization not found' => 96,
+      'sub organization'       => 95,
+      'team'                   => 94,
+      'external account'       => 93
+    }.freeze
+
+    def initialize(message = nil)
+      super
+    end
+
+    def exit_code
+      EXIT_CODES.detect { |key, _code| message =~ /#{key}/i }.last
+    rescue StandardError
+      1
+    end
+  end
+
+  class ExternalAccountCreator
+    attr_reader :aws
+
+    def initialize
+      @aws = AWSClients.new
+    end
+
+    def create
+      fail ESP::AddExternalAccountError, aws.errors.full_messages.join(', ') unless aws.valid?
+
+      puts "adding AWS account #{aws.owner_id} to ESP as #{team_name}" # rubocop:disable Rails/Output
+      aws_role_object = aws.create_and_attach_role!(external_account_id)
+      sleep 10
+
+      puts "aws_role_arn = #{aws_role_object.role.arn}, external_id = #{external_account_id}, nickname = #{team_name}, esp_suborg_id = #{sub_organization.id}, esp_team_id = #{team.id}" # rubocop:disable Rails/Output
+      external_account = ESP::ExternalAccount.create(arn: aws_role_object.role.arn, external_id: external_account_id, name: team_name, sub_organization_id: sub_organization.id, team_id: team.id)
+      fail ESP::AddExternalAccountError, "On External Account: #{external_account.errors.full_messages.join(', ')}" unless external_account.errors.blank?
+      external_account
+    end
+
+    private
+
+    def external_account_id
+      @external_id ||= ESP::ExternalAccount.new.generate_external_id
+    end
+
+    def organization
+      @organization ||= ESP::Organization.last
+      fail ESP::AddExternalAccountError, "Organization not found" if @organization.blank?
+      @organization
+    end
+
+    def sub_organization
+      @sub_org ||= begin
+        sub_org = ESP::SubOrganization.where(name_eq: 'AutoCreate').first
+        sub_org || ESP::SubOrganization.create(name: "AutoCreate", organization_id: organization.id)
+      end
+      fail ESP::AddExternalAccountError, "On Sub Organization: #{@sub_org.errors.full_messages.first}" unless @sub_org.errors.blank?
+      @sub_org
+    end
+
+    def team_name
+      "#{sub_organization.name} #{aws.owner_id}"
+    end
+
+    def team
+      @team ||= begin
+        team = ESP::Team.where(name: team_name, sub_organization_id: sub_organization.id).first
+        team || ESP::Team.create(name: team_name, sub_organization_id: sub_organization.id)
+      end
+      fail ESP::AddExternalAccountError, "On Team: #{@team.errors.full_messages.first}" unless @team.errors.blank?
+      @team
+    end
+  end
+end

data/lib/esp/resources/alert.rb

@@ -45,61 +45,57 @@ module ESP
     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
+    # +clauses+ | Required | Hash of attributes with appended predicates to search, sort and include.
     #
-    # +arguments+ | Not Required | An optional hash of search criteria to filter the returned collection
+    # ===== Valid Clauses
     #
-    # ===== Valid Arguments
+    # See {API documentation}[http://api-docs.evident.io?ruby#searching-alerts] for 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
+    # ==== 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
+      return super(clauses) if clauses[:from].present?
+      from = for_report(clauses.delete(:report_id))
+      super clauses.merge(from: from)
+    end
+
+    # Find an Alert by id
     #
-    # +team_id+ | Not Required | Return only alerts for the given team.
+    # ==== Parameter
     #
-    # +external_account_id+ | Not Required | Return only alerts for the given external id.
+    # +id+ | Required | The ID of the alert to retrieve
     #
-    # +service_id+ | Not Required | Return only alerts on signatures with the given service.
+    # +options+ | Optional | A hash of options
     #
-    # +signature_severity+ | Not Required | Return only alerts for signatures with the given risk_level.  Valid values are Low, Medium, High
+    # ===== Valid Options
     #
-    # +signature_name+ | Not Required | Return only alerts for signatures with the given name.
+    # +include+ | The list of associated objects to return on the initial request.
     #
-    # +resource+ | Not Required | Return only alerts for the given resource or tag.
+    # ===== Valid Includable Associations
     #
-    # +signature_identifier+ | Not Required | Return only alerts for signatures with the given identifier.
+    # See {API documentation}[http://api-docs.evident.io?ruby#searching-alerts] for valid arguments
     #
     # ==== 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
+    # alert = ESP::Alert.find(1, include: 'tags,external_account.team')
     #
     # :call-seq:
-    #  find(id)
+    #  find(id, options = {})
     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)
+      params = options.fetch(:params, {})
+      from = for_report(params.delete(:report_id))
+      all(from: "#{from}.json", params: params)
+    end
+
+    def self.for_report(report_id) # :nodoc:
+      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.

data/lib/esp/resources/cloud_trail_event.rb

@@ -1,5 +1,10 @@
 module ESP
   class CloudTrailEvent < ESP::Resource
+    # Not Implemented. You cannot search for a CloudTrailEvent.
+    def self.where(*)
+      fail ESP::NotImplementedError
+    end
+
     # Not Implemented. You cannot create or update a CloudTrailEvent.
     def save
       fail ESP::NotImplementedError

data/lib/esp/resources/contact_request.rb

@@ -6,6 +6,11 @@ module ESP
       fail ESP::NotImplementedError
     end
 
+    # Not Implemented. You cannot search for ContactRequest.
+    def self.where(*)
+      fail ESP::NotImplementedError
+    end
+
     # Not Implemented. You cannot update a ContactRequest.
     def update
       fail ESP::NotImplementedError
@@ -25,11 +30,7 @@ module ESP
     #
     # ===== Valid Attributes
     #
-    # +title+ | Required | Subject of your message
-    #
-    # +description+ | Required | Body of your message
-    #
-    # +request_type+ | Required | Type of contact request. Supported values are `support` for support requests and `feature` for a feature request
+    # See {API documentation}[http://api-docs.evident.io?ruby#contact-request-create] for valid arguments
     #
     #
     # :call-seq:

data/lib/esp/resources/custom_signature.rb

@@ -14,13 +14,7 @@ module ESP
     #
     # ===== Valid Arguments
     #
-    # +external_account_id+ | Required | The ID of the external account to run this custom signature against
-    #
-    # +signature+ | Required | The code for this custom signature
-    #
-    # +language+ | Required | The language of the custom signature. Possible values are `ruby` or `javascript`
-    #
-    # +regions+ | Required | Array of region names to run this custom signature against
+    # See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-run-new] for valid arguments
     #
     # ==== Example
     #   signature = "# Demo Ruby Signature\r\nconfigure do |c|\r\n  # Set regions to run in. Remove this line to run in all regions.\r\n  c.valid_regions     = [:us_east_1]\r\n  # Override region to display as global. Useful when checking resources\r\n  # like IAM that do not have a specific region.\r\n  c.display_as        = :global\r\n  # deep_inspection works with set_data to automically collect\r\n  # data fields for each alert. Not required.\r\n  c.deep_inspection   = [:users]\r\nend\r\n\r\n# Required perform method\r\ndef perform(aws)\r\n  list_users = aws.iam.list_users\r\n  count = list_users[:users].count\r\n\r\n  # Set data for deep_inspection to use\r\n  set_data(list_users)\r\n\r\n  if count == 0\r\n    fail(user_count: count, condition: 'count == 0')\r\n  else\r\n    pass(user_count: count, condition: 'count >= 1')\r\n  end\r\nend\r\n"
@@ -42,13 +36,7 @@ module ESP
     #
     # ===== Valid Arguments
     #
-    # +external_account_id+ | Required | The ID of the external account to run this custom signature against
-    #
-    # +signature+ | Required | The code for this custom signature
-    #
-    # +language+ | Required | The language of the custom signature. Possible values are `ruby` or `javascript`
-    #
-    # +regions+ | Required | Array of region names to run this custom signature against
+    # See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-run-new] for valid arguments
     #
     # ==== Example
     #   signature = "# Demo Ruby Signature\r\nconfigure do |c|\r\n  # Set regions to run in. Remove this line to run in all regions.\r\n  c.valid_regions     = [:us_east_1]\r\n  # Override region to display as global. Useful when checking resources\r\n  # like IAM that do not have a specific region.\r\n  c.display_as        = :global\r\n  # deep_inspection works with set_data to automically collect\r\n  # data fields for each alert. Not required.\r\n  c.deep_inspection   = [:users]\r\nend\r\n\r\n# Required perform method\r\ndef perform(aws)\r\n  list_users = aws.iam.list_users\r\n  count = list_users[:users].count\r\n\r\n  # Set data for deep_inspection to use\r\n  set_data(list_users)\r\n\r\n  if count == 0\r\n    fail(user_count: count, condition: 'count == 0')\r\n  else\r\n    pass(user_count: count, condition: 'count >= 1')\r\n  end\r\nend\r\n"
@@ -69,9 +57,7 @@ module ESP
     #
     # ===== Valid Arguments
     #
-    # +external_account_id+ | Required | The ID of the external account to run this custom signature against
-    #
-    # +regions+ | Required | Array of region names to run this custom signature against
+    # See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-run-existing] for valid arguments
     #
     # ==== Example
     #   custom_signature = ESP::CustomSignature.find(365)
@@ -93,9 +79,7 @@ module ESP
     #
     # ===== Valid Arguments
     #
-    # +external_account_id+ | Required | The ID of the external account to run this custom signature against
-    #
-    # +regions+ | Required | Array of region names to run this custom signature against
+    # See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-run-existing] for valid arguments
     #
     # ==== Example
     #   custom_signature = ESP::CustomSignature.find(365)
@@ -122,11 +106,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')
@@ -135,6 +115,20 @@ module ESP
       ESP::Suppression::Signature.create(custom_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 CustomSignature 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#custom-signature-attributes] for valid arguments
+    #
+    # :call-seq:
+    #  where(clauses = {})
+
     ##
     # :singleton-method: find
     # Find a CustomSignature by id
@@ -143,8 +137,18 @@ module ESP
     #
     # +id+ | Required | The ID of the custom 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#custom-signature-attributes] for valid arguments
+    #
     # :call-seq:
-    #  find(id)
+    #  find(id, options = {})
 
     # :singleton-method: all
     # Return a paginated CustomSignature list
@@ -160,21 +164,7 @@ module ESP
     #
     # ===== Valid Attributes
     #
-    # +active+ | Not Required | Flag that determines if this custom signature should run on reports
-    #
-    # +description+ | Not Required | The description of the custom signature that is displayed on alerts
-    #
-    # +identifier+ | Required | The identifier to use for the custom signature. Common format is AWS:<Service>-<Number> such as AWS:IAM-001
-    #
-    # +language+ | Required | The language of the custom signature. Possible values are `ruby` or `javascript`
-    #
-    # +name+ | Required | The name of the custom signature
-    #
-    # +resolution+ | Not Required | Details for how to resolve this custom signature that is displayed on alerts
-    #
-    # +risk_level+ | Required | The risk-level of the problem identified by the custom signature
-    #
-    # +signature+ | Required | The code for this custom signature
+    # See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-create] for valid arguments
     #
     # ==== Example
     #
@@ -186,21 +176,7 @@ module ESP
     #
     # ===== Valid Attributes
     #
-    # +active+ | Not Required | Flag that determines if this custom signature should run on reports
-    #
-    # +description+ | Not Required | The description of the custom signature that is displayed on alerts
-    #
-    # +identifier+ | Required | The identifier to use for the custom signature. Common format is AWS:<Service>-<Number> such as AWS:IAM-001
-    #
-    # +language+ | Required | The language of the custom signature. Possible values are `ruby` or `javascript`
-    #
-    # +name+ | Required | The name of the custom signature
-    #
-    # +resolution+ | Not Required | Details for how to resolve this custom signature that is displayed on alerts
-    #
-    # +risk_level+ | Required | The risk-level of the problem identified by the custom signature
-    #
-    # +signature+ | Required | The code for this custom signature
+    # See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-create] for valid arguments
     #
     # ==== Example
     #

data/lib/esp/resources/dashboard.rb

@@ -4,7 +4,14 @@ module ESP
     #
     # Regular ARELlike methods are disabled.
     def self.find(*)
-      fail ESP::NotImplementedError, 'Regular ARELlike methods are disabled.  Use either the .recent method.'
+      fail ESP::NotImplementedError, 'Regular ARELlike methods are disabled.  Use the .recent method.'
+    end
+
+    # Not Implemented. You cannot search for Suppression::Region.
+    #
+    # Regular ARELlike methods are disabled.
+    def self.where(*)
+      fail ESP::NotImplementedError, 'Regular ARELlike methods are disabled.  Use the .recent method.'
     end
 
     # Not Implemented. You cannot create or update a Dashboard.

data/lib/esp/resources/external_account.rb

@@ -24,6 +24,20 @@ module ESP
       super
     end
 
+    # :singleton-method: where
+    # Return a paginated ExternalAccount 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#external-account-attributes] for valid arguments
+    #
+    # :call-seq:
+    #  where(clauses = {})
+
     ##
     # :singleton-method: find
     # Find an ExternalAccount by id
@@ -32,8 +46,18 @@ module ESP
     #
     # +id+ | Required | The ID of the external account 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#external-account-attributes] for valid arguments
+    #
     # :call-seq:
-    #  find(id)
+    #  find(id, options = {})
 
     # :singleton-method: all
     # Return a paginated CustomSignature list
@@ -49,15 +73,7 @@ module ESP
     #
     # ===== Valid Attributes
     #
-    # +arn+ | Required | Amazon Resource Name for the IAM role
-    #
-    # +external_id+ | Required | External identifier set on the role.  This will be set by calling #generate_external_id if not already set.
-    #
-    # +name+ | Not Required |  The name for this external account
-    #
-    # +sub_organization_id+ | Required | The ID of the sub organization the external account will belong to
-    #
-    # +team_id+ | Required | The ID of the team the external account will belong to
+    # See {API documentation}[http://api-docs.evident.io?ruby#external-account-create] for valid arguments
     #
     # ==== Example
     #
@@ -68,15 +84,7 @@ module ESP
     #
     # ===== Valid Attributes
     #
-    # +arn+ | Required | Amazon Resource Name for the IAM role
-    #
-    # +external_id+ | Required | External identifier set on the role.  This will be set by calling #generate_external_id if not already set.
-    #
-    # +name+ | Not Required |  The name for this external account
-    #
-    # +sub_organization_id+ | Required | The ID of the sub organization the external account will belong to
-    #
-    # +team_id+ | Required | The ID of the team the external account will belong to
+    # See {API documentation}[http://api-docs.evident.io?ruby#external-account-create] for valid arguments
     #
     # ==== Example
     #

data/lib/esp/resources/organization.rb

@@ -34,6 +34,20 @@ module ESP
       fail ESP::NotImplementedError
     end
 
+    # :singleton-method: where
+    # Return a paginated Organization 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#organization-attributes] for valid arguments
+    #
+    # :call-seq:
+    #  where(clauses = {})
+
     ##
     # :singleton-method: find
     # Find a Organization by id
@@ -42,8 +56,18 @@ module ESP
     #
     # +id+ | Required | The ID of the 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#organization-attributes] for valid arguments
+    #
     # :call-seq:
-    #  find(id)
+    #  find(id, options = {})
 
     # :singleton-method: all
     # Return a paginated Organization list
@@ -54,8 +78,8 @@ module ESP
     # :method: save
     # Update an Organization.
     #
-    # ==== Valid Attributes
+    # ===== Valid Attributes
     #
-    # +name+ | Not Required | The new name of the organization
+    # See {API documentation}[http://api-docs.evident.io?ruby#organization-update] for valid arguments
   end
 end