contrast-agent 3.9.1 → 6.15.3

data/lib/contrast/utils/job_servers_running.rb

@@ -1,36 +1,46 @@
-# Copyright (c) 2020 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
 # frozen_string_literal: true
 
+require 'contrast/components/ruby_component'
+
 module Contrast
   module Utils
     # A module that detects whether any job servers attached to
     # the application are running
     module JobServersRunning
-      include Contrast::Components::Interface
-      access_component :logging
-
       class << self
         def job_servers_running?
           sidekiq_running? || rake_running?
         end
 
+        private
+
         def sidekiq_running?
           return unless defined?(Sidekiq) && Sidekiq.cs__respond_to?(:server?) && Sidekiq.server?
 
-          logger.debug(nil, 'Detected the spawn of a Sidekiq process')
           true
         end
 
         def rake_running?
-          return unless defined?(Rake) &&
-              Rake.cs__respond_to?(:application) &&
-              Rake.application.cs__respond_to?(:top_level_tasks)
+          unless defined?(Rake) &&
+                Rake.cs__respond_to?(:application) &&
+                Rake.application.cs__respond_to?(:top_level_tasks)
+
+            return
+          end
 
-          disabled_rake_tasks = Contrast::Agent::FeatureState.instance.disabled_agent_rake_tasks
-          has_disabled_task = Rake.application.top_level_tasks.any? { |top_level_task| disabled_rake_tasks.include?(top_level_task) }
+          # This might be called before component even exist, so we backup to
+          # default disabled rake tasks.
+          disabled_rake_tasks = if Contrast.const_defined?(:APP_CONTEXT) # rubocop:disable Security/Module/ConstDefined
+                                  Contrast::APP_CONTEXT.disabled_agent_rake_tasks
+                                else
+                                  Contrast::Components::Ruby::Interface::DISABLED_RAKE_TASK_LIST
+                                end
+          has_disabled_task = Rake.application.top_level_tasks.any? do |top_level_task|
+            disabled_rake_tasks.include?(top_level_task)
+          end
           return false unless has_disabled_task
 
-          logger.debug(nil, 'Detected startup within Rake task')
           true
         end
       end

data/lib/contrast/utils/log_utils.rb

