contrast-agent 7.2.0 → 7.3.1

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

@@ -0,0 +1,191 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/utils/object_share'
+require 'contrast/agent/protect/input_analyzer/input_analyzer'
+require 'contrast/agent/protect/rule/input_classification/extendable'
+require 'contrast/agent/protect/rule/input_classification/encoding'
+require 'contrast/components/logger'
+
+module Contrast
+  module Agent
+    module Protect
+      module Rule
+        module InputClassification
+          # This module will include all the similar information for all input classifications
+          # between different rules
+          module Base
+            UNKNOWN_KEY = 'unknown'
+            include Contrast::Components::Logger::InstanceMethods
+            include Contrast::Agent::Protect::Rule::InputClassification::Extendable
+            include Contrast::Agent::Protect::Rule::InputClassification::Encoding
+
+            KEYS_NEEDED = [
+              COOKIE_VALUE, PARAMETER_VALUE, HEADER, JSON_VALUE, MULTIPART_VALUE, XML_VALUE, DWR_VALUE
+            ].cs__freeze
+
+            BASE64_INPUT_TYPES = [BODY, COOKIE_VALUE, HEADER, PARAMETER_VALUE, MULTIPART_VALUE, XML_VALUE].cs__freeze
+
+            class << self
+              include Contrast::Components::Logger::InstanceMethods
+              include Contrast::Agent::Reporting::InputType
+
+              # Finds key value and type based on input type and value.
+              # @param request [Contrast::Agent::Request] the current request context.
+              # @param input_type [Contrast::Agent::Reporting::InputType] The type of the user input.
+              # @param value [String, Array<String>] the value of the input.
+              # @return [Array<(String, Contrast::Agent::Reporting::InputType)>] key and key type.
+              def find_key request, input_type, value
+                # TODO: RUBY-99999 Add handling for multipart, json and if any missing types.
+                case input_type
+                when COOKIE_VALUE
+                  [request.cookies.key(value), Contrast::Agent::Reporting::InputType::COOKIE_NAME]
+                when PARAMETER_VALUE, URL_PARAMETER
+                  [request.parameters.key(value), Contrast::Agent::Reporting::InputType::PARAMETER_NAME]
+                when HEADER
+                  [request.headers.key(value), Contrast::Agent::Reporting::InputType::HEADER]
+                when UNKNOWN
+                  [UNKNOWN_KEY, Contrast::Agent::Reporting::InputType::UNKNOWN]
+                else
+                  [nil, nil]
+                end
+              rescue StandardError => e
+                logger.warn('[InputAnalyzer] Could not find proper key for input traced value', message: e)
+                [nil, nil]
+              end
+
+              # Some input types are not yet supported from the AgentLib.
+              # This will convert the type to the closet possible if viable,
+              # so that the input tracing could be done.
+              #
+              # @param input_type [Contrast::Agent::Reporting::InputType] The type of the user input.
+              # @return [Integer<Contrast::AgentLib::Interface::INPUT_SET>]
+              def convert_input_type input_type
+                case input_type
+                when URI, URL_PARAMETER
+                  Contrast::AGENT_LIB.input_set[:URI_PATH]
+                when BODY, DWR_VALUE, SOCKET, UNDEFINED_TYPE, UNKNOWN, REQUEST, QUERYSTRING
+                  Contrast::AGENT_LIB.input_set[:PARAMETER_VALUE]
+                when HEADER
+                  Contrast::AGENT_LIB.input_set[:HEADER_VALUE]
+                when MULTIPART_VALUE, MULTIPART_FIELD_NAME
+                  Contrast::AGENT_LIB.input_set[:MULTIPART_NAME]
+                when JSON_ARRAYED_VALUE
+                  Contrast::AGENT_LIB.input_set[:JSON_KEY]
+                when PARAMETER_NAME
+                  Contrast::AGENT_LIB.input_set[:PARAMETER_KEY]
+                else
+                  Contrast::AGENT_LIB.input_set[input_type]
+                end
+              rescue StandardError => e
+                logger.debug('[InputAnalyzer] Protect Input classification could not determine input type,
+                          falling back to default',
+                             error: e)
+                Contrast::AGENT_LIB.input_set[:PARAMETER_VALUE]
+              end
+            end
+
+            # Input Classification stage is done to determine if an user input is
+            # DEFINITEATTACK or to be ignored.
+            #
+            # @param rule_id [String] Name of the protect rule.
+            # @param input_type [Symbol, Contrast::Agent::Reporting::InputType] The type of the user input.
+            # @param value [String, Array<String>] the value of the input.
+            # @param input_analysis [Contrast::Agent::Reporting::InputAnalysis] Holds all the results from the
+            #                                                       agent analysis from the current
+            #                                                       Request.
+            # @return ia [Contrast::Agent::Reporting::InputAnalysis, nil] with updated results.
+            def classify rule_id, input_type, value, input_analysis
+              return unless (rule = Contrast::PROTECT.rule(rule_id))
+              return unless rule.applicable_user_inputs.include?(input_type)
+              return unless input_analysis.request
+
+              Array(value).each do |val|
+                Array(val).each do |v|
+                  next unless v
+
+                  result = create_new_input_result(input_analysis.request, rule.rule_name, input_type, v)
+                  append_result(input_analysis, result)
+                end
+              end
+
+              input_analysis
+            rescue StandardError => e
+              logger.debug("An Error was recorded in the input classification of the #{ rule_id }", error: e)
+              nil
+            end
+
+            # This methods checks if input is value that matches a key in the input.
+            #
+            # @param request [Contrast::Agent::Request] the current request context.
+            # @param ia_result [Contrast::Agent::Reporting::InputAnalysisResult] result to be updated.
+            # @param input_type [Contrast::Agent::Reporting::InputType] The type of the user input.
+            # @param value [String, Array<String>] the value of the input.
+            #
+            # @return result [Array<String, Symbol>] updated with key result.
+            def add_needed_key request, ia_result, input_type, value
+              ia_result.key, ia_result.key_type = Contrast::Agent::Protect::Rule::InputClassification::Base.
+                  find_key(request, input_type, value)
+            end
+
+            private
+
+            # Appends result to the InputAnalysis.
+            #
+            # @param ia_analysis [Contrast::Agent::Reporting::InputAnalysis] the current input analysis.
+            # @param result [Contrast::Agent::Reporting::InputAnalysisResult] result to be appended.
+            # @return [Contrast::Agent::Reporting::InputAnalysis] the input analysis with the appended result.
+            def append_result ia_analysis, result
+              ia_analysis.results << result if result
+              ia_analysis
+            end
+
+            # Do not override this method, it will hold base operations, instead overwrite methods called inside
+            # of this method.
+            # This methods checks if input is tagged WORTHWATCHING or IGNORE matches value with it's
+            # key if needed and Creates new instance of InputAnalysisResult.
+            #
+            # @param request [Contrast::Agent::Request] the current request context.
+            # @param rule_id [String] The name of the Protect Rule.
+            # @param input_type [Contrast::Agent::Reporting::InputType] The type of the user input.
+            # @param value [String, Array<String>] the value of the input.
+            #
+            # @return res [Contrast::Agent::Reporting::InputAnalysisResult, nil]
+            def create_new_input_result request, rule_id, input_type, value
+              return unless Contrast::AGENT_LIB
+
+              # Cache retrieve
+              cached = Contrast::Agent::Protect::InputAnalyzer.lru_cache.lookout(rule_id, value, input_type, request)
+              return cached.result if cached.cs__is_a?(Contrast::Agent::Protect::InputClassification::CachedResult)
+
+              # Input evaluation
+              input_eval = build_input_eval(rule_id, input_type, base64_decode_input(value, input_type))
+              ia_result = build_ia_result(rule_id, input_type, value, request, input_eval)
+              return unless ia_result
+
+              add_needed_key(request, ia_result, input_type, value) if KEYS_NEEDED.include?(input_type)
+              # Input evaluation end
+
+              # Cache save. Cache must be saved after the input evaluation is completed.
+              Contrast::Agent::Protect::InputAnalyzer.lru_cache.save(rule_id, ia_result, request)
+              ia_result
+            end
+
+            # Decodes the value for the given input type.
+            # Applies to BODY, COOKIE_VALUE, HEADER, PARAMETER_VALUE, MULTIPART_VALUE, XML_VALUE
+            #
+            # @param value [String]
+            # @param input_type [Symbol]
+            # @return input [String]
+            def base64_decode_input value, input_type
+              return value unless Contrast::PROTECT.normalize_base64?
+              return value unless BASE64_INPUT_TYPES.include?(input_type)
+
+              cs__decode64(value, input_type)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/protect/rule/input_classification/base64_statistic.rb

