contrast-agent 4.11.0 → 4.14.0

data/lib/contrast/api/communication/service_lifecycle.rb

@@ -13,6 +13,10 @@ module Contrast
 
         private
 
+        # Attempt to start up a local process with SpeedRacer. This will ensure the process isn't just a zombie and is
+        # a real functioning process.
+        #
+        # @return [Boolean] Did the SpeedRacer process start?
         def attempt_local_service_startup
           zombie_check
           service_starter_thread.join(5)
@@ -25,8 +29,8 @@ module Contrast
           is_service_started
         end
 
-        # check if there's a zombie service that exists, and wait on it if so. currently, this only happens when trying
-        # to initialize speedracer
+        # Check if there's a zombie service that exists, and wait on it if so. Currently, this only happens when trying
+        # to initialize SpeedRacer. If there is a zombie, we'll wait until the zombie completes.
         def zombie_check
           zombie_pid_list = Contrast::Utils::OS.zombie_pids
           zombie_pid_list.each do |pid|
@@ -36,6 +40,10 @@ module Contrast
           end
         end
 
+        # Determine the options used to set up the SpeedRacer process. Specifically, this handles if we need to adjust
+        # where the process needs to log.
+        #
+        # @return [Hash] options used to spawn the SpeedRacer process
         def determine_startup_options
           return { out: :out, err: :out } if ::Contrast::CONTRAST_SERVICE.logger_path == 'STDOUT'
           return { out: :err, err: :err } if ::Contrast::CONTRAST_SERVICE.logger_path == 'STDERR'
@@ -43,13 +51,15 @@ module Contrast
           { out: File::NULL, err: File::NULL }
         end
 
-        # This is a separate method so we can overwrite it globally in specs
+        # Create a new process for the SpeedRacer. This is a separate method so we can overwrite it globally in specs.
         def spawn_service
           options = determine_startup_options
           logger.debug('Spawning service')
           spawn 'contrast_service', options
         end
 
+        # Create a thread to start the SpeedRacer, making calls to spawn until one starts successfully. As soon as the
+        # SpeedRacer process starts, this thread terminates.
         def service_starter_thread
           Contrast::Agent::Thread.new do
             # Always check to see if it already started

data/lib/contrast/api/communication/socket.rb

@@ -4,16 +4,15 @@
 module Contrast
   module Api
     module Communication
-      # Behavior common to all sockets used
-      # to communicate with the Contrast Service.
+      # Behavior common to all sockets used to communicate with the Contrast Service.
       module Socket
         SOCKET_MONITOR = Monitor.new
 
         # Send a message across the socket and read back the response.
-        # @param marshaled [String] some marshaled form of data to be sent across
-        #   the socket. Typically an encoded form of Contrast::Api::Dtm::Message.
-        # @return [String] some marshalled form of data returned by the socket.
-        #   Typically an encoded form of Contrast::Api::Settings::AgentSettings.
+        # @param marshaled [String] some marshaled form of data to be sent across the socket. Typically an encoded form
+        #   of Contrast::Api::Dtm::Message.
+        # @return [String] some marshalled form of data returned by the socket. Typically an encoded form of
+        #   Contrast::Api::Settings::AgentSettings.
         def send_marshaled marshaled
           SOCKET_MONITOR.synchronize do
             socket = new_socket
@@ -34,8 +33,7 @@ module Contrast
           end
         end
 
-        # Override this method to return a socket.
-        # Should be interface compatible with TCPSocket, UNIXSocket, etc.
+        # Override this method to return a socket. Should be interface compatible with TCPSocket, UNIXSocket, etc.
         def new_socket
           raise NoMethodError, 'This is abstract, override it.'
         end

data/lib/contrast/api/communication/socket_client.rb

@@ -11,8 +11,8 @@ require 'contrast/components/logger'
 module Contrast
   module Api
     module Communication
