contrast-agent 3.8.4 → 6.9.0

data/lib/contrast/agent/rule_set.rb

@@ -0,0 +1,52 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/components/logger'
+
+module Contrast
+  module Agent
+    # This class is responsible for holding our ruleset and performing filtering operations on all
+    # rules when asked by the middleware.
+    class RuleSet < Set
+      include Contrast::Components::Logger::InstanceMethods
+
+      # The filtering that needs to happen before the application gets access to the request object.
+      # The main action here is snapshotting the request as provided to the application from the
+      # user before any application code has acted upon it. Additionally, this is where Protect will
+      # terminate requests on attack detection if set to block at perimeter
+      #
+      # @raise [Contrast::SecurityException] raises error if security exception is thrown in prefilter
+      def prefilter
+        context = Contrast::Agent::REQUEST_TRACKER.current
+        return unless context&.analyze_request?
+
+        logger.trace_with_time('Running prefilter...') do
+          map { |rule| rule.prefilter(context) }
+        end
+      rescue Contrast::SecurityException => e
+        logger.warn('RASP threw security exception in prefilter', e)
+        raise(e)
+      rescue StandardError => e
+        logger.error('Unexpected exception during prefilter', e)
+      end
+
+      # The filtering that needs occur after the application has acted on the request and the response
+      # has been created. The main actions here are analyzing the response for unsafe state or actions.
+      #
+      # @raise [Contrast::SecurityException] raises error if security exception is thrown in postfilter
+      def postfilter
+        context = Contrast::Agent::REQUEST_TRACKER.current
+        return unless context&.analyze_response?
+
+        logger.trace_with_time('Running postfilter...') do
+          map { |rule| rule.postfilter(context) }
+        end
+      rescue Contrast::SecurityException => e
+        logger.warn('RASP threw security exception in postfilter', e)
+        raise(e)
+      rescue StandardError => e
+        logger.error('Unexpected exception during postfilter', e)
+      end
+    end
+  end
+end

data/lib/contrast/agent/scope.rb

@@ -1,28 +1,150 @@
-# 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
 
-# Scope lets us disable Contrast for certain code calls. We need to do this so
-# that we don't propagate through our own code.
-#
-# Think logging: If you have
-# something like "The source was '" + source + "'", and source is tracked,
-# you'll trigger propagation with the + method. This in turn would cause
-# propagation if you log there "The target ''" + target + "' was propagated'"
-# Which would then cause another propagation with the '+' method, forever.
-#
-# Instead, we should say "If I'm already doing Contrast things, don't track
-# this"
-#
-# NOTE: DO NOT DO ANYTHING IN THIS CLASS THAT COULD RESULT IN A MONKEY PATCHED
-# ACTION. WE CAN'T ENTER SCOPE BEFORE WE HAVE A SCOPE! YOU HAVE BEEN WARNED!!!
+require 'cs__scope/cs__scope'
+
 module Contrast
   module Agent
