contrast-agent 4.12.0 → 4.14.1

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

@@ -0,0 +1,232 @@
+# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+module Contrast
+  module Utils
+    module Patching
+      # This module will include all methods for different patch applies from Patch module
+      # and some other module methods from the same place, so we can ease the main module
+      module PatchUtils
+        # Method to choose which replaced return from the post_patch to
+        # actually return
+        #
+        # @param propagated_ret [Object, nil] The replaced return from the
+        #   propagation patch.
+        # @param source_ret [Object, nil] The replaced return from the
+        #   source patch.
+        # @param ret [Object, nil] The original return of the patched
+        #   method.
+        # @return [Object, nil] The thing to return from the post patch.
+        def handle_return propagated_ret, source_ret, ret
+          safe_return = propagated_ret || source_ret || ret
+          safe_return.rewind if Contrast::Utils::IOUtil.should_rewind?(safe_return)
+          safe_return
+        end
+
+        # Given a module and method, construct an expected name for the
+        # alias by which Contrast will reference the original.
+        #
+        # @param patched_class [Module] the module being patched
+        # @param patched_method [Symbol] the method being patched
+        # @return [Symbol]
+        def build_method_name patched_class, patched_method
+          (Contrast::Utils::ObjectShare::CONTRAST_PATCHED_METHOD_START +
+            patched_class.cs__name.gsub('::', '_').downcase +
+            Contrast::Utils::ObjectShare::UNDERSCORE +
+            patched_method.to_s).to_sym
+        end
+
+        # Given a method, return a symbol in the format
+        # <method_start>_unbound_<method_name>
+        def build_unbound_method_name patcher_method
+          (Contrast::Utils::ObjectShare::CONTRAST_PATCHED_METHOD_START +
+            'unbound' +
+            Contrast::Utils::ObjectShare::UNDERSCORE +
+            patcher_method.to_s).to_sym
+        end
+
+        # ===== PATCH APPLIERS =====
+        # THIS IS CALLED FROM C. Do not change the signature lightly.
+        #
+        # This method functions to call the infilter methods from our
+        # patches, allowing for analysis and reporting at the point just
+        # before the patched code is invoked.
+        #
+        # @param method_policy [Contrast::Agent::Patching::Policy::MethodPolicy]
+        #   Mapping of the triggers on the given method.
+        # @param method [Symbol] The method into which we're patching
+        # @param exception [StandardError] Any exception raised during the
+        #   call of the patched method.
+        # @param object [Object] The object on which the method is invoked,
+        #   typically what would be returned by self.
+        # @param args [Array<Object>] The arguments passed to the method
+        #   being invoked.
+        def apply_pre_patch method_policy, method, exception, object, args
+          apply_protect(method_policy, method, exception, object, args)
+          apply_inventory(method_policy, method, exception, object, args)
+        rescue Contrast::SecurityException => e
+          # We were told to block something, so we gotta. Don't catch this
+          # one, let it get back to our Middleware or even all the way out to
+          # the framework
+          raise e
+        rescue StandardError => e
+          # Anything else was our bad and we gotta catch that to allow for
+          # normal application flow
+          logger.error('Unable to apply pre patch to method.', e)
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          # This is something like NoMemoryError that we can't
+          # hope to handle.  Nonetheless, shouldn't leak scope.
+          exit_contrast_scope!
+          raise e
+        end
+
+        # THIS IS CALLED FROM C. Do not change the signature lightly.
+        #
+        # This method functions to call the infilter methods from our
+        # patches, allowing for analysis and reporting at the point just
+        # after the patched code is invoked
+        #
+        # @param method_policy [Contrast::Agent::Patching::Policy::MethodPolicy]
+        #   Mapping of the triggers on the given 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, typically what would be returned by self.
+        # @param ret [Object] The return of the method that was invoked.
+        # @param args [Array<Object>] The arguments passed to the method
+        #   being invoked.
+        # @param block [Proc] The block passed to the method that was
+        #   invoked.
+        def apply_post_patch method_policy, preshift, object, ret, args, block
+          apply_assess(method_policy, preshift, object, ret, args, block)
+        rescue StandardError => e
+          logger.error('Unable to apply post patch to method.', e)
+        end
+
+        # Apply the Protect patch which applies to the given method.
+        #
+        # @param method_policy [Contrast::Agent::Patching::Policy::MethodPolicy]
+        #   Mapping of the triggers on the given method.
+        # @param method [Symbol] The method into which we're patching
+        # @param exception [StandardError] Any exception raised during the
+        #   call of the patched method.
+        # @param object [Object] The object on which the method is invoked,
+        #   typically what would be returned by self.
+        # @param args [Array<Object>] The arguments passed to the method
+        #   being invoked.
+        def apply_protect method_policy, method, exception, object, args
+          return unless ::Contrast::AGENT.enabled?
+          return unless ::Contrast::PROTECT.enabled?
+
+          apply_trigger_only(method_policy&.protect_node, method, exception, object, args)
+        end
+
+        # Apply the Inventory patch which applies to the given method.
+        #
+        # @param method_policy [Contrast::Agent::Patching::Policy::MethodPolicy]
+        #   Mapping of the triggers on the given method.
+        # @param method [Symbol] The method into which we're patching
+        # @param exception [StandardError] Any exception raised during the
+        #   call of the patched method.
+        # @param object [Object] The object on which the method is invoked,
+        #   typically what would be returned by self.
+        # @param args [Array<Object>] The arguments passed to the method
+        #   being invoked.
+        def apply_inventory method_policy, method, exception, object, args
+          return unless ::Contrast::INVENTORY.enabled?
+
+          apply_trigger_only(method_policy&.inventory_node, method, exception, object, args)
+        end
+
+        # Apply the Assess patches which apply to the given method.
+        #
+        # @param method_policy [Contrast::Agent::Patching::Policy::MethodPolicy]
+        #   Mapping of the triggers on the given 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, typically what would be returned by self.
+        # @param ret [Object] The return of the method that was invoked.
+        # @param args [Array<Object>] The arguments passed to the method
+        #   being invoked.
+        # @param block [Proc] The block passed to the method that was
+        #   invoked.
+        def apply_assess method_policy, preshift, object, ret, args, block
+          source_ret = nil
+          propagated_ret = nil
+          return ret unless method_policy && ::Contrast::ASSESS.enabled?
+
+          current_context = Contrast::Agent::REQUEST_TRACKER.current
+          return ret if current_context && !current_context.analyze_request?
+
+          trigger_node = method_policy.trigger_node
+          if trigger_node
+            Contrast::Agent::Assess::Policy::TriggerMethod.apply_trigger_rule(trigger_node, object, ret, args)
+          end
+          if method_policy.source_node
+            # If we were given a frozen return, and it was the target of a
+            # source, and we have frozen sources enabled, we'll need to
+            # replace the return. Note, this is not the default case.
+            source_ret = Contrast::Agent::Assess::Policy::SourceMethod.source_patchers(method_policy, object, ret, args)
+          end
+          if method_policy.propagation_node
+            propagated_ret = Contrast::Agent::Assess::Policy::PropagationMethod.apply_propagation(
+                method_policy,
+                preshift,
+                object,
+                source_ret || ret,
+                args,
+                block)
+          end
+          handle_return(propagated_ret, source_ret, ret)
+        rescue StandardError => e
+          logger.error('Unable to assess method call.', e)
+          handle_return(propagated_ret, source_ret, ret)
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          logger.error('Unable to assess method call.', e)
+          handle_return(propagated_ret, source_ret, ret)
+          raise e
+        end
+
+        # Generic invocation of the Inventory or Protect patch which apply
+        # to the given method.
+        #
+        # @param trigger_node [Contrast::Agent::Inventory::Policy::TriggerNode]
+        #   Mapping of the specific trigger on the given method.
+        # @param method [Symbol] The method into which we're patching
+        # @param exception [StandardError] Any exception raised during the
+        #   call of the patched method.
+        # @param object [Object] The object on which the method is invoked,
+        #   typically what would be returned by self.
+        # @param args [Array<Object>] The arguments passed to the method
+        #   being invoked.
+        def apply_trigger_only trigger_node, method, exception, object, args
+          return unless trigger_node
+
+          # If that rule only applies in the case of an exception being
+          # thrown and there's no exception here, move along, or vice versa
+          return if trigger_node.on_exception && !exception
+          return if !trigger_node.on_exception && exception
+
+          # Each patch has an applicator that handles logic for it. Think
+          # of this as being similar to propagator actions, most closely
+          # resembling CUSTOM - they all have a common interface but their
+          # own logic based on what's in the method(s) they've been patched
+          # into.
+          # Each patch also knows the method of its applicator. Some
+          # things, like AppliesXxeRule, have different methods depending
+          # on the library patched. This lets us handle the boilerplate of
+          # patching while still allowing for custom handling of the
+          # methods.
+          applicator_method = trigger_node.applicator_method
+          # By calling send like this, we can reuse all the patching.
+          # We `send` to the given method of the given class
+          # (applicator) since they all accept the same inputs
+          trigger_node.applicator.send(applicator_method, method, exception, trigger_node.properties, object, args)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+module Contrast
+  module Utils
+    module Patching
+      # This module will include patch methods from Patcher module
+      # in case of need to add new logic to the Patcher
+      # please do it here
+      module PatcherUtils
+        # This method is called by TracePointHook to instrument a specific class during a require
+        # or eval of dynamic class definition
+        def patch_specific_module mod
+          with_contrast_scope do
+            mod_name = mod.cs__name
+            return unless Contrast::Utils::ClassUtil.truly_defined?(mod_name)
+            return if ::Contrast::AGENT.skip_instrumentation?(mod_name)
+
+            load_patches_for_module(mod_name)
+
+            return if all_module_names.none?(mod_name)
+
+            module_data = Contrast::Agent::ModuleData.new(mod, mod_name)
+            patch_into_module(module_data)
+            all_module_names.delete(mod_name) if status_type.get_status(mod).patched?
+          rescue StandardError => e
+            logger.error('Unable to patch module', e, module: mod_name)
+          end
+        end
+
+        # We did it, team. We found a patcher(s) that applies to the given
+        # class (or module) and the given method. Time to do some tracking.
+        #
+        # @param mod [Module] the module in which the patch should be
+        #   placed.
+        # @param methods [Array(Symbol)] all the instance or singleton
+        #   methods in this mod.
+        # @param method_policy [Contrast::Agent::Patching::Policy::MethodPolicy]
+        #   the policy that applies to the given method_name.
+        # @return [Boolean] if patched, either by this invocation or a
+        #   previous, or not
+        def patch_method mod, methods, method_policy
+          return false unless methods&.any? # don't even build the name if there are no methods
+
+          if Contrast::Utils::ClassUtil.prepended_method?(mod, method_policy)
+            Contrast::Agent::Patching::Policy::Patch.instrument_with_prepend(mod, method_policy)
+          else
+            Contrast::Agent::Patching::Policy::Patch.instrument_with_alias(mod, methods, method_policy)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/contrast/utils/request_utils.rb

