contrast-agent 3.8.4 → 6.9.0

data/lib/contrast/agent/reporting/input_analysis/score_level.rb

@@ -0,0 +1,21 @@
+# 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 Reporting
+      # input types for InputAnalysis results
+      module ScoreLevel
+        IGNORE = :DONTCARE.cs__freeze
+        WORTHWATCHING = :WORTHWATCHING.cs__freeze
+        DEFINITEATTACK = :DEFINITEATTACK.cs__freeze
+
+        class << self
+          def to_a
+            [IGNORE, WORTHWATCHING, DEFINITEATTACK]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/masker/masker.rb

@@ -0,0 +1,258 @@
+# 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/agent/reporting/reporter'
+require 'contrast/utils/object_share'
+require 'contrast/agent/reporting/attack_result/response_type'
+require 'contrast/agent/reporting/masker/masker_utils'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This module duty is to mask any activity containing sensitive information - PII masking.
+      module Masker
+        MASK = 'contrast-redacted-'
+        BODY_MASK = 'contrast-redacted-body'
+        BODY_BINARY_MASK = BODY_MASK.bytes.to_s.cs__freeze
+
+        class << self
+          include Contrast::Components::Logger::InstanceMethods
+          include Contrast::Utils::ObjectShare
+          include Contrast::Agent::Reporting::MaskerUtils
+
+          # Keyword dictionary, extracted from the TS response.
+          #
+          # @return Array<Contrast::Agent::Reporting::Settings::SensitiveDataMaskingRule>
+          def dictionary
+            @_dictionary ||= update_dictionary
+          end
+
+          # Mask sensitive data according to the contrast sensitive data rules.
+          #
+          # @param [Contrast::Agent::Reporting::ApplicationActivity]
+          def mask activity
+            return unless activity
+
+            logger.debug('Masker: masking sensitive data', activity: activity.__id__, request: activity.request&.__id__)
+            return if activity.request.nil?
+
+            mask_body(activity)
+            mask_query_string(activity)
+            mask_request_params(activity)
+            mask_request_cookies(activity)
+            mask_request_headers(activity)
+          rescue StandardError => _e
+            logger.debug('Could not mask activity!', activity: activity.__id__, request: activity.request&.__id__)
+          end
+
+          private
+
+          # When called this will overwrite existing rules with those
+          # in settings. Ideally we need to call this on init and when
+          # the Agent receives new rules from TS response.This is called
+          # from Contrast::Components::Settings.
+          #
+          # To make it save this is private method because if new
+          # settings arrive and they might be empty as edge case,
+          # this will produce dictionary with empty rules and this
+          # is not desirable.
+          def update_dictionary
+            @_dictionary = Contrast::SETTINGS.sensitive_data_masking.rules
+          end
+
+          # Mask request body:
+          #
+          # @param activity [Contrast::Agent::Reporting::ApplicationActivity]
+          # @return masked_body [String, nil]
+          def mask_body activity
+            return unless mask_body?
+
+            body = activity.request.body
+            return if body.nil? || body.empty?
+
+            activity.request.body = BODY_MASK
+            activity.request.body_binary = BODY_BINARY_MASK
+          end
+
+          # Mask request params.
+          #
+          # @param activity [Contrast::Agent::Reporting::ApplicationActivity]
+          # @return masked_body [String, nil]
+          def mask_request_params activity
+            params = activity.request.parameters
+            return unless params
+
+            mask_with_dictionary(activity.attack_results, params)
+          end
+
+          def mask_request_headers activity
+            headers = activity.request.headers
+            return if headers&.empty?
+
+            # Used normalized request_headers
+            mask = mask_with_dictionary(activity.attack_results, headers)
+            activity.request.headers = mask if mask
+          end
+
+          # Mask Cookies.
+          #
+          # @param activity [Contrast::Agent::Reporting::ApplicationActivity] Activity to mask
+          # @return masked_values [Hash, nil]
+          def mask_request_cookies activity
+            cookies = activity.request.cookies
+            return if cookies&.empty?
+
+            mask_with_dictionary(activity.attack_results, cookies)
+          end
+
+          # Mask request query string:
+          # exp: password => sensitive to password => contrast-redacted-password
+          #
+          # @param activity [Contrast::Agent::Reporting::ApplicationActivity]
+          # @return masked_query [String]
+          def mask_query_string activity
+            qs = activity.request.query_string
+            return if qs.nil? || qs.empty?
+
+            mask = mask_raw_query(qs, activity.attack_results)
+            activity.request.query_string = mask if mask
+          end
+
+          # Mask if the value in the passed hash are matched against dictionary
+          # keyword. If the mask_attack_vector flag is set, this will also mask
+          # any attack.
+          #
+          # @param results [Array<Contrast::Agent::Reporting::ApplicationDefendAttackActivity>]
+          # results to match against.
+          # @param hash [Hash] Normalized hash representing the key/val pair from
+          # the activity's http request parameters.
+          # @return nil | Protobuf::Field::FieldHash
+          def mask_with_dictionary results, hash
+            return if hash.nil? || hash.empty?
+
+            hash.each do |key, val|
+              next unless dictionary_match(key)
+
+              if val.cs__is_a?(Array)
+                mask_values(key, val, hash, results)
+              else
+                # Just assign keys.
+                mask_hash(key, val, hash, results)
+              end
+            end
+          end
+
+          # Mask the values of key value pair with array of string as input.
+          # If the mask_attack_vector? flag is set then the attack vector won't be
+          # masked.
+          #
+          # @param key [String]
+          # @param hash [Hash] Normalized hash representing the key/val pair.
+          # @param results [Array<Contrast::Agent::Reporting::ApplicationDefendAttackActivity>]
+          # results to match against.
+          # @param val [String, Array<String>]
+          def mask_values key, val, hash, results
+            val.each.with_index do |v, idx|
+              # Mask the attack vector only if the flag is set.
+              hash[key][idx] = MASK + key.downcase if attack_vector?(results, v) && mask_attack_vector?
+              # It is not attack vector and we mask it as normal.
+              hash[key][idx] = MASK + key.downcase unless attack_vector?(results, v)
+            end
+            hash
+          end
+
+          # Handles the masking of hash
+          #
+          # @param key [String] current iterable key from Protobuf::Field::FieldHash
+          # @param val [String] normalized value to be matched against the results
+          # and masked.
+          # @param hash [Hash] Normalized hash representing the key/val pair.
+          # @param results [Array<Contrast::Agent::Reporting::ApplicationDefendAttackActivity>]
+          # results to match against.
+          # @return [Hash]
+          def mask_hash key, val, hash, results
+            # Mask the attack vector only if the flag is set.
+            hash[key] = MASK + key.downcase if attack_vector?(results, val) && mask_attack_vector?
+            # It is not attack vector we mask it.
+            hash[key] = MASK + key.downcase unless attack_vector?(results, val)
+            hash
+          end
+
+          # Match to see if values matches input from AttackResults array.
+          # If match is found and the attack result's response is any of
+          # [BAP(Block At Perimeter), BLOCKED, PROBED] the return is true.
+          #
+          # @param results [Array<Contrast::Agent::Reporting::ApplicationDefendAttackActivity>]
+          # results to match against.
+          # @param value [String] Input to match.
+          # @return [Boolean]
+          def attack_vector? results, value
+            return false unless value && results
+
+            results.each do |attacker|
+              attacker.each do |activity|
+                blocked = iterate_attack_samples(activity.blocked, value)
+                return blocked if blocked
+
+                exploited = iterate_attack_samples(activity.exploited, value)
+                return exploited if exploited
+
+                ineffective = iterate_attack_samples(activity.ineffective, value)
+                return ineffective if ineffective
+
+                suspicious = iterate_attack_samples(activity.suspicious, value)
+                return suspicious if suspicious
+              end
+            end
+            false
+          end
+
+          # Go through activity samples and search for a matching input.
+          #
+          # @param activity [Contrast::Agent::Reporting::ApplicationDefendAttackActivity]
+          # @param value [String] Input to match.
+          # @return [Boolean]
+          def iterate_attack_samples activity, value
+            return false unless activity
+
+            activity.samples.any? do |sample|
+              match = sample.user_input.value == value.to_s
+
+              return true if match
+            end
+            false
+          end
+
+          # Consult with our current settings state.
+          #
+          # @return true | false
+          def mask_attack_vector?
+            Contrast::SETTINGS.sensitive_data_masking.mask_attack_vector?
+          end
+
+          # Consult with our current settings state.
+          #
+          # @return true | false
+          def mask_body?
+            Contrast::SETTINGS.sensitive_data_masking.mask_http_body?
+          end
+
+          # Check to see if value is matched in the dictionary.
+          #
+          # @param value [String] Value to check.
+          # @return match [String, nil] from the Dictionary, or nil.
+          def dictionary_match value
+            return unless @_dictionary
+
+            @_dictionary.each do |rule|
+              idx = rule.keywords.find_index(value.downcase)
+              return rule.keywords[idx] if idx
+            end
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/masker/masker_utils.rb

