contrast-agent 4.13.0 → 5.0.0

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

@@ -0,0 +1,75 @@
+# 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/reporting_events/reporting_event'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This is the new PreflightMessage class which will include all the needed information for the new reporting
+      # system to report a single message, part of the main Preflight, to TeamServer. This message represents the
+      # identifying information of a Finding/Trace, which TeamServer will use to determine if it requires the full
+      # information of the Finding/Trace to be reported.
+      #
+      # @attr_accessor data [String] the message identifier; rule_id,hash
+      # @attr_accessor hash_code [String]
+      # @attr_reader routes [Array<Contrast::Agent::Reporting::RouteDiscovery] the route that triggered the finding
+      #   to which this preflight applies.
+      class PreflightMessage
+        attr_accessor :data, :hash_code
+        attr_reader :routes
+
+        # The type of this event, as understood by TeamServer. While TRACE and APPUPDATE are both technically valid, we
+        # only use the TRACE type.
+        CODE = :TRACE
+
+        def initialize
+          @app_language = Contrast::Utils::ObjectShare::RUBY
+          @app_name = ::Contrast::APP_CONTEXT.app_name
+          @app_version = ::Contrast::APP_CONTEXT.app_version
+          @routes = []
+          @agent_session_id_value = Contrast::APP_CONTEXT.session_id
+        end
+
+        # Convert the instance variables on the class, and other information, into the identifiers required for
+        # TeamServer to process the JSON form of this message.
+        #
+        # @return [Hash]
+        # @raise [ArgumentError]
+        def to_controlled_hash
+          validate
+          {
+              code: CODE,
+              app_language: @app_language,
+              app_name: @app_name,
+              app_version: @app_version,
+              data: '',
+              key: 0,
+              routes: @routes,
+              session_id: @agent_session_id_value
+          }
+        end
+
+        def validate
+          raise(ArgumentError, "#{ cs__class } did not have a proper data. Unable to continue.") unless data
+          raise(ArgumentError, "#{ cs__class } did not have a proper routes. Unable to continue.") if routes.empty?
+          unless @app_name
+            raise(ArgumentError, "#{ cs__class } did not have a proper application name. Unable to continue.")
+          end
+          unless @app_language
+            raise(ArgumentError, "#{ cs__class } did not have a proper application language. Unable to continue.")
+          end
+          unless @app_version
+            raise(ArgumentError, "#{ cs__class } did not have a proper application version. Unable to continue.")
+          end
+          unless @agent_session_id_value
+            raise(ArgumentError, "#{ cs__class } did not have a proper session id. Unable to continue.")
+          end
+
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/reporting_events/reporting_event.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/components/logger'
+require 'contrast/utils/assess/trigger_method_utils'
+require 'contrast/agent/reporting/reporting_utilities/endpoints'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This is the new ReportingEvent class which will include all the needed and mutual information for the new
+      # reporting system.
+      #
+      # @abstract
+      # @attr_reader routes [Array]
+      # @attr_reader event_method [Symbol] the HTTP method to use to send this event
+      class ReportingEvent
+        attr_reader :event_endpoint, :event_method
+
+        def initialize
+          @agent_session_id_value = 0 # TODO: RUBY-99999 Contrast::APP_CONTEXT.session_id once we have app start
+          @event_endpoint ||= nil
+          @event_method ||= :POST
+        end
+
+        # Some reports require specific additional headers to be used. To that end, we'll attach them here, letting
+        # each handle their own.
+        #
+        # @param _request [Net::HTTPRequest]
+        def attach_headers _request; end
+
+        # Convert the instance variables on the class, and other information, into the identifiers required for
+        # TeamServer to process the JSON form of this message.
+        #
+        # @return [Hash]
+        # @raise [ArgumentError]
+        def to_controlled_hash
+          validate
+          {}
+        end
+
+        # @raise [ArgumentError]
+        def validate; end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'json'
+require 'contrast/components/logger'
+require 'contrast/agent/reporting/reporting_events/reporting_event'
+require 'contrast/utils/object_share'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This is the new Route Coverage class which will include all the needed information for the new reporting system
+      # to relay this information in the Route Observation messages. These observations are used by TeamServer to
+      # construct the route coverage information for the assess feature. They represent those methods which map to
+      # externally accessible endpoints within the application, as registered to the application framework. This also
+      # includes the literal URL and HTTP Verb used to invoke them, as they must have been called at this point to be
+      # recorded.
+      #
+      # @attr_accessor route [String] the method signature used to uniquely identify the coverage report.
+      # @attr_accessor url [String] the normalized URL used to access the method in the route.
+      # @attr_accessor verb [String] the HTTP Verb used  to access the method in the route.
+      # @attr_accessor count [Integer] the number of times this was hit; no longer needed as it can be derived.
+      class RouteCoverage
+        attr_accessor :route, :url, :verb, :count
+
+        def initialize
+          @route = Contrast::Utils::ObjectShare::EMPTY_STRING
+          @verb = Contrast::Utils::ObjectShare::EMPTY_STRING
+          @url = Contrast::Utils::ObjectShare::EMPTY_STRING
+          @count = 0
+        end
+
+        def attach_rack_based_data final_controller, method, route_pattern, url = nil
+          if route_pattern.cs__is_a?(Grape::Router::Route)
+            safe_pattern = route_pattern.pattern&.path&.to_s
+            safe_url = source_or_string(url || safe_pattern)
+          else
+            safe_pattern = source_or_string(route_pattern)
+            safe_url = source_or_string(url || route_pattern)
+          end
+
+          self.route = "#{ final_controller }##{ method } #{ safe_pattern }"
+          self.verb = Contrast::Utils::StringUtils.force_utf8(method)
+          self.url = Contrast::Utils::StringUtils.force_utf8(safe_url)
+          self
+        end
+
+        # Convert ActionDispatch::Journey::Route to Contrast::Agent::Reporting::RouteCoverage
+        #
+        # @param journey_obj [ActionDispatch::Journey::Route] a rails route
+        # @param url [String, nil] use url from string instead of journey object.
+        # @return [Contrast::Agent::Reporting::RouteCoverage]
+        def attach_rails_data journey_obj, url = nil
+          self.route = "#{ journey_obj.defaults[:controller] }##{ journey_obj.defaults[:action] }"
+
+          verb = source_or_string(journey_obj.verb)
+          self.verb = Contrast::Utils::StringUtils.force_utf8(verb)
+
+          url ||= source_or_string(journey_obj.path.spec)
+          self.url = Contrast::Utils::StringUtils.force_utf8(url)
+          self
+        end
+
+        def source_or_string obj
+          if obj.cs__is_a?(Regexp)
+            obj.source
+          elsif obj.cs__respond_to?(:safe_string)
+            obj.safe_string
+          else
+            obj.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/reporting_events/route_discovery.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/agent/reporting/reporting_events/route_discovery_observation'
+require 'contrast/api/dtm.pb'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This is the new Route Discovery class which will include all the needed information for the new reporting
+      # system to relay this information in the Application Update messages. These discoveries are used by TeamServer
+      # to construct the route coverage information for the assess feature. They represent those methods which map to
+      # externally accessible endpoints within the application, as registered to the application framework. They may or
+      # may not have been invoked at the time of reporting.
+      #
+      # @attr_reader observations [observations] the routes and verbs seen that match to this Route
+      # @attr_reader signature [String] the unique identifier for this route; typically the method signature. Required
+      #   for reporting.
+      class RouteDiscovery
+        # required attributes
+        attr_reader :observations, :signature
+
+        class << self
+          # Convert a DTM for SpeedRacer to an Event for TeamServer.
+          #
+          # @param route_coverage_dtm [Contrast::Api::Dtm::RouteCoverage]
+          # @return [Contrast::Agent::Reporting::RouteDiscovery]
+          def convert route_coverage_dtm
+            report = new
+            report.attach_data(route_coverage_dtm)
+            report
+          end
+        end
+
+        # Attach the data from the protobuf models to this reporter so that it can be sent to TeamServer directly
+        #
+        # @param route_coverage_dtm [Contrast::Api::Dtm::RouteCoverage]
+        def attach_data route_coverage_dtm
+          @signature = route_coverage_dtm.route
+          @observations = []
+          observations << Contrast::Agent::Reporting::RouteDiscoveryObservation.convert(route_coverage_dtm)
+        end
+
+        # Convert the instance variables on the class, and other information, into the identifiers required for
+        # TeamServer to process the JSON form of this message.
+        #
+        # @return [Hash]
+        # @raise [ArgumentError]
+        def to_controlled_hash
+          validate
+          {
+              observations: @observations.map(&:to_controlled_hash),
+              signature: @signature
+          }
+        end
+
+        # Ensure the required fields are present.
+        #
+        # @raise [ArgumentError]
+        def validate
+          raise(ArgumentError, "#{ self } did not have a proper signature. Unable to continue.") unless signature
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/api/dtm.pb'
+require 'contrast/utils/string_utils'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This is the new Route Discovery Observation class which will include all the needed information for the new
+      # reporting system to relay this information in the Application Update messages. These route observations are
+      # used by TeamServer to construct the route coverage information for the assess feature. They represent the
+      # literal URL and HTTP verb used to invoke a method in the application, as routed by the application framework.
+      #
+      # @attr_reader url [String] the URL requested to hit this endpoint. Required for reporting.
+      # @attr_reader verb [String] the HTTP Method requested to his this endpoint. Empty means all, so is allowed.
+      #   for reporting.
+      class RouteDiscoveryObservation
+        # required attributes
+        attr_reader :url
+        # optional attributes
+        attr_reader :verb
+
+        class << self
+          # Convert a DTM for SpeedRacer to an Event for TeamServer.
+          #
+          # @param route_coverage_dtm [Contrast::Api::Dtm::RouteCoverage]
+          # @return [Contrast::Agent::Reporting::RouteDiscoveryObservation]
+          def convert route_coverage_dtm
+            report = new
+            report.attach_data(route_coverage_dtm)
+            report
+          end
+        end
+
+        # Attach the data from the protobuf models to this reporter so that it can be sent to TeamServer directly
+        #
+        # @param route_coverage_dtm [Contrast::Api::Dtm::RouteCoverage]
+        def attach_data route_coverage_dtm
+          @url = route_coverage_dtm.url
+          @verb = route_coverage_dtm.verb if Contrast::Utils::StringUtils.present?(route_coverage_dtm.verb)
+        end
+
+        # Convert the instance variables on the class, and other information, into the identifiers required for
+        # TeamServer to process the JSON form of this message.
+        #
+        # @return [Hash]
+        # @raise [ArgumentError]
+        def to_controlled_hash
+          validate
+          hash = { url: url }
+          hash[:verb] = verb if verb
+          hash
+        end
+
+        # Ensure the required fields are present.
+        #
+        # @raise [ArgumentError]
+        def validate
+          raise(ArgumentError, "#{ self } did not have a proper url. Unable to continue.") unless url
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/agent/reporting/reporting_events/reporting_event'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This class will initialize empty ServerActivity body to be send to TS.
+      # The server activity endpoint records actions taken on the serveror process as a whole.
+      # It currently only reports the number of times a defensive action was taken and is most
+      # likely not populated by most agents. The main purpose of sending this message is for its
+      # response, which contains any updated server feature settings from TeamServer.
+      # The new Server Settings endpoint should let us remove this.
+      class ServerActivity < Contrast::Agent::Reporting::ReportingEvent
+        class << self
+          # @param _server_activity_dtm [Contrast::Api::Dtm::ServerActivity]
+          # @return [Contrast::Agent::Reporting::ServerActivity]
+          def convert _server_activity_dtm
+            new
+          end
+        end
+
+        def initialize
+          @event_method = :PUT
+          @event_endpoint = "#{ Contrast::API.api_url }/api/ng/activity/servers"
+          super
+        end
+
+        # Convert the instance variables on the class, and other information, into the identifiers required for
+        # TeamServer to process the JSON form of this message.
+        #
+        # @return [Hash]
+        # @raise [ArgumentError]
+        def to_controlled_hash
+          { lastUpdate: timestamp }
+        end
+
+        private
+
+        # The timestamp field is a bit of a misnomer. It's really the time, in ms, since the settings for this
+        # server have been updated.
+        #
+        # @return [Integer]
+        def timestamp
+          Contrast::Utils::Timer.now_ms -
+              (Contrast::Agent.reporter&.client&.response_handler&.last_server_update_ms || 0)
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/reporting_events/trace_event_source.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 'json'
+require 'contrast/components/logger'
+require 'contrast/utils/object_share'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This is the new Trace Event Source class which will include all the needed information for the new reporting
+      # system to relay this information in the Route Observation messages.
+      class TraceEventSource
+        attr_accessor :name, :type
+
+        def initialize
+          @name = Contrast::Utils::ObjectShare::EMPTY_STRING
+          @type = Contrast::Utils::ObjectShare::EMPTY_STRING
+        end
+
+        def to_controlled_hash
+          {
+              name: @name,
+              type: @type
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,137 @@
+# 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 'fileutils'
+require 'json'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This class will facilitate the Audit functionality and it will be
+      # controlled from the configuration classes
+      class Audit
+        include Contrast::Components::Logger::InstanceMethods
+
+        attr_reader :path_for_requests, :path_for_responses
+
+        def initialize
+          generate_paths if enabled? && Contrast::CONTRAST_SERVICE.use_agent_communication?
+        end
+
+        # This method will be handling the auditing of the requests and responses we send to SpeedRacer. If the audit
+        # feature is enabled, we'll log to file the request and/or response protobuf objects.
+        #
+        # @param event [Contrast::Api::Dtm|Contrast::Agent::Reporting::ReportingEvent] One of the DTMs valid for the
+        #   event field of Contrast::Api::Dtm::Message|Contrast::Agent::Reporting::ReportingEvent
+        # @param response_data [Contrast::Api::Settings::AgentSettings,nil]
+        def audit_event event, response_data = nil
+          return unless ::Contrast::API.request_audit_requests? || ::Contrast::API.request_audit_responses?
+
+          type = event.cs__respond_to?(:file_name) ? event.file_name : event.cs__class.cs__name.to_s.downcase
+          if ::Contrast::API.request_audit_requests?
+            data = if event.cs__class < Contrast::Agent::Reporting::ReportingEvent
+                     event.to_controlled_hash.to_json
+                   else # TODO: RUBY-1438 -- remove
+                     event.to_s
+                   end
+            log_data :request, type, data if data
+          end
+          return unless ::Contrast::API.request_audit_responses?
+
+          data = response_data.to_s || event.http_response.try(:body) || 'There is no available response'
+          log_data :response, type, data
+        end
+
+        private
+
+        # This method will proceed with passing the data with to the writing method
+        # @param type [Symbol] This is the type of the file /:request, :response/
+        # @param data_type[String] DTM type String representation
+        # @param data[String] String representation if the logged data
+        def log_data type, data_type, data = nil
+          return unless enabled?
+          return unless Contrast::CONTRAST_SERVICE.use_agent_communication?
+
+          write_to_file type, data_type, data
+        end
+
+        # This method will be actually writing to the file
+        # @param type [Symbol] This is the type of the file /:request, :response/
+        # @param data_type [String] Data type /Activity/Finding../
+        # @param data [any] The data to be written to the file
+        def write_to_file type, data_type, data = nil
+          time = Time.now.to_i
+          destination = type == :request ? path_for_requests : path_for_responses
+          # If the feature is disabled or we have yet to create the directory structure, then we could have a nil
+          # destination. In that case, take no action
+          return unless destination
+
+          filename = "#{ time }-#{ Thread.current.object_id }-#{ data_type.gsub('::', '_') }-teamserver.json"
+          filepath = File.join(destination, filename)
+          # Here is use append mode, because of a slightly possibility of overwriting an existing file
+          File.open(filepath, 'a') do |f|
+            if data_type.include?('reporting')
+              f.write(Contrast::Utils::StringUtils.force_utf8(data))
+            else
+              f.write({ data_type: Contrast::Utils::StringUtils.force_utf8(data) }.to_json)
+            end
+          end
+        rescue StandardError => e
+          logger.warn('Saving audit failed', e: e)
+        end
+
+        # Here we will generate the directories for the requests and responses
+        def generate_paths
+          message_directories = File.expand_path(path_to_audits)
+          FileUtils.mkdir_p(message_directories) unless Dir.exist?(message_directories)
+
+          requests_destination = File.expand_path(File.join(message_directories, '/requests'))
+          responses_destination = File.expand_path(File.join(message_directories, '/responses'))
+
+          Dir.mkdir(requests_destination) if enabled_for_requests? && !Dir.exist?(requests_destination)
+          Dir.mkdir(responses_destination) if enabled_for_responses? && !Dir.exist?(responses_destination)
+
+          @path_for_requests ||= requests_destination if enabled_for_requests?
+          @path_for_responses ||= responses_destination if enabled_for_responses?
+        rescue StandardError => e
+          logger.warn('Generating the paths failed with: ', e: e)
+        end
+
+        # Retrieves the configuration value if the request audit is enabled
+        # @return [Boolean]
+        def enabled?
+          ::Contrast::API.request_audit_enable?
+        end
+
+        # The boolean values for the requests and the responses should be taken under
+        # consideration only if it's in combination with enabled
+        # So in order for us to actually audit the requests, we need:
+        # - enabled? -> ture and enabled_for_requests? -> true
+        # The same is for the responses
+        #
+        #
+        # Retrieve the configuration value if the audit for requests is enabled
+        # @return [Boolean]
+        def enabled_for_requests?
+          ::Contrast::API.request_audit_requests?
+        end
+
+        # Retrieve the configuration value if the audit for responses is enabled
+        # @return [Boolean]
+        def enabled_for_responses?
+          ::Contrast::API.request_audit_requests?
+        end
+
+        # Retrieve the configuration value for the path of the audits
+        # The value will be read from the configuration yml
+        # but if it isn't defined any - here will be returned the default path from
+        # Contrast::Config::RequestAuditConfiguration::DEFAULT_PATH
+        # @return [String]
+        def path_to_audits
+          ::Contrast::API.request_audit_path
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/reporting_utilities/dtm_message.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/reporting_events/server_activity'
+require 'contrast/api/dtm.pb'
+
+module Contrast
+  module Agent
+    module Reporting
+      # Util module for checking DTM message type. It temporarily allows for the conversion from a DTM to an
+      # EventReport.
+      # TODO: RUBY-1438 -- remove
+      module DtmMessage
+        class << self
+          # Checks if the message is of Contrast::Api::Dtm::ServerActivity class
+          #
+          # @param dtm [Contrast::Api::Dtm::ServerActivity, Object]
+          # @return [Boolean]
+          def server_activity? dtm
+            dtm.cs__is_a?(Contrast::Api::Dtm::ServerActivity)
+          end
+
+          # Checks if the message is a Hash of Contrast::Api::Dtm::LibraryUsageUpdate class
+          #
+          # @param message [Protobuf::Field::FieldHash<String,::Contrast::Api::Dtm::LibraryUsageUpdate>]
+          # @return [Boolean]
+          def library_usage? message
+            message.cs__is_a?(Protobuf::Field::FieldHash) &&
+                message.values[0].cs__is_a?(Contrast::Api::Dtm::LibraryUsageUpdate)
+          end
+
+          # Checks if the message is of Contrast::Api::Dtm::ApplicationUpdate class
+          #
+          # @param dtm [Contrast::Api::Dtm::ApplicationUpdate,Object]
+          # @return [Boolean]
+          def application_update? dtm
+            dtm.cs__is_a?(Contrast::Api::Dtm::ApplicationUpdate)
+          end
+
+          # @param dtm [Contrast::Api::Dtm::Finding,Object]
+          # @return [Boolean]
+          def finding? dtm
+            dtm.cs__is_a?(Contrast::Api::Dtm::Finding)
+          end
+
+          # Converts DTM message to Reporting Event for those messages that have conversion methods crated. We use this
+          # as we work to move away from requiring the Service.
+          #
+          # @param dtm [Contrast::Api::Dtm]
+          # @return event [Contrast::Agent::Reporting::ReportingEvent, nil]
+          def dtm_to_event dtm
+            # For the ServerActivity we need to create and send empty body only. This is done because we need the
+            # response from TS.
+            return Contrast::Agent::Reporting::ServerActivity.new if server_activity?(dtm)
+
+            # For the others, we convert them.
+            return Contrast::Agent::Reporting::ObservedLibraryUsage.convert(dtm) if library_usage?(dtm)
+            return Contrast::Agent::Reporting::ApplicationUpdate.convert(dtm) if application_update?(dtm)
+            return Contrast::Agent::Reporting::Finding.convert(dtm) if finding?(dtm)
+
+            nil
+          end
+        end
+      end
+    end
+  end
+end