contrast-agent 6.1.2 → 6.4.0

data/lib/contrast/framework/base_support.rb

@@ -1,43 +1,52 @@
 # Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
 # frozen_string_literal: true
 
+require 'contrast/agent/reporting/reporting_events/discovered_route'
+
 module Contrast
   module Framework
     # The API for all subclasses to implement to correctly support a given framework
     module BaseSupport
       # The top level module name used by the framework
+      # @raise [NoMethodError] raises error if subclass does not implement this method
       def detection_class
         raise(NoMethodError('Subclasses of BaseSupport should implement this method'))
       end
 
+      # @raise [NoMethodError] raises error if subclass does not implement this method
       def version
         raise(NoMethodError('Subclasses of BaseSupport should implement this method'))
       end
 
+      # @raise [NoMethodError] raises error if subclass does not implement this method
       def application_name
         raise(NoMethodError, 'Subclasses of BaseSupport should implement this method')
       end
 
+      # @raise [NoMethodError] raises error if subclass does not implement this method
       def server_type
         raise(NoMethodError, 'Subclasses of BaseSupport should implement this method')
       end
 
-      # Find all the predefined routes for this application and append them to the
-      # provided inventory message
-      # msg should be a Contrast::Api::Dtm::ApplicationUpdate or some other msg
-      # that has a routes array consisting of Contrast::Api::Dtm::RouteCoverage
+      # Find all the predefined routes for this application
+      #
+      # @return [Array<Contrast::Agent::Reporting::DiscoveredRoute>]
+      # @raise [NoMethodError] raises error if subclass does not implement this method
       def collect_routes
         raise(NoMethodError, 'Subclasses of BaseSupport should implement this method')
       end
 
+      # @raise [NoMethodError] raises error if subclass does not implement this method
       def current_route_coverage
         raise(NoMethodError, 'Subclasses of BaseSupport should implement this method')
       end
 
+      # @raise [NoMethodError] raises error if subclass does not implement this method
       def current_route
         raise(NoMethodError, 'Subclasses of BaseSupport should implement this method')
       end
 
+      # @raise [NoMethodError] raises error if subclass does not implement this method
       def retrieve_request _env
         raise(NoMethodError, 'Subclasses of BaseSupport should implement this method')
       end

data/lib/contrast/framework/grape/support.rb

@@ -49,7 +49,7 @@ module Contrast
 
           # Find all classes that subclass ::Grape::API, Gather their routes
           #
-          # @return [Array<Contrast::Api::Dtm::RouteCoverage>, Array]- founded routes as Dtms
+          # @return [Array<Contrast::Agent::Reporting::DiscoveredRoute>]
           def collect_routes
             return Contrast::Utils::ObjectShare::EMPTY_ARRAY unless grape_defined?
 
@@ -60,8 +60,8 @@ module Contrast
               c&.endpoints&.each do |endpoint|
                 endpoint&.routes&.map do |r|
                   pattern = r.pattern.pattern
-                  temp = Contrast::Api::Dtm::RouteCoverage.from_grape_controller(c, r.request_method, pattern, r.path)
-                  routes << temp
+                  routes << Contrast::Agent::Reporting::DiscoveredRoute.from_grape_controller(c, r.request_method,
+                                                                                              pattern, r.path)
                 end
               end
             end
@@ -140,8 +140,8 @@ module Contrast
           # @param method [::Rack::REQUEST_METHOD] GET, POST, PUT, etc...
           # @param route [String] the relative route passed from Rack.
           # @param controllers [Array<::Grape::API>] All Grape controllers found
-          # @return [Array[::Grape::API]], nil] Either the controller that
-          # will handle the route along with the route pattern or nil if no match.
+          # @return [Array[::Grape::API. Grape::Router::Route], nil] Either the controller that will handle the route
+          #   along with the route pattern or nil if no match.
           def _route_recurse method, route, controllers = grape_controllers
             # return if there aren't any controllers
             return unless controllers&.any?
@@ -155,7 +155,7 @@ module Contrast
 
             contr_routes = controller.endpoints&.map(&:routes)&.flatten || []
             route_pattern = contr_routes&.find do |r|
-              r.pattern.to_regexp.match(route) # ::Mustermann::Grape match
+              r.pattern.to_regexp.match(route) # Grape::Router::Route match
             end
             return controller, route_pattern unless route_pattern.nil?
 

