contrast-agent 6.7.0 → 6.9.0

data/lib/contrast/agent_lib/api/panic.rb

@@ -0,0 +1,87 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: false
+
+require 'ffi'
+# require the gem
+require 'contrast-agent-lib'
+require 'contrast/utils/object_share'
+
+module Contrast
+  module AgentLib
+    # This module is defined in Rust as external, we used it here.
+    # Initializes the AgentLib. Here will be all methods from
+    # the C bindings contrast_c::panic_error module.
+    module Panic
+      extend FFI::Library
+      ffi_lib ContrastAgentLib::CONTRAST_C
+
+      attach_function :last_error_message, %i[pointer int32 pointer int32], :int32
+      attach_function :last_error_message_length, [], :int32
+      attach_function :last_error_stack_length, [], :int32
+
+      private
+
+      # Returns the last Error message saved for the thread.
+      # If there is no message it will return empty string.
+      #
+      # @return [String] Empty string if no errors, or a
+      # message + stack trace concat String.
+      def dl__get_error
+        message_length = last_error_message_length
+        stack_length = last_error_stack_length
+        return Contrast::Utils::ObjectShare::EMPTY_STRING if message_length.zero?
+
+        # If the buffer size is retrieved as 0 we need to add 1 byte for it
+        # else the Agent-Lib check for allocated memory would fail.
+        stack_length += 1 if stack_length.zero?
+        message_buffer = FFI::MemoryPointer.new(:char, message_length)
+        stack_buffer = FFI::MemoryPointer.new(:char, stack_length)
+        return dl__parse_error(message_buffer, stack_buffer) if last_error_message(message_buffer,
+                                                                                   message_length,
+                                                                                   stack_buffer,
+                                                                                   stack_length).positive?
+
+        Contrast::Utils::ObjectShare::EMPTY_STRING
+      ensure
+        # The free methods are auto called form the FFI::MemoryPointer
+        # when the variable is out of scope. Making sure it's all free,
+        # and call with safe navigation if is been already cleaned.
+        message_buffer&.free
+        stack_buffer&.free
+      end
+
+      # Retrieves the buffer bytecode and transforms it into String.
+      #
+      # @param buffer [FFI::MemoryPointer, nil] of type char (String)
+      # @return [String] the received message.
+      def dl__read_buffer buffer
+        return Contrast::Utils::ObjectShare::EMPTY_STRING unless buffer
+
+        string = buffer.read_string
+        return string unless string.empty?
+
+        # If there is a incorrect buffer size or the message can't be read
+        # from the FFI::MemoryPointer#read_string method we can still try
+        # and get the partial message:
+        bytes = buffer.get_array_of_int8(0, buffer.size)&.map { |byte| byte.zero? ? nil : byte }
+        bytes.compact.pack('C*').force_encoding('UTF-8') if bytes&.cs__is_a?(Array)
+      end
+
+      # The stack_message is still not integrated in the AgentLib.
+      # It always returns "". For now we are returning the message,
+      # but keeping the functionality for feature use.
+      #
+      # @param message_buffer [FFI::MemoryPointer, nil] of type char (String)
+      # @param stack_buffer [FFI::MemoryPointer, nil] of type char (String)
+      # @return [String] the received error message with stack.
+      def dl__parse_error message_buffer, stack_buffer
+        message = dl__read_buffer(message_buffer)
+        stack = dl__read_buffer(stack_buffer)
+
+        error_message = "Message: #{ message }"
+        error_message + " Stack Trace: #{ stack }" unless stack.empty?
+        error_message
+      end
+    end
+  end
+end