+    # Scope lets us disable Contrast for certain code calls. We need to do this so
+    # that we don't propagate through our own code.
+    #
+    # Think logging: If you have
+    # something like "The source was '" + source + "'", and source is tracked,
+    # you'll trigger propagation with the + method. This in turn would cause
+    # propagation if you log there "The target ''" + target + "' was propagated'"
+    # Which would then cause another propagation with the '+' method, forever.
+    #
+    # Instead, we should say "If I'm already doing Contrast things, don't track
+    # this"
+    #
+    # Scope Exits...
+    # by design, can go below zero.
+    # every exit/enter pair (regardless of series)
+    # should cancel each other out.
+    #
+    # so we prefer this sequence:
+    #   scope =  0
+    #   exit  = -1
+    #   enter =  0
+    #   enter =  1
+    #   exit  =  0
+    #   scope =  0
+    #
+    # over this sequence:
+    #   scope =  0
+    #   exit  =  0
+    #   enter =  1
+    #   enter =  2
+    #   exit  =  1
+    #   scope =  1
+    #
+    # This class have been moved to C and it's called from there. Here remains
+    # the validation and wrapper methods.
+    #
+    # Methods defined in C:
+    #
+    # sets scope instance variables.
+    # def initialize end;
+    #
+    # Check if we are in contrast scope.
+    # def in_contrast_scope? end;
+    # @return [Boolean] check if we are in contrast scope
+    #                   if the scope is above 0 return true.
+    #
+    # check if we are in deserialization scope.
+    # def in_deserialization_scope? end;
+    # @return [Boolean] check if we are in contrast scope
+    #                   if the scope is above 0 return true.
+    #
+    # check if we are in split scope.
+    # def in_split_scope? end;
+    # @return [Boolean] check if we are in contrast scope
+    #                   if the scope is above 0 return true.
+    #
+    # enter contrast scope.
+    # def enter_contrast_scope! end;
+    # @return @contrast_scope [Integer] contrast scope increased.
+    #
+    # enter deserialization scope.
+    # def enter_deserialization_scope! end;
+    # @return @deserialization_scope [Integer] deserialization scope increased.
+    #
+    # enter split scope.
+    # def enter_split_scope! end;
+    # @return @split_scope [Integer] split scope increased.
+    #
+    # check split scope depth.
+    # def split_scope_depth end;
+    # @return @split_scope [Integer] split scope depth.
+    #
+    # exit contrast scope.
+    # def exit_contrast_scope! end;
+    # @return @contrast_scope [Integer] contrast scope decreased.
+    #
+    # exit deserialization scope.
+    # def exit_deserialization_scope! end;
+    # @return @deserialization_scope [Integer] deserialization scope decreased.
+    #
+    # exit split scope.
+    # def exit_split_scope! end;
+    # @return @split_scope [Integer] split scope decreased.
+    #
+    # Static methods to be used, the cases are defined by the usage from the above methods
+    #
+    # check if we are in specific scope.
+    # def in_scope? name end;
+    # @param name [Symbol] scope symbol representing scope to check.
+    # @return [Boolean] check if we are in passed scope.
+    #
+    # enter specific scope.
+    # def enter_scope! name end;
+    # @param name [Symbol] scope symbol representing scope to enter.
+    # @return scope [Integer] entered scope value increased.
+    #
+    # exit specific scope.
+    # def exit_cope! name end;
+    # @param name [Symbol] scope symbol representing scope to exit.
+    # @return scope [Integer] entered scope value decreased.
     class Scope
-      # At first, all scopes are 0, meaning we're not in Contrast land
-      # NOTE: DO NOT DO ANYTHING IN THIS CLASS THAT COULD RESULT IN A MONKEY
-      # PATCHED ACTION. WE CAN'T ENTER SCOPE BEFORE WE HAVE A SCOPE! YOU HAVE
-      # BEEN WARNED!!! (again)
+      SCOPE_LIST = %i[contrast deserialization split].cs__freeze
+
+      # Wraps block to be executed in contrast scope.
+      # On completion exits scope.
+      def with_contrast_scope
+        enter_contrast_scope!
+        yield
+      ensure
+        exit_contrast_scope!
+      end
+
+      # Wraps block to be executed in deserialization scope.
+      # On completion exits scope.
+      def with_deserialization_scope
+        enter_deserialization_scope!
+        yield
+      ensure
+        exit_deserialization_scope!
+      end
+
+      # Wraps block to be executed in split scope.
+      # On completion exits scope.
+      def with_split_scope
+        enter_split_scope!
+        yield
+      ensure
+        exit_split_scope!
+      end
+
+      class << self
+        # Validates scope. To be valid the scope must be one of:
+        # :contrast, :split, :deserialization
+        #
+        # @param scope_sym [Symbol] scope to check.
+        # @return [Boolean] true | false
+        def valid_scope? scope_sym
+          Contrast::Agent::Scope::SCOPE_LIST.include?(scope_sym)
+        end
+      end
     end
   end
 end
-cs__scoped_require 'cs__scope/cs__scope'

data/lib/contrast/agent/static_analysis.rb

@@ -0,0 +1,51 @@
+# Copyright (c) 2022 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/scope'
+require 'contrast/agent/reporting/reporting_events/application_update'
+
+module Contrast
+  module Agent
+    # this module handles one time static analysis tasks
+    class StaticAnalysis
+      include Singleton
+      include Contrast::Components::Scope::InstanceMethods
+      extend Contrast::Components::Logger::InstanceMethods
+
+      class << self
+        # After the first request is complete, we do a one-time manual catchup to review and report the already-loaded
+        # gems.
+        def catchup
+          @_catchup ||= begin
+            threaded_analysis!
+            true
+          end
+        end
+
+        def send_inventory_message
+          return unless ::Contrast::INVENTORY.enable
+
+          report = Contrast::Agent::Reporting::ApplicationUpdate.new
+          # This convert here is left as it'll be easier to be replaced when the Library is being changed
+          report.libraries = Contrast::Agent::Inventory::DependencyAnalysis.instance.library_pb_list
+          Contrast::Agent::Inventory::DatabaseConfig.append_db_config(report)
+          [report, Contrast::Agent::Reporting::ApplicationInventory.new].each do |e|
+            Contrast::Agent.reporter.send_event(e)
+          end
+        end
+
+        private
+
+        def threaded_analysis!
+          Contrast::Agent::Thread.new do
+            Contrast::Agent::Inventory::DependencyUsageAnalysis.instance.catchup
+            send_inventory_message
+          rescue StandardError => e
+            logger.warn('Unable to run post-initialization static analysis', e)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/telemetry/base.rb

