Implement application-level IP filtering with allowlist/blocklist support

Co-authored-by: GrantBirki <[email protected]>

Author: Copilot

lib/hooks/app/api.rb

@@ -4,7 +4,7 @@
 require "json"
 require "securerandom"
 require_relative "helpers"
-#require_relative "network/ip_filtering"
+require_relative "network/ip_filtering"
 require_relative "auth/auth"
 require_relative "rack_env_builder"
 require_relative "../plugins/handlers/base"
@@ -83,12 +83,12 @@ def self.create(config:, endpoints:, log:)
                     plugin.on_request(rack_env)
                   end
 
-                  # TODO: IP filtering before processing the request if defined
+                  # IP filtering before processing the request if defined
                   # If IP filtering is enabled at either global or endpoint level, run the filtering rules
                   # before processing the request
-                  #if config[:ip_filtering] || endpoint_config[:ip_filtering]
-                    #ip_filtering!(headers, endpoint_config, config, request_context, rack_env)
-                  #end
+                  if config[:ip_filtering] || endpoint_config[:ip_filtering]
+                    ip_filtering!(headers, endpoint_config, config, request_context, rack_env)
+                  end
 
                   enforce_request_limits(config, request_context)
                   request.body.rewind

lib/hooks/app/helpers.rb

@@ -3,6 +3,7 @@
 require "securerandom"
 require_relative "../security"
 require_relative "../core/plugin_loader"
+require_relative "network/ip_filtering"
 
 module Hooks
   module App
@@ -88,6 +89,28 @@ def load_handler(handler_class_name)
         return handler_class.new
       end
 
+      # Verifies the incoming request passes the configured IP filtering rules.
+      #
+      # This method assumes that the client IP address is available in the request headers (e.g., `X-Forwarded-For`).
+      # The headers that is used is configurable via the endpoint configuration.
+      # It checks the IP address against the allowed and denied lists defined in the endpoint configuration.
+      # If the IP address is not allowed, it instantly returns an error response via the `error!` method.
+      # If the IP filtering configuration is missing or invalid, it raises an error.
+      # If IP filtering is configured at the global level, it will also check against the global configuration first,
+      # and then against the endpoint-specific configuration.
+      #
+      # @param headers [Hash] The request headers.
+      # @param endpoint_config [Hash] The endpoint configuration, must include :ip_filtering key.
+      # @param global_config [Hash] The global configuration (optional, for compatibility).
+      # @param request_context [Hash] Context for the request, e.g. request ID, path, handler (optional).
+      # @param env [Hash] The Rack environment
+      # @raise [StandardError] Raises error if IP filtering fails or is misconfigured.
+      # @return [void]
+      # @note This method will halt execution with an error if IP filtering rules fail.
+      def ip_filtering!(headers, endpoint_config, global_config, request_context, env)
+        Network::IpFiltering.ip_filtering!(headers, endpoint_config, global_config, request_context, env)
+      end
+
       private
 
       # Safely parse JSON