-      # SocketClient acts as a interface between the agent and the service. It instantiates a
-      # service proxy and tracks the state of that proxy.
+      # SocketClient acts as a interface between the agent and the service. It instantiates a service proxy and tracks
+      # the state of that proxy.
       class SocketClient
         include Contrast::Components::Logger::InstanceMethods
 
@@ -20,12 +20,13 @@ module Contrast
           @socket = init_connection
         end
 
-        # Wrap the given DTM in a Contrast::Api::Dtm::Message and send it to the
-        # Service for processing
+        # Wrap the given DTM in a Contrast::Api::Dtm::Message and send it to the SpeedRacer for processing. The
+        # Message is the top level object required to communicate to SpeedRacer as it encompasses the information
+        # needed to find this process' context.
         #
         # @param event [Contrast::Api::Dtm] One of the DTMs valid for the event field of
         #   Contrast::Api::Dtm::Message
-        # @return [Contrast::Api::Settings::AgentSettings]
+        # @return [Contrast::Api::Settings::AgentSettings, nil]
         def send_one event
           msg = Contrast::Api::Dtm::Message.build(event)
           send_message(msg)
@@ -33,6 +34,12 @@ module Contrast
 
         private
 
+        # Initialize the connection to the SpeedRacer process based on the configuration provided by the user. This can
+        # be either TCP or UDP. Note that unlike the Go and the Node Agents, we cannot use the GRPC communication
+        # option as we cannot use Google's protobuf gems; they do not compile reliably and result in segmentation
+        # faults in customer environments.
+        #
+        # @return [Contrast::Api::Communication::TcpSocket, Contrast::Api::Communication::UnixSocket]
         def init_connection
           log_connection
           if ::Contrast::CONTRAST_SERVICE.use_tcp?
@@ -43,6 +50,7 @@ module Contrast
           end
         end
 
+        # Log information about the connection being used to communicate between the Agent and SpeedRacer.
         def log_connection
           # The socket is set,
           if ::Contrast::CONFIG.root.agent.service.socket
@@ -72,19 +80,24 @@ module Contrast
         def log_connection_error_msg
           if ::Contrast::CONFIG.root.agent.service.host
             'Missing a required connection value to the Contrast Service. ' \
-            '`agent.service.port` is not set. ' \
-            'Falling back to default TCP socket port.'
+              '`agent.service.port` is not set. ' \
+              'Falling back to default TCP socket port.'
           elsif ::Contrast::CONFIG.root.agent.service.port
             'Missing a required connection value to the Contrast Service. ' \
-            '`agent.service.host` is not set. ' \
-            'Falling back to default TCP socket host.'
+              '`agent.service.host` is not set. ' \
+              'Falling back to default TCP socket host.'
           else
             'Missing a required connection value to the Contrast Service. ' \
-            'Neither `agent.service.socket` nor the pair of `agent.service.host` and `agent.service.port` are set. '\
-            'Falling back to default TCP socket.'
+              'Neither `agent.service.socket` nor the pair of `agent.service.host` and `agent.service.port` are set. '\
+              'Falling back to default TCP socket.'
           end
         end
 
+        # Send the given message to SpeedRacer and return the response from it.
+        #
+        # @param msg [Contrast::Api::Dtm::Message] the packaged message to send to SpeedRacer
+        # @return [Contrast::Api::Settings::AgentSettings, nil]
+        # @raise [StandardError] if unable to send a message to SpeedRacer
         def send_message msg
           return unless msg
 
@@ -98,9 +111,13 @@ module Contrast
         rescue StandardError => e
           logger.error('Sending failed for message.', e, msg_id: msg.__id__, p_id: msg.pid,
                                                          msg_count: msg.message_count, response_id: response&.__id__)
-          raise e # reraise to let Speedracer manage the connection
+          raise e # reraise to let SpeedRacer manage the connection
         end
 
