contrast-agent 3.8.4

data/lib/contrast/agent/patching/policy/method_policy.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
+
+module Contrast
+  module Agent
+    module Patching
+      module Policy
+        # This class is used to map each method to the trigger node that applies to it
+        class MethodPolicy
+          attr_accessor :source_node, :propagation_node, :trigger_node,
+                        :inventory_node, :protect_node, :deadzone_node,
+                        :method_name, :method_visibility, :instance_method
+          def initialize(source_node: nil, propagation_node: nil,
+                         trigger_node: nil, inventory_node: nil,
+                         protect_node: nil, deadzone_node: nil,
+                         method_name: nil, method_visibility: nil,
+                         instance_method: nil)
+            @method_name = method_name
+            @method_visibility = method_visibility
+            @instance_method = instance_method
+            @source_node = source_node
+            @propagation_node = propagation_node
+            @trigger_node = trigger_node
+            @inventory_node = inventory_node
+            @protect_node = protect_node
+            @deadzone_node = deadzone_node
+          end
+
+          def private_method?
+            method_visibility == :private
+          end
+
+          def empty?
+            return false if source_node
+            return false if propagation_node
+            return false if trigger_node
+            return false if inventory_node
+            return false if protect_node
+            return false if deadzone_node
+
+            true
+          end
+
+          def requires_custom_patch?
+            !!@trigger_node&.custom_patch?
+          end
+
+          class << self
+            # Given a Contrast::Agent::Patching::Policy::ModulePolicy, parse
+            # out its information for the given method in order to construct a
+            # Contrast::Agent::Patching::Policy::MethodPolicy
+            #
+            # @param method_name [Symbol] the name of the method for this policy
+            # @param module_policy [Contrast::Agent::Patching::Policy::ModulePolicy]
+            #   the entire policy for this module
+            # @param instance_method [Boolean] true if this method is an
+            #   instance method
+            # @return [Contrast::Agent::Patching::Policy::MethodPolicy]
+            def build_method_policy method_name, module_policy, instance_method
+              source_node =      find_method_node(module_policy.source_nodes, method_name, instance_method)
+              propagation_node = find_method_node(module_policy.propagator_nodes, method_name, instance_method)
+              trigger_node =     find_method_node(module_policy.trigger_nodes, method_name, instance_method)
+              protect_node =     find_method_node(module_policy.protect_nodes, method_name, instance_method)
+              inventory_node =   find_method_node(module_policy.inventory_nodes, method_name, instance_method)
+              deadzone_node =    find_method_node(module_policy.deadzone_nodes, method_name, instance_method)
+              method_visibility = find_visibility(source_node, propagation_node, trigger_node, protect_node, inventory_node, deadzone_node)
+              MethodPolicy.new(method_name: method_name,
+                               method_visibility: method_visibility,
+                               instance_method: instance_method,
+                               source_node: source_node,
+                               propagation_node: propagation_node,
+                               trigger_node: trigger_node,
+                               protect_node: protect_node,
+                               inventory_node: inventory_node,
+                               deadzone_node: deadzone_node)
+            end
+
+            def find_method_node nodes, method_name, is_instance_method
+              return nil unless nodes
+
+              nodes.find do |node|
+                node.instance_method? == is_instance_method && node.method_name == method_name
+              end
+            end
+
+            def find_visibility *nodes
+              nodes.find { |node| node }&.method_visibility
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/patching/policy/module_policy.rb

