contrast-agent 4.13.0 → 5.0.0

data/lib/contrast/agent/reporting/reporting_utilities/endpoints.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/components/logger'
+require 'contrast/utils/object_share'
+require 'base64'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This is the class which will hold up all the Endpoints we use for the direct report from the agent. It builds
+      # the full URLs needed for communication.
+      module Endpoints
+        extend Contrast::Components::Logger::InstanceMethods
+
+        APP_LANGUAGE = Contrast::Utils::ObjectShare::RUBY.upcase.cs__freeze
+        ENDPOINT_VERSION = '/v1.0'.cs__freeze
+        NG_ENDPOINTS = {
+            application_activity: "#{ Contrast::API.api_url }/api/ng/activity/application",
+            application_create: "#{ Contrast::API.api_url }/api/ng/applications/create",
+            agent_startup: "#{ Contrast::API.api_url }/api/ng/servers/"
+        }.cs__freeze
+
+        class << self
+          # @return [String,nil]
+          def application_startup
+            with_rescue do
+              "#{ application_endpoint }/startup".cs__freeze
+            end
+          end
+
+          # @return [String,nil]
+          def application_settings
+            with_rescue do
+              "#{ application_endpoint }/settings".cs__freeze
+            end
+          end
+
+          # @return [String,nil]
+          def application_inventory
+            with_rescue do
+              "#{ application_endpoint }/inventory".cs__freeze
+            end
+          end
+
+          # @return [String,nil]
+          def library_usage
+            with_rescue do
+              "#{ application_endpoint }/library-usage".cs__freeze
+            end
+          end
+
+          # @return [String,nil]
+          def heartbeat
+            with_rescue do
+              "#{ application_endpoint }/heartbeat".cs__freeze
+            end
+          end
+
+          # @return [String,nil]
+          def observed_route
+            # "/v1.0/routes/localhost///rails/ruby/observed"
+            with_rescue do
+              "#{ route_endpoint }/observed".cs__freeze
+            end
+          end
+
+          # @return [String,nil]
+          def trace_observed
+            with_rescue do
+              "#{ trace_endpoint }/observed".cs__freeze
+            end
+          end
+
+          private
+
+          # Returns the URL needed to connect to endpoints in TeamServer required for application related information.
+          #
+          # @return [String]
+          def application_endpoint
+            @_application_endpoint ||= "#{ Contrast::API.api_url }/agents#{ ENDPOINT_VERSION }/applications"\
+                                       "#{ server_path_segment }#{ application_path_segment }"
+          end
+
+          # Returns the URL needed to connect to endpoints in TeamServer required for route related information.
+          #
+          # @return [String]
+          def route_endpoint
+            @_route_endpoint ||= "#{ Contrast::API.api_url }/agents#{ ENDPOINT_VERSION }/routes"\
+                                 "#{ server_path_segment }#{ application_path_segment }"
+          end
+
+          # Returns the URL needed to connect to endpoints in TeamServer required for server related information.
+          #
+          # @return [String]
+          def server_endpoint
+            @_server_endpoint ||= "#{ Contrast::API.api_url }/agents#{ ENDPOINT_VERSION }/servers"\
+                                  "#{ server_path_segment }"
+          end
+
+          # Returns the URL needed to connect to endpoints in TeamServer required for trace/finding related information.
+          #
+          # @return [String]
+          def trace_endpoint
+            @_trace_endpoint ||= "#{ Contrast::API.api_url }/agents#{ ENDPOINT_VERSION }/traces"\
+                                 "#{ server_path_segment }#{ application_path_segment }"
+          end
+
+          # The server host, path, and type; required for endpoints that are server specific.
+          #
+          # @return [String]
+          def server_path_segment
+            @_server_path_segment ||= "/#{ Base64.urlsafe_encode64(server_host_name, padding: false) }"\
+                                      "/#{ Base64.urlsafe_encode64(server_path, padding: false) }"\
+                                      "/#{ Base64.urlsafe_encode64(server_type, padding: false) }"
+          end
+
+          # The application language and name; required for endpoints that are application specific.
+          #
+          # @return [String]
+          def application_path_segment
+            @_application_path_segment ||= "/#{ Base64.urlsafe_encode64(APP_LANGUAGE, padding: false) }"\
+                                           "/#{ Base64.urlsafe_encode64(app_name, padding: false) }"
+          end
+
+          # @return [String,nil]
+          def server_host_name
+            return @_server_host_name unless @_server_host_name.nil?
+
+            @_server_host_name = ::Contrast::APP_CONTEXT.server_name
+          end
+
+          # @return [String,nil]
+          def server_path
+            return @_server_path unless @_server_path.nil?
+
+            @_server_path = ::Contrast::APP_CONTEXT.server_path
+          end
+
+          # @return [String,nil]
+          def server_type
+            return @_server_type unless @_server_type.nil?
+
+            @_server_type = ::Contrast::APP_CONTEXT.server_type
+          end
+
+          # @return [String,nil]
+          def app_name
+            return @_app_name unless @_app_name.nil?
+
+            @_app_name = ::Contrast::APP_CONTEXT.app_name
+          end
+
+          # @return [String,nil]
+          def with_rescue
+            yield
+          rescue StandardError => e
+            logger.debug('Endpoint failed with the following error', e)
+            Contrast::Utils::ObjectShare::EMPTY_STRING
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# 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'
+require 'contrast/agent/version'
+require 'base64'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This class will build the required headers for agent reporting to TS
+      class Headers
+        attr_reader :app_name, :api_key, :agent_version, :app_language, :app_path, :app_version, :authorization,
+                    :server_name, :server_path, :server_type, :content_type, :encoding
+
+        ENCODING = 'base64'
+        CONTENT_TYPE = 'application/json'
+
+        include Contrast::Utils::ObjectShare
+
+        def initialize
+          @app_name = Base64.strict_encode64(Contrast::APP_CONTEXT.app_name)
+          @api_key = Contrast::API.api_key
+          @agent_version = [RUBY, Contrast::Agent::VERSION].join(SPACE)
+          @app_language = RUBY
+          @app_path = Base64.strict_encode64(Contrast::APP_CONTEXT.path)
+          @app_version = Contrast::APP_CONTEXT.app_version
+          @authorization = Base64.strict_encode64("#{ Contrast::API.username }:#{ Contrast::API.service_key }")
+          @server_name = Base64.strict_encode64(Contrast::APP_CONTEXT.server_name)
+          @server_path = Base64.strict_encode64(Contrast::APP_CONTEXT.server_path)
+          @server_type = Base64.strict_encode64(Contrast::APP_CONTEXT.server_type)
+          @content_type = CONTENT_TYPE
+          @encoding = ENCODING
+        end
+
+        def to_hash
+          {
+              app_name: @app_name,
+              api_key: @api_key,
+              agent_version: @agent_version,
+              app_language: @app_language,
+              app_path: @app_path,
+              app_version: @app_version,
+              authorization: @authorization,
+              server_name: @server_name,
+              server_path: @server_path,
+              server_type: @server_type,
+              content_type: @content_type,
+              encoding: @encoding
+          }.cs__freeze
+        end
+      end
+    end
+  end
+end

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