contrast-agent 7.5.0 → 7.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6b34ada48cf9e91e05d85ea0f003575119b751bf135ef49709fb1501c475b3e
-  data.tar.gz: 2915fb037c832fec213dfc7835b8d732e1c22005987ef2c4287dfb55264d41a2
+  metadata.gz: 8363c48e9a12500ea45f3d40389d6bf29d7931e01599a577dfb4026c9cedc260
+  data.tar.gz: 1c21202db2612d8715f1658fa9818442e16a5a51f613143a3c3c6b69c0a0fabf
 SHA512:
-  metadata.gz: 627d1959c5993100f6bc08624d1a68627b02af18f6aa48c074f0cf374925877761b09077ce21366b6d5ddafb3185907472564753b3fbab65f6f7d74d2b74dc10
-  data.tar.gz: 224228b9e9c276c39e6d78a330a456b37cf550b4155c4b96f5ff1d29e7bf7846521c102f510061f8d6ec5e9245b99fe567cce7a5202dd2acfd62c6e7bb9ca795
+  metadata.gz: 4f5fe5203e78e7ea7c6e996c32367c340704f3d1544890b64ed856d3554ef53f3006cc948fab0f3d36108e1577d19196249c10ee8f0fcee95c8677115b7a4a64
+  data.tar.gz: 7a1d876e9c49940daf97589adaaf5d2550fdbd51bd2216f44a28bf4f97ab9431a5b5db200035089a76bfbe66bf8849aed58f382ee99e7e681e555b8da5097af5

data/ext/cs__common/cs__common.c