@@ -0,0 +1,254 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'socket'
+require 'contrast/agent/version'
+require 'contrast/utils/object_share'
+require 'contrast/logger/aliased_logging'
+require 'fileutils'
+
+module Contrast
+  module Utils
+    # Method utility used by Contrast::Logger::log
+    module LogUtils
+      DEFAULT_NAME     = 'contrast.log'
+      DEFAULT_LEVEL    = ::Ougai::Logging::Severity::INFO
+      VALID_LEVELS     = ::Ougai::Logging::Severity::SEV_LABEL
+      STDOUT_STR       = 'STDOUT'
+      STDERR_STR       = 'STDERR'
+      PROGNAME         = 'Contrast Agent'
+      DATE_TIME_FORMAT = '%Y-%m-%dT%H:%M:%S.%L%z'
+
+      # StringIO is a valid path because it logs directly to a string buffer
+      def write_permission? path
+        return false if path.nil?
+        return true if path.is_a?(StringIO)
+        return File.writable?(path) if File.exist?(path)
+
+        dir_name = File.dirname(File.absolute_path(path))
+        FileUtils.mkdir_p(dir_name)
+        File.writable?(dir_name)
+      end
+
+      private
+
+      def build path: STDOUT_STR, level_const: DEFAULT_LEVEL, progname: PROGNAME
+        logger = case path
+                 when STDOUT_STR, STDERR_STR
+                   ::Ougai::Logger.new(Object.cs__const_get(path))
+                 else
+                   ::Ougai::Logger.new(path)
+                 end
+        add_contrast_loggers(logger)
+        logger.progname = progname
+        logger.level = level_const
+        logger.formatter = Contrast::Logger::Format.new
+        logger.formatter.datetime_format = DATE_TIME_FORMAT
+        logger
+      end
+
+      def add_contrast_loggers logger
+        logger.extend(Contrast::Logger::Application)
+        logger.extend(Contrast::Logger::Request)
+        logger.extend(Contrast::Logger::Time)
+        logger.extend(Contrast::Logger::AliasedLogging)
+      end
+
+      # Determine the valid path to which to log, given the precedence of config > settings > default.
+      #
+      # @param log_file [String, nil] the file to which to log as provided by the settings retrieved from the
+      #   TeamServer.
+      # @return [String] the path to which to log or STDOUT / STDERR if one of those values provided.
+      def find_valid_path log_file
+        config = ::Contrast::CONFIG.agent.logger
+        config_path = config&.path&.length.to_i.positive? ? config.path : nil
+        valid_path(config_path || log_file)
+      end
+
+      def valid_path path, default_name: DEFAULT_NAME
+        path = path.nil? ? Contrast::Utils::ObjectShare::EMPTY_STRING : path
+        return path if path == STDOUT_STR
+        return path if path == STDERR_STR
+
+        path = default_name if path.empty?
+        if write_permission?(path)
+          path
+        elsif write_permission?(default_name)
+          # Log once when the path is invalid. We'll change to this path, so no
+          # need to log again.
+          if previous_path != default_name
+            $stdout.puts("[!] Unable to write to '#{ path }'. Writing to default log '#{ default_name }' instead.")
+          end
+          default_name
+        else
+          # Log once when the path is invalid. We'll change to this path, so no
+          # need to log again.
+          $stdout.puts("[!] Unable to write to '#{ path }'. Writing to standard out instead.")
+          STDOUT_STR
+        end
+      end
+
+      # Determine the valid level to which to log, given the precedence of config > settings > default.
+      #
+      # @param log_level [String, nil] the level at which to log as provided by the settings retrieved from the
+      #   TeamServer.
+      # @return [::Ougai::Logging::Severity] the level at which to log
+      def find_valid_level log_level
+        config = ::Contrast::CONFIG.agent.logger
+        config_level = config&.level&.length&.positive? ? config.level : nil
+
+        valid_level(config_level || log_level)
+      end
+
+      def valid_level level
+        level ||= DEFAULT_LEVEL
+        level = level.upcase
+        if VALID_LEVELS.include?(level)
+          Object.cs__const_get("::Ougai::Logging::Severity::#{ level }")
+        else
+          DEFAULT_LEVEL
+        end
+      rescue StandardError
+        DEFAULT_LEVEL
+      end
+
+      # Log that the Agent log has changed and include some default information at the start of the log.
+      def log_update
+        logger.debug('Initialized new contrast agent logger')
+        logger.debug_with_time('middleware: log environment') do
+          logger.application_environment
+          logger.application_configuration
+          logger.application_libraries
+        end
+      end
+    end
+  end
+end
+
+module Contrast
+  module Utils
+    # These are the utilities for the CEF Logger, which will use the default ruby logger as we are not
+    # interested in special logging. We have the format we need and that's all we need. It would be useless
+    # to use Ougai
+    module CEFLogUtils
+      include Contrast::Utils::LogUtils
+      # <date> <host> CEF:<version>|<company>|<product>|<agent version>|<event type>
+      # |<event message>|<severity>|<other name-value pairs>
+      DEFAULT_CEF_NAME = 'security.log'
+      DEFAULT_LEVEL    = ::Logger::Severity::INFO
+      VALID_LEVELS     = ::Logger::SEV_LABEL
+      PROGNAME         = 'Contrast Agent Ruby'
+      DATE_TIME_FORMAT = '%b %d %Y %H:%M:%S.%L%z'
+      AGENT_VERSION    = Contrast::Agent::VERSION
+      EVENT_TYPE       = 'SECURITY'
+      DEFAULT_METADATA = '-'
+
+      private
+
+      def build path: STDOUT_STR, level_const: DEFAULT_LEVEL
+        logger = case path
+                 when STDOUT_STR, STDERR_STR
+                   ::Logger.new(Object.cs__const_get(path))
+                 else
+                   ::Logger.new(path)
+                 end
+        logger.progname = PROGNAME
+        logger.level = level_const
+        change_logger_formatter(logger)
+        logger
+      end
+
+      def context
+        Contrast::Agent::REQUEST_TRACKER.current
+      end
+
+      def change_logger_formatter logger
+        ip_address = extract_ip_address
+        logger.formatter = proc do |severity, datetime, progname, msg|
+          date_format = datetime.strftime(DATE_TIME_FORMAT)
+          message = []
+          message << "#{ date_format } #{ ip_address }"
+          message << 'CEF:0|Contrast Security'
+          message << progname
+          message << AGENT_VERSION
+          message << EVENT_TYPE
+          message << msg[0]
+          message << severity
+          message << extract_metadata(msg[1], msg[2])
+          "#{ message.join('|') }\n"
+        end
+      end
+
+      def valid_level level
+        level ||= DEFAULT_LEVEL
+        level = level.upcase
+        if VALID_LEVELS.include?(level)
+          Object.cs__const_get("::Logger::Severity::#{ level }")
+        else
+          DEFAULT_LEVEL
+        end
+      rescue StandardError
+        DEFAULT_LEVEL
+      end
+
+      # This method will extract the metadata information from context and other places
+      #
+      # initial structure of the data:
+      # <metadata> := <message-source>" "<source-ip>" "<source-port>" "<request-url>" "<request-method>" \
+      # "<application>" "<outcome>
+      # it could come from: blockEntry, lei, bbi(bot blocker), vp(virtual patch) or pri(rule)
+      # initially here we will use case to add it
+      def extract_metadata rule_id = nil, outcome = nil
+        message = []
+        request = context&.activity&.request
+        sender_info = { ip: request&.ip || Contrast::Utils::ObjectShare::EMPTY_STRING, port: request&.port || 0 }
+        rule_id ? message << "pri=#{ rule_id } " : 'asd'
+        request_method = assign_request_method(context)
+        app_name = ::Contrast::APP_CONTEXT.name # rubocop:disable Security/Module/Name
+        attach_request_and_sender_info(message, sender_info)
+        message << "request=#{ context.request.url } "
+        message << "requestMethod=#{ request_method } "
+        message << "app=#{ app_name } "
+        message << "outcome=#{ outcome } "
+      end
+
+      def attach_request_and_sender_info message, sender_info
+        # here, instead of the ip, we need to report the first non-private 'X-Forwarded-For' Header if available.
+        # if not we return '-'
+        needed_header = extract_sender_ip
+        # I'm not sure if we should report the sender ip from the ActivityDtm
+        src = if needed_header
+                needed_header
+              else
+                sender_info[:ip].length > 1 ? sender_info[:ip] : DEFAULT_METADATA
+              end
+        message << "src=#{ src }"
+        message << "port=#{ sender_info[:port] }"
+      end
+
+      def extract_ip_address
+        res = Socket.getifaddrs.reject do |ifaddr|
+          !ifaddr.addr.ipv4? ||
+              (ifaddr.flags & Socket::IFF_MULTICAST).zero? ||
+              ifaddr.name != 'en0' # rubocop:disable Security/Module/Name
+        end
+        return unless res.length.positive?
+
+        res[0].addr.ip_address
+      end
+
+      def extract_sender_ip
+        request_headers = context.activity.request.headers&.transform_keys(&:to_s)
+        request_headers['X-Forwarded-For']
+      end
+
+      def assign_request_method context
+        if context.request.rack_request.env['REQUEST_METHOD'].length.positive?
+          context.request.rack_request.env['REQUEST_METHOD']
+        else
+          DEFAULT_METADATA
+        end
+      end
+    end
+  end
+end

