contrast-agent 3.9.1 → 6.15.3

data/lib/contrast/logger/format.rb

@@ -0,0 +1,61 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'ougai'
+require 'contrast/utils/object_share'
+require 'contrast/utils/thread_tracker'
+
+module Contrast
+  module Logger
+    # Our format for the Ougai logger allowing for custom log format that
+    # extends the behavior of the default Ougai logger
+    class Format < Ougai::Formatters::Bunyan
+      NO_REQUEST_HASH = { request_id: -1 }.cs__freeze
+      LOG_TRACKER = Contrast::Utils::ThreadTracker.new
+      # Our override of the _call method to add in the extra data that we want,
+      # based on
+      # https://github.com/tilfin/ougai/blob/1fe4fc2587be8eabc47d36dc57ee2814f8a0162b/lib/ougai/formatters/bunyan.rb#L26
+      # By default, it adds:
+      #   name: progname || @app_name,
+      #   hostname: @hostname,
+      #   pid: $$,
+      #   level: to_level(severity),
+      #   time: time,
+      #   v: 0
+      # and we add the fields from #format_hash
+      def _call severity, time, progname, data
+        super(severity,
+              time,
+              progname,
+              format_hash.merge(data)
+        )
+      end
+
+      private
+
+      # The extra values to add to the Bunyan hash.
+      # @return [Hash{Symbol => Object}] the extra data to log
+      def format_hash
+        thread_hash.merge(request_hash)
+      end
+
+      # Because this is unique per thread, we'll create it once and then store
+      # it, rather than create a new hash on every log call during the request.
+      def thread_hash
+        hash = LOG_TRACKER.get(:logging_hash)
+        unless hash
+          hash = { thread_id: Thread.current.object_id }
+          LOG_TRACKER.set(:logging_hash, hash)
+        end
+        hash
+      end
+
+      def request_hash
+        @request_tracker_defined ||= defined?(Contrast::Agent) && defined?(Contrast::Agent::REQUEST_TRACKER)
+        return NO_REQUEST_HASH unless @request_tracker_defined
+
+        Contrast::Agent::REQUEST_TRACKER&.current&.logging_hash || NO_REQUEST_HASH
+      end
+    end
+  end
+end

data/lib/contrast/logger/log.rb

@@ -0,0 +1,90 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'logger'
+require 'ougai'
+require 'singleton'
+
+require 'contrast/extension/module'
+require 'contrast/logger/application'
+require 'contrast/logger/format'
+require 'contrast/logger/request'
+require 'contrast/logger/time'
+require 'contrast/components/config'
+require 'contrast/utils/log_utils'
+
+module Contrast
+  # Used as a wrapper around our logging. The module option specifically adds in a new method for error that raises the
+  # logged exception, used in testing so that we can see if anything unexpected happens without it being swallowed
+  # while still providing safe options for customers.
+  module Logger
+    # For development set following env var to raise logged exceptions instead of just logging.
+    if ENV['CONTRAST__AGENT__RUBY_MORE_COWBELL']
+      Ougai::Logger.class_eval do
+        alias_method :cs__error, :error
+        alias_method :cs__warn, :warn
+
+        def error *args, **kwargs
+          if kwargs.empty?
+            cs__error(*args)
+          else
+            cs__error(*args, **kwargs)
+          end
+          args.each { |arg| raise(arg) if arg && arg.cs__class < Exception }
+        end
+      end
+    end
+
+    # This class functions to serve as a wrapper around our logging, as we need to be able to dynamically update
+    # level based on updates to TeamServer.
+    class Log
+      include Singleton
+      include Contrast::Utils::LogUtils
+
+      attr_reader :previous_path, :previous_level
+
+      def initialize
+        update
+      end
+
+      # Given new settings from TeamServer, update our logging to use the new file and level, assuming they weren't
+      # set by local configuration.
+      #
+      # @param log_file [String] the file to which to log, as provided by TeamServer settings
+      # @param log_level [String] the level at which to log, as provided by TeamServer settings
+      def update log_file = nil, log_level = nil
+        current_path        = find_valid_path(log_file)
+        current_level_const = find_valid_level(log_level)
+
+        path_change = current_path != previous_path
+        level_change = current_level_const != previous_level
+
+        # don't needlessly recreate logger
+        return if @_logger && !(path_change || level_change)
+
+        @previous_path  = current_path
+        @previous_level = current_level_const
+
+        progname = Contrast::CONFIG.agent.logger.progname
+        @_logger = build(path: current_path, level_const: current_level_const, progname: progname)
+        # If we're logging to a new path, then let's start it w/ our helpful
+        # data gathering messages
+        log_update if path_change
+      rescue StandardError => e
+        if logger
+          logger.error('Unable to process update to LoggerManager.', e)
+        else
+          puts('Unable to process update to LoggerManager.')
+          raise(e) if ENV['CONTRAST__AGENT__RUBY_MORE_COWBELL']
+
+          puts(e.message)
+          puts(e.backtrace.join("\n"))
+        end
+      end
+
+      def logger
+        @_logger
+      end
+    end
+  end
+end

