contrast-agent 3.15.0 → 4.3.0

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

@@ -61,16 +61,16 @@ module Contrast
           # @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
+              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
 
           private

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

@@ -365,12 +365,18 @@ module Contrast
                 unless target_module.instance_methods(false).include? underlying_method_name
                   # alias_method may be private
                   target_module.send(:alias_method, underlying_method_name, method_name)
+                  # TODO: RUBY-1052
+                  # rubocop:disable Performance/Kernel/DefineMethod
                   target_module.send(:define_method, method_name, unbound_method.bind(target_module))
+                  # rubocop:enable Performance/Kernel/DefineMethod
                 end
                 target_module.send(visibility, method_name) # e.g., module.private(:my_method)
               when :prepend
                 prepending_module = Module.new
+                # TODO: RUBY-1052
+                # rubocop:disable Performance/Kernel/DefineMethod
                 prepending_module.send(:define_method, method_name, unbound_method.bind(target_module))
+                # rubocop:enable Performance/Kernel/DefineMethod
                 prepending_module.send(visibility, method_name)
                 # This prepends to the singleton class (it patches a class method)
                 target_module.prepend prepending_module

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

@@ -124,12 +124,26 @@ module Contrast
           end
 
           def find_source_node class_name, method_name, instance_method
-            sources.find { |source| source.class_name == class_name && source.method_name == method_name && source.instance_method == instance_method }
+            sources.find do |source|
+              source.class_name == class_name &&
+                  source.method_name == method_name &&
+                  source.instance_method == instance_method
+            end
+          end
+
+          def find_propagator_node class_name, method_name, instance_method
+            propagators.find do |propagator|
+              propagator.class_name == class_name &&
+                  propagator.method_name == method_name &&
+                  propagator.instance_method == instance_method
+            end
           end
 
           def find_node rule_id, class_name, method_name, instance_method
             find_triggers_by_rule(rule_id).find do |node|
-              node.class_name == class_name && node.method_name == method_name && node.instance_method == instance_method
+              node.class_name == class_name &&
+                  node.method_name == method_name &&
+                  node.instance_method == instance_method
             end
           end
         end

data/lib/contrast/agent/protect/policy/applies_command_injection_rule.rb

@@ -30,11 +30,9 @@ module Contrast
               Contrast::Agent::Protect::Policy::AppliesDeserializationRule.apply_deserialization_command_check(command)
               return if skip_analysis?
 
-              begin
-                clazz = object.is_a?(Module) ? object : object.cs__class
-                class_name = clazz.cs__name
-                rule.infilter(Contrast::Agent::REQUEST_TRACKER.current, class_name, method, command)
-              end
+              clazz = object.is_a?(Module) ? object : object.cs__class
+              class_name = clazz.cs__name
+              rule.infilter(Contrast::Agent::REQUEST_TRACKER.current, class_name, method, command)
             end
 
             protected

data/lib/contrast/agent/protect/policy/applies_deserialization_rule.rb

@@ -16,6 +16,23 @@ module Contrast
           extend Contrast::Agent::Protect::Policy::RuleApplicator
 
           class << self
+            # Calls the actual rule for this applicator, if required. Most rules
+            # invoke this from within their apply_rule method after doing
+            # whatever transformations they need to get into this common format.
+            #
+            # @param _method [Symbol] the name of the method for which this rule
+            #   is invoked
+            # @param _exception [Exception] any exception raised; used for rules
+            #   like Padding Oracle Attack (now defunct), which determine if the
+            #   number and type of exceptions are an attack
+            # @param _properties [Hash] set of extra information provided by the
+            #   applicator in an attempt to build a better story for the user
+            # @param _object [Object] the thing on which the triggering method
+            #   was invoked
+            # @param args [Array<Object>] the arguments passed to the triggering
+            #   method at invocation
+            # @raise [Contrast::SecurityException] on block, will pass the
+            #   exception from the rule
             def invoke _method, _exception, _properties, _object, args
               return unless valid_input?(args)
               return if skip_analysis?
