contrast-agent 4.13.1 → 5.1.0

data/lib/contrast/agent/reporting/reporting_utilities/reporter_client.rb

@@ -0,0 +1,86 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'contrast/components/logger'
+require 'contrast/utils/net_http_base'
+require 'contrast/api/communication/connection_status'
+require 'contrast/agent/reporting/reporting_utilities/response_handler'
+require 'contrast/agent/reporting/reporting_utilities/reporter_client_utils'
+require 'contrast/agent/reporting/reporting_utilities/endpoints'
+require 'contrast/agent/reporting/reporting_utilities/headers'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This class creates a Net::HTTP client and initiates a connection to the provided result
+      # @attr_reader headers [Contrast::Agent::Reporting::Headers]
+      class ReporterClient < Contrast::Utils::NetHttpBase
+        attr_reader :headers
+
+        include Contrast::Agent::Reporting::Endpoints
+        include Contrast::Agent::Reporting::ReporterClientUtils
+        SERVICE_NAME = 'Reporter'
+        include Contrast::Components::Logger::InstanceMethods
+        # This method initializes the Net::HTTP client we'll need. it will validate
+        # the connection and make the first request. If connection is valid and response
+        # is available then the open connection is returned.
+        #
+        # @return [Net::HTTP, nil] Return open connection or nil
+        def initialize_connection
+          # for this client we would use proxy and custom certificate file if available
+          super(SERVICE_NAME, Contrast::API.api_url, true, true)
+        end
+
+        def initialize
+          @headers = Contrast::Agent::Reporting::Headers.new
+          super()
+        end
+
+        # Start the client for first time and sent startup event
+        #
+        # @param connection [Net::HTTP] open connection
+        def startup! connection
+          return if status.startup_messages_sent?
+          return unless Contrast::Agent::Reporter.enabled?
+
+          send_agent_startup(connection)
+        end
+
+        # Check event type and send it to appropriate TS endpoint
+        #
+        # @param event [Contrast::Api::Dtm,Contrast::Agent::Reporting::ReportingEvent] One of the DTMs valid
+        # for the event field of Contrast::Api::Dtm::Message|Contrast::Api::Dtm::Activity
+        # @param connection [Net::HTTP] open connection
+        # @param send_immediately [Boolean] flag for the logger
+        # @return response [Net::HTTP::Response, nil] response from TS if no response
+        def send_event event, connection, send_immediately = false
+          return unless Contrast::Agent::Reporter.enabled?
+
+          response = send_events(event, connection)
+          log_send_event event if send_immediately
+          response
+        rescue StandardError => e
+          handle_error event, e
+        end
+
+        def status
+          @_status ||= Contrast::Api::Communication::ConnectionStatus.new
+        end
+
+        def response_handler
+          @_response_handler ||= Contrast::Agent::Reporting::ResponseHandler.new
+        end
+
+        def sleep?
+          response_handler.sleep?
+        end
+
+        def wake_up
+          response_handler.wake_up
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/reporting_utilities/reporter_client_utils.rb

