contrast-agent 3.9.1 → 6.15.3

data/lib/contrast/agent/scope/scope.rb

@@ -0,0 +1,158 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'cs__scope/cs__scope'
+
+module Contrast
+  module Agent
+    # Scope lets us disable Contrast for certain code calls. We need to do this so
+    # that we don't propagate through our own code.
+    #
+    # Think logging: If you have
+    # something like "The source was '" + source + "'", and source is tracked,
+    # you'll trigger propagation with the + method. This in turn would cause
+    # propagation if you log there "The target ''" + target + "' was propagated'"
+    # Which would then cause another propagation with the '+' method, forever.
+    #
+    # Instead, we should say "If I'm already doing Contrast things, don't track
+    # this"
+    #
+    # Scope Exits...
+    # by design, can go below zero.
+    # every exit/enter pair (regardless of series)
+    # should cancel each other out.
+    #
+    # so we prefer this sequence:
+    #   scope =  0
+    #   exit  = -1
+    #   enter =  0
+    #   enter =  1
+    #   exit  =  0
+    #   scope =  0
+    #
+    # over this sequence:
+    #   scope =  0
+    #   exit  =  0
+    #   enter =  1
+    #   enter =  2
+    #   exit  =  1
+    #   scope =  1
+    #
+    # This class have been moved to C and it's called from there. Here remains
+    # the validation and wrapper methods.
+    #
+    # Methods defined in C:
+    #
+    # sets scope instance variables.
+    # def initialize end;
+    #
+    # Check if we are in contrast scope.
+    # def in_contrast_scope? end;
+    # @return [Boolean] check if we are in contrast scope
+    #                   if the scope is above 0 return true.
+    #
+    # check if we are in deserialization scope.
+    # def in_deserialization_scope? end;
+    # @return [Boolean] check if we are in contrast scope
+    #                   if the scope is above 0 return true.
+    #
+    # check if we are in split scope.
+    # def in_split_scope? end;
+    # @return [Boolean] check if we are in contrast scope
+    #                   if the scope is above 0 return true.
+    #
+    # enter contrast scope.
+    # def enter_contrast_scope! end;
+    # @return @contrast_scope [Integer] contrast scope increased.
+    #
+    # enter deserialization scope.
+    # def enter_deserialization_scope! end;
+    # @return @deserialization_scope [Integer] deserialization scope increased.
+    #
+    # enter split scope.
+    # def enter_split_scope! end;
+    # @return @split_scope [Integer] split scope increased.
+    #
+    # check split scope depth.
+    # def split_scope_depth end;
+    # @return @split_scope [Integer] split scope depth.
+    #
+    # exit contrast scope.
+    # def exit_contrast_scope! end;
+    # @return @contrast_scope [Integer] contrast scope decreased.
+    #
+    # exit deserialization scope.
+    # def exit_deserialization_scope! end;
+    # @return @deserialization_scope [Integer] deserialization scope decreased.
+    #
+    # exit split scope.
+    # def exit_split_scope! end;
+    # @return @split_scope [Integer] split scope decreased.
+    #
+    # Static methods to be used, the cases are defined by the usage from the above methods
+    #
+    # check if we are in specific scope.
+    # def in_scope? name end;
+    # @param name [Symbol] scope symbol representing scope to check.
+    # @return [Boolean] check if we are in passed scope.
+    #
+    # enter specific scope.
+    # def enter_scope! name end;
+    # @param name [Symbol] scope symbol representing scope to enter.
+    # @return scope [Integer] entered scope value increased.
+    #
+    # exit specific scope.
+    # def exit_cope! name end;
+    # @param name [Symbol] scope symbol representing scope to exit.
+    # @return scope [Integer] entered scope value decreased.
+    class Scope
+      SCOPE_LIST = %i[contrast deserialization split].cs__freeze
+
+      # Wraps block to be executed in contrast scope.
+      # On completion exits scope.
+      def with_contrast_scope
+        enter_contrast_scope!
+        yield
+      ensure
+        exit_contrast_scope!
+      end
+
+      # Wraps block to be executed in deserialization scope.
+      # On completion exits scope.
+      def with_deserialization_scope
+        enter_deserialization_scope!
+        yield
+      ensure
+        exit_deserialization_scope!
+      end
+
+      # Wraps block to be executed in split scope.
+      # On completion exits scope.
+      def with_split_scope
+        enter_split_scope!
+        yield
+      ensure
+        exit_split_scope!
+      end
+
+      # Enter app scope
+      def with_app_scope
+        exit_contrast_scope!
+        yield
+      ensure
+        enter_contrast_scope!
+      end
+
+      class << self
+        # Validates scope. To be valid the scope must be one of:
+        # :contrast, :split, :deserialization
+        #
+        # @param scope_sym [Symbol] scope to check.
+        # @return [Boolean] true | false
+        def valid_scope? scope_sym
+          Contrast::Agent::Scope::SCOPE_LIST.include?(scope_sym)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,171 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/config/env_variables'
+require 'contrast/components/logger'
+require 'contrast/agent/telemetry/client'
+require 'contrast/agent/thread/worker_thread'
+require 'contrast/agent/telemetry/telemetry'
+require 'contrast/agent/telemetry/exception'
+require 'contrast/utils/job_servers_running'
+
+module Contrast
+  module Agent
+    module Telemetry
+      # This class will initialize and hold everything needed for the telemetry
+      class Base < WorkerThread # rubocop:disable Metrics/ClassLength
+        include Contrast::Components::Logger::InstanceMethods
+        # this is where we will send the data from the agents
+        URL = 'https://telemetry.ruby.contrastsecurity.com/'
+        # Suggested timeout after each send is to be 3 hours (10800 seconds)
+        SUGGESTED_TIMEOUT = 10_800
+
+        class << self
+          include Contrast::Components::Logger::InstanceMethods
+          include Contrast::Config::EnvVariables
+
+          # The unique identifier of this application based on Mac address and application name.
+          #
+          # @return [String]
+          def application_id
+            Contrast::Agent::Telemetry::Identifier.application_id
+          end
+
+          # The unique identifier of this instance, based on Mac address.
+          #
+          # @return [String]
+          def instance_id
+            Contrast::Agent::Telemetry::Identifier.instance_id
+          end
+
+          # If the feature as a whole is enabled or not, as determined by user opt-out
+          #
+          # @return [Boolean]
+          def enabled?
+            @enabled = telemetry_enabled? if @enabled.nil?
+            @enabled
+          end
+
+          private
+
+          def telemetry_enabled?
+            return false if Contrast::AGENT.disabled? || Contrast::Utils::JobServersRunning.job_servers_running?
+
+            opt_out_telemetry = return_value(:telemetry_opt_outs).to_s
+            return false if opt_out_telemetry.casecmp?('true') || opt_out_telemetry == '1'
+
+            # In case of connection error, do not create the background thread or queue,
+            # as if the opt-out env var was set
+            @_client = Contrast::Agent::Telemetry::Client.new
+            ip_opt_out_telemetry = @_client.initialize_connection(URL)
+            if ip_opt_out_telemetry.nil?
+              # TODO: RUBY-2033 we cannot log the error above debug level here b/c it results in
+              #   an infinite loop w/ telemetry
+              logger.debug("[Telemetry] Connection was not established properly!!! \n
+                          Telemetry reporting will be disabled!")
+              return false
+            end
+
+            true
+          end
+        end
+
+        def client
+          @_client ||= Contrast::Agent::Telemetry::Client.new
+        end
+
+        def connection
+          @_connection ||= client.initialize_connection(URL)
+        end
+
+        def attempt_to_start?
+          return unless super
+
+          unless cs__class.enabled?
+            logger.info('[Telemetry] Telemetry service is disabled!')
+            return false
+          end
+
+          logger.debug('[Telemetry] Attempting to start telemetry thread') unless running?
+          true
+        end
+
+        def start_thread!
+          return if running?
+
+          logger.debug('[Telemetry] Starting background telemetry thread.')
+          @_thread = create_thread
+        end
+
+        def send_event event
+          if ::Contrast::AGENT.disabled?
+            logger.debug('[Telemetry] Attempted to queue event with Agent disabled', caller: caller, event: event)
+            return
+          end
+
+          return unless cs__class.enabled?
+
+          logger.debug('[Telemetry] Enqueued event for sending', event_type: event.cs__class)
+          queue << event if event
+        end
+
+        def delete_queue!
+          @_queue&.close
+          @_queue = nil
+        end
+
+        def stop!
+          return unless running?
+
+          super
+          delete_queue!
+          Contrast::TELEMETRY_EXCEPTIONS&.clear
+        end
+
+        def request_with_response event
+          client.handle_response(client.send_request(event, connection))
+        end
+
+        private
+
+        def queue
+          @_queue ||= Queue.new
+        end
+
+        # It is recommended that implementations send a single payload of general metrics every 3 hours, starting from
+        # implementation startup. This returns a thread configured to do so.
+        #
+        # @return [::Thread] Contrast::Agent::Thread
+        def create_thread
+          Contrast::Agent::Thread.new do
+            loop do
+              next unless client && connection
+
+              # Start pushing exceptions to queue for reporting.
+              Contrast::TELEMETRY_EXCEPTIONS.each_value { |value| queue << value }
+              Contrast::TELEMETRY_EXCEPTIONS.clear
+              until queue.empty?
+                event = queue.pop
+                begin
+                  logger.debug('[Telemetry] This is the current processed event', event)
+                  if (sleep_time = request_with_response(event))
+                    sleep(sleep_time)
+                    logger.debug('[Telemetry] Retrying to process event', event)
+                    retry_sleep_time = request_with_response(event)
+                    sleep(retry_sleep_time) unless retry_sleep_time.nil?
+                  end
+                rescue StandardError => e
+                  # TODO: RUBY-2033 we cannot log the error above debug level here b/c it results in
+                  #   an infinite loop w/ telemetry
+                  logger.debug('[Telemetry] Could not send message to service from telemetry queue.', e)
+                  stop!
+                end
+              end
+              sleep(SUGGESTED_TIMEOUT)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,111 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'net/http'
+require 'contrast/utils/net_http_base'
+require 'contrast/components/logger'
+require 'contrast/utils/object_share'
+require 'contrast/agent/version'
+require 'json'
+
+module Contrast
+  module Agent
+    module Telemetry
+      # This module creates a Net::HTTP client and initiates a connection to the provided result
+      class Client < Contrast::Utils::NetHttpBase
+        include Contrast::Components::Logger::InstanceMethods
+        ENDPOINT = 'api/v1/telemetry/metrics' # /TelemetryEvent.path
+        EXCEPTIONS = 'api/v1/telemetry/exceptions' # /Telemetry::Exception::Event.path
+        SERVICE_NAME = 'Telemetry'
+        # This method initializes the Net::HTTP client we'll need. it will validate
+        # the connection and make the first request. If connection is valid and response
+        # is available then the open connection is returned.
+        #
+        # @param url [String]
+        # @return [Net::HTTP, nil] Return open connection or nil
+        def initialize_connection url
+          super(SERVICE_NAME, url, use_proxy: false, use_custom_cert: false)
+        end
+
+        # This method will be responsible for building the request. Because the telemetry collector expects to receive
+        # multiple events in a single request, we must always wrap the event in an array, even if there is only one.
+        #
+        # @param event [Contrast::Agent::Telemetry::Event, Array<Contrast::Agent::Telemetry::Exception::Event>]
+        # @return [Net::HTTP::Post]
+        def build_request event
+          return unless valid_event?(event)
+
+          header = {
+              'User-Agent' => "<#{ Contrast::Utils::ObjectShare::RUBY }>-<#{ Contrast::Agent::VERSION }>",
+              'Content-Type' => 'application/json'
+          }
+          request = Net::HTTP::Post.new(build_path(event), header)
+          request.body = get_event_json(event)
+          request
+        end
+
+        # This method will create the actual request and send it
+        # @param event[Contrast::Agent::Telemetry::Event]
+        # @param connection[Net::HTTP]
+        def send_request event, connection
+          return if connection.nil? || event.nil?
+          return unless valid_event?(event)
+
+          req = build_request(event)
+          connection.request(req)
+        end
+
+        # This method will handle the response from the tenant
+        # @param res [Net::HTTPResponse]
+        # @return sleep_time [Integer, nil]
+        def handle_response res
+          status_code = res.code.to_i
+          ready_after = if res.to_hash.keys.map(&:downcase).include?('ready-after')
+                          res['Ready-After']
+                        else
+                          60
+                        end
+          ready_after if status_code == 429
+        end
+
+        # This method will be responsible for validating the event. Valid if event is of a known
+        # Contrast::Agent::Telemetry type
+        #
+        # @param event [Object]
+        def valid_event? event
+          return true if event.cs__is_a?(Contrast::Agent::Telemetry::Event)
+          return true if event.cs__is_a?(Contrast::Agent::Telemetry::StartupMetricsEvent)
+          return true if event.cs__is_a?(Contrast::Agent::Telemetry::Exception::Event)
+
+          false
+        end
+
+        private
+
+        # The telemetry instance accepts any path to #{ Contrast::Agent::Telemetry::URL }#{ ENDPOINT }, using the
+        # remainder of the path to segregate messages.
+        #
+        # @param event [Contrast::Agent::Telemetry::Event, Contrast::Agent::Telemetry::Exception::Event]
+        # @return [String] the fully qualified path to send the request
+        def build_path event
+          endpoint = Array(event).all?(Contrast::Agent::Telemetry::Exception::Event) ? EXCEPTIONS : ENDPOINT
+          path = endpoint == EXCEPTIONS ? Contrast::Agent::Telemetry::Exception::Event.path : event.path
+          "#{ Contrast::Agent::Telemetry::Base::URL }#{ endpoint }#{ path }"
+        end
+
+        # Helper Method to get json representation of Telemetry Event data, handles error on to_json
+        #
+        # @param event [Contrast::Agent::Telemetry::Event, Array<Contrast::Agent::Telemetry::Exception::Event>]
+        # @return [String] - JSON
+        def get_event_json event
+          Array(event.to_controlled_hash).to_json
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          # TODO: RUBY-2033 we cannot log the error above debug level here b/c it results in
+          #   an infinite loop w/ telemetry
+          logger.debug('[Telemetry] Unable to convert TelemetryEvent to JSON string', e, hsh)
+          raise(e)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# 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'
+
+module Contrast
+  module Agent
+    module Telemetry
+      # This class will hold the basic information for a Telemetry Event
+      class Event
+        include Contrast::Utils
+
+        attr_reader :tags
+
+        def initialize
+          @tags = MetricsHash.new(String)
+          @timestamp = Time.now.iso8601
+        end
+
+        def path
+          ''
+        end
+
+        def to_controlled_hash **_args
+          {
+              tags: @tags,
+              timestamp: @timestamp,
+              instance: Contrast::Agent::Telemetry::Base.instance_id,
+              application: Contrast::Agent::Telemetry::Base.application_id
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# 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
+      module Exception
+        # This class will hold the all the mutual information for the Telemetry Exception
+        class Base
+          def to_controlled_hash; end
+
+          protected
+
+          # Validate required and option fields
+          #
+          # @param validations [Hash] Validation hash to use
+          # @return [nil]
+          def validate validations
+            validations.each do |k, v|
+              next if v[:required] == false
+
+              validate_field(validations[k], k)
+            end
+            nil
+          end
+
+          # This method will validate every single field passed from validate
+          #
+          # @param validation_pair [Hash] Validation hash to use
+          # @param key[String] The key to check in VALIDATIONS
+          # @raise [ArgumentError]
+          def validate_field validation_pair, key
+            value_to_validate = send(key.to_sym)
+            validate_class(value_to_validate, validation_pair[:class], key) if validation_pair.key?(:class)
+            value_length = if value_to_validate.cs__is_a?(String) || value_to_validate.cs__is_a?(Array)
+                             value_to_validate.length
+                           else
+                             value_to_validate.entries.length
+                           end
+            unless validation_pair[:range].include?(value_length)
+              raise(ArgumentError, "The provided value for #{ key } is invalid: #{ value_to_validate }")
+            end
+
+            nil
+          end
+
+          # With the all nested classes, we still need to double check if everything passed along the way
+          # is right
+          # @param message [Object] The message we want to check the class of
+          # @param klass [Class] The klass we want to check the message with
+          # @param field [Object] The field with the error
+          # @raise [ArgumentError]
+          def validate_class message, klass, field
+            message = message[0] if message.cs__is_a?(Array)
+            raise(ArgumentError, "The provided value for #{ field } is of wrong class") unless message.cs__is_a?(klass)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# 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'
+
+module Contrast
+  module Agent
+    module Telemetry
+      module Exception
+        # This class will hold the basic information for a Parent Telemetry Exception Event
+        class Event < Contrast::Agent::Telemetry::Exception::Base
+          # Array of Telemetry Exceptions
+          # @return [Array<Contrast::Agent::Telemetry::Exception::Message>]
+          attr_reader :exceptions
+
+          # Initialization of the Parent Event requires us to require the exception
+          # to be created
+          #
+          # @param message [Contrast::Agent::Telemetry::Exception::Message]
+          # @raise[ArgumentError]
+          def initialize message
+            super()
+            validate_class(message, Contrast::Agent::Telemetry::Exception::Message, 'exception_message')
+            @exceptions = Array.new(1, message)
+          end
+
+          # @param message [Contrast::Agent::Telemetry::Exception::Message]
+          # @raise[ArgumentError]
+          def push message
+            validate_class(message, Contrast::Agent::Telemetry::Exception::Message, 'exception_message')
+            @exceptions << message
+          end
+
+          def self.path
+            '/error'
+          end
+
+          def to_controlled_hash
+            exceptions.map(&:to_controlled_hash)
+          end
+        end
+      end
+    end
+  end
+end