contrast-agent 4.4.1 → 4.9.0

data/ext/cs__contrast_patch/extconf.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2020 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
 # frozen_string_literal: true
 
 $TO_MAKE = File.basename(__dir__)

data/ext/cs__protect_kernel/cs__protect_kernel.c

@@ -1,4 +1,4 @@
-/* Copyright (c) 2020 Contrast Security, Inc.  See
+/* Copyright (c) 2021 Contrast Security, Inc.  See
  * https://www.contrastsecurity.com/enduser-terms-0317a for more details. */
 
 #include "cs__protect_kernel.h"

data/ext/cs__protect_kernel/extconf.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2020 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
 # frozen_string_literal: true
 
 $TO_MAKE = File.basename(__dir__)

data/ext/extconf_common.rb

@@ -1,15 +1,11 @@
-# Copyright (c) 2020 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
 # frozen_string_literal: true
 
 require 'mkmf'
 require_relative '../lib/contrast/agent/version'
 
-def name
-  $TO_MAKE
-end
-
 def make!
-  create_makefile "#{ name }/#{ name }"
+  create_makefile "#{ $TO_MAKE }/#{ $TO_MAKE }"
 end
 
 def ext_path

data/lib/contrast-agent.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2020 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
 # frozen_string_literal: true
 
 # We need this to make bundler happy since it's the name of the gem, unless we

data/lib/contrast.rb

@@ -1,13 +1,9 @@
-# Copyright (c) 2020 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
 # frozen_string_literal: true
 
 # Used to prevent deprecation warnings from flooding stdout
 ENV['PB_IGNORE_DEPRECATIONS'] = 'true'
 
-# Top-level namespace for Contrast Security agent
-module Contrast
-end
-
 # Some developers override various methods on Object, which can often involve
 # changing expected method parity/behavior which in turn prevents us from being
 # able to reliably use affected methods.
@@ -25,25 +21,58 @@ class Object
   alias_method :cs__singleton_class, :singleton_class
 end
 
-# component interface for class creation
-# config gets built as a consequence of this require
-require 'contrast/components/interface'
+if RUBY_VERSION >= '3.0.0'
+  # This fixes Ruby 3.0 issues with Module#(some instance method) patching by preventing the prepending of
+  # a JSON helper on protobuf load. String.instance_method(:+) is one of the most noticable.
+  # TODO: RUBY-1132 Remove this once Ruby 3 is fixed.
+  # See bug here: https://bugs.ruby-lang.org/issues/17725
+  class Class
+    alias_method(:cs__orig_prepend, :prepend)
+    def prepend other
+      include(other)
+    end
+  end
+end
+
+require 'contrast/components/agent'
+require 'contrast/components/app_context'
+require 'contrast/components/assess'
+require 'contrast/components/config'
+require 'contrast/components/contrast_service'
+require 'contrast/components/inventory'
+require 'contrast/components/logger'
+require 'contrast/components/protect'
+require 'contrast/components/sampling'
+require 'contrast/components/scope'
+require 'contrast/components/settings'
+
+module Contrast
+  SCOPE = Contrast::Components::Scope::Interface.new
+  CONFIG = Contrast::Components::Config::Interface.new
+  SETTINGS = Contrast::Components::Settings::Interface.new
+  ASSESS = Contrast::Components::Assess::Interface.new
+  PROTECT = Contrast::Components::Protect::Interface.new
+  INVENTORY = Contrast::Components::Inventory::Interface.new
+  LOGGER = Contrast::Components::Logger::Interface.new
+  AGENT = Contrast::Components::Agent::Interface.new
+  CONTRAST_SERVICE = Contrast::Components::ContrastService::Interface.new
+  APP_CONTEXT = Contrast::Components::AppContext::Interface.new
+end
 
 # This needs to be required very early, after component interfaces, and before instrumentation attempts
 require 'contrast/funchook/funchook'
 
-# shared configuration support
-require 'contrast/config'
-require 'contrast/configuration'
-
 require 'contrast/agent/version'
 