@@ -0,0 +1,116 @@
+# 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/patching/policy/method_policy'
+
+module Contrast
+  module Agent
+    module Patching
+      module Policy
+        # This class is used to map a class to all policy nodes utilizing that
+        # class. It should be initialized using the create_module_policy method
+        # rather than new.
+        class ModulePolicy
+          class << self
+            # Given the name of a module, create a :ModulePolicy for it using
+            # the Policy of each supported feature
+            #
+            # @param module_name [String] the name of the module to which the
+            #   policy applies
+            # @return [Contrast::Agent::Patching::Policy::ModulePolicy]
+            def create_module_policy module_name
+              module_policy = Contrast::Agent::Patching::Policy::ModulePolicy.new
+              module_policy.source_nodes =      nodes_for_module(Contrast::Agent::Assess::Policy::Policy.instance.sources, module_name)
+              module_policy.propagator_nodes =  nodes_for_module(Contrast::Agent::Assess::Policy::Policy.instance.propagators, module_name)
+              module_policy.trigger_nodes =     nodes_for_module(Contrast::Agent::Assess::Policy::Policy.instance.triggers, module_name)
+              module_policy.protect_nodes =     nodes_for_module(Contrast::Agent::Protect::Policy::Policy.instance.triggers, module_name)
+              module_policy.inventory_nodes =   nodes_for_module(Contrast::Agent::Inventory::Policy::Policy.instance.triggers, module_name)
+              module_policy.deadzone_nodes =    nodes_for_module(Contrast::Agent::Deadzone::Policy::Policy.instance.deadzones, module_name)
+              module_policy
+            end
+
+            # Find any of the given patchers that match this class' names.
+            # Always returns an array, even if it's empty.
+            #
+            # @param nodes [Array(Contrast::Agent::Patching::Policy::PolicyNode)]
+            #   an array of nodes
+            # @param class_name [String] the class to filter the nodes on
+            # @return [Array<Contrast::Agent::Patching::Policy::PolicyNode>]
+            #   Subset of nodes which apply to the given class
+            def nodes_for_module nodes, class_name
+              nodes.select { |node| class_name == node.class_name }
+            end
+          end
+
+          attr_accessor :source_nodes, :propagator_nodes, :trigger_nodes, :inventory_nodes, :protect_nodes, :deadzone_nodes
+
+          def empty?
+            return false if source_nodes.any?
+            return false if propagator_nodes.any?
+            return false if trigger_nodes.any?
+            return false if inventory_nodes.any?
+            return false if protect_nodes.any?
+            return false if deadzone_nodes.any?
+
+            true
+          end
+
+          # The number of expected patches for this policy is the sum of unique
+          # targeted methods for the Module to which this policy applies.
+          #
+          # @return [Integer] count of methods to be patched
+          def num_expected_patches
+            @_num_expected_patches ||= begin
+                                         instance_methods = Set.new
+                                         singleton_methods = Set.new
+                                         sort_method_names(source_nodes, instance_methods, singleton_methods)
+                                         sort_method_names(propagator_nodes, instance_methods, singleton_methods)
+                                         sort_method_names(trigger_nodes, instance_methods, singleton_methods)
+                                         sort_method_names(inventory_nodes, instance_methods, singleton_methods)
+                                         sort_method_names(protect_nodes, instance_methods, singleton_methods)
+                                         sort_method_names(deadzone_nodes, instance_methods, singleton_methods)
+                                         instance_methods.length + singleton_methods.length
+                                       end
+          end
+
+          def collect_class_nodes nodes, clazz_name
+            return Contrast::Utils::ObjectShare::EMPTY_ARRAY unless nodes
+
+            nodes.select { |policy_node| clazz_name == policy_node.class_name }
+          end
+
+          def collect_method_nodes nodes, method, instance_method
+            return Contrast::Utils::ObjectShare::EMPTY_ARRAY unless nodes
+
+            nodes.select do |node|
+              node.instance_method? == instance_method && node.method_name == method
+            end
+          end
+
+          def create_method_policy_subset method, instance_method
+            method_policy = ModulePolicy.new
+            method_policy.source_nodes =     collect_method_nodes(source_nodes, method, instance_method)
+            method_policy.propagator_nodes = collect_method_nodes(propagator_nodes, method, instance_method)
+            method_policy.trigger_nodes =    collect_method_nodes(trigger_nodes, method, instance_method)
+            method_policy.inventory_nodes =  collect_method_nodes(inventory_nodes, method, instance_method)
+            method_policy.protect_nodes =    collect_method_nodes(protect_nodes, method, instance_method)
+            method_policy.deadzone_nodes =   collect_method_nodes(deadzone_nodes, method, instance_method)
+            method_policy
+          end
+
+          private
+
+          def sort_method_names nodes, instance_methods, singleton_methods
+            nodes.each do |node|
+              if node.instance_method?
+                instance_methods << node.method_name
+              else
+                singleton_methods << node.method_name
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/patching/policy/patch.rb