@@ -23,6 +40,28 @@ module Contrast
               rule.infilter(Contrast::Agent::REQUEST_TRACKER.current, args[0])
             end
 
+            # Calls the actual rule for this applicator, if required, when the
+            # triggering method is called from Marshal.load when it has been
+            # prepended.
+            #
+            # @param arg [Object] the argument passed to the triggering method
+            #   at invocation
+            # @raise [Contrast::SecurityException] on block, will pass the
+            #   exception from the rule
+            def prepended_invoke arg
+              return unless arg&.cs__is_a?(String)
+              return if skip_analysis?
+
+              rule.infilter(Contrast::Agent::REQUEST_TRACKER.current, arg)
+            end
+
+            # Allow the rule to check if the given input is an attempt to
+            # deserialize something in a way that will result in a command
+            # execution
+            #
+            # @param command [String] user input that potentially contains a
+            #   Gadget, a Module that results in code execution on
+            #   deserialization, and some form of command.
             def apply_deserialization_command_check command
               return unless command
               return if skip_analysis?
@@ -38,11 +77,18 @@ module Contrast
 
             private
 
+            # Determine if the rule would care about the arguments passed in
+            # this method invocation. Required b/c Ruby doesn't do type
+            # checking on its method signatures.
+            #
+            # @param args [Array<Object>] the arguments provided to the
+            #   instrumented method
+            # @return [Boolean]
             def valid_input? args
               return false unless args&.any?
 
               input = args[0]
-              input.is_a?(String)
+              input.cs__is_a?(String)
             end
           end
         end

data/lib/contrast/agent/protect/policy/applies_path_traversal_rule.rb

@@ -26,7 +26,7 @@ module Contrast
 
               action = properties['action']
               write_marker = write?(action, *args)
-              possible_write = write_marker && possible_write(write_marker)
+              possible_write = write_marker && possible_write?(write_marker)
               path_traversal_rule(path, possible_write, object, method)
 
               # If the action was copy, we need to handle the write half of it.
@@ -48,7 +48,7 @@ module Contrast
 
             private
 
-            def possible_write input
+            def possible_write? input
               input.cs__respond_to?(:to_s) &&
                   input.to_s.include?(Contrast::Utils::ObjectShare::WRITE_FLAG)
             end
@@ -62,7 +62,7 @@ module Contrast
               return true if action == WRITE
 
               write_marker = args.length > 1 ? args[1] : nil
-              write_marker && possible_write(write_marker)
+              write_marker && possible_write?(write_marker)
             end
 
             def path_traversal_rule path, possible_write, object, method
@@ -83,6 +83,7 @@ module Contrast
                   tmp = CS__SAFER_REL_PATHS.map { |r| "#{ pwd }/#{ r }" }
                   gems = ENV['GEM_PATH']
                   tmp += gems.split(Contrast::Utils::ObjectShare::COLON) if gems
+                  tmp.map!(&:downcase)
                   tmp
                 else
                   []

data/lib/contrast/agent/protect/policy/applies_xxe_rule.rb

@@ -27,7 +27,7 @@ module Contrast
             def apply_rule__io method, _exception, _properties, object, args
               need_rewind = false
               potential_xml = args[0]
-              return unless potential_xml&.respond_to?(:rewind)
+              return unless potential_xml.cs__respond_to?(:rewind)
 
               xml = potential_xml.read
               need_rewind = true

data/lib/contrast/agent/protect/policy/rule_applicator.rb

@@ -15,6 +15,28 @@ module Contrast
 
           access_component :analysis, :logging
 