+        # Send the marshaled Contrast::Api::Dtm::Message across the socket used to talk to SpeedRacer
+        #
+        # @param marshaled [String]
+        # @return [String] the marshaled from of Contrast::Api::Settings::AgentSettings
         def send_marshaled marshaled
           @socket.send_marshaled(marshaled)
         end

data/lib/contrast/api/communication/speedracer.rb

@@ -6,7 +6,10 @@ require 'contrast/components/logger'
 module Contrast
   module Api
     module Communication
-      # Wraps all connection data to speedracer
+      # Wraps all connection data to SpeedRacer. SpeedRacer, also known as the Contrast Service, is a standalone
+      # executable that sits between the Agent and TeamServer. It handles converting our Protobuf messages into a
+      # format consumable by TeamServer. The Agent requires a SpeedRacer process to be running somewhere to which it
+      # can connect, as specified by the user configuration, in order to function.
       class Speedracer
         include Contrast::Api::Communication::ServiceLifecycle
         include Contrast::Components::Logger::InstanceMethods
@@ -20,6 +23,14 @@ module Contrast
           @ensure_running = Mutex.new
         end
 
+        # If there is not a SpeedRacer at the location specified by the configuration of this Agent and the Agent is
+        # set such that it should manage one, start up a new child process to run the SpeedRacer executable. If a
+        # connection has not already been made to that process, after starting it, this method will also send the
+        # messages necessary to create a context for this Agent process in the SpeedRacer as well as trigger
+        # SpeedRacer's sending of startup messages which will return features and settings from TeamServer.
+        #
+        # This operation is synchronous and blocking, so it will only happen one at a time per process and will halt
+        # Thread execution here until completion.
         def ensure_startup!
           return if status.connected?
 
@@ -40,12 +51,24 @@ module Contrast
           end
         end
 
+        # Send the given Event to SpeedRacer, returning the response from it. This response will either be new settings
+        # if anything's changed in TeamServer meaning the Agent needs to replace its current settings or there is
+        # Protect analysis information or nil if the current Agent settings do not need updating.
+        #
+        # @param event [Contrast::Api::Dtm] One of the DTMs valid for the event field of
+        # Contrast::Api::Dtm::Message|Contrast::Api::Dtm::Activity
+        # @return [Contrast::Api::Settings::AgentSettings,nil]
         def return_response event
           send_to_speedracer(event) do |response|
             return response
           end
         end
 
+        # Send the given Event to SpeedRacer and pass the result to our Contrast::Api::Communication::ResponseProcessor
+        # as there is no immediate action required from sending this Event.
+        #
+        # @param event [Contrast::Api::Dtm] One of the DTMs valid for the event field of
+        # Contrast::Api::Dtm::Message|Contrast::Api::Dtm::Activity
         def process_internally event
           send_to_speedracer(event) do |response|
             response_processor.process(response)
@@ -54,6 +77,12 @@ module Contrast
 
         private
 
+        # Ensure there is a running SpeedRacer and then send the given Event to it. It is necessary to ensure the
+        # SpeedRacer is running as, if the process has crashed or restarted, we must rebuild our context there.
+        #
+        # @param event [Contrast::Api::Dtm] One of the DTMs valid for the event field of
+        # Contrast::Api::Dtm::Message|Contrast::Api::Dtm::Activity
+        # @return [Contrast::Api::Settings::AgentSettings, nil]
         def send_to_speedracer event
           ensure_startup!
 
@@ -68,6 +97,9 @@ module Contrast
           nil
         end
 
+        # Send those messages which are required to build a context for this Agent process on SpeedRacer as well as
+        # report server and application startup to TeamServer. With these messages, the SpeedRacer will be able to
+        # retrieve settings from TeamServer and provide those for the Agent to complete its initialization.
         def send_initialization_messages
           agent_startup_msg = ::Contrast::APP_CONTEXT.build_agent_startup_message
 
@@ -97,6 +129,10 @@ module Contrast
           nil
         end
 
