contrast-agent 7.1.0 → 7.3.0

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

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

@@ -0,0 +1,198 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/utils/lru_cache'
+require 'contrast/utils/duck_utils'
+require 'contrast/agent/protect/rule/input_classification/cached_result'
+require 'contrast/agent/protect/rule/input_classification/statistics'
+require 'contrast/agent/protect/rule/input_classification/utils'
+
+module Contrast
+  module Agent
+    module Protect
+      module Rule
+        module InputClassification
+          # This Class with store the input classification results for a given user input.
+          # Among the most used inputs are the headers values for session_id and path values.
+          class LRUCache < Contrast::Utils::LRUCache
+            include Contrast::Components::Logger::InstanceMethods
+            include Contrast::Agent::Protect::Rule::InputClassification::Utils
+
+            # Protect rules will always be fixed number, on other hand the number of inputs will grow,
+            # we need to limit the number of inputs to be cached.
+            RESULTS_CAPACITY = 20
+
+            private :[], :[]=
+
+            # Initialize the LRU Cache.
+            #
+            # @param capacity [Integer] the maximum number of elements to store in the cache. For this
+            # instance it will never reach outside of the number of supported Protect rules.
+            def initialize capacity = 10
+              super(capacity)
+            end
+
+            def mutex
+              @_mutex ||= Mutex.new
+            end
+
+            def with_mutex &block
+              return_type = mutex.synchronize(&block)
+            ensure
+              return_type
+            end
+
+            # Capacity of the statistics will always be the number of rule_id Protect supports.
+            #
+            # @return [Contrast::Agent::Protect::Rule::InputClassification::Statistics]
+            def statistics
+              @_statistics ||= Contrast::Agent::Protect::Rule::InputClassification::Statistics.new
+            end
+
+            # Clear the cache and statistics.
+            def clear
+              with_mutex { @cache.clear }
+              clear_statistics
+            end
+
+            # Clear only the statistics.
+            def clear_statistics
+              with_mutex { statistics.send(:clear) }
+            end
+
+            # Check if the cache is empty.
+            #
+            # @return [Boolean]
+            def empty?
+              Contrast::Utils::DuckUtils.empty_duck?(@cache)
+            end
+
+            # Check if the input is cached and returns it if so and record the statistics for the required input.
+            #
+            # @param rule_id [String] the Protect rule name.
+            # @param input [String] the user input.
+            # @param input_type [Symbol] Type of the input
+            # @param request [Contrast::Agent::Request] the current request.
+            # @return [Contrast::Agent::Protect::InputClassification::CachedResult, nil]
+            def lookout rule_id, input, input_type, request
+              with_mutex { _loockout(rule_id, input, input_type, request) }
+            end
+
+            # Save the input classification result for a given user input.
+            #
+            # @param rule_id [String] the Protect rule name.
+            # @param result [Contrast::Agent::Reporting::InputAnalysisResult]
+            # @param request [Contrast::Agent::Request] the current request.
+            # @return result [Contrast::Agent::Protect::InputClassification::CachedResult, nil]
+            def save rule_id, result, request
+              with_mutex { _save(rule_id, result, request) }
+            end
+
+            private
+
+            # Check if the input is cached and returns it if so and record the statistics for the required input.
+            #
+            # @param rule_id [String] the Protect rule name.
+            # @param input [String] the user input.
+            # @param input_type [Symbol] Type of the input
+            # @param request [Contrast::Agent::Request] the current request.
+            # @return [Contrast::Agent::Protect::InputClassification::CachedResult, nil]
+            def _loockout rule_id, input, input_type, request
+              cached = retrieve(rule_id, input, input_type)
+              if cached.cs__is_a?(Contrast::Agent::Protect::InputClassification::CachedResult)
+                # Telemetry event matched.
+                statistics.match!(rule_id, cached, request)
+                cached
+              else
+                # Telemetry event mismatched.
+                statistics.mismatch!(rule_id, input_type)
+                nil
+              end
+            rescue StandardError => e
+              logger.error("[IA_LRU_Cache] Error while looking for #{ input_type } for #{ rule_id }", error: e)
+              nil
+            end
+
+            # Save the input classification result for a given user input.
+            #
+            # @param rule_id [String] the Protect rule name.
+            # @param result [Contrast::Agent::Reporting::InputAnalysisResult]
+            # @param request [Contrast::Agent::Request] the current request.
+            # @return result [Contrast::Agent::Protect::InputClassification::CachedResult, nil]
+            def _save rule_id, result, request
+              cached_result = Contrast::Agent::Protect::InputClassification::CachedResult.new(result, request.__id__)
+              new_entry = safe_extract(push(rule_id, cached_result)) unless cached_result.empty?
+              statistics.push(rule_id, cached_result)
+
+              new_entry
+            rescue StandardError => e
+              logger.error("[IA_LRU_Cache] Error while saving #{ result } for #{ rule_id }",
+                           error: e,
+                           stack_trace: e.backtrace)
+            end
+
+            # @param rule_id [String] the Protect rule name.
+            # @param result [Contrast::Agent::Protect::InputClassification::CachedResult, nil]
+            # @return [Array<Contrast::Agent::Protect::InputClassification::CachedResult>, nil]
+            def push rule_id, result
+              return unless result.cs__is_a?(Contrast::Agent::Protect::InputClassification::CachedResult)
+              return @cache[rule_id] = [result] unless key?(rule_id)
+
+              cached_results = @cache[rule_id]
+              cached_results.shift if cached_results.length >= RESULTS_CAPACITY
+              return @cache[rule_id] << result unless already_saved?(result, rule_id)
+
+              nil
+            end
+
+            # Returns the cached result for a given user input. If the input is not cached, it will return nil.
+            # If the input is cached and key is needed, it will return the cached result and the key and key_type.
+            #
+            # @param rule_id [String] the Protect rule name.
+            # @param input [String] the user input.
+            # @param input_type [Symbol] Type of the input
+            # @return [Contrast::Agent::Protect::InputClassification::CachedResult, nil]
+            def retrieve rule_id, input, input_type
+              # Check to see if cache exist if not just return the keys info.
+              return unless key?(rule_id)
+
+              safe_extract(query_fetch(rule_id, input, input_type))
+            end
+
+            # returns true on first input already saved with the same input.
+            # We will know if the key is needed from the result itself.
+            #
+            # @param cached_result [Contrast::Agent::Protect::InputClassification::CachedResult, nil]
+            # @param rule_id [String]
+            # @return [Boolean]
+            def already_saved? cached_result, rule_id
+              return false unless cached_result.cs__is_a?(Contrast::Agent::Protect::InputClassification::CachedResult)
+
+              @cache[rule_id].any? do |entry|
+                if entry.result.value == cached_result.result.value &&
+                      entry.result.input_type == cached_result.result.input_type
+
+                  return true
+                end
+              end
+              false
+            end
+
+            # Returns first match for the required input.
+            #
+            # @param rule_id [String] the Protect rule name.
+            # @param input [String] the user input.
+            # @param input_type [Symbol] Type of the input
+            # @return result [Contrast::Agent::Protect::InputClassification::CachedResult, nil]
+            def query_fetch rule_id, input, input_type
+              @cache[rule_id].map do |cached_result|
+                return cached_result if cached_result.result.value == input &&
+                    cached_result.result.input_type == input_type
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# 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 MatchRates < Rates
+            # @return [Integer]
+            attr_reader :input_matches
+            # @return [Integer]
+            attr_reader :input_mismatches
+            # @return [Integer]
+            attr_reader :request_matches
+            # @return [String]
+            attr_reader :score_level
+
+            # @param rule_id [String]
+            # @param input_type [Symbol, nil]
+            # @param score_level [String]
+            def initialize rule_id, input_type, score_level
+              super(rule_id, input_type)
+              @input_matches = 0
+              @request_matches = 0
+              @input_mismatches = 0
+              @score_level = score_level if Contrast::Agent::Reporting::ScoreLevel.to_a.include?(score_level)
+            end
+
+            # Increase the match count for the given rule_id and input.
+            def increase_match_for_input
+              @input_matches += 1
+            end
+
+            def increase_mismatch_for_input
+              @input_mismatches += 1
+            end
+
+            # increase the missmatch count for the given rule_id and input.
+            def increase_match_for_request
+              @request_matches += 1
+            end
+
+            def empty?
+              super && @input_matches.zero? && @input_mismatches.zero? && @request_matches.zero?
+            end
+
+            # Returns Agent Telemetry reportable fields.
+            #
+            # @return [Hash]
+            def to_fields
+              {
+                  "#{ to_field_title }.input_matches" => input_matches,
+                  "#{ to_field_title }.input_mismatches" => input_mismatches,
+                  "#{ to_field_title }.request_matches" => request_matches
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# 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/utils/duck_utils'
+
+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 Rates
+            # Titles:
+            FIELD_NAME = 'ia'
+            TEST_NAME = '_t'
+
+            # @return [String]
+            attr_reader :rule_id
+            # @return [Symbol, nil]
+            attr_reader :input_type
+
+            def initialize rule_id, input_type
+              @rule_id = rule_id if rule_id
+              @input_type = input_type if Contrast::Agent::Reporting::InputType.to_a.include?(input_type)
+            end
+
+            def empty?
+              Contrast::Utils::DuckUtils.empty_duck?(@input_type)
+            end
+
+            # Override this method to return the required Agent Telemetry fields.
+            # @return [Hash]
+            def to_fields
+              {}
+            end
+
+            private
+
+            # @return [String]
+            def to_field_title
+              if (ENV['CONTRAST_AGENT_TELEMETRY_TEST'] = '1')
+                TEST_NAME
+              else
+                FIELD_NAME
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,115 @@
+# 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/utils'
+require 'contrast/agent/protect/rule/input_classification/match_rates'
+require 'contrast/agent/telemetry/input_analysis_cache_event'
+require 'contrast/agent/reporting/input_analysis/score_level'
+require 'contrast/agent/reporting/input_analysis/input_type'
+
+module Contrast
+  module Agent
+    module Protect
+      module Rule
+        module InputClassification
+          # This class will hold match information for each rule when input classification is being saved in LRU cache.
+          class Statistics
+            include Contrast::Agent::Protect::Rule::InputClassification::Utils
+            include Contrast::Components::Logger::InstanceMethods
+
+            attr_reader :data
+
+            # Protect rules will always be fixed number, on other hand the number of inputs will grow,
+            # we need to limit the number of inputs to be cached.
+            CAPACITY = 30
+
+            def initialize
+              @data = {}
+            end
+
+            # This method will handle the statistics for the input match
+            #
+            # @param rule_id [String] the Protect rule name.
+            # @param cached [Contrast::Agent::Protect::InputClassification::CachedResult]
+            # @param request [Contrast::Agent::Request] the current request.
+            def match! rule_id, cached, request
+              return unless Contrast::Agent::Telemetry::Base.enabled?
+
+              push(rule_id, cached)
+              fetch(rule_id, cached.result.input_type)&.increase_match_for_input
+              return unless cached.request_id == request.__id__
+
+              fetch(rule_id, cached.result.input_type)&.increase_match_for_request
+            end
+
+            # This method will handle the statistics for the input mismatch.
+            # Skip if this is the called with empty cache since it's not fair.
+            #
+            # @param rule_id [String] the Protect rule name.
+            # @param input_type [Symbol] Type of the input
+            def mismatch! rule_id, input_type
+              return unless Contrast::Agent::Telemetry::Base.enabled?
+              return if Contrast::Agent::Protect::InputAnalyzer.lru_cache.empty?
+
+              fetch(rule_id, input_type)&.increase_mismatch_for_input
+            end
+
+            # @return [Array<Contrast::Agent::Telemetry::InputAnalysisCacheEvent>] the events to be sent.
+            def to_events
+              events = []
+              data.each do |_rule_id, match_rates|
+                match_rates.each do |match_rate|
+                  event = Contrast::Agent::Telemetry::InputAnalysisCacheEvent.new(match_rate.rule_id, match_rate)
+                  next if event.empty?
+
+                  events << event
+                end
+              end
+              events
+            rescue StandardError => e
+              logger.error("[IA_LRU_Cache] Error while creating events: #{ e }", stacktrace: e.backtrace)
+              []
+            end
+
+            # Creates new statisctics for protect rule.
+            #
+            # @param rule_id [String] the Protect rule name.
+            # @param cached [Contrast::Agent::Protect::InputClassification::CachedResult]
+            def push rule_id, cached
+              new_entry = Contrast::Agent::Protect::Rule::InputClassification::MatchRates.
+                  new(rule_id, cached.result.input_type, cached.result.score_level)
+
+              @data[rule_id] = [] if Contrast::Utils::DuckUtils.empty_duck?(@data[rule_id])
+              @data[rule_id].shift if @data[rule_id].length >= CAPACITY
+              @data[rule_id] << new_entry unless saved?(rule_id, cached)
+            end
+
+            # Get the statistics for the protect rule.
+            #
+            # @param rule_id [String] the Protect rule name.
+            # @param input_type [Symbol] Type of the input
+            def fetch rule_id, input_type
+              safe_extract(@data[rule_id]&.select { |e| e.input_type == input_type })
+            end
+
+            private
+
+            # Checks if the rate is saved for the input.
+            #
+            # @param rule_id [String] the Protect rule name.
+            # @param new_entry [Contrast::Agent::Protect::InputClassification::CachedResult]
+            def saved? rule_id, new_entry
+              !fetch(rule_id, new_entry&.result&.input_type).nil?
+            end
+
+            # Call this method from the LRU Cache to get the statistics for a given rule_id, so it could be
+            # thread safe.
+            def clear
+              @data.clear
+            end
+          end
+        end
+      end
+    end
+  end
+end