contrast-agent 4.14.1 → 5.0.0

data/lib/contrast/agent/reporting/reporting_events/preflight_message.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'
@@ -7,34 +7,53 @@ 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
-      class PreflightMessage < Contrast::Agent::Reporting::ReportingEvent
-        attr_accessor :data, :routes, :hash_code
+      # 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
-          super
-          @event_type = :preflight_message
           @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
 
-        def to_controlled_hash **_args
+        # 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
-          super.merge!({
-                           app_language: @app_language,
-                           app_name: @app_name,
-                           app_version: @app_version,
-                           data: '',
-                           key: 0,
-                           routes: @routes,
-                           session_id: @agent_session_id_value
-                       })
+          {
+              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

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

@@ -1,36 +1,46 @@
-# 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'
 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
+      # 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 :routes
-        attr_accessor :event_type
+        attr_reader :event_endpoint, :event_method
 
-        CODE = :TRACE
-
-        def initialize(*) # rubocop:disable Style/MethodDefParentheses
-          @event_type = Contrast::Utils::ObjectShare::EMPTY_STRING
-          @agent_session_id_value = 0
-          @routes = []
-        end
-
-        def to_controlled_hash **_args
-          { code: CODE, routes: routes }
+        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
 
-        def validate
-          raise(ArgumentError, "#{ self } did not have a proper routes. Unable to continue.") if routes.empty?
+        # 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
 
-          nil
+        # 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

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

@@ -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'
@@ -22,18 +22,22 @@ module Contrast
         # 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] One of the DTMs valid for the event field of
-        #   Contrast::Api::Dtm::Message|Contrast::Api::Dtm::Activity
+        # @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
+          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 = event.to_s
+          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
+          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
@@ -63,12 +67,18 @@ module Contrast
           # destination. In that case, take no action
           return unless destination
 
-          filename = "#{ time }-#{ data_type.gsub('::', '_') }-teamserver.json"
+          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|
-            f.write({ data_type: Contrast::Utils::StringUtils.force_utf8(data) }.to_json)
+            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
@@ -91,7 +101,7 @@ module Contrast
         # Retrieves the configuration value if the request audit is enabled
         # @return [Boolean]
         def enabled?
-          ::Contrast::API.request_audit_enable
+          ::Contrast::API.request_audit_enable?
         end
 
         # The boolean values for the requests and the responses should be taken under
@@ -104,13 +114,13 @@ module Contrast
         # Retrieve the configuration value if the audit for requests is enabled
         # @return [Boolean]
         def enabled_for_requests?
-          ::Contrast::API.request_audit_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
+          ::Contrast::API.request_audit_requests?
         end
 
         # Retrieve the configuration value for the path of the audits

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