contrast-agent 3.8.4

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

@@ -0,0 +1,300 @@
+# Copyright (c) 2020 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+cs__scoped_require 'contrast/components/interface'
+
+module Contrast
+  module Agent
+    module Protect
+      module Rule
+        # 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
+        class Base
+          include Contrast::Components::Interface
+
+          access_component :logging, :analysis, :settings
+
+          UNKNOWN_USER_INPUT = Contrast::Api::Dtm::UserInput.new.tap do |user_input|
+            user_input.input_type = :UNKNOWN
+          end.cs__freeze
+
+          BLOCKING_MODES = Set.new(%i[BLOCK BLOCK_AT_PERIMETER]).cs__freeze
+          PREFILTER_MODES = Set.new(%i[BLOCK_AT_PERIMETER]).cs__freeze
+          POSTFILTER_MODES = Set.new(%i[BLOCK PERMIT MONITOR]).cs__freeze
+          STACK_COLLECTION_RESULTS = Set.new(%i[BLOCKED MONITORED]).cs__freeze
+
+          attr_reader :mode
+
+          def initialize default_mode = :NO_ACTION
+            SETTINGS.protect_rules[name] = self
+            @mode = mode_from_settings || default_mode
+          end
+
+          # Should return the name as it is known to Teamserver; defaults to class
+          def name
+            cs__class.name
+          end
+
+          OFF = 'off'
+
+          def enabled?
+            # 1. it is not enabled because protect is not enabled
+            return false unless PROTECT.enabled?
+
+            rule_configs = Contrast::Agent::FeatureState.instance.protect_rule_config
+            unless rule_configs.nil?
+              # 2. it is not enabled because it is in the list of disabled protect rules
+              disabled_rules = rule_configs.disabled_rules
+              return false if disabled_rules&.include?(name)
+
+              # 3. it is not enabled because it has been turned "off" explicitly
+              rule_config = rule_configs.send(name)
+
+              return rule_config.mode != OFF unless rule_config.mode.nil?
+            end
+
+            # 4. it is not enabled because it's mode is :NO_ACTION
+            @mode != :NO_ACTION
+          end
+
+          # this rule is excluded if any of the given exclusions have a protection rule that matches this rule name
+          def excluded? exclusions
+            Array(exclusions).any? do |ex|
+              ex.protection_rule?(name)
+            end
+          end
+
+          def infilter? _context
+            false
+          end
+
+          # return false for rules that modify or inspect the response body
+          # during postfilter
+          #
+          # @return [Boolean] if the rule can safely be evaluated in streaming
+          #   requests
+          def stream_safe?
+            true
+          end
+
+          # Actions required for the rules that have to happen before the
+          # application has completed its processing of the request.
+          #
+          # For most rules, these actions are performed within the analysis
+          # engine and communicated as an input analysis result. Those that
+          # require specific action need to provide that action.
+          #
+          # @param _context [Contrast::Agent::RequestContext] the context for
+          #   the current request
+          def prefilter _context; end
+
+          # This should only ever be called directly from patched code and will
+          # have a different implementation based on the rule. As such, there
+          # is not parent implementation.
+          #
+          # @param _context [Contrast::Agent::RequestContext] the context for
+          #   the current request
+          # @param _match_string [String] the input that violated the rule and
+          #   matched the attack detection logic
+          # @param _kwargs [Hash] key-value pairs used by the rule to build a
+          #   report.
+          def infilter _context, _match_string, **_kwargs; end
+
+          # Actions required for the rules that have to happen after the
+          # application has completed its processing of the request.
+          #
+          # Any implementation here needs to account for the fact that
+          # responses may be streaming and, as such, transformations of the
+          # response itself may not be permissible.
+          #
+          # @param _context [Contrast::Agent::RequestContext] the context for
+          #    the current request
+          def postfilter _context; end
+
+          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)
+            append_sample(context, ia_result, result, candidate_string, **kwargs)
+
+            result
+          end
+
+          def build_attack_without_match context, ia_result, result, **kwargs
+            result ||= build_attack_result(context)
+            update_perimeter_attack_response(context, ia_result, result)
+            append_sample(context, ia_result, result, nil, **kwargs)
+
+            result
+          end
+
+          def append_to_activity context, result
+            context.activity.results << result if result
+          end
+
+          protected
+
+          def build_details _input_string, _ia_result
+            raise Contrast::InternalException, "Rule #{ name } did not implement build_details"
+          end
+
+          def mode_from_settings
+            SETTINGS.protect_rule_mode(name).tap do |mode|
+              logger.debug("rule #{ name } mode = #{ mode }")
+            end
+          end
+
+          def blocked?
+            enabled? && BLOCKING_MODES.include?(mode)
+          end
+
+          # Determine if there's an exclusion that matches an item in the call
+          # stack
+          #
+          # @return [Boolean] if an exclusion was applicable to this request
+          #   for this rule
+          def protect_excluded_by_code?
+            exclusions = Contrast::Agent::FeatureState.instance.code_exclusions
+            return false unless exclusions
+
+            for_rule = exclusions.select { |ex| ex.protection_rule?(name) }
+            return false if for_rule.empty?
+
+            stack = caller_locations
+            for_rule.any? { |ex| ex.match_code?(stack) }
+          end
+
+          # By default, rules do not have to find attackers as they do not have
+          # Input Analysis. Any attack for the standard rule will be evaluated
+          # at execution time. As such, those rules are expected to implement
+          # this custom behavior
+          #
+          # @param _context [Contrast::Agent::RequestContext] the context for
+          #   the current request
+          # @param _potential_attack_string [String] the input that may violate
+          #   the rule and matched the attack detection logic
+          # @param _kwargs [Hash] key-value pairs used by the rule to build a
+          #   report.
+          def find_attacker _context, _potential_attack_string, **_kwargs
+            raise Contrast::InternalException, "Rule #{ name } did not implement find_attack"
+          end
+
+          def update_successful_attack_response context, ia_result, result, attack_string = nil
+            if mode == :MONITOR
+              result.response = :MONITORED
+            elsif mode == :BLOCK
+              result.response = :BLOCKED
+            end
+
+            ia_result.attack_count = ia_result.attack_count + 1 if ia_result
+            log_rule_matched(context, ia_result, result.response, attack_string)
+
+            result
+          end
+
+          def update_perimeter_attack_response context, ia_result, result
+            if mode == :BLOCK_AT_PERIMETER
+              result.response = :BLOCKED_AT_PERIMETER
+              log_rule_matched(context, ia_result, result.response)
+            elsif ia_result.nil? || ia_result.attack_count.zero?
+              result.response = :PROBED
+              log_rule_probed(context, ia_result)
+            end
+
+            result
+          end
+
+          def build_attack_result _context
+            result = Contrast::Api::Dtm::AttackResult.new
+            result.rule_id = name
+            result
+          end
+
+          def append_stack sample, result
+            return unless sample
+            return unless STACK_COLLECTION_RESULTS.include?(result&.response)
+
+            stack = Contrast::Utils::StackTraceUtils.build(ignore: true, class_lookup: true, depth: 50)
+            return unless stack
+
+            sample.stack_trace_elements += stack
+          end
+
+          def append_sample context, ia_result, result, candidate_string, **kwargs
+            return nil unless result
+
+            sample = build_sample(context, ia_result, candidate_string, **kwargs)
+            return nil unless sample
+
+            append_stack(sample, result)
+
+            result.samples << sample
+          end
+
+          # Override if rule can make use of the candidate string or kwargs to
+          # build rasp rule sample.
+          def build_sample context, ia_result, _candidate_string, **_kwargs
+            build_base_sample(context, ia_result)
+          end
+
+          def build_user_input ia_result
+            return UNKNOWN_USER_INPUT unless ia_result
+
+            input = Contrast::Api::Dtm::UserInput.new
+            input.input_type = ia_result.input_type.to_sym
+            input.matcher_ids = ia_result.ids
+            input.path = ia_result.path.to_s
+            input.key = ia_result.key.to_s
+            input.value = ia_result.value.to_s
+            input
+          end
+
+          def build_base_sample context, ia_result
+            sample = Contrast::Api::Dtm::RaspRuleSample.new
+            sample.timestamp_ms = context.timer.start_ms
+            sample.user_input = build_user_input(ia_result)
+            sample.user_input.document_type = context.request.dtm.document_type unless sample.user_input.cs__frozen?
+            sample
+          end
+
+          def log_rule_matched _context, ia_result, response, _matched_string = nil
+            return unless ia_result
+
+            # Log to agent logger
+            message = if ia_result
+                        log_msg(ia_result, true)
+                      else
+                        "An effective attack was detected against #{ name }."
+                      end
+
+            logger.debug([response, message].join)
+          end
+
+          private
+
+          def log_rule_probed _context, ia_result
+            message = if ia_result
+                        log_msg(ia_result, false)
+                      else
+                        "An unsuccessful attack was detected against #{ name }"
+                      end
+
+            logger.debug(message)
+          end
+
+          def log_msg ia_result, matched
+            key = ia_result.key ? ia_result.key.to_s + ' ' : ''
+            val = ia_result.value.to_s
+            typ = ia_result.input_type.to_s
+            if matched
+              "The #{ typ } #{ key } had a value that successfully exploited #{ name } - #{ val }."
+            else
+              "The #{ typ } #{ key } had a value that matched a signature for, but did not successfully exploit, #{ name } - #{ val }."
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,88 @@
+# Copyright (c) 2020 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+module Contrast
+  module Agent
+    module Protect
+      module Rule
+        # Encapsulate common code for protect rules that do their
+        # input analysis on Speedracer rather in ruby code
+        class BaseService < Contrast::Agent::Protect::Rule::Base
+          def name
+            'base-service'
+          end
+
+          def block_message
+            'Contrast Security Protect Rule Triggered. Response blocked.'
+          end
+
+          def infilter? context
+            return false unless context&.speedracer_input_analysis&.results
+            return false unless enabled?
+            return false if protect_excluded_by_code?
+
+            true
+          end
+
+          # Override for rules that need the response
+          # Currently postfilter can be applied to streamed responses,
+          # if any logic within postfilter changes to modify the response
+          # streamed responses will break
+          def postfilter context
+            return unless enabled? && POSTFILTER_MODES.include?(mode)
+            return if mode == :NO_ACTION || mode == :PERMIT
+
+            result = find_postfilter_attacker(context, nil)
+            return unless result&.samples&.any?
+
+            append_to_activity(context, result)
+            return unless result.response == :BLOCKED
+
+            raise Contrast::SecurityException.new(self, "#{ name } triggered in postfilter. Response blocked.")
+          end
+
+          protected
+
+          def gather_ia_results context
+            context.speedracer_input_analysis.results.select do |ia_result|
+              ia_result.rule_id == name
+            end
+          end
+
+          def find_attacker context, potential_attack_string, **kwargs
+            ia_results = gather_ia_results(context)
+            find_attacker_with_results(context, potential_attack_string, ia_results, **kwargs)
+          end
+
+          # Allows for the InputAnalysis from service to be extracted early
+          def find_attacker_with_results context, potential_attack_string, ia_results, **kwargs
+            logger.debug("checking: #{ name } vectors=#{ ia_results.length } in '#{ potential_attack_string }'")
+
+            result = nil
+            ia_results.each do |ia_result|
+              if potential_attack_string
+                idx = potential_attack_string.index(ia_result.value)
+                next unless idx
+
+                result = build_attack_with_match(context, ia_result, result, potential_attack_string, **kwargs)
+              else
+                result = build_attack_without_match(context, ia_result, result, **kwargs)
+              end
+            end
+            result
+          end
+
+          private
+
+          def find_postfilter_attacker context, potential_attack_string, **kwargs
+            ia_results = gather_ia_results(context)
+            ia_results.select! do |ia_result|
+              ia_result.score_level == :DEFINITEATTACK
+            end
+            find_attacker_with_results(context, potential_attack_string, ia_results, **kwargs)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,156 @@
+# Copyright (c) 2020 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+cs__scoped_require 'contrast/utils/stack_trace_utils'
+cs__scoped_require 'contrast/utils/object_share'
+cs__scoped_require 'contrast/components/interface'
+
+module Contrast
+  module Agent
+    module Protect
+      module Rule
+        # The Ruby implementation of the Protect Command Injection rule.
+        class CmdInjection < Contrast::Agent::Protect::Rule::BaseService
+          include Contrast::Components::Interface
+          access_component :logging, :contrast_service
+
+          NAME = 'cmd-injection'
+          CHAINED_COMMAND_CHARS = /[;&|<>]/.cs__freeze
+
+          def name
+            NAME
+          end
+
+          def infilter context, classname, method, command
+            return nil unless infilter?(context)
+
+            ia_results = gather_ia_results(context)
+            return nil if ia_results.empty?
+
+            if Contrast::Agent::FeatureState.instance.in_new_process?
+              logger.debug('Running cmd-injection infilter within new process - creating new context')
+              context = Contrast::Agent::RequestContext.new(context.request.rack_request)
+              Contrast::Agent::REQUEST_TRACKER.update_current_context(context)
+            end
+
+            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
+
+            append_to_activity(context, result)
+            if %I[exec `].include?(method)
+              # TODO: RUBY-737
+              # Kernel#exec replaces the current process and does not go through at_exit hooks
+              # Kernel#` runs as a subshell - messages appended here do not seem to be present in the original process?
+              CONTRAST_SERVICE.send_message(context.activity)
+            end
+
+            return unless blocked?
+
+            raise Contrast::SecurityException.new(
+                self,
+                "Command Injection rule triggered. Call to #{ classname }.#{ method } blocked.")
+          end
+
+          def build_attack_with_match context, input_analysis_result, result, candidate_string, **kwargs
+            return result if mode == :NO_ACTION || mode == :PERMIT
+
+            result ||= build_attack_result(context)
+            update_successful_attack_response(context, input_analysis_result, result, candidate_string)
+            append_sample(context, input_analysis_result, result, candidate_string, **kwargs)
+            result
+          end
+
+          protected
+
+          # Because results are not necessarily on the context across
+          # processes; extract early and pass into the method
+          def find_attacker_with_results context, potential_attack_string, ia_results, **kwargs
+            logger.debug("checking: #{ name } in '#{ potential_attack_string }'")
+            result = super(context, potential_attack_string, ia_results, **kwargs)
+            if result.nil? && potential_attack_string
+              result = find_probable_attacker(
+                  context,
+                  potential_attack_string,
+                  ia_results,
+                  **kwargs)
+            end
+            result
+          end
+
+          # Build a subclass of the RaspRuleSample using the query string and the
+          # evaluation
+          def build_sample context, input_analysis_result, candidate_string, **_kwargs
+            sample = build_base_sample(context, input_analysis_result)
+            sample.cmdi = Contrast::Api::Dtm::CmdInjectionDetails.new
+
+            command = candidate_string || input_analysis_result.value
+            command = Contrast::Utils::StringUtils.protobuf_safe_string(command)
+            sample.cmdi.command = command
+
+            # This is a special case where the user input is UNKNOWN_USER_INPUT but
+            # we want to send the attack value
+            if input_analysis_result.nil?
+              ui = Contrast::Api::Dtm::UserInput.new
+              ui.input_type = :UNKNOWN
+              ui.value = command
+              sample.user_input = ui
+            end
+
+            sample
+          end
+
+          private
+
+          def report_command_execution context, command, **kwargs
+            return unless report_any_command_execution?
+            return nil if protect_excluded_by_code?
+
+            build_attack_with_match(context, nil, nil, command, **kwargs)
+          end
+
+          def find_probable_attacker context, potential_attack_string, ia_results, **kwargs
+            result = nil
+            if chained_command?(potential_attack_string) # this is probably an attack
+              most_likely = nil
+              ia_results.each do |input_analysis_result|
+                next unless chained_command?(input_analysis_result.value)
+
+                most_likely = input_analysis_result
+                break
+              end
+            end
+            return result unless most_likely
+
+            result ||= build_attack_with_match(
+                context,
+                most_likely,
+                result,
+                potential_attack_string,
+                **kwargs)
+            return nil if result.nil?
+
+            log_rule_matched(context, most_likely, mode, potential_attack_string)
+            result
+          end
+
+          def chained_command? command
+            return true if CHAINED_COMMAND_CHARS.match(command)
+
+            false
+          end
+
+          # Part of the Hardening for Command Injection detection is the
+          # ability to detect and prevent any command execution from within the
+          # application. This check determines if that hardening has been
+          # enabled.
+          # @return [Boolean] if the agent should report all command
+          #   executions.
+          def report_any_command_execution?
+            Contrast::Agent::FeatureState.instance.report_any_command_execution?
+          end
+        end
+      end
+    end
+  end
+end