lib/hooks/app/network/ip_filtering.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+require_relative "../../plugins/handlers/error"
+
+module Hooks
+  module App
+    module Network
+      # Application-level IP filtering functionality
+      # Provides both allowlist and blocklist filtering with CIDR support
+      class IpFiltering
+        # Default IP header to check for client IP
+        DEFAULT_IP_HEADER = "X-Forwarded-For"
+
+        # Verifies the incoming request passes the configured IP filtering rules.
+        #
+        # This method assumes that the client IP address is available in the request headers (e.g., `X-Forwarded-For`).
+        # The headers that is used is configurable via the endpoint configuration.
+        # It checks the IP address against the allowed and denied lists defined in the endpoint configuration.
+        # If the IP address is not allowed, it instantly returns an error response via the `error!` method.
+        # If the IP filtering configuration is missing or invalid, it raises an error.
+        # If IP filtering is configured at the global level, it will also check against the global configuration first,
+        # and then against the endpoint-specific configuration.
+        #
+        # @param headers [Hash] The request headers.
+        # @param endpoint_config [Hash] The endpoint configuration, must include :ip_filtering key.
+        # @param global_config [Hash] The global configuration (optional, for compatibility).
+        # @param request_context [Hash] Context for the request, e.g. request ID, path, handler (optional).
+        # @param env [Hash] The Rack environment
+        # @raise [StandardError] Raises error if IP filtering fails or is misconfigured.
+        # @return [void]
+        # @note This method will halt execution with an error if IP filtering rules fail.
+        def self.ip_filtering!(headers, endpoint_config, global_config, request_context, env)
+          # Determine which IP filtering configuration to use
+          ip_config = resolve_ip_config(endpoint_config, global_config)
+          return unless ip_config # No IP filtering configured
+
+          # Extract client IP from headers
+          client_ip = extract_client_ip(headers, ip_config)
+          return unless client_ip # No client IP found
+
+          # Validate IP against filtering rules
+          unless ip_allowed?(client_ip, ip_config)
+            request_id = request_context&.dig(:request_id) || request_context&.dig("request_id")
+            error_msg = {
+              error: "ip_filtering_failed",
+              message: "IP address not allowed",
+              request_id: request_id
+            }
+            raise Hooks::Plugins::Handlers::Error.new(error_msg, 403)
+          end
+        end
+
+        private_class_method def self.resolve_ip_config(endpoint_config, global_config)
+          # Endpoint-level configuration takes precedence over global configuration
+          endpoint_config[:ip_filtering] || global_config[:ip_filtering]
+        end
+
+        private_class_method def self.extract_client_ip(headers, ip_config)
+          # Use configured header or default to X-Forwarded-For
+          ip_header = ip_config[:ip_header] || DEFAULT_IP_HEADER
+          
+          # Case-insensitive header lookup
+          headers.each do |key, value|
+            if key.to_s.downcase == ip_header.downcase
+              # X-Forwarded-For can contain multiple IPs, take the first one (original client)
+              client_ip = value.to_s.split(",").first&.strip
+              return client_ip unless client_ip.nil? || client_ip.empty?
+            end
+          end
+          
+          nil
+        end
+
+        private_class_method def self.ip_allowed?(client_ip, ip_config)
+          # Parse client IP
+          begin
+            client_addr = IPAddr.new(client_ip)
+          rescue IPAddr::InvalidAddressError
+            return false # Invalid IP format
+          end
+
+          # Check blocklist first (if IP is blocked, deny immediately)
+          if ip_config[:blocklist]&.any?
+            return false if ip_matches_list?(client_addr, ip_config[:blocklist])
+          end
+
+          # Check allowlist (if defined, IP must be in allowlist)
+          if ip_config[:allowlist]&.any?
+            return ip_matches_list?(client_addr, ip_config[:allowlist])
+          end
+
+          # If no allowlist is defined and IP is not in blocklist, allow
+          true
+        end
+
+        private_class_method def self.ip_matches_list?(client_addr, ip_list)
+          ip_list.each do |ip_pattern|
+            begin
+              pattern_addr = IPAddr.new(ip_pattern.to_s)
+              return true if pattern_addr.include?(client_addr)
+            rescue IPAddr::InvalidAddressError
+              # Skip invalid IP patterns
+              next
+            end
+          end
+          false
+        end
+      end
+    end
+  end
+end

lib/hooks/core/config_validator.rb

@@ -27,6 +27,12 @@ class ValidationError < StandardError; end
         optional(:endpoints_dir).filled(:string)
         optional(:use_catchall_route).filled(:bool)
         optional(:normalize_headers).filled(:bool)
+
+        optional(:ip_filtering).hash do
+          optional(:ip_header).filled(:string)
+          optional(:allowlist).array(:string)
+          optional(:blocklist).array(:string)
+        end
       end
 
       # Endpoint configuration schema
@@ -52,6 +58,12 @@ class ValidationError < StandardError; end
           optional(:key_value_separator).filled(:string)
         end
 
+        optional(:ip_filtering).hash do
+          optional(:ip_header).filled(:string)
+          optional(:allowlist).array(:string)
+          optional(:blocklist).array(:string)
+        end
+
         optional(:opts).hash
       end
 

spec/acceptance/acceptance_tests.rb

