threatstack-agent-ruby 0.2.1

data/lib/events/models/instrumentation_event.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative './base_event'
+
+module Threatstack
+  module Events
+
+    # Instrumentation event model that inherits the common attributes and adds its own specifics
+    class InstrumentationEvent < BaseEvent
+      attr_accessor :module_name
+      attr_accessor :method_name
+      attr_accessor :file_path
+      attr_accessor :line_num
+      attr_accessor :arguments
+
+      # @param [Hash]    args
+      #        [String]  args.module_name
+      #        [String]  args.method_name
+      #        [String]  args.file_path
+      #        [Integer] args.line_num
+      #        [Array]   args.arguments
+      def initialize(args)
+        args[:event_type] = 'instrumentation'
+        @module_name = args[:module_name]
+        @method_name = args[:method_name]
+        @file_path = args[:file_path]
+        @line_num = args[:line_num]
+        @arguments = args[:arguments]
+        super args
+      end
+
+      def to_hash
+        hash = to_core_hash
+        hash[:module_name] = @module_name
+        hash[:method_name] = @method_name
+        hash[:line_num] = @line_num
+        hash[:file_path] = @file_path
+        hash[:payload] = {
+          :arguments => @arguments
+        }
+        hash
+      end
+    end
+
+  end
+end

data/lib/exceptions/request_blocked_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Threatstack
+  module Exceptions
+
+    # Custom exception class used when a client request is blocked by the agent
+    class RequestBlockedError < StandardError
+    end
+
+  end
+end

