aikido-zen 1.7.2.beta.1-aarch64-linux → 1.8.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57c43e61f0b2a3e40d012d5737b7df660f3bd1bfc1097926b6ac13e4e53a9f01
-  data.tar.gz: 813f4f2e3d923e371620115c90a2147bd7401a851d2b48deab2601b5300db63d
+  metadata.gz: c4c9820f5bed416d8a88ff5620690ff8a2dea5f404f967e6b1650562c05cb2cc
+  data.tar.gz: b08ee75b98ecd70862a4352d2a57713877d9ffaec6ba6820470c915c99169a12
 SHA512:
-  metadata.gz: 4e5d9c802009572c20ee6327d1dac8fa22cdfad7a14c07d9c943fd91b2d0f5c8cdab2d112f26aeecfba61e9211251a352de75285484cb5530fd15449ba8c1715
-  data.tar.gz: 6d359a6862e30f592d0c5caaea8b9e0be0d59fe021eb764371398513d7dc13ddaf8a8999cbf2ffce755a55b8d03c34dc5f5aa67bf68367cd71f38fa9b15a0f52
+  metadata.gz: 35f2cba1d894bb9b2e5048b2fcbd32cde9691c2236befc958e44f77f4a46f7b539d0b336d54ace283086f1d1f85ad3c0609af9df20d662088f8feeb5db8ebe2b
+  data.tar.gz: 18d284076efbb1b74c60ffd7a2e9bcb59a201a27941171027a31a289794a3a35362c5ba85113e35d682b7831b996c5317b58a8ee184d6342429c4dbfa80ab609

data/docs/request-bypassing.md

@@ -0,0 +1,50 @@
+# Bypass Zen for a specific request
+
+Call `Aikido::Zen.request_bypassed!` from a Rack middleware to bypass Zen for this request. A bypassed request is fully excluded from Zen inspection and enforcement: Zen will not analyze the request, generate findings, or apply blocking rules for that traffic. Your application handles the request normally.
+
+> [!NOTE]
+> Zen's built-in [Bypassed IPs](https://help.aikido.dev/zen-firewall/zen-features/bypassed-ips) feature uses request bypassing internally, triggered by a matching IP/CIDR. `Aikido::Zen.request_bypassed!` lets you bypass requests using your custom logic.
+
+## What gets bypassed
+
+* **Attack protection** — SQL injection, path traversal, command injection, and SSRF attacks are not blocked or reported
+* **Rate limiting** — never triggered.
+* **IP blocking** — Known Threat Actors, Tor traffic blocking/monitoring, country blocking, and custom IP allow/block lists are not checked.
+* **Bot traffic blocking** — not checked.
+* **User blocking** — blocked users are not blocked.
+* **Statistics** — the request isn't counted, and doesn't count against your monitored request quota.
+* **Attack wave protection** — the request doesn't count towards wave detection.
+
+## Usage
+
+Insert your middleware directly after `Aikido::Zen::Middleware::ContextSetter`, so it runs after the request context is set up but before Zen's other middleware:
+
+```ruby
+# config/application.rb
+class RequestBypasser
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    if your_custom_logic?(env)
+      Aikido::Zen.request_bypassed! # Bypasses Zen for this request
+    end
+
+    @app.call(env)
+  end
+end
+
+module YourApp
+  class Application < Rails::Application
+    # ...
+
+    initializer "your_app.insert_request_bypasser", after: "aikido.add_middleware" do |app|
+      app.middleware.insert_after Aikido::Zen::Middleware::ContextSetter, RequestBypasser
+    end
+  end
+end
+```
+
+> [!WARNING]
+> A bypassed request gets zero protection from Zen — no attack detection, no rate limiting, no blocking, no tracking. Ensure that your custom logic only bypasses requests that you fully trust.

data/lib/aikido/zen/agent.rb

@@ -220,6 +220,8 @@ module Aikido::Zen
       updated_at = Time.at(event[:data]["configUpdatedAt"].to_i)
 
       if should_fetch_settings?(updated_at)
+        return if realtime_settings_updates_too_fast?
+
         if update_settings_from_runtime_config!(@api_client.fetch_runtime_config, reason: "after server-sent event")
           updated_settings!
 