-# errors and exceptions
-require 'contrast/security_exception'
-
 # shared utils
 require 'contrast/utils/timer'
 require 'contrast/utils/preflight_util'
 
 require 'contrast/utils/assess/sampling_util'
 require 'contrast/agent'
+
+if RUBY_VERSION >= '3.0.0'
+  # Put prepend back as it was.
+  Class.alias_method(:prepend, :cs__orig_prepend)
+  Class.remove_method(:cs__orig_prepend)
+end

data/lib/contrast/agent.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2020 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
 # frozen_string_literal: true
 
 require 'English'
@@ -27,8 +27,6 @@ require 'contrast/utils/string_utils'
 require 'contrast/utils/io_util'
 require 'contrast/utils/os'
 
-require 'contrast/common_agent_configuration'
-
 require 'contrast/utils/hash_digest'
 require 'contrast/utils/invalid_configuration_util'
 

data/lib/contrast/agent/assess.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2020 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
 # frozen_string_literal: true
 
 module Contrast
@@ -10,7 +10,7 @@ module Contrast
     module Assess
       require 'contrast/agent/assess/tracker'
       require 'contrast/agent/module_data'
-      require 'contrast/agent/rewriter'
+      require 'contrast/agent/rewriter' if RUBY_VERSION < '2.6.0' # TODO: RUBY-714 remove guard w/ EOL of 2.5
       require 'contrast/agent/assess/policy/preshift'
 
       # Dynamic Sources

data/lib/contrast/agent/assess/contrast_event.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2020 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
 # frozen_string_literal: true
 
 require 'contrast/utils/assess/tracking_util'
@@ -8,43 +8,30 @@ require 'contrast/utils/object_share'
 require 'contrast/utils/stack_trace_utils'
 require 'contrast/utils/string_utils'
 require 'contrast/utils/timer'
-require 'contrast/components/interface'
 require 'contrast/agent/assess/contrast_object'
 
 module Contrast
   module Agent
     module Assess
-      # This class holds the data about an event in the application
-      # We'll use it to build an event that TeamServer can consume if
-      # the object to which this event belongs ends in a trigger.
+      # This class holds the data about an event in the application We'll use it to build an event that TeamServer can
+      # consume if the object to which this event belongs ends in a trigger.
       #
       # @attr_reader event_id [Integer] the atomic id of this event
-      # @attr_reader policy_node [Contrast::Agent::Assess::Policy::PolicyNode]
-      #   the node that governs this event.
-      # @attr_reader stack_trace [Array<String>] the execution stack at the
-      #   time the method for this event was invoked
-      # @attr_reader time [Integer] the time, in epoch ms, when this event was
-      #   created
-      # @attr_reader thread [Integer] the object id of the thread on which this
-      #   event was generated
-      # @attr_reader object [Contrast::Agent::Assess::ContrastObject] the safe
-      #   representation of the Object on which the method was invoked
-      # @attr_reader ret [Contrast::Agent::Assess::ContrastObject] the safe
-      #   representation of the Return of the invoked method
-      # @attr_reader args [Array<Contrast::Agent::Assess::ContrastObject>] the
-      #   safe representation of the Arguments with which the method was invoked
+      # @attr_reader policy_node [Contrast::Agent::Assess::Policy::PolicyNode] the node that governs this event.
+      # @attr_reader stack_trace [Array<String>] the execution stack at the time the method for this event was invoked
+      # @attr_reader time [Integer] the time, in epoch ms, when this event was created
+      # @attr_reader thread [Integer] the object id of the thread on which this event was generated
+      # @attr_reader object [Contrast::Agent::Assess::ContrastObject] the safe representation of the Object on which
+      #   the method was invoked
+      # @attr_reader ret [Contrast::Agent::Assess::ContrastObject] the safe representation of the Return of the invoked
+      #   method
+      # @attr_reader args [Array<Contrast::Agent::Assess::ContrastObject>] the safe representation of the Arguments
+      #   with which the method was invoked
       class ContrastEvent