+          # Calls the actual invocation for this applicator, if required. Will
+          # attempt to transform the data as required prior to invocation and
+          # provides a common interface for those rules that have the same
+          # implementation regardless of the method patched.
+          #
+          # For those methods with different transformations depending on the
+          # method instrumented, variations of this method, including an
+          # indication of for which instrumented method they apply, will exist.
+          #
+          # @param method [Symbol] the name of the method for which this rule
+          #   is invoked
+          # @param exception [Exception] any exception raised; used for rules
+          #   like Padding Oracle Attack (now defunct), which determine if the
+          #   number and type of exceptions are an attack
+          # @param properties [Hash] set of extra information provided by the
+          #   applicator in an attempt to build a better story for the user
+          # @param object [Object] the thing on which the triggering method was
+          #   invoked
+          # @param args [Array<Object>] the arguments passed to the triggering
+          #   method at invocation
+          # @raise [Contrast::SecurityException] on block, will pass the
+          #   exception from the rule
           def apply_rule method, exception, properties, object, args
             invoke(method, exception, properties, object, args)
           rescue Contrast::SecurityException => e
@@ -25,18 +47,49 @@ module Contrast
 
           protected
 
+          # Calls the actual rule for this applicator, if required. Most rules
+          # invoke this from within their apply_rule method after doing
+          # whatever transformations they need to get into this common format.
+          #
+          # @param _method [Symbol] the name of the method for which this rule
+          #   is invoked
+          # @param _exception [Exception] any exception raised; used for rules
+          #   like Padding Oracle Attack (now defunct), which determine if the
+          #   number and type of exceptions are an attack
+          # @param _properties [Hash] set of extra information provided by the
+          #   applicator in an attempt to build a better story for the user
+          # @param _object [Object] the thing on which the triggering method
+          #   was invoked
+          # @param _args [Array<Object>] the arguments passed to the triggering
+          #   method at invocation
+          # @raise [Contrast::SecurityException] on block, will pass the
+          #   exception from the rule
           def invoke _method, _exception, _properties, _object, _args
             raise NoMethodError, 'This is abstract, override it.'
           end
 
+          # The name of the rule, as expected by the Contrast Service and
+          # Contrast UI.
+          #
+          # @return [String]
           def name
             raise NoMethodError, 'This is abstract, override it.'
           end
 
+          # The rule for which this applicator applies. It'll be a concrete
+          # sub-class of Contrast::Agent::Protect::Rule::Base, found based on
+          # the value of Contrast::Agent::Protect::Policy::RuleApplicator#name.
+          #
+          # @return [Contrast::Agent::Protect::Rule::Base]
           def rule
             PROTECT.rule name
           end
 
+          # Should we skip analysis for this rule for this method invocation?
+          # This allows us to short circuit in those cases for which the rule
+          # will not apply.
+          #
+          # @return [Boolean]
           def skip_analysis?
             context = Contrast::Agent::REQUEST_TRACKER.current
             return true unless context&.app_loaded?

data/lib/contrast/agent/protect/rule/base.rb

@@ -10,7 +10,7 @@ module Contrast
         # This is a basic rule for Protect. It's the abstract class which all other
         # protect rules extend in order to function.
         #
-        # @abstract Subclass and override {#prefilter}, {#infilter}, {#find_attacker}, {#postfilter} and {#build_details} to implement
+        # @abstract Subclass and override {#prefilter}, {#infilter}, {#find_attacker}, {#postfilter} to implement
         class Base
           include Contrast::Components::Interface
 
@@ -20,13 +20,19 @@ module Contrast
             user_input.input_type = :UNKNOWN
           end
 
