contrast-agent 6.0.0 → 6.1.0

data/lib/contrast/agent/telemetry/events/exceptions/telemetry_exception_message.rb

@@ -3,94 +3,112 @@
 
 require_relative 'telemetry_exception_base'
 require_relative 'telemetry_exception_message_exception'
+require 'contrast/utils/telemetry_identifier'
 
 module Contrast
   module Agent
-    # This class will hold the all the information for the specific exceptions
-    # and will be passed in the the event to be sent to TS
-    class TelemetryExceptionMessage < Contrast::Agent::TelemetryExceptionBase
-      VALIDATIONS = {
-          instance: { required: true, range: 12..64 },
-          tags: { required: true, range: 1..512 },
-          logger: { required: false, range: 1..128 },
-          message: { required: false, range: 1..512 },
-          exceptions: { required: true, range: 1..512, class: Contrast::Agent::TelemetryExceptionMessageException }
-      }.cs__freeze
+    module Telemetry
+      module TelemetryException
+        # This class will hold the all the information for the specific exceptions
+        # and will be passed in the the event to be sent to TS
+        class Message < Contrast::Agent::Telemetry::TelemetryException::Base
+          VALIDATIONS = {
+              instance: { required: true, range: 12..64 },
+              tags: { required: true, range: 0..512 },
+              logger: { required: false, range: 1..128 },
+              message: { required: false, range: 1..512 },
+              exceptions: {
+                  required: true,
+                  range: 1..512,
+                  class: Contrast::Agent::Telemetry::TelemetryException::MessageException
+              }
+          }.cs__freeze
 
-      # Timestamp of creation in ISO8601 format
-      # @return [Integer]
-      attr_reader :timestamp
+          # Timestamp of creation in ISO8601 format
+          # @return [Integer]
+          attr_reader :timestamp
 
-      # An Instance ID as defined in Unique Identification // Application ID
-      # @return [String]
-      attr_reader :instance
+          # An Instance ID as defined in Unique Identification // Application ID
+          # @return [String]
+          attr_reader :instance
 
-      # Tags are key-value string pairs that annotate either metrics
-      # or errors to help provide context, filtering, grouping, and deduplication.
-      # @return [Hash{String => String}]
-      attr_reader :tags
+          # Tags are key-value string pairs that annotate either metrics
+          # or errors to help provide context, filtering, grouping, and deduplication.
+          # @return [Hash{String => String}]
+          attr_reader :tags
 
-      # @return [Integer] A number of the occurrences of the exception
-      attr_accessor :occurrences
+          # @return [Integer] A number of the occurrences of the exception
+          attr_accessor :occurrences
 
-      # Array of exceptions, but in our case the Array will only include one exception
-      # @return [Array<Contrast::Agent::TelemetryExceptionMessageException>]
-      attr_reader :exceptions
+          # Array of exceptions, but in our case the Array will only include one exception
+          # @return [Array<Contrast::Agent::Telemetry::TelemetryException::MessageException>]
+          attr_reader :exceptions
 
-      # @return [String,nil] A string denoting the origin of this error.
-      attr_reader :logger
+          # @return [String,nil] A string denoting the origin of this error.
+          attr_reader :logger
 
-      # @return [String | nil] A string message to provide additional context to the errors.
-      attr_reader :message
+          # @return [String | nil] A string message to provide additional context to the errors.
+          attr_reader :message
 
-      def initialize instance, tags, exceptions
-        super()
-        @tags = tags
-        @timestamp = Time.now.iso8601
-        @instance = instance
-        @occurrences = 1
-        @exceptions = exceptions
-        validate VALIDATIONS
-      end
+          def initialize instance, tags, exceptions
+            super()
+            @tags = tags
+            @timestamp = Time.now.iso8601
+            @instance = instance
+            @occurrences = 1
+            @exceptions = exceptions
+            validate(VALIDATIONS)
+          end
 
-      # Optional parameters will be set separately from the required
-      #
-      # @param logger[String]
-      def logger= logger
-        validate_field VALIDATIONS[:logger], 'logger'
-        @logger = logger
-      end
+          # Optional parameters will be set separately from the required
+          #
+          # @param logger[String]
+          def logger= logger
+            validate_field(VALIDATIONS[:logger], 'logger')
+            @logger = logger
+          end
 
-      # Optional parameters will be set separately from the required
-      #
-      # @param message[String]
-      def message= message
-        validate_field VALIDATIONS[:message], 'message'
-        @message = message
-      end
+          # Optional parameters will be set separately from the required
+          #
+          # @param message[String]
+          def message= message
+            validate_field(VALIDATIONS[:message], 'message')
+            @message = message
+          end
 