data/lib/contrast/agent_lib/api/path_semantic_file_security_bypass.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: false
+
+require 'ffi'
+require 'contrast-agent-lib'
+require 'contrast/utils/object_share'
+
+module Contrast
+  module AgentLib
+    # This module is defined in Rust as external, we used it here.
+    # Initializes the AgentLib. Here will be all methods from
+    # the C bindings contrast_c::path_semantic_file_security_bypass module.
+    module PathSemanticFileSecurityBypass
+      extend FFI::Library
+      ffi_lib ContrastAgentLib::CONTRAST_C
+
+      # Attach all the needed functions
+      # @param file_path[String] This is the full path of the file, being accessed
+      # @param is_custom_code[Integer] whether the file is being accessed by custom (user) code,
+      #     rather than framework code.
+      attach_function :does_file_path_bypass_security, %i[string int], :int
+
+      private
+
+      # do we need to get the full path before we invoke it or here I need to extract the full path?
+
+      # This is the function from the agent lib, that checks if
+      # a given file_path is attempting to access system files
+      # or bypass file security
+      # This is used for the `path-traversal-semantic-file-security-bypass` rule.
+      #
+      # @param file_path[String] This is the full path of the file, being accessed
+      # @param is_custom_code[Integer] whether the file is being accessed by custom (user) code,
+      #     rather than framework code.
+      def dl__does_file_bypass_security file_path, is_custom_code
+        does_file_path_bypass_security(file_path, is_custom_code)
+      end
+    end
+  end
+end

data/lib/contrast/agent_lib/interface.rb