data/lib/contrast/logger/request.rb

@@ -0,0 +1,25 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/utils/timer'
+
+module Contrast
+  module Logger
+    # Our decorator for the Ougai logger allowing for the logging of the
+    # request lifecycle, used to provide context during troubleshooting.
+    module Request
+      # Utility method to log the start of a request
+      def request_start
+        debug('Beginning request analysis')
+      end
+
+      # Utility method to log the end of a request, including the time it took
+      # for that request to be processed.
+      def request_end
+        context = Contrast::Agent::REQUEST_TRACKER.current
+        elapsed_time = context ? (Contrast::Utils::Timer.now_ms - context.timer.start_ms) : -1
+        debug('Ending request analysis', elapsed_time_ms: elapsed_time)
+      end
+    end
+  end
+end

data/lib/contrast/logger/time.rb

@@ -0,0 +1,57 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+module Contrast
+  module Logger
+    # Our decorator for the Ougai logger allowing for timing and with_level
+    # methods.
+    module Time
+      # Log the message at the given level.
+      #
+      # @param level [String] the name of the method to use. Should be one of trace, debug, info, warn, error
+      # @param message [String] the message to log
+      def with_level level, message
+        send(level.to_sym, message)
+      end
+
+      # Log, at the debug level, the action with a message including the time it took for the wrapped function to
+      # complete. If not logging to debug, simply yield the given block.
+      #
+      # @param msgs [Array<Object>] the arguments to pass to the logger. msgs[0] will be modified to include the elapsed
+      #   time.
+      # @param block [Block, Proc] the block to execute
+      def debug_with_time *msgs, &block
+        if debug?
+          log_with_time(:debug, *msgs, &block)
+        elsif block
+          yield
+        end
+      end
+
+      # Log, at the trace level, the action with a message including the time it took for the wrapped function to
+      # complete. If not logging to debug, simply yield the given block.
+      #
+      # @param msgs [Array<Object>] the arguments to pass to the logger. msgs[0] will be modified to include the elapsed
+      #   time.
+      # @param block [Block, Proc] the block to execute
+      def trace_with_time *msgs, &block
+        if trace?
+          log_with_time(:trace, *msgs, &block)
+        elsif block
+          yield
+        end
+      end
+
+      private
+
+      def log_with_time level, *msgs
+        a = Contrast::Utils::Timer.now_ms
+        ret = yield if block_given?
+        z = Contrast::Utils::Timer.now_ms
+        msgs[0] = "#{ msgs[0] }: pid=#{ Process.pid }, elapsed=#{ z - a }ms"
+        send(level, *msgs)
+        ret
+      end
+    end
+  end
+end

data/lib/contrast/security_exception.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2020 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
 # frozen_string_literal: true
 
 module Contrast
@@ -8,7 +8,7 @@ module Contrast
   # to be handled by our customer's applications.
   class SecurityException < StandardError
     def initialize rule, message = nil
-      super(message || "Rule #{ rule.name } threw a security exception")
+      super(message || "Rule #{ rule.rule_name } threw a security exception")
     end
   end
 end

data/lib/contrast/tasks/config.rb

@@ -0,0 +1,33 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/config/yaml_file'
+require 'contrast/config/validate'
+
+module Contrast
+  # A Rake task to generate a contrast_security.yaml file with some basic settings
+  module Config
+    extend Rake::DSL
+    # The file create methods are required in the gemspec. Some of the Agent functions are not
+    # available there. To be safe the validate mechanics are extracted in different module.
+    extend Contrast::Config::Validate
+
+    namespace :contrast do
+      namespace :config do
+        desc 'Create a contrast_security.yaml in the applications root directory'
+        task :create do
+          Contrast::Config::YamlFile.create
+        end
+      end
+    end
+
+    namespace :contrast do
+      namespace :config do
+        desc 'Validate the provided Contrast configuration and confirm connectivity'
+        task validate: :environment do
+          validate_file
+        end
+      end
+    end
+  end
+end

