esp_sdk 2.4.0 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: eb2adf95c6d86093eac45d8f35aba16bfc4b92fd
-  data.tar.gz: 866a1a8d25f13d6c948cf2c5763d32733c488706
+  metadata.gz: 985f05618a6621f6fd81b455b13b532c91712638
+  data.tar.gz: 773b7274d4889449a4264f8f19e869f4b9830798
 SHA512:
-  metadata.gz: 8c956e5ead24371596d4b00c95d2d4a60d385a51c6ffc7fb1df4cfac3b3b73eff6ada2ee93bb36741eb54c12ee4a8c2f75d8c6d5e894b1f6b8291c063302d7e0
-  data.tar.gz: b4bde23260e83f6819e757c86bb10b720a6378895885e2d806058ae9ea68e93519a1ca1d7ff6639d8265717378c3b864268610c5be78c7db877687386f2ee3e2
+  metadata.gz: 54b0c9606230136eff0b3c463467be3f9eebf1986b4e603622c1efa59e680496769b7d086ae13913be912df2c12e7ac2f1e5352e39a1ba18628ffc4c9e36828a
+  data.tar.gz: c398c98653b66c5adac110c958580662fb1bba451fa0d8db98cc6f435e6d1ed0f5f79c594a768bee60232d9b9799eeff230c65961ab1c4cc43e2917bb344667e

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## Unreleased
 
+## 2.5.0 - 2016-07-20
+### Added
+- Add custom signature definitions and results. Code for a custom signature is now created/updated under a definition. Running a definition for an on demand test creates a result record which will have errors and alerts when completed.
+  - This is a backwards incompatible change on the API. If you need to save or run code on a custom signature, make sure to use this version or later.
+
 ## 2.4.0 - 2016-06-30
 ### Added
 - Report relationship to ExternalAccount

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    esp_sdk (2.4.0)
+    esp_sdk (2.5.0)
       activeresource (~> 4.0.0)
       api-auth (~> 2.0.0)
       rack

data/lib/esp.rb

@@ -102,11 +102,6 @@ module ESP
   autoload :Tag, File.expand_path(File.dirname(__FILE__) + '/esp/resources/tag')
   autoload :Region, File.expand_path(File.dirname(__FILE__) + '/esp/resources/region')
   autoload :Suppression, File.expand_path(File.dirname(__FILE__) + '/esp/resources/suppression')
-  class Suppression
-    autoload :UniqueIdentifier, File.expand_path(File.dirname(__FILE__) + '/esp/resources/suppression/unique_identifier')
-    autoload :Signature, File.expand_path(File.dirname(__FILE__) + '/esp/resources/suppression/signature')
-    autoload :Region, File.expand_path(File.dirname(__FILE__) + '/esp/resources/suppression/region')
-  end
   autoload :Stat, File.expand_path(File.dirname(__FILE__) + '/esp/resources/stat')
   autoload :StatCustomSignature, File.expand_path(File.dirname(__FILE__) + '/esp/resources/stat_custom_signature')
   autoload :StatSignature, File.expand_path(File.dirname(__FILE__) + '/esp/resources/stat_signature')
@@ -114,9 +109,4 @@ module ESP
   autoload :StatService, File.expand_path(File.dirname(__FILE__) + '/esp/resources/stat_service')
   autoload :ExternalAccountCreator, File.expand_path(File.dirname(__FILE__) + '/../lib/esp/external_account_creator')
   autoload :AWSClients, File.expand_path(File.dirname(__FILE__) + '/../lib/esp/aws_clients')
-  class Report
-    module Export
-      autoload :Integration, File.expand_path(File.dirname(__FILE__) + '/esp/resources/reports/export/integration')
-    end
-  end
 end

data/lib/esp/resources/custom_signature.rb

@@ -1,8 +1,12 @@
 module ESP
   class CustomSignature < ESP::Resource
+    autoload :Definition, File.expand_path(File.dirname(__FILE__) + '/custom_signature/definition')
+    autoload :Result, File.expand_path(File.dirname(__FILE__) + '/custom_signature/result')
+
     ##
     # The organization this custom signature belongs to.
     belongs_to :organization, class_name: 'ESP::Organization'
+    has_many :definitions, class_name: 'ESP::CustomSignature::Definition'
 
     ##
     # The collection of teams that belong to the custom_signature.
@@ -11,100 +15,6 @@ module ESP
       Team.where(custom_signatures_id_eq: id)
     end
 