-        include Contrast::Components::Interface
-        access_component :analysis
 
-        attr_reader :event_id, :policy_node, :stack_trace, :time, :thread,
-                    :object,
-                    :ret,
-                    :args,
-                    :tags
+        attr_reader :event_id, :policy_node, :stack_trace, :time, :thread, :object, :ret, :args, :tags
 
-        # We need this to track the parent id's of events to build up a flow
-        # chart of the finding
+        # We need this to track the parent id's of events to build up a flow chart of the finding
         @atomic_id = 0
         @atomic_mutex = Mutex.new
         def self.next_atomic_id
@@ -56,26 +43,13 @@ module Contrast
           end
         end
 
-        # @param policy_node [Contrast::Agent::Assess::Policy::PolicyNode]
-        #   the node that governs this event.
+        # @param policy_node [Contrast::Agent::Assess::Policy::PolicyNode] the node that governs this event.
         # @param tagged [Object] the Target to which this event pertains.
         # @param object [Object] the Object on which the method was invoked
         # @param ret [Object] the Return of the invoked method
-        # @param args [Array<Object>] the Arguments with which the method
-        #   was invoked
+        # @param args [Array<Object>] the Arguments with which the method was invoked
         def initialize policy_node, tagged, object, ret, args
           @policy_node = policy_node
-
-          # Capture stacktraces only as configured.
-          #
-          # So long as this event is built in a factory, we know Contrast Code
-          # will be the first three events
-          @stack_trace = if ASSESS.capture_stacktrace?(policy_node)
-                           caller(3, 20)
-                         else
-                           Contrast::Utils::ObjectShare::EMPTY_ARRAY
-                         end
-
           @time = Contrast::Utils::Timer.now_ms
           @thread = Thread.current.object_id
 
@@ -84,17 +58,17 @@ module Contrast
           @tags = Contrast::Agent::Assess::Tracker.properties(tagged)&.tags
           find_parent_events!(policy_node, object, ret, args)
           snapshot!(object, ret, args)
+          capture_stacktrace!
         end
 
         def parent_events
           @_parent_events ||= []
         end
 
-        # We have to do a little work to figure out what our TS appropriate
-        # target is. To break this down, the logic is as follows:
-        # 1) If my policy_node has a target, work on targets. Else, work on sources.
-        #    Per TS law, each policy_node must have at least a source or a target.
-        #    The only type of policy_node w/o targets is a Trigger, but that may
+        # We have to do a little work to figure out what our TS appropriate target is. To break this down, the logic is
+        # as follows:
+        # 1) If my policy_node has a target, work on targets. Else, work on sources. Per TS law, each policy_node must
+        #    have at least a source or a target. The only type of policy_node w/o targets is a Trigger, but that may
         #    change.
         # 2) I'll set the event's source and target to TS values.
         # 3) Return the first source/target as the taint target.
@@ -117,21 +91,17 @@ module Contrast
 
         private
 
-        # Parent events are the events of all the sources of this event which
-        # were tracked prior to this event occurring. Depending on which, if
-        # any of the sources were tracked, there may be more than one parent.
+        # Parent events are the events of all the sources of this event which were tracked prior to this event
+        # occurring. Depending on which, if any of the sources were tracked, there may be more than one parent.
         #
-        # All events except for [Contrast::Agent::Assess::Events::SourceEvent]
-        # will have at least one parent.
+        # All events except for [Contrast::Agent::Assess::Events::SourceEvent] will have at least one parent.
         #
         # We set those events to this event's instance variables.
         #
-        # @param policy_node [Contrast::Agent::Assess::Policy::PolicyNode]
-        #   the node that governs this event.
+        # @param policy_node [Contrast::Agent::Assess::Policy::PolicyNode] the node that governs this event.
         # @param object [Object] the Object on which the method was invoked
         # @param ret [Object] the Return of the invoked method