-          BLOCKING_MODES = Set.new([Contrast::Api::Settings::ProtectionRule::Mode::BLOCK,
-                                    Contrast::Api::Settings::ProtectionRule::Mode::BLOCK_AT_PERIMETER]).cs__freeze
-          POSTFILTER_MODES = Set.new([Contrast::Api::Settings::ProtectionRule::Mode::BLOCK,
-                                      Contrast::Api::Settings::ProtectionRule::Mode::PERMIT,
-                                      Contrast::Api::Settings::ProtectionRule::Mode::MONITOR]).cs__freeze
-          STACK_COLLECTION_RESULTS = Set.new([Contrast::Api::Dtm::AttackResult::ResponseType::BLOCKED,
-                                              Contrast::Api::Dtm::AttackResult::ResponseType::MONITORED]).cs__freeze
+          BLOCKING_MODES = Set.new([
+                                     Contrast::Api::Settings::ProtectionRule::Mode::BLOCK,
+                                     Contrast::Api::Settings::ProtectionRule::Mode::BLOCK_AT_PERIMETER
+                                   ]).cs__freeze
+          POSTFILTER_MODES = Set.new([
+                                       Contrast::Api::Settings::ProtectionRule::Mode::BLOCK,
+                                       Contrast::Api::Settings::ProtectionRule::Mode::PERMIT,
+                                       Contrast::Api::Settings::ProtectionRule::Mode::MONITOR
+                                     ]).cs__freeze
+          STACK_COLLECTION_RESULTS = Set.new([
+                                               Contrast::Api::Dtm::AttackResult::ResponseType::BLOCKED,
+                                               Contrast::Api::Dtm::AttackResult::ResponseType::MONITORED
+                                             ]).cs__freeze
 
           attr_reader :mode
 
@@ -116,6 +122,26 @@ module Contrast
           #    the current request
           def postfilter _context; end
 
+          # A given input, candidate_string, was determined to violate a
+          # protect rule and did exploit the application, or at least made it
+          # to exploitable code in the case where we blocked the attack. As
+          # such, we need to build a result to report this violation to the
+          # Service.
+          #
+          # @param context [Contrast::Agent::RequestContext] the context of the
+          #   request in which this input is evaluated.
+          # @param ia_result [Contrast::Api::Settings::InputAnalysisResult] the
+          #   analysis of the input that was determined to be an attack
+          # @param result [Contrast::Api::Dtm::AttackResult, nil] previous
+          #   attack result for this rule, if one exists, in the case of
+          #   multiple inputs being found to violate the protection criteria
+          # @param candidate_string [String] the value of the input which may
+          #   be an attack
+          # @param kwargs [Hash] key - value pairs of context individual rules
+          #   need to build out details to send to the Service to tell the
+          #   story of the attack
+          # @return [Contrast::Api::Dtm::AttackResult] the attack result from
+          #   this input
           def build_attack_with_match context, ia_result, result, candidate_string, **kwargs
             result ||= build_attack_result(context)
             update_successful_attack_response(context, ia_result, result, candidate_string)
@@ -124,6 +150,22 @@ module Contrast
             result
           end
 
+          # A given input, candidate_string, was determined to violate a
+          # protect rule but did not exploit the application. As such, we need
+          # to build a result to report this violation to the Service.
+          #
+          # @param context [Contrast::Agent::RequestContext] the context of the
+          #   request in which this input is evaluated.
+          # @param ia_result [Contrast::Api::Settings::InputAnalysisResult] the
+          #   analysis of the input that was determined to be an attack
+          # @param result [Contrast::Api::Dtm::AttackResult, nil] previous
+          #   attack result for this rule, if one exists, in the case of
+          #   multiple inputs being found to violate the protection criteria
+          # @param kwargs [Hash] key - value pairs of context individual rules
+          #   need to build out details to send to the Service to tell the
+          #   story of the attack
+          # @return [Contrast::Api::Dtm::AttackResult] the attack result from
+          #   this input
           def build_attack_without_match context, ia_result, result, **kwargs
             result ||= build_attack_result(context)
             update_perimeter_attack_response(context, ia_result, result)
@@ -132,16 +174,18 @@ module Contrast
             result
           end
 
+          # Attach the given result to the current request's context to report
+          # it to the Service
+          #
+          # @param context [Contrast::Agent::RequestContext] the context of the
+          #   request in which this input is evaluated.
+          # @param result [Contrast::Api::Dtm::AttackResult]
           def append_to_activity context, result
             context.activity.results << result if result
           end
 
           protected
 
