contrast-agent 4.13.0 → 5.0.0

data/lib/contrast/agent/startup_metrics_telemetry_event.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
 # frozen_string_literal: true
 
 require 'contrast/utils/metrics_hash'
@@ -17,14 +17,41 @@ module Contrast
       include Contrast::Utils::OS
 
       APP_AND_SERVER_DATA = ::Contrast::APP_CONTEXT.app_and_server_information.cs__freeze
-      SAAS_DEFAULT = { addr: 'app.contrastsecuirty.com', type: 'SAAS_DEFAULT' }.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
-      SAAS_CUSTOM = { addr: 'contrastsecurite.com', type: 'SAAS_CUSTOM' }.cs__freeze
-      SAAS_POV = { addr: 'eval.contrastsecuirty.com', type: 'SAAS_POV' }.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 = [:EMPTY_VALUE, 'NEEDS_TO_BE_SET', Contrast::Utils::ObjectShare::EMPTY_STRING].cs__freeze
 
       def initialize
         super
+        @settings = []
+        add_config_keys ::Contrast::CONFIG.root, 'root'
+        @settings << ENV.keys.select { |v| v.starts_with?('CONTRAST') }
+        @settings.flatten
         add_tags
       end
 
@@ -33,14 +60,25 @@ module Contrast
       end
 
       def add_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']
+        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.configuration_map.reject! { |_k, v| REJECTED_VALUES.include?(v) }
+
+        config.configuration_map.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
@@ -50,21 +88,33 @@ module Contrast
 
       private
 
-      # Here we extract the Teamserver url type
+      # Here we extract the TeamServer url type
       #
-      # @return[String] type, it could be SAAS_DEFAULT, SAAS_POV, SAAS_CE, SAAS_CUSTOM, or EOP
+      # @return [String] the type of TeamServer environment to which we're connecting
       def teamserver_type
-        @_teamserver_type ||= if Contrast::API.api_url.include?(SAAS_DEFAULT[:addr])
-                                SAAS_DEFAULT[:type]
-                              elsif Contrast::API.api_url.include?(SAAS_POV[:addr])
-                                SAAS_POV[:type]
-                              elsif Contrast::API.api_url.include?(SAAS_CE[:addr])
-                                SAAS_CE[:type]
-                              elsif Contrast::API.api_url.end_with? SAAS_CUSTOM[:addr]
-                                SAAS_CUSTOM[:type]
-                              else
-                                EOP
-                              end
+        @_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

data/lib/contrast/agent/static_analysis.rb

@@ -1,8 +1,9 @@
-# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
 # frozen_string_literal: true
 
 require 'contrast/components/logger'
 require 'contrast/components/scope'
+require 'contrast/agent/reporting/reporting_events/application_update'
 require 'contrast/api/decorators/application_update'
 
 module Contrast
@@ -10,8 +11,8 @@ module Contrast
     # this module handles one time static analysis tasks
     class StaticAnalysis
       include Singleton
-      include Contrast::Components::Logger::InstanceMethods
       include Contrast::Components::Scope::InstanceMethods
+      extend Contrast::Components::Logger::InstanceMethods
 
       class << self
         # After the first request is complete, we do a one-time manual catchup to review and report the already-loaded
@@ -23,7 +24,6 @@ module Contrast
           end
         end
 
-        # TODO: RUBY-1354
         # TODO: RUBY-1356
         def send_inventory_message
           return unless ::Contrast::INVENTORY.enabled?
@@ -31,7 +31,17 @@ module Contrast
           app_update_msg = Contrast::Api::Dtm::ApplicationUpdate.build
 
           Contrast::Agent::Inventory::DatabaseConfig.append_db_config(app_update_msg)
-          Contrast::Agent.messaging_queue.send_event_eventually(app_update_msg)
+          # TODO: RUBY-1438 -- remove and build ReportingEvent directly
+          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)
+          end
         end
 
         private

data/lib/contrast/agent/telemetry.rb

@@ -1,9 +1,9 @@
-# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# Copyright (c) 2022 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/utils/requests_client'
+require 'contrast/utils/telemetry_client'
 require 'contrast/agent/worker_thread'
 require 'contrast/utils/telemetry'
 
@@ -11,7 +11,6 @@ module Contrast
   module Agent
     # This class will initialize and hold everything needed for the telemetry
     class Telemetry < WorkerThread
-      include Contrast::Utils::RequestsClient
       include Contrast::Components::Logger::InstanceMethods
       # this is where we will send the data from the agents
       URL = 'https://telemetry.ruby.contrastsecurity.com/'
