contrast-agent 4.13.1 → 5.1.0

data/lib/contrast/agent/reporting/reporting_events/finding_stack.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
+
+module Contrast
+  module Agent
+    module Reporting
+      # This is the new FindingStack class which will include all the needed information for the new reporting system
+      # to relay this information in the Finding/Trace messages. These FindingStack are used by TeamServer to construct
+      # the vulnerability information for the assess feature. They represent the callstack at the time that each
+      # FindingEvent was generated.
+      #
+      # @attr_reader eval [String] unused
+      # @attr_reader file [String] the stack frame to show in TeamServer; the value of an entry in #caller
+      # @attr_reader line_number [String] unused
+      # @attr_reader method [String] unused
+      # @attr_reader signature [String] unused
+      # @attr_reader type [String] unused
+      class FindingStack
+        attr_reader :eval, :file, :line_number, :method, :signature, :type
+
+        AGENT_CLASS_MARKER = '/lib/contrast/'
+
+        class << self
+          # @param stack [Array<String>]
+          # @return [Contrast::Agent::Reporting::FindingStack,nil]
+          def convert stack
+            return unless stack
+            return if stack.include?(AGENT_CLASS_MARKER)
+
+            report = new
+            report.attach_data(stack)
+            report
+          end
+        end
+
+        # Parse the data from a Contrast::Agent::Assess::Tag to attach what is required for reporting to TeamServer to
+        # this Contrast::Agent::Reporting::FindingTaintRange
+        #
+        # @param stack [Array<String>]
+        def attach_data stack
+          @file = stack
+        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
+          {
+              # eval: eval,
+              file: file # ,
+            # line_number: line_number, # This is unused by the Ruby agent
+            # method: method, # This is unused by the Ruby agent
+            # signature: signature, # This is unused by the Ruby agent
+            # type: type  # This is unused by the Ruby agent
+          }
+        end
+
+        def validate
+          raise(ArgumentError, "#{ self } did not have a proper hash. Unable to continue.") unless file && !file.empty?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+module Contrast
+  module Agent
+    module Reporting
+      # This is the new FindingObject class which will include all the needed information for the new reporting system
+      # to relay this information in the Finding/Trace messages. These FindingTaintRanges are used by TeamServer to
+      # construct the vulnerability information for the assess feature. They represent those parts of the objects that
+      # are tracked because of a security relevant operation acting on them.
+      #
+      # @attr_reader range [String] the range (inclusive:exclusive), that this tag covers.
+      # @attr_reader tag [String] the type of action this tag represents.
+      class FindingTaintRange
+        attr_reader :range, :tag
+
+        class << self
+          # @param tag [Contrast::Agent::Assess::Tag] the tag to convert
+          # @return [Contrast::Agent::Reporting::FindingTaintRange]
+          def convert tag
+            report = new
+            report.attach_data(tag)
+            report
+          end
+        end
+
+        # Parse the data from a Contrast::Agent::Assess::Tag to attach what is required for reporting to TeamServer to
+        # this Contrast::Agent::Reporting::FindingTaintRange
+        #
+        # @param tag [Contrast::Agent::Assess::Tag] the tag to convert
+        def attach_data tag
+          @range = "#{ tag.start_idx }:#{ tag.end_idx }"
+          @tag = tag.label
+        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
+          {
+              range: range,
+              tag: tag
+          }
+        end
+
+        def validate
+          raise(ArgumentError, "#{ self } did not have a proper hash. Unable to continue.") unless hash && !hash.empty?
+          return unless value && !value.empty?
+
+          raise(ArgumentError, "#{ self } did not have a proper value. Unable to continue.")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,93 @@
+# 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'
+
+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_reader 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
+        # required attributes
+        attr_reader :external_date, :file, :hash, :internal_date
+        # optional attributes
+        attr_reader :class_count, :manifest, :tags, :url, :version
+
+        class << self
+          # Convert a DTM for SpeedRacer to an Event for TeamServer.
+          #
+          # @param library_dtm [Contrast::Api::Dtm::Library]
+          # @return [Contrast::Agent::Reporting::LibraryDiscovery]
+          def convert library_dtm
+            report = new
+            report.attach_data(library_dtm)
+            report
+          end
+        end
+
+        # Attach the data from the protobuf models to this reporter so that it can be sent to TeamServer directly
+        #
+        # @param library_dtm [Contrast::Api::Dtm::Library]
+        def attach_data library_dtm
+          @class_count = library_dtm.class_count
+          @external_date = library_dtm.external_ms
+          @file = library_dtm.file_path
+          @hash = library_dtm.hash_code
+          @internal_date = library_dtm.internal_ms
+          @manifest = library_dtm.manifest
+          @tags = Contrast::INVENTORY.tags
+          @url = library_dtm.url
+          @version = library_dtm.version
+        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
+          msg = {
+              classCount: class_count,
+              externalDate: external_date,
+              file: file,
+              hash: hash,
+              internalDate: internal_date,
+              manifest: manifest,
+              url: url,
+              version: version
+          }
+          msg[:tags] = tags if tags
+          msg
+        end
+
+        # Ensure the required fields are present.
+        #
+        # @raise [ArgumentError]
+        def validate
+          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
+          raise(ArgumentError, "#{ self } did not have a proper file. Unable to continue.") unless file
+          raise(ArgumentError, "#{ self } did not have a proper hash. Unable to continue.") unless hash
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+module Contrast
+  module Agent
+    module Reporting
+      #
+      # @attr_accessor id - [String]  - Hash of library as identified by the agent
+      # @attr_accessor names Array[String] - List of file paths that have been loaded out of or executed by the library
+      #
+      class LibraryUsageObservation
+        attr_accessor :id, :names
+
+        class << self
+          # Convert a DTM for SpeedRacer to an Event for TeamServer.
+          #
+          # @param usage_dtm [Contrast::Api::Dtm::LibraryUsageUpdate]
+          # @return [Contrast::Agent::Reporting::LibraryUsageObservation]
+          def convert usage_dtm
+            observation = new
+            observation.attach_data(usage_dtm)
+            observation
+          end
+        end
+
+        def initialize
+          @names = []
+        end
+
+        def attach_data usage_dtm
+          @id = usage_dtm.hash_code
+          @names = usage_dtm.class_names.keys
+        end
+
+        def to_controlled_hash
+          validate
+          {
+              id: @id,
+              names: @names
+          }
+        end
+
+        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,54 @@
+# 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/agent/reporting/reporting_events/library_usage_observation'
+
+module Contrast
+  module Agent
+    module Reporting
+      # List of libraries that have been observed to have something loaded or executed.
+      #
+      # @attr_reader observations - Array[Contrast::Agent::Reporting::LibraryUsageObservation]
+      #                            - Hash of LibraryUsageObservations
+      class ObservedLibraryUsage < Contrast::Agent::Reporting::ReportingEvent
+        attr_reader :observations
+
+        class << self
+          # Convert a Hash of LibraryUsageUpdate DTMs for SpeedRacer to an Event for TeamServer.
+          #
+          # @param usages_dtm_hash Hash[Contrast::Api::Dtm::LibraryUsageUpdate]
+          # @return [Contrast::Agent::Reporting::ObservedLibraryUsage]
+          def convert usages_dtm_hash
+            report = new
+            report.attach_data(usages_dtm_hash)
+            report
+          end
+        end
+
+        def initialize
+          @event_endpoint = Contrast::Agent::Reporting::Endpoints.library_usage
+          @observations = []
+          super
+        end
+
+        def to_controlled_hash
+          validate
+          { observations: @observations.map(&:to_controlled_hash) }
+        end
+
+        def attach_data usages_dtm_hash
+          usages_dtm_hash.each do |_key, value|
+            next unless value.class_names.any?
+
+            @observations << Contrast::Agent::Reporting::LibraryUsageObservation.convert(value)
+          end
+        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,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/preflight.rb

