aikido-zen 1.0.0.pre.beta.1-arm64-darwin → 1.0.1.beta.3-arm64-darwin

data/lib/aikido/zen/sinks/resolv.rb

@@ -1,28 +1,28 @@
 # frozen_string_literal: true
 
-require_relative "../sink"
 require_relative "../scanners/stored_ssrf_scanner"
 require_relative "../scanners/ssrf_scanner"
 
 module Aikido::Zen
   module Sinks
     module Resolv
+      def self.load_sinks!
+        # In stdlib but not always required
+        require "resolv"
+
+        ::Resolv.prepend(ResolvExtensions)
+      end
+
       SINK = Sinks.add("resolv", scanners: [
-        Aikido::Zen::Scanners::StoredSSRFScanner,
-        Aikido::Zen::Scanners::SSRFScanner
+        Scanners::StoredSSRFScanner,
+        Scanners::SSRFScanner
       ])
 
-      module Extensions
-        def each_address(name, &block)
-          addresses = []
-
-          super do |address|
-            addresses << address
-            yield address
-          end
-        ensure
-          if (context = Aikido::Zen.current_context)
-            context["dns.lookups"] ||= Aikido::Zen::Scanners::SSRF::DNSLookups.new
+      module Helpers
+        def self.scan(name, addresses, operation)
+          context = Aikido::Zen.current_context
+          if context
+            context["dns.lookups"] ||= Scanners::SSRF::DNSLookups.new
             context["dns.lookups"].add(name, addresses)
           end
 
@@ -30,12 +30,33 @@ module Aikido::Zen
             hostname: name,
             addresses: addresses,
             request: context && context["ssrf.request"],
-            operation: "lookup"
+            operation: operation
           )
         end
       end
+
+      module ResolvExtensions
+        def each_address(*args, **kwargs, &blk)
+          # each_address is defined "manually" because no sink method pattern
+          # is applicable.
+
+          name, = args
+
+          addresses = []
+          super(*args, **kwargs) do |address| # rubocop:disable Style/SuperArguments
+            addresses << address
+            blk.call(address)
+          end
+        ensure
+          # Ensure partial results are scanned.
+
+          Sinks::DSL.safe do
+            Helpers.scan(name, addresses, "lookup")
+          end
+        end
+      end
     end
   end
 end
 
-::Resolv.prepend(Aikido::Zen::Sinks::Resolv::Extensions)
+Aikido::Zen::Sinks::Resolv.load_sinks!

data/lib/aikido/zen/sinks/socket.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "socket"
+require_relative "../scanners/stored_ssrf_scanner"
+require_relative "../scanners/ssrf_scanner"
 
 module Aikido::Zen
   module Sinks
@@ -8,13 +10,17 @@ module Aikido::Zen
     # there's no way to access the internal DNS resolution that happens in C
     # when using the socket primitives.
     module Socket
+      def self.load_sinks!
+        ::IPSocket.singleton_class.prepend(Socket::IPSocketExtensions)
+      end
+
       SINK = Sinks.add("socket", scanners: [
-        Aikido::Zen::Scanners::StoredSSRFScanner,
-        Aikido::Zen::Scanners::SSRFScanner
+        Scanners::StoredSSRFScanner,
+        Scanners::SSRFScanner
       ])
 
-      module IPSocketExtensions
-        def self.scan_socket(hostname, socket)
+      module Helpers
+        def self.scan(hostname, socket, operation)
           # We're patching IPSocket.open(..) method.
           # The IPSocket class hierarchy is:
           #             IPSocket
@@ -29,36 +35,46 @@ module Aikido::Zen
           return unless socket.instance_of?(TCPSocket)
 
           # ["AF_INET", 80, "10.0.0.1", "10.0.0.1"]
-          addr_family, *, remote_address = socket.peeraddr
+          address_family, _port, _hostname, numeric_address = socket.peeraddr(:numeric)
 
           # We only care about IPv4 (AF_INET) or IPv6 (AF_INET6) sockets
           # This might be overcautious, since this is _IP_Socket, so you
           # would expect it's only used for IP connections?
-          return unless addr_family.start_with?("AF_INET")
 
-          if (context = Aikido::Zen.current_context)
-            context["dns.lookups"] ||= Aikido::Zen::Scanners::SSRF::DNSLookups.new
-            context["dns.lookups"].add(hostname, remote_address)
+          # Code coverage is disabled here because the then clause is a no-op,
+          # so there is nothing to cover.
+          # :nocov:
+          return unless address_family.start_with?("AF_INET")
+          # :nocov:
+
+          context = Aikido::Zen.current_context
+          if context
+            context["dns.lookups"] ||= Scanners::SSRF::DNSLookups.new
+            context["dns.lookups"].add(hostname, numeric_address)
           end
 
           SINK.scan(
             hostname: hostname,
-            addresses: [remote_address],
+            addresses: [numeric_address],
             request: context && context["ssrf.request"],
-            operation: "open"
+            operation: operation
           )
         end