@@ -0,0 +1,88 @@
+# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+module Contrast
+  module Utils
+    # used in Contrast::Agent::Request
+    module RequestUtils
+      # Return a flattened hash of params with realized paths for keys, in
+      # addition to a separate, valueless, entry for each nest key.
+      # See RUBY-621 for more details.
+      # { key : { nested_key : ['x','y','z' ] } }
+      # becomes
+      # {
+      #   key[nested_key][0] : 'x'
+      #   key[nested_key][1] : 'y'
+      #   key[nested_key][2] : 'z'
+      #   key :                ''
+      #   nested_key :         ''
+      # }
+      def normalize_params val, prefix: nil
+        # In non-recursive invocations, val should always be a Hash
+        # (rather than breaking this out into two methods)
+        case val
+        when Tempfile
+          # Skip if it's the auto-generated value from rails when it handles
+          # file uploads. The file name will still be sent to SR for analysis.
+          {}
+        when Hash
+          res = val.each_with_object({}) do |(k, v), hash|
+            k = Contrast::Utils::StringUtils.force_utf8(k)
+            nested_prefix = prefix.nil? ? k : "#{ prefix }[#{ k }]"
+            hash[k] = Contrast::Utils::ObjectShare::EMPTY_STRING
+            hash.merge! normalize_params(v, prefix: nested_prefix)
+          end
+          res[prefix] = Contrast::Utils::ObjectShare::EMPTY_STRING if prefix
+          res
+        when Enumerable
+          idx = 0
+          res = {}
+          while idx < val.length
+            res.merge! normalize_params(val[idx], prefix: "#{ prefix }[#{ idx }]")
+            idx += 1
+          end
+          res[prefix] = Contrast::Utils::ObjectShare::EMPTY_STRING if prefix
+          res
+        else
+          { prefix => Contrast::Utils::StringUtils.force_utf8(val) }
+        end
+      end
+
+      def read_body body
+        return body if body.is_a?(String)
+
+        begin
+          can_rewind = Contrast::Utils::DuckUtils.quacks_to?(body, :rewind)
+          # if we are after a middleware that failed to rewind
+          body.rewind if can_rewind
+          body.read
+        rescue StandardError => e
+          logger.error('Error in attempt to read body', message: e.message)
+          logger.trace('With Stack', e)
+          body.to_s
+        ensure
+          # be a good citizen and rewind
+          body.rewind if can_rewind
+        end
+      end
+
+      def traverse_parsed_multipart multipart_data, current_names
+        return current_names unless multipart_data
+
+        multipart_data.each_value do |data_value|
+          next unless data_value.is_a?(Hash)
+
+          tempfile = data_value[:tempfile]
+          if tempfile.nil?
+            traverse_parsed_multipart(data_value, current_names)
+          else
+            name = data_value[:name].to_s
+            file_name = data_value[:filename].to_s
+            current_names[name] = file_name
+          end
+        end
+        current_names
+      end
+    end
+  end
+end