@@ -239,6 +241,19 @@ module Aikido::Zen
       updated_at > last_updated_at
     end
 
+    def realtime_settings_updates_too_fast?
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+
+      last_updated_at = @realtime_settings_updates_last_updated_at
+      if last_updated_at && now - last_updated_at < @config.realtime_settings_updates_min_time_between_events
+        return true
+      end
+
+      @realtime_settings_updates_last_updated_at = now
+
+      false
+    end
+
     def heartbeats
       @heartbeats ||= Aikido::Zen::Agent::HeartbeatsManager.new(
         config: @config,

data/lib/aikido/zen/attack_wave/helpers.rb

@@ -13,6 +13,16 @@ module Aikido::Zen
         false
       end
 
+      # Builds the sample for a request that has been classified as suspicious.
+      #
+      # @param context [Aikido::Zen::Context]
+      # @return [Aikido::Zen::AttackWave::Sample]
+      def self.sample_for(context)
+        request = context.request
+
+        Sample.new(verb: request.request_method, path: original_fullpath(request))
+      end
+
       def self.suspicious_request?(context, status_code)
         request = context.request
 

data/lib/aikido/zen/attack_wave.rb

@@ -5,6 +5,11 @@ require_relative "attack_wave/helpers"
 
 module Aikido::Zen
   module AttackWave
+    # Tracks per-client-IP attack wave state.
+    #
+    # In multiprocess deployments, the main process has a single instance
+    # that may be accessed concurrently from each forked worker process's
+    # Aikido::Zen::RPC::Server connection thread.
     class Detector
       # @return [Aikido::Zen::CappedSet]
       attr_reader :samples
@@ -12,6 +17,8 @@ module Aikido::Zen
       def initialize(config: Aikido::Zen.config, clock: nil)
         @config = config
 
+        @mutex = Mutex.new
+
         @event_times = Cache.new(@config.attack_wave_max_cache_entries, ttl: @config.attack_wave_min_time_between_events, clock: clock)
 
         @request_counts = Cache.new(@config.attack_wave_max_cache_entries, 0, ttl: @config.attack_wave_min_time_between_requests, clock: clock)
@@ -21,29 +28,54 @@ module Aikido::Zen
         end
       end
 
-      def attack_wave?(context, status_code = nil)
-        client_ip = context.request.client_ip
-
-        return false unless client_ip
+      # @api private
+      # @note Visible for testing.
+      #
+      # Whether the client IP is within the cooldown period after triggering
+      # an attack wave.
+      #
+      # @param client_ip [String]
+      # @return [Boolean]
+      def flagged?(client_ip)
+        !!@event_times[client_ip]
+      end
 
-        return false if @event_times[client_ip]
+      # @api private
+      # @note Visible for testing.
+      #
+      # Flags the client IP as having triggered an attack wave for the
+      # cooldown period.
+      #
+      # @param client_ip [String]
+      # @return [void]
+      def flag!(client_ip)
+        @event_times[client_ip] = Time.now.utc
+      end
 
-        return false unless AttackWave::Helpers.web_scanner?(context, status_code)
+      # Records a suspicious sample and, if it crosses the threshold for
+      # triggering an attack wave, flags the client IP as having just
+      # triggered an attack wave.
+      #
+      # This method is synchronized to prevent concurrent calls for the
+      # same client IP from crossing the threshold in the same instant.
+      #
+      # @param client_ip [String]
+      # @param sample [Aikido::Zen::AttackWave::Sample]
+      # @return [Array<Aikido::Zen::AttackWave::Sample>, nil]
+      def record(client_ip, sample)
+        @mutex.synchronize do
+          return nil if flagged?(client_ip)
 
-        request_count = @request_counts[client_ip] += 1
+          request_count = @request_counts[client_ip] += 1
 
-        context.request.then do |request|
-          @samples[client_ip] <<= Sample.new(
-            verb: request.request_method,
-            path: AttackWave::Helpers.original_fullpath(request)
-          )
-        end
+          @samples[client_ip] <<= sample
 
-        return false if request_count < @config.attack_wave_threshold
+          return nil if request_count < @config.attack_wave_threshold
 
-        @event_times[client_ip] = Time.now.utc
+          flag!(client_ip)
 
-        true
+          @samples[client_ip].to_a
+        end
       end
     end
 
@@ -117,6 +149,10 @@ module Aikido::Zen
     end
 
     class Sample
+      def self.from_json(data)
+        new(verb: data["method"], path: data["url"])
+      end
+
       # @return [String]
       attr_reader :verb
 

data/lib/aikido/zen/cache.rb

@@ -5,7 +5,7 @@ module Aikido::Zen
     extend Forwardable
 
     # @api private
-    # Visible for testing.
+    # @note Visible for testing.
     def_delegators :@data,
       :size, :empty?
 
@@ -54,13 +54,13 @@ module Aikido::Zen
     end
 
     # @api private
-    # Visible for testing.
+    # @note Visible for testing.
     def to_a
       @data.map { |key, entry| [key, entry.value] }
     end
 
     # @api private
-    # Visible for testing.
+    # @note Visible for testing.
     def to_h
       to_a.to_h
     end

data/lib/aikido/zen/collector/event.rb

@@ -157,14 +157,16 @@ module Aikido::Zen
         def self.from_json(data)
           new(
             data["sink_name"],
+            data["sink_kind"],
             data["duration"],
             has_errors: data["has_errors"]
           )
         end
 
-        def initialize(sink_name, duration, has_errors:)
+        def initialize(sink_name, sink_kind, duration, has_errors:)
           super()
           @sink_name = sink_name
+          @sink_kind = sink_kind
           @duration = duration
           @has_errors = has_errors
         end
@@ -172,17 +174,18 @@ module Aikido::Zen
         def as_json
           super.update({
             "sink_name" => @sink_name,
+            "sink_kind" => @sink_kind,
             "duration" => @duration,
             "has_errors" => @has_errors
           })
         end
 
         def handle(collector)
-          collector.handle_track_scan(@sink_name, @duration, has_errors: @has_errors)
+          collector.handle_track_scan(@sink_name, @sink_kind, @duration, has_errors: @has_errors)
         end
 
         def inspect
-          "#<#{self.class.name} #{@sink_name} #{format "%0.6f", @duration} #{@has_errors}>"
+          "#<#{self.class.name} #{@sink_name} #{@sink_kind} #{format "%0.6f", @duration} #{@has_errors}>"
         end
       end
 
@@ -192,29 +195,32 @@ module Aikido::Zen
         def self.from_json(data)
           new(
             data["sink_name"],
+            data["sink_kind"],
             being_blocked: data["being_blocked"]
           )
         end
 
-        def initialize(sink_name, being_blocked:)
+        def initialize(sink_name, sink_kind, being_blocked:)
           super()
           @sink_name = sink_name
+          @sink_kind = sink_kind
           @being_blocked = being_blocked
         end
 
         def as_json
           super.update({
             "sink_name" => @sink_name,
+            "sink_kind" => @sink_kind,
             "being_blocked" => @being_blocked
           })
         end
 
         def handle(collector)
-          collector.handle_track_attack(@sink_name, being_blocked: @being_blocked)
+          collector.handle_track_attack(@sink_name, @sink_kind, being_blocked: @being_blocked)
         end
 
         def inspect
-          "#<#{self.class.name} #{@sink_name} #{@being_blocked}>"
+          "#<#{self.class.name} #{@sink_name} #{@sink_kind} #{@being_blocked}>"
         end
       end
 

data/lib/aikido/zen/collector/routes.rb

@@ -8,7 +8,7 @@ module Aikido::Zen
   # Keeps track of the visited routes.
   class Collector::Routes
     # @api private
-    # Visible for testing.
+    # @note Visible for testing.
     attr_reader :visits
 
     def initialize(config = Aikido::Zen.config)
@@ -35,7 +35,7 @@ module Aikido::Zen
     end
 
     # @api private
-    # Visible for testing.
+    # @note Visible for testing.
     def [](route)
       @visits[route]
     end

data/lib/aikido/zen/collector/sink_stats.rb

@@ -7,6 +7,9 @@ module Aikido::Zen
   #
   # Tracks data specific to a single Sink.
   class Collector::SinkStats
+    # @return [String] category of operation this sink represents.
+    attr_accessor :kind
+
     # @return [Integer] number of total calls to Sink#scan.
     attr_accessor :scans
 
@@ -62,6 +65,7 @@ module Aikido::Zen
 
     def as_json
       {
+        "kind" => @kind,
         "total" => @scans,
         "interceptorThrewError" => @errors,
         "withoutContext" => 0,

data/lib/aikido/zen/collector/stats.rb

@@ -94,21 +94,25 @@ module Aikido::Zen
     end
 
     # @param sink_name [String] the name of the sink
+    # @param sink_kind [String] the category of operation the sink represents
     # @param duration [Float] the length the scan in seconds
     # @param has_errors [Boolean] whether errors occurred during the scan
     # @return [void]
-    def add_scan(sink_name, duration, has_errors:)
+    def add_scan(sink_name, sink_kind, duration, has_errors:)
       stats = @sinks[sink_name]
+      stats.kind = sink_kind
       stats.scans += 1
       stats.errors += 1 if has_errors
       stats.add_timing(duration)
     end
 
     # @param sink_name [String] the name of the sink
+    # @param sink_kind [String] the category of operation the sink represents
     # @param being_blocked [Boolean] whether the Agent blocked the request
     # @return [void]
-    def add_attack(sink_name, being_blocked:)
+    def add_attack(sink_name, sink_kind, being_blocked:)
       stats = @sinks[sink_name]
+      stats.kind = sink_kind
       stats.attacks += 1
       stats.blocked_attacks += 1 if being_blocked
     end

data/lib/aikido/zen/collector.rb

@@ -146,12 +146,12 @@ module Aikido::Zen
     # @param scan [Aikido::Zen::Scan]
     # @return [void]
     def track_scan(scan)
-      add_event(Events::TrackScan.new(scan.sink.name, scan.duration, has_errors: scan.errors?))
+      add_event(Events::TrackScan.new(scan.sink.name, scan.sink.kind, scan.duration, has_errors: scan.errors?))
     end
 
-    def handle_track_scan(sink_name, duration, has_errors:)
+    def handle_track_scan(sink_name, sink_kind, duration, has_errors:)
       synchronize(@stats) do |stats|
-        stats.add_scan(sink_name, duration, has_errors: has_errors)
+        stats.add_scan(sink_name, sink_kind, duration, has_errors: has_errors)
       end
     end
 
@@ -160,12 +160,12 @@ module Aikido::Zen
     # @param attack [Aikido::Zen::Attack]
     # @return [void]
     def track_attack(attack)
-      add_event(Events::TrackAttack.new(attack.sink.name, being_blocked: attack.blocked?))
+      add_event(Events::TrackAttack.new(attack.sink.name, attack.sink.kind, being_blocked: attack.blocked?))
     end
 
-    def handle_track_attack(sink_name, being_blocked:)
+    def handle_track_attack(sink_name, sink_kind, being_blocked:)
       synchronize(@stats) do |stats|
-        stats.add_attack(sink_name, being_blocked: being_blocked)
+        stats.add_attack(sink_name, sink_kind, being_blocked: being_blocked)
       end
     end
 
@@ -210,7 +210,6 @@ module Aikido::Zen
     end
 
     # @api private
-    #
     # @note Visible for testing.
     def stats
       handle
@@ -218,7 +217,6 @@ module Aikido::Zen
     end
 
     # @api private
-    #
     # @note Visible for testing.
     def users
       handle
@@ -226,7 +224,6 @@ module Aikido::Zen
     end
 
     # @api private
-    #
     # @note Visible for testing.
     def hosts
       handle
@@ -234,7 +231,6 @@ module Aikido::Zen
     end
 
     # @api private
-    #
     # @note Visible for testing.
     def routes
       handle
@@ -242,7 +238,6 @@ module Aikido::Zen
     end
 
     # @api private
-    #
     # @note Visible for testing.
     def middleware_installed?
       @middleware_installed.true?

data/lib/aikido/zen/config.rb

@@ -42,7 +42,7 @@ module Aikido::Zen
     attr_reader :api_endpoint
 
     # @return [URI] The HTTP host for the Aikido Runtime API. Defaults to
-    #   +https://runtime.aikido.dev+.
+    #   +https://guard.aikido.dev+.
     attr_reader :realtime_endpoint
 
     # @return [Hash] HTTP timeouts for communicating with the API.
@@ -229,6 +229,11 @@ module Aikido::Zen
     attr_accessor :realtime_settings_updates_enabled
     alias_method :realtime_settings_updates_enabled?, :realtime_settings_updates_enabled
 
+    # @return [Integer] the minimum time in milliseconds between realtime
+    #   settings updates.
+    #   Defaults to 9 seconds in milliseconds.
+    attr_accessor :realtime_settings_updates_min_time_between_events
+
     def initialize
       self.insert_middleware_after = ::ActionDispatch::RemoteIp
       self.disabled = read_boolean_from_env(ENV.fetch("AIKIDO_DISABLE", false)) || read_boolean_from_env(ENV.fetch("AIKIDO_DISABLED", false))
@@ -236,7 +241,7 @@ module Aikido::Zen
       self.debugging = read_boolean_from_env(ENV.fetch("AIKIDO_DEBUG", false))
       self.api_token = ENV.fetch("AIKIDO_TOKEN", nil)
       self.api_endpoint = ENV.fetch("AIKIDO_ENDPOINT") { regional_api_endpoint(api_token) }
-      self.realtime_endpoint = ENV.fetch("AIKIDO_REALTIME_ENDPOINT", DEFAULT_RUNTIME_BASE_URL)
+      self.realtime_endpoint = api_endpoint
       self.api_timeouts = 10
       self.polling_interval = 60 # 1 min
       self.initial_heartbeat_delays = [30, 60 * 2] # 30 sec, 2 min
@@ -277,6 +282,7 @@ module Aikido::Zen
       self.idor_excluded_table_names = []
       self.idor_max_cache_entries = 1000
       self.realtime_settings_updates_enabled = false
+      self.realtime_settings_updates_min_time_between_events = 9 * 1000 # 9 sec (ms)
     end
 
     # Set the base URL for API requests.
@@ -377,9 +383,6 @@ module Aikido::Zen
       "AU" => "https://guard.au.aikido.dev"
     }.freeze
 
-    # @!visibility private
-    DEFAULT_RUNTIME_BASE_URL = "https://runtime.aikido.dev"
-
     # @!visibility private
     DEFAULT_JSON_ENCODER = JSON.method(:dump)
 

data/lib/aikido/zen/context.rb

@@ -24,6 +24,10 @@ module Aikido::Zen
     attr_accessor :scanning
     alias_method :scanning?, :scanning
 
+    # @return [Boolean, nil] whether the request is bypassed.
+    attr_accessor :request_bypassed
+    alias_method :request_bypassed?, :request_bypassed
+
     # @return [Boolean] whether attack protection for the currently requested
     #   endpoint was disabled on the Aikido dashboard, or if the source IP for
     #   this request is in the "Bypass List".
@@ -48,6 +52,7 @@ module Aikido::Zen
 
       @metadata = {}
       @scanning = false
+      @request_bypassed = nil
       @protection_disabled = false
       @idor_protection_enabled = false
     end

data/lib/aikido/zen/idor/protector.rb

@@ -7,7 +7,7 @@ module Aikido::Zen
 
     class Protector
       # @api private
-      # Visible for testing.
+      # @note Visible for testing.
       attr_accessor :cache
 
       def initialize(config: Aikido::Zen.config)

data/lib/aikido/zen/middleware/allowed_address_checker.rb

@@ -5,8 +5,9 @@ module Aikido::Zen
     # Middleware that only allows allowed IPs when allowed IPs are configured for
     # any matching route in the Aikido dashboard.
     class AllowedAddressChecker
-      def initialize(app, config: Aikido::Zen.config, settings: Aikido::Zen.runtime_settings)
+      def initialize(app, zen: Aikido::Zen, config: zen.config, settings: zen.runtime_settings)
         @app = app
+        @zen = zen
         @config = config
         @settings = settings
       end
@@ -22,7 +23,7 @@ module Aikido::Zen
       end
 
       private def allowed?(request)
-        return true if @settings.bypassed_ips.include?(request.client_ip)
+        return true if @zen.request_bypassed?
 
         matches = @settings.endpoints.matched_settings(request.route)
 

data/lib/aikido/zen/middleware/attack_protector.rb

@@ -19,7 +19,7 @@ module Aikido::Zen
       end
 
       private def protection_disabled?(request)
-        return true if @settings.bypassed_ips.include?(request.client_ip)
+        return true if @zen.request_bypassed?
 
         !@settings.endpoints.matched_settings(request.route).all?(&:protected?)
       end

data/lib/aikido/zen/middleware/attack_wave_protector.rb

@@ -4,10 +4,9 @@ module Aikido
   module Zen
     module Middleware
       class AttackWaveProtector
-        def initialize(app, zen: Aikido::Zen, settings: Aikido::Zen.runtime_settings)
+        def initialize(app, zen: Aikido::Zen)
           @app = app
           @zen = zen
-          @settings = settings
         end
 
         def call(env)
@@ -21,43 +20,46 @@ module Aikido
         end
 
         # @api private
-        # Visible for testing.
-        def attack_wave?(context, status_code = nil)
+        # @note Visible for testing.
+        #
+        # @param context [Aikido::Zen::Context]
+        # @param status_code [Integer, nil]
+        # @return [Array<Aikido::Zen::AttackWave::Sample>, nil]
+        def detect_attack_wave(context, status_code = nil)
           request = context.request
-          return false if request.nil?
+          return nil if request.nil?
 
-          return false if @settings.bypassed_ips.include?(request.client_ip)
+          return nil if @zen.request_bypassed?
 
-          @zen.attack_wave_detector.attack_wave?(context, status_code)
+          @zen.detect_attack_wave(context, status_code)
         end
 
         # @api private
-        # Visible for testing.
+        # @note Visible for testing.
         def protect(context, status_code = nil)
-          if attack_wave?(context, status_code)
-            client_ip = context.request.client_ip
+          samples = detect_attack_wave(context, status_code)
+          return unless samples
 
-            request = Aikido::Zen::AttackWave::Request.new(
-              ip_address: client_ip,
-              user_agent: context.request.user_agent,
-              source: context.request.framework
-            )
+          client_ip = context.request.client_ip
 
-            samples = @zen.attack_wave_detector.samples[client_ip].to_a
+          request = Aikido::Zen::AttackWave::Request.new(
+            ip_address: client_ip,
+            user_agent: context.request.user_agent,
+            source: context.request.framework
+          )
 
-            attack = Aikido::Zen::AttackWave::Attack.new(
-              samples: samples,
-              user: context.request.actor
-            )
+          attack = Aikido::Zen::AttackWave::Attack.new(
+            samples: samples,
+            user: context.request.actor
+          )
 
-            attack_wave = Aikido::Zen::Events::AttackWave.new(
-              request: request,
-              attack: attack
-            )
+          attack_wave = Aikido::Zen::Events::AttackWave.new(
+            request: request,
+            attack: attack
+          )
 
-            @zen.track_attack_wave(attack_wave)
-            @zen.agent.report(attack_wave)
-          end
+          @zen.track_attack_wave(attack_wave)
+          @zen.agent.report(attack_wave)
         end
       end
     end

data/lib/aikido/zen/middleware/ip_list_checker.rb

@@ -15,7 +15,7 @@ module Aikido::Zen
 
         client_ip = request.client_ip
 
-        return @app.call(env) if bypassed_ip?(client_ip)
+        return @app.call(env) if @zen.request_bypassed?
 
         if !@settings.allowed_ip?(client_ip)
           return @config.blocked_responder.call(request, :ip_allowed_list)
@@ -38,10 +38,6 @@ module Aikido::Zen
 
         @app.call(env)
       end
-
-      def bypassed_ip?(client_ip)
-        @settings.bypassed_ips.include?(client_ip)
-      end
     end
   end
 end

data/lib/aikido/zen/middleware/rack_throttler.rb

@@ -34,7 +34,7 @@ module Aikido::Zen
       private
 
       def should_throttle?(request)
-        return false if @settings.bypassed_ips.include?(request.client_ip)
+        return false if @zen.request_bypassed?
 
         return false if request.actor && @settings.user_excluded_from_rate_limiting?(request.actor.id)