data/lib/contrast/framework/manager.rb

@@ -7,7 +7,6 @@ require 'contrast/components/logger'
 require 'contrast/extension/module'
 require 'contrast/framework/grape/support'
 require 'contrast/framework/manager_extend'
-require 'contrast/framework/platform_version'
 require 'contrast/framework/rack/support'
 require 'contrast/framework/rails/support'
 require 'contrast/framework/sinatra/support'
@@ -59,20 +58,11 @@ module Contrast
         patches
       end
 
+      # @return [Array<Contrast::Agent::Reporting::DiscoveredRoute>]
       def find_route_discovery_data
         routes_for_all_frameworks
       end
 
-      def platform_version
-        framework_version = first_framework_result(:version, '')
-
-        Contrast::Framework::PlatformVersion.from_string(framework_version)
-      end
-
-      def platform_version_string
-        first_framework_result(:version, '')
-      end
-
       def server_type
         first_framework_result(:server_type, 'rack')
       end
@@ -156,19 +146,13 @@ module Contrast
           next unless module_name == framework.detection_class
 
           @_frameworks << framework
-          # Report the registered routes of that framework now that we know we need to find them
-          # TODO: RUBY-1438 -- remove and build ReportingEvent directly
-          app_update_msg = Contrast::Api::Dtm::ApplicationUpdate.build
-          if Contrast::Agent.reporter
-            report = Contrast::Agent::Reporting::DtmMessage.dtm_to_event(app_update_msg)
-            Contrast::Agent.reporter.send_event(report)
-
-            # This is being reported separately because we extract the data from the same message
-            inventory_report = Contrast::Agent::Reporting::ApplicationInventory.convert(app_update_msg)
-            Contrast::Agent.reporter.send_event(inventory_report)
-          else
-            Contrast::Agent.messaging_queue.send_event_eventually(app_update_msg)
+          report = Contrast::Agent::Reporting::ApplicationUpdate.new
+          # This convert here is left as it'll be easier to be replaced when the Library is being changed
+          report.libraries = Contrast::Agent::Inventory::DependencyAnalysis.instance.library_pb_list
+          [report, Contrast::Agent::Reporting::ApplicationInventory.new].each do |e|
+            Contrast::Agent.reporter.send_event(e)
           end
+
           logger.info('Framework detected after initialization. Enabling support.',
                       framework: framework.detection_class,
                       frameworks: @_frameworks)

data/lib/contrast/framework/manager_extend.rb

@@ -3,7 +3,6 @@
 
 require 'contrast/components/logger'
 require 'contrast/extension/module'
-require 'contrast/framework/platform_version'
 require 'contrast/framework/rack/support'
 require 'contrast/framework/rails/support'
 require 'contrast/framework/grape/support'
@@ -20,6 +19,7 @@ module Contrast
         Contrast::Utils::ClassUtil.truly_defined?(klass)
       end
 
+      # @return [Array<Contrast::Agent::Reporting::DiscoveredRoute>]
       def routes_for_all_frameworks
         data_for_all_frameworks(:collect_routes)
       end

data/lib/contrast/framework/rails/patch/action_controller_live_buffer.rb

@@ -1,6 +1,8 @@
 # Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
 # frozen_string_literal: true
 
+require 'contrast/agent/inventory/dependency_usage_analysis'
+
 module Contrast
   module Framework
     module Rails
@@ -9,26 +11,20 @@ module Contrast
         # event on streamed responses.
         module ActionControllerLiveBuffer
           class << self
-            # TODO: RUBY-1353
-            # TODO: RUBY-1355
-            # TODO: RUBY-1357
-            # TODO: RUBY-1357
             def send_messages
               return unless (context = Contrast::Agent::REQUEST_TRACKER.current)
 
+              [
+                context.observed_route
+              ].each do |event|
+                Contrast::Agent.reporter&.send_event_immediately(event)
+              end
+
               if Contrast::Agent::Reporter.enabled?
-                [
-                  context.new_observed_route,
-                  Contrast::Agent::Reporting::DtmMessage.dtm_to_event(context.server_activity),
-                  Contrast::Agent::Reporting::DtmMessage.dtm_to_event(context.activity.library_usages),
-                  Contrast::Agent::Reporting::DtmMessage.dtm_to_event(context.activity)
-                ].each do |event|
-                  Contrast::Agent.reporter&.send_event_immediately(event)
-                end
+                event = Contrast::Agent::Reporting::DtmMessage.dtm_to_event(context.activity)
+                Contrast::Agent.reporter&.send_event_immediately(event)
               else