@@ -0,0 +1,71 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/agent/protect/rule/input_classification/encoding_rates'
+require 'contrast/agent/telemetry/input_analysis_encoding_event'
+require 'contrast/components/logger'
+
+module Contrast
+  module Agent
+    module Protect
+      module Rule
+        module InputClassification
+          # This class will safe all the information for the Base64 decoding matches per input type.
+          class Base64Statistic
+            include Contrast::Components::Logger::InstanceMethods
+
+            # @return [Hash<Contrast::Agent::Protect::Rule::InputClassification::EncodingRates>]
+            attr_reader :data
+
+            # Capacity for request context life cycle.
+            CAPACITY = 1000
+
+            def initialize
+              @data = {}
+            end
+
+            # Add a match for the given input type.
+            #
+            # @param input_type [Symbol]
+            def match! input_type
+              return @data[input_type]&.increase_match_base64 if @data[input_type]
+
+              @data[input_type] = Contrast::Agent::Protect::Rule::InputClassification::EncodingRates.new(input_type)
+              @data[input_type].increase_match_base64
+            end
+
+            # Add a mismatch for the given input type.
+            #
+            # @param input_type [Symbol]
+            def mismatch! input_type
+              return @data[input_type]&.increase_mismatch_base64 if @data[input_type]
+
+              @data[input_type] = Contrast::Agent::Protect::Rule::InputClassification::EncodingRates.new(input_type)
+              @data[input_type].increase_mismatch_base64
+            end
+
+            # Clears statistic data.
+            def clear
+              @data.clear
+            end
+
+            # @return [Array<Contrast::Agent::Telemetry::InputAnalysisCacheEvent>] the events to be sent.
+            def to_events
+              events = []
+              data.each do |_input_type, encoding_rate|
+                event = Contrast::Agent::Telemetry::InputAnalysisEncodingEvent.new(nil, encoding_rate)
+                next if event.empty?
+
+                events << event
+              end
+              events
+            rescue StandardError => e
+              logger.error("[Telemetry] Error while creating events: #{ e }", stacktrace: e.backtrace)
+              []
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/protect/rule/input_classification/cached_result.rb