+      end
 
-        def open(name, *)
-          socket = super
-
-          IPSocketExtensions.scan_socket(name, socket)
+      module IPSocketExtensions
+        extend Sinks::DSL
 
-          socket
+        sink_after :open do |socket, remote_host|
+          # Code coverage is disabled here because the tests are contrived and
+          # intentionally do not call open.
+          # :nocov:
+          Helpers.scan(remote_host, socket, "open")
+          # :nocov:
         end
       end
     end
   end
 end
 
-::IPSocket.singleton_class.prepend(Aikido::Zen::Sinks::Socket::IPSocketExtensions)
+Aikido::Zen::Sinks::Socket.load_sinks!

data/lib/aikido/zen/sinks/sqlite3.rb

@@ -1,30 +1,49 @@
 # frozen_string_literal: true
 
-require_relative "../sink"
-
 module Aikido::Zen
   module Sinks
     module SQLite3
+      def self.load_sinks!
+        if Aikido::Zen.satisfy "sqlite3", ">= 1.0"
+          require "sqlite3"
+
+          ::SQLite3::Database.prepend(DatabaseExtensions)
+          ::SQLite3::Statement.prepend(StatementExtensions)
+        end
+      end
+
       SINK = Sinks.add("sqlite3", scanners: [Scanners::SQLInjectionScanner])
 
-      module DatabaseExt
-        def exec_batch(sql, *)
-          SINK.scan(query: sql, dialect: :sqlite, operation: "exec_batch")
+      module Helpers
+        def self.scan(query, operation)
+          SINK.scan(
+            query: query,
+            dialect: :sqlite,
+            operation: operation
+          )
+        end
+      end
+
+      module DatabaseExtensions
+        extend Sinks::DSL
+
+        private
 
-          super
+        # SQLite3::Database#exec_batch is an internal native private method.
+        sink_before :exec_batch do |sql|
+          Helpers.scan(sql, "exec_batch")
         end
       end
 
-      module StatementExt
-        def initialize(_, sql, *)
-          SINK.scan(query: sql, dialect: :sqlite, operation: "statement.execute")
+      module StatementExtensions
+        extend Sinks::DSL
 
-          super
+        sink_before :initialize do |_db, sql|
+          Helpers.scan(sql, "statement.execute")
         end
       end
     end
   end
 end
 
-::SQLite3::Database.prepend(Aikido::Zen::Sinks::SQLite3::DatabaseExt)
-::SQLite3::Statement.prepend(Aikido::Zen::Sinks::SQLite3::StatementExt)
+Aikido::Zen::Sinks::SQLite3.load_sinks!

data/lib/aikido/zen/sinks/trilogy.rb

@@ -1,21 +1,33 @@
 # frozen_string_literal: true
 
-require_relative "../sink"
-
 module Aikido::Zen
   module Sinks
     module Trilogy
+      def self.load_sinks!
+        if Aikido::Zen.satisfy "trilogy", ">= 2.0"
+          require "trilogy"
+
+          ::Trilogy.prepend(TrilogyExtensions)
+        end
+      end
+
       SINK = Sinks.add("trilogy", scanners: [Scanners::SQLInjectionScanner])
 
-      module Extensions
-        def query(query, *)
-          SINK.scan(query: query, dialect: :mysql, operation: "query")
+      module Helpers
+        def self.scan(query, operation)
+          SINK.scan(query: query, dialect: :mysql, operation: operation)
+        end
+      end
+
+      module TrilogyExtensions
+        extend Sinks::DSL
 
-          super
+        sink_before :query do |query|
+          Helpers.scan(query, "query")
         end
       end
     end
   end
 end
 
-::Trilogy.prepend(Aikido::Zen::Sinks::Trilogy::Extensions)
+Aikido::Zen::Sinks::Trilogy.load_sinks!

data/lib/aikido/zen/sinks.rb

@@ -1,30 +1,39 @@
 # frozen_string_literal: true
 
-require_relative "sink"
+# Code coverage is disabled in this file because it is environment-specific and
+# not intended to be tested directly.
+# :nocov:
 
-require_relative "sinks/socket"
+require_relative "sink"
+require_relative "sinks_dsl"
 
 require_relative "sinks/action_controller" if defined?(::ActionController)
