contrast-agent 3.8.4

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

@@ -0,0 +1,44 @@
+# 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/utils/object_share'
+cs__scoped_require 'contrast/components/interface'
+cs__scoped_require 'contrast/core_extensions/assess/assess_extension'
+
+module Contrast
+  module Agent
+    module Assess
+      module Policy
+        # This is how we scan our customer's code. It provides a way to analyze
+        # the classes we need to observe to find vulnerabilities in the context
+        # of a file vs data flow, such as the detection of Hardcoded Passwords
+        # or Keys.
+        module PolicyScanner
+          include Contrast::Components::Interface
+          access_component :analysis, :logging
+
+          class << self
+            def scan trace_point
+              return unless ASSESS.enabled?
+              return unless ASSESS.require_scan?
+
+              return unless trace_point.path
+              return if trace_point.path.start_with?(Gem.dir)
+
+              mod = trace_point.self
+              return if mod.cs__frozen? || mod.singleton_class?
+
+              policy.providers.each_value do |provider|
+                provider.analyze mod
+              end
+            end
+
+            def policy
+              Contrast::Agent::Assess::Policy::Policy.instance
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,94 @@
+# 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/components/interface'
+
+module Contrast
+  module Agent
+    module Assess
+      # In order to properly shift tags to account for the changes this method
+      # caused, we'll need to store the state before the change occurred.
+      class PreShift
+        include Contrast::Components::Interface
+        access_component :analysis, :logging
+
+        UNDUPLICABLE_MODULES = [
+          Enumerator # dup'ing results in 'can't copy execution context'
+        ].cs__freeze
+
+        attr_accessor :object, :object_length, :args, :arg_lengths
+
+        class << self
+          # Save the state before we do the propagation. This is one of the
+          # few things that we'll call BEFORE calling the original method.
+          # Unfortunately, we may waste some time here if the method then
+          # throws an exception, but hey, it threw an exception. These few
+          # extra objects aren't the real problem in that case.
+          #
+          # @param propagation_node [Contrast::Agent::Assess::Policy::PropagationNode]
+          #   The node responsible for the propagation action required by this
+          #   method.
+          # @param object [Object] the object on which the method is to be
+          #   called.
+          # @param args [Array<Object>] the arguments to be passed to the
+          #   method.
+          # @return [Contrast::Agent::Assess::PreShift, nil] a holder saving
+          #   the state of the object and arguments just prior to the method
+          #   being called or nil if one is not required.
+          def build_preshift propagation_node, object, args
+            return nil unless propagation_node
+            return nil unless ASSESS.enabled?
+
+            initializing = propagation_node.method_name == :initialize
+            return nil if unsafe_io_object?(object, initializing)
+
+            needs_object = propagation_node.needs_object?
+            needs_args = propagation_node.needs_args?
+
+            preshift = Contrast::Agent::Assess::PreShift.new
+            append_object_details(preshift, initializing, object) if needs_object
+            append_arg_details(preshift, args) if needs_args
+
+            preshift
+          rescue StandardError => e
+            logger.error(e, 'Unable to build preshift for method.')
+            nil
+          end
+
+          private
+
+          def unsafe_io_object? object, initializing
+            Contrast::Utils::DuckUtils.quacks_like_closable_io(object) && !initializing && object.closed?
+          end
+
+          def can_dup? initializing, object
+            return false if initializing
+
+            check = object.is_a?(Module) ? object : object.cs__class
+            !UNDUPLICABLE_MODULES.include?(check)
+          end
+
+          def append_object_details preshift, initializing, object
+            preshift.object = can_dup?(initializing, object) ? object.dup : object
+            preshift.object.cs__copy_from(object) if object.cs__frozen? && Contrast::Utils::DuckUtils.quacks_to?(preshift.object, :cs__copy_from)
+            preshift.object_length = if Contrast::Utils::DuckUtils.quacks_to?(preshift.object, :length)
+                                       object.length
+                                     else
+                                       0
+                                     end
+          end
+
+          def append_arg_details preshift, args
+            preshift.args = args.dup
+            preshift.args.each_with_index do |arg, index|
+              next unless args[index].cs__frozen? && Contrast::Utils::DuckUtils.quacks_to?(arg, :cs__copy_from)
+
+              arg.cs__copy_from(args[index])
+            end
+            preshift.arg_lengths = preshift.args.map { |arg| Contrast::Utils::DuckUtils.quacks_to?(arg, :length) ? arg.length : 0 }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,260 @@
+# Copyright (c) 2020 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+# 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
+cs__scoped_require 'set'
+
+cs__scoped_require 'contrast/utils/object_share'
+cs__scoped_require 'contrast/utils/sha256_builder'
+
+cs__scoped_require 'contrast/agent/assess/policy/propagator'
+
+cs__scoped_require 'contrast/components/interface'
+
+module Contrast
+  module Agent
+    module Assess
+      module Policy
+        # This module contains the logic for determining how to propagate tags
+        # and events from a source to a target
+        module PropagationMethod
+          include Contrast::Components::Interface
+          access_component :logging
+
+          APPEND_ACTION = 'APPEND'
+          CENTER_ACTION = 'CENTER'
+          INSERT_ACTION = 'INSERT'
+          KEEP_ACTION = 'KEEP'
+          NEXT_ACTION = 'NEXT'
+          PREPEND_ACTION = 'PREPEND'
+          REPLACE_ACTION = 'REPLACE'
+          REMOVE_ACTION = 'REMOVE'
+          REVERSE_ACTION = 'REVERSE'
+          SPLAT_ACTION = 'SPLAT'
+          SPLIT_ACTION = 'SPLIT'
+          TAG_ACTION = 'TAG'
+          DB_WRITE_ACTION = 'DB_WRITE'
+          CUSTOM_ACTION = 'CUSTOM'
+
+          class << self
+            def determine_target propagation_node, ret, object, args
+              target_key = propagation_node.targets[0]
+              return ret if target_key == Contrast::Utils::ObjectShare::RETURN_KEY
+              return object if target_key == Contrast::Utils::ObjectShare::OBJECT_KEY
+
+              return args[target_key] if target_key.is_a?(Integer)
+
+              arg = nil
+              args.each do |search|
+                next unless search.is_a?(Hash)
+
+                arg = search[target_key]
+                break if arg
+              end
+              arg
+            end
+
+            def apply_propagation method_policy, preshift, object, ret, args, block
+              return unless method_policy.propagation_node
+              return unless preshift
+
+              propagation_node = method_policy.propagation_node
+
+              target = determine_target(propagation_node, ret, object, args)
+              PropagationMethod.apply_propagator(propagation_node, preshift, target, object, ret, 0, args, block)
+            end
+
+            PROPAGATION_ACTIONS = {
+                APPEND_ACTION => Contrast::Agent::Assess::Policy::Propagator::Append,
+                CENTER_ACTION => Contrast::Agent::Assess::Policy::Propagator::Center,
+                INSERT_ACTION => Contrast::Agent::Assess::Policy::Propagator::Insert,
+                KEEP_ACTION => Contrast::Agent::Assess::Policy::Propagator::Keep,
+                NEXT_ACTION => Contrast::Agent::Assess::Policy::Propagator::Next,
+                PREPEND_ACTION => Contrast::Agent::Assess::Policy::Propagator::Prepend,
+                REPLACE_ACTION => Contrast::Agent::Assess::Policy::Propagator::Replace,
+                REMOVE_ACTION => Contrast::Agent::Assess::Policy::Propagator::Remove,
+                REVERSE_ACTION => Contrast::Agent::Assess::Policy::Propagator::Reverse,
+                SPLAT_ACTION => Contrast::Agent::Assess::Policy::Propagator::Splat,
+                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.
+            def apply_propagator propagation_node, preshift, target, object, ret, invoked, args, block
+              context = Contrast::Agent::REQUEST_TRACKER.current
+              return unless context && propagation_node && valid_target?(target, propagation_node)
+              return unless valid_length?(target, propagation_node.action)
+
+              if propagation_node.action == DB_WRITE_ACTION
+                Contrast::Agent::Assess::Policy::Propagator::DatabaseWrite.propagate(propagation_node, preshift, ret)
+              elsif propagation_node.action == CUSTOM_ACTION
+                Contrast::Agent::Assess::Policy::Propagator::Custom.propagate(propagation_node, preshift, ret, block)
+              elsif propagation_node.action == SPLIT_ACTION
+                Contrast::Agent::Assess::Policy::Propagator::Split.propagate(propagation_node, preshift, target)
+                logger.debug(
+                    nil,
+                    "Propagator #{ propagation_node.id } detected: propagated to #{ target.__id__ }")
+              elsif Contrast::Utils::DuckUtils.quacks_to?(target, :cs__properties)
+                handle_cs_properties_propagation(propagation_node, preshift, target, object, ret, invoked, args, block)
+              elsif Contrast::Utils::DuckUtils.quacks_like_tracked_hash?(target)
+                handle_hash_propagation(propagation_node, preshift, target, object, ret, invoked, args, block)
+              elsif Contrast::Utils::DuckUtils.quacks_like_tracked_enumerable?(target)
+                handle_enumerable_propagation(propagation_node, preshift, target, object, ret, invoked, args, block)
+              end
+            rescue StandardError => e
+              logger.warn(e, "Unable to apply propagator #{ propagation_node.id }")
+            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.
+            #
+            # In all other cases, a target is valid for propagation if it is not
+            # nil
+            def valid_target? target, propagation_node
+              return true if propagation_node.action == CUSTOM_ACTION
+
+              !!target
+            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
+            def valid_length? target, action
+              return true if ZERO_LENGTH_ACTIONS.include?(action)
+
+              if Contrast::Utils::DuckUtils.quacks_to?(target, :length)
+                target.length != 0 # rubocop:disable Style/ZeroLengthPredicate
+              else
+                !target.to_s.empty?
+              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.
+            def can_propagate? propagation_node, preshift, target
+              # We cannot propagate to things that do not have cs__properties.
+              return false unless Contrast::Utils::DuckUtils.quacks_to?(target, :cs__properties)
+
+              # We cannot propagate to frozen things that have not been
+              # previously tracked. 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.
+              return false if target.cs__properties == Contrast::Agent::Assess::Insulator.generate_frozen.properties &&
+                  propagation_node.targets[0] != Contrast::Utils::ObjectShare::RETURN_KEY
+              return true if Contrast::Utils::Assess::TrackingUtil.tracked?(target)
+              return false unless preshift
+
+              propagation_node.sources.each do |source|
+                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?)
+                  return true if preshift.args && Contrast::Utils::Assess::TrackingUtil.tracked?(preshift.args[source])
+                end
+              end
+              false
+            end
+
+            # If this patcher has tags, apply them to the entire target
+            def apply_tags propagation_node, target
+              return unless propagation_node.tags
+
+              length = Contrast::Utils::StringUtils.ret_length(target)
+              propagation_node.tags.each do |tag|
+                span = Contrast::Agent::Assess::AdjustedSpan.new(0, length)
+                target.cs__properties.add_tag(tag, span)
+              end
+            end
+
+            # If this patcher has tags, remove them from the entire target
+            def apply_untags propagation_node, target
+              return unless propagation_node.untags
+
+              propagation_node.untags.each do |tag|
+                target.cs__properties.delete_tags(tag)
+              end
+            end
+
+            private
+
+            def handle_hash_propagation propagation_node, preshift, target, object, ret, invoked, args, block
+              invoked += 2
+              target.each_pair do |key, value|
+                apply_propagator(propagation_node, preshift, key, object, ret, invoked, args, block)
+                apply_propagator(propagation_node, preshift, value, object, ret, invoked, args, block)
+              end
+            end
+
+            def handle_enumerable_propagation propagation_node, preshift, target, object, ret, invoked, args, block
+              invoked += 2
+              target.each do |value|
+                next if target == value # Some Enumerable#each are overriden to return self the first time which leads to infinite propagation
+
+                apply_propagator(propagation_node, preshift, value, object, ret, invoked, args, block)
+              end
+            end
+
+            def handle_cs_properties_propagation propagation_node, preshift, target, object, ret, invoked, args, _block
+              invoked += 1
+              return unless can_propagate?(propagation_node, preshift, target)
+
+              # propagate all the tags from the sources to the target
+              propagation_class = PROPAGATION_ACTIONS.fetch(propagation_node.action, nil)
+              unless propagation_class
+                logger.warn(
+                    nil,
+                    "Unknown action type #{ propagation_node.action }. Unable to "\
+                    "propagate for #{ propagation_node.id }.")
+                return ret
+              end
+
+              restore_frozen_state = false
+              if target.cs__frozen?
+                return ret unless propagation_node.targets[0] == Contrast::Utils::ObjectShare::RETURN_KEY
+
+                restore_frozen_state = true
+                ret = Contrast::Utils::FreezeUtil.unfreeze_dup(target)
+                target = ret
+              end
+              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.
+              apply_untags(propagation_node, target)
+
+              target.cs__properties.add_properties(propagation_node.properties)
+
+              target.cs__properties.build_event(propagation_node, target, object, ret, args, invoked)
+
+              logger.debug(
+                  nil,
+                  "Propagator #{ propagation_node.id } detected: propagated to "\
+                  "#{ target.__id__ }")
+
+              ret.cs__freeze if restore_frozen_state
+              ret
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,127 @@
+# 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/policy_node'
+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 transformation of
+        # untrusted data (indicate points in the application where user
+        # controlled input is modified).
+        class PropagationNode < PolicyNode
+          JSON_ACTION = 'action'
+          JSON_UNTAGS = 'untags'
+          JSON_PATCH_CLASS = 'patch_class'
+          JSON_PATCH_METHOD = 'patch_method'
+
+          attr_accessor :action, :untags, :patch_class, :patch_method
+
+          # Most things here carry over from PolicyNode.
+          # A couple things are new / have new rules
+          #
+          # Source - from where the tainted data flows, cannot be nil
+          # Target - to where the tainted data flows, cannot be nil
+          # Action - how the tainted data flows from source to target, should not be nil
+          # 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
+          def initialize propagation_hash = {}
+            super(propagation_hash)
+            @action = propagation_hash[JSON_ACTION]
+            @untags = Set.new(propagation_hash[JSON_UNTAGS])
+            @patch_class = propagation_hash[JSON_PATCH_CLASS]
+            @patch_method = propagation_hash[JSON_PATCH_METHOD]
+            @patch_method = @patch_method.to_sym if @patch_method
+            validate
+          end
+
+          TAGGER = 'Tagger'
+          PROPAGATOR = 'Propagator'
+
+          def node_class
+            @_node_class ||= tagger? ? TAGGER : PROPAGATOR
+          end
+
+          # 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
+          def node_type
+            tagger? ? :TYPE_TAG : :TYPE_PROPAGATION
+          end
+
+          # Standard validation + TS trace version two rules:
+          # Must have source, target, and action
+          def validate
+            super
+            raise(ArgumentError, "Propagator #{ id } did not have a proper action. Unable to create.") unless action
+
+            if @action == 'CUSTOM'
+              raise(ArgumentError, "Propagator #{ id } did not have a proper patch_class. Unable to create.") unless patch_class
+              raise(ArgumentError, "Propagator #{ id } did not have a proper patch_method. Unable to create.") unless patch_method.is_a?(Symbol)
+            else
+              raise(ArgumentError, "Propagator #{ id } did not have a proper target. Unable to create.") unless targets&.any?
+              raise(ArgumentError, "Propagator #{ id } did not have a proper source. Unable to create.") unless sources&.any?
+            end
+            validate_untags
+          end
+
+          def validate_untags
+            return unless untags
+
+            untags.each do |tag|
+              raise(ArgumentError, "#{ node_type } #{ id } did not have a valid untag. #{ tag } is not a known value.") unless VALID_TAGS.include?(tag)
+              raise(ArgumentError, "#{ node_type } #{ id } had the same tag and untag, #{ tag }.") if tags&.include?(tag)
+            end
+          end
+
+          def needs_object?
+            @_needs_object ||= begin
+              if action == Contrast::Agent::Assess::Policy::PropagationMethod::CUSTOM_ACTION
+                true
+              elsif action == Contrast::Agent::Assess::Policy::PropagationMethod::DB_WRITE_ACTION
+                true
+              elsif sources.any? { |source| source == Contrast::Utils::ObjectShare::OBJECT_KEY }
+                true
+              elsif targets.any? { |target| target == Contrast::Utils::ObjectShare::OBJECT_KEY }
+                true
+              else
+                false
+              end
+            end
+          end
+
+          def needs_args?
+            @_needs_args ||= begin
+              if action == Contrast::Agent::Assess::Policy::PropagationMethod::CUSTOM_ACTION
+                true
+              elsif action == Contrast::Agent::Assess::Policy::PropagationMethod::DB_WRITE_ACTION
+                true
+              elsif sources.any? { |source| source.is_a?(Integer) || source.is_a?(Symbol) }
+                true
+              elsif targets.any? { |target| target.is_a?(Integer) || target.is_a?(Symbol) }
+                true
+              else
+                false
+              end
+            end
+          end
+
+          # This is a tagger if it has a tag or an untag.
+          # It indicates this method is more than just a transformation,
+          # it is an interesting security event that has a meaningful
+          # change.
+          def tagger?
+            @_tagger ||= begin
+              has_tags = tags&.any?
+              has_untags = untags&.any?
+              has_tags || has_untags
+            end
+          end
+        end
+      end
+    end
+  end
+end