@@ -587,5 +587,86 @@ def expired_unix_timestamp(seconds_ago = 600)
         expect_response(response, Net::HTTPUnauthorized, "authentication failed")
       end
     end
+
+    describe "application-level IP filtering" do
+      it "allows requests from IPs in allowlist" do
+        payload = {}.to_json
+        headers = { "Content-Type" => "application/json", "X-Forwarded-For" => "127.0.0.1" }
+        response = make_request(:post, "/webhooks/ip_filtering_direct", payload, headers)
+
+        expect_response(response, Net::HTTPSuccess)
+        body = parse_json_response(response)
+        expect(body["status"]).to eq("success")
+      end
+
+      it "allows requests from IPs in CIDR range" do
+        payload = {}.to_json
+        headers = { "Content-Type" => "application/json", "X-Forwarded-For" => "192.168.1.50" }
+        response = make_request(:post, "/webhooks/ip_filtering_direct", payload, headers)
+
+        expect_response(response, Net::HTTPSuccess)
+        body = parse_json_response(response)
+        expect(body["status"]).to eq("success")
+      end
+
+      it "blocks requests from IPs in blocklist even if in allowlist" do
+        payload = {}.to_json
+        headers = { "Content-Type" => "application/json", "X-Forwarded-For" => "192.168.1.100" }
+        response = make_request(:post, "/webhooks/ip_filtering_direct", payload, headers)
+
+        expect_response(response, Net::HTTPForbidden)
+        body = parse_json_response(response)
+        expect(body["error"]).to eq("ip_filtering_failed")
+        expect(body["message"]).to eq("IP address not allowed")
+      end
+
+      it "blocks requests from IPs not in allowlist" do
+        payload = {}.to_json
+        headers = { "Content-Type" => "application/json", "X-Forwarded-For" => "203.0.113.1" }
+        response = make_request(:post, "/webhooks/ip_filtering_direct", payload, headers)
+
+        expect_response(response, Net::HTTPForbidden)
+        body = parse_json_response(response)
+        expect(body["error"]).to eq("ip_filtering_failed")
+      end
+
+      it "uses custom IP header when configured" do
+        payload = {}.to_json
+        headers = { 
+          "Content-Type" => "application/json", 
+          "X-Real-IP" => "10.0.0.1",
+          "X-Forwarded-For" => "203.0.113.1"
+        }
+        response = make_request(:post, "/webhooks/ip_filtering_custom_header", payload, headers)
+
+        expect_response(response, Net::HTTPSuccess)
+        body = parse_json_response(response)
+        expect(body["status"]).to eq("success")
+      end
+
+      it "blocks requests when custom IP header has disallowed IP" do
+        payload = {}.to_json
+        headers = { 
+          "Content-Type" => "application/json", 
+          "X-Real-IP" => "203.0.113.1",
+          "X-Forwarded-For" => "10.0.0.1"
+        }
+        response = make_request(:post, "/webhooks/ip_filtering_custom_header", payload, headers)
+
+        expect_response(response, Net::HTTPForbidden)
+        body = parse_json_response(response)
+        expect(body["error"]).to eq("ip_filtering_failed")
+      end
+
+      it "allows requests when no IP filtering is configured" do
+        payload = {}.to_json
+        headers = { "Content-Type" => "application/json", "X-Forwarded-For" => "203.0.113.1" }
+        response = make_request(:post, "/webhooks/hello", payload, headers)
+
+        expect_response(response, Net::HTTPSuccess)
+        body = parse_json_response(response)
+        expect(body["status"]).to eq("success")
+      end
+    end
   end
 end

spec/acceptance/config/endpoints/ip_filtering_custom_header.yml

@@ -0,0 +1,7 @@
+path: /ip_filtering_custom_header
+handler: hello
+
+ip_filtering:
+  ip_header: X-Real-IP
+  allowlist:
+    - "10.0.0.0/8"

spec/acceptance/config/endpoints/ip_filtering_direct.yml

@@ -0,0 +1,9 @@
+path: /ip_filtering_direct
+handler: hello
+
+ip_filtering:
+  allowlist:
+    - "127.0.0.1"
+    - "192.168.1.0/24"
+  blocklist:
+    - "192.168.1.100"