@@ -0,0 +1,155 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/config/env_variables'
+require 'contrast/components/logger'
+require 'contrast/utils/telemetry_client'
+require 'contrast/agent/worker_thread'
+require 'contrast/utils/telemetry'
+require 'contrast/agent/telemetry/events/exceptions/telemetry_exceptions'
+
+module Contrast
+  module Agent
+    module Telemetry
+      # This class will initialize and hold everything needed for the telemetry
+      class Base < WorkerThread
+        include Contrast::Components::Logger::InstanceMethods
+
+        # this is where we will send the data from the agents
+        URL = 'https://telemetry.ruby.contrastsecurity.com/'
+        # Suggested timeout after each send is to be 3 hours (10800 seconds)
+        SUGGESTED_TIMEOUT = 10_800
+
+        class << self
+          include Contrast::Components::Logger::InstanceMethods
+          include Contrast::Config::EnvVariables
+
+          def application_id
+            Contrast::Utils::Telemetry::Identifier.application_id
+          end
+
+          def instance_id
+            Contrast::Utils::Telemetry::Identifier.instance_id
+          end
+
+          def enabled?
+            @_enabled = telemetry_enabled? if @_enabled.nil?
+            @_enabled
+          end
+
+          private
+
+          def telemetry_enabled?
+            opt_out_telemetry = return_value(:telemetry_opt_outs).to_s
+            return false if opt_out_telemetry.casecmp?('true') || opt_out_telemetry == '1'
+
+            # In case of connection error, do not create the background thread or queue,
+            # as if the opt-out env var was set
+            @_client = Contrast::Utils::TelemetryClient.new
+            ip_opt_out_telemetry = @_client.initialize_connection(URL)
+            if ip_opt_out_telemetry.nil?
+              logger.warn("Connection was not established properly!!! \n Telemetry reporting will be disabled!")
+              return false
+            end
+
+            true
+          end
+        end
+
+        def client
+          @_client ||= Contrast::Utils::TelemetryClient.new
+        end
+
+        def connection
+          @_connection ||= client.initialize_connection(URL)
+        end
+
+        def attempt_to_start?
+          unless cs__class.enabled?
+            logger.warn('Telemetry service is disabled!')
+            return false
+          end
+
+          logger.debug('Attempting to start telemetry thread') unless running?
+          true
+        end
+
+        def start_thread!
+          return if running?
+
+          logger.debug('Starting background telemetry thread.')
+          @_thread = create_thread
+        end
+
+        def send_event event
+          if ::Contrast::AGENT.disabled?
+            logger.warn('Attempted to queue event with Agent disabled', caller: caller, event: event)
+            return
+          end
+
+          return unless cs__class.enabled?
+
+          logger.debug('Enqueued event for sending', event_type: event.cs__class)
+          queue << event if event
+        end
+
+        def delete_queue!
+          @_queue&.close
+          @_queue = nil
+        end
+
+        def stop!
+          return unless running?
+
+          @_enabled = false
+          delete_queue!
+          super
+        end
+
+        def request_with_response event
+          res = client.send_request(event, connection)
+          client.handle_response(res)
+        end
+
+        private
+
+        def queue
+          @_queue ||= Queue.new
+        end
+
+        # It is recommended that implementations send a single payload of general metrics every 3 hours, starting from
+        # implementation startup. This returns a thread configured to do so.
+        #
+        # @return [Contrast::Agent::Thread]
+        def create_thread
+          Contrast::Agent::Thread.new do
+            loop do
+              next unless client && connection
+
+              # Start pushing exceptions to queue for reporting.
+              Contrast::TELEMETRY_EXCEPTIONS.each_value { |value| queue << value }
+              Contrast::TELEMETRY_EXCEPTIONS.clear
+              until queue.empty?
+                event = queue.pop
+                begin
+                  logger.debug('This is the current processed event', event)
+                  sleep_time = request_with_response(event)
+                  if sleep_time
+                    sleep(sleep_time)
+                    logger.debug('Retrying to process event', event)
+                    retry_sleep_time = request_with_response(event)
+                    sleep(retry_sleep_time) unless retry_sleep_time.nil?
+                  end
+                rescue StandardError => e
+                  logger.error('Could not send message to service from telemetry queue.', e)
+                  stop!
+                end
+              end
+              sleep(SUGGESTED_TIMEOUT)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/telemetry/events/event.rb