-      # Optional parameters will be set separately from the required
-      # This method is different and is regarding the way we proceed
-      # with incrementing occurrences
-      # If we keep track of them in different places and we store that value
-      # in separated variable - we may directly re-assign occurrences=
-      # But if we are not doing that - we may on same message generated
-      # to increment occurrences from here
-      def increment_occurrences
-        @occurrences += 1
-      end
+          # Optional parameters will be set separately from the required
+          # This method is different and is regarding the way we proceed
+          # with incrementing occurrences
+          # If we keep track of them in different places and we store that value
+          # in separated variable - we may directly re-assign occurrences=
+          # But if we are not doing that - we may on same message generated
+          # to increment occurrences from here
+          def increment_occurrences
+            @occurrences += 1
+          end
+
+          def to_controlled_hash
+            super()
+            {
+                timestamp: timestamp,
+                instance: instance,
+                occurrences: occurrences,
+                tags: tags,
+                exceptions: exceptions.map(&:to_controlled_hash),
+                logger: logger,
+                message: message
+            }.compact
+          end
 
-      def to_controlled_hash
-        super()
-        {
-            timestamp: timestamp,
-            instance: instance,
-            occurrences: occurrences,
-            tags: tags,
-            exceptions: exceptions.map(&:to_controlled_hash),
-            logger: logger,
-            message: message
-        }.compact
+          class << self
+            def build tags, exceptions, logger = nil, message = nil
+              inst = new(Contrast::Utils::Telemetry::Identifier.instance_id, tags, exceptions)
+              inst.logger = logger unless logger.nil?
+              inst.message = message unless message.nil?
+              inst
+            end
+          end
+        end
       end
     end
   end

data/lib/contrast/agent/telemetry/events/exceptions/telemetry_exception_message_exception.rb

@@ -6,59 +6,77 @@ require_relative 'telemetry_exception_stack_frame'
 
 module Contrast
   module Agent
-    # This class will hold the all the information for the specific exception
-    # and will be passed in the Exception message itself
-    class TelemetryExceptionMessageException < Contrast::Agent::TelemetryExceptionBase
-      VALIDATIONS = {
-          type: { required: true, range: 1..256 },
-          module_name: { required: false, range: 1..256 },
-          value: { required: false, range: 1..256 },
-          stack_frames: { required: true, range: 1..128, class: Contrast::Agent::TelemetryExceptionStackFrame }
-      }.cs__freeze
+    module Telemetry
+      module TelemetryException
+        # This class will hold the all the information for the specific exception
+        # and will be passed in the Exception message itself
+        class MessageException < Contrast::Agent::Telemetry::TelemetryException::Base
+          VALIDATIONS = {
+              type: { required: true, range: 1..256 },
+              module_name: { required: false, range: 1..256 },
+              value: { required: false, range: 1..256 },
+              stack_frames: {
+                  required: true,
+                  range: 1..128,
+                  class: Contrast::Agent::Telemetry::TelemetryException::StackFrame
+              }
+          }.cs__freeze
 
-      # @return [String] The type of the exception itself
-      attr_reader :type
+          # @return [String] The type of the exception itself
+          attr_reader :type
 
-      # @return [Array<Contrast::Agent::TelemetryExceptionStackFrame>] stack frames for the message exception
-      attr_reader :stack_frames
+          # stack frames for the message exception
+          # @return [Array<Contrast::Agent::Telemetry::TelemetryException::StackFrame>]
+          attr_reader :stack_frames
 
-      # @return [String]
-      attr_reader :module_name
+          # @return [String]
+          attr_reader :module_name
 
-      # @return [String]
-      attr_reader :value
+          # @return [String]
+          attr_reader :value
 
-      def initialize type, stack_frame
-        super()
-        @type = type
-        @stack_frames = Array.new(1, stack_frame)
-        validate VALIDATIONS
-      end
+          def initialize type, stack_frame
+            super()
+            @type = type
+            @stack_frames = Array.new(1, stack_frame)
+            validate VALIDATIONS
+          end
 
-      # @param stack_frame [Contrast::Agent::TelemetryExceptionStackFrame]
-      def push stack_frame
-        validate_class stack_frame, Contrast::Agent::TelemetryExceptionStackFrame, 'stack_frame'
-        @stack_frames << stack_frame
-      end
+          # @param stack_frame [Contrast::Agent::Telemetry::TelemetryException::StackFrame]
+          def push stack_frame
+            validate_class(stack_frame, Contrast::Agent::Telemetry::TelemetryException::StackFrame, 'stack_frame')
+            @stack_frames << stack_frame
+          end
 