-                [context.server_activity, context.activity, context.observed_route].each do |msg|
-                  Contrast::Agent.messaging_queue&.send_event_immediately(msg)
-                end
+                Contrast::Agent.messaging_queue&.send_event_immediately(context.activity)
               end
             end
 

data/lib/contrast/framework/rails/support.rb

@@ -44,6 +44,7 @@ module Contrast
             'rails'
           end
 
+          # @return [Array<Contrast::Agent::Reporting::DiscoveredRoute>]
           def collect_routes
             find_all_routes(::Rails.application, [])
           end
@@ -138,7 +139,8 @@ module Contrast
             route.app.is_a?(::ActionDispatch::Routing::Mapper::Constraints) && route.app.app < ::Rails::Engine
           end
 
-          # Recursively get final route traversing engines as required.
+          # Recursively get final route traversing engines as required. Because this can only be called once, we store
+          # this match for the duration of our request context.
           #
           # @param request [::Rack::Request] the rack request as will be handed to rails controller.
           # @param top_router [::ActionDispatch::Journey::Router] the current router relative to the previous.
@@ -162,12 +164,17 @@ module Contrast
           end
 
           # Rails engine routes need to be detected by inspecting Engine class route set
+          #
+          # @param app [Rails::Application]
+          # @param route_list [Array<Contrast::Agent::Reporting::DiscoveredRoute>] the list of discovered routes to
+          #   which to append and return
+          # @return [Array<Contrast::Agent::Reporting::DiscoveredRoute>]
           def find_all_routes app, route_list
             return route_list unless app.cs__respond_to?(:routes) && app.routes.cs__respond_to?(:routes)
 
             app.routes.routes.each do |route|
               if route.cs__respond_to?(:app) && route.app.cs__class == ActionDispatch::Routing::RouteSet::Dispatcher
-                route_list << Contrast::Api::Dtm::RouteCoverage.from_action_dispatch_journey(route)
+                route_list << Contrast::Agent::Reporting::DiscoveredRoute.from_action_dispatch_journey(route)
               elsif route.app.app.cs__respond_to?(:routes)
                 route_list += find_all_routes(route.app.app, [])
               end

data/lib/contrast/framework/sinatra/support.rb

@@ -47,7 +47,7 @@ module Contrast
 
           # Find all classes that subclass ::Sinatra::Base. Gather their routes.
           #
-          # @return [Array<Contrast::Api::Dtm::RouteCoverage>] the routes found as Dtms.
+          # @return [Array<Contrast::Agent::Reporting::DiscoveredRoute>]
           def collect_routes
             return Contrast::Utils::ObjectShare::EMPTY_ARRAY unless defined?(::Sinatra) && defined?(::Sinatra::Base)
 
@@ -56,7 +56,8 @@ module Contrast
               controller.routes.each_pair do |method, route_triplets|
                 # Sinatra stores its routes as a triplet: [Mustermann::Sinatra, [], Proc]
                 route_triplets.map(&:first).each do |route_pattern|
-                  routes << Contrast::Api::Dtm::RouteCoverage.from_sinatra_route(controller, method, route_pattern)
+                  routes << Contrast::Agent::Reporting::DiscoveredRoute.from_sinatra_route(controller, method,
+                                                                                           route_pattern)
                 end
               end
             end

data/lib/contrast/logger/aliased_logging.rb

@@ -17,7 +17,7 @@ module Contrast
       # @param data [Object] Any structured data
       def warn message = nil, exception = nil, data = nil, &block
         # build Telemetry Exclusion
-        build_exclusion(ALIASED_WARN, message, exception, data)
+        build_exception(ALIASED_WARN, message, exception, data)
         super(message, exception, data, &block)
       end
 
@@ -26,7 +26,7 @@ module Contrast
       # @param data [Object] Any structured data
       def error message = nil, exception = nil, data = nil, &block
         # build Telemetry Exclusion
-        build_exclusion(ALIASED_ERROR, message, exception, data)
+        build_exception(ALIASED_ERROR, message, exception, data)
         super(message, exception, data, &block)
       end
 