-        # @param args [Array<Object>] the Arguments with which the method
-        #   was invoked
+        # @param args [Array<Object>] the Arguments with which the method was invoked
         def find_parent_events! policy_node, object, ret, args
           policy_node.sources.each do |source_marker|
             source = value_of_source(source_marker, object, ret, args)
@@ -145,10 +115,8 @@ module Contrast
         # @param source [String] the marker for the source type
         # @param object [Object] the Object on which the method was invoked
         # @param ret [Object] the Return of the invoked method
-        # @param args [Array<Object>] the Arguments with which the method
-        #   was invoked
-        # @return [Object,nil] the literal value of the source indicated by the
-        #   given marker
+        # @param args [Array<Object>] the Arguments with which the method was invoked
+        # @return [Object,nil] the literal value of the source indicated by the given marker
         def value_of_source source, object, ret, args
           case source
           when Contrast::Utils::ObjectShare::OBJECT_KEY
@@ -160,16 +128,13 @@ module Contrast
           end
         end
 
-        # Everything* is mutable in Ruby. As such, to ensure we can accurately
-        # report the application state at the time of this method's invocation,
-        # we have to snapshot the given values, making safe representations of
-        # them for our later use. We set those safe values to this event's
-        # instance variables.
+        # Everything* is mutable in Ruby. As such, to ensure we can accurately report the application state at the time
+        # of this method's invocation, we have to snapshot the given values, making safe representations of them for
+        # our later use. We set those safe values to this event's instance variables.
         #
         # @param object [Object] the Object on which the method was invoked
         # @param ret [Object] the Return of the invoked method
-        # @param args [Array<Object>] the Arguments with which the method
-        #   was invoked
+        # @param args [Array<Object>] the Arguments with which the method was invoked
         def snapshot! object, ret, args
           @object = Contrast::Agent::Assess::ContrastObject.new(object) if object
           @ret = Contrast::Agent::Assess::ContrastObject.new(ret) if ret
@@ -177,18 +142,35 @@ module Contrast
           self
         end
 
-        # Given an array of arguments, copy them into a safe, meaning String,
-        # format that we can use to send to SR and TS for rendering.
+        # Given an array of arguments, copy them into a safe, meaning String, format that we can use to send to SR and
+        # TS for rendering.
         #
         # @param args [Array<Object>] the arguments to translate
-        # @return [Array<Contrast::Agent::Assess::ContrastObject>] the String forms of those Objects, as
-        #   determined by Contrast::Utils::ClassUtil.to_contrast_string
+        # @return [Array<Contrast::Agent::Assess::ContrastObject>] the String forms of those Objects, as determined by
+        #   Contrast::Utils::ClassUtil.to_contrast_string
         def safe_args_representation args
           return unless args
           return Contrast::Utils::ObjectShare::EMPTY_ARRAY if args.empty?
 
           args.map { |arg| arg ? Contrast::Agent::Assess::ContrastObject.new(arg) : nil }
         end
+
+        # Capture stack traces only as configured. We'll use this to grab the start of the call stack as if the
+        # instrumented method were the caller. This means we'll start at the entry just after the first block of
+        # Contrast code.
+        def capture_stacktrace!
+          # If we're configured to not capture the stacktrace, usually for performance reasons, then don't and return an
+          # empty array instead
+          unless ::Contrast::ASSESS.capture_stacktrace?(policy_node)
+            @stack_trace = Contrast::Utils::ObjectShare::EMPTY_ARRAY
+            return
+          end
+
+          # Otherwise, find where in the stack the application / Ruby code starts
+          start = caller(0, 20)&.find_index { |stack| !stack.include?('/lib/contrast') }
+          # And then use that to build out the reported stacktrace, or a fallback if we couldn't find it.
+          @stack_trace = start ? caller(start + 1, 20) : caller(20, 20)
+        end
       end
     end
   end

data/lib/contrast/agent/assess/contrast_object.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2020 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
 # frozen_string_literal: true
 
 require 'contrast/utils/class_util'