@@ -0,0 +1,260 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/agent_lib/api/init'
+require 'contrast/agent_lib/api/command_injection'
+require 'contrast/agent_lib/api/input_tracing'
+require 'contrast/agent_lib/api/panic'
+require 'contrast/agent_lib/api/method_tempering'
+require 'contrast/agent_lib/api/path_semantic_file_security_bypass'
+require 'contrast/components/logger'
+require 'contrast/utils/object_share'
+require 'fileutils'
+require 'ffi'
+require 'contrast/agent_lib/return_types/eval_result'
+require 'contrast/agent_lib/interface_base'
+
+module Contrast
+  module AgentLib
+    # The interface to react with the AgentLib. This will be the one place of
+    # contact with the DynamicLib, synchronized and loaded with modules to use.
+    class Interface < InterfaceBase
+      # Include the modules to use from the FFI wrappers of the AgentLib.
+      include Contrast::AgentLib::Init
+      include Contrast::AgentLib::Panic
+      include Contrast::AgentLib::InputTracing
+      include Contrast::AgentLib::CommandInjection
+      # TODO: RUBY-1632
+      # include Contrast::AgentLib::MethodTempering
+      include Contrast::AgentLib::PathSemanticFileSecurityBypass
+      include Contrast::Components::Logger::InstanceMethods
+
+      # Attached methods are always public. We need to make them private
+      # so that this interface is the only mean to call native functions.
+      # The dl__ (dynamic lib) wrapper methods are used to transfer and
+      # convert data to required by the AgentLib types. If native method
+      # is called with wrong arguments a panic is raised. Public instance
+      # methods in this module are used to safe guard and set state by
+      # instance variables. Add any newly attached native functions
+      # included above here:
+      private :init, :init_with_options, :change_log_settings, :check_cmd_injection_query,
+              :free_check_query_sink_result, :get_index_of_chained_command, :last_error_message,
+              :does_command_contain_dangerous_path, :last_error_message_length, :last_error_stack_length,
+              :evaluate_header_input, :evaluate_input, :free_eval_result, :check_sql_injection_query,
+              :free_check_query_sink_result
+
+      # @return enable_log [Boolean] flag to enable or disable logging.
+      attr_reader :enable_log
+      # @return log_dir [String] path to existing log directory.
+      attr_reader :log_dir
+      # @return log_level [String] OFF, ERROR, WARN, INFO, DEBUG or TRACE.
+      attr_reader :log_level
+      # @return enable_log_change [Boolean] flag set during initialization.
+      # If true the log level and enable status could be change during
+      # runtime.
+      attr_reader :enable_log_change
+      # Initialization status
+      # @return [Boolean]
+      attr_reader :init_status
+      # We need to synchronize all calls to the AgentLib vie mutex or monitor.
+      #
+      # @return mutex [Mutex] to synchronize calls, also to prevent situations
+      # such as calling a re_init on not init lib:
+      # This is not the thread you are looking for.
+      attr_reader :mutex
+      # retrieves last error message.
+      # note: last_error_message is the name of the attached function and will
+      # override the agent_lib native method if renamed.
+      #
+      # @return last_error_message [String]
+      attr_reader :last_error
+
+      # Initializes the Agent lib.
+      #
+      # @param enable_logging [Boolean, nil] flag to enable or disable logging.
+      # @param set_log_level [Integer, nil]
+      # @param set_log_dir [String, nil] dir to write log files.
+      # @return [Boolean] true if success.
+      # @raise [StandardError] Any Errors raised in the init process are most
+      # likely to be a C segfaults and termination, probably redundant but safe.
+      def initialize enable_logging = nil, set_log_level = nil, set_log_dir = nil
+        super
+        @mutex = Mutex.new
+        @enable_log = !!enable_logging
+        self.log_level = set_log_level
+        @log_dir = create_log_dir(set_log_dir)
+        @init_status = if enable_log && log_dir && log_level
+                         # Preferred as we will be able to to set the log level at run time.
+                         @enable_log_change = true
+                         with_mutex { dl__init_with_options(enable_log, log_dir, log_level) }
+                       else
+                         # Initialize the lib without logging.
+                         # The log level could not be changed during runtime.
+                         @enable_log_change = false
+                         with_mutex { dl__init }
+                       end
+      rescue StandardError => e
+        logger.error('Could not start АgentLib', error: e, backtrace: e.backtrace)
+      end
+
+      # Changes the logs level in runtime.
+      #
+      # @param new_enable_log [Boolean] flag to enable or disable logging this sets the inner flag.
+      # @param new_log_level [Integer]
+      def change_log_options new_enable_log, new_log_level
+        return unless @enable_log_change
+
+        update_logging(new_log_level, new_enable_log)
+        with_mutex { dl__change_log_settings(enable_log, log_level) }
+      end
+
+      # Set the log_level of the Interface.
+      #
+      # @param level [Integer, nil] one of:
+      # [-1...4]
+      def log_level= level = nil
+        set_level = level.nil? ? 3 : level
+        update_log_level(set_level)
+      end
+
+      # Execute calls to Native methods with mutex.
+      # If Error is raised from the AgentLib it will
+      # be logged. If C error occurs there will be a
+      # segfault and termination.
+      #
+      # @raise [StandardError] Capture any unforeseen errors.
+      # @return [String, Boolean, Integer, nil] Wrapper method's
+      # return types, or nil if something terrible happens.
+      def with_mutex &block
+        return_value = mutex.synchronize(&block)
+      rescue StandardError => e
+        logger.error('AgentLib runtime error', error: e, backtrace: e.backtrace)
+        handle_error
+      ensure
+        # Since every method is called with_mutex this is
+        # the natural candidate for handling any errors
+        # from the AgentLib.
+        handle_error
+        # The return value is used to set some instance
+        # variable state depending on the original return
+        # of the wrapper methods.
+        return_value
+      end
+
+      # Method to extract last error if any and log it.
+      def handle_error
+        @last_error = mutex.synchronize { dl__get_error }
+        logger.error('AgentLib encountered exception: ', error: @last_error) unless @last_error.empty?
+      end
+
+      # Checks that a given shell command contained a chained command.
+      # This is used for the cmd-injection-semantic-chained-commands rule.
+      #
+      # @param cmd [String] command to check.
+      # @return index[Integer, nil] Returns the index of the command chaining if found.
+      # If the chaining index is >= 0, an injection is detected. Returns -1 when no
+      # command chaining is found.
+      def chained_cmdi_index cmd
+        return unless cmd
+
+        with_mutex { dl__index_of_chained_command(cmd) }
+      end
+
+      # Checks if a given shell command is trying to access a dangerous path.
+      # This is used for the cmd-injection-semantic-dangerous-paths rule.
+      #
+      # @param path [String] path to check.
+      # @return index[Boolean] Returns true if a dangerous path is found.
+      # Returns false if no dangerous paths are found.
+      def dangerous_path? path
+        return unless path
+
+        with_mutex { dl__dangerous_path?(path) }
+      end
+
+      # Evaluate a subset of executing shell command for token boundaries being crossed.
+      # This is used by the cmd-injection rule during sink time. If a previously
+      # worth-watching input is contained in the shell command it crosses token
+      # boundaries then an injection should be raised.
+      #
+      # @param input_index [Integer] index in the cmdText string where user input was found.
+      # @param input_length [Integer] length of the user input.
+      # @param input_cmd [String] full text of the command being executed.
+      # @return result [Hash, nil] output parameter which will contain the result of the evaluation.
+      def check_cmdi_query input_index, input_length, input_cmd
+        return unless input_index && input_length && input_cmd
+
+        with_mutex { dl__check_cmdi_query(input_index, input_length, input_cmd) }
+      end
+
+      # Evaluates a header for input tracing rules.
+      #
+      # @param header_name [String] key/name of the header to be evaluated.
+      # NOTE: the only header names used are "custom", "accept", and "user-agent".
+      # Header-name-used is part of the output because the accept and user-agent
+      # headers get special handling by agent-lib, so they are evaluated twice -
+      # once exactly like all other headers and once with the specific header that
+      # gets special handling.
+      # @param header_value [String] header value
+      # @param rule_set [Integer] One of Contrast::AgentLib::Interface::RULE_SET
+      # @param eval_options [Integer] 0 or 1 from Contrast::AgentLib::Interface::EVAL_OPTIONS
+      # @return [Contrast::AgentLib::EvalResult, nil]
+      def eval_header header_name, header_value, rule_set, eval_options
+        return unless header_name && header_value && rule_set && eval_options
+
+        result = with_mutex { dl__eval_header_input(header_name, header_value, rule_set, eval_options) }
+        return EvalResult.new(result) if result
+
+        nil
+      end
+
+      # Evaluates an input part for input tracing rules. This should be used for all input parts except headers.
+      #
+      # @param input [String] input value to be evaluated.
+      # @param input_type [Integer]  type of the input one of Contrast::AgentLib::Interface::INPUT_SET
+      # @param rule_set [Integer] One of Contrast::AgentLib::Interface::RULE_SET
+      # @param eval_options [Integer] 0 or 1 from Contrast::AgentLib::Interface::EVAL_OPTIONS
+      # @return [Contrast::AgentLib::EvalResult, nil]
+      def eval_input input, input_type, rule_set, eval_options
+        return unless input && input_type && rule_set && eval_options
+
+        result = with_mutex { dl__eval_input(input, input_type, rule_set, eval_options) }
+        return EvalResult.new(result) if result
+
+        nil
+      end
+
+      def check_sql_query input_index, input_length, db_type, sql_query
+        return unless input_index && input_length && db_type && sql_query
+
+        with_mutex { dl__check_sql_injection_query(input_index, input_length, db_type, sql_query) }
+      end
+
+      # Invoke Path Semantic File Security Bypass
+      #
+      # @param file_path[String] the absolute file path
+      # @param is_custom_code[Integer] is this is being called from customer (user) code
+      #     or the framework
+      # @return result[Integer, nil] returns:
+      #     1 => security bypass is detected.
+      #     0 => no security bypass is detected.
+      def check_path_semantic_security_bypass file_path, is_custom_code
+        return unless file_path || is_custom_code
+
+        with_mutex { dl__does_file_bypass_security(file_path, is_custom_code) }
+      end
+
+      # TODO: RUBY-1632 Test after integration and if method-tempering is covered
+      # # Check to see if method is being tempered or not.
+      # # Used with Protect method-tampering rule.
+      # #
+      # # @param method [String] method to check
+      # # @return [Boolean]
+      # def method_tempered? method
+      #   return false unless method
+      #
+      #   with_mutex { dl__method_tempered?(method) }
+      # end
+    end
+  end
+end