@@ -0,0 +1,37 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/utils/duck_utils'
+require 'contrast/agent/reporting/input_analysis/input_analysis_result'
+
+module Contrast
+  module Agent
+    module Protect
+      module InputClassification
+        # This Class with store the input classification results for a given user input.
+        class CachedResult
+          # @return [String]
+          attr_reader :result
+          # @return [Integer]
+          attr_reader :request_id
+
+          # Initialize Input Classification Cached Result
+          #
+          # @param result [Contrast::Agent::Reporting::InputAnalysisResult]
+          # @param request_id [Integer] the id of current request.
+          def initialize result, request_id
+            @result = result.dup if result&.cs__is_a?(Contrast::Agent::Reporting::InputAnalysisResult)
+            @request_id = request_id
+          end
+
+          # Check if the input classification result is empty.
+          #
+          # @return [Boolean]
+          def empty?
+            Contrast::Utils::DuckUtils.empty_duck?(@result) && Contrast::Utils::DuckUtils.empty_duck?(@request_id)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/protect/rule/input_classification/encoding.rb

@@ -0,0 +1,109 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'base64'
+require 'cgi'
+require 'uri'
+
+module Contrast
+  module Agent
+    module Protect
+      module Rule
+        module InputClassification
+          # Module to hold different encoding utils.
+          module Encoding
+            include Contrast::Components::Logger::InstanceMethods
+
+            # Still a list is needed for this one, as it is not possible to determine if the value is encoded or not.
+            # As long as the list is short the method has a good percentage of success.
+            KNOWN_DECODING_EXCEPTIONS = %w[cmd].cs__freeze
+
+            # This methods is not performant, but is more safe for false positive.
+            # Base64 check is no trivial task. For example if one passes a value like 'stringdw' it will return true,
+            # or value 'pass', but it is indeed not encoded. using regexp like:
+            #
+            #     ^([A-Za-z0-9+/]{4})*([A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}==)?$
+            #
+            # This will fail with any inputs from above, and this is because any characters with 4 bytes will be
+            # considered as base64 encoded, and without additional context it is impossible to determine if the
+            # value is encoded or not. Not to mention the above regexp will not detect empty spaces.
+            #
+            # Alternative to the above regexp, acting the same way, could be this:
+            #
+            #     Base64.strict_encode64(Base64.decode64(value)) == value
+            #
+            # Making an exception list is not a good idea, because it will be hard to maintain.
+            #
+            # The Base64 method will return printable ascii characters, so we can use this to determine if the value is
+            # encoded or not.
+            #
+            # The solution in this case is encodind the value, and then decoding it. If the value is already encoded
+            # it will not be eq to the original value. If the value is not encoded, it will be eq to the original value.
+            #
+            # @param value [String] input to check for encoding status.
+            # @param input_type [Symbol] input type.
+            # @return [Boolean] true if value is base64 encoded, false otherwise.
+            def cs__base64? value, input_type
+              return false unless value.is_a?(String)
+              return false if Contrast::Utils::DuckUtils.empty_duck?(value)
+
+              # Encoded string levels of decoding example:
+              #
+              # Value encoded 'pass' => 'cGFzcw=='
+              # decode level 0 => 'pass'
+              # decode level 1 => '\xA5\xAB,'
+              # decode level 2 => ''
+              check_value = value.dup
+              return false if KNOWN_DECODING_EXCEPTIONS.include?(check_value)
+
+              level = 0
+              iteration = 0
+              until Contrast::Utils::DuckUtils.empty_duck?(Base64.decode64(check_value))
+                iteration += 1
+                # handle cases like 'command' or 'injection' which will check out as encoded regarding the level of
+                # decoding, but will produce ascii escape characters on first iteration, rather than decoded value.
+                level += 1 unless iteration == 2 && ::CGI.escape(check_value) != check_value
+
+                check_value = Base64.decode64(check_value)
+              end
+
+              # if we have more than 2 levels the value is encoded.
+              base64 = level > 1
+
+              # Call base64 statistics:
+              if base64
+                Contrast::Agent::Protect::InputAnalyzer.base64_statistic.match!(input_type)
+              else
+                Contrast::Agent::Protect::InputAnalyzer.base64_statistic.mismatch!(input_type)
+              end
+
+              base64
+            rescue StandardError => e
+              logger.error('Error while checking for base64 encoding',
+                           error: e,
+                           message: e.message,
+                           backtrace: e.backtrace)
+              false
+            end
+
+            # This method will decode the value using Base64.decode64, only if value was encoded.
+            # If value is not encoded, it will return the original value.
+            #
+            # @param value [String] input to decode.
+            # @param input_type [Symbol] input type.
+            # @return [String] decoded or original value.
+            # @raise [StandardError]
+            def cs__decode64 value, input_type
+              return value unless cs__base64?(value, input_type)
+
+              Base64.decode64(value)
+            rescue StandardError => e
+              logger.error('Error while decoding base64', error: e, message: e.message, backtrace: e.backtrace)
+              value
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/protect/rule/input_classification/encoding_rates.rb

