aikido-zen 1.7.2.beta.1 → 1.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9df9011f3e8f6d0df4ea0b12df6ed7202c0b91eda333f4318a6217b379702fc9
-  data.tar.gz: d13cd7f6f6cf72aa8dd0d76ff5bfc44dbb5620701ea3179f10f543587703695c
+  metadata.gz: 41f1982e134a806c513cc166247059c3f290f6bbc88ff32dcf4bdc65da9f377d
+  data.tar.gz: d97dac2f830555239836a143b815ca3c85c4993776183ce73bc5dc392fed9618
 SHA512:
-  metadata.gz: 5853f8f8cb5f74f439d155165ec137a965778741707537bce4dbc035f2f76529ed92910569b89137599f61b9e706f5fcacd95391e0157100f93326417e913df5
-  data.tar.gz: 1c742e2f46dde686ae8f70c65d7cfb0dd8fb552d10b9bff5b9b22934e25be3d8cc2c3a92cf7487e2d3c5884ca1803f585a4e7029f90564cb353563bc5960c220
+  metadata.gz: 526140c45a47c29f4f36e1508bc3305bafe535e92479c877deeb92a1f74c618fa19d7c46a7d67183310fbc414f05912b93c88f2cdb109730d04c0b4b6a54b301
+  data.tar.gz: 6c43bc7461a52ded8331b6ba2188afd9d273e1b012f5912b2d9786c439e2890380003779925bd3f37fdd4422f4b34aefe13af6d29d0a6a7f3b4e351c5019dca1

data/docs/request-bypassing.md