data/lib/contrast/agent_lib/interface_base.rb

@@ -0,0 +1,118 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+module Contrast
+  module AgentLib
+    # Base class to set basic rule sets and input list.
+    class InterfaceBase
+      # This could be changed to regular Hash.
+      # This format is used to supports this kind of log_level assignment:
+      # via Contrast::Api::Settings::LogLevel::WARN => 3
+      # ( note -1 is not supported in the protobuf LogLevel)
+      LOG_LEVEL = { -1 => 'OFF', 0 => 'TRACE', 1 => 'DEBUG', 2 => 'INFO', 3 => 'WARN', 4 => 'ERROR' }.cs__freeze
+      LOG_DIR = File.join(Dir.pwd).cs__freeze
+      # Named after Protect rule_id / Names
+      # Corresponding to Rust's ulong enum
+      RULE_SET = {
+          'unsafe-file-upload' => 1 << 0,
+          'path-traversal' => 1 << 1,
+          'reflected-xss' => 1 << 2,
+          'sql-injection' => 1 << 3,
+          'cmd-injection' => 1 << 4,
+          'nosql-injection' => 1 << 5,
+          'bot-blocker' => 1 << 6,
+          'ssjs-injection' => 1 << 7,
+          'method-tampering' => 1 << 8
+      }.cs__freeze
+      # Named same as Contrast::Agent::Reporting::InputTypes
+      INPUT_SET = {
+          COOKIE_NAME: 1,
+          COOKIE_VALUE: 2,
+          HEADER_NAME: 3,
+          HEADER_VALUE: 4,
+          JSON_NAME: 5,
+          JSON_VALUE: 6,
+          METHOD: 7,
+          PARAMETER_NAME: 8,
+          PARAMETER_VALUE: 9,
+          URI: 10,
+          URL_PARAMETER: 11,
+          MULTIPART_NAME: 12,
+          XML_VALUE: 13
+      }.cs__freeze
+      EVAL_OPTIONS = { NONE: 0, WORTHWATCHING: 1 }.cs__freeze
+
+      # Initializes the Agent lib.
+      #
+      # @param enable_logging [Boolean, nil] flag to enable or disable logging.
+      # @param set_log_level [Integer, nil]
+      # @param set_log_dir [String, nil] dir to write log files.
+      # @return [Boolean] true if success.
+      # @raise [StandardError] Any Errors raised in the init process are most
+      # likely to be a C segfaults and termination, probably redundant but safe.
+      def initialize enable_logging = nil, set_log_level = nil, set_log_dir = nil
+        # Override
+      end
+
+      # Return list of available rules
+      #
+      # @return [Hash]
+      def rule_set
+        RULE_SET
+      end
+
+      # Returns list of available input types.
+      #
+      # @return [Hash]
+      def input_set
+        INPUT_SET
+      end
+
+      # Return list of input evaluation options:
+      # WorthWatching or none
+      #
+      # @return [Hash]
+      def eval_option
+        EVAL_OPTIONS
+      end
+
+      private
+
+      # Updates the logging status:
+      # Enabled && Level
+      #
+      # @param level [Integer] one of:
+      # [-1...4]
+      # @param enabled [Boolean] logging status.
+      def update_logging level, enabled
+        update_log_level(level)
+        @enable_log = !!enabled
+      end
+
+      # Updates the log level for the AgentLib.
+      #
+      # @param level [Integer] one of:
+      # [-1...4]
+      def update_log_level level
+        value = LOG_LEVEL[level]
+        @log_level = value if value
+      end
+
+      # Creates the directory for AgentLib log files.
+      # If no path provided use default.
+      #
+      # @param log_dir [String, nil] path to log.
+      # @rescue [StandardError] any error concerning
+      # the directory creation.
+      def create_log_dir log_dir = nil
+        path = log_dir.nil? ? LOG_DIR : log_dir
+        FileUtils.mkdir_p(path)
+        path
+      rescue StandardError => e
+        logger.debug('Could not create log directory', error: e)
+        FileUtils.mkdir_p(LOG_DIR)
+        LOG_DIR
+      end
+    end
+  end
+end