@@ -0,0 +1,312 @@
+# Copyright (c) 2020 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+cs__scoped_require 'monitor'
+# base
+cs__scoped_require 'contrast/core_extensions/module'
+cs__scoped_require 'contrast/agent/patching/policy/method_policy'
+cs__scoped_require 'contrast/agent/patching/policy/patch_status'
+cs__scoped_require 'contrast/agent/patching/policy/trigger_node'
+cs__scoped_require 'contrast/components/interface'
+cs__scoped_require 'contrast/utils/scope_util'
+
+# assess
+cs__scoped_require 'contrast/agent/assess/policy/policy'
+cs__scoped_require 'contrast/agent/assess/policy/propagation_method'
+cs__scoped_require 'contrast/agent/assess/policy/source_method'
+cs__scoped_require 'contrast/agent/assess/policy/trigger_method'
+cs__scoped_require 'contrast/core_extensions/assess'
+
+# inventory
+cs__scoped_require 'contrast/agent/inventory/policy/policy'
+cs__scoped_require 'contrast/core_extensions/inventory'
+
+# protect
+cs__scoped_require 'contrast/agent/protect/policy/policy'
+cs__scoped_require 'contrast/core_extensions/protect'
+cs__scoped_require 'contrast/core_extensions/protect/kernel'
+
+module Contrast
+  module Agent
+    module Patching
+      module Policy
+        # This is how we patch into our customer's code. It provides a way to
+        # track which classes we need to patch into and, once we've woven,
+        # provides a map for which methods our renamed functions need to call
+        # and how.
+        module Patch
+          class << self
+            include Contrast::Agent::Assess::Policy::SourceMethod
+            include Contrast::Agent::Assess::Policy::PropagationMethod
+            include Contrast::Agent::Assess::Policy::TriggerMethod
+            extend Contrast::Utils::ScopeUtil
+
+            include Contrast::Components::Interface
+            access_component :logging, :analysis, :agent, :scope
+
+            POLICIES = [
+              Contrast::Agent::Assess::Policy::Policy,
+              Contrast::Agent::Inventory::Policy::Policy,
+              Contrast::Agent::Protect::Policy::Policy
+            ].cs__freeze
+
+            # 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)
+            # 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
+            rescue Contrast::SecurityException => e
+              # This can be C's responsibility, but it's a lot of code.
+              # Rewrite this to make C do it, once we have better macroing.
+              exit_contrast_scope!
+              raise e
+            # Anything else was our bad and we gotta catch that to allow for
+            # normal application flow
+            rescue StandardError => e
+              logger.error(e, 'Unable to apply pre patch to method.')
+            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(e, 'Unable to apply post patch to method.')
+            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 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 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 && ASSESS.enabled?
+
+              current_context = Contrast::Agent::REQUEST_TRACKER.current
+              return ret unless current_context.analyze_request?
+
+              trigger_node = method_policy.trigger_node
+              Contrast::Agent::Assess::Policy::TriggerMethod.apply_trigger_rule(trigger_node, object, ret, args) if trigger_node
+
+              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(e, 'Unable to assess method call.')
+              handle_return(propagated_ret, source_ret, ret)
+            rescue Exception => e # rubocop:disable Lint/RescueException
+              logger.error(e, 'Unable to assess method call.')
+              handle_return(propagated_ret, source_ret, ret)
+              # This will unwind the stack, so we handle our own scope exit.
+              # Move this to C when it's convenient.
+              exit_contrast_scope!
+              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.
+              applicator = trigger_node.applicator
+              # 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
+              applicator.send(applicator_method, method, exception, trigger_node.properties, object, args)
+            end
+
+            # 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 class, method, and type, return a symbol in the format
+            # <method_start>_<class_name>_<method_name>
+            def build_method_name patcher_class, patcher_method
+              (Contrast::Utils::ObjectShare::CONTRAST_PATCHED_METHOD_START +
+                  patcher_class.cs__name.gsub('::', '_').downcase +
+                  Contrast::Utils::ObjectShare::UNDERSCORE +
+                  patcher_method.to_s).to_sym
+            end
+
+            # @param mod [Module] the module in which the patch should be
+            #   placed.
+            # @param methods [Array(Symbol)] all the instance or singleton
+            #   methods in this clazz.
+            # @param method_policy [Contrast::Agent::Patching::Policy::MethodPolicy]
+            #   the policy that applies to the method to be patched.
+            # @return [Boolean] if patched, either by this invocation or a
+            #   previous, or not
+            def instrument_with_alias mod, methods, method_policy
+              cs_method_name = build_method_name(mod, method_policy.method_name)
+              # we've already patched this class, don't do it again
+              return true if methods.include?(cs_method_name)
+
+              begin
+                contrast_define_method(mod, method_policy, cs_method_name)
+              rescue NameError => e
+                # This shouldn't happen anymore, but just in case calling alias
+                # results in a NameError, we'll be safe here.
+                logger.debug(
+                    e,
+                    "The class #{ mod.cs__name } does not respond to the "\
+                    "method#{ method_policy.method_name }.")
+                return false
+              end
+              true
+            end
+
+            # @param mod [Module] the module in which the patch should be
+            #   placed.
+            # @param method_policy [Contrast::Agent::Patching::Policy::MethodPolicy]
+            #   the policy that applies to the method to be patched.
+            # @return [Boolean] if patched, either by this invocation or a
+            #   previous, or not
+            def instrument_with_prepend mod, method_policy
+              contrast_prepend_method(mod, method_policy)
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+cs__scoped_require 'cs__contrast_patch/cs__contrast_patch'