data/lib/contrast/utils/assess/event_limit_utils.rb

@@ -0,0 +1,134 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/components/logger'
+require 'contrast/components/assess'
+
+module Contrast
+  module Utils
+    module Assess
+      # EventLimitUtils is used to check and validate the number of source, propagation, or trigger events collected
+      # during the reporting time frame
+      module EventLimitUtils
+        include Contrast::Components::Logger::InstanceMethods
+        # Checks to see if the event limit for the policy type has been met or exceeded
+        # @param policy [Contrast::Agent::Patching::Policy::MethodPolicy,
+        #   Contrast::Agent::Patching::Policy::TriggerNode] method to check for event limit
+        def event_limit? policy
+          return false unless (context = Contrast::Agent::REQUEST_TRACKER.current)
+
+          if policy.source_node
+            max =  ::Contrast::ASSESS.max_context_source_events
+            return at_limit?(policy, context.source_event_count, max, context)
+          end
+
+          if policy.propagation_node
+            max = ::Contrast::ASSESS.max_propagation_events
+            return at_limit?(policy, context.propagation_event_count, max, context)
+          end
+
+          false # policy does not have limit
+        end
+
+        def event_limit_for_rule? rule_id # rubocop:disable Metrics/AbcSize
+          return false unless (context = Contrast::Agent::REQUEST_TRACKER.current)
+
+          saved_request_ids = rule_counts.keys.map { |k| k.to_s.split('_')[1].to_i }
+
+          # if we passed the threshold and we actually have records for that request - wipe them
+          if saved_request_ids.uniq.include?(context.request.__id__)
+            restore_defaults
+            threshold_time_limit
+          end
+
+          # if we have recorded rule counts, but none of them are for the current request_id
+          # eventually we can try and play with the time_limit_threshold -> DEFAULT_MAX_RULE_TIME_THRESHOLD
+          if !rule_counts.empty? && !saved_request_ids.include?(context.request.__id__)
+            restore_defaults
+            threshold_time_limit
+          end
+
+          rule_key = "#{ rule_id }_#{ context.request.__id__ }"
+          rule_counts[rule_key] += 1
+          rule_counts[rule_key] >= ::Contrast::ASSESS.max_rule_reported
+        end
+
+        # Increments the event count for the type of event that is being tracked
+        #
+        # @param node [Contrast::Agent::Assess::Policy::PolicyNode] policy to increment
+        def increment_event_count node
+          return unless (context = Contrast::Agent::REQUEST_TRACKER.current)
+
+          context.source_event_count += 1 if node.cs__is_a?(Contrast::Agent::Assess::Policy::SourceNode)
+          context.propagation_event_count += 1 if node.cs__is_a?(Contrast::Agent::Assess::Policy::PropagationNode)
+        end
+
+        private
+
+        # helper method to check limit and log when necessary
+        def at_limit? method_policy, current_count, event_max, context
+          if current_count == event_max
+            return if event_limit_counts.key?(get_event_limit_key(method_policy, context))
+
+            logger.warn('Event Limit Reached:',
+                        {
+                            count: current_count,
+                            max: event_max,
+                            policy: method_policy.method_name,
+                            node: method_policy
+                        })
+            # increment to be over count for logging purposes
+            increment_event_count(method_policy)
+            increment_event_limit_logs(method_policy, context)
+
+            return true
+          elsif current_count > event_max
+            increment_event_count(method_policy)
+            return if event_limit_counts.key?(get_event_limit_key(method_policy, context))
+
+            # increment to be over count for logging purposes
+            logger.warn('Event Limit Exceeded:',
+                        {
+                            count: current_count,
+                            policy: method_policy.method_name,
+                            node: method_policy
+                        })
+            increment_event_limit_logs(method_policy, context)
+            return true
+          end
+          false
+        end
+
+        def rule_counts
+          @_rule_counts ||= Hash.new { |h, k| h[k] = 0 }
+        end
+
+        def event_limit_counts
+          @_event_limit_counts ||= Hash.new { |h, k| h[k] = 0 }
+        end
+
+        def get_event_limit_key method_policy, context
+          "#{ method_policy.method_name }_#{ context.request.__id__ }"
+        end
+
+        def increment_event_limit_logs method_policy, context
+          event_limit_counter = get_event_limit_key(method_policy, context)
+
+          event_limit_counts[event_limit_counter] += 1
+        end
+
+        # the time threshold for which to track rule counts resets when now >= threshold_time_limit
+        # @return [Integer]
+        def threshold_time_limit
+          @_threshold_time_limit ||= Contrast::Utils::Timer.now_ms + (::Contrast::ASSESS.time_limit_threshold || 0)
+        end
+
+        # @return nil
+        def restore_defaults
+          @_rule_counts = nil
+          @_threshold_time_limit = nil
+        end
+      end
+    end
+  end
+end