data/lib/contrast/agent_lib/return_types/eval_result.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_lib/interface'
+
+module Contrast
+  module AgentLib
+    # This class will hold resulst received form AgentLib structs.
+    class EvalResult
+      # Name of the Protect rule analyzed.
+      # @return [String]
+      attr_accessor :rule_id
+      # Type of the input.
+      # @return [String]
+      attr_accessor :input_type
+      # Score of the input after AgentLib
+      # Analysis
+      #
+      # @return score [Float]
+      attr_accessor :score
+
+      # Init a new EvalResult, and translate results to usable for
+      # reporting values.
+      #
+      # @param hsh [Hash, nil] return from AgentLib populated struct.
+      def initialize hsh
+        return unless hsh&.cs__is_a?(Hash)
+
+        @rule_id = Contrast::AgentLib::Interface::RULE_SET.key(hsh[:rule_id])
+        @input_type = Contrast::AgentLib::Interface::INPUT_SET.key(hsh[:input_type])
+        @score = hsh[:score]
+      end
+
+      # Used in specs.
+      def to_controlled_hash
+        {
+            rule_id: rule_id,
+            input_type: input_type,
+            score: score
+        }
+      end
+    end
+  end
+end

data/lib/contrast/agent_lib/test.rb

@@ -0,0 +1,29 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: false
+
+require_relative 'api/init'
+
+module Contrast # :nodoc:
+  module Test # :nodoc:
+    extend Contrast::AgentLib::Init
+
+    LOG_DIR = File.join(File.dirname(__FILE__))
+
+    class << self
+      def test_init_with_options enable_log, log_level
+        dl__init_with_options(enable_log, LOG_DIR, log_level)
+      end
+    end
+  end
+end
+
+# for the other cases - I tried with loop and everything, but nothing worked
+# Contrast::Test.test_init_with_options(true, "WARN")
+# Contrast::Test.test_init_with_options(true, "ERROR")
+# Contrast::Test.test_init_with_options(true, "DEBUG")
+# Contrast::Test.test_init_with_options(true, "TRACE")
+response = Contrast::Test.test_init_with_options(true, 'INFO')
+puts response # rubocop:disable Rails/Output
+
+# we cannot check here for the file as it's being created after the execution of the file is done
+raise(StandardError, 'Not Working') if response == false

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

