contrast-agent 4.1.0 → 4.4.0

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

@@ -89,7 +89,7 @@ module Contrast
             end
 
             def find_method_node nodes, method_name, is_instance_method
-              return nil unless nodes
+              return unless nodes
 
               nodes.find do |node|
                 node.instance_method? == is_instance_method && node.method_name == method_name

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/patch_status.rb

@@ -13,7 +13,7 @@ module Contrast
             # one does not exist.
             #
             # @param mod [Module] the Module for which the status is asked
-            # @return [Contrast::Agent::Patching::Policy::PolicyStatus]
+            # @return [Contrast::Agent::Patching::Policy::PatchStatus]
             def get_status mod
               if mod.cs__const_defined?(status_key, false)
                 mod.cs__const_get(status_key, false)

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

@@ -52,7 +52,7 @@ module Contrast
             # startup to catchup on everything we didn't see get loaded
             def patch
               catchup_after_load_patches
-              patch_methods
+              catchup_loaded_methods
               Contrast::Agent::Assess::Policy::RewriterPatch.rewrite_interpolations
             end
 
@@ -62,10 +62,11 @@ module Contrast
             # where only a subset of the Assess changes are needed.
             PATCH_MONITOR = Monitor.new
 
-            def patch_methods
+            # Iterate over and patch those Modules and Methods which were loaded before the Agent was enabled.
+            def catchup_loaded_methods
               PATCH_MONITOR.synchronize do
                 t = Contrast::Agent::Thread.new do
-                  synchronized_patch_methods
+                  synchronized_catchup_loaded_methods
                 end
                 # aborting on exception makes exceptions propagate.
                 t.abort_on_exception = true
@@ -100,7 +101,7 @@ module Contrast
             # @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.
+            #   methods in this mod.
             # @param method_policy [Contrast::Agent::Patching::Policy::MethodPolicy]
             #   the policy that applies to the given method_name.
             # @return [Boolean] if patched, either by this invocation or a
@@ -149,7 +150,7 @@ module Contrast
             # other functions, like rewriting or scanning. This method should
             # only be invoked by the patch_methods method above in order to
             # ensure it is wrapped in a synchronize call
-            def synchronized_patch_methods
+            def synchronized_catchup_loaded_methods
               logger.trace_with_time('Running patching') do
                 patched = []
                 all_module_names.each do |patchable_name|
@@ -166,53 +167,37 @@ module Contrast
               end
             end
 
-            # Given the patchers that apply to this class that may apply, patch
-            # Contrast method calls into the methods for which we have rules.
+            # Given the patchers that apply to this class that may apply, patch Contrast method calls into the methods
+            # for which we have rules.
             #
-            # @param module_data [Contrast::Agent::ModuleData] the module, and
-            #   its name, that's being patched into
-            # @param redo_patch [Boolean] a trigger to force patching
-            #   regardless of the state of the
-            #   Contrast::Agent::Patching::Policy::PatchStatus status on the
-            #   Module
+            # @param module_data [Contrast::Agent::ModuleData] the module, and its name, that's being patched into
+            # @param redo_patch [Boolean] a trigger to force patching regardless of the state of the
+            #   Contrast::Agent::Patching::Policy::PatchStatus status on the Module
             def patch_into_module module_data, redo_patch = false
               status = status_type.get_status(module_data.mod)
               return if (status&.patched? || status&.patching?) && !redo_patch
 
-              # Begin patching our sources into the given clazz (or module)
-              # Any patcher that has the name of the clazz will be evaluated for
-              # patching.
-              # Find all the patchers that apply to this class, sorted by type.
+              # Begin patching our sources into the given module. Any patcher that has the name of the module will be
+              # evaluated for patching. Find all the patchers that apply to this class, sorted by type.
               module_policy = Contrast::Agent::Patching::Policy::ModulePolicy.create_module_policy(module_data.name)
-
-              clazz = module_data.mod
+              # If there's nothing to match, then set that status and exit
+              if module_policy.empty?
+                status.no_patch!
+                return
+              end
 
               status.patching!