@@ -0,0 +1,47 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/agent/protect/rule/input_classification/rates'
+
+module Contrast
+  module Agent
+    module Protect
+      module Rule
+        module InputClassification
+          # This class will hold match information when input classification is being saved in LRU cache.
+          class EncodingRates < Contrast::Agent::Protect::Rule::InputClassification::Rates
+            # @return [Integer]
+            attr_reader :base64_matches
+            # @return [Integer]
+            attr_reader :base64_mismatches
+
+            def initialize input_type
+              super(nil, input_type)
+              @base64_matches = 0
+              @base64_mismatches = 0
+            end
+
+            # Increase the match count for the given rule_id and input.
+            def increase_match_base64
+              @base64_matches += 1
+            end
+
+            def increase_mismatch_base64
+              @base64_mismatches += 1
+            end
+
+            # Returns Agent Telemetry reportable fields.
+            #
+            # @return [Hash]
+            def to_fields
+              {
+                  "#{ to_field_title }.input_base64_matches" => base64_matches,
+                  "#{ to_field_title }.input_base64_mismatches" => base64_mismatches
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/protect/rule/input_classification/extendable.rb

@@ -0,0 +1,80 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/agent/reporting/input_analysis/input_type'
+require 'contrast/agent/reporting/input_analysis/score_level'
+
+module Contrast
+  module Agent
+    module Protect
+      module Rule
+        module InputClassification
+          # Module holding the overwritable methods for input classification. This is used by the
+          # Protect rules to define their own input classification logic. To be Used input_types,
+          # score_level, AgentLib, and InputAnalysisResult must be required.
+          module Extendable
+            THRESHOLD = 90.cs__freeze
+            WORTHWATCHING_THRESHOLD = 10.cs__freeze
+            include Contrast::Agent::Reporting::InputType
+            include Contrast::Agent::Reporting::ScoreLevel
+
+            ################################################################
+            # Methods to be overwritten for each individual Protect rule. #
+            ##############################################################
+
+            # Creates new instance of AgentLib evaluation result with direct call to AgentLib.
+            #
+            # @param rule_id [String] The name of the Protect Rule.
+            # @param input_type [Contrast::Agent::Reporting::InputType] The type of the user input.
+            # @param value [String] the value of the input.
+            # @return [Contrast::AgentLib::EvalResult, nil] the result of the input evaluation.
+            def build_input_eval rule_id, input_type, value
+              Contrast::AGENT_LIB.eval_input(value,
+                                             Contrast::Agent::Protect::Rule::InputClassification::Base.
+                                                convert_input_type(input_type),
+                                             Contrast::AGENT_LIB.rule_set[rule_id],
+                                             Contrast::AGENT_LIB.eval_option[:PREFER_WORTH_WATCHING])
+            end
+
+            # Creates specific result from the AgentLib evaluation.
+            #
+            # @param rule_id [String] The name of the Protect Rule.
+            # @param input_type [Contrast::Agent::Reporting::InputType] The type of the user input.
+            # @param value [String the value of the input.
+            # @param request [Contrast::Agent::Request] the current request context.
+            # @param input_eval [Contrast::AgentLib::EvalResult] the result of the input evaluation.
+            # @return [Contrast::Agent::Reporting::InputAnalysisResult, nil] the result of the input analysis.
+            def build_ia_result rule_id, input_type, value, request, input_eval
+              ia_result = new_ia_result(rule_id, input_type, request.path, value)
+              score = input_eval&.score || 0
+              if score >= WORTHWATCHING_THRESHOLD
+                ia_result.score_level = WORTHWATCHING
+                ia_result.ids << self::WORTHWATCHING_MATCH
+              else
+                ia_result.score_level = IGNORE
+              end
+              ia_result
+            end
+
+            # Creates new isntance of InputAnalysisResult with basic info.
+            #
+            # @param rule_id [String] The name of the Protect Rule.
+            # @param input_type [Contrast::Agent::Reporting::InputType] The type of the user input.
+            # @param value [String, Array<String>] the value of the input.
+            # @param path [String] the path of the current request context.
+            #
+            # @return res [Contrast::Agent::Reporting::InputAnalysisResult]
+            def new_ia_result rule_id, input_type, path, value = nil
+              res = Contrast::Agent::Reporting::InputAnalysisResult.new
+              res.rule_id = rule_id
+              res.input_type = input_type
+              res.path = path
+              res.value = value
+              res
+            end
+          end
+        end
+      end
+    end
+  end
+end