contrast-agent 3.8.4 → 6.9.0

data/lib/contrast/logger/aliased_logging.rb

@@ -0,0 +1,101 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/agent/telemetry/events/exceptions/telemetry_exceptions'
+require 'contrast/agent/telemetry/events/exceptions/obfuscate'
+
+module Contrast
+  module Logger
+    # Our decorator for the Ougai logger allowing for the catching, creating and saving Telemetry exceptions
+    module AliasedLogging
+      ALIASED_WARN = 'warn'.cs__freeze
+      ALIASED_ERROR = 'error'.cs__freeze
+      ALIASED_FATAL = 'fatal'.cs__freeze
+
+      # @param message [String] The message to log. Use default_message if not specified.
+      # @param exception [Exception] The exception or the error
+      # @param data [Object] Any structured data
+      def warn message = nil, exception = nil, data = nil, &block
+        # build Telemetry Exclusion
+        build_exception(ALIASED_WARN, message, exception, data)
+        super(message, exception, data, &block)
+      end
+
+      # @param message [String] The message to log. Use default_message if not specified.
+      # @param exception [Exception] The exception or the error
+      # @param data [Object] Any structured data
+      def error message = nil, exception = nil, data = nil, &block
+        # build Telemetry Exclusion
+        build_exception(ALIASED_ERROR, message, exception, data)
+        super(message, exception, data, &block)
+      end
+
+      # @param message [String] The message to log. Use default_message if not specified.
+      # @param exception [Exception] The exception or the error
+      # @param data [Object] Any structured data
+      def fatal message = nil, exception = nil, data = nil, &block
+        # build Telemetry Exclusion
+        build_exception(ALIASED_FATAL, message, exception, data)
+        super(message, exception, data, &block)
+      end
+
+      private
+
+      def build_exception type, message = nil, exception = nil, data = nil
+        stack_trace = get_stack_trace(type)
+        stack_frame_type = Contrast::Agent::Telemetry::TelemetryException::Obfuscate.obfuscate_type(
+            stack_trace[1].path.delete_prefix(Dir.pwd))
+        stack_frame_function = stack_trace[1].label
+        key = "#{ stack_frame_type }|#{ stack_frame_function }|#{ message }"
+        if TELEMETRY_EXCEPTIONS[key]
+          TELEMETRY_EXCEPTIONS.increment(key)
+          return
+        end
+
+        return if TELEMETRY_EXCEPTIONS.exception_limit?
+
+        message_exception_type = Contrast::Agent::Telemetry::TelemetryException::Obfuscate.obfuscate_exception_type(
+            exception ? exception.cs__class.to_s : stack_frame_type.split('/').last)
+
+        event_message = create_message(stack_frame_function,
+                                       stack_frame_type, message_exception_type,
+                                       data, exception,
+                                       message)
+        TELEMETRY_EXCEPTIONS[key] = event_message
+      rescue StandardError => e
+        debug('Unable to report exception to telemetry', e)
+      end
+
+      def create_message stack_frame_function, stack_frame_type, message_exception_type, data, exception, message
+        message_for_exception = if exception
+                                  exception.cs__respond_to?(:message) ? exception.message : exception
+                                else
+                                  message
+                                end
+        module_name = message_exception_type ? message_exception_type.split('::')[0] : nil
+        stack_frame = Contrast::Agent::Telemetry::TelemetryException::StackFrame.build(stack_frame_function,
+                                                                                       stack_frame_type,
+                                                                                       module_name)
+        message_exception = Contrast::Agent::Telemetry::TelemetryException::MessageException.build(
+            message_exception_type,
+            message_for_exception,
+            module_name,
+            stack_frame)
+        tags = if data
+                 data
+               else
+                 exception.cs__is_a?(Hash) ? exception : {}
+               end
+        message = Contrast::Agent::Telemetry::TelemetryException::Message.build(tags, [message_exception])
+        Contrast::Agent::Telemetry::TelemetryException::Event.new(message)
+      rescue ArgumentError => e
+        debug('TelemetryException failed from aliased logging with: ', e)
+      end
+
+      def get_stack_trace type
+        start = caller_locations&.find_index { |stack| stack.to_s.include?(type) }
+        start ? caller_locations(start + 1, 20) : caller_locations(20, 20)
+      end
+    end
+  end
+end

data/lib/contrast/logger/application.rb