data/lib/contrast/utils/response_utils.rb

@@ -0,0 +1,97 @@
+# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+module Contrast
+  module Utils
+    # used in Contrast::Agent::Response
+    module ResponseUtils
+      private
+
+      # From the dtm for normalized_response_headers:
+      #   Key is UPPERCASE_UNDERSCORE
+      #
+      #   Example: Content-Type: text/html; charset=utf-8
+      #   "CONTENT_TYPE" => Content-Type,["text/html; charset=utf8"]
+      def append_pair map, key, value
+        return unless key && value
+        return if value.is_a?(Hash)
+
+        safe_key = Contrast::Utils::StringUtils.force_utf8(key)
+        hash_key = Contrast::Utils::StringUtils.normalized_key(safe_key)
+        map[hash_key] ||= Contrast::Api::Dtm::Pair.new
+        map[hash_key].key = safe_key
+        map[hash_key].values << Contrast::Utils::StringUtils.force_utf8(value)
+      end
+
+      HTTP_PREFIX = /^[Hh][Tt][Tt][Pp][_-]/i.cs__freeze
+
+      # Given some holder of the content of the response's body, extract that
+      # content and return it as a String
+      #
+      # @param body [String, Rack::File, Rack::BodyProxy,
+      #   ActionDispatch::Response::RackBody, Rack::Response] Something that
+      #   holds, wraps, or is the body of the Response
+      # @return [nil, String] the content of the body
+      def extract_body body
+        return unless body
+        return if defined?(Rack::File) && body.is_a?(Rack::File)
+
+        case body
+        when Rack::BodyProxy
+          handle_rack_body_proxy(body)
+        when ActionDispatch::Response::RackBody
+          extract_body(body.body) if defined?(ActionDispatch::Response::RackBody)
+        when Rack::Response
+          extract_body(body.body)
+        when Contrast::Utils::DuckUtils.quacks_to?(body, :each)
+          acc = []
+          body.each { |tmp| acc << read_or_string(tmp) }
+          acc.compact.join(Contrast::Utils::ObjectShare::NEW_LINE)
+        when ActionView::OutputBuffer
+          # https://stackoverflow.com/questions/15654676/how-to-convert-activesupportsafebuffer-to-string
+          body.to_str
+        else
+          read_or_string(body)
+        end
+        # if body.is_a?(Rack::BodyProxy)
+        #   handle_rack_body_proxy(body)
+        # elsif (defined?(ActionDispatch::Response::RackBody) && body.is_a?(ActionDispatch::Response::RackBody)) ||
+        #       body.is_a?(Rack::Response)
+        #
+        #   extract_body(body.body)
+        # elsif Contrast::Utils::DuckUtils.quacks_to?(body, :each)
+        #   acc = []
+        #   body.each { |tmp| acc << read_or_string(tmp) }
+        #   acc.compact.join(Contrast::Utils::ObjectShare::NEW_LINE)
+        # elsif ActionView::OutputBuffer
+        #   # https://stackoverflow.com/questions/15654676/how-to-convert-activesupportsafebuffer-to-string
+        #   body.to_str
+        # else
+        #   read_or_string(body)
+        # end
+      end
+
+      def handle_rack_body_proxy body
+        next_body = body.instance_variable_get(:@body)
+        case next_body
+        when Array
+          extract_body(next_body[0])
+        else
+          extract_body(next_body)
+        end
+      end
+
+      def read_or_string obj
+        return unless obj
+
+        if Contrast::Utils::DuckUtils.quacks_to?(obj, :read)
+          tmp = obj.read
+          obj.rewind
+          tmp
+        else
+          obj.to_s
+        end
+      end
+    end
+  end
+end

