contrast-agent 3.8.4 → 6.9.0

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

@@ -0,0 +1,106 @@
+# 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'
+require 'contrast/components/logger'
+
+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
+        include Contrast::Components::Logger::InstanceMethods
+
+        # @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
+
+        # @param policy_node [Contrast::Agent::Assess::Policy::PolicyNode] the node that governs this event.
+        # @param args[Array<Contrast::Agent::Assess::ContrastObject, nil>] the safe representation of the Arguments with
+        #   which the method was invoked
+        # @param ret [Contrast::Agent::Assess::ContrastObject] the safe representation of the Return of the
+        # invoked method
+        def initialize policy_node, args, ret
+          node = policy_node
+          @arg_types = []
+          args&.each { |arg| arg_types << type_name(arg) }
+          @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.to_s
+          @return_type = type_name(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 = ret.nil? || ret.object.nil? || 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
+          begin
+            validate
+          rescue ArgumentError => e
+            logger.error('FindingEventSignature validation failed with: ', e)
+            return
+          end
+
+          {
+              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,74 @@
+# 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/components/logger'
+
+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
+        include Contrast::Components::Logger::InstanceMethods
+
+        # @return [String] the name of the source
+        attr_reader :source_name
+        # @return [String] the type of the source
+        attr_reader :source_type
+
+        # @param type [String]
+        # @param name [String]
+        def initialize type, name
+          @source_type = type
+          @source_name = name
+        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('FindingEventSource validation failed with: ', e)
+            return
+          end
+
+          {
+              sourceName: source_name,
+              sourceType: source_type
+          }
+        end
+
+        # Convert this EventSource into the format expected for route observation
+        #
+        # @return [Hash]
+        # @raise [ArgumentError]
+        def to_controlled_observation_hash
+          begin
+            validate
+          rescue ArgumentError => e
+            logger.error('FindingEventSource observation validation failed with: ', e)
+            return
+          end
+
+          {
+              name: source_name,
+              type: source_type
+          }
+        end
+
+        # @raise [ArgumentError]
+        def validate
+          raise(ArgumentError, "#{ self } did not have a proper type. Unable to continue.") unless source_type &&
+              !source_type.empty?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# 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
+      # 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
+        include Contrast::Components::Logger::InstanceMethods
+
+        # @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/'
+
+        # To play nice with the way that TeamServer is rendering these values, we only populate the file_name field with
+        # exactly what we want them to display.
+        #
+        # @param file_name [String] the caller location this stack frame represents.
+        def initialize file_name
+          @file = file_name
+        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('FindingEventStack validation failed with: ', e)
+            return
+          end
+
+          {
+              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,71 @@
+# 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'
+require 'contrast/agent/reporting/reporting_events/finding_event_taint_range_tags'
+require 'contrast/components/logger'
+
+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
+        include Contrast::Components::Logger::InstanceMethods
+
+        # @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
+          begin
+            validate
+          rescue ArgumentError => e
+            logger.error('FindingEventTaintRange validation failed with: ', e)
+            return
+          end
+
+          {
+              range: range,
+              tag: tag
+          }
+        end
+
+        # @raise [ArgumentError]
+        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_event_taint_range_tags.rb

@@ -0,0 +1,105 @@
+# 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
+      # A holder for the valid tags that can be sent to TeamServer that we have to honor. Placed here so as not to
+      # clutter other code.
+      module FindingEventTaintRangeTags
+        # EventTagTypeDTM
+        # @return [Array<Symbol>]
+        VALID_TAGS = %w[
+          XML_ENCODED
+          XML_DECODED
+          HTML_ENCODED
+          HTML_DECODED
+          URL_ENCODED
+          URL_DECODED
+          CSS_ENCODED
+          CSS_DECODED
+          BASE64_ENCODED
+          BASE64_DECODED
+          JAVASCRIPT_ENCODED
+          JAVASCRIPT_DECODED
+          JAVA_ENCODED
+          JAVA_DECODED
+          CSV_ENCODED
+          CSV_DECODED
+          SQL_ENCODED
+          SQL_DECODED
+          LDAP_ENCODED
+          LDAP_DECODED
+          XPATH_ENCODED
+          XPATH_DECODED
+          OS_ENCODED
+          OS_DECODED
+          VBSCRIPT_ENCODED
+          VBSCRIPT_DECODED
+          POTENTIAL_SANITIZED
+          POTENTIAL_VALIDATED
+          NO_CONTROL_CHARS
+          CUSTOM
+
+          CUSTOM_ENCODED
+          CUSTOM_ENCODED_CMD_INJECTION
+          CUSTOM_ENCODED_EXPRESSION_LANGUAGE_INJECTION
+          CUSTOM_ENCODED_HEADER_INJECTION
+          CUSTOM_ENCODED_HQL_INJECTION
+          CUSTOM_ENCODED_LDAP_INJECTION
+          CUSTOM_ENCODED_LOG_INJECTION
+          CUSTOM_ENCODED_NOSQL_INJECTION
+          CUSTOM_ENCODED_PATH_TRAVERSAL
+          CUSTOM_ENCODED_REDOS
+          CUSTOM_ENCODED_REFLECTED_XSS
+          CUSTOM_ENCODED_REFLECTION_INJECTION
+          CUSTOM_ENCODED_SMTP_INJECTION
+          CUSTOM_ENCODED_SQL_INJECTION
+          CUSTOM_ENCODED_SSRF
+          CUSTOM_ENCODED_STORED_XSS
+          CUSTOM_ENCODED_TRUST_BOUNDARY_VIOLATION
+          CUSTOM_ENCODED_UNSAFE_CODE_EXECUTION
+          CUSTOM_ENCODED_UNSAFE_READLINE
+          CUSTOM_ENCODED_UNSAFE_XML_DECODE
+          CUSTOM_ENCODED_UNTRUSTED_DESERIALIZATION
+          CUSTOM_ENCODED_UNVALIDATED_FORWARD
+          CUSTOM_ENCODED_UNVALIDATED_REDIRECT
+          CUSTOM_ENCODED_XPATH_INJECTION
+          CUSTOM_ENCODED_XXE
+          CUSTOM_SECURITY_CONTROL_APPLIED
+
+          CUSTOM_VALIDATED
+          CUSTOM_VALIDATED_CMD_INJECTION
+          CUSTOM_VALIDATED_EXPRESSION_LANGUAGE_INJECTION
+          CUSTOM_VALIDATED_HEADER_INJECTION
+          CUSTOM_VALIDATED_HQL_INJECTION
+          CUSTOM_VALIDATED_LDAP_INJECTION
+          CUSTOM_VALIDATED_LOG_INJECTION
+          CUSTOM_VALIDATED_NOSQL_INJECTION
+          CUSTOM_VALIDATED_PATH_TRAVERSAL
+          CUSTOM_VALIDATED_REDOS
+          CUSTOM_VALIDATED_REFLECTED_XSS
+          CUSTOM_VALIDATED_REFLECTION_INJECTION
+          CUSTOM_VALIDATED_SMTP_INJECTION
+          CUSTOM_VALIDATED_SQL_INJECTION
+          CUSTOM_VALIDATED_SSRF
+          CUSTOM_VALIDATED_STORED_XSS
+          CUSTOM_VALIDATED_TRUST_BOUNDARY_VIOLATION
+          CUSTOM_VALIDATED_UNSAFE_CODE_EXECUTION
+          CUSTOM_VALIDATED_UNSAFE_READLINE
+          CUSTOM_VALIDATED_UNSAFE_XML_DECODE
+          CUSTOM_VALIDATED_UNTRUSTED_DESERIALIZATION
+          CUSTOM_VALIDATED_UNVALIDATED_FORWARD
+          CUSTOM_VALIDATED_UNVALIDATED_REDIRECT
+          CUSTOM_VALIDATED_XPATH_INJECTION
+          CUSTOM_VALIDATED_XXE
+
+          DATABASE_WRITE
+        ].cs__freeze
+
+        # @return [Array<Symbol>]
+        VALID_SOURCE_TAGS = %w[NO_NEWLINES UNTRUSTED CROSS_SITE LIMITED_CHARS].cs__freeze
+      end
+    end
+  end
+end

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

@@ -0,0 +1,134 @@
+# 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
+      # 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
+        include Contrast::Components::Logger::InstanceMethods
+
+        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
+          begin
+            validate
+          rescue ArgumentError => e
+            logger.error('FindingRequest validation failed with: ', e)
+            return
+          end
+
+          {
+              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) 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 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
+        include Contrast::Components::Logger::InstanceMethods
+
+        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
+        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('LibraryDiscovery validation failed with: ', e)
+            return
+          end
+
+          {
+              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
+          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