contrast-agent 4.9.0 → 4.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04fe75ff7b610b12a7c4e3416830e0362dcc272346a2591dee97d36b08fe4d20
-  data.tar.gz: 319c8eb0cf2377f735d9ba9318ec518e10c9986c7674bf652885ff73c40423fb
+  metadata.gz: 6a0a50913c5c680462f9afd79070ca1f3d46d09d66ffdb943b1dc778f84830d6
+  data.tar.gz: bb3254c6a2cdc2b4add4e09b4bf1ed63c6a640f0dd82824db2769b911aacf96b
 SHA512:
-  metadata.gz: 66f782973a14ee44b732f3fb17d4a40ac072ca6b78627c72f343bf5a4902d5d9dcf95aa92249f8659cb3214fb765828834507196f6bcb8787eece732a7242795
-  data.tar.gz: 5a9578db89d3d2a6f1e904fe3e248d5577d1db30a4d81049d4552fa6c0a3733638cbe9862d3f29f5979bad718add38b6d579541df40780e3746c1990bbe4f882
+  metadata.gz: 78d5e66ee3ab7408e94348f6c2998e73cd78227a8b75cffa7add261b771092d470431ce8e44357dfb7d1a178e03e5033efc9f7a4c974a979f9dea88b2c55a3ec
+  data.tar.gz: d20f41b563778d84e63e4db7a9399e666a85fe1a2343772258f5248cd139f02e6a6bea33e51d9e5a0f954b1e2b4683ec08f3db7a52ab5a6990f7d725d2bc3dea

data/.rspec

@@ -3,4 +3,3 @@
 --format documentation
 --format RspecJunitFormatter
 --out ./test-results/results.xml
---color

data/.rspec_parallel

@@ -0,0 +1,6 @@
+--require spec_helper
+--order rand
+--format progress
+--format RspecJunitFormatter
+--out ./test-results/results.xml
+--format ParallelTests::RSpec::FailuresLogger --out tmp/failing_specs.log

data/ext/cs__common/cs__common.c

@@ -73,11 +73,20 @@ VALUE contrast_register_singleton_patch(const char *module_name,
                                     IMPL_ALIAS_SINGLETON);
 }
 
-VALUE contrast_register_singleton_prepend_patch(
-    const char *module_name, const char *method_name,
-    VALUE(c_fn)(const int, VALUE *, const VALUE)) {
+VALUE contrast_register_prepend_patch(const char *module_name,
+                              const char *method_name,
+                              VALUE(c_fn)(const int, VALUE *,
+                                          const VALUE)) {
+    return _contrast_register_patch(module_name, method_name, c_fn,
+                                    IMPL_PREPEND_INSTANCE);
+}
+
+VALUE contrast_register_singleton_prepend_patch(const char *module_name,
+                              const char *method_name,
+                              VALUE(c_fn)(const int, VALUE *,
+                                          const VALUE)) {
     return _contrast_register_patch(module_name, method_name, c_fn,
-                                    IMPL_PREPEND);
+                                    IMPL_PREPEND_SINGLETON);
 }
 
 static VALUE
@@ -122,8 +131,10 @@ _contrast_register_patch(const char *module_name, const char *method_name,
     case IMPL_ALIAS_SINGLETON:
         impl = ID2SYM(rb_sym_alias_singleton);
         break;
-    case IMPL_PREPEND:
-        impl = ID2SYM(rb_sym_prepend);
+    case IMPL_PREPEND_INSTANCE:
+        impl = ID2SYM(rb_sym_prepend_instance);
+    case IMPL_PREPEND_SINGLETON:
+         impl = ID2SYM(rb_sym_prepend_singleton);
         break;
     }
 