-require_relative "sinks/file" if defined?(::File)
 
 # Sadly, in ruby versions lower than 3.0, it's not possible to patch the
 # Kernel module because how the `prepend` method is applied
 # (https://stackoverflow.com/questions/78110397/prepend-kernel-module-function-globally#comment137713906_78112924)
-if RUBY_VERSION >= "3.0"
-  require_relative "sinks/kernel" if defined?(::Kernel)
-end
-require_relative "sinks/resolv" if defined?(::Resolv)
-require_relative "sinks/net_http" if defined?(::Net::HTTP)
-require_relative "sinks/http" if defined?(::HTTP)
-require_relative "sinks/httpx" if defined?(::HTTPX)
-require_relative "sinks/httpclient" if defined?(::HTTPClient)
-require_relative "sinks/excon" if defined?(::Excon)
-require_relative "sinks/curb" if defined?(::Curl)
-require_relative "sinks/patron" if defined?(::Patron)
+require_relative "sinks/kernel" if RUBY_VERSION >= "3.0"
+
+require_relative "sinks/file"
+require_relative "sinks/socket"
+require_relative "sinks/resolv"
+require_relative "sinks/net_http"
+
+# http.rb aims to support and is tested against Ruby 3.0+:
+# https://github.com/httprb/http?tab=readme-ov-file#supported-ruby-versions
+require_relative "sinks/http" if RUBY_VERSION >= "3.0"
+
+require_relative "sinks/httpx"
+require_relative "sinks/httpclient"
+require_relative "sinks/excon"
+require_relative "sinks/curb"
+require_relative "sinks/patron"
 require_relative "sinks/typhoeus" if defined?(::Typhoeus)
-require_relative "sinks/async_http" if defined?(::Async::HTTP)
-require_relative "sinks/em_http" if defined?(::EventMachine::HttpRequest)
-require_relative "sinks/mysql2" if defined?(::Mysql2)
-require_relative "sinks/pg" if defined?(::PG)
-require_relative "sinks/sqlite3" if defined?(::SQLite3)
-require_relative "sinks/trilogy" if defined?(::Trilogy)
+require_relative "sinks/async_http"
+require_relative "sinks/em_http"
+require_relative "sinks/mysql2"
+require_relative "sinks/pg"
+require_relative "sinks/sqlite3"
+require_relative "sinks/trilogy"
+
+# :nocov:

data/lib/aikido/zen/sinks_dsl.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module Aikido::Zen
+  module Sinks
+    module DSL
+      extend self
+
+      # In the context of `Aikido::Zen::Sinks::DSL`, the terms safe and presafe
+      # are defined as follows:
+      #
+      # safe: the desired state for a sink, particularly with respect to rescue.
+      #
+      # A sink is considered safe when unintended errors in the sink are handled,
+      # and-so are prevented from disrupting the operation of the original method
+      # (by raising unintended errors).
+      #
+      # presafe: the default state of a sink, particularly with respect to rescue.
+      #
+      # A sink is in the presafe state before and while unintended errors in the
+      # sink are not handled.
+      #
+      # Sink methods (like all methods) are in the presafe state when defined and
+      # become safe when unexpected errors cannot cause harm. The `safe` method
+      # is used to establish a safe state for the duration of the block executed.
+      # It is sometimes useful to be able to reestablish the presafe safe while
+      # inside a `safe` block; the `presafe` method allows this.
+      #
+      # Methods that contain the term presafe in their name should be used with
+      # appropriate care and understanding.
+      #
+      # IMPORTANT: All sinks should be safe!
+      #
+      # While this DSL proves useful for defining safe sink methods that follow
+      # common patterns, there are exceptions. It is always possible to define
+      # sink methods without using this DSL, but this should only be done when
+      # absolutely necessary. The sink methods defined using this DSL are safe,
+      # unless explicitly declared presafe.
+      #
+      # IMPORTANT: No sinks should be presafe in production!
+      #
+      # We are all responsible for ensuring that the sinks we implement are safe
+      # for production use. This DSL is only here to assist, by taking care of
+      # delicate edge cases and reducing the space for errors.
+      #
+      # When writing sink methods manually, some principles should be considered,
+      # to ensure safety for production:
+      #
+      # 1. Sink methods should ensure that the original method is always called,
+      # passing all parameters (positional, keyword, and block) exactly as they
+      # were passed to the original method, and return the result returned by
+      # the original method exactly as it was returned by the original method.
+      # (Unless intervention is required.)
+      #
+      # 2. Sink methods should not predict the signature of the original method,
+      # and-so restrict it from varying. The original method implementation is
+      # the sole and ultimate reference for its own behavior. We are observers
+      # (unless intervention is required).
+      #
+      # 3. Unexpected errors that are encountered in sink methods should not be
+      # capable of interfering with or preventing the normal operation of the
+      # original method. This includes but is not limited to exceptions that
+      # that may be raised when the sink method is called. Safe sink methods
+      # should return control to their caller (unless intervention is required).
+      #
+      # These are the guidelines adhered to by the `Aikido::Zen::Sinks::DSL`.
+
+      # The error with an original error as its cause to re-raise in `safe`.
+      class PresafeError < StandardError
+      end
+
+      # Safely execute the given block
+      #
+      # All standard errors are suppressed except `Aikido::Zen::UnderAttackError`s.
+      # This ensures that unexpected errors do not interrupt the execution of the
+      # original method, while all detected attacks are raised.
+      #
+      # When an error is wrapped in `PresafeError` the original error is reraised.
+      #
+      # @yield the block to execute
+      def safe
+        yield
+      rescue Aikido::Zen::UnderAttackError
+        raise
+      rescue PresafeError => err
+        raise err.cause
+      rescue => err
+        Aikido::Zen.config.logger.debug("[safe] #{err.class}: #{err.message}")
+      end
+
+      # Presafely execute the given block
+      #
+      # Safely wrap standard errors in `PresafeError` so that the original error is
+      # reraised when rescued in `safe`.
+      #
+      # @yield the block to execute
+      def presafe
+        yield
+      rescue => err
+        raise PresafeError, cause: err
+      end
+
+      # Define a method `method_name` that presafely executes the given block before
+      # the original method.
+      #
+      # @param method_name [Symbol, String] the name of the method to define
+      # @yield the block to execute before the original method
+      # @yieldparam args [Array] the positional arguments passed to the original method
+      # @yieldparam kwargs [Hash] the keyword arguments passed to the original method
+      #
+      # @return [void]
+      def presafe_sink_before(method_name, &block)
+        define_method(method_name) do |*args, **kwargs, &blk|
+          instance_exec(*args, **kwargs, &block)
+          super(*args, **kwargs, &blk)
+        end
+      end
+
+      # Define a method `method_name` that safely executes the given block before
+      # the original method.
+      #
+      # @param method_name [Symbol, String] the name of the method to define
+      # @yield the block to execute before the original method
+      # @yieldparam args [Array] the positional arguments passed to the original method
+      # @yieldparam kwargs [Hash] the keyword arguments passed to the original method
+      #
+      # @return [void]
+      #
+      # @note the block is executed within `safe` to handle errors safely; the original method is executed outside of `safe` to preserve the original behavior
+      def sink_before(method_name, &block)
+        presafe_sink_before(method_name) do |*args, **kwargs|
+          DSL.safe do
+            instance_exec(*args, **kwargs, &block)
+          end
+        end
+      end
+
+      # Define a method `method_name` that presafely executes the given block after
+      # the original method.
+      #
+      # @param method_name [Symbol, String] the name of the method to define
+      # @yield the block to execute after the original method
+      # @yieldparam result [Object] the result returned by the original method
+      # @yieldparam args [Array] the positional arguments passed to the original method
+      # @yieldparam kwargs [Hash] the keyword arguments passed to the original method
+      #
+      # @return [void]
+      def presafe_sink_after(method_name, &block)
+        define_method(method_name) do |*args, **kwargs, &blk|
+          result = super(*args, **kwargs, &blk)
+          instance_exec(result, *args, **kwargs, &block)
+          result
+        end
+      end
+
+      # Define a method `method_name` that safely executes the given block after
+      # the original method.
+      #
+      # @param method_name [Symbol, String] the name of the method to define
+      # @yield the block to execute after the original method
+      # @yieldparam result [Object] the result returned by the original method
+      # @yieldparam args [Array] the positional arguments passed to the original method
+      # @yieldparam kwargs [Hash] the keyword arguments passed to the original method
+      #
+      # @return [void]
+      #
+      # @note the block is executed within `safe` to handle errors safely; the original method is executed outside of `safe` to preserve the original behavior
+      def sink_after(method_name, &block)
+        presafe_sink_after(method_name) do |result, *args, **kwargs|
+          DSL.safe do
+            instance_exec(result, *args, **kwargs, &block)
+          end
+        end
+      end
+
+      # Define a method `method_name` that presafely executes the given block around
+      # the original method.
+      #
+      # @param method_name [Symbol, String] the name of the method to define
+      # @yield the block to execute around the original method
+      # @yieldparam super_call [Proc] the proc that calls the original method
+      # @yieldparam args [Array] the positional arguments passed to the original method
+      # @yieldparam kwargs [Hash] the keyword arguments passed to the original method
+      #
+      # @return [void]
+      def presafe_sink_around(method_name, &block)
+        define_method(method_name) do |*args, **kwargs, &blk|
+          result = nil
+          super_call = proc do
+            result = super(*args, **kwargs, &blk)
+          end
+          instance_exec(super_call, *args, **kwargs, &block)
+          result
+        end
+      end
+
+      # Define a method `method_name` that safely executes the given block around
+      # the original method.
+      #
+      # @param method_name [Symbol, String] the name of the method to define
+      # @yield the block to execute around the original method
+      # @yieldparam super_call [Proc] the proc that calls the original method
+      # @yieldparam args [Array] the positional arguments passed to the original method
+      # @yieldparam kwargs [Hash] the keyword arguments passed to the original method
+      #
+      # @return [void]
+      #
+      # @note the block is executed within `safe` to handle errors safely; the original method is executed within `presafe` to preserve the original behavior
+      # @note if the block does not call `super_call`, the original method is called automatically after the block is executed
+      def sink_around(method_name, &block)
+        presafe_sink_around(method_name) do |presafe_super_call, *args, **kwargs|
+          super_called = false
+          super_call = proc do
+            super_called = true
+            DSL.presafe do
+              presafe_super_call.call
+            end
+          end
+          DSL.safe do
+            instance_exec(super_call, *args, **kwargs, &block)
+          end
+          presafe_super_call.call unless super_called
+        end
+      end
+    end
+  end
+end