@@ -4,22 +4,37 @@
 module Contrast
   module Api
     module Communication
-      # Keeps track of the state of connections to SpeedRacer.
+      # Keeps track of the state of connections to TeamServer.
       class ConnectionStatus
         def initialize
           @last_success = nil
           @last_failure = nil
           @startup_messages_sent = false
+          @_startup_server_message_sent = false
         end
 
-        # Whether we have sent startup message to SpeedRacer. True after successfully sending startup messages to
-        # SpeedRacer and reset to false if we lose connection.
+        # Whether we have sent startup message to TeamServer. True after successfully sending startup messages to
+        # TeamServer and reset to false if we lose connection.
         #
         # @return [Boolean]
         def startup_messages_sent?
           @startup_messages_sent
         end
 
+        # Check to see if we have sent server message and received settings from TS.
+        #
+        # @return [Boolean]
+        def startup_server_message_sent?
+          @_startup_server_message_sent
+        end
+
+        # Set the server message status state
+        #
+        # @return [Boolean]
+        def server_response_success!
+          @_startup_server_message_sent = true
+        end
+
         # The last message sent was successful or not
         #
         # @return [Boolean]
@@ -27,13 +42,13 @@ module Contrast
           @last_success && (@last_failure.nil? || @last_success > @last_failure)
         end
 
-        # The current state of the SpeedRacer is active with a successful message sent
+        # The current state of the TeamServer is active with a successful message sent
         def success!
           @startup_messages_sent = true
           @last_success = Time.now.to_f
         end
 
-        # The SpeedRacer may be in some sort of error state
+        # The TeamServer may be in some sort of error state
         def failure!
           @startup_messages_sent = false
           @last_failure = Time.now.to_f