data/lib/contrast/utils/assess/object_store.rb

@@ -0,0 +1,36 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+module Contrast
+  module Utils
+    module Assess
+      # keep track of object properties and events data
+      class ObjectStore
+        def initialize capacity = 500
+          @capacity = capacity
+          @cache = {}
+        end
+
+        def get
+          @cache
+        end
+
+        def [] key
+          @cache[key]
+        end
+
+        def delete key
+          @cache.delete(key)
+        end
+
+        # We would keep object ids with capacity.
+        # If a reference is kept to an object only by it's id,
+        # It would be CG-ted safely.
+        def []= key, value
+          @cache[key] = value
+          @cache.shift if @cache.length > @capacity
+        end
+      end
+    end
+  end
+end

data/lib/contrast/utils/assess/propagation_method_utils.rb

@@ -0,0 +1,155 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+module Contrast
+  module Utils
+    module Assess
+      # This module will include all methods for some internal validations in the PropagationMethod module
+      # and some other module methods from the same place, so we can ease the main module
+      module PropagationMethodUtils
+        APPEND_ACTION = 'APPEND'
+        CENTER_ACTION = 'CENTER'
+        INSERT_ACTION = 'INSERT'
+        BUFFER_ACTION = 'BUFFER'
+        KEEP_ACTION = 'KEEP'
+        NEXT_ACTION = 'NEXT'
+        NOOP_ACTION = 'NOOP'
+        PREPEND_ACTION = 'PREPEND'
+        REPLACE_ACTION = 'REPLACE'
+        REMOVE_ACTION = 'REMOVE'
+        REVERSE_ACTION = 'REVERSE'
+        SPLAT_ACTION = 'SPLAT'
+        SPLIT_ACTION = 'SPLIT'
+        DB_WRITE_ACTION = 'DB_WRITE'
+        CUSTOM_ACTION = 'CUSTOM'
+
+        ZERO_LENGTH_ACTIONS = [DB_WRITE_ACTION, CUSTOM_ACTION, KEEP_ACTION, REPLACE_ACTION, SPLAT_ACTION].cs__freeze
+
+        PROPAGATION_ACTIONS = {
+            APPEND_ACTION => Contrast::Agent::Assess::Policy::Propagator::Append,
+            CENTER_ACTION => Contrast::Agent::Assess::Policy::Propagator::Center,
+            INSERT_ACTION => Contrast::Agent::Assess::Policy::Propagator::Insert,
+            KEEP_ACTION => Contrast::Agent::Assess::Policy::Propagator::Keep,
+            NEXT_ACTION => Contrast::Agent::Assess::Policy::Propagator::Next,
+            BUFFER_ACTION => Contrast::Agent::Assess::Policy::Propagator::Buffer,
+            NOOP_ACTION => nil,
+            PREPEND_ACTION => Contrast::Agent::Assess::Policy::Propagator::Prepend,
+            REPLACE_ACTION => Contrast::Agent::Assess::Policy::Propagator::Replace,
+            REMOVE_ACTION => Contrast::Agent::Assess::Policy::Propagator::Remove,
+            REVERSE_ACTION => Contrast::Agent::Assess::Policy::Propagator::Reverse,
+            SPLAT_ACTION => Contrast::Agent::Assess::Policy::Propagator::Splat,
+            SPLIT_ACTION => Contrast::Agent::Assess::Policy::Propagator::Split
+        }.cs__freeze
+
+        def determine_target propagation_node, ret, object, args
+          target = propagation_node.targets[0]
+          case target
+          when Contrast::Utils::ObjectShare::OBJECT_KEY
+            object
+          when Contrast::Utils::ObjectShare::RETURN_KEY
+            ret
+          else
+            args[target]
+          end
+        end
+
+        # Custom actions tend to be the more complex of our propagations. Often, the method has to make decisions
+        # about the target based on the context with which the method was called. As such, defer determining if the
+        # target is valid to that method.
+        #
+        # In all other cases, a target is valid for propagation if it is not nil
+        #
+        # @param target [Object] the thing to which to propagate
+        # @param propagation_node [Contrast::Agent::Assess::Policy::PropagationNode] the node that governs this
+        #   propagation event.
+        # @return [Boolean]
+        def valid_target? target, propagation_node
+          return true if propagation_node.action == CUSTOM_ACTION
+
+          !!target
+        end
+
+        # If the action required needs a length and the target does not have one, the length is not valid
+        #
+        # @param target [Object] the thing to which to propagate
+        # @param action [String] the name of the action taken during this propagation
+        # @return [Boolean]
+        def valid_length? target, action
+          return true if ZERO_LENGTH_ACTIONS.include?(action)
+
+          if Contrast::Utils::DuckUtils.quacks_to?(target, :length)
+            target.length != 0 # rubocop:disable Style/ZeroLengthPredicate
+          else
+            !target.to_s.empty?
+          end
+        end
+
+        # Before we do any work, we should check if we even need to. If the source and target of this patcher are
+        # not tracked, there's no need to do anything. A copy of nothing is still nothing.
+        #
+        # @param propagation_node [Contrast::Agent::Assess::Policy::PropagationNode] the node that governs this
+        #   propagation event.
+        # @param preshift [Contrast::Agent::Assess::PreShift] The capture of the state of the code just prior to
+        #   the invocation of the patched method.
+        # @param target [Object] the thing to which to propagate
+        # @param propagation_data [Contrast::Agent::Assess::Events::EventData] this will hold the
+        #                         object [Object] the Object on which the method was invoked
+        #                         args [Array<Object>] the Arguments with which the method was invoked
+        # @return [Boolean]
+        def can_propagate? propagation_node, preshift, target, propagation_data
+          return false unless appropriate_target?(propagation_node, target)
+          return true if Contrast::Utils::Assess::TrackingUtil.tracked?(target)
+          return false unless appropriate_source?(propagation_node, propagation_data, preshift)
+
+          propagation_node.sources.each do |source|
+            case source
+            when Contrast::Utils::ObjectShare::OBJECT_KEY
+              source_object = if propagation_node.use_original_object?
+                                propagation_data.object
+                              else
+                                preshift.object
+                              end
+              return true if Contrast::Utils::Assess::TrackingUtil.tracked?(source_object)
+            else
+              # has to be P, there's no ret source type (yet? ever?)
+              return true if preshift.args && Contrast::Utils::Assess::TrackingUtil.tracked?(preshift.args[source])
+            end
+          end
+          false
+        end
+
+        # We cannot propagate to frozen things that have not been updated to work with our property tracking,
+        # unless they're duplicable and the return. We probably shouldn't propagate to frozen things at all, as
+        # they're supposed to be immutable, but third parties do jenky things, so allow it as long as it is safe to
+        # do.
+        #
+        # @param propagation_node [Contrast::Agent::Assess::Policy::PropagationNode] the node that governs this
+        #   propagation event.
+        # @param target [Object] the Target to which to propagate.
+        # @return [Boolean] if the target can be propagated to
+        def appropriate_target? propagation_node, target
+          # special handle Returns b/c we can do unfreezing magic during propagation
+          return true if propagation_node.targets[0] == Contrast::Utils::ObjectShare::RETURN_KEY
+
+          Contrast::Agent::Assess::Tracker.trackable?(target)
+        end
+
+        # A source is appropriate if it is available for propagation
+        #
+        # @param propagation_node [Contrast::Agent::Assess::Policy::PropagationNode] the node that governs this
+        #   propagation event.
+        # @param propagation_data [Contrast::Agent::Assess::Events::EventData] this will hold the
+        #                         object [Object] the Object on which the method was invoked
+        #                         args [Array<Object>] the Arguments with which the method was invoked
+        # @param preshift [Contrast::Agent::Assess::PreShift] The capture of the state of the code just prior to
+        #   the invocation of the patched method.
+        # @return [Boolean]
+        def appropriate_source? propagation_node, propagation_data, preshift
+          return true if preshift
+
+          propagation_node.use_original_object? && propagation_data&.object
+        end
+      end
+    end
+  end
+end