-    # Run a custom signature that has not been saved.  Useful for debugging a custom signature.
-    # Returns a collection of alerts.
-    # Throws an error if not successful.
-    #
-    # ==== Parameters
-    #
-    # +arguments+ | Required | A hash of run arguments
-    #
-    # ===== Valid Arguments
-    #
-    # 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"
-    #   alerts = ESP::CustomSignature.run!(external_account_id: 3, regions: ['us_east_1'], language: 'ruby', signature: signature)
-    def self.run!(arguments = {})
-      result = run(arguments)
-      return result if result.is_a?(ActiveResource::Collection)
-      result.message = result.errors.full_messages.join(' ')
-      fail(ActiveResource::ResourceInvalid.new(result)) # rubocop:disable Style/RaiseArgs
-    end
-
-    # Run a custom signature that has not been saved.  Useful for debugging a custom signature.
-    # Returns a collection of alerts.
-    # If not successful, returns a CustomSignature object with the errors object populated.
-    #
-    # ==== Parameters
-    #
-    # +arguments+ | Required | A hash of run arguments
-    #
-    # ===== Valid Arguments
-    #
-    # 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"
-    #   alerts = ESP::CustomSignature.run(external_account_id: 3, regions: ['us_east_1'], language: 'ruby', signature: signature)
-    def self.run(arguments = {})
-      arguments = arguments.with_indifferent_access
-      arguments[:regions] = Array(arguments[:regions])
-      new(arguments).run
-    end
-
-    # Run this custom signature instance.
-    # Returns a collection of alerts.
-    # Throws an error if not successful.
-    #
-    # ==== Parameters
-    #
-    # +arguments+ | Required | A hash of run arguments
-    #
-    # ===== Valid Arguments
-    #
-    # See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-run-existing] for valid arguments
-    #
-    # ==== Example
-    #   custom_signature = ESP::CustomSignature.find(365)
-    #   alerts = custom_signature.run!(external_account_id: 3, regions: ['us_east_1'])
-    def run!(arguments = {})
-      result = run(arguments)
-      return result if result.is_a?(ActiveResource::Collection)
-      self.message = errors.full_messages.join(' ')
-      fail(ActiveResource::ResourceInvalid.new(self)) # rubocop:disable Style/RaiseArgs
-    end
-
-    # Run this custom signature instance.
-    # Returns a collection of alerts.
-    # If not successful, returns a CustomSignature object with the errors object populated.
-    #
-    # ==== Parameters
-    #
-    # +arguments+ | Required | A hash of run arguments
-    #
-    # ===== Valid Arguments
-    #
-    # See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-run-existing] for valid arguments
-    #
-    # ==== Example
-    #   custom_signature = ESP::CustomSignature.find(365)
-    #   alerts = custom_signature.run(external_account_id: 3, regions: ['us_east_1'])
-    def run(arguments = {})
-      arguments = arguments.with_indifferent_access
-
-      attributes['external_account_id'] ||= arguments[:external_account_id]
-      attributes['regions'] ||= Array(arguments[:regions])
-
-      response = connection.post endpoint, to_json
-      ESP::Alert.send(:instantiate_collection, self.class.format.decode(response.body))
-    rescue ActiveResource::BadRequest, ActiveResource::ResourceInvalid, ActiveResource::ResourceNotFound => error
-      load_remote_errors(error, true)
-      self.code = error.response.code
-      self
-    end
-
     # Create a suppression for this custom signature.
     #
     # ==== Parameter
@@ -175,8 +85,7 @@ module ESP
     #
     # ==== 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"
-    #  custom_signature = ESP::CustomSignature.create(signature: signature, description: "A test custom signature.", identifier: "AWS::IAM::001", language: "ruby", name: "Test Signature", risk_level: "Medium")
+    #  custom_signature = ESP::CustomSignature.create(description: "A test custom signature.", identifier: "AWS::IAM::001", name: "Test Signature", risk_level: "Medium")
 
     # :method: save
     # Create or update a CustomSignature
@@ -187,21 +96,10 @@ module ESP
     #
     # ==== 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"
-    #  custom_signature = ESP::CustomSignature.new(signature: signature, description: "A test custom signature.", identifier: "AWS::IAM::001", language: "ruby", name: "Test Signature", risk_level: "Medium")
+    #  custom_signature = ESP::CustomSignature.new(description: "A test custom signature.", identifier: "AWS::IAM::001", name: "Test Signature", risk_level: "Medium")
     #  custom_signature.save
 
     # :method: destroy
     # Delete a CustomSignature
-
-    private
-
-    def endpoint
-      if id.present?
-        "#{self.class.prefix}custom_signatures/#{id}/run.json"
-      else
-        "#{self.class.prefix}custom_signatures/run.json"
-      end
-    end
   end
 end

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

