contrast-agent 3.9.1 → 6.15.3

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

@@ -0,0 +1,126 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/agent/reporting/reporting_events/reportable_hash'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This is the new FindingRequest class which will include all the needed information for the new reporting system
+      # to relay this information in the Finding/Trace messages. These requests are used by TeamServer to construct the
+      # HTTP information for the assess feature. They represent the literal request made that resulted in the
+      # vulnerability being triggered.
+      class FindingRequest < Contrast::Agent::Reporting::ReportableHash
+        OMITTED_BODY = '{{body-omitted-by-contrast}}'
+
+        # @return [String] the body of this request
+        attr_accessor :body
+        # @return [Hash<String,Array<String>>] the headers of this request
+        attr_accessor :headers
+        # @return [String] the HTTP verb of this request
+        attr_reader :method
+        # @return [Hash<String,Array<String>>] the parameters of this request
+        attr_reader :parameters
+        # @return [Integer] the port to which this request connected
+        attr_reader :port
+        # @return [String] the HTTP(S) protocol of this request
+        attr_reader :protocol
+        # @return [String] the query string of this request
+        attr_accessor :query_string
+        # @return [String] the url, including path and script, of this request
+        attr_reader :uri
+        # @return [String] the HTTP version of this request
+        attr_reader :version
+        # @return [Integer]
+        attr_reader :ip
+        # @return [String] Byte representation of the body
+        attr_accessor :body_binary
+        # @return [Hash]
+        attr_reader :cookies
+
+        class << self
+          # @param request [Contrast::Agent::Request]
+          # @return [Contrast::Agent::Reporting::FindingRequest]
+          def convert request
+            return unless request
+
+            report = new
+            report.attach_data(request)
+            report
+          end
+        end
+
+        # Parse the data from a Contrast::Agent::Request to attach what is required for reporting to TeamServer to this
+        # Contrast::Agent::Reporting::FindingRequest
+        #
+        # @param request [Contrast::Agent::Request]
+        def attach_data request
+          @body = request.body
+          @headers = {}
+          extract_headers(request)
+          @method = request.request_method
+          @parameters = {}
+          request.parameters.each_pair { |key, value| @parameters[key] = Array(value) }
+          @port = request.port || 0
+          @protocol = request.scheme
+          @query_string = request.query_string
+          @uri = request.normalized_uri
+          @version = request.version
+          @ip = request.ip || ''
+          @body_binary = if omit_body?(request)
+                           OMITTED_BODY
+                         else
+                           Contrast::Utils::StringUtils.force_utf8(request.body)
+                         end
+          @cookies = {}
+          @cookies = request.cookies unless request.cookies.empty?
+        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
+          {
+              body: body,
+              headers: headers,
+              method: method, # rubocop:disable Security/Object/Method
+              parameters: parameters,
+              port: port || 0,
+              protocol: protocol,
+              queryString: query_string,
+              uri: uri,
+              version: version
+          }
+        end
+
+        def omit_body? request
+          return true if ::Contrast::AGENT.omit_body?
+          return false if request.document_type != :NORMAL
+
+          request.media_type&.include?('multipart/form-data')
+        end
+
+        def validate
+          unless method && !method.empty? # rubocop:disable Security/Object/Method
+            raise(ArgumentError, "#{ self } did not have a proper method. Unable to continue.")
+          end
+          raise(ArgumentError, "#{ self } did not have a proper uri. Unable to continue.") unless uri && !uri.empty?
+        end
+
+        # @param request [Contrast::Agent::Request]
+        def extract_headers request
+          request.headers.each_pair do |key, value|
+            # We need to change from the uppercase _ format to capitalized - format.
+            header = key.split('_')
+            header.each(&:capitalize!)
+            header = header.join('-')
+            headers[header] = value.split
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,89 @@
+# Copyright (c) 2023 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/utils/duck_utils'
+require 'contrast/agent/reporting/reporting_events/reportable_hash'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This is the new Library Discovery class which will include all the needed information for the new
+      # reporting system to relay this information in the Application Update messages. These libraries are used by
+      # TeamServer to construct the dependency information for the SCA feature. They represent those gems that are
+      # included in the GemSpec, not necessarily those that have had files in them required.
+      #
+      # @attr_reader class_count [Integer] the number of files in the Gem which contain code.
+      # @attr_reader external_date [Integer] the time, in ms, when the Gem was published. Required for reporting.
+      # @attr_reader file [String] the name of the Gem. Required for reporting.
+      # @attr_reader hash [String] the Sha256 of the Gem, matching its hash in RubyGems. Required for reporting.
+      # @attr_reader internal_date [Integer] the time, in ms, when the Gem was published. Required for reporting.
+      # @attr_accessor manifest [String] the YAML form of the Gem's specification.
+      # @attr_reader tags [String] Inventory tags set by the user via configuration.
+      # @attr_reader url [String] The homepage of the Gem.
+      # @attr_reader version [String] The version of the Gem.
+      class LibraryDiscovery < Contrast::Agent::Reporting::ReportableHash
+        StringUtils = Contrast::Utils::StringUtils
+
+        # required attributes
+        attr_reader :external_date, :file, :hash, :internal_date
+        # optional attributes
+        attr_reader :class_count, :tags, :url, :version
+        attr_accessor :manifest
+
+        def initialize digest, spec
+          @file = StringUtils.force_utf8(spec.name) # rubocop:disable Security/Module/Name
+          @hash = StringUtils.force_utf8(digest)
+          @version     = StringUtils.force_utf8(spec.version)
+          @manifest    = StringUtils.force_utf8(StringUtils.force_utf8(spec.to_yaml.to_s))
+          @external_date = (spec.date.to_f * 1000.0).to_i
+          @internal_date = @external_date
+          @url         = StringUtils.force_utf8(spec.homepage)
+          @class_count = Contrast::Utils::Sha256Builder.instance.files(spec.full_gem_path.to_s).length
+          @tags = Contrast::INVENTORY.tags
+          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
+          {
+              classCount: class_count,
+              externalDate: external_date,
+              file: file,
+              hash: hash,
+              internalDate: internal_date,
+              manifest: manifest,
+              url: url,
+              version: version,
+              tags: tags
+          }.compact
+        end
+
+        # Ensure the required fields are present.
+        #
+        # @raise [ArgumentError]
+        def validate
+          if Contrast::Utils::DuckUtils.empty_duck?(file)
+            raise(ArgumentError, "#{ self } did not have a proper file. Unable to continue.")
+          end
+          if Contrast::Utils::DuckUtils.empty_duck?(hash)
+            raise(ArgumentError, "#{ self } did not have a proper hash. Unable to continue.")
+          end
+          unless external_date
+            raise(ArgumentError, "#{ self } did not have a proper external date. Unable to continue.")
+          end
+          unless internal_date
+            raise(ArgumentError, "#{ self } did not have a proper internal date. Unable to continue.")
+          end
+
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/agent/reporting/reporting_events/reportable_hash'
+require 'contrast/utils/duck_utils'
+
+module Contrast
+  module Agent
+    module Reporting
+      # The usage, meaning loaded files, of a library seen during this request
+      class LibraryUsageObservation < Contrast::Agent::Reporting::ReportableHash
+        # @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
+          super()
+        end
+
+        # @raise [ArgumentError]
+        def to_controlled_hash
+          validate
+          {
+              id: @id,
+              names: @names
+          }
+        end
+
+        # @raise [ArgumentError]
+        def validate
+          if Contrast::Utils::DuckUtils.empty_duck?(id)
+            raise(ArgumentError, "#{ self } did not have a proper id. Unable to continue.")
+          end
+          if Contrast::Utils::DuckUtils.empty_duck?(names)
+            raise(ArgumentError, "#{ self } did not have a proper names. Unable to continue.")
+          end
+
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# Copyright (c) 2023 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
+        # @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
+          validate
+          { 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,83 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+require 'contrast/agent/reporting/reporting_events/application_reporting_event'
+require 'contrast/utils/object_share'
+require 'contrast/utils/duck_utils'
+
+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
+        # @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 = []
+          @verb = 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
+          validate
+          {
+              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.reject { |key, _value| key == :session_id } # rubocop:disable Style/HashExcept
+          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?
+          if Contrast::Utils::DuckUtils.empty_duck?(signature)
+            raise(ArgumentError, "#{ self } did not have a proper signature. Unable to continue.")
+          end
+          if Contrast::Utils::DuckUtils.empty_duck?(url)
+            raise(ArgumentError, "#{ self } did not have a proper url. Unable to continue.")
+          end
+
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# Copyright (c) 2023 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,52 @@
+# Copyright (c) 2023 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/utils/duck_utils'
+
+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
+          validate
+          { messages: @messages.map(&:to_controlled_hash) }
+        end
+
+        # @raise [ArgumentError]
+        def validate
+          if Contrast::Utils::DuckUtils.empty_duck?(messages)
+            raise(ArgumentError, "#{ cs__class } did not have any messages. Unable to continue.")
+          end
+
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/components/assess'
+require 'contrast/utils/string_utils'
+require 'contrast/agent/reporting/reporting_events/reportable_hash'
+
+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 < Contrast::Agent::Reporting::ReportableHash
+        # @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 = []
+          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
+          {
+              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/reportable_hash.rb

@@ -0,0 +1,47 @@
+# Copyright (c) 2023 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
+      # A class supporting all to_controlled_hash reporting methods. All errors raised during
+      # validation will be handled here.
+      class ReportableHash
+        include Contrast::Components::Logger::InstanceMethods
+
+        # 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, nil]
+        # @raise [ArgumentError]
+        def to_controlled_hash
+          validate
+          {}
+        end
+
+        # @raise [ArgumentError]
+        def validate; end
+
+        # Helper method to get json representation of event objects and handle errors.
+        #
+        #  @return [String, nil] - JSON
+        def event_json
+          hsh = to_controlled_hash
+          hsh.to_json
+        rescue ArgumentError => e
+          # Log the error and raise it for the client to handle:
+          logger.error(validation_error_message, e)
+          raise(e)
+        end
+
+        private
+
+        def validation_error_message
+          "#{ cs__class } failed validation with: "
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/agent/reporting/reporting_events/reportable_hash'
+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 < Contrast::Agent::Reporting::ReportableHash
+        # @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
+          super()
+        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
+      end
+    end
+  end
+end