data/lib/instrumentation/common.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require_relative '../../ext/libinjection/libinjection'
+require_relative '../events/models/instrumentation_event'
+require_relative '../events/models/attack_event'
+require_relative '../jobs/event_submitter'
+require_relative '../utils/logger'
+require_relative '../constants'
+
+module Threatstack
+  module Instrumentation
+    include Threatstack::Constants
+
+    @@logger = Threatstack::Utils::TSLogger.create 'CommonInstrumentation'
+    @@submitter = Threatstack::Jobs::EventSubmitter.instance
+
+    def self.create_instrumentation_event(module_name, method_name, file_path, line_num, arguments)
+      data = {
+        :module_name => module_name,
+        :method_name => method_name,
+        :file_path => file_path,
+        :line_num => line_num,
+        :arguments => drop_sensitive_fields(arguments)
+      }
+      @@logger.debug "Creating instrumentation event with data: #{data}"
+      # create and submit the attack event
+      @@submitter.queue_event Threatstack::Events::InstrumentationEvent.new(drop_sensitive_fields(data))
+    end
+
+    def self.create_attack_event(payload, type, location, request, headers, backtrace)
+      is_blocked = (type == SQLI && BLOCK_SQLI) || (type == XSS && BLOCK_XSS)
+      data = {
+        :timestamp => Time.now.utc.strftime('%FT%T.%3NZ'),
+        :module_name => AGENT_NAME,
+        :request_ip => request.remote_ip,
+        :request_headers => headers,
+        :request_url => request.path,
+        :request_method => request.request_method,
+        :attack_message => is_blocked ? REQUEST_BLOCKED : DETECTED_NOT_BLOCKED,
+        :attack_stack => backtrace,
+        :attack_details => {
+          # TODO: get signature from libinjection
+          :details => [{ :signature => nil, :value => drop_sensitive_fields(payload) }],
+          :in => location,
+          :type => type,
+          :isBlocked => is_blocked,
+          :action => 'process_action'
+        }
+      }
+      @@logger.debug "Creating attack event with data: #{data}"
+      # create and submit the attack event
+      @@submitter.queue_event Threatstack::Events::AttackEvent.new(drop_sensitive_fields(data))
+    end
+
+    def self.const_exist?(name)
+      resolve_const(name) && true
+    rescue NameError, ArgumentError
+      false
+    end
+
+    def self.resolve_const(name)
+      raise ArgumentError if name.nil? || name.empty?
+
+      name.to_s.split('::').inject(Object) { |a, e| a.const_get(e) }
+    end
+
+    def self.flatten(obj)
+      if obj.is_a?(Hash)
+        obj.each_with_object({}) do |(k, v), h|
+          if v.is_a?(Hash) || v.is_a?(Array)
+            flatten(v).map do |h_k, h_v|
+              h["#{k}.#{h_k}".to_sym] = h_v
+            end
+          else
+            h[k] = v
+          end
+        end
+      elsif obj.is_a?(Array)
+        h = {}
+        obj.each_with_index do |v, index|
+          if v.is_a?(Hash) || v.is_a?(Array)
+            flatten(v).map do |h_k, h_v|
+              h["#{index}.#{h_k}".to_sym] = h_v
+            end
+          else
+            h[index.to_s] = v
+          end
+        end
+        h
+      else
+        obj
+      end
+    end
+
+    def self.drop_sensitive_fields(obj)
+      return obj if DROP_FIELDS.nil?
+
+      if obj.is_a?(Hash)
+        obj.each_with_object({}) do |(k, v), h|
+          if DROP_FIELDS[k] || DROP_FIELDS[k.to_s]
+            h[k] = REDACTED
+            next
+          end
+
+          if v.is_a?(Hash) || v.is_a?(Array)
+            h[k] = drop_sensitive_fields(v)
+          else
+            h[k] = v
+          end
+        end
+      elsif obj.is_a?(Array)
+        obj.each_with_object([]) do |v, arr|
+          if v.is_a?(Hash) || v.is_a?(Array)
+            arr.push drop_sensitive_fields(v)
+          else
+            arr.push v
+          end
+        end
+      else
+        obj
+      end
+    end
+
+    def self.check_sqli_payload(param, name = nil)
+      if param.nil? || !param.kind_of?(String)
+        @@logger.debug "SQLI Check skipped for: #{name}" unless name.nil?
+        return false
+      end
+      match = (Libinjection.libinjection_sqli(param, param.length, '') === 1 ? true : false)
+      @@logger.send(match ? :warn : :debug, "SQLI Check #{match ? 'positive' : 'negative'} for: #{name}") unless name.nil?
+      match
+    end
+
+    def self.check_xss_payload(param, name = nil)
+      if param.nil? || !param.kind_of?(String)
+        @@logger.debug "XSS Check skipped for: #{name}" unless name.nil?
+        return false
+      end
+
+      match = (Libinjection.libinjection_xss(param, param.length) === 1 ? true : false)
+      @@logger.send(match ? :warn : :debug, "XSS Check #{match ? 'positive' : 'negative'} for: #{name}") unless name.nil?
+      match
+    end
+
+    def self.check_parameters(params, location, request, headers, backtrace, include_payload = true)
+      if params.nil? || !params.is_a?(Hash)
+        @@logger.debug "Skipping param check for: #{params}"
+        return nil
+      end
+
+      # flatten hash for easier checking
+      flattened = flatten params
+
+      # check each parameter value for dangerous payloads
+      sqli_found, xss_found = false, false
+      flattened.each do |key, val|
+        sqli_found = check_sqli_payload(val, key) unless sqli_found
+        xss_found = check_xss_payload(val, key) unless xss_found
+      end
+
+      # whether or not to include the payload in the event
+      payload = include_payload ? params : nil
+
+      # create the according attack event if the checks above returned positive
+      create_attack_event(payload, SQLI, location, request, headers, backtrace) if sqli_found
+      create_attack_event(payload, XSS, location, request, headers, backtrace) if xss_found
+
+      # return results
+      { :sqli => sqli_found, :xss => xss_found }
+    end
+  end
+end