@@ -28,13 +27,13 @@ module Contrast
             mac = Contrast::Utils::Telemetry::Identifier.mac
             app_name = Contrast::Utils::Telemetry::Identifier.app_name
             id = mac + app_name if mac && app_name
-            Digest::SHA2.new(256).hexdigest(id || '_' + SecureRandom.uuid)
+            Digest::SHA2.new(256).hexdigest(id || ('_' + SecureRandom.uuid))
           end
         end
 
         def instance_id
           @_instance_id ||= Digest::SHA2.new(256).hexdigest(Contrast::Utils::Telemetry::Identifier.mac ||
-                                                                  '_' + SecureRandom.uuid)
+                                                                  ('_' + SecureRandom.uuid))
         end
 
         def enabled?
@@ -51,7 +50,8 @@ module Contrast
 
           # In case of connection error, do not create the background thread or queue,
           # as if the opt-out env var was set
-          ip_opt_out_telemetry = Contrast::Utils::RequestsClient.initialize_connection(URL)
+          @_client = Contrast::Utils::TelemetryClient.new
+          ip_opt_out_telemetry = @_client.initialize_connection(URL)
           if ip_opt_out_telemetry.nil?
             logger.warn('Connection was not established properly!!!')
             logger.warn('THE SERVICE IS GOING TO BE TERMINATED!!')
@@ -62,6 +62,14 @@ module Contrast
         end
       end
 
+      def client
+        @_client ||= Contrast::Utils::TelemetryClient.new
+      end
+
+      def connection
+        @_connection ||= client.initialize_connection(URL)
+      end
+
       def attempt_to_start?
         unless cs__class.enabled?
           logger.warn('Telemetry service is disabled!')
@@ -83,8 +91,8 @@ module Contrast
 
           begin
             logger.debug('This is the current processed event', event)
-            res = Contrast::Utils::RequestsClient.send_request event, connection
-            sleep_time = Contrast::Utils::RequestsClient.handle_response res
+            res = client.send_request event, connection
+            sleep_time = client.handle_response res
             sleep(sleep_time) unless sleep_time.nil?
           rescue StandardError => e
             logger.error('Could not send message to service from telemetry queue.', e)

data/lib/contrast/agent/telemetry_event.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
 # frozen_string_literal: true
 
 require 'contrast/utils/metrics_hash'
@@ -11,23 +11,22 @@ module Contrast
 
       attr_reader :timestamp, :tags
 
-      # The instance_id comes from the Telemetry Instance
       def initialize
         @tags = MetricsHash.new(String)
-        @timestamp = format_date
-        @instance_id = Contrast::Agent.telemetry_queue.__id__
+        @timestamp = Time.now.iso8601
       end
 
       def path
         ''
       end
 
-      def to_json **_args
-        { tags: @tags, timestamp: @timestamp, instance_id: @instance_id }
-      end
-
-      def format_date
-        Time.now.strftime('%Y-%m-%d %H:%M:%S.%L')
+      def to_hash **_args
+        {
+            tags: @tags,
+            timestamp: @timestamp,
+            instance: Contrast::Agent::Telemetry.instance_id,
+            application: Contrast::Agent::Telemetry.application_id
+        }
       end
     end
   end

data/lib/contrast/agent/thread.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
 # frozen_string_literal: true
 
 require 'contrast/components/scope'

data/lib/contrast/agent/thread_watcher.rb

@@ -1,9 +1,10 @@
-# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# Copyright (c) 2022 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/service_heartbeat'
 require 'contrast/api/communication/messaging_queue'
+require 'contrast/agent/reporting/report'
 require 'contrast/agent/telemetry'
 
 module Contrast
@@ -24,21 +25,26 @@ module Contrast
         @heartbeat = Contrast::Agent::ServiceHeartbeat.new
         @messaging_queue = Contrast::Api::Communication::MessagingQueue.new
         @telemetry = Contrast::Agent::Telemetry.new if Contrast::Agent::Telemetry.enabled?
+        @reporter = Contrast::Agent::Reporter.new if Contrast::Agent::Reporter.enabled?
       end
 
       def startup!
         return unless ::Contrast::AGENT.enabled?
 
-        telemetry_thread_status = telemetry_thread_init
-        heartbeat_thread_status = heartbeat_thread_init
-        messaging_thread_status = messaging_thread_init
+        telemetry_status = telemetry_thread_init
+        heartbeat_status = heartbeat_thread_init
+        messaging_status = messaging_thread_init
+        reporter_status = reporter_thread_init
 
         logger.debug('ThreadWatcher started threads')
 
-        @pids[Process.pid] = messaging_thread_status && heartbeat_thread_status
+        @pids[Process.pid] = messaging_status && heartbeat_status
         return @pids unless Contrast::Agent::Telemetry.enabled?
 