data/lib/contrast/utils/lru_cache.rb

@@ -0,0 +1,48 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+module Contrast
+  module Utils
+    # A LRU(Least Recently Used) Cache store.
+    class LRUCache
+      # Initializes new Least Recently Used Cache Store
+      #
+      # @raise [StandardError] raises error if provided capacity is invalid or less or equal to zero
+      def initialize capacity = 500
+        raise(StandardError('Capacity must be bigger than 0')) if capacity <= 0
+
+        @capacity = capacity
+        @cache = {}
+      end
+
+      def [] key
+        val = @cache.delete(key)
+        @cache[key] = val if val
+        val
+      end
+
+      def []= key, value
+        @cache.delete(key)
+        @cache[key] = value
+        @cache.shift if @cache.size > @capacity
+        value # rubocop:disable Lint/Void
+      end
+
+      def keys
+        @cache.keys
+      end
+
+      def key? key
+        @cache.key?(key)
+      end
+
+      def values
+        @cache.values
+      end
+
+      def clear
+        @cache.clear
+      end
+    end
+  end
+end

data/lib/contrast/utils/metrics_hash.rb

@@ -0,0 +1,59 @@
+# 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'
+
+module Contrast
+  module Utils
+    # This is the MetricsHash, which will take data type, so we now what is introduced/included
+    # in the TelemetryEvent
+    class MetricsHash < Hash
+      include Contrast::Components::Logger::InstanceMethods
+
+      attr_reader :data_type
+
+      ERROR_MESSAGES = [
+        'The key is not string or does not meet the requirements.',
+        'The key extends the allowed length.',
+        'The provided value is not the right data type'
+      ].cs__freeze
+      KEY_REGEXP = /[a-zA-Z0-9_-]{1,63}/.cs__freeze
+
+      def initialize data_type, *several_variants
+        super
+        @data_type = data_type
+      end
+
+      def []= key, value
+        key_val = key.dup
+        value_val = value.dup
+        key_val.strip! if key_val.cs__is_a?(String)
+        value_val.strip! if value_val.cs__is_a?(String)
+        return unless valid_pair?(key_val, value_val)
+
+        key_val.downcase!
+        key_val.strip!
+        super(key_val, value_val)
+      end
+
+      def valid_pair? key, value
+        if !key.cs__is_a?(String) || (KEY_REGEXP =~ key).nil?
+          logger.warn('The following key will be omitted', key: key, error: ERROR_MESSAGES[0])
+          return false
+        end
+        unless key.length <= 28
+          logger.warn('The following key will be omitted', key: key, error: ERROR_MESSAGES[1])
+          return false
+        end
+        unless value.cs__is_a?(data_type)
+          logger.warn('The following key will be omitted', value: value, error: ERROR_MESSAGES[2])
+          return false
+        end
+        return false if value.cs__is_a?(String) && value.empty?
+        return false if value.cs__is_a?(String) && value.length > 200
+
+        true
+      end
+    end
+  end
+end