@@ -28,12 +28,12 @@ void patch_via_funchook(void *original_function, void *hook_function) {
 
     void *funchook_lib_handle;
     void *funchook_reference, *(*funchook_create)(void);
-    /* This variables are used to load the funchook dylib */
-    #pragma GCC diagnostic ignored "-Wunused-but-set-variable"
-    #pragma GCC diagnostic push
+/* This variables are used to load the funchook dylib */
+#pragma GCC diagnostic ignored "-Wunused-but-set-variable"
+#pragma GCC diagnostic push
     int prepareResult, (*funchook_prepare)(void *, void **, void *);
     int installResult, (*funchook_install)(void *, int);
-    #pragma GCC diagnostic pop
+#pragma GCC diagnostic pop
 
     funchook_lib_handle =
         dlopen(StringValueCStr(funchook_path), RTLD_NOW | RTLD_GLOBAL);
@@ -198,7 +198,7 @@ extern VALUE contrast_lookout_prepended(VALUE self, VALUE object_name,
 }
 
 VALUE _contrast_check_prepended(VALUE object, VALUE method_name,
-                                       VALUE is_instance) {
+                                VALUE is_instance) {
     VALUE entry, ancestors, entry_methods;
     VALUE result = Qfalse;
     VALUE object_idx = Qnil;

data/ext/cs__contrast_patch/cs__contrast_patch.c

@@ -107,7 +107,8 @@ VALUE rescue_func(VALUE arg1) {
  *
  **/
 VALUE contrast_patch_call_ensure(const VALUE *args) {
-    /* we do not need to ensure that post patch is called if no error was thrown */
+    /* we do not need to ensure that post patch is called if no error was thrown
+     */
     if (!RTEST(rb_errinfo())) {
         return Qnil;
     }

data/ext/cs__scope/cs__scope.c

@@ -3,9 +3,9 @@
 
 #include "cs__scope.h"
 #include "../cs__common/cs__common.h"
+#include <pthread.h>
 #include <ruby.h>
 #include <stdlib.h>
-#include <pthread.h>
 
 /*-----------------------------------------
  |  Calls to Contrast modules and classes
@@ -161,8 +161,8 @@ VALUE contrast_scope_application_update() {
     return INT2FIX(env_var_set(eVar));
 }
 
-/** 
- * @brief Determines if the Contrast Scope should be set with the Trap Context. 
+/**
+ * @brief Determines if the Contrast Scope should be set with the Trap Context.
  * @return 1 if set, 0 if not set.
  */
 int contrast_scope_with_trap_context() {
@@ -556,7 +556,7 @@ VALUE contrast_scope_for_current_ec(VALUE self, VALUE args) {
          * different thread, at once, but since the mutex stays  in
          * the C API context, this might work fine. Still use  only
          * when unusual conditions are met.
-         * 
+         *
          * In addition we could use C mutex lock just in case. Ruby
          * Threads under the hood are C threads (pthread),  so they
          * should be treated as such. In theory only one thread can
@@ -894,7 +894,8 @@ void Init_cs__scope() {
     rb_const_ec = "EXECUTION_CONTEXT";
     rb_const_ec_keys = "EC_KEYS";
     c_const_ctr_agent_app_scope = "CONTRAST__AGENT__RUBY__APPLICATION_SCOPE";
-    c_const_ctr_agent_scope_trap_context = "CONTRAST__AGENT__SCOPE__WITH_TRAP_CONTEXT";
+    c_const_ctr_agent_scope_trap_context =
+        "CONTRAST__AGENT__SCOPE__WITH_TRAP_CONTEXT";
 
     /* Symbols */
     rb_sym_scope_mod = rb_intern("Scope");

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

@@ -5,9 +5,18 @@ module Contrast
   module Agent
     module Assess
       module Events
-        # this class will gather and build event
+        # this class will gather and build event.
         class EventData
-          attr_reader :policy_node, :tagged, :object, :ret, :args
+          # @return [Contrast::Agent::Assess::Policy::PolicyNode, nil] the node that governs this event.
+          attr_reader :policy_node
+          # @return [Object, nil] the Target to which this event pertains.
+          attr_reader :tagged
+          # @return [Object, nil] the Object on which the method was invoked.
+          attr_reader :object
+          # @return [Object, nil] the Return of the invoked method.
+          attr_reader :ret
+          # @return [Array<Object>, nil] the Arguments with which the method was invoked.
+          attr_reader :args
 
           # Group event data together
           #

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

@@ -8,6 +8,7 @@ require 'contrast/agent/assess/tracker'
 class Object
   alias_method :cs__patched_object_freeze, :freeze
 
+  # Applies the the freeze patch and handles the pre-finalizes the object.
   def freeze
     Contrast::Agent::Assess::Tracker.pre_freeze(self)
     cs__patched_object_freeze

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

@@ -16,6 +16,10 @@ module Contrast
           FROZEN_FINALIZED_IDS = Set.new
           KEEP_AGE = 600_000.cs__freeze # 10 minutes
 
+          # Store the given Object in the Hash, using its __id__ as the key. If the Object is frozen, we need to
+          # pre-finalize it and store its __id__ in our tracking Set.
+          #
+          # @return [Object] the Object stored
           def []= key, obj
             return unless obj
             return unless ::Contrast::AGENT.enabled? && ::Contrast::ASSESS.enabled?
@@ -29,6 +33,9 @@ module Contrast
             super(key.__id__, obj)
           end
 
+          # Retrieves the Object stored in the Hash by its __id__.
+          #
+          # @return [Object, nil] the Object stored.
           def [] key
             super(key.__id__)
           end

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

@@ -34,6 +34,8 @@ module Contrast
             # load. These methods only exist once a module or class eval has been
             # called. This hook is provided so that patches to those methods can
             # pass us execution flow once a new method has been made available.
+            #
+            # @param mod [Module]
             def patch_assess_on_eval mod
               return unless ::Contrast::ASSESS.enabled?
               return if in_contrast_scope?

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

@@ -34,6 +34,8 @@ module Contrast
 
           # Indicates is this feature has been disabled by the configuration,
           # read at startup, and therefore can never be enabled.
+          #
+          # @return [Boolean] if this feature is disabled
           def disabled_globally?
             ::Contrast::ASSESS.forcibly_disabled?
           end
@@ -49,6 +51,8 @@ module Contrast
           # This let's us be flexible and extensible
           # * when we want to do lvl 2 rules, we could have the customers unzip
           # our gem, insert things into the json, zip, and go *
+          #
+          # @param string [String]
           def from_hash_string string
             # The default behavior of the agent is to load the policy on startup,
             # as at this point we do not know in which mode we'll be run.

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

@@ -26,8 +26,17 @@ module Contrast
           JSON_TARGET = 'target'
           TO_MARKER = '2'
 
-          attr_accessor :tags, :type
-          attr_reader   :sources, :targets, :source_string, :target_string
+          # @return [Set<String>]
+          attr_accessor :tags
+          # @return [Symbol]
+          attr_accessor :type
+          attr_reader   :sources
+          # @return [Array<String>]
+          attr_reader :targets
+          # @return [String]
+          attr_reader :source_string
+          # @return [String]
+          attr_reader :target_string
 
           # Here are all methods that can use original objects without mutation the source.
           # For methods with REMOVE action, their (!) bang alternative is not listed, since
@@ -68,6 +77,8 @@ module Contrast
           # String#to_s => self or string. This method is included here to cover the situations such as
           # String.to_s.html_safe, where normally the dynamic sources properties get lost. To solve this
           # we will simply return the original object here.
+          #
+          # @param policy_hash [Hash]
           def assign_on_bang_check policy_hash
             return true if @_use_original_object && TO_S.include?(policy_hash[JSON_METHOD_NAME])
 
@@ -76,18 +87,24 @@ module Contrast
                 policy_hash[JSON_METHOD_NAME].end_with?(Contrast::Utils::ObjectShare::BANG)
           end
 
+          # @return [String]
           def feature
             'Assess'
           end
 
+          # @return [String]
           def node_class
             'Node'
           end
 
+          # @return [Symbol]
           def node_type
             :TYPE_METHOD
           end
 
+          # Set the target string.
+          #
+          # @param value [String]
           def target_string= value
             @target_string = value
             @targets = convert_policy_markers(value)
@@ -96,6 +113,9 @@ module Contrast
           # Sometimes we need to tie information to an event. We'll add a
           # properties section to the patch node, which can pass them along to
           # the pre-dtm event
+          #
+          # @param name [String]
+          # @param value [String]
           def add_property name, value
             return unless name && value
 
@@ -103,6 +123,8 @@ module Contrast
             @properties[name] = value
           end
 
+          # @param name [String]
+          # @return [String]
           def get_property name
             return unless @properties
 
@@ -112,6 +134,8 @@ module Contrast
           # Don't let nodes be created that will be missing things we need
           # later on. Really, if they don't have these things, they couldn't have
           # done their jobs anyway.
+          #
+          # @raise [ArgumentError] raises if the node is invalid.
           def validate
             super
             validate_tags
@@ -124,11 +148,10 @@ module Contrast
           # isn't a matching ENUM in TS land, the database gets got. We really
           # don't want to get them, so we're going to prevent the node from being
           # made.
+          #
           # @raise[ArgumentError] raises if any of the tags is invalid
           def validate_tags
-            return unless tags
-
-            tags.each do |tag|
+            tags&.each do |tag|
               next if Contrast::Agent::Reporting::FindingEventTaintRangeTags::VALID_TAGS.include?(tag) ||
                   Contrast::Agent::Reporting::FindingEventTaintRangeTags::VALID_SOURCE_TAGS.include?(tag)
 
@@ -159,8 +182,7 @@ module Contrast
                                   # by changing them to 'A'
                                   source = all_type?(source_string) ? ALL_TYPE : source_string
                                   target = all_type?(target_string) ? ALL_TYPE : target_string
-                                  str = source[0] + TO_MARKER + target[0]
-                                  str.to_sym
+                                  (source[0] + TO_MARKER + target[0]).to_sym
                                 end
                               end
 

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

@@ -21,7 +21,15 @@ module Contrast
         UNDUPLICABLE_MODULES << IO::Buffer if RUBY_VERSION >= '3.1.0'
         UNDUPLICABLE_MODULES.cs__freeze
 
-        attr_accessor :object, :object_length, :args, :arg_lengths
+        # @return [Object] the object on which the method is to be called.
+        attr_accessor :object
+        # @return [Integer] the length of the object on which the method is to
+        #  be called.
+        attr_accessor :object_length
+        # @return [Array<Object>] the arguments to be passed to the method.
+        attr_accessor :args
+        # @return [Array<Integer>] the lengths of the arguments to be passed to
+        attr_accessor :arg_lengths
 
         class << self
           # Save the state before we do the propagation. This is one of the
@@ -65,10 +73,23 @@ module Contrast
 
           private
 
+          # Determine if the given object is an IO object that is closed, not in
+          # initialization, and therefore unsafe to use.
+          #
+          # @param object [Object] the object on which the method is to be
+          #  called.
+          # @param initializing [Boolean] whether or not the method being
+          # called is the initialize method.
           def unsafe_io_object? object, initializing
             Contrast::Utils::DuckUtils.closable_io?(object) && !initializing && object.closed?
           end
 
+          # check if object is duplicable
+          #
+          # @param initializing [Boolean] whether or not the method being
+          # called is the initialize method.
+          # @param object [Object] the object on which the method is to be
+          # called.
           def can_dup? initializing, object
             return false if initializing
 
@@ -76,6 +97,14 @@ module Contrast
             !UNDUPLICABLE_MODULES.include?(check)
           end
 
+          # Appends the object details to the given preshift and adds it to the LRU cache.
+          #
+          # @param preshift [Contrast::Agent::Assess::PreShift] the preshift to
+          #  which the object details should be appended.
+          # @param initializing [Boolean] whether or not the method being
+          # called is the initialize method.
+          # @param object [Object] the object on which the method is to be
+          # called.
           def append_object_details preshift, initializing, object
             can = can_dup?(initializing, object)
             preshift.object = if @lru_cache.key?(object.__id__) && !Contrast::Agent::Assess::Tracker.tracked?(object)
@@ -97,6 +126,10 @@ module Contrast
             @lru_cache[object.__id__] = object
           end
 
+          # @param preshift [Contrast::Agent::Assess::PreShift] the preshift to
+          # which the argument details should be appended.
+          # @param args [Array<Object>] the arguments to be passed to the
+          # method.
           def append_arg_details preshift, args
             args_length = args.length
             preshift.args = Array.new(args_length)

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

@@ -88,6 +88,7 @@ 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.
@@ -101,6 +102,9 @@ module Contrast
               end
             end
 
+            # Checks to see if the given target is valid for propagation.
+            #
+            # @return [Bool]
             def context_available?
               !!Contrast::Agent::REQUEST_TRACKER.current
             end
@@ -121,7 +125,8 @@ module Contrast
 
             private
 
-            # This is checked right before actual propagation
+            # 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.
@@ -198,6 +203,10 @@ module Contrast
               increment_event_count(propagation_node)
             end
 
+            # @param propagation_class [Contrast::Agent::Assess::Policy::Propagator]
+            # @param propagation_node [Contrast::Agent::Assess::Policy::PropagationNode]
+            # @param source [Object] The object from which the propagation begins.
+            # @param target [Object] the Target to which to propagate.
             def handle_propagation propagation_class, propagation_node, source, target
               if propagation_node.patch_method
                 propagation_class.send(propagation_node.patch_method, propagation_node, source, target)
@@ -206,6 +215,12 @@ module Contrast
               end
             end
 
+            # @param propagation_node [Contrast::Agent::Assess::Policy::PropagationNode]
+            # @param target [Object] the Target to which to propagate.
+            # @param propagation_data [Contrast::Agent::Assess::Events::EventData] this will hold the
+            #                         object [Object] the Object on which the method was invoked
+            #                         ret [Object] the Return of the invoked method
+            #                         args [Array<Object>] the Arguments with which the method was invoked
             def update_properties propagation_node, target, propagation_data
               if propagation_node.use_original_on_bang_method?
                 properties = use_original_object_properties(propagation_data)

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

@@ -22,7 +22,34 @@ module Contrast
           JSON_PATCH_CLASS = 'patch_class'
           JSON_PATCH_METHOD = 'patch_method'
 
-          attr_reader :action, :untags, :patch_method
+          # @return action [String] the action to be taken by this propagation
+          #  node. This can be one of the following:
+          # - 'CUSTOM' - the propagation node is a custom propagation node
+          # - 'DB_WRITE' - the propagation node is a database write propagation
+          #  node
+          # - 'APPEND' - the propagation node is an append propagation node
+          # - 'CENTER' - the propagation node is a center propagation node
+          # - 'INSERT' - the propagation node is an insert propagation node
+          # - 'KEEP' - the propagation node is a keep propagation node
+          # - 'NEXT' - the propagation node is a next propagation node
+          # - 'BUFFER' - the propagation node is a buffer propagation node
+          # - 'NOOP' - the propagation node is a noop propagation node
+          # - 'PREPEND' - the propagation node is a prepend propagation node
+          # - 'REPLACE' - the propagation node is a replace propagation node
+          # - 'REMOVE' - the propagation node is a remove propagation node
+          # - 'REVERSE' - the propagation node is a reverse propagation node
+          # - 'RESPONSE' - the propagation node is a response propagation node
+          # - 'SPLAT' - the propagation node is a splat propagation node
+          # - 'SPLIT' - the propagation node is a split propagation node
+          attr_reader :action
+          # @return untags [Array<String>] the tags to be removed from the
+          # target of this propagation node.
+          attr_reader :untags
+          # @return patch_class [String] the class name of the class that
+          # contains the method to be called for this propagation node.
+          attr_reader :patch_method
+          # @return patch_method [Symbol] the name of the method to be called
+          # for this propagation node.
           attr_accessor :patch_class
 
           TAGGER = 'Tagger'
@@ -36,6 +63,9 @@ module Contrast
           # Tags - array of tags to apply to the target, can be nil if no tags are added
           # Untags - array of tags to remove from the target, can be nil if not tags are removed
           # id, class_name, instance_method, method_name, source, target, action, tags = nil, untags = nil
+          #
+          # @param propagation_hash [Hash] the hash from which to build the
+          #   propagation node.
           def initialize propagation_hash = {}
             super(propagation_hash)
             @action = propagation_hash[JSON_ACTION]
@@ -49,6 +79,7 @@ module Contrast
             nil
           end
 
+          # @return [String] class name
           def node_class
             @_node_class ||= tagger? ? TAGGER : PROPAGATOR
           end
@@ -56,12 +87,15 @@ module Contrast
           # Unlike the other agents, we don't have separate tag & propagation
           # events. To make TS happy, we need to have different types though.
           # Pretty straight forward: if there's a tag, this is a tagger
+          #
+          # @return [Symbol] the type of node.
           def node_type
             tagger? ? :TYPE_TAG : :TYPE_PROPAGATION
           end
 
           # Standard validation + TS trace version two rules:
           # Must have source, target, and action
+          #
           # @raise[ArgumentError] raises if any of the required propagation node field is not valid, or is missing
           def validate
             super
@@ -100,6 +134,8 @@ module Contrast
             end
           end
 
+          # @return [Boolean]
+          #  propagation node.
           def needs_object?
             if @_needs_object.nil?
               @_needs_object = action == Contrast::Utils::Assess::PropagationMethodUtils::CUSTOM_ACTION ||
@@ -110,6 +146,7 @@ module Contrast
             @_needs_object
           end
 
+          # @return [Boolean]
           def needs_args?
             if @_needs_args.nil?
               @_needs_args = action == Contrast::Utils::Assess::PropagationMethodUtils::CUSTOM_ACTION ||
@@ -124,6 +161,8 @@ module Contrast
           # It indicates this method is more than just a transformation,
           # it is an interesting security event that has a meaningful
           # change.
+          #
+          # @return [Boolean]
           def tagger?
             @_tagger = tags&.any? || untags&.any? if @_tagger.nil?
             @_tagger

data/lib/contrast/agent/assess/policy/propagator/append.rb

@@ -15,6 +15,11 @@ module Contrast
               # if the target length is greater than the source
               # copy tags from the param to the target in chunks of param size or less
               # if param is appended in space less than param length
+              #
+              # @param propagation_node [Contrast::Agent::Assess::Policy::PropagationNode] the node responsible for the
+              #  propagation action required by this method.
+              # @param preshift [Object] pre call state of the things.
+              # @param target [Object] the object to which the source is being appended
               def propagate propagation_node, preshift, target
                 return unless (properties = Contrast::Agent::Assess::Tracker.properties!(target))
 

data/lib/contrast/agent/assess/policy/propagator/base.rb

@@ -12,6 +12,10 @@ module Contrast
           # to pass tags from it to a Target.
           class Base
             class << self
+              # Retrieve the source from the preshift state.
+              #
+              # @param source [Symbol] the source to retrieve.
+              # @param preshift [Contrast::Agent::Assess::PreShift] the pre-call state of the things.
               def find_source source, preshift
                 case source
                 when Contrast::Utils::ObjectShare::OBJECT_KEY
@@ -21,10 +25,16 @@ module Contrast
                 end
               end
 
+              # Check if tags are present on the given target.
+              #
+              # @return [Boolean]
               def tracked_value? value
                 Contrast::Agent::Assess::Tracker.tracked?(value)
               end
 
+              # Propagate the tags from the source to the target.
+              # This method should be extended by the subclasses.
+              #
               # @raise [NoMethodError] This is being raised if any of the implementing subclasses does not have
               #     that method implemented, but is being called on.
               def propagate _propagation_node, _preshift, _target

data/lib/contrast/agent/assess/policy/propagator/buffer.rb

@@ -17,6 +17,12 @@ module Contrast
               # Once the tag is applied, shift it to the location of the insert
               # Unlike additive propagation, this currently only supports one source
               # We assume that insert changes the preshift target
+              #
+              # @param propagation_node [Contrast::Agent::Assess::Policy::PropagationNode] the node responsible for the
+              # propagation action required by this method.
+              # @param preshift [Object] pre call state of the things.
+              # @param target [Object] the object to which the source is being appended
+              # @return [Object] the target with the tags applied
               def propagate_insert propagation_node, preshift, target
                 return unless (properties = Contrast::Agent::Assess::Tracker.properties!(target))
 

data/lib/contrast/agent/assess/policy/propagator/center.rb

@@ -11,6 +11,11 @@ module Contrast
           # are unaffected beyond any merging of overlapping tags.
           class Center < Contrast::Agent::Assess::Policy::Propagator::Base
             class << self
+              # @param propagation_node [Contrast::Agent::Assess::Policy::PropagationNode] the node responsible for the
+              # propagation action required by this method.
+              # @param preshift [Object] pre call state of the things.
+              # @param target [Object] the object to which the source is being appended
+              # @return [Object] the target with the tags applied
               def propagate propagation_node, preshift, target
                 return unless (properties = Contrast::Agent::Assess::Tracker.properties!(target))
 
@@ -56,6 +61,15 @@ module Contrast
                 iterate_tags(target, propagation_node, source, end_index, target.length)
               end
 
+              # This method will iterate over the tags of the source and apply
+              # them to the target.
+              #
+              # @param target [Object] the thing to apply tags to.
+              # @param propagation_node [Contrast::Agent::Assess::Policy::PropagationNode]
+              #  the node that indicates how this propagation should be handled.
+              # @param source [Object] the thing to copy tags from.
+              # @param start [Integer] where to start copying tags from.
+              # @param stop [Integer] where to stop copying tags from.
               def iterate_tags target, propagation_node, source, start, stop
                 properties = Contrast::Agent::Assess::Tracker.properties(target)
                 while start < stop

data/lib/contrast/agent/assess/policy/propagator/custom.rb

@@ -17,6 +17,12 @@ module Contrast
             extend Contrast::Utils::Assess::EventLimitUtils
 
             class << self
+              # @param  propagation_node [Contrast::Agent::Assess::Policy::PropagationNode] the node responsible for the
+              #  propagation action required by this method.
+              # @param preshift [Object] pre call state of the things.
+              # @param ret [Object] the return value of the method.
+              # @param block [Proc] the block passed to the method.
+              # @return [Object] the return value of the method.
               def propagate propagation_node, preshift, ret, block
                 clazz = propagation_node.patch_class
                 method = propagation_node.patch_method

data/lib/contrast/agent/assess/policy/propagator/database_write.rb

@@ -16,6 +16,11 @@ module Contrast
             extend Contrast::Utils::Assess::EventLimitUtils
 
             class << self
+              # @param propagation_node [Contrast::Agent::Assess::Policy::PropagationNode] the node responsible for the
+              # propagation action required by this method.
+              # @param preshift [Object] pre call state of the things.
+              # @param target [Object] the object to which the source is being appended
+              # @return [Object] the target with the tags applied
               def propagate propagation_node, preshift, target
                 return unless Contrast::ASSESS.require_dynamic_sources?
 
@@ -41,6 +46,15 @@ module Contrast
 
               private
 
+              # Handles the write propagation for the given source.
+              #
+              # @param propagation_node [Contrast::Agent::Assess::Policy::PropagationNode] the node responsible for the
+              # propagation action required by this method.
+              # @param source [Symbol] the source to retrieve.
+              # @param preshift [Contrast::Agent::Assess::PreShift] the pre-call state of the things.
+              # @param target [Object] the object to which the source is being appended
+              # @param known_tainted [Array] the list of known tainted columns
+              # @param tainted_columns [Hash] the hash of tainted columns
               def handle_write propagation_node, source, preshift, target, known_tainted, tainted_columns
                 arg = preshift.args[source]
                 return unless arg.cs__respond_to?(:each_pair)

data/lib/contrast/agent/assess/policy/propagator/insert.rb

@@ -15,6 +15,12 @@ module Contrast
               # Once the tag is applied, shift it to the location of the insert
               # Unlike additive propagation, this currently only supports one source
               # We assume that insert changes the preshift target
+              #
+              # @param propagation_node [Contrast::Agent::Assess::Policy::PropagationNode] the node responsible for the
+              # propagation action required by this method.
+              # @param preshift [Object] pre call state of the things.
+              # @param target [Object] the object to which the source is being appended
+              # @return [Object] the target with the tags applied
               def propagate propagation_node, preshift, target
                 return unless (properties = Contrast::Agent::Assess::Tracker.properties!(target))