data/lib/aikido/zen/version.rb

@@ -2,9 +2,9 @@
 
 module Aikido
   module Zen
-    VERSION = "1.0.0-beta.1"
+    VERSION = "1.0.1.beta.3"
 
     # The version of libzen_internals that we build against.
-    LIBZEN_VERSION = "0.1.37"
+    LIBZEN_VERSION = "0.1.39"
   end
 end

data/lib/aikido/zen.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# IMPORTANT: Any files that load sinks or start the Aikido Agent should
+# be required in `Aikido::Zen.protect!`.
+
 require_relative "zen/version"
 require_relative "zen/errors"
 require_relative "zen/actor"
@@ -20,10 +23,48 @@ require_relative "zen/outbound_connection_monitor"
 require_relative "zen/runtime_settings"
 require_relative "zen/rate_limiter"
 require_relative "zen/scanners"
-require_relative "zen/rails_engine" if defined?(::Rails)
 
 module Aikido
   module Zen
+    # Enable protection. Until this method is called no sinks are loaded
+    # and the Aikido Agent does not start.
+    #
+    # @return [void]
+    def self.protect!
+      if config.disabled?
+        config.logger.warn("Zen has been disabled and will not run.")
+        return
+      end
+
+      # IMPORTANT: Any files that load sinks or start the Aikido Agent
+      # should be required here only.
+
+      if Aikido::Zen.satisfy "rails", ">= 7.0"
+        require_relative "zen/rails_engine"
+      end
+
+      if Aikido::Zen::Sinks.registry.empty?
+        warn "Zen could not find any supported libraries or frameworks. Visit https://github.com/AikidoSec/firewall-ruby for more information."
+      end
+    end
+
+    # @!visibility private
+    # Returns whether the loaded gem specification satisfies the listed requirements.
+    #
+    # Returns false if the gem specification is not loaded.
+    #
+    # @param name [String] the gem name
+    # @param requirements [Array<String>] a variable number of gem requirement strings
+    #
+    # @return [Boolean] true if the gem specification is loaded and all gem requirements are satisfied
+    def self.satisfy(name, *requirements)
+      spec = Gem.loaded_specs[name]
+
+      return false if spec.nil?
+
+      Gem::Requirement.new(*requirements).satisfied_by?(spec.version)
+    end
+
     # @return [Aikido::Zen::Config] the agent configuration.
     def self.config
       @config ||= Config.new

data/placeholder/.gitignore

@@ -0,0 +1,4 @@
+LICENSE
+*.gemspec
+/lib/*.rb
+*.gem

data/placeholder/README.md

@@ -0,0 +1,11 @@
+# Security Placeholder
+
+This gem has been published by [Aikido Security](https://aikido.dev) to help prevent supply chain attacks and protect the integrity of the Ruby ecosystem.
+
+It is **not intended for direct use** and contains no functional code.
+
+If you are looking for the actual library, please use [`aikido-zen`](https://rubygems.org/gems/aikido-zen).
+
+---
+
+This package exists solely for security purposes. For more information, visit [aikido.dev](https://aikido.dev).