data/lib/contrast/utils/middleware_utils.rb

@@ -0,0 +1,97 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/config/yaml_file'
+require 'contrast/utils/job_servers_running'
+
+module Contrast
+  module Utils
+    # helper methods for Contrast::Agent::Middleware
+    # including disclaimers, deprecation notices, error handling, setup
+    module MiddlewareUtils
+      private
+
+      # TODO: RUBY-1609 update this part of the method for Ruby Version and Year
+      LANGUAGE_DEPRECATION_VERSION = '2.7'
+      LANGUAGE_DEPRECATION_YEAR = '2023'
+      LANGUAGE_DEPRECATION_WARNING =
+        "[Contrast Security] [DEPRECATION] Support for Ruby #{ LANGUAGE_DEPRECATION_VERSION } will be removed in " \
+        "April #{ LANGUAGE_DEPRECATION_YEAR }. Please contact Customer Support prior if you require continued support."
+
+      def setup_agent
+        # Generate new config file if one is not already created:
+        Contrast::Config::YamlFile.create unless Contrast::Config::YamlFile.created?
+        ::Contrast::SETTINGS.reset_state
+
+        inform_deprecations
+        telemetry_disclaimer
+
+        if ::Contrast::CONFIG.invalid?
+          ::Contrast::AGENT.disable!
+          logger.error('!!! CONFIG FILE IS INVALID - DISABLING CONTRAST AGENT !!!')
+        elsif ::Contrast::AGENT.disabled?
+          logger.warn('Contrast disabled by configuration. Continuing without instrumentation.')
+        elsif Contrast::Utils::JobServersRunning.job_servers_running?
+          logger.info('Server job detected disabling Agent...')
+          ::Contrast::AGENT.disable!
+        else
+          ::Contrast::AGENT.enable!
+        end
+      end
+
+      SECURITY_EXCEPTION_MARKER = 'Contrast::SecurityException'
+      # We're only going to suppress SecurityExceptions indicating a blocked attack. And, only if the
+      # config.agent.ruby.exceptions.capture? is set
+      # @raise [Contrast::SecurityException] if exceptions.capture? is allowed
+      def handle_exception exception
+        if security_exception?(exception)
+          exception_control = ::Contrast::AGENT.exception_control
+          raise(exception) unless exception_control[:enable]
+
+          [exception_control[:status], {}, [exception_control[:message]]]
+        else
+          logger.debug('Re-throwing original error', exception)
+          raise(exception)
+        end
+      end
+
+      # Is the given exception one raised by our Protect code?
+      #
+      # @param exception [Exception]
+      # @return [Boolean]
+      def security_exception? exception
+        exception.is_a?(Contrast::SecurityException) || exception.message&.include?(SECURITY_EXCEPTION_MARKER)
+      end
+
+      # As we deprecate support to prepare to remove dead code, we need to inform our users still relying on the now
+      # deprecated and soon to be removed functionality. This method handles doing that by leveraging the standard
+      # Kernel#warn approach
+      def inform_deprecations
+        # Warn customers that they're on a version that's losing support in the next year.
+        Kernel.warn(LANGUAGE_DEPRECATION_WARNING) if RUBY_VERSION.start_with?(LANGUAGE_DEPRECATION_VERSION)
+      end
+
+      # Displays Telemetry disclaimer if Telemetry is enabled.
+      # if .telemetry file doesn't exist we create one and then show the disclaimer.
+      # if the file already exists we do nothing.
+      def telemetry_disclaimer
+        return unless Contrast::Agent::Telemetry::Base.enabled?
+        return unless Contrast::Agent::Telemetry.create_telemetry_file
+
+        logger.info(Contrast::Agent::Telemetry.disclaimer)
+        $stdout.print(Contrast::Agent::Telemetry.disclaimer)
+        true
+      end
+
+      # @raise [Contrast::SecurityException] raises error to prevent an attack
+      def application_code env
+        logger.trace_with_time('application') do
+          app.call(env)
+        end
+      rescue Contrast::SecurityException => e
+        logger.trace('Security Exception raised during application lifecycle to prevent an attack', e)
+        raise(e)
+      end
+    end
+  end
+end

