contrast-agent 3.9.1 → 6.15.3

data/lib/contrast/agent/telemetry/exception/message.rb

@@ -0,0 +1,118 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'message_exception'
+require 'contrast/agent/telemetry/identifier'
+
+module Contrast
+  module Agent
+    module Telemetry
+      module Exception
+        # 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::Exception::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::Exception::MessageException
+              }
+          }.cs__freeze
+
+          # 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
+
+          # 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
+
+          # Array of exceptions, but in our case the Array will only include one exception
+          # @return [Array<Contrast::Agent::Telemetry::Exception::MessageException>]
+          attr_reader :exceptions
+
+          # @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
+
+          # @raise[ArgumentError]
+          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]
+          # @raise[ArgumentError]
+          def logger= logger
+            @logger = logger
+            validate_field(VALIDATIONS[:logger], 'logger')
+          end
+
+          # Optional parameters will be set separately from the required
+          #
+          # @param message[String]
+          # @raise[ArgumentError]
+          def message= message
+            @message = message
+            validate_field(VALIDATIONS[: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
+
+          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
+
+          class << self
+            def build tags, exceptions, logger = nil, message = nil
+              inst = new(Contrast::Agent::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
+end

data/lib/contrast/agent/telemetry/exception/message_exception.rb

@@ -0,0 +1,86 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'stack_frame'
+
+module Contrast
+  module Agent
+    module Telemetry
+      module Exception
+        # 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::Exception::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::Exception::StackFrame
+              }
+          }.cs__freeze
+
+          # @return [String] The type of the exception itself
+          attr_reader :type
+
+          # stack frames for the message exception
+          # @return [Array<Contrast::Agent::Telemetry::Exception::StackFrame>]
+          attr_reader :stack_frames
+
+          # @return [String]
+          attr_reader :module_name
+
+          # @return [String]
+          attr_reader :value
+
+          def initialize type, stack_frame
+            super()
+            @type = type
+            @stack_frames = Array.new(1, stack_frame)
+            validate(VALIDATIONS)
+          end
+
+          # @param stack_frame [Contrast::Agent::Telemetry::Exception::StackFrame]
+          # @raise[ArgumentError]
+          def push stack_frame
+            validate_class(stack_frame, Contrast::Agent::Telemetry::Exception::StackFrame, 'stack_frame')
+            @stack_frames << stack_frame
+          end
+
+          # @raise[ArgumentError]
+          def module_name= module_name
+            @module_name = module_name
+            validate_field(VALIDATIONS[:module_name], 'module_name')
+          end
+
+          # @raise[ArgumentError]
+          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
+
+          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
+end

data/lib/contrast/agent/telemetry/exception/stack_frame.rb

@@ -0,0 +1,67 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Contrast
+  module Agent
+    module Telemetry
+      module Exception
+        # 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::Exception::Base
+          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
+
+          # @return [String]
+          attr_reader :module_name
+
+          # @raise [ArgumentError]
+          def initialize function, type
+            super()
+            @function = function
+            @type = type
+            @in_contrast = false
+            validate(VALIDATIONS)
+          end
+
+          # @raise [ArgumentError]
+          def module_name= module_name
+            @module_name = module_name
+            validate_field(VALIDATIONS[:module_name], 'module_name')
+          end
+
+          # @raise [ArgumentError]
+          def to_controlled_hash
+            super
+            { function: function, type: type, module: module_name, inContrast: in_contrast }.compact
+          end
+
+          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
+end

data/lib/contrast/agent/telemetry/exception.rb

@@ -0,0 +1,19 @@
+# Copyright (c) 2023 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 Exception
+      end
+    end
+  end
+end
+
+require 'contrast/agent/telemetry/exception/base'
+require 'contrast/agent/telemetry/exception/stack_frame'
+require 'contrast/agent/telemetry/exception/message_exception'
+require 'contrast/agent/telemetry/exception/message'
+require 'contrast/agent/telemetry/exception/event'

data/lib/contrast/agent/telemetry/hash.rb

@@ -0,0 +1,71 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/components/logger'
+require 'contrast/agent/telemetry/exception/event'
+
+module Contrast
+  module Agent
+    module Telemetry
+      # This is the Telemetry::Hash, which will store Contrast::Agent::Telemetry::Exception::Event, so we can push
+      # freely, without worrying about validating the event before that. Telemetry::Hash has a max size of events,
+      # default is 10 events
+      class Hash < Hash
+        include Contrast::Components::Logger::InstanceMethods
+        HASH_SIZE_LIMIT = 10
+
+        # Wrapper to set a value in this Telemetry::Hash only if the provided value is of the data_type for this
+        # Telemetry::Hash or the hash has not reached its limit of for unique keys
+        #
+        # @param key [Object] the key to which to associate the value
+        # @param value [Object] the value to store
+        # @return [Object, nil] echo back out the value as the Hash#[]= method does, or nil if not of the expected
+        #   data_type
+        def []= key, value
+          # If telemetry is not running, do not add more as we want to avoid a memory leak.
+          return unless Contrast::Agent.telemetry_queue&.running?
+          # If the Hash is full, do not add more as we want to avoid consuming all application resources.
+          return if exception_limit?
+          # If the given value is of unexpected type, do not add it to avoid issues later where type is assumed.
+          return unless valid_value?(value)
+
+          super(key, value)
+        end
+
+        # Increment the occurrences for the exception object contained in this Telemetry::Hash
+        #
+        # @param key [Object] the key to check for the exception stored in this Telemetry::Hash
+        def increment key
+          value = self[key]
+          return unless value&.exceptions&.any?
+
+          value.exceptions[0].increment_occurrences
+        end
+
+        # Determine if hash has reached exception event limit
+        # @return [Boolean]
+        def exception_limit?
+          unless size < HASH_SIZE_LIMIT
+            logger.debug("Number of TelemetryExceptions exceeds limit of #{ HASH_SIZE_LIMIT }")
+            return true
+          end
+          false
+        end
+
+        private
+
+        # Determine if the given value is valid based on the datatype which this Telemetry::Hash contains
+        # @param value [Object]
+        # @return boolean
+        def valid_value? value
+          unless value.cs__is_a?(Contrast::Agent::Telemetry::Exception::Event)
+            logger.debug('The following key will be omitted', value: value)
+            return false
+          end
+
+          true
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/telemetry/identifier.rb

@@ -0,0 +1,153 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/utils/os'
+require 'digest'
+require 'socket'
+
+module Contrast
+  module Agent
+    # Tools for supporting the Telemetry feature
+    module Telemetry
+      # Gets info about the instrumented application required to build unique identifiers,
+      # used in the agent's Telemetry.
+      module Identifier
+        MAC_REGEX = /^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$/.cs__freeze
+        LINUX_OS_REG = /hwaddr=.*?(([A-F0-9]{2}:){5}[A-F0-9]{2})/im.cs__freeze
+        MAC_OS_PRIMARY = 'en0'.cs__freeze
+        LINUX_PRIMARY = 'enp'.cs__freeze
+
+        # Sinatra and Grape both use similar approach to identify the app_name.
+        # Rails has a different way of doing it, but to unify this we'll use this one.
+        # If app_name is changed/renamed during production it would still get the
+        # new folder's name.
+        #
+        # @ return [String] name of the application from the current working directory
+        def self.app_name
+          @_app_name ||= File.basename(Dir.pwd)
+        end
+
+        # Returns the MAC address of the primary network interface, depending on the used OS.
+        # If the primary is unknown it finds the first available network interface and gets it's
+        # MAC address instead.
+        #
+        # @return [String, nil] MAC address of the primary network interface or
+        # the first available one, or nil if nothing found
+        def self.mac
+          primary = Contrast::Utils::OS.mac? ? MAC_OS_PRIMARY : LINUX_PRIMARY
+          @_mac = find_mac(primary) || find_mac
+        end
+
+        # Set and return a Sha256 hash representing this application, based on the mac identifier of this machine and
+        # the application name or a Secure UUID if one of them cannot be determined.
+        #
+        # @return [String]
+        def self.application_id
+          @_application_id ||= begin
+            id = nil
+            mac = Contrast::Agent::Telemetry::Identifier.mac
+            app_name = Contrast::Agent::Telemetry::Identifier.app_name
+            id = mac + app_name if mac && app_name
+            Digest::SHA2.new(256).hexdigest(id || "_#{ SecureRandom.uuid }")
+          end
+        end
+
+        # Set and return a Sha256 hash representing this agent run, based on the mac identifier of this machine or a
+        # Secure UUID if one cannot be determined.
+        #
+        # @return [String]
+        def self.instance_id
+          @_instance_id ||= Digest::SHA2.new(256).hexdigest(Contrast::Agent::Telemetry::Identifier.mac ||
+                                                              "_#{ SecureRandom.uuid }")
+        end
+
+        class << self
+          private
+
+          # Finds the primary MAC address of all listed network adapters.
+          # If primary is not set or unknown, use the first MAC address found
+          # from the listed adapters.
+          #
+          # @param primary [nil, String] optional param if set look only for primary
+          # network adapter's name
+          # @return [String, nil] MAC address of the first listed network adapter or
+          # nil if not found
+          def find_mac primary = nil
+            result = nil
+            idx = 0
+            return if interfaces.empty?
+
+            while idx < interfaces.length
+              addr = interfaces[idx].addr
+              name = interfaces[idx].name # rubocop:disable Security/Module/Name
+              idx += 1
+              next if primary && !name.include?(primary)
+
+              # retrieving MAC address from primary network interface or first available
+              mac = retrieve_mac(addr)
+              next unless mac
+
+              result = mac if mac&.match?(MAC_REGEX)
+              break if result
+            end
+            result
+          end
+
+          # Retrieves MAC address for primary or any network interface.
+          # This is OS dependent search.
+          #
+          # @param addr [String] address info
+          # example: #<Addrinfo: LINK[en0 aa:bb:cc:00:11:22]>
+          # @return mac [nil, String] MAC address of primary network interface,
+          # any network interface, or nil if no interface is found.
+          def retrieve_mac addr
+            # Mac OS allow us to use getnameinfo(sockaddr [, flags]) => [hostname, servicename]
+            #
+            # returned address:
+            # <Socket::Ifaddr en0 UP,BROADCAST,RUNNING,NOTRAILERS,SIMPLEX,MULTICAST LINK[en0 aa:bb:cc:00:11:22]>
+            return addr.getnameinfo[0] if Contrast::Utils::OS.mac?
+
+            # In Linux using Socket::addr#getnameinfo results in ai_family not supported exception.
+            # In this case we are relying on match filtering of addresses.
+            #
+            # returned address:
+            # #<Socket::Ifaddr eth0 UP,BROADCAST,RUNNING,MULTICAST,0x10000
+            # PACKET[protocol=0 eth0 hatype=1 HOST hwaddr=aa:bb:cc:00:11:22]>
+            return Regexp.last_match(1) if addr.inspect =~ LINUX_OS_REG
+
+            nil
+          end
+
+          # Returns array of network interfaces.
+          # This is OS dependent search.
+          #
+          # @return interfaces [Array] Returns an array of interface addresses.
+          # Socket::Ifaddr - represents a result of getifaddrs().
+          def interfaces
+            @_interfaces ||= []
+
+            return @_interfaces unless @_interfaces.empty?
+
+            arr = Socket.getifaddrs
+            idx = 0
+            check_family = 0
+            while idx < arr.length
+              # We need only network adapters MACs. Checking for pfamily of every socket address:
+              # 18 for Mac OS and 17 for Linux.
+              # family should be an address family such as: :INET, :INET6, :UNIX, etc.
+              check_family = 18 if Contrast::Utils::OS.mac?
+              check_family = 17 if Contrast::Utils::OS.linux?
+              if arr[idx].addr.pfamily != check_family
+                idx += 1
+                next
+              end
+              @_interfaces << arr[idx]
+              idx += 1
+            end
+            @_interfaces
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# Copyright (c) 2023 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/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_controlled_hash **_args
+          super.merge!({ fields: @fields })
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,123 @@
+# Copyright (c) 2023 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/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.config, 'root')
+          @settings << ENV.keys.select { |v| v.start_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_contrast_hash.reject! { |_k, v| REJECTED_VALUES.include?(v) }
+
+          config.to_contrast_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