-              patched = false
-
-              counts = 0
-              # Monkey patch any methods in this class that have matching nodes in the policy
-              unless module_policy.empty?
-                instance_methods = all_instance_methods(clazz, true)
-                singleton_methods = clazz.singleton_methods(false)
-                counts += patch_into_methods(clazz, instance_methods, module_policy, true)
-                counts += patch_into_methods(clazz, singleton_methods, module_policy, false)
-                counts = module_policy.num_expected_patches if adjust_for_prepend(clazz)
-                patched = true
-              end
+              num_applied_patches = patch_into_instance_methods(module_data, module_policy)
+              num_applied_patches += patch_into_singleton_methods(module_data, module_policy)
+              if adjust_for_prepend(module_data) ||
+                    module_policy.num_expected_patches == num_applied_patches
 
-              if patched
-                if module_policy.num_expected_patches == counts
-                  status.patched!
-                else
-                  status.partial_patch!
-                end
+                status.patched!
               else
-                status.no_patch!
+                status.partial_patch!
               end
             rescue StandardError => e
-              status ||= status_type.get_status(module_data.mod)
-              status.failed_patch!
+              status&.failed_patch!
               logger.warn('Patching failed', e, module: module_data.name)
             ensure
               logger.trace('Patching complete',
@@ -249,6 +234,29 @@ module Contrast
               instance_methods
             end
 
+            # Patch into the Instance Methods, including private, of the given Module that match the ModulePolicy
+            # provided.
+            #
+            # @param module_data [Contrast::Agent::ModuleData] the module, and its name, that's being patched into
+            # @param module_policy [Contrast::Agent::Patching::Policy::ModulePolicy] All the patchers that apply to
+            #   this module, sorted by type.
+            def patch_into_instance_methods module_data, module_policy
+              mod = module_data.mod
+              methods = all_instance_methods(mod, true)
+              patch_into_methods(mod, methods, module_policy, true)
+            end
+
+            # Patch into the Singleton Methods of the given Module that match the ModulePolicy provided.
+            #
+            # @param module_data [Contrast::Agent::ModuleData] the module, and its name, that's being patched into
+            # @param module_policy [Contrast::Agent::Patching::Policy::ModulePolicy] All the patchers that apply to
+            #   this module, sorted by type.
+            def patch_into_singleton_methods module_data, module_policy
+              mod = module_data.mod
+              methods = mod.singleton_methods(false)
+              patch_into_methods(mod, methods, module_policy, false)
+            end
+
             # We've found the patchers that apply to this class (or module). Now we'll
             # filter on the given method.
             #
@@ -279,11 +287,10 @@ module Contrast
             # it has to be reapplied.
             # TODO: RUBY-620 should remove the need for this
             #
-            # @param mod[Module] the Module for which a prepend action needs to
-            #   be accounted
+            # @param module_data [Contrast::Agent::ModuleData] the module, and its name, that's being patched into
             # @return [Boolean] if an adjustment was made or not
-            def adjust_for_prepend mod
-              return false unless mod.cs__name == 'CGI::Util'
+            def adjust_for_prepend module_data
+              return false unless module_data.mod.cs__name == 'CGI::Util'
 
               CGI.include(CGI::Util)
               CGI.extend(CGI::Util)

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

@@ -46,6 +46,11 @@ module Contrast
               raise(ArgumentError,
                     "#{ id } did not have a proper applicator method: #{ applicator } does not respond to #{ applicator_method }. Unable to create.")
             end
+            validate_properties
+            validate_rule
+          end
+
+          def validate_properties
             if (required_properties & optional_properties).any?
               raise(ArgumentError, "#{ rule_id } had overlapping elements between required and optional properties. Unable to create.")
             end
@@ -53,8 +58,6 @@ module Contrast
               raise(ArgumentError, "#{ id } had an unexpected property. Unable to create.")
             end
             raise(ArgumentError, "#{ id } did not have a required property. Unable to create.") if (required_properties - properties.keys).any?
-
-            validate_rule
           end
 
           def validate_rule

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/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)