-          def build_details _input_string, _ia_result
-            raise NoMethodError, "Rule #{ name } did not implement build_details"
-          end
-
           def mode_from_settings
             PROTECT.rule_mode(name).tap do |mode|
               logger.trace('Retrieving rule mode', rule: name, mode: mode)
@@ -209,6 +253,11 @@ module Contrast
             result
           end
 
+          # Set up an attack result for the current rule
+          #
+          # @param _context [Contrast::Agent::RequestContext] the context of
+          #   the current request
+          # @return [Contrast::Api::Dtm::AttackResult]
           def build_attack_result _context
             result = Contrast::Api::Dtm::AttackResult.new
             result.rule_id = name
@@ -226,10 +275,10 @@ module Contrast
           end
 
           def append_sample context, ia_result, result, candidate_string, **kwargs
-            return nil unless result
+            return unless result
 
             sample = build_sample(context, ia_result, candidate_string, **kwargs)
-            return nil unless sample
+            return unless sample
 
             append_stack(sample, result)
 

data/lib/contrast/agent/protect/rule/cmd_injection.rb

@@ -1,7 +1,6 @@
 # Copyright (c) 2020 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
 # frozen_string_literal: true
 
-require 'contrast/agent/at_exit_hook'
 require 'contrast/agent/protect/rule/base_service'
 require 'contrast/utils/stack_trace_utils'
 require 'contrast/utils/object_share'
@@ -24,10 +23,10 @@ module Contrast
           end
 
           def infilter context, classname, method, command
-            return nil unless infilter?(context)
+            return unless infilter?(context)
 
             ia_results = gather_ia_results(context)
-            return nil if ia_results.empty?
+            return if ia_results.empty?
 
             if APP_CONTEXT.in_new_process?
               logger.trace('Running cmd-injection infilter within new process - creating new context')
@@ -37,7 +36,7 @@ module Contrast
 
             result = find_attacker_with_results(context, command, ia_results, **{ classname: classname, method: method })
             result ||= report_command_execution(context, command, **{ classname: classname, method: method })
-            return nil unless result
+            return unless result
 
             append_to_activity(context, result)
             return unless blocked?
@@ -45,11 +44,6 @@ module Contrast
             raise Contrast::SecurityException.new(
                 self,
                 "Command Injection rule triggered. Call to #{ classname }.#{ method } blocked.")
-          ensure
-            # Kernel#exec replaces the current process and does not go through
-            # at_exit hooks. Kernel#` runs as a subshell - messages appended
-            # here do not seem to be present in the original process.
-            Contrast::Agent::AtExitHook.on_exit if %i[exec `].include?(method.to_sym)
           end
 
           def build_attack_with_match context, input_analysis_result, result, candidate_string, **kwargs
@@ -104,37 +98,27 @@ module Contrast
 
           def report_command_execution context, command, **kwargs
             return unless report_any_command_execution?
-            return nil if protect_excluded_by_code?
+            return if protect_excluded_by_code?
 
             build_attack_with_match(context, nil, nil, command, **kwargs)
           end
 
           def find_probable_attacker context, potential_attack_string, ia_results, **kwargs
-            result = nil
-            if chained_command?(potential_attack_string) # this is probably an attack
-              most_likely = nil
-              ia_results.each do |input_analysis_result|
-                next unless chained_command?(input_analysis_result.value)
-
-                most_likely = input_analysis_result
-                break
-              end
-            end
-            return result unless most_likely
+            return unless chained_command?(potential_attack_string)
+
+            likely_attacker = ia_results.find { |input_analysis_result| chained_command?(input_analysis_result.value) }
+            return unless likely_attacker
 
-            result ||= build_attack_with_match(
+            build_attack_with_match(
                 context,
-                most_likely,
-                result,
+                likely_attacker,
+                nil,
                 potential_attack_string,
                 **kwargs)
-            result
           end
 
           def chained_command? command
-            return true if CHAINED_COMMAND_CHARS.match(command)
-
-            false
+            CHAINED_COMMAND_CHARS.match(command)
           end
 
           # Part of the Hardening for Command Injection detection is the