data/lib/instrumentation/instrumenter.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require_relative '../utils/logger'
+require_relative '../jobs/job_queue'
+
+module Threatstack
+  module Instrumentation
+    class Instrumenter
+      include Singleton
+
+      @@logger = Threatstack::Utils::TSLogger.create 'Instrumenter'
+
+      if RUBY_VERSION < '1.9'
+        def normalize_method_name(method)
+          method.to_s
+        end
+      else
+        def normalize_method_name(method)
+          method
+        end
+      end
+
+      def self.define_callback(klass, method, &block)
+        backup_name = get_backup_name method
+        outer_block = block
+        Proc.new do |*args, &block|
+          @@logger.debug "Wrapped method called: #{klass}.#{method}"
+          caller_loc = caller_locations(1, 10)
+          if outer_block
+            # exec callback
+            outer_block.call(:caller_loc => caller_loc, :args => args, :method_name => method, :target_class => klass)
+          end
+          __send__(backup_name, *args, &block)
+        end
+      end
+
+      def wrap_method(klass, method, &block)
+        if is_class_method?(klass, method)
+          wrap_class_method(klass, method, &block)
+        elsif is_instance_method?(klass, method)
+          @@logger.debug "Wrapping instance method: #{klass}.#{method}"
+          wrap_instance_method(klass, method, &block)
+        else
+          raise "#{klass}.#{method} is not a class nor instance method"
+        end
+      end
+
+      def wrap_class_method(klass, method, &block)
+        @@logger.debug "Wrapping class method: #{klass}.#{method}"
+        original_name = method.to_sym
+        backup_name = get_backup_name method
+        wrapped_name = get_wrapped_name method
+
+        klass.singleton_class.instance_eval do
+          alias_method backup_name, original_name
+
+          p = Instrumenter.define_callback(klass, method, &block)
+          define_method(wrapped_name, p)
+
+          private wrapped_name
+
+          method_kind = nil
+          if public_method_defined? original_name
+            method_kind = :public
+          elsif protected_method_defined? original_name
+            method_kind = :protected
+          elsif private_method_defined? original_name
+            method_kind = :private
+          end
+
+          alias_method original_name, wrapped_name
+          __send__(method_kind, original_name)
+          private backup_name
+        end
+      end
+
+      def wrap_instance_method(klass, method, &block)
+        @@logger.debug "Wrapping instance method: #{klass}.#{method}"
+        backup_name = get_backup_name method
+        wrapped_name = get_wrapped_name method
+
+        private_methods = klass.private_instance_methods(false)
+        if private_methods.include?(backup_name)
+          @@logger.debug "#{klass}.#{method} already instrumented"
+          return backup_name
+        end
+
+        p = Instrumenter.define_callback(klass, method, &block)
+        visibility = nil
+        klass.class_eval do
+          alias_method backup_name, method
+
+          define_method(wrapped_name, p)
+
+          if public_method_defined?(method)
+            visibility = :public
+          elsif protected_method_defined?(method)
+            visibility = :protected
+          elsif private_method_defined?(method)
+            visibility = :private
+          end
+
+          alias_method method, wrapped_name
+          private backup_name
+          private wrapped_name
+          __send__(visibility, method)
+        end
+        backup_name
+      end
+
+      def self.get_backup_name(method, suffix = nil)
+        "ts_#{method}_backup#{suffix ? "_#{suffix}" : ''}".to_sym
+      end
+
+      def self.get_wrapped_name(method, suffix = nil)
+        "ts_#{method}_wrapped#{suffix ? "_#{suffix}" : ''}".to_sym
+      end
+
+      def get_backup_name(method, suffix = nil)
+        Instrumenter.get_backup_name(method, suffix)
+      end
+
+      def get_wrapped_name(method, suffix = nil)
+        Instrumenter.get_wrapped_name(method, suffix)
+      end
+
+      def is_instance_method?(klass, method)
+        method = normalize_method_name(method)
+        klass.instance_methods.include?(method) || klass.private_instance_methods.include?(method)
+      end
+
+      def is_class_method?(klass, method)
+        method = normalize_method_name(method)
+        klass.singleton_methods.include? method
+      end
+
+      def method_exists?(obj, method)
+        return true if is_class_method?(obj, method)
+        return false unless obj.respond_to?(:instance_methods)
+        is_instance_method?(obj, method)
+      end
+    end
+  end
+end

