contrast-agent 3.8.4 → 6.9.0

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

@@ -0,0 +1,48 @@
+# 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
+      # The usage, meaning loaded files, of a library seen during this request
+      class LibraryUsageObservation
+        include Contrast::Components::Logger::InstanceMethods
+
+        # @param [String] Sha256Sum of library as identified by the agent
+        attr_reader :id
+        # @param [Array<String>] List of file paths that have been loaded out of or executed by the library
+        attr_reader :names
+
+        # @param id [String] Sha256Sum of library as identified by the agent
+        # @param class_names [Array<String>] List of file paths that have been loaded out of or executed by the library
+        def initialize id, class_names
+          @id = id
+          @names = class_names
+        end
+
+        # @raise [ArgumentError]
+        def to_controlled_hash
+          begin
+            validate
+          rescue ArgumentError => e
+            logger.error('LibraryUsageObservation validation failed with: ', e)
+            return
+          end
+
+          {
+              id: @id,
+              names: @names
+          }
+        end
+
+        # @raise [ArgumentError]
+        def validate
+          raise(ArgumentError, "#{ self } did not have a proper id. Unable to continue.") unless id
+          raise(ArgumentError, "#{ self } did not have a proper names. Unable to continue.") if names.empty?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/agent/reporting/reporting_events/application_reporting_event'
+require 'contrast/agent/reporting/reporting_events/library_usage_observation'
+require 'contrast/components/logger'
+
+module Contrast
+  module Agent
+    module Reporting
+      # List of libraries that have been observed to have something loaded or executed.
+      class ObservedLibraryUsage < Contrast::Agent::Reporting::ApplicationReportingEvent
+        include Contrast::Components::Logger::InstanceMethods
+
+        # @return Array[Contrast::Agent::Reporting::LibraryUsageObservation]
+        attr_reader :observations
+
+        def initialize
+          @event_endpoint = Contrast::Agent::Reporting::Endpoints.library_usage
+          @observations = []
+          super
+        end
+
+        def file_name
+          'library-observation'
+        end
+
+        def to_controlled_hash
+          begin
+            validate
+          rescue ArgumentError => e
+            logger.error('ObservedLibraryUsage validation failed with: ', e)
+            return
+          end
+
+          { observations: @observations.map(&:to_controlled_hash) }
+        end
+
+        def validate
+          raise(ArgumentError, "#{ self } did not have observations. Unable to continue.") if observations.empty?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,89 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+require 'contrast/components/logger'
+require 'contrast/agent/reporting/reporting_events/application_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.
+      class ObservedRoute < Contrast::Agent::Reporting::ApplicationReportingEvent
+        include Contrast::Components::Logger::InstanceMethods
+
+        # @param [String] the method signature used to uniquely identify the coverage report.
+        attr_accessor :signature
+        # @param [String] the normalized URL used to access the method in the route.
+        attr_accessor :url
+        # @param [String] the HTTP Verb used  to access the method in the route.
+        attr_accessor :verb
+        # @param [Array<Contrast::Agent::Reporting::FindingEventSource>] the sources of user input accessed during this
+        #   request. Used for remediation determinations in TeamServer.
+        attr_reader :sources
+
+        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
+
+        def file_name
+          'routes-observed'
+        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
+          begin
+            validate
+          rescue ArgumentError => e
+            logger.error('ObservedRoute validation failed with: ', e)
+            return
+          end
+
+          {
+              session_id: ::Contrast::ASSESS.session_id,
+              sources: @sources.map(&:to_controlled_observation_hash),
+              signature: @signature,
+              verb: @verb,
+              url: @url
+          }.compact
+        end
+
+        # Generates a hash id for the observed route, based on the sources, signature, verb, and url.
+        #
+        # @return [String]
+        #
+        def hash_id
+          hashable_data = to_controlled_hash.except(:session_id)
+          hashable_data[:sources] = hashable_data[:sources].sort_by { |s| s[:name] }
+
+          Digest::SHA2.new(256).hexdigest(hashable_data.to_s)
+        end
+
+        # @raise [ArgumentError]
+        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,23 @@
+# 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/application_reporting_event'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This is the new Poll class for the Heartbeat to TeamServer.
+      class Poll < Contrast::Agent::Reporting::ApplicationReportingEvent
+        def initialize
+          @event_type = :heartbeat
+          @event_endpoint = Contrast::Agent::Reporting::Endpoints.heartbeat
+          super
+        end
+
+        def file_name
+          'applications-heartbeat'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# 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/application_reporting_event'
+
+module Contrast
+  module Agent
+    module Reporting
+      # 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.
+      class Preflight < Contrast::Agent::Reporting::ApplicationReportingEvent
+        # For our purposes, we'll only ever send one message per request; however,
+        # we must use an array to conform to the specification.
+        # @return messages [Array<Contrast::Agent::Reporting::PreflightMessage>]
+        attr_reader :messages
+
+        def initialize
+          @event_method = :PUT
+          @event_endpoint = "#{ Contrast::API.api_url }/api/ng/preflight/"
+          @messages = []
+          super
+        end
+
+        def file_name
+          'preflight'
+        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
+          { messages: @messages.map(&:to_controlled_hash) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+# 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'
+require 'contrast/components/assess'
+require 'contrast/components/logger'
+require 'contrast/utils/string_utils'
+
+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.
+      class PreflightMessage
+        include Contrast::Components::Logger::InstanceMethods
+
+        # @return [String] the message identifier; rule_id,hash
+        attr_accessor :data
+        # @return [String] CRC checksum of the finding to which this message pertains
+        attr_accessor :hash_code
+        # @return [Array<Contrast::Agent::Reporting::RouteDiscovery] the route that triggered the finding to which this
+        #   preflight applies.
+        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
+          @routes = []
+        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
+          begin
+            validate
+          rescue ArgumentError => e
+            logger.error('PreflightMessage validation failed with: ', e)
+            return
+          end
+
+          {
+              code: CODE,
+              app_language: Contrast::Utils::ObjectShare::RUBY,
+              app_name: ::Contrast::APP_CONTEXT.name, # rubocop:disable Security/Module/Name
+              app_version: ::Contrast::APP_CONTEXT.version,
+              data: '',
+              key: 0,
+              routes: @routes.map(&:to_controlled_hash),
+              session_id: ::Contrast::ASSESS.session_id
+          }
+        end
+
+        # @raise [ArgumentError]
+        def validate
+          unless Contrast::Utils::StringUtils.present?(data)
+            raise(ArgumentError, "#{ cs__class } did not have a proper data. Unable to continue.")
+          end
+          unless ::Contrast::ASSESS.session_id
+            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,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'
+require 'contrast/utils/assess/trigger_method_utils'
+require 'contrast/agent/reporting/reporting_utilities/endpoints'
+require 'contrast/components/assess'
+
+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
+      class ReportingEvent
+        include Contrast::Components::Logger::InstanceMethods
+
+        # @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
+
+        def initialize
+          @event_method ||= :POST # rubocop:disable Lint/DisjunctiveAssignmentInConstructor
+        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
+          begin
+            validate
+          rescue ArgumentError => e
+            logger.error('ReportingEvent validation failed with: ', e)
+            return
+          end
+
+          {}
+        end
+
+        # @raise [ArgumentError]
+        def validate; end
+
+        # Helper method to get json representation of event and handle errors
+        #
+        #  @return [String] - JSON
+        def event_json
+          hsh = to_controlled_hash
+          hsh.to_json
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          logger.error('Unable to convert JSON string', e, hsh)
+          raise(e)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,89 @@
+# 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.
+      class RouteCoverage
+        # @param [String] the method signature used to uniquely identify the coverage report.
+        attr_accessor :route
+        # @param [String] the normalized URL used to access the method in the route.
+        attr_accessor :url
+        # @param [String] the HTTP Verb used  to access the method in the route.
+        attr_accessor :verb
+        # @param [Integer] the number of times this was hit; no longer needed as it can be derived.
+        attr_reader :count
+
+        def initialize
+          @route = Contrast::Utils::ObjectShare::EMPTY_STRING
+          @verb = Contrast::Utils::ObjectShare::EMPTY_STRING
+          @url = Contrast::Utils::ObjectShare::EMPTY_STRING
+          @count = 0
+        end
+
+        # Parse the given controller and route from a Rack based application framework in order to create an instance
+        # of this class
+        #
+        # @param final_controller [Grape::API, Sinatra::Base] the controller responsible for the definition of the
+        #   entrypoint of the route actively being executed
+        # @param method [String] the HTTP request method of the route actively being executed
+        # @param route_pattern [Grape::Router::Route, Mustermann::Sinatra] the pattern to which the url maps
+        # @param url [String] the literal url of the route actively being executed
+        # @return [Contrast::Agent::Reporting::RouteCoverage]
+        def attach_rack_based_data final_controller, method, route_pattern, url = nil
+          if Contrast::Utils::ClassUtil.truly_defined?('Grape::Router::Route') &&
+                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,63 @@
+# 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/components/logger'
+
+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.
+      #
+      class RouteDiscovery
+        include Contrast::Components::Logger::InstanceMethods
+
+        # @return [Array<Contrast::Agent::Reporting::RouteDiscoveryObservation>] the routes and verbs seen that match
+        #   to this Route.
+        attr_reader :observations
+        # @return [String] the unique identifier for this route; typically the method signature. Required for
+        #   reporting.
+        attr_accessor :signature
+
+        # @param signature [String]
+        # @param observation [Contrast::Agent::Reporting::RouteDiscoveryObservation]
+        def initialize signature, observation
+          @signature = signature
+          @observations = []
+          observations << observation
+        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
+          begin
+            validate
+          rescue ArgumentError => e
+            logger.error('RouteDiscovery validation failed with: ', e)
+            return
+          end
+
+          {
+              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,53 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/utils/string_utils'
+require 'contrast/components/logger'
+
+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.
+      class RouteDiscoveryObservation
+        include Contrast::Components::Logger::InstanceMethods
+
+        # @return [String] the URL requested to hit this endpoint. Required for reporting; required attributes
+        attr_accessor :url
+        # @return [String] the HTTP Method requested to his this endpoint. Empty means all, so is allowed for
+        #   reporting; optional attributes
+        attr_accessor :verb
+
+        def initialize url, verb
+          @url = url
+          @verb = verb if Contrast::Utils::StringUtils.present?(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
+          begin
+            validate
+          rescue ArgumentError => e
+            logger.error('RouteDiscoveryObservation validation failed with: ', e)
+            return
+          end
+
+          { url: url, verb: verb }.compact
+        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_reporting_event.rb

@@ -0,0 +1,35 @@
+# 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'
+require 'contrast/utils/timer'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This is the new ServerReportingEvent class which will include all the needed and mutual information for those
+      # events which correspond to Servers, such as Servers Activity.
+      #
+      # @abstract
+      class ServerReportingEvent < Contrast::Agent::Reporting::ReportingEvent
+        protected
+
+        # The timestamp field is a bit of a misnomer. It's really the time, in ms, since the settings for this
+        # application have been updated. If I've never updated, then it's been 0ms since then.
+        #
+        # @return [Integer]
+        def since_last_update
+          (update_time = Contrast::SETTINGS.last_server_update_ms) ? Contrast::Utils::Timer.now_ms - update_time : 0
+        end
+
+        # Human readable last time update for header set. Set to 0 if the agent is just starting and have not received
+        # the latest header from TS.
+        #
+        # @return [String]
+        def since_last_update_httpdate
+          Contrast::SETTINGS.server_settings_last_httpdate || Contrast::Utils::Timer.ms_to_httpdate(0)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# 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_reporting_event'
+require 'contrast/agent/reporting/reporting_utilities/endpoints'
+require 'contrast/utils/timer'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This class will initialize a GET request to be send to TS. The server settings endpoint is the way the Agent
+      # receives server sittings - Protect rules settings, patterns, keywords and deny/allow lists, log setting.
+      class ServerSettings < Contrast::Agent::Reporting::ServerReportingEvent
+        def initialize
+          @event_method = :GET
+          @event_endpoint = Contrast::Agent::Reporting::Endpoints.server_settings
+          super
+        end
+
+        def file_name
+          'server-settings'
+        end
+
+        # Attach the last server settings received timestamp to the request as it is required.
+        #
+        # If-Modified-Since: <day-name>, <day> <month> <year> <hour>:<minute>:<second> GMT
+        # @param request [Net::HTTPRequest]
+        def attach_headers request
+          request['If-Modified-Since'] = since_last_update_httpdate
+        end
+
+        # @return [Hash]
+        # @raise [ArgumentError]
+        def to_controlled_hash
+          {}
+        end
+      end
+    end
+  end
+end