-      def module_name= module_name
-        validate_field VALIDATIONS[:module_name], 'module_name'
-        @module_name = module_name
-      end
+          def module_name= module_name
+            @module_name = module_name
+            validate_field(VALIDATIONS[:module_name], 'module_name')
+          end
 
-      def value= value
-        validate_field VALIDATIONS[:value], 'value'
-        @value = value
-      end
+          def value= value
+            @value = value
+            validate_field(VALIDATIONS[:value], 'value')
+          end
+
+          def to_controlled_hash
+            super
+            {
+                type: type,
+                module: module_name,
+                stackFrames: stack_frames.map(&:to_controlled_hash),
+                value: value
+            }.compact
+          end
 
-      def to_controlled_hash
-        super
-        {
-            type: type,
-            stack_frames: stack_frames.map(&:to_controlled_hash),
-            module_name: module_name,
-            value: value
-        }.compact
+          class << self
+            def build type, value, module_name, stackframes
+              inst = new(type, stackframes)
+              inst.module_name = module_name if module_name
+              inst.value = value
+              inst
+            end
+          end
+        end
       end
     end
   end

data/lib/contrast/agent/telemetry/events/exceptions/telemetry_exception_stack_frame.rb

@@ -5,42 +5,59 @@ require_relative 'telemetry_exception_base'
 
 module Contrast
   module Agent
-    # This class will hold the all the information for the specific exception
-    # and will be passed in the Exception message itself
-    class TelemetryExceptionStackFrame < Contrast::Agent::TelemetryExceptionBase
-      VALIDATIONS = {
-          function: { required: true, range: 1..256 },
-          type: { required: true, range: 1..256 },
-          module_name: { required: false, range: 1..256 }
-      }.cs__freeze
-
-      # @return [String] The type of the exception itself
-      attr_reader :type
-
-      # @return [String] the function of the stack trace
-      attr_reader :function
-
-      # @return [Boolean] Is it in contrast
-      attr_accessor :in_contrast
-
-      def initialize function, type
-        super()
-        @function = function
-        @type = type
-        @in_contrast = false
-        validate VALIDATIONS
-      end
+    module Telemetry
+      module TelemetryException
+        # This class will hold the all the information for the specific exception
+        # and will be passed in the Exception message itself
+        class StackFrame < Contrast::Agent::Telemetry::TelemetryException::Base
+          VALIDATIONS = {
+              function: { required: true, range: 1..256 },
+              type: { required: true, range: 1..256 },
+              module_name: { required: false, range: 1..256 }
+          }.cs__freeze
 
-      attr_reader :module_name
+          # @return [String] The type of the exception itself
+          attr_reader :type
 
-      def module_name= module_name
-        validate_field VALIDATIONS[:module_name], 'module_name'
-        @module_name = module_name
-      end
+          # @return [String] the function of the stack trace
+          attr_reader :function
+
+          # @return [Boolean] Is it in contrast
+          attr_accessor :in_contrast
+
+          # @return [String]
+          attr_reader :module_name
+
+          def initialize function, type
+            super()
+            @function = function
+            @type = type
+            @in_contrast = false
+            validate VALIDATIONS
+          end
+
+          def module_name= module_name
+            @module_name = module_name
+            validate_field(VALIDATIONS[:module_name], 'module_name')
+          end
+
+          def to_controlled_hash
+            super
+            { function: function, type: type, module: module_name, inContrast: in_contrast }.compact
+          end
 
-      def to_controlled_hash
-        super
-        { function: function, type: type, inContrast: in_contrast, module_name: module_name }.compact
+          class << self
+            # @param method [String] method, triggered the logger on warn/error/fatal
+            # @param type [String] the type ( where it occurred )
+            # @param module_name [String, nil] Name of the module if any.
+            def build method, type, module_name = nil
+              inst = new(method, type)
+              inst.module_name = module_name if module_name
+              inst.in_contrast = type.include?('lib/contrast')
+              inst
+            end
+          end
+        end
       end
     end
   end

data/lib/contrast/agent/telemetry/events/exceptions/telemetry_exceptions.rb

