contrast-agent 4.2.0 → 4.3.0

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

@@ -23,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')
@@ -36,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?

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

@@ -123,10 +123,7 @@ class Contrast::Agent::Protect::Rule::DefaultScanner # rubocop:disable Style/Cla
     elsif start_block_comment?(char, index, query)
       boundaries << index
       :STATE_INSIDE_BLOCK_COMMENT
-    elsif operator?(char)
-      boundaries << index
-      :STATE_EXPECTING_TOKEN
-    elsif char.match?(Contrast::Utils::ObjectShare::WHITE_SPACE_REGEXP)
+    elsif operator?(char) || char.match?(Contrast::Utils::ObjectShare::WHITE_SPACE_REGEXP)
       boundaries << index
       :STATE_EXPECTING_TOKEN
     else

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

@@ -17,19 +17,22 @@ module Contrast
           BLOCK_MESSAGE = 'Untrusted Deserialization rule triggered. Deserialization blocked.'
 
           # Gadgets that map to ERB modules
-          ERB_GADGETS = %w[
+          ERB_GADGETS = %W[
             object:ERB
+            o:\bERB
           ].cs__freeze
 
           # Gadgets that map to ActionDispatch modules
           ACTION_DISPATCH_GADGETS = %w[
             object:ActionDispatch::Routing::RouteSet::NamedRouteCollection
+            o:\bActionDispatch::Routing::RouteSet::NamedRouteCollection
           ].cs__freeze
 
           # Gadgets that map to Arel Modules
           AREL_GADGETS = %w[
             string:Arel::Nodes::SqlLiteral
             object:Arel::Nodes
+            o:\bArel::Nodes
           ].cs__freeze
 
           # Used to indicate to TeamServer the gadget is an ERB module

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

@@ -21,10 +21,10 @@ module Contrast
           end
 
           def infilter context, database, query_string
-            return nil unless infilter?(context)
+            return unless infilter?(context)
 
             result = find_attacker(context, query_string, database: database)
-            return nil unless result
+            return unless result
 
             append_to_activity(context, result)
 
@@ -36,7 +36,7 @@ module Contrast
 
             attack_string = input_analysis_result.value
             regexp = Regexp.new(Regexp.escape(attack_string), Regexp::IGNORECASE)
-            return nil unless query_string.match?(regexp)
+            return unless query_string.match?(regexp)
 
             scanner = select_scanner
             ss = StringScanner.new(query_string)

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

@@ -22,10 +22,10 @@ module Contrast
           end
 
           def infilter context, database, query_string
-            return nil unless infilter?(context)
+            return unless infilter?(context)
 
             result = find_attacker(context, query_string, database: database)
-            return nil unless result
+            return unless result
 
             append_to_activity(context, result)
 
@@ -36,7 +36,7 @@ module Contrast
             attack_string = input_analysis_result.value
             regexp = Regexp.new(Regexp.escape(attack_string), Regexp::IGNORECASE)
 
-            return nil unless query_string.match?(regexp)
+            return unless query_string.match?(regexp)
 
             database = kwargs[:database]
             scanner = select_scanner(database)

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

@@ -19,7 +19,9 @@ module Contrast
             NAME
           end
 
-          # Given an xml, evaluate it for an XXE attack.
+          # Given an xml, evaluate it for an XXE attack. There's no return here
+          # as this method handles appending the evaluation to the request
+          # context, connecting it to the reporting mechanism at request end.
           #
           # @param context [Contrast::Agent::RequestContext] the context of the
           #   request in which this input is evaluated.
@@ -29,7 +31,7 @@ module Contrast
           #   attack is found and the rule is in block mode.
           def infilter context, framework, xml
             result = find_attacker(context, xml, framework: framework)
-            return nil unless result
+            return unless result
 
             append_to_activity(context, result)
             return unless blocked?
@@ -39,16 +41,23 @@ module Contrast
 
           protected
 
+          # Given an XML, find any externally resolved entities and create an
+          # Attack Result for them
+          #
+          # @param context [Contrast::Agent::RequestContext] the context of the
+          #   request in which this input is evaluated.
+          # @param xml [String] the literal value of the XML being checked for
+          #   external entity resolution
+          # @param _kwargs [Hash]
+          # @return [Contrast::Api::Dtm::AttackResult, nil] the determination
+          #   as to whether or not this XML has an XXE attack in it.
           def find_attacker context, xml, **_kwargs
-            return nil unless xml
-            return nil if protect_excluded_by_code?
+            return unless xml
+            return if protect_excluded_by_code?
 
-            xxe_details, last_idx = build_details(xml)
-            return nil unless xxe_details
+            xxe_details = build_details(xml)
+            return unless xxe_details
 
-            # For our definition, the prolog goes from the start of the XML
-            # string to the end of the last entity declaration.
-            xxe_details.xml = Contrast::Utils::StringUtils.protobuf_safe_string(xml[0, last_idx])
             ia_result = build_evaluation(xxe_details.xml)
             build_attack_with_match(
                 context,
@@ -58,7 +67,15 @@ module Contrast
                 details: xxe_details)
           end
 
-          def build_details xml, _evaluation = nil
+          # Given an XML determined to be unsafe, build out the details of the
+          # attack. The details will include a substring of the given XML up to
+          # the end of the prolog, where the external entities are declared.
+          #
+          # @param xml [String] the literal value of the XML being checked for
+          #   external entity resolution
+          # @return [Contrast::Api::Dtm::XxeDetails] The details of
+          #   the XXE attack and the index of the last entity discovered
+          def build_details xml
             last_idx = 0
             ss = StringScanner.new(xml)
             while ss.scan_until(EXTERNAL_ENTITY_PATTERN)
@@ -70,7 +87,11 @@ module Contrast
               xxe_details.declared_entities << build_match(ss)
               xxe_details.entities_resolved << build_wrapper(entity_wrapper)
             end
-            [xxe_details, last_idx]
+            # For our definition, the prolog goes from the start of the XML
+            # string to the end of the last entity declaration.
+            xxe_details.xml = Contrast::Utils::StringUtils.protobuf_safe_string(xml[0, last_idx]) if xxe_details
+
+            xxe_details
           end
 
           def build_sample context, ia_result, _url, **kwargs

data/lib/contrast/agent/protect/rule/xxe/entity_wrapper.rb

@@ -18,12 +18,16 @@ module Contrast
             end
 
             def external_entity?
-              @_external_entity ||= begin
-                return external_id?(@system_id) if @system_id
-                return external_id?(@public_id) if @public_id
-
-                false
+              if @_external_entity.nil?
+                @_external_entity ||= if @system_id
+                                        external_id?(@system_id)
+                                      elsif @public_id
+                                        external_id?(@public_id)
+                                      else
+                                        false
+                                      end
               end
+              @_external_entity
             end
 
             # <!ENTITY name SYSTEM "URI">
@@ -48,7 +52,7 @@ module Contrast
             UP_DIR_LINUX = '../'
             UP_DIR_WIN =   '..\\'
             # we only use this against lowercase strings, removed A-Z for speed
-            FILE_PATTERN_WINDOWS = /^[\\\\]*[a-z]{1,3}:.*/.cs__freeze
+            FILE_PATTERN_WINDOWS = /^\\*[a-z]{1,3}:.*/.cs__freeze
             def external_id? entity_id
               return false unless entity_id
 

data/lib/contrast/agent/reaction_processor.rb

@@ -22,7 +22,7 @@ module Contrast
       # @param application_settings [Contrast::Api::Settings::ApplicationSettings]
       #   those settings which the Service has relayed from TeamServer.
       def self.process application_settings
-        return nil unless application_settings&.reactions&.any?
+        return unless application_settings&.reactions&.any?
 
         application_settings.reactions.each do |reaction|
           # the enums are all uppercase, we need to downcase them before attempting to log

data/lib/contrast/agent/response.rb

@@ -118,16 +118,16 @@ module Contrast
       #   holds, wraps, or is the body of the Response
       # @return [nil, String] the content of the body
       def extract_body body
-        return nil unless body
+        return unless body
 
         if defined?(Rack::File) && body.is_a?(Rack::File)
           # not sure what to do in this situation, so don't do anything.
           nil
         elsif body.is_a?(Rack::BodyProxy)
           handle_rack_body_proxy(body)
-        elsif defined?(ActionDispatch::Response::RackBody) && body.is_a?(ActionDispatch::Response::RackBody)
-          extract_body(body.body)
-        elsif body.is_a?(Rack::Response)
+        elsif (defined?(ActionDispatch::Response::RackBody) && body.is_a?(ActionDispatch::Response::RackBody)) ||
+              body.is_a?(Rack::Response)
+
           extract_body(body.body)
         elsif Contrast::Utils::DuckUtils.quacks_to?(body, :each)
           acc = []
@@ -152,7 +152,7 @@ module Contrast
       end
 
       def read_or_string obj
-        return nil unless obj
+        return unless obj
 
         if Contrast::Utils::DuckUtils.quacks_to?(obj, :read)
           tmp = obj.read