@@ -0,0 +1,154 @@
+# 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_utilities/reporter_client'
+require 'contrast/agent/reporting/reporting_utilities/endpoints'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This module holds utilities required by the reporting service client
+      module ReporterClientUtils
+        include Contrast::Components::Logger::InstanceMethods
+        include Contrast::Components::Scope::InstanceMethods
+        include Contrast::Agent::Reporting::Endpoints
+
+        private
+
+        # This method will build headers of the request required for TS communication
+        #
+        # @param request [Net::HTTPRequest]
+        def build_headers request
+          app_version = @headers.app_version
+          request['API-Key'] = @headers.api_key
+          request['Application-Language'] = @headers.app_language
+          request['Application-Name'] = @headers.app_name
+          request['Application-Path'] = @headers.app_path
+          request['Application-Version'] = app_version if app_version
+          request['Authorization'] = @headers.authorization
+          request['Content-Type'] = @headers.content_type
+          request['Server-Name'] = @headers.server_name
+          request['Server-Path'] = @headers.server_path
+          request['Server-Type'] = @headers.server_type
+          request['X-Contrast-Agent'] = @headers.agent_version
+          request['X-Contrast-Header-Encoding'] = @headers.encoding
+          request
+        end
+
+        # log the event sent immediately
+        #
+        # @param event [Contrast::Api::Dtm,Contrast::Agent::Reporting::ReportingEvent] One of the DTMs valid for the
+        # event field of Contrast::Api::Dtm::Message|Contrast::Api::Dtm::Activity
+        def log_send_event event
+          logger.debug("#{ Contrast::Agent::Reporting::ReporterClient::SERVICE_NAME } immediately sending event.",
+                       event_id: event.__id__, event_type: event.cs__class.cs__name)
+        end
+
+        # Handles standard error case, logs and set status for failure
+        #
+        # @param event [Contrast::Api::Dtm, Contrast::Agent::Reporting::ReportingEvent]
+        # One of the DTMs valid for the event field of Contrast::Api::Dtm::Message|Contrast::Api::Dtm::Activity
+        # @param error_msg [StandardError]
+        # @return nil [NilClass] to be passed as response
+        def handle_error event, error_msg
+          status.failure!
+          logger.error('Unable to send message.',
+                       error_msg,
+                       client: Contrast::Agent::Reporting::ReporterClient::SERVICE_NAME,
+                       event_id: event&.__id__,
+                       event_type: event&.cs__class&.cs__name)
+          nil
+        end
+
+        # Handles response processing and sets status
+        #
+        # @param response [Net::HTTP::Response]
+        # @return response [Net::HTTP::Response]
+        def process_response response
+          response_handler.process response
+          logger.debug('Successfully sent startup messages to service.')
+          status.success!
+          response
+        end
+
+        # build the request headers and assign endpoint
+        #
+        # @param event event [Contrast::Api::Dtm::AgentStartup, Contrast::Agent::Reporting::ReportingEvent]
+        # One of the DTMs valid for the event field of Contrast::Api::Dtm::Message|Contrast::Api::Dtm::Activity
+        # @return [Net::HTTP::Post,Net::HTTP::Put]
+        def build_request event
+          with_contrast_scope do
+            request = if event.cs__is_a?(Contrast::Agent::Reporting::ReportingEvent)
+                        case event.event_method
+                        when :PUT
+                          Net::HTTP::Put.new(event.event_endpoint)
+                        when :POST
+                          Net::HTTP::Post.new(event.event_endpoint)
+                        end
+                      else # TODO: RUBY-1438 -- remove
+                        Net::HTTP::Put.new(Contrast::Agent::Reporting::Endpoints::NG_ENDPOINTS[:agent_startup])
+                      end
+            build_headers(request)
+            if event.cs__is_a?(Contrast::Agent::Reporting::ReportingEvent)
+              event.attach_headers(request)
+              request.body = event.to_controlled_hash.to_json
+            else
+              request.body = event.to_json
+            end
+            request
+          end
+        end
+
+        # Send Agent Startup event
+        #
+        # @param connection [Net::HTTP] open connection
+        # @return response [Net::HTTP::Response] response from TS
+        def send_agent_startup connection
+          logger.debug('Preparing to send startup messages')
+          startup = Contrast::APP_CONTEXT.build_agent_startup_message
+          request = build_request(startup)
+          response = connection.request(request)
+          process_response(response)
+        rescue StandardError => e
+          handle_error(startup, e)
+        end
+
+        # Sent different events to different endpoints
+        #
+        # @param event [Contrast::Api::Dtm,Contrast::Agent::Reporting::ReportingEvent] Main reporting event, all events
+        # inherit it
+        # @param connection [Net::HTTP] open connection
+        def send_events event, connection
+          request = build_request(event)
+          response = connection.request(request)
+          process_response(response)
+        rescue StandardError => e
+          handle_error(event, e)
+        end
+
+        # Eventually here we'll handle more response types and etc
+
+        # @param event [Contrast::Agent::Reporting::Preflight] the preflight we handle here
+        # @param response [Net::HTTP::Response,nil] The response we handle and read from
+        # @param connection [Net::HTTP] open connection
+        def handle_response event, response, connection
+          return unless event || response || connection
+          return unless event.cs__is_a?(Contrast::Agent::Reporting::Preflight)
+
+          preflight_message = event.messages[0]
+          # for handling multiple findings
+          # we'll only extract the indexes without *
+          # findings_to_return = response.body.split(',').delete_if { |el| el.include?('*') }
+          # after that we'll do some magic and return them the same way we do for corresponding_finding
+          corresponding_finding = Contrast::Agent::Reporting::ReportingStorage.delete(preflight_message.hash_code)
+          return unless corresponding_finding
+
+          send_event corresponding_finding, connection, true
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/reporting_utilities/reporting_storage.rb

