contrast-agent 3.8.4 → 6.9.0

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

@@ -0,0 +1,44 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/agent/reporting/reporting_events/application_reporting_event'
+require 'contrast/agent/reporting/reporting_events/application_startup_instrumentation'
+require 'contrast/config'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This is the new ApplicationStartup class which will include all the needed information for the new reporting
+      # system to report an Application has started; creating a new one or marking an existing one as online in the
+      # Contrast UI
+      class ApplicationStartup < Contrast::Agent::Reporting::ApplicationReportingEvent
+        def initialize
+          @event_method = :PUT
+          @event_endpoint = Contrast::Agent::Reporting::Endpoints::NG_ENDPOINTS[:application_create]
+          super
+        end
+
+        def file_name
+          'applications-create'
+        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]
+        def to_controlled_hash
+          app_config = ::Contrast::CONFIG.application
+          {
+              code: app_config.code,
+              group: app_config.group,
+              instrumentation: Contrast::Agent::Reporting::ApplicationStartupInstrumentation.new.to_controlled_hash,
+              metadata: app_config.metadata,
+              session_id: ::Contrast::CONFIG.session_id,
+              session_metadata: ::Contrast::CONFIG.session_metadata,
+              tags: app_config.tags
+          }.compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/components/protect'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This is the new ApplicationStartupInstrumentation class which will include all the needed information for the
+      # system to report the instrumentation mode to which the agent was set by local configuration.
+      class ApplicationStartupInstrumentation
+        # 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
+          {
+              protect: {
+                  enable: ::Contrast::PROTECT.enabled?
+              }
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# 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/architecture_component'
+require 'contrast/agent/reporting/reporting_events/application_reporting_event'
+require 'contrast/agent/reporting/reporting_events/library_discovery'
+require 'contrast/agent/reporting/reporting_events/reporting_event'
+require 'contrast/agent/reporting/reporting_events/route_discovery'
+require 'contrast/components/logger'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This is the new Application Update class which will include all the needed information for the new reporting
+      # system. Contains data used by TeamServer to render the Flow Map and SCA features.
+      #
+      # @attr_reader components [Array<Contrast::Agent::Reporting::ArchitectureComponent>]
+      # @attr_accessor libraries [Array<Contrast::Agent::Reporting::LibraryDiscovery>]
+      class ApplicationUpdate < Contrast::Agent::Reporting::ApplicationReportingEvent
+        attr_reader :components
+        attr_accessor :libraries
+
+        def initialize
+          @event_method = :PUT
+          @event_endpoint = "#{ Contrast::API.api_url }/api/ng/update/application"
+          @components = []
+          @libraries = []
+          super
+        end
+
+        def file_name
+          'update-application'
+        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
+          {
+              components: components.map(&:to_controlled_hash),
+              libraries: libraries.map(&:to_controlled_hash),
+              timestamp: since_last_update
+          }
+        end
+
+        # Ensure the required fields are present.
+        #
+        # @raise [ArgumentError]
+        def validate; end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# 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 Architecture Component class which will include all the needed information for the new
+      # reporting system to relay this information in the Application Update and Application Activity messages. These
+      # components are used by TeamServer to construct the backend/ outbound connection section of the Flow Map
+      # feature.
+      #
+      # @attr_reader remote_host [String] the host section of the connection to the component.
+      # @attr_reader remote_port [Integer] the port section of the connection to the component.
+      # @attr_reader type [String] the type of the component. Only ::VALID_TYPES can be used. Required for reporting.
+      # @attr_reader url [String] the url used to connect to the component. Required for reporting.
+      # @attr_reader vendor [String] the publisher of the component, like MySQL.
+      class ArchitectureComponent
+        include Contrast::Components::Logger::InstanceMethods
+        # required attributes
+        attr_accessor :type, :url
+        # optional attributes
+        attr_accessor :remote_host, :remote_port, :vendor
+
+        # TeamServer only treats these specific values as valid for Architecture Components. It does not know how to
+        # process a message with a different type.
+        AC_TYPE_DB = 'db'
+        VALID_TYPES = %w[db ldap ws].cs__freeze
+
+        class << self
+          def build_database
+            msg = new
+            msg.type = AC_TYPE_DB
+            msg
+          end
+        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('ArchitectureComponent validation failed with: ', e)
+            return
+          end
+          {
+              remoteHost: remote_host,
+              remotePort: remote_port,
+              type: type,
+              url: url,
+              vendor: vendor
+          }
+        end
+
+        # Ensure the required fields are present.
+        #
+        # @raise [ArgumentError]
+        def validate
+          unless VALID_TYPES.include?(type)
+            raise(ArgumentError, "#{ self } did not have a proper type - '#{ type }'. Unable to continue.")
+          end
+          raise(ArgumentError, "#{ self } did not have a proper URL. Unable to continue.") unless url
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,126 @@
+# 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 Discovered Route 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 DiscoveredRoute < Contrast::Agent::Reporting::ObservedRoute
+        include Contrast::Components::Logger::InstanceMethods
+
+        class << self
+          # @param obj [Regexp, Object]
+          # @return [String]
+          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
+
+          # Convert ActionDispatch::Journey::Route to Contrast::Agent::Reporting::DiscoveredRoute
+          #
+          # @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::DiscoveredRoute]
+          def from_action_dispatch_journey journey_obj, url = nil
+            msg = new
+            msg.signature = "#{ journey_obj.defaults[:controller] }##{ journey_obj.defaults[:action] }"
+
+            verb = source_or_string(journey_obj.verb)
+            msg.verb = Contrast::Utils::StringUtils.force_utf8(verb)
+
+            url ||= source_or_string(journey_obj.path.spec)
+            msg.url = Contrast::Utils::StringUtils.force_utf8(url)
+            msg
+          end
+
+          # Convert Grape route data to discovered route.
+          #
+          # @param controller [::Grape::API] the route's final controller.
+          # @param method [String] GET, PUT, POST, etc...
+          # @param url [String, nil] use url from string instead matched pattern.
+          # @param pattern [String, Grape::Router::Route] the pattern that was matched in routing.
+          # @return [Contrast::Agent::Reporting::DiscoveredRoute]
+          def from_grape_controller controller, method, pattern, url = nil
+            if pattern.cs__is_a?(Grape::Router::Route)
+              safe_pattern = pattern.pattern&.path&.to_s
+              safe_url = source_or_string(url || safe_pattern)
+            else
+              safe_pattern = source_or_string(pattern)
+              safe_url = source_or_string(url || pattern)
+            end
+
+            msg = new
+            msg.signature = "#{ controller }##{ method } #{ safe_pattern }"
+            msg.verb = Contrast::Utils::StringUtils.force_utf8(method)
+            msg.url = Contrast::Utils::StringUtils.force_utf8(safe_url)
+            msg
+          end
+
+          # Convert Sinatra route data to discovered route.
+          #
+          # @param controller [::Sinatra::Base] the route's final controller.
+          # @param method [String] GET, PUT, POST, etc...
+          # @param pattern [::Mustermann::Sinatra]  the pattern that was matched in routing.
+          # @param url [String, nil] use url from string instead matched pattern.
+          # @return [Contrast::Agent::Reporting::DiscoveredRoute]
+          def from_sinatra_route controller, method, pattern, url = nil
+            safe_pattern = source_or_string(pattern)
+            safe_url = source_or_string(url || pattern)
+
+            msg = new
+            msg.signature = "#{ controller }##{ method } #{ safe_pattern }"
+            msg.verb = Contrast::Utils::StringUtils.force_utf8(method)
+            msg.url = Contrast::Utils::StringUtils.force_utf8(safe_url)
+            msg
+          end
+        end
+
+        # @return [String] the controller, method, and pattern of this route
+        attr_accessor :signature
+        # @return [String] the url (or url pattern) used to access this route
+        attr_accessor :url
+        # @return [String, nil] the HTTP verb used to access this route or nil for any verb
+        attr_accessor :verb
+
+        def initialize
+          super
+          @event_type = :discovered_route
+          @signature = Contrast::Utils::ObjectShare::EMPTY_STRING
+          @verb = Contrast::Utils::ObjectShare::EMPTY_STRING
+          @url = Contrast::Utils::ObjectShare::EMPTY_STRING
+        end
+
+        def to_controlled_hash
+          begin
+            validate
+          rescue ArgumentError => e
+            logger.error('DiscoveredRoute validation failed with: ', e)
+            return
+          end
+          { session_id: ::Contrast::ASSESS.session_id, signature: @signature, verb: @verb, url: @url }.compact
+        end
+
+        def validate
+          raise(ArgumentError, "#{ self } did not have a proper signature. Unable to continue.") unless signature
+
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,210 @@
+# 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/application_reporting_event'
+require 'contrast/agent/reporting/reporting_events/finding_event'
+require 'contrast/agent/reporting/reporting_events/finding_request'
+require 'contrast/agent/assess/events/event_data'
+require 'contrast/utils/timer'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This is the new Finding class which will include all the needed information for the new reporting system to
+      # relay this information in the Finding/Trace messages. These findings are used by TeamServer to construct the
+      # vulnerability information for the assess feature. They represent those parts of the application, either through
+      # configuration, method invocation, or dataflow, which are determined to be insecure.
+      class Finding < Contrast::Agent::Reporting::ApplicationReportingEvent
+        include Contrast::Components::Logger::InstanceMethods
+
+        # @return [Integer] the time, in ms, that this object was initialized
+        attr_reader :created
+        # @return [String] the ID of the rule associated with this finding
+        attr_reader :rule_id
+        # @return [Array<Contrast::Agent::Reporting::RouteDiscovery>] the routes associated with this finding, if the
+        #   finding is request based.
+        attr_reader :routes
+        # @return [Array<Contrast::Agent::Reporting::FindingEvent>] the events associated with this finding, if the
+        #   finding is event (dataflow) based.
+        attr_reader :events
+        # # @return [String] the evidence associated with this finding, if the finding is event based. deprecated in
+        # #   favor of properties
+        # attr_reader :evidence
+        # @return [Hash<String,String>] properties that prove the violation of the rule for this finding
+        attr_reader :properties
+        # @return [Contrast::Agent::Reporting::FindingRequest] the request associated with this finding, if the finding
+        #   is request based
+        attr_accessor :request
+        # @return [String] the uniquely identifying hash of this finding
+        attr_accessor :hash_code
+
+        CONFIGURATION_RULES = %w[rails-http-only-disabled secure-flag-missing session-timeout].cs__freeze
+        HARDCODED_RULES = %w[hardcoded-key hardcoded-password].cs__freeze
+        PROPERTIES_RULES = %w[
+          autocomplete-missing
+          cache-controls-missing
+          clickjacking-control-missing
+          csp-header-missing
+          csp-header-insecure
+          hsts-header-missing
+          parameter-pollution
+          xcontenttype-header-missing
+          xxssprotection-header-disabled
+        ].cs__freeze
+
+        def initialize rule_id
+          @event_method = :PUT
+          @event_endpoint = "#{ Contrast::API.api_url }/api/ng/traces"
+          @events = []
+          @routes = []
+          @rule_id = Contrast::Utils::StringUtils.truncate(rule_id)
+          @properties = {}
+          @created = Contrast::Utils::Timer.now_ms
+          super()
+        end
+
+        def file_name
+          'traces'
+        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
+          request['Report-Hash'] = hash_code
+        end
+
+        # @param trigger_node [Contrast::Agent::Assess::Policy::TriggerNode] the node to direct applying this
+        #   trigger event
+        # @param source [Object] the source of the Trigger Event
+        # @param object [Object] the Object on which the method was invoked
+        # @param ret [Object] the Return of the invoked method
+        # @param request [Contrast::Agent::Request]
+        # @param args [Array<Object>] the Arguments with which the method was invoked
+        def attach_data trigger_node, source, object, ret, request, *args
+          event_messages = Contrast::Agent::Reporting::FindingEvent.from_source(source)
+          events.concat(event_messages) if event_messages&.any?
+          event_data = Contrast::Agent::Assess::Events::EventData.new(trigger_node, source, object, ret, args)
+          contrast_event = Contrast::Agent::Reporting::FindingEvent.new(event_data)
+          events << contrast_event
+          return unless request
+
+          @request = Contrast::Agent::Reporting::FindingRequest.convert(request)
+          @routes << request.discovered_route if request.discovered_route
+        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('Finding event validation failed with: ', e)
+            return
+          end
+
+          hsh = base_hash
+          hsh[:events] = events.map(&:to_controlled_hash) if events.any?
+          hsh[:properties] = properties if properties.any?
+          hsh[:tags] = Contrast::ASSESS.tags if Contrast::ASSESS.tags
+          return hsh unless request_based?
+
+          hsh[:request] = request.to_controlled_hash
+          hsh[:routes] = routes.map(&:to_controlled_hash)
+          hsh
+        end
+
+        # @return [Hash] the base of every finding, regardless of type
+        def base_hash
+          {
+              created: created,
+              hash: hash_code.to_s,
+              ruleId: rule_id,
+              session_id: ::Contrast::ASSESS.session_id,
+              version: 4
+          }
+        end
+
+        # @raise [ArgumentError]
+        def validate
+          raise(ArgumentError, "#{ self } did not have a proper rule. Unable to continue.") unless @rule_id
+          unless ::Contrast::ASSESS.session_id
+            raise(ArgumentError, "#{ self } did not have a proper session id. Unable to continue.")
+          end
+          if event_based? && events.empty?
+            raise(ArgumentError, "#{ self } did not have proper events for #{ @rule_id }. Unable to continue.")
+          end
+          if property_based? && properties.empty?
+            raise(ArgumentError, "#{ self } did not have proper properties for #{ @rule_id }. Unable to continue.")
+          end
+          return unless request_based? && request.nil?
+
+          raise(ArgumentError, "#{ self } did not have a proper request for #{ @rule_id }. Unable to continue.")
+        end
+
+        private
+
+        def build_events events, event
+          return unless event
+
+          event.parent_events&.each do |parent_event|
+            build_events(events, parent_event)
+          end
+          events << event
+        end
+
+        # Rules which are event based must have an event to be sent to TeamServer. They include the Trigger, Regexp,
+        # and Data flow type Rules, meaning all those which are not Properties based. Eventually, we may have
+        # validation for each of those types; however, that's a refactor for after we've translated all rules from the
+        # TeamServer and have had time to build proper child structure.
+        #
+        # @return [Boolean]
+        def event_based?
+          !property_based? && !config_based? && !hardcoded?
+        end
+
+        # Rules which are property based must have a property to be sent to TeamServer. Eventually, each rule may own
+        # its own validation, as the properties each needs are different; however, that's a refactor for after we've
+        # translated all rules from TeamServer and have had time to build proper child structure.
+        #
+        # @return [Boolean]
+        def property_based?
+          PROPERTIES_RULES.include?(@rule_id)
+        end
+
+        # Rules which are config based must have a configuration to be sent to TeamServer. Eventually, each rule may own
+        # its own validation, as the properties each needs are different; however, that's a refactor for after we've
+        # translated all rules from TeamServer and have had time to build proper child structure.
+        #
+        # @return [Boolean]
+        def config_based?
+          CONFIGURATION_RULES.include?(@rule_id)
+        end
+
+        # Rules which are hardcode based send properties to TeamServer. Eventually, each rule may own its own
+        # validation, as the properties each needs are different; however, that's a refactor for after we've
+        # translated all rules from TeamServer and have had time to build proper child structure.
+        #
+        # @return [Boolean]
+        def hardcoded?
+          HARDCODED_RULES.include?(@rule_id)
+        end
+
+        # Rules which are request based must have a request to be sent to TeamServer. Most rules fit this category, so
+        # we'll default to true for now. Eventually, this will be split out for those rules, like Hardcoded, which do
+        # not need requests.
+        #
+        # @return [Boolean]
+        def request_based?
+          !config_based? && !hardcoded?
+        end
+      end
+    end
+  end
+end