@@ -0,0 +1,33 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/utils/object_share'
+
+module Contrast
+  module Agent
+    module Reporting
+      # helper methods used for masking
+      module MaskerUtils
+        include Contrast::Utils::ObjectShare
+
+        # Mask raw query as it comes from the env.
+        # exp:
+        # 'ssn=1234567&id=%272%20or%202%20=%202%27' =>
+        # 'ssn=contrast-redacted-ssn&id=contrast-redacted-id'
+        #
+        # @param query [String]
+        # @param results [Array<Contrast::Agent::Reporting::ApplicationDefendAttackActivitys>]
+        # results to match against.
+        def mask_raw_query query, results
+          masked = EMPTY_STRING
+          hash = URI.decode_www_form(query).to_h
+          mask_with_dictionary(results, hash)
+          # Restore to string form.
+          hash.each { |k, v| masked += "#{ k }=#{ v }&" }
+          query = masked
+          query.chomp!(masked[-1])
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/report.rb

@@ -0,0 +1,31 @@
+# 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
+    # This is the base module for our reporting functionality. It is intended to
+    # facilitate all the needed report generating functionality and eventual
+    # report to RS.
+    # Any class under this namespace should be required here, providing a
+    # single point of require for this functionality.
+    module Reporting
+    end
+  end
+end
+
+require 'contrast/agent/reporting/reporter'
+require 'contrast/agent/reporting/reporting_utilities/audit'
+require 'contrast/agent/reporting/reporting_utilities/reporter_client'
+require 'contrast/agent/reporting/reporting_utilities/response_handler'
+require 'contrast/agent/reporting/reporting_utilities/response'
+# Events
+require 'contrast/agent/reporting/reporting_events/finding'
+require 'contrast/agent/reporting/reporting_events/preflight_message'
+require 'contrast/agent/reporting/reporting_events/preflight'
+require 'contrast/agent/reporting/reporting_events/observed_route'
+require 'contrast/agent/reporting/reporting_events/route_coverage'
+require 'contrast/agent/reporting/reporting_events/observed_library_usage'
+require 'contrast/agent/reporting/reporting_events/poll'
+require 'contrast/agent/reporting/reporting_events/server_settings'
+# Sensitive data masking
+require 'contrast/agent/reporting/masker/masker'