@@ -152,7 +163,8 @@ void Init_cs__common(void) {
     rb_sym_register_c_patch = rb_intern("register_c_patch");
     rb_sym_alias_instance = rb_intern("alias_instance");
     rb_sym_alias_singleton = rb_intern("alias_singleton");
-    rb_sym_prepend = rb_intern("prepend");
+    rb_sym_prepend_instance = rb_intern("prepend_instance");
+    rb_sym_prepend_singleton = rb_intern("prepend_singleton");
 
     /* Ensure definition of core Contrast instrumentation modules */
     contrast = rb_define_module("Contrast");

data/ext/cs__common/cs__common.h

@@ -6,7 +6,8 @@
 typedef enum {
     IMPL_ALIAS_INSTANCE,
     IMPL_ALIAS_SINGLETON,
-    IMPL_PREPEND
+    IMPL_PREPEND_INSTANCE,
+    IMPL_PREPEND_SINGLETON,
 } patch_impl;
 
 static VALUE cs__send_method;
@@ -30,7 +31,8 @@ static VALUE rb_sym_instance_method;
 static VALUE rb_sym_register_c_patch;
 static VALUE rb_sym_alias_instance;
 static VALUE rb_sym_alias_singleton;
-static VALUE rb_sym_prepend;
+static VALUE rb_sym_prepend_instance;
+static VALUE rb_sym_prepend_singleton;
 
 void patch_via_funchook(void *original_function, void *hook_function);
 

data/ext/cs__contrast_patch/cs__contrast_patch.c

@@ -182,7 +182,8 @@ VALUE contrast_run_patches(const VALUE *wrapped_args) {
                                   contrast_patch_call_rescue,
                                   (VALUE)rescue_args, rb_eException, 0);
         break;
-    case IMPL_PREPEND:
+    case IMPL_PREPEND_INSTANCE:
+    case IMPL_PREPEND_SINGLETON:
         original_ret = rb_rescue2(contrast_call_super, original_args,
                                   contrast_patch_call_rescue,
                                   (VALUE)rescue_args, rb_eException, 0);
@@ -247,10 +248,14 @@ VALUE contrast_patch_dispatch(const int argc, const VALUE *argv,
      */
     switch (impl) {
     case IMPL_ALIAS_INSTANCE:
-    case IMPL_PREPEND:
+    case IMPL_PREPEND_INSTANCE:
         known =
             rb_funcall(patch_status, rb_sym_info_for, 3, object, method, Qtrue);
         break;
+    case IMPL_PREPEND_SINGLETON:
+       known =
+           rb_funcall(patch_status, rb_sym_info_for, 3, object, method, Qfalse);
+       break;
     case IMPL_ALIAS_SINGLETON:
         known = rb_funcall(patch_status, rb_sym_info_for, 3, object, method,
                            Qfalse);
@@ -323,7 +328,8 @@ call_original:
     case IMPL_ALIAS_INSTANCE:
     case IMPL_ALIAS_SINGLETON:
         return contrast_patch_call_original(original_args);
-    case IMPL_PREPEND:
+    case IMPL_PREPEND_INSTANCE:
+    case IMPL_PREPEND_SINGLETON:
         return contrast_call_super(original_args);
     };
 }
@@ -338,9 +344,14 @@ VALUE contrast_alias_singleton_patch(const int argc, const VALUE *argv,
     return contrast_patch_dispatch(argc, argv, IMPL_ALIAS_SINGLETON, object);
 }
 
-VALUE contrast_prepend_patch(const int argc, const VALUE *argv,
+VALUE contrast_prepend_instance_patch(const int argc, const VALUE *argv,
                              const VALUE object) {
-    return contrast_patch_dispatch(argc, argv, IMPL_PREPEND, object);
+    return contrast_patch_dispatch(argc, argv, IMPL_PREPEND_INSTANCE, object);
+}
+
+VALUE contrast_prepend_singleton_patch(const int argc, const VALUE *argv,
+                             const VALUE object) {
+    return contrast_patch_dispatch(argc, argv, IMPL_PREPEND_SINGLETON, object);
 }
 
 VALUE contrast_patch_define_method(const VALUE self, const VALUE clazz, const VALUE method_policy,
@@ -403,26 +414,37 @@ VALUE contrast_patch_define_method(const VALUE self, const VALUE clazz, const VA
 VALUE contrast_patch_prepend(const VALUE self, const VALUE originalModule,
                              const VALUE method_policy) {
 
+    const VALUE instance = Qtrue;
+    const VALUE singleton = Qfalse;
     const VALUE original_method_name =
         rb_funcall(method_policy, rb_sym_method_name, 0);
     const VALUE is_private =
         rb_funcall(method_policy, rb_sym_private_method, 0);
     const VALUE is_instance_method =
         rb_funcall(method_policy, rb_sym_instance_method, 0);
-    rb_funcall(patch_status, rb_sym_set_info_for, 5, originalModule,
-               original_method_name, method_policy, Qtrue, Qnil);
+
+// Set the value for instance or singleton method
+    if (RTEST(is_instance_method)){
+        rb_funcall(patch_status, rb_sym_set_info_for, 5, originalModule,
+                   original_method_name, method_policy, instance, Qnil);
+
+    } else {
+        rb_funcall(patch_status, rb_sym_set_info_for, 5, originalModule,
+                   original_method_name, method_policy, singleton, Qnil);
+    }
+
     VALUE module = rb_define_module_under(originalModule, "ContrastPrepend");
     VALUE str = rb_funcall(original_method_name, rb_sym_cs_to_s, 0);
     char *cMethodName = StringValueCStr(str);
     if (RTEST(is_instance_method)) {
         if (RTEST(is_private)) {
             rb_define_private_method(module, cMethodName,
-                                     contrast_prepend_patch, -1);
+                                     contrast_prepend_instance_patch, -1);
         } else {
-            rb_define_method(module, cMethodName, contrast_prepend_patch, -1);
+            rb_define_method(module, cMethodName, contrast_prepend_instance_patch, -1);
         }
     } else {
-        rb_define_singleton_method(module, cMethodName, contrast_prepend_patch,
+        rb_define_singleton_method(module, cMethodName, contrast_prepend_singleton_patch,
                                    -1);
     }
     rb_prepend_module(originalModule, module);
@@ -437,7 +459,6 @@ void Init_cs__contrast_patch(void) {
     rb_sym_contrast_apply_pre_patch = rb_intern("apply_pre_patch");
     rb_sym_cs_to_s = rb_intern("to_s");
     rb_sym_custom_patch = rb_intern("requires_custom_patch?");
-    rb_sym_in_request_context = rb_intern("in_request_context?");
     rb_sym_info_for = rb_intern("info_for");
     rb_sym_propagation_node = rb_intern("propagation_node");
     rb_sym_set_info_for = rb_intern("set_info_for");

data/ext/cs__contrast_patch/cs__contrast_patch.h

@@ -16,8 +16,6 @@ static VALUE rb_sym_contrast_apply_pre_patch;
 static VALUE rb_sym_custom_patch;
 static VALUE rb_sym_cs_to_s;
 
-static VALUE rb_sym_in_request_context;
-
 static VALUE rb_sym_enter_method_scope;
 static VALUE rb_sym_exit_method_scope;
 
@@ -148,8 +146,11 @@ VALUE contrast_alias_instance_patch(const int argc, const VALUE *argv,
 VALUE contrast_alias_singleton_patch(const int argc, const VALUE *argv,
                                      const VALUE object);
 
-VALUE contrast_prepend_patch(const int argc, const VALUE *argv,
-                             const VALUE object);
+VALUE contrast_prepend_instance_patch(const int argc, const VALUE *argv,
+                                    const VALUE object);
+
+VALUE contrast_prepend_singleton_patch(const int argc, const VALUE *argv,
+                                     const VALUE object);
 
 /*
  * Patches a module's method by prepend:

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

@@ -28,7 +28,6 @@ module Contrast
       # @attr_reader args [Array<Contrast::Agent::Assess::ContrastObject>] the safe representation of the Arguments
       #   with which the method was invoked
       class ContrastEvent
-
         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
@@ -55,7 +54,7 @@ module Contrast
 
           # These methods rely on the above being set. Don't move them!
           @event_id = Contrast::Agent::Assess::ContrastEvent.next_atomic_id
-          @tags = Contrast::Agent::Assess::Tracker.properties(tagged)&.tags
+          @tags = Contrast::Agent::Assess::Tracker.properties(tagged)&.get_tags
           find_parent_events!(policy_node, object, ret, args)
           snapshot!(object, ret, args)
           capture_stacktrace!

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

@@ -35,10 +35,7 @@ module Contrast
           if object
             @object = Contrast::Utils::ClassUtil.to_contrast_string(object)
             @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
+            @tags = Contrast::Agent::Assess::Tracker.properties(object)&.get_tags
           else
             @object = Contrast::Utils::ObjectShare::NIL_STRING
             @object_type = nil.cs__class.cs__name

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

@@ -10,7 +10,6 @@ module Contrast
         # 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
-
           FROZEN_FINALIZED_IDS = Set.new
 
           def []= key, obj

data/lib/contrast/agent/assess/policy/dynamic_source_factory.rb

@@ -24,6 +24,8 @@ module Contrast
             #   the name of the method to taint, mapped to the properties it
             #   should apply
             def create_sources klass, tainted_columns
+              return unless Contrast::ASSESS.require_dynamic_sources?
+
               class_name = klass.cs__name
               instance_methods = klass.instance_methods
               instance_methods.concat(klass.private_instance_methods)

data/lib/contrast/agent/assess/policy/patcher.rb

@@ -20,7 +20,6 @@ module Contrast
           extend Contrast::Components::Logger::InstanceMethods
           extend Contrast::Components::Scope::InstanceMethods
 
-
           class << self
             def policy
               Contrast::Agent::Assess::Policy::Policy.instance

data/lib/contrast/agent/assess/policy/policy_scanner.rb

@@ -12,8 +12,6 @@ module Contrast
         # of a file vs data flow, such as the detection of Hardcoded Passwords
         # or Keys.
         module PolicyScanner
-
-
           class << self
             # Use the given trace_point, built from an :end event, to determine
             # where the loaded code lives and scan that code for policy

data/lib/contrast/agent/assess/policy/preshift.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require 'contrast/components/logger'
+require 'contrast/utils/lru_cache'
 
 module Contrast
   module Agent
@@ -10,8 +11,9 @@ module Contrast
       # caused, we'll need to store the state before the change occurred.
       class PreShift
         include Contrast::Components::Logger::InstanceMethods
+        extend Contrast::Components::Logger::InstanceMethods
 
-
+        @lru_cache = Contrast::Utils::LRUCache.new
         UNDUPLICABLE_MODULES = [
           Enumerator # dup'ing results in 'can't copy execution context'
         ].cs__freeze
@@ -70,29 +72,44 @@ module Contrast
 
           def append_object_details preshift, initializing, object
             can = can_dup?(initializing, object)
-            preshift.object = can ? object.dup : object
+            preshift.object = if @lru_cache.key?(object.__id__) && !Contrast::Agent::Assess::Tracker.tracked?(object)
+                                @lru_cache[object.__id__]
+                              else
+                                can ? object.dup : object
+                              end
             preshift.object_length = if Contrast::Utils::DuckUtils.quacks_to?(preshift.object, :length)
                                        object.length
                                      else
                                        0
                                      end
+
             return unless can
+
             return unless Contrast::Agent::Assess::Tracker.tracked?(object)
 
             Contrast::Agent::Assess::Tracker.copy(object, preshift.object)
+            @lru_cache[object.__id__] = object
           end
 
           def append_arg_details preshift, args
-            preshift.args = args.dup
-            preshift.args.each_with_index do |preshift_arg, index|
-              original_arg = args[index]
-              next if preshift_arg.__id__ == original_arg.__id__
-              next unless Contrast::Agent::Assess::Tracker.tracked?(original_arg)
-
-              Contrast::Agent::Assess::Tracker.copy(original_arg, preshift_arg)
-            end
-            preshift.arg_lengths = preshift.args.map do |preshift_arg|
-              Contrast::Utils::DuckUtils.quacks_to?(preshift_arg, :length) ? preshift_arg.length : 0
+            args_length = args.length
+            preshift.args = Array.new(args_length)
+            preshift.arg_lengths = Array.new(args_length)
+            idx = 0
+            while idx < args_length
+              or_arg = args[idx]
+              p_arg = if @lru_cache.key?(or_arg.__id__)
+                        @lru_cache[or_arg.__id__]
+                      else
+                        can_dup?(false, or_arg) ? or_arg.dup : or_arg
+                      end
+              preshift.args[idx] = p_arg
+              preshift.arg_lengths[idx] = Contrast::Utils::DuckUtils.quacks_to?(p_arg, :length) ? p_arg.length : 0
+              idx += 1
+              next if p_arg.__id__ == or_arg.__id__
+
+              Contrast::Agent::Assess::Tracker.copy(or_arg, p_arg)
+              @lru_cache[p_arg.__id__] = p_arg
             end
           end
         end

data/lib/contrast/agent/assess/policy/propagation_method.rb

@@ -12,14 +12,11 @@ module Contrast
   module Agent
     module Assess
       module Policy
-        # This class is responsible for the continuation of traces. A
-        # Propagator is any method that transforms an untrusted value. In
-        # general, these methods work on the String class or a holder of
-        # Strings
+        # This class is responsible for the continuation of traces. A Propagator is any method that transforms an
+        # untrusted value. In general, these methods work on the String class or a holder of Strings.
         module PropagationMethod
           extend Contrast::Components::Logger::InstanceMethods
 
-
           APPEND_ACTION = 'APPEND'
           CENTER_ACTION = 'CENTER'
           INSERT_ACTION = 'INSERT'
@@ -48,19 +45,16 @@ module Contrast
               end
             end
 
-            # @param method_policy [Contrast::Agent::Patching::Policy::MethodPolicy]
-            #   the policy that governs the patches to this method
-            # @param preshift [Contrast::Agent::Assess::PreShift] The capture
-            #   of the state of the code just prior to the invocation of the
-            #   patched method.
+            # @param method_policy [Contrast::Agent::Patching::Policy::MethodPolicy] the policy that governs the
+            #   patches to this method
+            # @param preshift [Contrast::Agent::Assess::PreShift] The capture of the state of the code just prior to
+            #   the invocation of the patched method.
             # @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
             # @param block [Block] the Block passed to the original method
-            # @return [Object, nil] the tracked Return or nil if no changes
-            #   were made; will replace the return of the original function if
-            #   not nil
+            # @return [Object, nil] the tracked Return or nil if no changes were made; will replace the return of the
+            #   original function if not nil
             def apply_propagation method_policy, preshift, object, ret, args, block
               return unless method_policy.propagation_node
               return unless preshift
@@ -86,26 +80,21 @@ module Contrast
                 SPLIT_ACTION => Contrast::Agent::Assess::Policy::Propagator::Split
             }.cs__freeze
 
-            # I lied above. We had to figure out what the target of the
-            # propagation was. Now that we know, we'll actually do things to
-            # it. Note that the return of this method will replace the original
-            # return of the patched function unless it is nil, so be sure
-            # you're returning what you intend.
+            # I lied above. We had to figure out what the target of the propagation was. Now that we know, we'll
+            # actually do things to it. Note that the return of this method will replace the original return of the
+            # patched function unless it is nil, so be sure you're returning what you intend.
             #
-            # @param propagation_node [Contrast::Agent::Assess::Policy::PropagationNode]
-            #   the node that governs this propagation event.
-            # @param preshift [Contrast::Agent::Assess::PreShift] The capture
-            #   of the state of the code just prior to the invocation of the
-            #   patched method.
+            # @param propagation_node [Contrast::Agent::Assess::Policy::PropagationNode] the node that governs this
+            #   propagation event.
+            # @param preshift [Contrast::Agent::Assess::PreShift] The capture of the state of the code just prior to
+            #   the invocation of the patched method.
             # @param target [Object] the Target to which to propagate.
             # @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
             # @param block [Block] the Block passed to the original method
-            # @return [Object, nil] the tracked Return or nil if no changes
-            #   were made; will replace the return of the original function if
-            #   not nil
+            # @return [Object, nil] the tracked Return or nil if no changes were made; will replace the return of the
+            #   original function if not nil
             def apply_propagator propagation_node, preshift, target, object, ret, args, block
               return unless propagation_possible?(propagation_node, target)
 
@@ -127,13 +116,16 @@ module Contrast
               nil
             end
 
-            # Custom actions tend to be the more complex of our propagations.
-            # Often, the method has to make decisions about the target based on
-            # the context with which the method was called. As such, defer
-            # determining if the target is valid to that method.
+            # Custom actions tend to be the more complex of our propagations. Often, the method has to make decisions
+            # about the target based on the context with which the method was called. As such, defer determining if the
+            # target is valid to that method.
+            #
+            # In all other cases, a target is valid for propagation if it is not nil
             #
-            # In all other cases, a target is valid for propagation if it is not
-            # nil
+            # @param target [Object] the thing to which to propagate
+            # @param propagation_node [Contrast::Agent::Assess::Policy::PropagationNode] the node that governs this
+            #   propagation event.
+            # @return [Boolean]
             def valid_target? target, propagation_node
               return true if propagation_node.action == CUSTOM_ACTION
 
@@ -141,8 +133,11 @@ module Contrast
             end
 
             ZERO_LENGTH_ACTIONS = [DB_WRITE_ACTION, CUSTOM_ACTION, KEEP_ACTION, REPLACE_ACTION, SPLAT_ACTION].cs__freeze
-            # If the action required needs a length and the target does not have
-            # one, the length is not valid
+            # If the action required needs a length and the target does not have one, the length is not valid
+            #
+            # @param target [Object] the thing to which to propagate
+            # @param action [String] the name of the action taken during this propagation
+            # @return [Boolean]
             def valid_length? target, action
               return true if ZERO_LENGTH_ACTIONS.include?(action)
 
@@ -153,9 +148,15 @@ module Contrast
               end
             end
 
-            # Before we do any work, we should check if we even need to.
-            # If the source of this patcher is not tracked, there's no need to do
-            # anything. A copy of nothing is still nothing.
+            # Before we do any work, we should check if we even need to. If the source and target of this patcher are
+            # not tracked, there's no need to do anything. A copy of nothing is still nothing.
+            #
+            # @param propagation_node [Contrast::Agent::Assess::Policy::PropagationNode] the node that governs this
+            #   propagation event.
+            # @param preshift [Contrast::Agent::Assess::PreShift] The capture of the state of the code just prior to
+            #   the invocation of the patched method.
+            # @param target [Object] the thing to which to propagate
+            # @return [Boolean]
             def can_propagate? propagation_node, preshift, target
               return false unless appropriate_target?(propagation_node, target)
               return true if Contrast::Utils::Assess::TrackingUtil.tracked?(target)
@@ -165,22 +166,21 @@ module Contrast
                 case source
                 when Contrast::Utils::ObjectShare::OBJECT_KEY
                   return true if Contrast::Utils::Assess::TrackingUtil.tracked?(preshift.object)
-                else # has to be P, there's no ret source type (yet? ever?)
+                else
+                  # has to be P, there's no ret source type (yet? ever?)
                   return true if preshift.args && Contrast::Utils::Assess::TrackingUtil.tracked?(preshift.args[source])
                 end
               end
               false
             end
 
-            # We cannot propagate to frozen things that have not been updated
-            # to work with our property tracking, unless they're duplicable and
-            # the return.
-            # We probably shouldn't propagate to frozen things at all, as
-            # they're supposed to be immutable, but third parties do jenky
-            # things, so allow it as long as it is safe to do.
+            # We cannot propagate to frozen things that have not been updated to work with our property tracking,
+            # unless they're duplicable and the return. We probably shouldn't propagate to frozen things at all, as
+            # they're supposed to be immutable, but third parties do jenky things, so allow it as long as it is safe to
+            # do.
             #
-            # @param propagation_node [Contrast::Agent::Assess::Policy::PropagationNode]
-            #   the node that governs this propagation event.
+            # @param propagation_node [Contrast::Agent::Assess::Policy::PropagationNode] the node that governs this
+            #   propagation event.
             # @param target [Object] the Target to which to propagate.
             # @return [Boolean] if the target can be propagated to
             def appropriate_target? propagation_node, target
@@ -191,6 +191,9 @@ module Contrast
             end
 
             # If this patcher has tags, apply them to the entire target
+            # @param propagation_node [Contrast::Agent::Assess::Policy::PropagationNode] the node that governs this
+            #   propagation event.
+            # @param target [Object] the Target to which to propagate.
             def apply_tags propagation_node, target
               return unless propagation_node.tags
               return unless (properties = Contrast::Agent::Assess::Tracker.properties(target))
@@ -202,6 +205,10 @@ module Contrast
             end
 
             # If this patcher has tags, remove them from the entire target
+            #
+            # @param propagation_node [Contrast::Agent::Assess::Policy::PropagationNode] the node that governs this
+            #   propagation event.
+            # @param target [Object] the Target to which to propagate.
             def apply_untags propagation_node, target
               return unless propagation_node.untags
               return unless (properties = Contrast::Agent::Assess::Tracker.properties(target))
@@ -214,6 +221,10 @@ module Contrast
             private
 
             # This is checked right before actual propagation
+            # @param propagation_node [Contrast::Agent::Assess::Policy::PropagationNode] the node that governs this
+            #   propagation event.
+            # @param target [Object] the Target to which to propagate.
+            # @return [Boolean]
             def propagation_possible? propagation_node, target
               return false unless propagation_node && valid_target?(target, propagation_node)
               return false unless valid_length?(target, propagation_node.action)
@@ -224,12 +235,24 @@ module Contrast
             # Safely duplicate the target, or return nil
             #
             # @param target [Object] the thing to check for duplication
+            # @return [Object, nil]
             def safe_dup target
               target.dup
             rescue StandardError => _e
               nil
             end
 
+            # Iterate over each key and value in a hash to allow for propagation to each.
+            #
+            # @param propagation_node [Contrast::Agent::Assess::Policy::PropagationNode] the node that governs this
+            #   propagation event.
+            # @param preshift [Contrast::Agent::Assess::PreShift] The capture of the state of the code just prior to
+            #   the invocation of the patched method.
+            # @param target [Object] the Target to which to propagate.
+            # @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 block [Block] the Block passed to the original method
             def handle_hash_propagation propagation_node, preshift, target, object, ret, args, block
               target.each_pair do |key, value|
                 apply_propagator(propagation_node, preshift, key, object, ret, args, block)
@@ -237,6 +260,17 @@ module Contrast
               end
             end
 
+            # Iterate over each value in an enumerable to allow for propagation to each.
+            #
+            # @param propagation_node [Contrast::Agent::Assess::Policy::PropagationNode] the node that governs this
+            #   propagation event.
+            # @param preshift [Contrast::Agent::Assess::PreShift] The capture of the state of the code just prior to
+            #   the invocation of the patched method.
+            # @param target [Object] the Target to which to propagate.
+            # @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 block [Block] the Block passed to the original method
             def handle_enumerable_propagation propagation_node, preshift, target, object, ret, args, block
               target.each do |value|
                 next if target == value
@@ -245,6 +279,17 @@ module Contrast
               end
             end
 
+            # Move the properties from the source(s) to the target of the propagation.
+            #
+            # @param propagation_node [Contrast::Agent::Assess::Policy::PropagationNode] the node that governs this
+            #   propagation event.
+            # @param preshift [Contrast::Agent::Assess::PreShift] The capture of the state of the code just prior to
+            #   the invocation of the patched method.
+            # @param target [Object] the Target to which to propagate.
+            # @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 _block [Block] the Block passed to the original method
             def handle_cs_properties_propagation propagation_node, preshift, target, object, ret, args, _block
               return if propagation_node.action == NOOP_ACTION
               return unless can_propagate?(propagation_node, preshift, target)
@@ -266,12 +311,9 @@ module Contrast
               propagation_class.propagate(propagation_node, preshift, target)
               # Once we've propagated, attempt to tag the target if there is a tag(s) to be applied
               apply_tags(propagation_node, target)
-              # Even though we skipped propagating tags from the source if they
-              # were included in untags, the target may have already had some on
-              # it. Let's go ahead and remove them.
-              # In this order, untags takes precedent over tags; but we control
-              # both and there should never be a propagator that has a tag in
-              # its untag.
+              # Even though we skipped propagating tags from the source if they were included in untags, the target may
+              # have already had some on it. Let's go ahead and remove them. In this order, untags takes precedent over
+              # tags; but we control both and there should never be a propagator that has a tag in its untag.
               apply_untags(propagation_node, target)
               return unless (properties = Contrast::Agent::Assess::Tracker.properties!(target))
 
@@ -302,7 +344,8 @@ module Contrast
             #   propagation event.
             # @return [Boolean]
             def can_handle_frozen? propagation_node
-              ::Contrast::ASSESS.track_frozen_sources? && propagation_node.targets[0] == Contrast::Utils::ObjectShare::RETURN_KEY
+              ::Contrast::ASSESS.track_frozen_sources? &&
+                  propagation_node.targets[0] == Contrast::Utils::ObjectShare::RETURN_KEY
             end
           end
         end