contrast-agent 3.8.4

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

@@ -0,0 +1,198 @@
+# Copyright (c) 2020 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+module Contrast
+  module Agent
+    module Assess
+      module Policy
+        # This class functions to translate our policy.json into an actionable
+        # Ruby object, allowing for dynamic patching over hardcoded patching,
+        # specifically for those methods which result in the trigger of a
+        # vulnerability (indicate points in the application where uncontrolled
+        # user input can do damage).
+        class TriggerNode < PolicyNode
+          JSON_BAD_VALUE = 'bad_value'
+          JSON_GOOD_VALUE = 'good_value'
+          JSON_DISALLOWED_TAGS = 'disallowed_tags'
+          JSON_REQUIRED_TAGS = 'required_tags'
+          JSON_NODES = 'nodes'
+          JSON_RULE_NAME = 'name'
+          JSON_CUSTOM_PATCH = 'custom_patch'
+
+          attr_reader :rule_id
+          attr_accessor :required_tags, :disallowed_tags, :good_value, :bad_value
+
+          def initialize trigger_hash = {}, rule_hash = {}
+            super(trigger_hash)
+            good_value = trigger_hash[JSON_GOOD_VALUE]
+            bad_value = trigger_hash[JSON_BAD_VALUE]
+            @good_value = Regexp.new(good_value, true) if good_value
+            @bad_value = Regexp.new(bad_value, true) if bad_value
+            @regexp = !@dataflow && (@good_value || @bad_value)
+            @custom_patch = trigger_hash.fetch(JSON_CUSTOM_PATCH, false)
+            @rule_id = rule_hash.fetch(JSON_RULE_NAME) # raises KeyError exception if not found
+            @dataflow = rule_hash.fetch(JSON_DATAFLOW, true)
+            @required_tags = populate_tags(rule_hash[JSON_REQUIRED_TAGS])
+            @disallowed_tags = populate_disallowed(rule_hash[JSON_DISALLOWED_TAGS])
+            @trigger_class = trigger_hash['trigger_class']
+            @trigger_method = trigger_hash['trigger_method']
+            @trigger_method = @trigger_method.to_sym if @trigger_method
+            validate
+          end
+
+          TRIGGER = 'Trigger'
+          def node_class
+            TRIGGER
+          end
+
+          def apply_custom_trigger context, trigger_node, source, object, ret, invoked, *args
+            custom_trigger_class.send(@trigger_method, context, trigger_node, source, object, ret, invoked, *args)
+          end
+
+          def custom_trigger_class
+            @_custom_trigger_class ||= Object.cs__const_get(@trigger_class)
+          end
+
+          def custom_trigger?
+            @trigger_class && @trigger_method
+          end
+
+          def custom_patch?
+            @custom_patch
+          end
+
+          def node_type
+            :TYPE_METHOD
+          end
+
+          def rule_disabled?
+            Contrast::Agent::FeatureState.instance.assess_disabled_rules.include?(rule_id)
+          end
+
+          # Indicate if this is a dataflow based trigger, meaning it has a proper
+          # synch that requires a tainted source to reach it. If this returns
+          # false, this rule is for method validation, ensuring that an insecure
+          # method, such as a non-cryptographically secure random, is not invoked
+          def dataflow?
+            @dataflow
+          end
+
+          # Indicate if this is a regexp based trigger, meaning it has a proper
+          # synch that requires a source to reach it. While this type of rule
+          # does not require the source to be tainted, it does validate it with
+          # a regular expression to determine if the method is being invoked
+          # safely.
+          def regexp_rule?
+            @regexp
+          end
+
+          # the name of the rule, in capital & underscore format
+          # used to make it match enum things in TeamServer
+          def loud_name
+            @_loud_name ||= rule_id.upcase.gsub(Contrast::Utils::ObjectShare::DASH,
+                                                Contrast::Utils::ObjectShare::UNDERSCORE)
+          end
+
+          # Determine if a dataflow rule violation has occurred
+          def violated? source
+            # if the source isn't tracked, there can't be a violation
+            # this condition may not hold true forever, but for now it's
+            # a nice optimization
+            return false unless source.cs__tracked?
+
+            # find the ranges that violate the rule (untrusted, etc)
+            vulnerable_ranges = find_ranges_by_tag(source.cs__properties, required_tags)
+            # if there aren't any vulnerable ranges, nope out
+            return false if vulnerable_ranges.empty?
+
+            # find the ranges that are exempt from the rule
+            # (validated, sanitized, etc)
+            secure_ranges = find_ranges_by_tag(source.cs__properties, disallowed_tags)
+            # if there are vulnerable ranges and no secure, report
+            return true if secure_ranges.empty?
+
+            # figure out if there are any vulnerable ranges that aren't
+            # covered by a secure one. if there are, the rule was violated
+            !Contrast::Utils::TagUtil.covered?(vulnerable_ranges, secure_ranges)
+          end
+
+          # Standard validation + TS trace version two rules:
+          # Must have source
+          def validate
+            super
+            # If this isn't a dataflow rule, it can't have a source
+            return unless dataflow?
+            raise(ArgumentError, "Trigger #{ id } did not have a proper source. Unable to create.") unless sources&.any?
+          end
+
+          private
+
+          # By default, any rule will be triggered if the source
+          # of the rule event has an untrusted tag range that is
+          # not covered by one of its disallowed tags.
+          UNTRUSTED = 'UNTRUSTED'
+          def populate_tags required_tags
+            return unless dataflow?
+
+            validate_rule_tags(required_tags)
+            @required_tags = required_tags || []
+            @required_tags << UNTRUSTED
+          end
+
+          ENCODER_START = 'CUSTOM_ENCODED_'
+          VALIDATOR_START = 'CUSTOM_VALIDATED_'
+          # If a level 1 rule comes from TeamServer, it will have the
+          # tag 'custom-encoder-#{ name }' or 'custom-validator-#{ name }'.
+          # All rules should take this into account.
+          # Additionally, if something is marked 'limited-chars' it means
+          # it has been properly vetted to not contain dangerous input.
+          LIMITED_CHARS = 'LIMITED_CHARS'
+          CUSTOM_ENCODED = 'CUSTOM_ENCODED'
+          CUSTOM_VALIDATED = 'CUSTOM_VALIDATED'
+          def populate_disallowed disallowed_tags
+            return unless dataflow?
+
+            validate_rule_tags(disallowed_tags)
+            @disallowed_tags = disallowed_tags || []
+            @disallowed_tags << LIMITED_CHARS
+            @disallowed_tags << CUSTOM_ENCODED
+            @disallowed_tags << CUSTOM_VALIDATED
+            @disallowed_tags << ENCODER_START + loud_name
+            @disallowed_tags << VALIDATOR_START + loud_name
+          end
+
+          ENCODED_MARKER = '_ENCODED'
+          def validate_rule_tags tags
+            return unless tags
+
+            tags.each do |tag|
+              raise(ArgumentError, "Rule #{ rule_id } had an invalid tag. #{ tag } is not a known value.") unless
+                  Contrast::Agent::Assess::Policy::PolicyNode::VALID_TAGS.include?(tag) ||
+                      Contrast::Agent::Assess::Policy::PolicyNode::VALID_SOURCE_TAGS.include?(tag)
+            end
+          end
+
+          def find_ranges_by_tag cs__properties, tags
+            ranges = []
+
+            # if there aren't any all_tags or tags, break early
+            return ranges unless cs__properties.tracked?
+            return ranges unless tags&.any?
+
+            # find all tags that match the desired ones
+            tags.each do |desired|
+              found = cs__properties.fetch_tag(desired)
+              next unless found
+
+              # we need to dup here so that we don't change the tags if target is
+              # used in another trace
+              ranges = Contrast::Utils::TagUtil.ordered_merge(ranges, found.dup)
+            end
+
+            ranges
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+# Copyright (c) 2020 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+module Contrast
+  module Agent
+    module Assess
+      module Policy
+        module TriggerValidation
+          # Validator used to assert a SSRF finding is actually vulnerable
+          # before serializing that finding as a DTM to report to the service.
+          module SSRFValidator
+            SSRF_RULE = 'ssrf'
+            URL_PATTERN =
+              %r{(?<protocol>http|https|ftp|sftp|telnet|gopher|rtsp|rtsps|ssh|svn)://(?<host>[^/?]+)(?<path>/?[^?]*)(?<query_string>\?.*)?}i.cs__freeze
+            # The Net::HTTP class validates host format on instantiation. Since
+            # our triggers for that class are on the instance, they already
+            # have this validation done for them. We do not need to apply the
+            # validation in this case.
+            PATH_ONLY_PATCH_MARKER = 'Assess:Trigger:Net::HTTP#'
+
+            # A finding is valid for SSRF if the source of the trigger event is
+            # a valid URL in which the User controls a section prior to the
+            # querystring
+            # https://bitbucket.org/contrastsecurity/assess-specifications/src/master/rules/dataflow/server_side_request_forgery.md
+            def self.valid? patcher, _object, _ret, args
+              return true unless SSRF_RULE == patcher&.rule_id
+              return true if patcher.id.to_s.start_with?(PATH_ONLY_PATCH_MARKER)
+
+              url = args[0].to_s
+              match = url.match(URL_PATTERN)
+              return false unless match
+
+              # It is dangerous for the user to control a section of the URL
+              # between the start of the protocol and the beginning of the
+              # querystring. If there is no querystring, then the entire URL is
+              # dangerous for the User to control.
+              start = match.begin(:protocol)
+              finish = match.begin(:query_string)
+              finish ||= url.length
+
+              args[0].cs__properties.any_tags_between?(start, finish)
+            end
+
+            # Some SSRF triggers take multiple parameters to build the URL.
+            # For the net_http_# sources, if the first parameter is a String,
+            # the URL is built by appending the first and second parameters.
+            def self.composite? patcher, args
+              id = patcher.id.to_s
+              return false unless id.start_with?(PATH_ONLY_PATCH_MARKER)
+
+              args[0].is_a?(String)
+            end
+
+            def self.build_single_source args
+              return nil unless args[0].cs__respond_to?(:cs__properties)
+
+              args[0].to_s
+            end
+
+            def self.build_composite_source args
+              if args.length > 1
+                return nil unless args[0].cs__respond_to?(:cs__properties) ||
+                    args[1].cs__respond_to?(:cs__properties)
+
+                args[0] + args[1]
+              else
+                return nil unless args[0].cs__respond_to?(:cs__properties)
+
+                args[0].to_s
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# Copyright (c) 2020 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+cs__scoped_require 'contrast/agent/assess/policy/trigger_validation/ssrf_validator'
+cs__scoped_require 'contrast/agent/assess/policy/trigger_validation/xss_validator'
+
+module Contrast
+  module Agent
+    module Assess
+      module Policy
+        # Some of our triggers require transformation or validation prior to
+        # reporting in order to account for false positives or other aberrant
+        # conditions. This provides a single place from which those validations
+        # can be called.
+        module TriggerValidation
+          VALIDATORS = [
+            Contrast::Agent::Assess::Policy::TriggerValidation::SSRFValidator,
+            Contrast::Agent::Assess::Policy::TriggerValidation::XSSValidator
+          ].cs__freeze
+
+          def self.valid? patcher, object, ret, args
+            VALIDATORS.each do |validator|
+              return false unless validator.valid?(patcher, object, ret, args)
+            end
+            true
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# Copyright (c) 2020 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+module Contrast
+  module Agent
+    module Assess
+      module Policy
+        module TriggerValidation
+          # Validator used to assert a Reflected XSS finding is actually
+          # vulnerable before serializing that finding as a DTM to report to
+          # the service.
+          module XSSValidator
+            XSS_RULE = 'reflected-xss'
+            SAFE_CONTENT_TYPES = %w[
+              /csv
+              /javascript
+              /json
+              /pdf
+              /x-javascript
+              /x-json
+            ].cs__freeze
+
+            # A finding is valid for XSS if the response type is not one of
+            # those assumed to be safe
+            # https://bitbucket.org/contrastsecurity/assess-specifications/src/master/rules/dataflow/reflected_xss.md
+            def self.valid? patcher, _object, _ret, _args
+              return true unless XSS_RULE == patcher&.rule_id
+
+              content_type = Contrast::Agent::REQUEST_TRACKER.current&.response&.content_type
+              return true unless content_type
+
+              content_type = content_type.downcase
+              SAFE_CONTENT_TYPES.none? { |safe_type| content_type.index(safe_type) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,392 @@
+# Copyright (c) 2020 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+cs__scoped_require 'set'
+cs__scoped_require 'base64'
+cs__scoped_require 'contrast/utils/prevent_serialization'
+cs__scoped_require 'contrast/utils/tag_util'
+cs__scoped_require 'contrast/agent/assess/contrast_event'
+
+module Contrast
+  module Agent
+    module Assess
+      # Properties associated with a tracked String. If String is monkey
+      # patched this object is lazily generated on affected Strings.
+      #
+      # This class acts as a holder for the Assess information we need in order
+      # to properly convey the events that lead up to the state of the tracked
+      # user input.
+      class Properties
+        include Contrast::Utils::PreventSerialization
+
+        # CONTRAST-36937
+        # Creating these on Properties is expensive. We want to delay this for
+        # as long as possible.
+        def properties
+          @_properties ||= {}
+        end
+
+        def events
+          @_events ||= []
+        end
+
+        def tracked?
+          tags? && tags.any?
+        end
+
+        def tagged? label
+          tags? && tags.key?(label)
+        end
+
+        def add_properties hash
+          return unless hash
+
+          properties.merge!(hash)
+        end
+
+        def add_property name, value
+          return unless name && value
+
+          properties[name] = value
+        end
+
+        def any_tags_between? start, finish
+          return false unless tags?
+
+          range = Contrast::Agent::Assess::Tag.new(start + finish, start)
+          tags.each_value do |tag_array|
+            return true if tag_array.any? { |tag| tag.overlaps?(range) }
+          end
+          false
+        end
+
+        # Find all of the ranges that span a given index. This is used
+        # in propagation when we need to shift tags about. For instance, in
+        # the append method when we need to see if any tag at the end needs
+        # to be expanded out to the size of the new String.
+        #
+        # Note: Tags do not know their key, so this is only the range covered
+        def tags_at idx
+          return Contrast::Utils::ObjectShare::EMPTY_ARRAY unless tags?
+
+          at = []
+          tags.each_value do |tag_array|
+            tag_array.each do |tag|
+              if tag.covers?(idx)
+                at << tag
+              elsif tag.above?(idx)
+                break
+              end
+            end
+          end
+          at
+        end
+
+        # given a range, select all tags in that range the selected tags are
+        # shifted such that the start index of the new tag (0) aligns with the
+        # given start index in the range
+        #
+        # current tags: 5-15
+        # range       : 5-10
+        # result      : 0-05
+        def tags_at_range range
+          return Contrast::Utils::ObjectShare::EMPTY_HASH unless tags?
+
+          at = Hash.new { |h, k| h[k] = [] }
+          length = range.stop - range.start
+          tags.each_pair do |key, value|
+            add = []
+            value.each do |tag|
+              comparison = tag.compare_range(range.start, range.stop)
+              # BELOW and ABOVE are applicable to this check and are removed.
+              case comparison
+              # part of the tag is being selected
+              when Contrast::Agent::Assess::Tag::LOW_SPAN
+                add << Contrast::Agent::Assess::Tag.new(length)
+              # the tag exists in the requested range, figure out the boundaries
+              when Contrast::Agent::Assess::Tag::WITHIN
+                start = tag.start_idx - range.start
+                finish = length - start
+                add << Contrast::Agent::Assess::Tag.new(finish, start)
+              # the tag spans the requested range.
+              when Contrast::Agent::Assess::Tag::WITHOUT
+                add << Contrast::Agent::Assess::Tag.new(length)
+              # part of the tag is being selected
+              when Contrast::Agent::Assess::Tag::HIGH_SPAN
+                add << Contrast::Agent::Assess::Tag.new(length)
+              end
+            end
+            next if add.empty?
+
+            at[key] = add
+          end
+          at
+        end
+
+        # Given a tag name and range object, add a new tag to this
+        # collection. If the given range touches an existing tag,
+        # we'll combine the two, adjusting the existing one and
+        # dropping this new one.
+        def add_tag label, range
+          length = range.stop - range.start
+          tag = Contrast::Agent::Assess::Tag.new(length, range.start)
+          existing = fetch_tag(label)
+          tags[label] = Contrast::Utils::TagUtil.ordered_merge(existing, tag)
+        end
+
+        def set_tags label, tag_ranges
+          tags[label] = tag_ranges
+        end
+
+        # Remove all tags with a given label
+        def delete_tags label
+          return unless tags?
+
+          tags.delete(label)
+        end
+
+        # Reset the tag hash
+        def clear_tags
+          return unless tags?
+
+          tags.clear
+        end
+
+        # Returns a list of all current tag labels, most likely to be used for
+        # a splat operation
+        def tag_keys
+          return Contrast::Utils::ObjectShare::EMPTY_ARRAY unless tags?
+
+          tags.keys
+        end
+
+        # Calls merge to combine touching or overlapping tags
+        # Deletes empty tags
+        def cleanup_tags
+          return unless tags?
+
+          Contrast::Utils::TagUtil.merge_tags(tags)
+          tags.delete_if { |_, value| value.empty? }
+        end
+
+        # We'll use this as a helper method to retrieve tags from the hash.
+        # Because the hash auto-populates an empty array when we try to access
+        # a tag in it, we cannot use the [] method without side effect. To get
+        # around this, we'll use a fetch work around.
+        def fetch_tag label
+          return unless tags?
+
+          tags.fetch(label, nil)
+        end
+
+        # Convert the tags of this object into the TraceTaintRange requried to
+        # be sent to the service
+        def tags_to_dtm
+          return Contrast::Utils::ObjectShare::EMPTY_ARRAY unless tags?
+
+          ranges = []
+          tags.each_pair do |key, value|
+            next if value.empty?
+
+            value.each do |tag|
+              range = Contrast::Api::Dtm::TraceTaintRange.new
+              range.tag = Contrast::Utils::StringUtils.protobuf_safe_string(key)
+              range.range = tag.start_idx.to_s + Contrast::Utils::ObjectShare::COLON + tag.end_idx.to_s
+              ranges << range
+            end
+          end
+          ranges
+        end
+
+        # Remove all tags within the given ranges.
+        # This does not delete an entire tag if part of that tag is
+        # outside this range, meaning we may reduce sizes of tags
+        # or split them.
+        #
+        # If shift is true, it is assumed the characters at those ranges were
+        # removed. If shift is false, it is assumed those ranges were replaced
+        # by the same number of characters and no shift is needed.
+        #
+        # current tags: 0-15
+        # range:        5-10
+        # result:       0-5, 10-15
+        def delete_tags_at_ranges ranges, shift = true
+          return unless tags?
+
+          # Stage one - delete the tags w/o changing their
+          # location.
+          ranges.each do |range|
+            remove_tags(range)
+          end
+
+          return unless shift
+
+          # the amount we've already removed from the string
+          shift = 0
+          # Stage two - shift the tags to the left to account
+          # for the sections that were deleted.
+          ranges.each do |range|
+            shift_tags_for_deletion(range, shift)
+            shift += (range.stop - range.start)
+          end
+
+          # Clean up and merge any touching tags
+          Contrast::Utils::TagUtil.merge_tags(tags)
+        end
+
+        # Shift all the tags in this object by the given ranges.
+        # This method assumes the ranges are sorted, meaning
+        # the leftmost (lowest) range is first
+        #
+        # current tags: 0-15
+        # range:        5-10
+        # result:       0-5, 10-20
+        def shift_tags ranges
+          return unless tags?
+
+          ranges.each do |range|
+            shift_tags_for_insertion(range)
+          end
+        end
+
+        # Add an event to these properties. It will be used to build
+        # a trace if this object ends up in a trigger.
+        def add_event event
+          events << event
+          self
+        end
+
+        def build_event policy_node, tagged, object, ret, args, invoked = 0, source_type = nil, source_name = nil
+          event = Contrast::Agent::Assess::ContrastEvent.new(policy_node, tagged, object, ret, args, invoked, source_type, source_name)
+          add_event(event)
+          report_sources(tagged, event)
+        end
+
+        private
+
+        def report_sources tagged, event
+          return unless tagged && !tagged.to_s.empty?
+          return unless event&.source_type
+
+          current_request = Contrast::Agent::REQUEST_TRACKER.current
+          return unless current_request
+          return if current_request.observed_route.sources.any? { |source| source.type == event.forced_source_type && source.name == event.forced_source_name }
+
+          event_source_dtm = event.build_event_source_dtm
+          return unless event_source_dtm
+
+          current_request.observed_route.sources << event_source_dtm
+        end
+
+        # Because of the auto-fill thing, we should not allow direct access to
+        # the tags hash. Instead, the methods above should be used to do
+        # operations like add, delete, and fetch.
+        #
+        # CONTRAST-22914
+        # please do NOT expose this w/ an attr_reader / accessor. there are
+        # helper methods in this class that safely access the hash. the tags
+        # method is private to avoid the side effect of a direct lookup with
+        # `[]` adding an empty array to the hash.
+        def tags
+          @_tags ||= Hash.new { |h, k| h[k] = [] }
+        end
+
+        # Creating Tags is expensive and we check for Tags all the time on
+        # untracked things. ALWAYS!!! call this method before checking if
+        # an object has tags
+        def tags?
+          instance_variable_defined?(:@_tags)
+        end
+
+        # Remove the tag ranges covering the given range
+        def remove_tags range
+          return unless tags?
+
+          full_delete = []
+          tags.each_pair do |key, value|
+            remove = []
+            add = []
+            value.each do |tag|
+              comparison = tag.compare_range(range.start, range.stop)
+              # ABOVE and BELOW are not affected by this check
+              case comparison
+              when Contrast::Agent::Assess::Tag::LOW_SPAN
+                tag.update_end(range.start)
+              when Contrast::Agent::Assess::Tag::WITHIN
+                remove << tag
+              when Contrast::Agent::Assess::Tag::WITHOUT
+                new_tag = tag.clone
+                new_tag.update_start(range.stop)
+                add << new_tag
+                tag.update_end(range.start)
+              when Contrast::Agent::Assess::Tag::HIGH_SPAN
+                tag.update_start(range.stop)
+              end
+            end
+            value.delete_if { |tag| remove.include?(tag) }
+            Contrast::Utils::TagUtil.ordered_merge(value, add)
+            full_delete << key if value.empty?
+          end
+          full_delete.each { |key| tags.delete(key) }
+        end
+
+        # Shift the tag ranges covering the given range
+        # We assume this is for a deletion, meaning we
+        # have to move tags to the left
+        def shift_tags_for_deletion range, shift
+          return unless tags?
+
+          tags.each_value do |value|
+            value.each do |tag|
+              comparison = tag.compare_range(range.start - shift, range.stop - shift)
+              length = range.stop - range.start
+              case comparison
+              # this is really the only thing we need to shift
+              when Contrast::Agent::Assess::Tag::ABOVE
+                tag.shift(0 - length)
+              end
+            end
+          end
+        end
+
+        # Shift the tag ranges covering the given range
+        # We assume this is for a insertion, meaning we
+        # have to move tags to the right
+        def shift_tags_for_insertion range
+          return unless tags?
+
+          tags.each_value do |value|
+            add = []
+            value.each do |tag|
+              comparison = tag.compare_range(range.start, range.stop)
+              length = range.stop - range.start
+              # BELOW is not affected by this check
+              case comparison
+              # part of the tag is being inserted on
+              when Contrast::Agent::Assess::Tag::LOW_SPAN
+                new_tag = tag.clone
+                new_tag.update_start(range.start)
+                new_tag.shift(length)
+                add << new_tag
+                tag.update_end(range.start)
+              # the tag exists in the inserted range. it is partially shifted
+              when Contrast::Agent::Assess::Tag::WITHIN
+                tag.shift(length)
+              # the tag spans the range. leave the part below alone
+              when Contrast::Agent::Assess::Tag::WITHOUT
+                new_tag = tag.clone
+                new_tag.update_start(range.start)
+                new_tag.shift(length)
+                add << new_tag
+                tag.update_end(range.start)
+              when Contrast::Agent::Assess::Tag::HIGH_SPAN, Contrast::Agent::Assess::Tag::ABOVE
+                tag.shift(length)
+              end
+            end
+            Contrast::Utils::TagUtil.ordered_merge(value, add)
+          end
+        end
+      end
+    end
+  end
+end