contrast-agent 4.14.0 → 5.2.0

data/lib/contrast/agent/reporting/reporting_events/observed_route.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 '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 Observation 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 signature [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 agent_session_id_value [Integer] the session of this process, as determined from TeamServer on
+      #   application create.
+      # @attr_accessor sources [Array<Contrast::Agent::Reporting::TraceEventSource>] the sources of user input accessed
+      #   during this request. Used for remediation determinations in TeamServer.
+      class ObservedRoute < Contrast::Agent::Reporting::ReportingEvent
+        attr_accessor :sources, :agent_session_id_value, :signature, :verb, :url
+
+        def initialize
+          @event_endpoint = Contrast::Agent::Reporting::Endpoints.observed_route
+          @sources = []
+          @signature = Contrast::Utils::ObjectShare::EMPTY_STRING
+          @verb = Contrast::Utils::ObjectShare::EMPTY_STRING
+          @url = Contrast::Utils::ObjectShare::EMPTY_STRING
+          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
+          validate
+          rc_hash = {
+              session_id: @agent_session_id_value,
+              sources: @sources,
+              signature: @signature,
+              verb: @verb,
+              url: @url
+          }
+          rc_hash.delete(:verb) unless @verb
+          rc_hash
+        end
+
+        def validate
+          raise(ArgumentError, "#{ self } did not have a proper sources. Unable to continue.") if @sources.nil?
+          raise(ArgumentError, "#{ self } did not have a proper signature. Unable to continue.") unless signature
+          raise(ArgumentError, "#{ self } did not have a proper url. Unable to continue.") unless url
+
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# 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 is the new Poll class for the Heartbeat Service.
+      class Poll < Contrast::Agent::Reporting::ReportingEvent
+        def initialize
+          @event_type = :heartbeat
+          @event_endpoint = Contrast::Agent::Reporting::Endpoints.heartbeat
+          super
+        end
+
+        # This is commented out as I am not aware if we're supposed to send some information and/or parse it to hash
+        # In https://github.com/Contrast-Security-Inc/contrast-service/blob/next/reporting/tsreporter.go
+        #
+        # 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; end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/reporting_events/preflight.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/agent/reporting/reporting_events/reporting_event'
@@ -6,17 +6,31 @@ require 'contrast/agent/reporting/reporting_events/reporting_event'
 module Contrast
   module Agent
     module Reporting
-      # This class here will hold the needed preflights we will send for certain trace/traces
+      # This is the new Preflight class which will include all the needed information for the new reporting system
+      # to report a Preflight message to TeamServer. This message represents the identifying information of a
+      # collection of Findings/Traces, which TeamServer will use to determine if it requires the full information of
+      # any of the Findings/Traces to be reported.
+      #
+      # For our purposes, we'll only ever send one message per request; however, we must use an array to conform to the
+      # specification.
+      #
+      # @attr_reader messages [Array<Contrast::Agent::Reporting::PreflightMessage>]
       class Preflight < Contrast::Agent::Reporting::ReportingEvent
-        attr_accessor :messages
+        attr_reader :messages
 
         def initialize
-          super
-          @event_type = :preflight
+          @event_method = :PUT
+          @event_endpoint = "#{ Contrast::API.api_url }/api/ng/preflight/"
           @messages = []
+          super
         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
           { messages: @messages }
         end
       end

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,47 @@
-# 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
       class ReportingEvent
-        attr_reader :routes
-        attr_accessor :event_type
+        # @return [String] the endpoint, with host, to which this event should be sent
+        attr_reader :event_endpoint
+        # @return event_method [Symbol] the HTTP method to use to send this event
+        attr_reader :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-1514 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,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/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
+          {
+              count: 0, # we have this to make TS happy
+              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/server"
+          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