@@ -0,0 +1,84 @@
+# Copyright (c) 2022 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 the logging of the
+    # application environment, used to provide context during troubleshooting.
+    module Application
+      ENV_KEYS = %w[HOME PWD RACK_ENV RAILS_ENV RUBY_VERSION GEM_HOME GEM_PATH].cs__freeze
+      # Utility method to log some current ruby and rails information from environment
+      def application_environment
+        return unless info?
+
+        info('Process environment information', p_id: Process.pid, pp_id: Process.ppid,
+                                                agent_version: Contrast::Agent::VERSION,
+                                                ruby_version: RUBY_VERSION)
+        ENV.each do |env_key, env_value|
+          env_key = env_key.to_s
+          next unless ENV_KEYS.include?(env_key) ||
+              (env_key.start_with?(Contrast::Components::Config::CONTRAST_ENV_MARKER) &&
+                  !env_key.start_with?("#{ Contrast::Components::Config::CONTRAST_ENV_MARKER }API"))
+
+          info('Environment settings', key: env_key, value: env_value)
+        end
+      end
+
+      def application_configuration
+        return unless info?
+
+        loggable = ::Contrast::CONFIG.loggable
+        info('Current configuration', configuration: loggable)
+        env_keys = ENV.keys.select do |env_key|
+          env_key&.to_s&.start_with?(Contrast::Components::Config::CONTRAST_ENV_MARKER)
+        end
+        env_items = env_keys.map { |env_key| Contrast::Utils::EnvConfigurationItem.new(env_key, nil) }
+        env_translations = env_items.each_with_object({}) do |conversion, hash|
+          hash[conversion.key] = conversion.dot_path_array.join('.')
+        end
+        info('Set by environment', overrides: env_translations)
+      end
+
+      def application_libraries
+        if debug?
+          log_all_libraries
+        elsif info?
+          log_specific_libraries
+        end
+      end
+
+      FRAMEWORKS = %w[rails sinatra grape].cs__freeze
+      WEB_SERVERS = %w[
+        agoo falcon hoof iodine mongrel mongrel2 passenger puma rack skinny thin trinidad unicorn
+        webrick yarn
+      ].cs__freeze
+      LIBRARIES = %w[excon json mongo moped mysql nokogiri oga ox pg psych sqlite3 typhoeus yaml].cs__freeze
+      def log_specific_libraries
+        FRAMEWORKS.each(&cs__method(:log_gem_data))
+        WEB_SERVERS.each(&cs__method(:log_gem_data))
+        LIBRARIES.each(&cs__method(:log_gem_data))
+      end
+
+      private
+
+      def log_all_libraries
+        return unless debug?
+
+        Gem.loaded_specs.each_pair do |_name, gem_spec|
+          debug('Gem loaded',
+                # rubocop:disable Security/Module/Name -- gems builtin.
+                gem_name: gem_spec.name,
+                gem_version: gem_spec.version.to_s)
+        end
+      end
+
+      def log_gem_data gem_name
+        gem_spec = Gem.loaded_specs[gem_name]
+        return unless gem_spec
+
+        info('Gem loaded', gem_name: gem_spec.name, gem_version: gem_spec.version.to_s)
+        # rubocop:enable Security/Module/Name
+      end
+    end
+  end
+end

data/lib/contrast/logger/cef_log.rb