@@ -35,35 +35,35 @@ module Contrast
       # @param data [Object] Any structured data
       def fatal message = nil, exception = nil, data = nil, &block
         # build Telemetry Exclusion
-        build_exclusion(ALIASED_FATAL, message, exception, data)
+        build_exception(ALIASED_FATAL, message, exception, data)
         super(message, exception, data, &block)
       end
 
       private
 
-      def build_exclusion _type, _message = nil, _exception = nil, _data = nil
-        # TODO: RUBY-1698
-        nil
-        #   start = caller_locations&.find_index { |stack| stack.to_s.include?(type) }
-        #   stack_trace = start ? caller_locations(start + 1, 20) : caller_locations(20, 20)
-        #   stack_frame_type = Contrast::Agent::Telemetry::TelemetryException::Obfuscate.obfuscate_type(
-        #       stack_trace[1].path.delete_prefix(Dir.pwd))
-        #   message_exception_type = Contrast::Agent::Telemetry::TelemetryException::Obfuscate.obfuscate_exception_type(
-        #       exception ? exception.cs__class.to_s : stack_frame_type.split('/').last)
-        #   stack_frame_function = stack_trace[1].label
-        #   key = "#{ stack_frame_type }|#{ stack_frame_function }|#{ message }"
-        #   if TELEMETRY_EXCEPTIONS[key]
-        #     TELEMETRY_EXCEPTIONS.increment(key)
-        #     return
-        #   end
-        #
-        #   event_message = create_message(stack_frame_function,
-        #                                  stack_frame_type, message_exception_type,
-        #                                  data, exception,
-        #                                  message)
-        #   TELEMETRY_EXCEPTIONS[key] = event_message
-        # rescue StandardError => e
-        #   debug('Unable to report exception to telemetry', e)
+      def build_exception type, message = nil, exception = nil, data = nil
+        stack_trace = get_stack_trace(type)
+        stack_frame_type = Contrast::Agent::Telemetry::TelemetryException::Obfuscate.obfuscate_type(
+            stack_trace[1].path.delete_prefix(Dir.pwd))
+        stack_frame_function = stack_trace[1].label
+        key = "#{ stack_frame_type }|#{ stack_frame_function }|#{ message }"
+        if TELEMETRY_EXCEPTIONS[key]
+          TELEMETRY_EXCEPTIONS.increment(key)
+          return
+        end
+
+        return if TELEMETRY_EXCEPTIONS.exception_limit?
+
+        message_exception_type = Contrast::Agent::Telemetry::TelemetryException::Obfuscate.obfuscate_exception_type(
+            exception ? exception.cs__class.to_s : stack_frame_type.split('/').last)
+
+        event_message = create_message(stack_frame_function,
+                                       stack_frame_type, message_exception_type,
+                                       data, exception,
+                                       message)
+        TELEMETRY_EXCEPTIONS[key] = event_message
+      rescue StandardError => e
+        debug('Unable to report exception to telemetry', e)
       end
 
       def create_message stack_frame_function, stack_frame_type, message_exception_type, data, exception, message
@@ -88,6 +88,13 @@ module Contrast
                end
         message = Contrast::Agent::Telemetry::TelemetryException::Message.build(tags, [message_exception])
         Contrast::Agent::Telemetry::TelemetryException::Event.new(message)
+      rescue ArgumentError => e
+        debug('TelemetryException failed from aliased logging with: ', e)
+      end
+
+      def get_stack_trace type
+        start = caller_locations&.find_index { |stack| stack.to_s.include?(type) }
+        start ? caller_locations(start + 1, 20) : caller_locations(20, 20)
       end
     end
   end

data/lib/contrast/utils/assess/source_method_utils.rb

@@ -7,15 +7,6 @@ module Contrast
       # This module will include all methods for some internal validations in the SourceMethod module
       # and some other module methods from the same place, so we can ease the main module
       module SourceMethodUtils
-        # Safely duplicate the target, or return nil
-        #
-        # @param target [Object] the thing to check for duplication
-        def safe_dup target
-          target.dup
-        rescue StandardError => _e
-          nil
-        end
-
         # Find the name of the source
         #
         # @param source_node [Contrast::Agent::Assess::Policy::SourceNode] the node to direct applying this source

data/lib/contrast/utils/lru_cache.rb

@@ -5,6 +5,9 @@ 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
 