-        @pids[Process.pid] = messaging_thread_status && heartbeat_thread_status && telemetry_thread_status
+        @pids[Process.pid] = @pids[Process.pid] && telemetry_status
+        return @pids unless Contrast::Agent::Reporter.enabled?
+
+        @pids[Process.pid] = @pids[Process.pid] && reporter_status
       end
 
       def ensure_running?
@@ -53,6 +59,7 @@ module Contrast
         messaging_queue.stop!
         heapdump_util.stop!
         telemetry_queue&.stop!
+        reporter&.stop!
       end
 
       def heartbeat_thread_init
@@ -82,11 +89,30 @@ module Contrast
         messaging_result
       end
 
+      def reporter_thread_init
+        @reporter.start_thread! if @reporter&.attempt_to_start?
+        unless @reporter&.running?
+          logger.debug('Attempting to start reporter thread')
+          @reporter&.start_thread!
+        end
+        reporter_result = @reporter&.running?
+        logger.debug('Reporter thread status', alive: reporter_result)
+        reporter_result
+      end
+
+      # @return [Contrast::Agent::Telemetry]
       def telemetry_queue
         return if @telemetry.nil?
 
         @telemetry
       end
+
+      # @return [Contrast::Agent::Reporter]
+      def reporter
+        return if @reporter.nil?
+
+        @reporter
+      end
     end
   end
 end

data/lib/contrast/agent/tracepoint_hook.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
 # frozen_string_literal: true
 
 require 'contrast/components/logger'
@@ -46,9 +46,6 @@ module Contrast
             Contrast::Agent.framework_manager.register_late_framework(loaded_module)
             Contrast::Agent::Inventory::DependencyUsageAnalysis.instance.associate_file(path) if path
             Contrast::Agent::Patching::Policy::Patcher.patch_specific_module(loaded_module)
-            if RUBY_VERSION < '2.6.0' # TODO: RUBY-714 remove guard w/ EOL of 2.5
-              Contrast::Agent::Assess::Policy::RewriterPatch.rewrite_interpolation(loaded_module)
-            end
             Contrast::Agent::Assess::Policy::PolicyScanner.scan(tracepoint_event)
           rescue StandardError => e
             logger.error('Unable to complete TracePoint analysis', e, module: loaded_module, path: path)

data/lib/contrast/agent/version.rb

@@ -1,8 +1,8 @@
-# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
 # frozen_string_literal: true
 
 module Contrast
   module Agent
-    VERSION = '4.13.0'
+    VERSION = '5.0.0'
   end
 end

data/lib/contrast/agent/worker_thread.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
 # frozen_string_literal: true
 
 module Contrast

data/lib/contrast/agent.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
 # frozen_string_literal: true
 
 require 'English'
@@ -29,6 +29,9 @@ require 'contrast/utils/os'
 require 'contrast/utils/hash_digest'
 require 'contrast/utils/invalid_configuration_util'
 
+# Collect findings
+require 'contrast/utils/findings'
+
 # scoping
 require 'contrast/agent/scope'
 
@@ -48,25 +51,37 @@ module Contrast
   module Agent
     # build a map for tracking the context of the current request
     REQUEST_TRACKER = Contrast::Utils::ThreadTracker.new
+    FINDINGS = Contrast::Utils::Findings.new
 
+    # @return [Contrast::Framework::Manager]
     def self.framework_manager
       @_framework_manager ||= Contrast::Framework::Manager.new
     end
 
+    # @return [nil, Contrast::Utils::HeapDumpUtil]
     def self.heapdump_util
       thread_watcher.heapdump_util
     end
 
+    # @return [nil, Contrast::Api::Communication::MessagingQueue]
     def self.messaging_queue
       thread_watcher.messaging_queue
     end
 
+    # @return [nil, Contrast::Agent::Telemetry]
     def self.telemetry_queue
       return unless thread_watcher.telemetry_queue
 
       thread_watcher.telemetry_queue
     end
 
+    # @return [nil, Contrast::Agent::Reporter]
+    def self.reporter
+      return unless  thread_watcher.reporter
+
+      thread_watcher.reporter
+    end
+
     def self.thread_watcher
       @_thread_watcher ||= Contrast::Agent::ThreadWatcher.new
     end

data/lib/contrast/api/communication/connection_status.rb

@@ -1,10 +1,10 @@
-# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
 # frozen_string_literal: true
 
 module Contrast
   module Api
     module Communication
-      # Keeps track of the state of connections to the service.
+      # Keeps track of the state of connections to SpeedRacer.
       class ConnectionStatus
         def initialize
           @last_success = nil