data/lib/contrast/utils/net_http_base.rb

@@ -0,0 +1,173 @@
+# 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/components/logger'
+require 'contrast/utils/object_share'
+require 'socket'
+
+module Contrast
+  module Utils
+    # This module creates a Net::HTTP client base to be used by different services
+    # All HTTP clients reporting to Telemetry or TS should inherit from this
+    class NetHttpBase
+      include Contrast::Components::Logger::InstanceMethods
+      # 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 service_name [String] Name of service used in logging messages
+      # @param url [String]
+      # @param use_proxy [Boolean] flag used to indicate proxy connections [default = false]
+      # @param use_custom_cert [Boolean] flag used to indicate whether the client is to use
+      # self signed certificates provided by config [default = false]
+      # @return [Net::HTTP, nil] Return open connection or nil
+      def initialize_connection service_name, url, use_proxy: false, use_custom_cert: false
+        return unless url
+
+        addr = URI(url)
+        return if addr.host.nil? || addr.port.nil?
+        return if addr.scheme != 'https' && !addr.host.to_s.include?('localhost')
+
+        # the proxy is enabled only if there is provided url even if the enable is set to true
+        proxy_addr = URI(Contrast::API.proxy_url) if proxy_enabled?
+        net_http_client = initialize_client(addr, proxy_addr, use_proxy, use_custom_cert)
+        return if net_http_client.nil?
+
+        net_http_client.start
+        return unless net_http_client.started?
+
+        logger.debug("Starting #{ service_name } connection test")
+        return unless connection_verified?(net_http_client, url)
+
+        logger.debug('Client verified', service: service_name, url: url)
+        net_http_client
+      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('Connection failed', e, service: service_name, url: url)
+        nil
+      end
+
+      # Validates connection with assigned domain.
+      # If connection is running, SSL certificate of the endpoint is valid, Ip address is resolvable
+      # and response is received without peer's reset or refuse of connection, then validation returns true.
+      #
+      # @param client [Net::HTTP]
+      # @param url [String]
+      # @return [Boolean] true | false
+      def connection_verified? client, url
+        return @_connection_verified unless @_connection_verified.nil?
+        return false if client.nil?
+
+        ipaddr = get_ipaddr(client)
+        response = client.request(Net::HTTP::Get.new(url))
+        verify_cert = client.address.to_s.include?('localhost') ||
+            OpenSSL::SSL.verify_certificate_identity(client.peer_cert, client.address)
+        resolved = resolved?(client.address, ipaddr)
+        @_connection_verified = if resolved && response && verify_cert
+                                  true
+                                else
+                                  false
+                                end
+      rescue OpenSSL::SSL::SSLError, Resolv::ResolvError, Errno::ECONNRESET, Errno::ECONNREFUSED,
+             Errno::ETIMEDOUT, Errno::ESHUTDOWN, Errno::EHOSTDOWN, Errno::EHOSTUNREACH, Errno::EISCONN,
+             Errno::ECONNABORTED, Errno::ENETRESET, Errno::ENETUNREACH => 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("#{ service_name } connection failed", e.message)
+        false
+      end
+
+      private
+
+      # Resolves the address of the assigned domain to array of corresponding IPs (if more than one)
+      # and runs a matcher to see if current connection IP is in the list.
+      # This is called within #verify_connection, if called on it's own there will be no
+      # error handling.
+      #
+      # @param address [String] Human friendly address of assigned domain
+      # @param ipaddr [String] Machine friendly IP address of the assigned domain
+      # @return[Boolean] true if both addresses are resolved | false if one of the addresses
+      # is non-resolvable
+      def resolved? address, ipaddr
+        return @_resolved unless @_resolved.nil?
+
+        @_resolved = if (addresses = Resolv.getaddresses(address))
+                       addresses.any? { |addr| addr.include?(ipaddr) }
+                     else
+                       false
+                     end
+      end
+
+      # if the configuration for the use of self-signed certificates is enabled
+      # and required for this client then assign the files and keys to the client
+      #
+      # @param client [Net::HTTP]
+      def assign_cert client
+        if Contrast::API.certification_ca_file
+          client.ca_file = OpenSSL::X509::Certificate.new(File.read(Contrast::API.certification_ca_file)).to_s
+        elsif Contrast::API.certification_cert_file
+          client.cert = OpenSSL::X509::Certificate.new(File.read(Contrast::API.certification_cert_file)).to_s
+        elsif Contrast::API.certification_key_file
+          client.key = OpenSSL::PKey::RSA.new(File.read(Contrast::API.certification_key_file)).to_s
+        end
+      rescue Errno::ENOENT => 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('Custom certificates failed', e.message)
+      end
+
+      # sets default setting for client validation of certificates and
+      # timeout options
+      #
+      # @param addr [URI::Generic] uri of assigned domain
+      # @param proxy_addr [URI::Generic | nil] uri of proxy
+      # @param use_proxy [Boolean] flag used to indicate proxy connections [default = false]
+      # @param use_custom_cert [Boolean] flag used to indicate whether the client is to use
+      # self signed certificates provided by config [default = false]
+      # @return [Net::HTTP]
+      def initialize_client addr, proxy_addr, use_proxy, use_custom_cert
+        initialize_client = if proxy_enabled? && use_proxy
+                              Net::HTTP.new(addr.host, nil, proxy_addr&.host, proxy_addr&.port)
+                            else
+                              Net::HTTP.new(addr.host, addr.port)
+                            end
+        return initialize_client if addr.host.to_s.include?('localhost') # TODO: RUBY-99999 allow http w/ localhost
+
+        assign_cert(initialize_client) if use_custom_cert && Contrast::API.certification_enable
+        initialize_client.use_ssl = true
+        initialize_client.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        initialize_client.verify_depth = 5
+        # open connection timeout in ms
+        # if connection reaches timeout this will produce Net::OpenTimeout error
+        initialize_client.open_timeout = 15
+        # if we can't read the response or a chunk within time this will cause a
+        # Net::ReadTimeout error when the request is made
+        initialize_client.read_timeout = 15
+        initialize_client
+      end
+
+      # Check if proxy is enabled
+      #
+      # @return @_proxy_enabled [Boolean] True if proxy is enabled and url is present else false
+      def proxy_enabled?
+        return @_proxy_enabled unless @_proxy_enabled.nil?
+
+        @_proxy_enabled = Contrast::API.proxy_enable && !Contrast::API.proxy_url.nil?
+      end
+
+      # Retrieve the IP address from the client.
+      #
+      # @param client [Net::HTTP]
+      # @return [String]
+      def get_ipaddr client
+        socket = TCPSocket.open(client.address, client.port)
+        ipaddr = socket.peeraddr[3]
+        socket.close
+        ipaddr
+      end
+    end
+  end
+end