contrast-agent 4.14.0 → 5.2.0

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

@@ -0,0 +1,162 @@
+# 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
+
+        # @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
+
+          audit&.audit_event(corresponding_finding, response) if ::Contrast::API.request_audit_enable?
+          send_event(corresponding_finding, connection, true)
+          nil
+        rescue StandardError => e
+          logger.error('Unable to handle response', e)
+        end
+
+        private
+
+        # TODO: RUBY-1466 find better home for this?
+        def audit
+          @_audit ||= Contrast::Agent::Reporting::Audit.new
+        end
+
+        # 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
+      end
+    end
+  end
+end

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

@@ -1,4 +1,4 @@
-# Copyright (c) 2021 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
 
 require 'contrast/components/logger'

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('Unable to process response from TeamServer', e)
+          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,208 @@
+# 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]
+          return unless assessments
+
+          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]
+          return unless protect
+
+          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]
+          return unless exclusions
+
+          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]
+          return unless assess
+
+          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]
+          return unless protect
+
+          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]
+          return unless protect
+
+          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

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

@@ -0,0 +1,45 @@
+# 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
+      # This module will hold all the settings from the TS responce
+      module Settings
+        # Application level settings for the Assess featureset.
+        class Assess
+          # Assess rules to disable for this application.
+          #
+          # @return disabled_rules [Array<AssessRuleID>] Array with string rule_ids
+          def disabled_rules
+            @_disabled_rules ||= []
+          end
+
+          # @param disabled_rules [Array] with AssessRuleID strings
+          # @return disabled_rules [Array<AssessRuleID>] Array with string rule_ids
+          def disabled_rules= disabled_rules
+            @_disabled_rules = disabled_rules if disabled_rules.is_a? Array
+          end
+
+          # The id of a session on TeamServer under which this session of this application should report
+          # Overrides that set by application.session_id (should match if provided).
+          #
+          # @return session_id [String]
+          def session_id
+            @_session_id ||= Contrast::Utils::ObjectShare::EMPTY_STRING
+          end
+
+          # Set the session_id
+          #
+          # @param session_id [String]
+          # @return session_id [String]
+          def session_id= session_id
+            @_session_id = session_id if session_id.is_a? String
+          end
+        end
+      end
+    end
+  end
+end