@@ -0,0 +1,20 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+module Contrast
+  module Agent
+    module Telemetry
+      # This is the module that will include every information created and stored for the
+      # Telemetry Exceptions
+      module TelemetryException
+      end
+    end
+  end
+end
+
+require 'contrast/agent/telemetry/events/exceptions/telemetry_exception_base'
+require 'contrast/agent/telemetry/events/exceptions/telemetry_exception_stack_frame'
+require 'contrast/agent/telemetry/events/exceptions/telemetry_exception_message_exception'
+require 'contrast/agent/telemetry/events/exceptions/telemetry_exception_message'
+require 'contrast/agent/telemetry/events/exceptions/telemetry_exception_event'
+require 'contrast/agent/telemetry/events/exceptions/telemetry_exceptions_report'

data/lib/contrast/agent/telemetry/events/exceptions/telemetry_exceptions_report.rb

@@ -0,0 +1,32 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+module Contrast
+  module Agent
+    module Telemetry
+      # This module will handle the reporting of the TelemetryExceptionHash
+      module TelemetryExceptionReport
+        class << self
+          # Here we will send any exceptions gathered. The telemetry_hash is split into batches of 256
+          # and then added to the telemetry queue. Since this method is called before entering the
+          # until queue loop any updates after clearing the Contrast::TELEMETRY_EXCEPTIONS would have
+          # to wait for the sending process to be completed, so accumulating new batches.
+          # This methods expects queue and error_messages methods from Contrast::Agent::Telemetry::Base
+          def push_exceptions
+            return unless Contrast::TELEMETRY_EXCEPTIONS&.any?
+
+            Contrast::TELEMETRY_EXCEPTIONS.values.each_slice(256) { |tuple| error_messages.push tuple }
+            # Clear the hash. All exceptions now live in @_error_messages instance variable. and we will
+            # add them to the queue. Clearing would make the hash available to be populated again while the
+            # sending is proceeding.
+            Contrast::TELEMETRY_EXCEPTIONS.clear
+            # Add batch to queue. We need to shift here, because we want to report from the oldest batch to
+            # the newest. And even if somehow the array is filled during sending the new messages would stay
+            # and wait their turn.
+            queue << error_messages.shift until error_messages.empty?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/telemetry/events/metric_event.rb

@@ -0,0 +1,28 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/utils/metrics_hash'
+require 'contrast/agent/telemetry/events/event'
+
+module Contrast
+  module Agent
+    module Telemetry
+      # This class will hold the basic information for a Telemetry Event
+      class MetricEvent < Contrast::Agent::Telemetry::Event
+        include Contrast::Utils
+
+        attr_reader :fields
+
+        def initialize
+          super
+          @fields = MetricsHash.new(Numeric)
+          @fields['_filler'] = 0
+        end
+
+        def to_hash **_args
+          super.merge!({ fields: @fields })
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/telemetry/events/startup_metrics_event.rb