+        # Log the startup message we're sending to SpeedRacer
+        #
+        # @param event [Contrast::Api::Dtm] One of the DTMs valid for the event field of
+        # Contrast::Api::Dtm::Message|Contrast::Api::Dtm::Activity
         def log_send_event event
           logger.debug('Immediately sending event.', event_id: event.__id__, event_type: event.cs__class.cs__name)
         end

data/lib/contrast/api/communication/tcp_socket.rb

@@ -6,15 +6,15 @@ require 'contrast/api/communication/socket'
 module Contrast
   module Api
     module Communication
-      # This class allows us to create a TCP Socket to communicate to the Service
-      # (Speed Racer). Either it or the Unix Socket will be used, as determined
-      # by the configuration options set for Service communication.
+      # This class allows us to create a TCP Socket to communicate to the Service (Speed Racer). Either it or the Unix
+      # Socket will be used, as determined by the configuration options set for Service communication.
       class TcpSocket
         include Contrast::Api::Communication::Socket
 
         attr_reader :host, :port
 
         # Create the socket
+        #
         # @param host [String] socket target hostname or IP address
         # @param port [String,Integer] socket target port
         def initialize host, port
@@ -22,6 +22,7 @@ module Contrast
           @port = port.to_i
         end
 
+        # @return [::TCPSocket]
         def new_socket
           ::TCPSocket.new(host, port)
         end

data/lib/contrast/api/communication/unix_socket.rb

@@ -18,6 +18,7 @@ module Contrast
           @path = path
         end
 
+        # @return [::UNIXSocket]
         def new_socket
           ::UNIXSocket.new(path)
         end

data/lib/contrast/api/decorators/finding.rb

@@ -0,0 +1,45 @@
+# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/api/dtm.pb'
+require 'contrast/utils/string_utils'
+require 'contrast/components/base'
+
+module Contrast
+  module Api
+    module Decorators
+      # Used to decorate the {Contrast::Api::Dtm::Finding} protobuf
+      # model so it can own the request which its data is for.
+      module Finding
+        def self.included klass
+          klass.extend(ClassMethods)
+        end
+
+        # Used to add class methods to the AgentStartup class on inclusion of the decorator
+        module ClassMethods
+          def build
+            new
+          end
+
+          def to_controlled_hash finding, *_args
+            {
+                hash_code: finding.hash_code,
+                platform: finding.platform,
+                rule_id: finding.rule_id,
+                evidence: finding.evidence,
+                properties: finding.properties,
+                events: finding.events,
+                tags: finding.tags,
+                version: finding.version,
+                routes: finding.routes,
+                session_id: finding.session_id,
+                teamserver_url: ::Contrast::API.api_url
+            }
+          end
+        end
+      end
+    end
+  end
+end
+
+Contrast::Api::Dtm::Finding.include(Contrast::Api::Decorators::Finding)

data/lib/contrast/components/api.rb