@@ -0,0 +1,66 @@
+# 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
+    module Reporting
+      # This module will be used to store everything that would be sent
+      # and depends on the response we receive
+      module ReportingStorage
+        class << self
+          include Contrast::Components::Logger::InstanceMethods
+
+          # So the collection will be used to store those events
+          def collection
+            @_collection ||= {}
+          end
+
+          # @param key[String] the key for the pair
+          # @param value[Object] the value we need to store
+          # @return [Object] the value we saved
+          def []= key, value
+            return unless key
+            return unless value
+
+            logger.debug('Saving new value', key: key)
+
+            key = key.to_s.downcase.strip
+            collection[key] = value
+
+            value # rubocop:disable Lint/Void
+          end
+
+          # @param key[String] the key for the pair
+          def [] key
+            return unless key
+
+            collection[key]
+          end
+          alias_method :get, :[]
+          alias_method :set, :[]=
+
+          def delete key
+            return unless key
+
+            logger.debug('Starting deleting value for', key: key)
+
+            deleted_value = collection.delete(key)
+            logger.debug('Key wasn\'t found') unless deleted_value
+
+            deleted_value
+          end
+
+          # @param rule_id [String] the rule_id
+          # @return [Hash, nil] return array with key and value of the pair
+          def find_by_rule_id rule_id
+            return unless rule_id
+
+            collection.find { |_, v| v.rule_id == rule_id }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/reporting_utilities/response.rb

@@ -0,0 +1,30 @@
+# 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/settings/application_settings'
+require 'contrast/agent/reporting/settings/server_features'
+
+module Contrast
+  module Agent
+    module Reporting
+      # this class will hold the response from TS
+      class Response
+        # All of the settings from TeamServer that apply at the application level.
+        # At least one, but not necessarily all, setting will differ from the agent's current set.
+        # Agents are able to replace all application settings with those in this message.
+        #
+        # @return application_settings [Contrast::Agent::Reporting::Settings::ApplicationSettings]
+        def application_settings
+          @_application_settings ||= Contrast::Agent::Reporting::Settings::ApplicationSettings.new
+        end
+
+        # All of the feature server_features
+        #
+        # @return server_features [Contrast::Agent::Reporting::Settings::FeatureSettings]
+        def server_features
+          @_server_features ||= Contrast::Agent::Reporting::Settings::ServerFeatures.new
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/reporting_utilities/response_handler.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
+
+require 'contrast/api/communication/response_processor'
+require 'contrast/api/decorators/application_settings'
+require 'contrast/agent/reporting/reporting_utilities/response'
+require 'contrast/agent/reporting/reporting_utilities/response_handler_utils'
+require 'contrast/api/decorators/server_features'
+require 'contrast/components/logger'
+require 'json'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This class will facilitate the Response capture and analysis functionality.
+      class ResponseHandler < Contrast::Api::Communication::ResponseProcessor
+        include Contrast::Components::Logger::InstanceMethods
+        include Contrast::Agent::Reporting::ResponseHandlerUtils
+        # Process the response from TS
+        #
+        # @param response [Net::HTTP::Response, nil]
+        # @return response [Net::HTTP::Response, nil]
+        def process response
+          logger.debug('Reporter Received a response')
+          return unless analyze_response_code? response&.code
+
+          # handle the response body and obtain server_features or app_settings
+          report_response = convert_response response
+
+          return unless report_response
+
+          update_agent_settings report_response
+          update_reaction report_response
+          # this one is called from super needs to be placed here after protobuf
+          update_features report_response.server_features, report_response.application_settings
+          logger.trace('Agent settings updated in response to Service', protect_on: ::Contrast::PROTECT.enabled?,
+                                                                        assess_on: ::Contrast::ASSESS.enabled?)
+          response
+        rescue StandardError => e
+          logger.error(e.message)
+          nil
+        end
+
+        # if sleep is true puts reporting service to sleep
+        def sleep?
+          @_sleep = wake_up if @_sleep.nil?
+          @_sleep
+        end
+
+        # wakes the reporting service
+        def wake_up
+          @_sleep = false
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/reporting_utilities/response_handler_utils.rb

