contrast-agent 4.14.0 → 5.2.0

data/lib/contrast/agent/reporting/reporting_events/finding_event_parent_object.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 'base64'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This is the new FindingEventParentObject class which will include all the needed information for the new
+      # reporting system to relay this information in the Finding/Trace messages. These FindingEventParentObject are
+      # used by TeamServer to relate this event to those that came previously. They represent the events that directly
+      # preceding the FindingEvent generated.
+      class FindingEventParentObject
+        # @return [Integer] the Id of the parent event
+        attr_reader :id
+
+        def initialize id
+          @id = 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
+          {
+              id: id
+          }
+        end
+
+        def validate
+          raise(ArgumentError, "#{ self } did not have a proper id. Unable to continue.") unless id
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/reporting_events/finding_event_property.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
+
+module Contrast
+  module Agent
+    module Reporting
+      # This is the new FindingEventProperty class which will include all the needed information for the new reporting
+      # system to relay this information in the Finding/Trace messages. Events have properties on them which are held
+      # as an array of key-value pairs.
+      class FindingEventProperty
+        # @return [String] the key of the property
+        attr_reader :key
+        # @return [String] the value of the source
+        attr_reader :value
+
+        def initialize key, value
+          @key = key
+          @value = value
+        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
+          {
+              key: key,
+              value: value
+          }
+        end
+
+        def validate
+          raise(ArgumentError, "#{ self } did not have a proper key. Unable to continue.") unless key && !key.empty?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,110 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/utils/object_share'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This is the new FindingEventSignature class which will include all the needed information for the new reporting
+      # system to relay this information in the Finding/Trace messages. These FindingEventSignatures are used by
+      # TeamServer to construct the method signature for the assess feature. They represent the method invoked when the
+      # FindingEvent was generated.
+      class FindingEventSignature
+        # @return [String] the types of the arguments in this event; may be different for each invocation of the
+        #   method.
+        attr_reader :arg_types
+        # @return [String] the name of the class of this object or the name itself if of Module type.
+        attr_reader :class_name
+        # @return [Boolean] if the method is a constructor or not.
+        attr_reader :constructor
+        # @return [String] unused.
+        attr_reader :expression_type
+        # @return [Integer] the Java flags; static or not.
+        attr_reader :flags
+        # @return [String] the name of the method.
+        attr_reader :method_name
+        # @return [String] unused.
+        attr_reader :operator
+        # @return [String] the type of the return in this event; may be different for each invocation of the method.
+        attr_reader :return_type
+        # @return [String] unused.
+        attr_reader :signature
+        # @return [Boolean] if the method is void or not; may be different for each invocation of the method.
+        attr_reader :void_method
+
+        class << self
+          # @param event [Contrast::Agent::Assess::ContrastEvent] the event to build a signature for
+          # @return [Contrast::Agent::Reporting::FindingEventSignature]
+          def convert event
+            report = new
+            report.attach_data(event)
+            report
+          end
+        end
+
+        # Parse the data from a Contrast::Agent::Assess::ContrastEvent to attach what is required for reporting to
+        # TeamServer to this Contrast::Agent::Reporting::FindingEventSignature
+        #
+        # @param event [Contrast::Agent::Assess::ContrastEvent]
+        def attach_data event
+          node = event.policy_node
+          @arg_types = []
+          event.args&.each do |arg|
+            arg_types << type_name(arg)
+          end
+          @class_name = node.class_name
+          @constructor = node.method_name == :new || node.method_name == :initialize
+          # 8 is STATIC in Java... we have to placate them for now it has been requested that flags be removed since it
+          # isn't used
+          @flags = 8 unless node.instance_method?
+          @method_name = node.method_name
+          @return_type = type_name(event.ret)
+          # if there's a ret, then this method isn't nil. not 100% full proof since you can return nil, but this is the
+          # best we've got currently.
+          @void_method = event.ret.nil? ||
+              event.ret.object.nil? ||
+              event.ret.object == Contrast::Utils::ObjectShare::NIL_STRING
+        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
+          {
+              argTypes: arg_types,
+              className: class_name,
+              constructor: constructor,
+              # expressionType: expression_type, # This is unused by the Ruby agent
+              flags: flags.to_i,
+              methodName: method_name,
+              # operator: operator, # This is unused by the Ruby agent
+              returnType: return_type,
+              # signature: signature, # This is unused by the Ruby agent
+              voidMethod: void_method
+          }
+        end
+
+        def validate
+          raise(ArgumentError, "#{ self } did not have a proper argTypes. Unable to continue.") unless arg_types
+          raise(ArgumentError, "#{ self } did not have a proper constructor. Unable to continue.") if constructor.nil?
+        end
+
+        private
+
+        # While Ruby signatures do not require neither a return type and can return anything depending on inputs, code
+        # paths, etc, nor constant parameter types, TeamServer was designed with strongly typed languages (Java) in
+        # mind, so we need types in our signatures.
+        #
+        # @param contrast_object [Contrast::Agent::Assess::ContrastObject, nil] the object to find the type of
+        # @return [String] the name of the module of the ret_obj, or `nil`
+        def type_name contrast_object
+          contrast_object ? contrast_object.object_type : Contrast::Utils::ObjectShare::NIL_STRING
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'base64'
+require 'contrast/agent/assess/contrast_event'
+require 'contrast/agent/assess/events/source_event'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This is the new FindingEventSource class which will include all the needed information for the new reporting
+      # system to relay this information in the Finding/Trace messages. These FindingEventSource are used by TeamServer
+      # to construct the vulnerability information for the assess feature. They indicate the type of data that the
+      # event represents.
+      class FindingEventSource
+        # @return [String] the name of the source
+        attr_reader :name
+        # @return [String] the type of the source
+        attr_reader :type
+
+        class << self
+          # @param event [Contrast::Agent::Assess::Events::ContrastEvent] the event to pull the source off of
+          # @return [Contrast::Agent::Reporting::FindingEventSource]
+          def convert event
+            return unless event.cs__is_a?(Contrast::Agent::Assess::Events::SourceEvent)
+
+            report = new
+            report.attach_data(event)
+            report
+          end
+        end
+
+        # Parse the data from a Contrast::Agent::Assess::Events::SourceEvent to attach what is required for reporting
+        # to TeamServer to this Contrast::Agent::Reporting::FindingEventSource
+        #
+        # @param event [Contrast::Agent::Assess::Events::SourceEvent] the event to pull the source off of
+        def attach_data event
+          @name = event.source_name
+          @type = event.source_type
+        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
+          {
+              sourceName: name, # rubocop:disable Security/Module/Name
+              sourceType: type
+          }
+        end
+
+        def validate
+          raise(ArgumentError, "#{ self } did not have a proper type. Unable to continue.") unless type && !type.empty?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# 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 FindingEventStack class which will include all the needed information for the new reporting
+      # system to relay this information in the Finding/Trace messages. These FindingEventStack 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.
+      class FindingEventStack
+        # @return [String] unused
+        attr_reader :eval
+        # @return [String] the stack frame to show in TeamServer; the value of an entry in #caller
+        attr_reader :file
+        # @return [String] unused
+        attr_reader :line_number
+        # @return [String] unused
+        attr_reader :method
+        # @return [String] unused
+        attr_reader :signature
+        # @return [String] unused
+        attr_reader :type
+
+        AGENT_CLASS_MARKER = '/lib/contrast/'
+
+        class << self
+          # @param stack [String]
+          # @return [Contrast::Agent::Reporting::FindingEventStack,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::FindingEventTaintRange
+        #
+        # @param stack [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
+          {
+              file: file
+            # eval: eval, # This is unused by the Ruby agent
+            # 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_event_taint_range.rb

@@ -0,0 +1,60 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/agent/assess/tag'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This is the new FindingEventTaintRange 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.
+      class FindingEventTaintRange
+        # @return [String] the range (inclusive:exclusive), that this tag covers.
+        attr_reader :range
+        # @return [String] the type of action this tag represents.
+        attr_reader :tag
+
+        class << self
+          # @param tag [Contrast::Agent::Assess::Tag] the tag to convert
+          # @return [Contrast::Agent::Reporting::FindingEventTaintRange]
+          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::FindingEventTaintRange
+        #
+        # @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
+          unless range && !range.empty?
+            raise(ArgumentError, "#{ self } did not have a proper range. Unable to continue.")
+          end
+          raise(ArgumentError, "#{ self } did not have a proper tag. Unable to continue.") unless tag && !tag.empty?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,94 @@
+# 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 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
+        # @return [String] the body of this request
+        attr_reader :body
+        # @return [Hash<String,Array<String>>] the headers of this request
+        attr_reader :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_reader :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
+
+        class << self
+          # @param request [Contrast::Agent::Request]
+          # @return [Contrast::Agent::Reporting::FindingRequest]
+          def convert 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 = {}
+          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
+          @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
+        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 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
+      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