@@ -0,0 +1,123 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/utils/metrics_hash'
+require 'contrast/agent/telemetry/events/metric_event'
+require 'contrast/agent/version'
+require 'contrast/utils/os'
+
+module Contrast
+  module Agent
+    module Telemetry
+      # This class will hold the Startup Metrics Telemetry Event
+      # The class will include initialization of the agent version, language version
+      # os type, arch and version
+      # application framework and version and server framework
+      # It will be initialized and send in Middleware#agent_startup_routine
+      class StartupMetricsEvent < Contrast::Agent::Telemetry::MetricEvent
+        include Contrast::Utils::OS
+
+        APP_AND_SERVER_DATA = ::Contrast::APP_CONTEXT.app_and_server_information.cs__freeze
+        # Multi-tenant Production Environments
+        SAAS_DEFAULT = { addr: 'app.contrastsecurity.com', type: 'SAAS_DEFAULT' }.cs__freeze
+        SAAS_CS = { addr: /cs[[:digit:]]+\.contrastsecurity\.com/, type: 'SAAS_DEFAULT' }.cs__freeze
+        SAAS_JP = { addr: 'app.contrastsecurity.jp', type: 'SAAS_DEFAULT' }.cs__freeze
+        SAAS_CE = { addr: 'ce.contrastsecurity.com', type: 'SAAS_CE' }.cs__freeze
+        # Multi-tenant Demo Environments
+        SAAS_DEMO = { addr: 'apptwo.contrastsecurity.com', type: 'SAAS_DEMO' }.cs__freeze
+        SAAS_POV = { addr: 'eval.contrastsecurity.com', type: 'SAAS_POV' }.cs__freeze
+        # Multi-tenant Testing Environment
+        SAAS_RESEARCH = { addr: 'security-research.contrastsecurity.com', type: 'SAAS_RESEARCH' }.cs__freeze
+        SAAS_ALPHA = { addr: 'alpha.contrastsecurity.com', type: 'SAAS_ALPHA' }.cs__freeze
+        SAAS_STAGING = { addr: 'teamserver-staging.contsec.com', type: 'SAAS_TESTING' }.cs__freeze
+        SAAS_STAGING_TOKYO = { addr: 'teamserver-staging.contsec.jp', type: 'SAAS_TESTING' }.cs__freeze
+        SAAS_TESTING = { addr: 'teamserver-darpa.contsec.com', type: 'SAAS_TESTING' }.cs__freeze
+        SAAS_OPS_TESTING = { addr: 'teamserver-ops.contsec.com', type: 'SAAS_TESTING' }.cs__freeze
+        # Fallback for Single-tenant Production Environments
+        SAAS_CUSTOM = { addr: 'contrastsecurity.com', type: 'SAAS_CUSTOM' }.cs__freeze
+        SAAS_CUSTOM_JP = { addr: 'contrastsecurity.jp', type: 'SAAS_CUSTOM' }.cs__freeze
+
+        SINGLE_MAP_TENANTS = [
+          SAAS_DEFAULT, SAAS_JP, SAAS_CE, SAAS_DEMO, SAAS_POV, SAAS_RESEARCH, SAAS_ALPHA,
+          SAAS_STAGING, SAAS_STAGING_TOKYO, SAAS_TESTING, SAAS_OPS_TESTING
+        ].cs__freeze
+        REGEXP_MAP_TENANTS = [SAAS_CS].cs__freeze
+        FALLBACK_TENANTS = [SAAS_CUSTOM, SAAS_CUSTOM_JP].cs__freeze
+        # Fallback for Custom, most likely self-hosted, Environments
+        EOP = 'EOP'
+        REJECTED_VALUES = [nil, 'NEEDS_TO_BE_SET', Contrast::Utils::ObjectShare::EMPTY_STRING].cs__freeze
+
+        def initialize
+          super
+          @settings = []
+          add_config_keys ::Contrast::CONFIG.root, 'root'
+          @settings << ENV.keys.select { |v| v.starts_with?('CONTRAST') }
+          @settings.flatten
+          add_tags
+        end
+
+        def path
+          '/startup'
+        end
+
+        def add_tags
+          add_system_tags
+          @tags['app_framework_and_version'] = APP_AND_SERVER_DATA[:application_info].to_s
+          @tags['server_framework_and_version'] = APP_AND_SERVER_DATA[:server_info].to_s
+          @tags['ASSESS'] = Contrast::ASSESS.enabled?.to_s
+          @tags['PROTECT'] = Contrast::PROTECT.enabled?.to_s
+          @tags['settings'] = @settings.join(',')
+        end
+
+        def add_config_keys config, nested_key
+          config.to_hash.reject! { |_k, v| REJECTED_VALUES.include?(v) }
+
+          config.to_hash.each do |k, v|
+            unless v.cs__class <= Contrast::Config::BaseConfiguration
+              @settings << "#{ nested_key }.#{ k }"
+              next
+            end
+
+            add_config_keys v, "#{ nested_key }.#{ k }"
+          end
+        end
+
+        def sys_info
+          @sys_info ||= get_system_information if @sys_info.nil?
+          @sys_info
+        end
+
+        private
+
+        # Here we extract the TeamServer url type
+        #
+        # @return [String] the type of TeamServer environment to which we're connecting
+        def teamserver_type
+          @_teamserver_type ||= begin
+            url = Contrast::API.api_url
+            if (single = SINGLE_MAP_TENANTS.find { |tenant| url.include?(tenant[:addr]) })
+              single[:type]
+            elsif (regexp = REGEXP_MAP_TENANTS.find { |tenant| tenant[:addr].match?(url) })
+              regexp[:type]
+            elsif (fallback = FALLBACK_TENANTS.find { |tenant| url.include?(tenant[:addr]) })
+              fallback[:type]
+            else
+              EOP
+            end
+          end
+        end
+
+        # Here we attach the key-value pairs of the system
+        #
+        def add_system_tags
+          @tags['teamserver'] = teamserver_type
+          @tags['agent_version'] = VERSION
+          @tags['ruby_version'] = RUBY_VERSION
+          @tags['os_type'] = sys_info['os_type'] == 'Darwin' ? 'MacOS' : 'Linux'
+          @tags['os_arch'] = sys_info['os_arch']
+          @tags['os_version'] = sys_info['os_version']
+        end
+      end
+    end
+  end
+end