@@ -0,0 +1,196 @@
+# 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
+      # This module holds utilities required by the reporting service response handler
+      module ResponseHandlerUtils
+        ANALYZE_WHEN = '200'
+        SLEEP_WHEN = %w[401 408 500].cs__freeze
+
+        private
+
+        # check if response code is valid before analyze it
+        #
+        # @param response_code [Integer]
+        # @return [Boolean]
+        def analyze_response_code? response_code
+          # 200 Successful recording of the server record on the database. FeatureSet successfully returned
+          # 401:
+          # If any authentication errors occur. Agents should enter a suspended mode
+          # (no reporting) and attempt to reconnect in 15 minutes.
+          # 408:
+          # If the FeatureSet from TeamServer cannot be constructed in time.
+          # Agents should enter a suspended mode (no reporting) and attempt to reconnect in 15 minutes.
+          # 500:
+          # If any server error occurs. Agents should enter a suspended mode
+          # (no reporting) and attempt to reconnect in 15 minutes.
+          # 204, 304
+          # Successful update of the server record on the database.
+          # No FeatureSet update since the last time an activity was sent.
+          @_sleep = true if SLEEP_WHEN.include? response_code
+          return true if ANALYZE_WHEN.include? response_code
+
+          false
+        end
+
+        # Applies the settings from the TS response
+        #
+        # @param response [Contrast::Agent::Reporting::Response]
+        def update_agent_settings response
+          if response.server_features
+            log_file = response.server_features.log_file
+            log_level = response.server_features.log_level
+            Contrast::Logger::Log.instance.update(log_file, log_level) if log_file && log_level
+            Contrast::SETTINGS.update_from_server_features(response)
+          end
+          Contrast::SETTINGS.update_from_application_settings(response) if response.application_settings
+        end
+
+        # Process the given Reactions from the application settings based on what
+        # TeamServer has indicated. Each Reaction will result in a log message
+        # and, optionally, an action.
+        #
+        # @param response [Contrast::Agent::Reporting::Response]
+        def update_reaction response
+          return unless response.application_settings.reactions.any?
+
+          response.application_settings.reactions.each do |reaction|
+            # The enums are all uppercase, we need to downcase them before attempting to log.
+            level = if reaction.level.nil?
+                      :error
+                    else
+                      reaction.level.downcase
+                    end
+
+            logger.with_level(level, reaction.message) if reaction.message
+
+            case reaction.operation
+            when Contrast::Agent::Reporting::Settings::Reaction::OPERATIONS.second
+              # DISABLED
+              Contrast::Agent::DisableReaction.run reaction, level
+            when Contrast::Agent::Reporting::Settings::Reaction::OPERATIONS.first
+              # NOOP
+            else
+              logger.warn('ReactionProcessor received a reaction with an unknown operation',
+                          operation: reaction.operation)
+            end
+          end
+        end
+
+        # Converts response from Net to Reporting Response object
+        #
+        # @param response [Net::HTTP::Response, nil]
+        # @return response [Contrast::Agent::Reporting::Response]
+        def convert_response response
+          response_body = response&.body
+          return unless response_body
+
+          response_data = JSON.parse(response_body)
+          return unless response_data.cs__is_a?(Hash)
+
+          response_data = response_data.deep_symbolize_keys
+          # check if response contains application settings or Feature settings
+          if response_data[:settings]
+            # the response contains ApplicationSettings
+            logger.trace('Agent: Received updated application settings')
+            build_application_settings response_data
+          else
+            # the response contains FeatureSettings
+            logger.trace('Agent: Received updated server features')
+            build_feature_settings response_data
+          end
+        rescue StandardError => e
+          logger.error('Unable to convert response', e)
+          nil
+        end
+
+        # @param response_data [Hash]
+        # @return res [Contrast::Agent::Reporting::Response]
+        def build_application_settings response_data
+          res = Contrast::Agent::Reporting::Response.new
+          extract_assess response_data, res
+          extract_protect response_data, res
+          extract_exclusions response_data, res
+          extract_reactions response_data, res
+          res
+        end
+
+        # @param response_data [Hash]
+        # @return res [Contrast::Agent::Reporting::Response]
+        def build_feature_settings response_data
+          res = Contrast::Agent::Reporting::Response.new
+          extract_assess_server_features response_data, res
+          extract_protect_server_features response_data, res
+          extract_protect_lists response_data, res
+          res.server_features.log_level = response_data[:logLevel]
+          res.server_features.log_file = response_data[:logFile]
+          res.server_features.telemetry = response_data[:telemetry]
+          res
+        end
+
+        # @param response_data [Hash]
+        # @return res [Contrast::Agent::Reporting::Response]
+        def extract_assess response_data, res
+          assessments = response_data[:settings][:assessment]
+          res.application_settings.assess.disabled_rules = assessments[:disabledRules]
+          res.application_settings.assess.session_id = assessments[:session_id]
+        end
+
+        # @param response_data [Hash]
+        # @return res [Contrast::Agent::Reporting::Response]
+        def extract_protect response_data, res
+          protect = response_data[:settings][:defend]
+          res.application_settings.protect.protection_rules = protect[:protectionRules]
+          res.application_settings.protect.virtual_patches = protect[:virtualPatches]
+        end
+
+        # @param response_data [Hash]
+        # @return res [Contrast::Agent::Reporting::Response]
+        def extract_exclusions response_data, res
+          exclusions = response_data[:settings][:exceptions]
+          res.application_settings.exclusions.code_exclusions = exclusions[:codeExceptions]
+          res.application_settings.exclusions.input_exclusions = exclusions[:inputExceptions]
+          res.application_settings.exclusions.url_exclusions = exclusions[:urlExceptions]
+        end
+
+        # @param response_data [Hash]
+        # @return res [Contrast::Agent::Reporting::Response]
+        def extract_reactions response_data, res
+          res.application_settings.reactions = response_data[:settings][:reactions]
+        end
+
+        # @param response_data [Hash]
+        # @return res [Contrast::Agent::Reporting::Response]
+        def extract_assess_server_features response_data, res
+          assess = response_data[:assessment]
+          res.server_features.assess.enabled = assess[:enabled]
+          res.server_features.assess.disabled_rules = assess[:disabledRules]
+          res.server_features.assess.sampling = assess[:sampling]
+          res.server_features.assess.sanitizers = assess[:sanitizers]
+          res.server_features.assess.validators = assess[:validators]
+        end
+
+        # @param response_data [Hash]
+        # @return res [Contrast::Agent::Reporting::Response]
+        def extract_protect_server_features response_data, res
+          protect = response_data[:defend]
+          res.server_features.protect.enabled = protect[:enabled]
+          res.server_features.protect.bot_blocker = protect[:bot_blocker]
+          res.server_features.protect.syslog = protect[:syslog]
+        end
+
+        # @param response_data [Hash]
+        # @return res [Contrast::Agent::Reporting::Response]
+        def extract_protect_lists response_data, res
+          protect = response_data[:defend]
+          res.server_features.protect.ip_allowlist = protect[:ipAllowlist]
+          res.server_features.protect.ip_denylist = protect[:ipDenyList]
+          res.server_features.protect.log_enchancers = protect[:logEnhancers]
+          res.server_features.protect.rule_definition_list = protect[:ruleDefinitionList]
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/settings/application_settings.rb