data/lib/contrast/utils/substitution_utils.rb

@@ -0,0 +1,167 @@
+# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+module Contrast
+  module Utils
+    # used in Contrast::Agent::Assesss::Policy::Propagator::Substitution
+    module SubstitutionUtils
+      CAPTURE_GROUP_REGEXP = /\\[[:digit:]]/.cs__freeze
+      CAPTURE_NAME_REGEXP = /\\k<[[:alpha:]]/.cs__freeze
+
+      private
+
+      def substitution_tagger patcher, preshift, ret, block, global = true
+        return ret unless ret
+
+        begin
+          source = preshift.object
+          self_tracked = Contrast::Agent::Assess::Tracker.tracked?(source)
+          args = preshift.args[1]
+          incoming_tracked = args && determine_tracked(args)
+          return ret unless self_tracked || incoming_tracked
+
+          parent_events = []
+          if block
+            block_sub(self_tracked, source, ret)
+          elsif args.is_a?(String)
+            string_sub(parent_events, self_tracked, preshift, ret, args, incoming_tracked, global)
+          elsif args.is_a?(Hash)
+            hash_sub(self_tracked, source, ret)
+          else # Enumerator, only for gsub
+            pattern_gsub(parent_events, preshift, ret)
+          end
+
+          self_tracked_handle self_tracked, source, parent_events
+          string_build_event(parent_events, patcher, preshift, ret)
+        rescue StandardError => e
+          logger.error('Unable to apply gsub propagator', e)
+        end
+        ret
+      end
+
+      def self_tracked_handle self_tracked, source, parent_events
+        return unless self_tracked
+
+        source_properties = Contrast::Agent::Assess::Tracker.properties(source)
+        parent_event = source_properties&.event
+        parent_events.prepend(parent_event) if parent_event
+      end
+
+      def determine_tracked args
+        # if there's no arg, it can't be tracked
+        return false unless args
+
+        # if it's a string, just ask if it's tracked
+        case args
+        when String
+          Contrast::Agent::Assess::Tracker.tracked?(args)
+          # if it's a hash, ask if it has a tracked string
+        when Hash
+          args.values.any? { |value| value.is_a?(String) && Contrast::Agent::Assess::Tracker.tracked?(value) }
+          # this should never happen
+        else
+          false
+        end
+      end
+
+      def string_sub parent_events, self_tracked, preshift, ret, incoming, incoming_tracked, global
+        return unless (properties = Contrast::Agent::Assess::Tracker.properties!(ret))
+
+        incoming_properties = Contrast::Agent::Assess::Tracker.properties(incoming)
+        parent_events << incoming_properties&.event if incoming_properties&.event
+
+        source = preshift.object
+
+        # We can't efficiently find the places that things were
+        # copied from regexp / captures. Trading accuracy for
+        # performance
+        if incoming.match?(CAPTURE_GROUP_REGEXP) || incoming.match?(CAPTURE_NAME_REGEXP)
+          properties.splat_from(source, ret) if self_tracked
+          return
+        end
+
+        # if it's just a straight insert, that we can do
+        # Copy the tags from us to the return
+        ranges = find_string_sub_insert(properties, preshift, incoming, ret, global)
+
+        properties.delete_tags_at_ranges(ranges)
+        properties.shift_tags(ranges)
+        return unless incoming_tracked
+        return unless incoming_properties
+
+        tags = incoming_properties.tag_keys
+        ranges.each do |range|
+          tags.each do |tag|
+            properties.add_tag(tag, range)
+          end
+        end
+      end
+
+      # Find the points at which the new String was placed into the original
+      #
+      # @param properties [Contrast::Agent::Assess::Properties] the Properties of the ret
+      # @param preshift [Contrast::Agent::Assess::PreShift] the capture of the state of the code just prior to
+      #   the invocation of the patched method
+      # @param incoming [String] the new String going into the substitution
+      # @param ret [String] the result of the substitution
+      # @param global [Boolean] if this was a global or single substitution
+      # @return [Array<Range>] the Ranges where substitution occurred
+      def find_string_sub_insert properties, preshift, incoming, ret, global
+        pattern = preshift.args[0]
+        source = preshift.object
+
+        properties.copy_from(source, ret)
+        # Figure out where inserts occurred
+        last_idx = 0
+        ranges = []
+        # For each insert, move the tag ranges
+        while last_idx
+          idx = source.index(pattern, last_idx)
+          break unless idx
+
+          last_idx = idx ? idx + 1 : nil
+          start_index = idx
+          end_index = idx + incoming.length
+          ranges << (start_index...end_index)
+          break unless global
+        end
+        ranges
+      end
+
+      def block_sub self_tracked, source, ret
+        return unless self_tracked
+
+        properties = Contrast::Agent::Assess::Tracker.properties!(ret)
+        properties&.splat_from(source, ret)
+      end
+
+      def hash_sub self_tracked, source, ret
+        return unless self_tracked
+
+        properties = Contrast::Agent::Assess::Tracker.properties!(ret)
+        properties&.splat_from(source, ret)
+      end
+
+      def pattern_gsub parent_events, preshift, ret
+        source = preshift.object
+        return unless (source_properties = Contrast::Agent::Assess::Tracker.properties(source))
+        return unless (properties = Contrast::Agent::Assess::Tracker.properties!(ret))
+
+        source_properties.tag_keys.each do |key|
+          properties.add_tag(key, 0...1)
+        end
+        parent_event = source_properties.event
+        parent_events << parent_event if parent_event
+      end
+
+      def string_build_event parent_events, patcher, preshift, ret
+        return unless Contrast::Agent::Assess::Tracker.tracked?(ret)
+
+        properties = Contrast::Agent::Assess::Tracker.properties(ret)
+        args = preshift.args
+        properties.build_event(patcher, ret, preshift.object, ret, args, 2)
+        properties.event.instance_variable_set(:@_parent_events, parent_events)
+      end
+    end
+  end
+end

data/lib/contrast/utils/tag_util.rb

@@ -56,20 +56,20 @@ module Contrast
         # Any overlapping ranges are merged before returning
         #
         # arr: the array of tags to which we are adding
-        # new_arr: misnomer. either an array of or a single Tag to be added
-        def ordered_merge arr, new_arr
+        # add_arr:  array of Tags or a single Tag to be added
+        def ordered_merge arr, add_arr
           # [Contrast::Agent::Assess::Tag, ...]
-          if new_arr.is_a?(Array)
-            return arr unless new_arr.any?
-            return new_arr unless arr&.any?
+          if add_arr.is_a?(Array)
+            return arr unless add_arr.any?
+            return add_arr unless arr&.any?
 
-            new_arr.each { |new_element| single_ordered_merge(arr, new_element) }
+            add_arr.each { |new_element| single_ordered_merge(arr, new_element) }
           # Contrast::Agent::Assess::Tag
           else
-            return arr unless new_arr
-            return [new_arr] unless arr
+            return arr unless add_arr
+            return [add_arr] unless arr
 
-            single_ordered_merge(arr, new_arr)
+            single_ordered_merge(arr, add_arr)
           end
           smallerize(arr)
         end