@@ -0,0 +1,169 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'logger'
+require 'singleton'
+
+require 'contrast/extension/module'
+require 'contrast/logger/application'
+require 'contrast/logger/format'
+require 'contrast/logger/request'
+require 'contrast/logger/time'
+require 'contrast/logger/log'
+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']
+      ::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 is the CEF Logger implementation. It uses the default ::Logger.
+    class CEFLog
+      include Singleton
+      include ::Contrast::Utils::LogUtils
+      include ::Contrast::Utils::CEFLogUtils
+
+      attr_reader :previous_path, :previous_level
+
+      def initialize
+        build_logger
+      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_level [String] the level at which to log, as provided by TeamServer settings
+      # @param log_file [String] the file to which to log, as provided by TeamServer settings
+      def build_logger log_level = nil, log_file = nil
+        current_path_const = find_valid_path(log_file)
+        current_level_const = find_valid_level(log_level)
+        level_change = current_level_const != previous_level
+        path_change = current_path_const != previous_path
+
+        # don't needlessly recreate logger
+        return if @cef_logger && !(level_change || path_change)
+
+        @previous_level = current_level_const
+        @previous_path = current_path_const
+
+        @_cef_logger = build(path: current_path_const, level_const: current_level_const)
+        # 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
+        # rubocop:disable Rails/Output
+        if @_cef_logger
+          @_cef_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
+        # rubocop:enable Rails/Output
+      end
+
+      def cef_logger
+        @_cef_logger
+      end
+
+      def find_valid_path log_file
+        config = ::Contrast::CONFIG.agent.security_logger
+        config_path = config&.path&.length.to_i.positive? ? config.path : nil
+        valid_path(config_path || log_file, default_name: DEFAULT_CEF_NAME)
+      end
+
+      # @return [::Ougai::Logging::Severity] the level at which to log
+      def find_valid_level log_level
+        config = ::Contrast::CONFIG.agent.security_logger
+        config_level = config&.level&.length&.positive? ? config.level : nil
+
+        valid_level(config_level || log_level)
+      end
+
+      def log msg, level = @_cef_logger.level
+        case level
+        when ::Logger::Severity::INFO
+          @_cef_logger.info(msg)
+        when ::Logger::Severity::ERROR
+          @_cef_logger.error(msg)
+        when ::Logger::Severity::WARN
+          @_cef_logger.warn(msg)
+        when ::Logger::Severity::FATAL
+          @_cef_logger.fatal(msg)
+        else
+          @_cef_logger.debug(msg)
+        end
+      end
+
+      def virtual_patch_message patch, outcome
+        message = "Virtual Patch #{ patch.fetch(:name, '') } - #{ patch[:uuid] } was triggered by this request."
+        log([message, patch, outcome], ::Logger::Severity::DEBUG)
+      end
+
+      def bot_blocking_message matching_bot, outcome
+        message = "User agent #{ matching_bot[:user_agent] } matched the disallowed value #{ matching_bot[:bot] }"
+        log([message, matching_bot, outcome], ::Logger::Severity::DEBUG)
+      end
+
+      def ip_denylisted_message remote_ip, block_entry, outcome
+        message = "IP Address #{ remote_ip } matched the disallowed value" \
+                  "#{ block_entry[:ip] } in the IP Blacklist #{ block_entry[:uuid] }"
+        log([message, block_entry, outcome], ::Logger::Severity::DEBUG)
+      end
+
+      def successful_attack rule_id, outcome, input_type = nil, input_value = nil
+        if input_type.present? && input_value.present?
+          successful_attack_with_input = "#{ input_type } had a value that successfully exploited" \
+                                         "#{ rule_id } - #{ input_value }"
+          log([successful_attack_with_input, rule_id, outcome], ::Logger::Severity::WARN)
+        else
+          successful_attack_wo_input = "An effective attack was detected against #{ rule_id }"
+          log([successful_attack_wo_input, rule_id, outcome], ::Logger::Severity::WARN)
+        end
+      end
+
+      def ineffective_attack rule_id, outcome, input_type = nil, input_value = nil
+        if input_type.present? && input_value.present?
+          ineffective_attack_with_input = "#{ input_type } had a value that matched a signature for, " \
+                                          "but did not successfully exploit #{ rule_id } - #{ input_value }"
+          log([ineffective_attack_with_input, rule_id, outcome], ::Logger::Severity::WARN)
+        else
+          ineffective_attack_wo_input = "An unsuccessful attack was detected against #{ rule_id }"
+          log([ineffective_attack_wo_input, rule_id, outcome], ::Logger::Severity::WARN)
+        end
+      end
+
+      # newer - currently not in the agent, currently is a probe for us
+      def suspicious_attack rule_id, outcome, input_type = nil, input_value = nil
+        if input_type.present? && input_value.present?
+          suspicious_attack_with = "#{ input_type } included a potential attack value that was detected" \
+                                   "as suspicious using #{ rule_id } - #{ input_value }"
+          log([suspicious_attack_with, rule_id, outcome], ::Logger::WARN)
+        elsif input_value.present?
+          suspicious_attack_without = "Suspicious activity indicates a potential attack using #{ rule_id }"
+          log([suspicious_attack_without, rule_id, outcome], ::Logger::WARN)
+        end
+      end
+    end
+  end
+end

data/lib/contrast/logger/format.rb

@@ -0,0 +1,61 @@
+# Copyright (c) 2022 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) 2022 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) 2022 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) 2022 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) 2022 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