@@ -0,0 +1,67 @@
+# 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/settings/assess'
+require 'contrast/agent/reporting/settings/protect'
+require 'contrast/agent/reporting/settings/exclusions'
+require 'contrast/agent/reporting/settings/reaction'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This module will hold all the settings from the TS responce
+      module Settings
+        # All of the settings from TeamServer that apply at the application level.
+        # At least one, but not necessarily all, setting will differ from the agent's current set.
+        # Agents are able to replace all application settings with those in this message.
+        class ApplicationSettings
+          # Application level settings for the Assess featureset
+          #
+          # @return assess [Contrast::Agent::Reporting::Settings::Assess]
+          def assess
+            @_assess ||= Contrast::Agent::Reporting::Settings::Assess.new
+          end
+
+          # Application level settings for the Protect featureset
+          #
+          # @return protect [Contrast::Agent::Reporting::Settings::Protect]
+          def protect
+            @_protect ||= Contrast::Agent::Reporting::Settings::Protect.new
+          end
+
+          # Array of all the exclusions
+          #
+          # @return exclusions [Contrast::Agent::Reporting::Settings::Exclusions]
+          def exclusions
+            @_exclusions ||= Contrast::Agent::Reporting::Settings::Exclusions.new
+          end
+
+          # Reaction the agent should take based on a state in TS.
+          #
+          # @return [Array<Contrast::Agent::Reporting::Settings::Reaction>, nil]
+          def reactions
+            @_reactions
+          end
+
+          # Set the reaction
+          #
+          # @param reactions [Array<Reaction>] {
+          #   level     [String] The level at which the agent should log this reaction.
+          #                      [ERROR, WARN, INFO, DEBUG, TRACE]
+          #   message   [String] A message to log when receiving this reaction.
+          #   operation [String] What to do in response to this reaction.[NOOP, DISABLE] }
+          # @return [Array<Contrast::Agent::Reporting::Settings::Reaction>]
+          def reactions= reactions
+            return unless reactions.is_a? Array
+
+            @_reactions = []
+            reactions.each do |r|
+              reaction = Contrast::Agent::Reporting::Settings::Reaction.new(r[:level], r[:operation], r[:message])
+              @_reactions << reaction
+            end
+          end
+        end
+      end
+    end
+  end
+end