@@ -34,14 +34,14 @@ module Contrast
         def initialize object
           if object
             @object = Contrast::Utils::ClassUtil.to_contrast_string(object)
-            @object_type = object.cs__class.name
+            @object_type = object.cs__class.cs__name
             # TODO: RUBY-1084 determine if we need to copy these tags to
             #   restore immutability. For instance, if these tags were on a
             #   String that was then #reverse!'d, would our tags be wrong?
             @tags = Contrast::Agent::Assess::Tracker.properties(object)&.tags
           else
             @object = Contrast::Utils::ObjectShare::NIL_STRING
-            @object_type = nil.cs__class.name
+            @object_type = nil.cs__class.cs__name
           end
         end
 

data/lib/contrast/agent/assess/events/event_factory.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2020 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
 # frozen_string_literal: true
 
 require 'contrast/agent/assess/contrast_event'
@@ -13,7 +13,8 @@ module Contrast
           def self.build policy_node, tagged, object, ret, args, source_type = nil, source_name = nil
             case policy_node
             when Contrast::Agent::Assess::Policy::SourceNode
-              Contrast::Agent::Assess::Events::SourceEvent.new(policy_node, tagged, object, ret, args, source_type, source_name)
+              Contrast::Agent::Assess::Events::SourceEvent.new(policy_node, tagged, object, ret, args, source_type,
+                                                               source_name)
             when Contrast::Agent::Assess::Policy::PolicyNode
               Contrast::Agent::Assess::ContrastEvent.new(policy_node, tagged, object, ret, args)
             end

data/lib/contrast/agent/assess/events/source_event.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2020 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
 # frozen_string_literal: true
 
 require 'contrast/agent/assess/contrast_event'
@@ -11,8 +11,13 @@ module Contrast
         # This class holds the data about an event in the application
         # We'll use it to build an event that TeamServer can consume if
         # the object to which this event belongs ends in a trigger.
+        #
+        # @attr_reader request [Contrast::Agent::Request] our wrapper around the Rack::Request at the time this source
+        #  was created
+        # @attr_reader source_name [String] the name of the source if it comes from a map-like entity
+        # @attr_reader source_type [String] the TeamServer understood type of source; i.e. parameter
         class SourceEvent < Contrast::Agent::Assess::ContrastEvent
-          attr_reader :source_name, :source_type, :request
+          attr_reader :request, :source_name, :source_type
 
           def initialize policy_node, tagged, object, ret, args, source_type = nil, source_name = nil
             super(policy_node, tagged, object, ret, args)

data/lib/contrast/agent/assess/finalizers/freeze.rb

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

data/lib/contrast/agent/assess/finalizers/hash.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2020 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
 # frozen_string_literal: true
 
 require 'contrast/utils/duck_utils'
@@ -7,25 +7,20 @@ module Contrast
   module Agent
     module Assess
       module Finalizers
-        # An extension of Hash that doesn't impact GC of the object being
-        # stored by storing its ID as a Key to lookup and registering a
-        # finalizer on the object to remove its entry from the Hash immediately
-        # after it's GC'd.
+        # An extension of Hash that doesn't impact GC of the object being stored by storing its ID as a Key to lookup
+        # and registering a finalizer on the object to remove its entry from the Hash immediately after it's GC'd.
         class Hash < Hash
-          include Contrast::Components::Interface
-          access_component :agent, :analysis
 
           FROZEN_FINALIZED_IDS = Set.new
 
           def []= key, obj
-            return unless AGENT.enabled? && ASSESS.enabled?
+            return unless ::Contrast::AGENT.enabled? && ::Contrast::ASSESS.enabled?
 
-            # We can't finalize frozen things, so only act on those that went
-            # through .pre_freeze
+            # We can't finalize frozen things, so only act on those that went through .pre_freeze
             if key.cs__frozen?
               return unless FROZEN_FINALIZED_IDS.include?(key.__id__)
             else