@@ -0,0 +1,90 @@
+# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/components/base'
+require 'contrast/components/config'
+
+module Contrast
+  module Components
+    module Api
+      # A wrapper build around the Common Agent Configuration project to allow
+      # for Api keys to be mapped with their values contained in their
+      # parent_configuration_spec.yaml.
+      class Interface
+        include Contrast::Components::ComponentBase
+
+        def api_url
+          @_api_url ||= ::Contrast::CONFIG.root.api.url
+        end
+
+        def api_key
+          @_api_key ||= ::Contrast::CONFIG.root.api.api_key
+        end
+
+        def service_key
+          @_service_key ||= ::Contrast::CONFIG.root.api.service_key
+        end
+
+        def username
+          @_username ||= ::Contrast::CONFIG.root.api.user_name
+        end
+
+        def proxy_enabled?
+          @_proxy_enabled = true?(::Contrast::CONFIG.root.api.proxy.enable) if @_proxy_enabled.nil?
+          @_proxy_enabled
+        end
+
+        def proxy_url
+          @_proxy_url ||= ::Contrast::CONFIG.root.api.proxy.url
+        end
+
+        def request_audit_enable
+          @_request_audit_enable ||= true?(::Contrast::CONFIG.root.api.request_audit.enable)
+        end
+
+        def request_audit_requests
+          return @_request_audit_requests unless @_request_audit_requests.nil?
+
+          @_request_audit_requests = true?(::Contrast::CONFIG.root.api.request_audit.requests)
+        end
+
+        def request_audit_responses
+          return @_request_audit_responses unless @_request_audit_responses.nil?
+
+          @_request_audit_responses = true?(::Contrast::CONFIG.root.api.request_audit.responses)
+        end
+
+        def request_audit_path
+          @_request_audit_path ||= ::Contrast::CONFIG.root.api.request_audit.path.to_s
+        end
+
+        def certification_enabled?
+          @_certification_enabled ||= certification_truly_enabled?(::Contrast::CONFIG.root.api.certificate)
+        end
+
+        def certification_ca_file
+          @_certification_ca_file ||= ::Contrast::CONFIG.root.api.certificate.ca_file
+        end
+
+        def certification_cert_file
+          @_certification_cert_file ||= ::Contrast::CONFIG.root.api.certificate.cert_file
+        end
+
+        def certification_key_file
+          @_certification_key_file ||= ::Contrast::CONFIG.root.api.certificate.key_file
+        end
+
+        private
+
+        def certification_truly_enabled? config_path
+          return false unless true?(config_path.enable)
+          return true if file_exists?(certification_ca_file) && valid_cert?(certification_ca_file)
+          return true if file_exists?(certification_cert_file) && valid_cert?(certification_cert_file)
+          return true if file_exists?(certification_key_file) && valid_cert?(certification_key_file)
+
+          false
+        end
+      end
+    end
+  end
+end

data/lib/contrast/components/app_context.rb

@@ -5,6 +5,7 @@ require 'rubygems/version'
 require 'contrast/api/decorators/agent_startup'
 require 'contrast/api/decorators/application_startup'
 require 'contrast/utils/object_share'
+require 'contrast/components/app_context_extend'
 
 module Contrast
   module Components
@@ -15,6 +16,7 @@ module Contrast
       # Specifically, this allows for querying the state of the Application,
       # including the Client, Process, and Server information.
       class Interface
+        include Contrast::Components::AppContextExtend
         include Contrast::Components::ComponentBase
         include Contrast::Components::Logger::InstanceMethods
 
@@ -46,6 +48,14 @@ module Contrast
           end
         end
 
+        def session_id
+          @_session_id ||= build_app_startup_message.session_id
+        end
+
+        def app_version
+          @_app_version ||= Contrast::CONFIG.root.application.version
+        end
+
         def path
           @_path ||= begin
             tmp = ::Contrast::CONFIG.root.application.path
@@ -76,47 +86,6 @@ module Contrast
           end
         end
 
-        def build_app_startup_message
-          Contrast::Api::Dtm::ApplicationCreate.build
-        end
-
-        def build_agent_startup_message
-          msg = Contrast::Api::Dtm::AgentStartup.build(server_name, server_path, server_type)
-          logger.info('Application context',
-                      server_name: msg.server_name,
-                      server_path: msg.server_path,
-                      server_type: msg.server_type,
-                      application_name: app_name,
-                      application_path: path,
-                      application_language: Contrast::Utils::ObjectShare::RUBY)
-
-          msg
-        end
-
-        def pid
-          Process.pid
-        end
-
-        def ppid
-          Process.ppid
-        end
-
-        def pgid
-          Process.getpgid(pid)
-        end
-
-        def client_id
-          @_client_id ||= [app_name, pgid].join('-')
-        end
-
-        def instrument_middleware_stack?
-          !Contrast::Utils::JobServersRunning.job_servers_running?
-        end
-
-        def disabled_agent_rake_tasks
-          ::Contrast::CONFIG.root.agent.ruby.disabled_agent_rake_tasks
-        end
-
         # Determines if the Process we're currently in matches that of the
         # Process in which the App Context instance was created.
         # If it doesn't, that indicates the running context is in a new