@@ -0,0 +1,39 @@
+# 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 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_reader :messages
+
+        def initialize
+          @event_method = :PUT
+          @event_endpoint = "#{ Contrast::API.api_url }/api/ng/preflight/"
+          @messages = []
+          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
+          { messages: @messages }
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,47 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/components/logger'
+require 'contrast/utils/assess/trigger_method_utils'
+require 'contrast/agent/reporting/reporting_utilities/endpoints'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This is the new ReportingEvent class which will include all the needed and mutual information for the new
+      # reporting system.
+      #
+      # @abstract
+      # @attr_reader routes [Array]
+      # @attr_reader event_method [Symbol] the HTTP method to use to send this event
+      class ReportingEvent
+        attr_reader :event_endpoint, :event_method
+
+        def initialize
+          @agent_session_id_value = 0 # TODO: RUBY-99999 Contrast::APP_CONTEXT.session_id once we have app start
+          @event_endpoint ||= nil
+          @event_method ||= :POST
+        end
+
+        # Some reports require specific additional headers to be used. To that end, we'll attach them here, letting
+        # each handle their own.
+        #
+        # @param _request [Net::HTTPRequest]
+        def attach_headers _request; end
+
+        # Convert the instance variables on the class, and other information, into the identifiers required for
+        # TeamServer to process the JSON form of this message.
+        #
+        # @return [Hash]
+        # @raise [ArgumentError]
+        def to_controlled_hash
+          validate
+          {}
+        end
+
+        # @raise [ArgumentError]
+        def validate; end
+      end
+    end
+  end
+end

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

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