data/lib/instrumentation/kernel.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative './common.rb'
+require_relative './instrumenter.rb'
+require_relative '../utils/logger'
+
+module Threatstack
+  module Instrumentation
+    module TSKernel
+      @@logger = Threatstack::Utils::TSLogger.create 'KernelInstrumentation'
+
+      # methods to wrap
+      METHOD_NAMES = ['exec', 'system', '`'].freeze
+
+      def self.wrap_methods
+        # executed every time a wrapped method is called
+        on_method_call = Proc.new do |params|
+          module_name = params[:target_class].name.downcase
+          method_name = params[:method_name].downcase
+          called_by = params[:caller_loc] ? params[:caller_loc].first : nil
+          file_path = called_by ? called_by.absolute_path : nil
+          # special case for ` method emulation
+          if method_name == '`' && !file_path.nil? && file_path =~ /.*\/kernel\/agnostics\.rb$/
+            called_by = params[:caller_loc][1]
+            file_path = called_by ? called_by.absolute_path : nil
+          end
+          line_num = called_by ? called_by.lineno : nil
+
+          arg = params[:args] ? params[:args].first : nil
+          args = arg ? [arg] : []
+
+          # create and queue the event
+          Threatstack::Instrumentation.create_instrumentation_event(module_name, method_name, file_path, line_num, args)
+        end
+        @@logger.info "Instrumenting Kernel methods: #{METHOD_NAMES}"
+        instrumenter =  Threatstack::Instrumentation::Instrumenter.instance
+        METHOD_NAMES.each do |method_name|
+          instrumenter.wrap_class_method(Kernel, method_name, &on_method_call)
+          instrumenter.wrap_instance_method(Kernel, method_name, &on_method_call)
+        end
+      end
+
+    end
+  end
+end

data/lib/instrumentation/rails.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'json'
+
+require_relative '../constants'
+require_relative '../exceptions/request_blocked_error'
+require_relative './common'
+require_relative '../utils/logger'
+
+module Threatstack
+  module Instrumentation
+    module TSRails
+      @@logger = Threatstack::Utils::TSLogger.create 'RailsInstrumentation'
+
+      def self.patch_action_controller
+        @@logger.info 'Looking for Rails gem'
+        return unless defined?(::Rails) && defined?(::Rails::VERSION)
+        return unless defined?(ActionController) && defined?(ActionController::Base)
+
+        @@logger.info "Rails #{Rails::VERSION::MAJOR.to_s} gem found, instrumenting ActionController"
+        ActionController::Base.class_eval do
+          include Threatstack::Instrumentation::TSRails::TSActionController
+        end
+        @@logger.info 'Rails instrumentation done'
+      end
+
+      module TSActionController
+        include Threatstack::Constants
+        @@logger = Threatstack::Utils::TSLogger.create 'RailsInstrumentation'
+
+        def process_action(*args)
+          # we need the headers hack below because Rails adds a lot of internal headers
+          headers = request.headers.each_with_object({}) do |(k, v), obj|
+            obj[k] = v if k.in?(CGI_VARIABLES) || k =~ /^HTTP_/
+          end
+          @@logger.debug("Incoming request: #{{ :headers => headers, :path => request.path_parameters,
+                                                :query => Threatstack::Instrumentation.drop_sensitive_fields(request.query_parameters),
+                                                :body => Threatstack::Instrumentation.drop_sensitive_fields(request.request_parameters) }}")
+          backtrace = caller.join("\n")
+
+          # check path/query/body parameters
+          path_res = Threatstack::Instrumentation.check_parameters(request.path_parameters, 'path', request, headers, backtrace)
+          query_res = Threatstack::Instrumentation.check_parameters(request.query_parameters, 'query', request, headers, backtrace)
+          body_res = Threatstack::Instrumentation.check_parameters(request.request_parameters, 'body', request, headers, backtrace)
+
+          @@logger.debug "RequestStats -- Path: #{path_res}, Query: #{query_res}, Body: #{body_res}"
+          sqli_found = (path_res[:sqli] || query_res[:sqli] || body_res[:sqli])
+          xss_found = (path_res[:xss] || query_res[:xss] || body_res[:xss])
+          # raise an exception if any attack payloads were detected and blocking is enabled
+          if (BLOCK_SQLI && sqli_found) || (BLOCK_XSS && xss_found)
+            raise Threatstack::Exceptions::RequestBlockedError, REQUEST_BLOCKED
+          end
+
+          # continue processing the request normally if no issues were found
+          super
+        end
+
+      end
+    end
+  end
+end