-              ObjectSpace.define_finalizer(key, finalize(key.__id__))
+              ObjectSpace.define_finalizer(key, finalizing_proc)
             end
             super key.__id__, obj
           end
@@ -34,8 +29,8 @@ module Contrast
             super key.__id__
           end
 
-          # Something is trackable if it is not a collection and either not
-          # frozen or it was frozen after we put a finalizer on it.
+          # Something is trackable if it is not a collection and either not frozen or it was frozen after we put a
+          # finalizer on it.
           #
           # @param key [Object] the thing to determine if trackable
           # @return [Boolean]
@@ -47,51 +42,46 @@ module Contrast
             # If it's not frozen, we can finalize/ track it.
             return true unless key.cs__frozen?
 
-            # Otherwise, we can only track it if we've finalized it in our
-            # freeze patch.
+            # Otherwise, we can only track it if we've finalized it in our freeze patch.
             FROZEN_FINALIZED_IDS.include?(key.__id__)
           end
 
-          # Determine if the given Object is tracked, meaning it has a known
-          # set of properties and those properties are tracked.
+          # Determine if the given Object is tracked, meaning it has a known set of properties and those properties are
+          # tracked.
           #
-          # @param key [Object] the Object whose properties, by id, we want to
-          #   check for tracked status
+          # @param key [Object] the Object whose properties, by id, we want to check for tracked status
           # @return [Boolean]
           def tracked? key
             key?(key.__id__) && fetch(key.__id__, nil)&.tracked?
           end
 
-          # Remove the given key from our frozen and properties tracking during
-          # finalization of the Object to which the given key_id pertains.
-          # NOTE: by necessity, this is the only method which takes the __id__,
-          # not the Object itself. You CANNOT pass the Object to this as a
-          # finalizer cannot hold reference to the Object being finalized; that
-          # prevents GC, which introduces a memory leak and defeats the entire
-          # purpose of this.
+          # Create a Proc to remove the given key from our frozen and properties tracking during finalization of the
+          # Object to which the given key_id pertains. The ObjectSpace's finalizer mechanism will handle passing this
+          # ID in, so we only need to define the Proc once.
           #
-          # @param key_id [Integer] the Object Identifier to clean up during
-          #   finalization.
-          def finalize key_id
-            proc do
+          # NOTE: by necessity, this is the only method which takes the __id__, not the Object itself. You CANNOT pass
+          # the Object to this as a finalizer cannot hold reference to the Object being finalized; that prevents GC,
+          # which introduces a memory leak and defeats the entire purpose of this.
+          #
+          # @return [Proc] the Proc to remove references to the ID of the GC'd object from our Hash
+          def finalizing_proc
+            @_finalizing_proc ||= proc do |key_id|
               FROZEN_FINALIZED_IDS.delete(key_id)
               delete(key_id)
             end
           end
 
-          # Frozen things cannot be finalized. To avoid any issue here, we
-          # intercept the #freeze call and set finalizers on the Object. To
-          # ensure later we know it's been pre-finalized, we add it's __id__ to
-          # our tracking.
+          # Frozen things cannot be finalized. To avoid any issue here, we intercept the #freeze call and set
+          # finalizers on the Object. To ensure later we know it's been pre-finalized, we add it's __id__ to our
+          # tracking.
           #
-          # @param key [Object] the Object on which we need to pre-define
-          #   finalizers
+          # @param key [Object] the Object on which we need to pre-define finalizers
           def pre_freeze key
-            return unless AGENT.enabled? && ASSESS.enabled?
+            return unless ::Contrast::AGENT.enabled? && ::Contrast::ASSESS.enabled?
             return if key.cs__frozen?
             return if FROZEN_FINALIZED_IDS.include?(key.__id__)
 
-            ObjectSpace.define_finalizer(key, finalize(key.__id__))
+            ObjectSpace.define_finalizer(key, finalizing_proc)
 
             FROZEN_FINALIZED_IDS << key.__id__
           rescue StandardError => _e