@@ -0,0 +1,100 @@
+module ESP
+  class CustomSignature
+    class Definition < ESP::Resource
+      self.prefix += "custom_signature_"
+
+      belongs_to :custom_signature, class_name: 'ESP::CustomSignature'
+      has_many :results, class_name: 'ESP::CustomSignature::Result'
+
+      def activate
+        patch(:activate).tap do |response|
+          load_attributes_from_response(response)
+        end
+      rescue ActiveResource::BadRequest, ActiveResource::ResourceInvalid, ActiveResource::UnauthorizedAccess => error
+        load_remote_errors(error, true)
+        self.code = error.response.code
+        false
+      end
+
+      def archive
+        patch(:archive).tap do |response|
+          load_attributes_from_response(response)
+        end
+      rescue ActiveResource::BadRequest, ActiveResource::ResourceInvalid, ActiveResource::UnauthorizedAccess => error
+        load_remote_errors(error, true)
+        self.code = error.response.code
+        false
+      end
+
+      # :singleton-method: where
+      # Return a paginated CustomSignature::Definition 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-definition-attributes] for valid arguments
+      #
+      # :call-seq:
+      #  where(clauses = {})
+
+      ##
+      # :singleton-method: find
+      # Find a CustomSignature::Definition by id
+      #
+      # ==== Parameter
+      #
+      # +id+ | Required | The ID of the custom signature definition 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-definition-attributes] for valid arguments
+      #
+      # :call-seq:
+      #  find(id, options = {})
+
+      # :singleton-method: all
+      # Return a paginated CustomSignature::Definition list
+
+      # :singleton-method: create
+      # Create a CustomSignature::Definition
+      # :call-seq:
+      #   create(attributes={})
+      #
+      # ==== 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
+      #
+      # ==== Example
+      #
+      #  definition = ESP::CustomSignature::Definition.create(custom_signature_id: 1)
+
+      # :method: save
+      # Create or update a CustomSignature::Definition
+      #
+      # ===== Valid Attributes
+      #
+      # See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-definition-create] for valid arguments
+      #
+      # ==== Example
+      #
+      #  definition = ESP::CustomSignature::Definition.new(custom_signature_id: 1)
+      #  definition.save
+
+      # :method: destroy
+      # Delete a CustomSignature::Definition
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+module ESP
+  class CustomSignature
+    class Result < ESP::Resource
+      autoload :Alert, File.expand_path(File.dirname(__FILE__) + '/result/alert')
+
+      self.prefix += "custom_signature_"
+
+      belongs_to :definition, class_name: 'ESP::CustomSignature::Definition', foreign_key: :definition_id
+      belongs_to :region, class_name: 'ESP::Region'
+      belongs_to :external_account, class_name: 'ESP::ExternalAccount'
+
+      def alerts
+        return attributes['alerts'] if attributes['alerts'].present?
+        CustomSignature::Result::Alert.for_result(id)
+      end
+
+      # Not Implemented. You cannot update a CustomSignature::Result.
+      def update
+        fail ESP::NotImplementedError
+      end
+
+      # Not Implemented. You cannot destroy a CustomSignature::Result.
+      def destroy
+        fail ESP::NotImplementedError
+      end
+
+      # :singleton-method: where
+      # Return a paginated CustomSignature::Result 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-result-attributes] for valid arguments
+      #
+      # :call-seq:
+      #  where(clauses = {})
+
+      ##
+      # :singleton-method: find
+      # Find a CustomSignature::Result by id
+      #
+      # ==== Parameter
+      #
+      # +id+ | Required | The ID of the custom signature result 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-result-attributes] for valid arguments
+      #
+      # :call-seq:
+      #  find(id, options = {})
+
+      # :singleton-method: all
+      # Return a paginated CustomSignature::Result list
+
+      # :singleton-method: create
+      # Create a CustomSignature::Result
+      # :call-seq:
+      #   create(attributes={})
+      #
+      # ==== Parameter
+      #
+      # +attributes+ | Required | A hash of custom signature result attributes
+      #
+      # ===== Valid Attributes
+      #
+      # See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-result-create] 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"
+      #  result = ESP::CustomSignature::Result.create(signature: signature, language: "ruby", region_id: 1, external_account_id: 1)
+
+      # :method: save
+      # Create or update a CustomSignature::Result
+      #
+      # ===== Valid Attributes
+      #
+      # See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-result-create] 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"
+      #  result = ESP::CustomSignature::Result.new(signature: signature, language: "ruby", region_id: 1, external_account_id: 1)
+      #  result.save
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+module ESP
+  class CustomSignature
+    class Result
+      class Alert < ESP::Resource
+        belongs_to :region, class_name: 'ESP::Region'
+        belongs_to :external_account, class_name: 'ESP::ExternalAccount'
+        belongs_to :custom_signature, class_name: 'ESP::CustomSignature'
+
+        # 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
+        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
+          find_every(from: "#{prefix}custom_signature_results/#{custom_signature_result_id}/alerts.json")
+        end
+
+        # Not Implemented. You cannot search for CustomSignature::Result::Alert.
+        #
+        # Regular ARELlike methods are disabled.
+        def self.find(*)
+          fail ESP::NotImplementedError, 'Regular ARELlike methods are disabled. Use the .for_result method.'
+        end
+
+        # Not Implemented. You cannot search for CustomSignature::Result::Alert.
+        #
+        # Regular ARELlike methods are disabled.
+        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.
+        def create
+          fail ESP::NotImplementedError
+        end
+
+        # Not Implemented. You cannot update a CustomSignature::Result::Alert.
+        def update
+          fail ESP::NotImplementedError
+        end
+
+        # Not Implemented. You cannot destroy a CustomSignature::Result::Alert.
+        def destroy
+          fail ESP::NotImplementedError
+        end
+      end
+    end
+  end
+end