@@ -12,25 +12,28 @@ module Contrast
           @startup_messages_sent = false
         end
 
-        # Whether we have sent startup message to the service. True after successfully
-        # sending startup messages to service and reset to false if we lose connection
-        # to the service.
+        # Whether we have sent startup message to SpeedRacer. True after successfully sending startup messages to
+        # SpeedRacer and reset to false if we lose connection.
+        #
+        # @return [Boolean]
         def startup_messages_sent?
           @startup_messages_sent
         end
 
-        # The last message sent was successful
+        # The last message sent was successful or not
+        #
+        # @return [Boolean]
         def connected?
           @last_success && (@last_failure.nil? || @last_success > @last_failure)
         end
 
-        # The current state of the service is active with a successful message sent
+        # The current state of the SpeedRacer is active with a successful message sent
         def success!
           @startup_messages_sent = true
           @last_success = Time.now.to_f
         end
 
-        # The service may be in some sort of error state
+        # The SpeedRacer may be in some sort of error state
         def failure!
           @startup_messages_sent = false
           @last_failure = Time.now.to_f

data/lib/contrast/api/communication/messaging_queue.rb

@@ -1,8 +1,9 @@
-# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# Copyright (c) 2022 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/worker_thread'
+require 'contrast/agent/reporting/reporting_utilities/audit'
 
 module Contrast
   module Api
@@ -15,23 +16,46 @@ module Contrast
 
         def initialize
           @speedracer = Contrast::Api::Communication::Speedracer.new
+          @audit = Contrast::Agent::Reporting::Audit.new if ::Contrast::API.request_audit_enable?
           super
         end
 
-        # Use this to bypass the messaging queue and leave response processing to the caller
+        # Use this to bypass the messaging queue and leave response processing to the caller. We use this method for
+        # those operations which are blocking, meaning they must complete for the Agent to continue operations. These
+        # types of events include initial settings/ setup on startup and analysis required to complete before handing
+        # execution from our pre-filter operations to the application code (i.e. Protect's input analysis).
+        #
+        # @param event [Contrast::Api::Dtm] One of the DTMs valid for the event field of
+        #   Contrast::Api::Dtm::Message|Contrast::Api::Dtm::Activity
+        # @return [Contrast::Api::Settings::AgentSettings,nil]
         def send_event_immediately event
           if ::Contrast::AGENT.disabled?
             logger.warn('Attempted to send event immediately with Agent disabled', caller: caller, event: event)
             return
           end
-          speedracer.return_response(event)
+          response_data = speedracer.return_response(event)
+          return response_data unless ::Contrast::API.request_audit_enable?
+
+          @audit&.audit_event(event, response_data)
+          response_data
         end
 
+        # A simple Queue used to hold messages that are ready to be sent to SpeedRacer but for which we do not need an
+        # immediate response
+        #
+        # @return [Queue]
         def queue
           @_queue ||= Queue.new
         end
 
-        # Use this to add a message to the queue and process the response internally
+        # Use this to add a message to the queue and process the response internally. We use this method for those
+        # operations which are non-blocking, meaning they don't need to complete for the Agent to continue operations.
+        # These types of events include any post-request messaging that occurs after execution is returned from the
+        # application to our post-filter operations as well as those that don't alter the application's execution (i.e.
+        # Assess' vulnerability reporting).
+        #
+        # @param event [Contrast::Api::Dtm] One of the DTMs valid for the event field of
+        #   Contrast::Api::Dtm::Message|Contrast::Api::Dtm::Activity
         def send_event_eventually event
           if ::Contrast::AGENT.disabled?
             logger.warn('Attempted to queue event with Agent disabled', caller: caller, event: event)
@@ -39,8 +63,14 @@ module Contrast
           end
           logger.debug('Enqueued event for sending', event_type: event.cs__class)
           queue << event if event
+          return unless ::Contrast::API.request_audit_enable?
+
+          @audit&.audit_event(event)
         end
 
+        # Create the reporting thread, which will pull from the queue in order to send messages to SpeedRacer. If
+        # SpeedRacer is not running and should be, meaning the Agent is configured to control it, then we will also
+        # try to start that process.
         def start_thread!
           speedracer.ensure_startup!
           return if running?
@@ -60,12 +90,16 @@ module Contrast
           logger.debug('Started background sending thread.')
         end
 
+        # When the Agent shuts down, we terminate the message sending operations. This method clears, closes, and
+        # destroys the queue.
         def delete_queue!
           @_queue&.clear
           @_queue&.close
           @_queue = nil
         end
 
+        # When the Agent shuts down, we terminate the thread responsible for reporting. This method destroys that
+        # thread and any data we would have sent with it.
         def stop!
           return unless running?