data/lib/contrast/utils/middleware_utils.rb

@@ -34,6 +34,7 @@ module Contrast
       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
@@ -74,6 +75,7 @@ module Contrast
         true
       end
 
+      # @raise [Contrast::SecurityException] raises error to prevent an attack
       def application_code env
         logger.trace_with_time('application') do
           app.call(env)

data/lib/contrast/utils/patching/policy/patch_utils.rb

@@ -7,18 +7,6 @@ module Contrast
       # This module will include all methods for different patch applies from Patch module and some other module
       # methods from the same place, so we can ease the main module
       module PatchUtils
-        # Method to choose which replaced return from the post_patch to actually return.
-        #
-        # @param propagated_ret [Object, nil] The replaced return from the propagation patch.
-        # @param source_ret [Object, nil] The replaced return from the source patch.
-        # @param ret [Object, nil] The original return of the patched method.
-        # @return [Object, nil] The thing to return from the post patch.
-        def handle_return propagated_ret, source_ret, ret
-          safe_return = propagated_ret || source_ret || ret
-          safe_return.rewind if Contrast::Utils::IOUtil.should_rewind?(safe_return)
-          safe_return
-        end
-
         # Given a module and method, construct an expected name for the alias by which Contrast will reference the
         # original.
         #
@@ -123,8 +111,6 @@ module Contrast
         # @param args [Array<Object>] The arguments passed to the method being invoked.
         # @param block [Proc] The block passed to the method that was invoked.
         def apply_assess method_policy, preshift, object, ret, args, block
-          source_ret = nil
-          propagated_ret = nil
           return ret unless method_policy && ::Contrast::ASSESS.enabled?
 
           current_context = Contrast::Agent::REQUEST_TRACKER.current
@@ -135,27 +121,24 @@ module Contrast
             Contrast::Agent::Assess::Policy::TriggerMethod.apply_trigger_rule(trigger_node, object, ret, args)
           end
           if method_policy.source_node
-            # If we were given a frozen return, and it was the target of a source, and we have frozen sources enabled,
-            # we'll need to replace the return. Note, this is not the default case.
-            source_ret = Contrast::Agent::Assess::Policy::SourceMethod.apply_source(method_policy, object, ret, args)
+            Contrast::Agent::Assess::Policy::SourceMethod.apply_source(method_policy, object, ret, args)
           end
           if method_policy.propagation_node