data/lib/contrast/components/app_context_extend.rb

@@ -0,0 +1,78 @@
+# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+module Contrast
+  module Components
+    # A wrapper build around the Common Agent Configuration project to allow
+    # for access of the values contained in its
+    # parent_configuration_spec.yaml.
+    # Specifically, this allows for querying the state of the Application,
+    # including the Client, Process, and Server information.
+    module AppContextExtend
+      SUPPORTED_FRAMEWORKS = %w[rails sinatra grape rack].cs__freeze
+      SUPPORTED_SERVERS = %w[passenger puma thin unicorn].cs__freeze
+
+      def build_app_startup_message
+        @_build_app_startup_message ||= Contrast::Api::Dtm::ApplicationCreate.build
+      end
+
+      def build_agent_startup_message
+        msg = Contrast::Api::Dtm::AgentStartup.build(server_name, server_path, server_type)
+        logger.info('Application context',
+                    server_name: msg.server_name,
+                    server_path: msg.server_path,
+                    server_type: msg.server_type,
+                    application_name: app_name,
+                    application_path: path,
+                    application_language: Contrast::Utils::ObjectShare::RUBY)
+
+        msg
+      end
+
+      def pid
+        Process.pid
+      end
+
+      def ppid
+        Process.ppid
+      end
+
+      def pgid
+        Process.getpgid(pid)
+      end
+
+      def client_id
+        @_client_id ||= [app_name, pgid].join('-')
+      end
+
+      def app_and_server_information
+        {
+            application_info: find_gem_information(SUPPORTED_FRAMEWORKS),
+            server_info: find_gem_information(SUPPORTED_SERVERS)
+        }
+      end
+
+      def find_gem_information arr
+        arr.each do |framework|
+          next unless Gem.loaded_specs.key?(framework)
+
+          loaded = Gem.loaded_specs[framework]
+          next unless loaded
+
+          name = loaded.instance_variable_get(:@name)
+          version = loaded.instance_variable_get(:@version).to_s
+          return [name, version].join(' ')
+        end
+        nil
+      end
+
+      def instrument_middleware_stack?
+        !Contrast::Utils::JobServersRunning.job_servers_running?
+      end
+
+      def disabled_agent_rake_tasks
+        ::Contrast::CONFIG.root.agent.ruby.disabled_agent_rake_tasks
+      end
+    end
+  end
+end

data/lib/contrast/components/assess.rb

@@ -88,6 +88,13 @@ module Contrast
           @_require_scan
         end
 
+        def require_dynamic_sources?
+          if @_require_dynamic_sources.nil?
+            @_require_dynamic_sources = !false?(::Contrast::CONFIG.root.assess.enable_dynamic_sources)
+          end
+          @_require_dynamic_sources
+        end
+
         def tags
           ::Contrast::CONFIG.root.assess&.tags
         end

data/lib/contrast/components/base.rb

@@ -35,6 +35,29 @@ module Contrast
 
         config_param.downcase == Contrast::Utils::ObjectShare::TRUE
       end
+
+      # this method will check if a path could be possibly used
+      # So for example if we pass a path to a file - we'll check
+      # if there is actually that file and if it's with certain extension
+      #
+      # @param config_path [String,nil]
+      # @return [Boolean]
+      def valid_cert? config_path
+        return false if config_path.nil?
+
+        exts = %w[.pem .crt .cer].cs__freeze
+        return false unless exts.include?(File.extname(config_path))
+
+        true
+      end
+
+      # check if file exists at all
+      # @param path [String,nil]
+      def file_exists? path
+        return false unless path
+
+        File.exist? path
+      end
     end
   end
 end