@@ -0,0 +1,38 @@
+# Bypass Zen for a specific request
+
+To disable Zen for a specific request, call `Aikido::Zen.request_bypassed!` from a Rack middleware. This bypasses Zen's security checks and stats collection for that request.
+
+> [!NOTE]
+> Zen already has a built-in feature for bypassing specific IP addresses. This feature offers more flexibility, letting you bypass Zen for a request based on any criteria you choose.
+
+`Aikido::Zen.request_bypassed!` needs the request's context to already be set up, so your middleware must run after Zen's `ContextSetter` middleware. The following example shows how to bypass a specific request in a Rails application:
+
+```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]
+> Use this feature with caution, as it can potentially expose your application to security risks if not used properly.

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/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.rb

@@ -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/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)
 

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

@@ -5,8 +5,9 @@ module Aikido::Zen
     # Rack middleware used to track request
     # It implements the logic under that which is considered worthy of being tracked.
     class RequestTracker
-      def initialize(app, settings: Aikido::Zen.runtime_settings)
+      def initialize(app, zen: Aikido::Zen, settings: zen.runtime_settings)
         @app = app
+        @zen = zen
         @settings = settings
       end
 
@@ -17,13 +18,12 @@ module Aikido::Zen
         if request.route && track?(
           status_code: response[0],
           route: request.route.path,
-          http_method: request.request_method,
-          ip: request.client_ip
+          http_method: request.request_method
         )
-          Aikido::Zen.track_request(request)
+          @zen.track_request(request)
 
-          if Aikido::Zen.config.collect_api_schema?
-            Aikido::Zen.track_discovered_route(request)
+          if @zen.config.collect_api_schema?
+            @zen.track_discovered_route(request)
           end
         end
 
@@ -128,8 +128,8 @@ module Aikido::Zen
       # @param status_code [Integer]
       # @param route [String]
       # @param http_method [String]
-      def track?(status_code:, route:, http_method:, ip: nil)
-        return false if @settings.bypassed_ips.include?(ip)
+      def track?(status_code:, route:, http_method:)
+        return false if @zen.request_bypassed?
 
         # In the UI we want to show only successful (2xx) or redirect (3xx) responses
         # anything else is discarded.

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

@@ -13,7 +13,7 @@ module Aikido::Zen
       def call(env)
         request = Aikido::Zen::Middleware.request_from(env)
 
-        return @app.call(env) if bypassed?(request)
+        return @app.call(env) if @zen.request_bypassed?
 
         user_agent = request.user_agent
 
@@ -31,10 +31,6 @@ module Aikido::Zen
 
         @app.call(env)
       end
-
-      def bypassed?(request)
-        @settings.bypassed_ips.include?(request.client_ip)
-      end
     end
   end
 end

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

@@ -30,7 +30,7 @@ module Aikido::Zen
 
           request = context.request
 
-          return false if @settings.bypassed_ips.include?(request.client_ip)
+          return false if @zen.request_bypassed?
 
           if should_block_user?(request)
             status, headers, body = @config.blocked_responder.call(request, :user)

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

@@ -52,9 +52,7 @@ module Aikido::Zen
 
                 settings = Aikido::Zen.runtime_settings
 
-                client_ip = context&.request&.client_ip
-
-                unless settings.bypassed_ip?(client_ip)
+                unless Aikido::Zen.request_bypassed?
                   Aikido::Zen.track_outbound(connection)
 
                   if settings.block_outbound?(connection)

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

@@ -64,9 +64,7 @@ module Aikido::Zen
 
               settings = Aikido::Zen.runtime_settings
 
-              client_ip = context&.request&.client_ip
-
-              unless settings.bypassed_ip?(client_ip)
+              unless Aikido::Zen.request_bypassed?
                 Aikido::Zen.track_outbound(connection)
 
                 if settings.block_outbound?(connection)

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

@@ -50,9 +50,7 @@ module Aikido::Zen
 
                 settings = Aikido::Zen.runtime_settings
 
-                client_ip = context&.request&.client_ip
-
-                unless settings.bypassed_ip?(client_ip)
+                unless Aikido::Zen.request_bypassed?
                   Aikido::Zen.track_outbound(connection)
 
                   if settings.block_outbound?(connection)

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

@@ -56,9 +56,7 @@ module Aikido::Zen
 
               settings = Aikido::Zen.runtime_settings
 
-              client_ip = context&.request&.client_ip
-
-              unless settings.bypassed_ip?(client_ip)
+              unless Aikido::Zen.request_bypassed?
                 Aikido::Zen.track_outbound(connection)
 
                 if settings.block_outbound?(connection)

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

@@ -70,9 +70,7 @@ module Aikido::Zen
 
               settings = Aikido::Zen.runtime_settings
 
-              client_ip = context&.request&.client_ip
-
-              unless settings.bypassed_ip?(client_ip)
+              unless Aikido::Zen.request_bypassed?
                 Aikido::Zen.track_outbound(connection)
 
                 if settings.block_outbound?(connection)

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

@@ -50,9 +50,7 @@ module Aikido::Zen
 
           settings = Aikido::Zen.runtime_settings
 
-          client_ip = context&.request&.client_ip
-
-          unless settings.bypassed_ip?(client_ip)
+          unless Aikido::Zen.request_bypassed?
             Aikido::Zen.track_outbound(connection)
 
             if settings.block_outbound?(connection)

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

@@ -55,9 +55,7 @@ module Aikido::Zen
 
               settings = Aikido::Zen.runtime_settings
 
-              client_ip = context&.request&.client_ip
-
-              unless settings.bypassed_ip?(client_ip)
+              unless Aikido::Zen.request_bypassed?
                 Aikido::Zen.track_outbound(connection)
 
                 if settings.block_outbound?(connection)

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

@@ -86,9 +86,7 @@ module Aikido::Zen
 
               settings = Aikido::Zen.runtime_settings
 
-              client_ip = context&.request&.client_ip
-
-              unless settings.bypassed_ip?(client_ip)
+              unless Aikido::Zen.request_bypassed?
                 Aikido::Zen.track_outbound(connection)
 
                 if settings.block_outbound?(connection)

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

@@ -59,9 +59,7 @@ module Aikido::Zen
 
               settings = Aikido::Zen.runtime_settings
 
-              client_ip = context&.request&.client_ip
-
-              unless settings.bypassed_ip?(client_ip)
+              unless Aikido::Zen.request_bypassed?
                 Aikido::Zen.track_outbound(connection)
 
                 if settings.block_outbound?(connection)

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

@@ -26,9 +26,7 @@ module Aikido::Zen
 
         settings = Aikido::Zen.runtime_settings
 
-        client_ip = context&.request&.client_ip
-
-        unless settings.bypassed_ip?(client_ip)
+        unless Aikido::Zen.request_bypassed?
           Aikido::Zen.track_outbound(connection)
 
           if settings.block_outbound?(connection)

data/lib/aikido/zen/version.rb

@@ -2,7 +2,7 @@
 
 module Aikido
   module Zen
-    VERSION = "1.7.2.beta.1"
+    VERSION = "1.7.2"
 
     # The version of libzen_internals that we build against.
     LIBZEN_VERSION = "0.1.61"

data/lib/aikido/zen/worker_process/agent/client.rb

@@ -8,6 +8,11 @@ module Aikido::Zen::WorkerProcess
       # The keepalive interval must be less than the RPC server read timeout.
       KEEPALIVE_INTERVAL = 4
 
+      # This read timeout should be kept short because attackers can trigger
+      # attack wave detection checks at will, to limit how much latency an
+      # attacker can introduce per request.
+      ATTACK_WAVE_TIMEOUT = 1.0
+
       def initialize(
         host,
         port,
@@ -68,6 +73,20 @@ module Aikido::Zen::WorkerProcess
         raise
       end
 
+      # @param client_ip [String]
+      # @param sample [Aikido::Zen::AttackWave::Sample]
+      # @return [Array<Aikido::Zen::AttackWave::Sample>, nil]
+      def record_attack_wave(client_ip, sample)
+        result = @rpc_client.invoke(
+          "record_attack_wave", ATTACK_WAVE_TIMEOUT,
+          client_ip, sample.verb, sample.path
+        )
+        result&.map { |data| Aikido::Zen::AttackWave::Sample.from_json(data) }
+      rescue => err
+        @config.logger.error("Forked worker process #{Process.pid}: failed to record attack wave sample with parent: #{err.message}")
+        raise
+      end
+
       private
 
       def updated_settings

data/lib/aikido/zen/worker_process/agent/server.rb

@@ -3,8 +3,9 @@
 module Aikido::Zen::WorkerProcess
   module Agent
     class Server
-      def initialize(config: Aikido::Zen.config)
+      def initialize(config: Aikido::Zen.config, detector: Aikido::Zen.attack_wave_detector)
         @config = config
+        @detector = detector
 
         @rpc_server = Aikido::Zen::RPC::Server.new(Aikido::Zen.secret)
 
@@ -25,6 +26,10 @@ module Aikido::Zen::WorkerProcess
           result = calculate_rate_limits(route_data, ip, actor_data)
           respond.call(result&.as_json)
         end
+
+        @rpc_server.handle("record_attack_wave") do |respond, client_ip, verb, path|
+          respond.call(record_attack_wave(client_ip, verb, path))
+        end
       end
 
       def host
@@ -60,8 +65,7 @@ module Aikido::Zen::WorkerProcess
       end
 
       # @api private
-      #
-      # Visible for testing.
+      # @note Visible for testing.
       RequestKind = Struct.new(:route, :schema, :client_ip, :actor)
 
       def updated_settings(known_config_generation = nil, known_firewall_lists_generation = nil)
@@ -92,6 +96,13 @@ module Aikido::Zen::WorkerProcess
         route = Aikido::Zen::Route.from_json(route_data)
         Aikido::Zen.rate_limiter.calculate_rate_limits(RequestKind.new(route, nil, ip, actor))
       end
+
+      # @return [Array<Hash>, nil]
+      def record_attack_wave(client_ip, verb, path)
+        sample = Aikido::Zen::AttackWave::Sample.new(verb: verb, path: path)
+        samples = @detector.record(client_ip, sample)
+        samples&.map(&:as_json)
+      end
     end
   end
 end

data/lib/aikido/zen.rb

@@ -153,6 +153,23 @@ module Aikido
       Fiber.current.aikido_current_context = context
     end
 
+    # @return [Boolean] whether the current request is bypassed.
+    def self.request_bypassed?
+      context = current_context
+      return unless context
+
+      return context.request_bypassed unless context.request_bypassed.nil?
+
+      context.request_bypassed = runtime_settings.bypassed_ip?(context.request.client_ip)
+    end
+
+    # Marks the current request as bypassed.
+    #
+    # @return [void]
+    def self.request_bypassed!
+      current_context&.request_bypassed = true
+    end
+
     # Track statistics about an HTTP request the app is handling.
     #
     # @param request [Aikido::Zen::Request]
@@ -249,6 +266,49 @@ module Aikido
       @attack_wave_detector ||= AttackWave::Detector.new
     end
 
+    # Classifies the current request and, if it is classified as suspicious,
+    # records a sample against the attack wave detector.
+    #
+    # @param context [Aikido::Zen::Context]
+    # @param status_code [Integer, nil]
+    # @return [Array<Aikido::Zen::AttackWave::Sample>, nil]
+    def self.detect_attack_wave(context, status_code = nil)
+      client_ip = context.request.client_ip
+      return nil unless client_ip
+
+      return nil unless AttackWave::Helpers.web_scanner?(context, status_code)
+
+      record_attack_wave(client_ip, AttackWave::Helpers.sample_for(context))
+    end
+
+    # Records a suspicious sample and, if the threshold for triggering
+    # an attack wave has been crossed, flags the client IP as having
+    # just triggered an attack wave.
+    #
+    # In multiprocess deployments, on RPC failure, the worker process
+    # records against its local detector.
+    #
+    # If RPC failures are intermittent, it is possible that an attack
+    # wave may be missed or duplicated, because state is split between
+    # the global and local detectors.
+    #
+    # @param client_ip [String]
+    # @param sample [Aikido::Zen::AttackWave::Sample]
+    # @return [Array<Aikido::Zen::AttackWave::Sample>, nil]
+    def self.record_attack_wave(client_ip, sample)
+      worker_process_client = @worker_process_client
+
+      if worker_process_client
+        begin
+          worker_process_client.record_attack_wave(client_ip, sample)
+        rescue
+          attack_wave_detector.record(client_ip, sample)
+        end
+      else
+        attack_wave_detector.record(client_ip, sample)
+      end
+    end
+
     # @return [Aikido::Zen::IDOR::Protector]
     def self.idor_protector
       @idor_protector ||= IDOR::Protector.new

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: aikido-zen
 version: !ruby/object:Gem::Version
-  version: 1.7.2.beta.1
+  version: 1.7.2
 platform: ruby
 authors:
 - Aikido Security
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-11 00:00:00.000000000 Z
+date: 2026-08-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -93,6 +93,7 @@ files:
 - docs/invalid-sql-queries.md
 - docs/proxy.md
 - docs/rails.md
+- docs/request-bypassing.md
 - docs/troubleshooting.md
 - lib/aikido-zen.rb
 - lib/aikido/zen.rb