data/lib/contrast/agent/reporting/reporter.rb

@@ -0,0 +1,165 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/agent/worker_thread'
+require 'contrast/agent/reporting/report'
+require 'contrast/components/logger'
+require 'contrast/agent/reporting/reporting_events/agent_startup'
+require 'contrast/agent/telemetry/events/exceptions/telemetry_exceptions'
+require 'contrast/agent/telemetry/events/exceptions/obfuscate'
+
+module Contrast
+  module Agent
+    # This module will hold everything essential to reporting to TeamServer
+    class Reporter < WorkerThread
+      include Contrast::Components::Logger::InstanceMethods
+      include Contrast::Utils::ObjectShare
+
+      MAX_QUEUE_SIZE = 1000
+
+      class << self
+        # check if we can report to TS
+        #
+        # @return[Boolean] true if bypass is enabled, or false if bypass disabled
+        def enabled?
+          @_enabled = ::Contrast::AGENT.enabled? if @_enabled.nil?
+          @_enabled
+        end
+      end
+
+      def client
+        @_client ||= Contrast::Agent::Reporting::ReporterClient.new
+      end
+
+      def connection
+        @_connection ||= client.initialize_connection
+      end
+
+      def start_thread!
+        return if running?
+
+        client.startup!(connection)
+        @_thread = Contrast::Agent::Thread.new do
+          logger.debug('Starting background Reporter thread.')
+          loop do
+            next unless connected?
+
+            process_event(queue.pop)
+          rescue StandardError => e
+            logger.debug('Reporter thread could not process because of:', e)
+          end
+        end
+      end
+
+      # Suspend the Reporter and try sending the event after the timeout.
+      # The timeout is either default 15 min or received via TS response.
+      #
+      # @param event [Contrast::Agent::Reporting::ReportingEvent] Freshly pop-ed event.
+      def handle_resend event
+        sleep(client.timeout) if client.sleep?
+        # Retry once than discard the event. This is trigger on too many events of
+        # same kind error.
+        client.send_event(event, connection) if client.mode.status == client.mode.resending
+        client.mode.reset_mode
+        client.wake_up
+      end
+
+      # @param event [Contrast::Agent::Reporting::ReportingEvent]
+      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 event
+
+        if queue.size >= MAX_QUEUE_SIZE
+          if Contrast::Agent::Telemetry::Base.enabled?
+            Contrast::Agent.thread_watcher.telemetry_queue.send_event(queue_limit_telemetry_event)
+          end
+
+          return
+        end
+
+        queue << event
+      end
+
+      # Use this to bypass the messaging queue and leave response processing to the caller
+      #
+      # @param event [Contrast::Agent::Reporting::ReportingEvent]
+      # @return [Net::HTTPResponse, nil]
+      def send_event_immediately event
+        if ::Contrast::AGENT.disabled?
+          logger.warn('Reporter attempted to send event immediately with Agent disabled', caller: caller, event: event)
+          return
+        end
+        return unless event
+
+        client.send_event(event, connection)
+      rescue StandardError => e
+        logger.error('Could not send message to TeamServer from Reporter queue.', e)
+      end
+
+      def delete_queue!
+        @_queue&.clear
+        @_queue&.close
+        @_queue = nil
+      end
+
+      def stop!
+        return unless running?
+
+        super
+        delete_queue!
+      end
+
+      private
+
+      def queue
+        @_queue ||= Queue.new
+      end
+
+      # TODO: RUBY-99999
+      # The client and connection are being used in multiple threads/ concurrently, and that's not okay. We need
+      # to figure out why that is and lock it so that it isn't.
+      #
+      # @return [Boolean]
+      def connected?
+        return true if client && connection
+
+        logger.debug('No client/connection; sleeping', client: client, connection: connection)
+        sleep(5)
+        false
+      end
+
+      # @param event [Contrast::Agent::Reporting::ReportingEvent]
+      def process_event event
+        client.send_event(event, connection)
+        handle_resend(event) if client.mode.status == client.mode.resending
+      rescue StandardError => e
+        logger.error('Could not send message to TeamServer from Reporter queue.', e)
+      end
+
+      # @return [Contrast::Agent::Telemetry::TelemetryException::Event]
+      def queue_limit_telemetry_event
+        message_exception = Contrast::Agent::Telemetry::TelemetryException::MessageException.build(
+            'String',
+            "Maximum queue size (#{ MAX_QUEUE_SIZE }) reached for reporting events", nil, stack_frame)
+        message = Contrast::Agent::Telemetry::TelemetryException::Message.build({}, [message_exception])
+        Contrast::Agent::Telemetry::TelemetryException::Event.new(message)
+      end
+
+      def stack_frame
+        stack_trace = caller_locations(20, 20)
+        stack_frame_type = if stack_trace.nil? || stack_trace[1].nil?
+                             'none'
+                           else
+                             Contrast::Agent::Telemetry::TelemetryException::Obfuscate.obfuscate_type(
+                                 stack_trace[1].path.delete_prefix(Dir.pwd))
+                           end
+
+        stack_frame_function = stack_trace.nil? || stack_trace[1].nil? ? 'none' : stack_trace[1].label
+        Contrast::Agent::Telemetry::TelemetryException::StackFrame.build(stack_frame_function, stack_frame_type, nil)
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/reporter_heartbeat.rb