-            propagated_ret = Contrast::Agent::Assess::Policy::PropagationMethod.apply_propagation(
+            Contrast::Agent::Assess::Policy::PropagationMethod.apply_propagation(
                 method_policy,
                 preshift,
                 object,
-                source_ret || ret,
+                ret,
                 args,
                 block)
           end
-          handle_return(propagated_ret, source_ret, ret)
         rescue StandardError => e
           logger.error('Unable to assess method call.', e)
-          handle_return(propagated_ret, source_ret, ret)
         rescue Exception => e # rubocop:disable Lint/RescueException
           logger.error('Unable to assess method call.', e)
-          handle_return(propagated_ret, source_ret, ret)
           raise(e)
+        ensure
+          ret.rewind if Contrast::Utils::IOUtil.should_rewind?(ret)
         end
 
         # Generic invocation of the Inventory or Protect patch which apply to the given method.

data/lib/contrast/utils/response_utils.rb

@@ -34,7 +34,7 @@ module Contrast
       # @return [nil, String] the content of the body
       def extract_body body
         return unless body
-        return if defined?(Rack::File) && body.is_a?(Rack::File)
+        return if body_is_file?(body)
 
         return handle_rack_body_proxy(body) if body.is_a?(Rack::BodyProxy)
         return extract_body(body.body) if sub_extractable?(body)
@@ -77,6 +77,19 @@ module Contrast
           obj.to_s
         end
       end
+
+      # After Rack 3.1 gets live - line 88 (Rack::File) will be removed.
+      # In 3.1 version, they drop the support for File class and will only support Files class
+      #
+      # @param body [String, Rack::File, Rack::BodyProxy,
+      #   ActionDispatch::Response::RackBody, Rack::Response] Something that
+      #   holds, wraps, or is the body of the Response
+      def body_is_file? body
+        return true if defined?(Rack::File) && (body.is_a?(Rack::File) || body.is_a?(Rack::File::Iterator))
+        return true if defined?(Rack::Files) && (body.is_a?(Rack::Files) || body.is_a?(Rack::Files::Iterator))
+
+        false
+      end
     end
   end
 end

data/lib/contrast/utils/telemetry.rb

@@ -34,10 +34,16 @@ module Contrast
         write_mark_file(DIR, FILE, CONFIG_DIR)
       end
 
+      # The telemetry disclaimer message, set if needed.
+      #
+      # @return [String]
       def self.disclaimer
         @_disclaimer = MESSAGE[:disclaimer]
       end
 
+      # Determine if telemetry has been explicitly disabled by opt out or has been left running.
+      #
+      # @return [Boolean]
       def self.exceptions_enabled?
         @_exceptions_enabled = telemetry_exceptions_enabled? if @_exceptions_enabled.nil?
         @_exceptions_enabled
@@ -82,6 +88,9 @@ module Contrast
           false
         end
 
+        # Determine if telemetry has been explicitly disabled by opt out or has been left running.
+        #
+        # @return [Boolean]
         def telemetry_exceptions_enabled?
           opts_out_telemetry = return_value(:telemetry_opt_outs).to_s
           return false if opts_out_telemetry.casecmp?('true') || opts_out_telemetry == '1'

data/lib/contrast/utils/telemetry_client.rb

@@ -34,8 +34,8 @@ module Contrast
       def build_request event
         return unless valid_event?(event)
 
-        string_body = if Array(event).all?(Contrast::Agent::Telemetry::TelemetryException::Event)
-                        event.map(&:to_controlled_hash).flatten!
+        string_body = if event.cs__is_a?(Contrast::Agent::Telemetry::TelemetryException::Event)
+                        [event.to_controlled_hash]
                       else
                         [event.to_hash]
                       end
@@ -73,14 +73,14 @@ module Contrast
         ready_after if status_code == 429
       end
 
-      # This method will be responsible for validating the event
-      # @param event[Contrast::Agent::Telemetry::Event,Contrast::Agent::Telemetry::StartupMetricsEvent,
-      # array<Contrast::Agent::Telemetry::TelemetryException::Event>]
+      # 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)
-        # Batch
-        return true if Array(event).all?(Contrast::Agent::Telemetry::TelemetryException::Event)
+        return true if event.cs__is_a?(Contrast::Agent::Telemetry::TelemetryException::Event)
 
         false
       end

data/lib/contrast/utils/telemetry_hash.rb

@@ -2,34 +2,58 @@
 # frozen_string_literal: true
 
 require 'contrast/components/logger'
+require 'contrast/agent/telemetry/events/exceptions/telemetry_exception_event'
 
 module Contrast
   module Utils
-    # This is the TelemetryHash, which will take data type, so we can push freely, without worrying about
-    # validating the event before that
+    # This is the TelemetryHash, which will store Contrast::Agent::Telemetry::TelemetryException::Event, so we can push
+    # freely, without worrying about validating the event before that.  TelemetryHash has a max size of events,
+    # default is 10 events
     class TelemetryHash < Hash
       include Contrast::Components::Logger::InstanceMethods
+      HASH_SIZE_LIMIT = 10
 
-      attr_reader :data_type
-
-      def initialize data_type, *_several_variants
-        super()
-        @data_type = data_type
-      end
-
+      # Wrapper to set a value in this TelemetryHash only if the provided value is of the data_type for this
+      # TelemetryHash 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
+        return if exception_limit?
         return unless valid_value?(value)
 
         super(key, value)
       end
 
+      # Increment the occurrences for the exception object contained in this TelemetryHash
+      #
+      # @param key [Object] the key to check for the exception stored in this TelemetryHash
       def increment key
-        self[key].exceptions[0].increment_occurrences
-        :incremented!
+        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 TelemetryHash contains
+      # @param value [Object]
+      # @return boolean
       def valid_value? value
-        unless value.cs__is_a?(data_type)
+        unless value.cs__is_a?(Contrast::Agent::Telemetry::TelemetryException::Event)
           logger.debug('The following key will be omitted', value: value)
           return false
         end

data/lib/contrast/utils/telemetry_identifier.rb

@@ -38,6 +38,10 @@ module Contrast
           @_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
@@ -48,6 +52,10 @@ module Contrast
           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::Utils::Telemetry::Identifier.mac ||
                                                               "_#{ SecureRandom.uuid }")