@@ -0,0 +1,35 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/utils/metrics_hash'
+
+module Contrast
+  module Agent
+    module Telemetry
+      # This class will hold the basic information for a Telemetry Event
+      class Event
+        include Contrast::Utils
+
+        attr_reader :tags
+
+        def initialize
+          @tags = MetricsHash.new(String)
+          @timestamp = Time.now.iso8601
+        end
+
+        def path
+          ''
+        end
+
+        def to_controlled_hash **_args
+          {
+              tags: @tags,
+              timestamp: @timestamp,
+              instance: Contrast::Agent::Telemetry::Base.instance_id,
+              application: Contrast::Agent::Telemetry::Base.application_id
+          }
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/telemetry/events/exceptions/obfuscate.rb

@@ -0,0 +1,119 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+module Contrast
+  module Agent
+    module Telemetry
+      module TelemetryException
+        # Here will be all known gems to obfuscate during the building of TelemetryExceptions
+        module Obfuscate
+          # List of known gems to be third parties not containing any
+          # user sensitive data.
+          KNOWN_GEMS = %w[
+            activesupport redis-activesupport redis builder dry-types rails rails-html-sanitizer rails-observers sinatra
+            benchmark-ips bundler climate_control execjs factory_bot debride fake_ftp fasterer flay openssl
+            parallel_tests contrast contrast-agent ruby pry-byebug byebug pry resolv ougai protobuf async nokogiri
+            benchmark grape-order grape-activerecord newrelic newrelic-grape grape-rails-cache grape-msgpack
+            grape-batch rspec rake rubocop grape-jbuilder rack-test rack-protection minitest grape-instrumentation
+            minitest-global_expectations rack-proxy rack-attack rack-ssl grape-cancan grape-attack grape-rake-tasks
+            grape-route-helpers benchmark-memory grape-rabl grape-kaminari grape-path-helpers grape-swagger-entity
+            grape-swagger-rails grape-roar newrelic-rake grapes-wagger-representative grape-forgery_protection
+            grape-papertrail grape-app grape-middleware-logger rack-protection rake-compile rhino rspec-benchmark
+            rspec_junit_formatter rspec-rails rake-performance rubocop-rails rubocop-rake rubocop-rspec
+            ruby-debug-ide simplecov sqlite steep tilt tzinfo-data warning xpath sinatra-activerecord sinatra-param
+            sinatra-partial sinatra-flash sinatra-reloader sinatra-sinatra rake_fly rack rack-accept grape grape-entity
+            sinatra-advanced-routes sinatra-warden grape_logging grape-swagger sinatra-namespace sinatra-resource
+            sinatra-hashfix sinatra-instrumentation sinatra-helpers redis-rack sinatra-support sinatra-assetpack
+            sinatra-router sinatra-cross_origin sinatra_more sinatra-jsonp faraday-rack zlib mustermann mustermann-grape
+            rspec-expectations rspec-core rspec-mocks rspec-sidekiq
+          ].cs__freeze
+          KNOWN_ERRORS = %w[
+            ActiveModel Error Errors Resolv Rspec ActiveRecord nil NilClass NoMemoryError ScriptError
+            LoadError NotImplementedError SyntaxError SecurityError SignalException Interrupt
+            StandardError ArgumentError UncaughtThrowError FiberError IOError EOFError IndexError KeyError
+            StopIteration LocalJumpError NameError NoMethodError RangeError FloatDomainError RegexpError
+            RuntimeError FrozenError SystemCallError ThreadError TypeError ZeroDivisionError SystemExit
+            SystemStackError fatal Warning buffer OpenSSL SSL SSLError Errno Timeout Exception EOFError
+            ECONNRESET ECONNREFUSED ETIMEDOUT EINVAL ESHUTDOWN EHOSTDOWN EHOSTUNREACH EISCONN
+            ECONNABORTED ENETRESET ENETUNREACH Net HTTPBadResponse HTTPHeaderSyntaxError ProtocolError
+            Faraday BadRequestError UnauthorizedError ForbiddenError ResourceNotFound ProxyAuthError
+            ConflictError UnprocessableEntityError ClientError
+          ].cs__freeze
+          CHARS = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'.cs__freeze
+          # This will generate different chars for each agent startup but will be constant
+          # for current run and will make identical obfuscation to be compared if given type
+          # is the same.
+          CYPHER = CHARS.chars.shuffle.join
+
+          class << self
+            # Returns paths for known gems.
+            #
+            # @return [Array<Regexp>] known paths
+            def known_gem_paths
+              @_known_gem_paths ||= KNOWN_GEMS.map do |gem_name|
+                to_regexp(File.join(
+                              'gems', gem_name.tr('-', ''), 'lib'))
+              end
+            end
+
+            # Returns known modules names.
+            #
+            # @return [Array<Regexp>] known modules
+            def known_modules
+              @_known_modules ||= KNOWN_ERRORS.map { |module_name| to_regexp(module_name) }
+            end
+
+            # Obfuscate a type and replace it with random characters.
+            #
+            # @param type [String] the StackFrame type to obfuscate
+            # @return [String] obfuscated type
+            def obfuscate_type type
+              return unless type
+
+              check = type.tr('[^0-9].-', '')
+              type = cypher(type) unless match_known(known_gem_paths, check)
+              type
+            end
+
+            # Obfuscate a type and replace it with random characters.
+            #
+            # @param exception_type [String] the exception type to obfuscate
+            # @return [String] obfuscated exception type
+            def obfuscate_exception_type exception_type
+              return unless exception_type
+
+              exceptions = exception_type.split('::').each do |exception|
+                cypher(exception) unless match_known(known_modules, exception)
+              end
+              exceptions.join('::')
+            end
+
+            private
+
+            # Transforms string to regexp
+            #
+            # @param string [String]
+            def to_regexp string
+              /#{ string }/
+            end
+
+            # Add cypher to path to make it obscure, but unique enough for
+            # comparisons. Mutates original or duplicate if frozen string.
+            #
+            # @param string [String] string to be transformed.
+            def cypher string
+              string = string.dup if string.cs__frozen?
+              string.to_s.tr!(CHARS, CYPHER)
+            end
+
+            # @param known [Array<Regexp>] Array of regexp to match againts
+            # @param type [String] type to check
+            def match_known known, type
+              known.any? { |regexp| type =~ regexp }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/telemetry/events/exceptions/telemetry_exception_base.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
+
+module Contrast
+  module Agent
+    module Telemetry
+      module TelemetryException
+        # This class will hold the all the mutual information for the Telemetry Exception
+        class Base
+          def to_controlled_hash; end
+
+          protected
+
+          # Validate required and option fields
+          #
+          # @param validations [Hash] Validation hash to use
+          # @return [nil]
+          def validate validations
+            validations.each do |k, v|
+              next if v[:required] == false
+
+              validate_field(validations[k], k)
+            end
+            nil
+          end
+
+          # This method will validate every single field passed from validate
+          #
+          # @param validation_pair [Hash] Validation hash to use
+          # @param key[String] The key to check in VALIDATIONS
+          # @raise [ArgumentError]
+          def validate_field validation_pair, key
+            value_to_validate = send(key.to_sym)
+            validate_class(value_to_validate, validation_pair[:class], key) if validation_pair.key?(:class)
+            value_length = if value_to_validate.cs__is_a?(String) || value_to_validate.cs__is_a?(Array)
+                             value_to_validate.length
+                           else
+                             value_to_validate.entries.length
+                           end
+            unless validation_pair[:range].include?(value_length)
+              raise(ArgumentError, "The provided value for #{ key } is invalid: #{ value_to_validate }")
+            end
+
+            nil
+          end
+
+          # With the all nested classes, we still need to double check if everything passed along the way
+          # is right
+          # @param message [Object] The message we want to check the class of
+          # @param klass [Class] The klass we want to check the message with
+          # @param field [Object] The field with the error
+          # @raise [ArgumentError]
+          def validate_class message, klass, field
+            message = message[0] if message.cs__is_a?(Array)
+            raise(ArgumentError, "The provided value for #{ field } is of wrong class") unless message.cs__is_a?(klass)
+          end
+        end
+      end
+    end
+  end
+end