@@ -0,0 +1,47 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/agent/reporting/reporter'
+require 'contrast/agent/inventory/dependency_usage_analysis'
+require 'contrast/agent/reporting/reporting_events/poll'
+
+module Contrast
+  module Agent
+    # The ReporterHeartbeat will make sure that the process remains marked alive by TeamServer and that we periodically
+    # reach out to get the latest settings for this application. It also sends out those messages which do not need to
+    # be associated directly with a request, such as Server Activity and Library Observation.
+    class ReporterHeartbeat < Reporter
+      # TeamServer will mark an application offline after 5 minutes. Sending this every one should be more than enough
+      # to satisfy our goals.
+      REFRESH_INTERVAL_SEC = 60
+
+      def start_thread!
+        return if running?
+
+        @_thread = Contrast::Agent::Thread.new do
+          logger.info('Starting heartbeat thread.')
+          loop do
+            polling_events.each do |event|
+              Contrast::Agent.reporter&.send_event(event)
+            end
+            clean_properties
+            sleep(REFRESH_INTERVAL_SEC)
+          end
+        end
+      end
+
+      private
+
+      def poll_message
+        @_poll_message ||= Contrast::Agent::Reporting::Poll.new
+      end
+
+      # Those events which should be sent periodically, rather than on event or request.
+      #
+      # @return [Array<Contrast::Agent::Reporting::ReportingEvent>]
+      def polling_events
+        [Contrast::Agent::Inventory::DependencyUsageAnalysis.instance.generate_library_usage, poll_message].compact
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/reporting_events/agent_startup.rb

@@ -0,0 +1,34 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/agent/reporting/reporting_events/server_reporting_event'
+require 'contrast/config'
+
+module Contrast
+  module Agent
+    module Reporting
+      #	AgentStartup Event which sends the agent data to TeamServer on the startup of a server or process,
+      # used to create a new Server entity there.
+      class AgentStartup < Contrast::Agent::Reporting::ServerReportingEvent
+        def initialize
+          @event_method = :PUT
+          @event_endpoint = Contrast::Agent::Reporting::Endpoints::NG_ENDPOINTS[:agent_startup]
+          @event_type = :agent_startup
+          super
+        end
+
+        def file_name
+          'agent-startup'
+        end
+
+        def to_controlled_hash
+          {
+              environment: ::Contrast::CONFIG.server.environment,
+              tags: ::Contrast::CONFIG.server.tags,
+              version: Contrast::Agent::VERSION
+          }
+        end
+      end
+    end
+  end
+end