add docs

Author: GrantBirki

docs/ip_filtering.md

@@ -1,6 +1,6 @@
 # IP Filtering
 
-The Hooks service provides comprehensive application-level IP filtering functionality that allows you to control access to your webhooks based on client IP addresses. This feature supports both allowlist (whitelist) and blocklist (blacklist) configurations with CIDR notation support.
+The Hooks service provides comprehensive application-level IP filtering functionality that allows you to control access to your webhooks based on client IP addresses. This feature supports both allowlist and blocklist configurations with CIDR notation support.
 
 ## Overview
 
@@ -38,6 +38,8 @@ ip_filtering:
 
 Configure IP filtering for specific endpoints:
 
+> If a global configuration is set, endpoint-level settings will override it.
+
 ```yaml
 # config/endpoints/secure-endpoint.yml
 path: /secure-webhook
@@ -55,17 +57,20 @@ ip_filtering:
 ## Configuration Options
 
 ### `ip_header` (optional)
+
 - **Default**: `X-Forwarded-For`
 - **Description**: HTTP header to check for the client IP address
 - **Common alternatives**: `X-Real-IP`, `CF-Connecting-IP`, `X-Client-IP`
 
 ### `allowlist` (optional)
+
 - **Type**: Array of strings
 - **Description**: List of allowed IP addresses or CIDR ranges
 - **Behavior**: If specified, only IPs in this list are allowed access
 - **Format**: Individual IPs (`192.168.1.1`) or CIDR notation (`192.168.1.0/24`)
 
 ### `blocklist` (optional)
+
 - **Type**: Array of strings
 - **Description**: List of blocked IP addresses or CIDR ranges
 - **Behavior**: IPs in this list are denied access, even if they appear in the allowlist
@@ -167,7 +172,7 @@ When IP filtering fails, the service returns an HTTP 403 Forbidden response:
 {
   "error": "ip_filtering_failed",
   "message": "IP address not allowed",
-  "request_id": "550e8400-e29b-41d4-a716-446655440000"
+  "request_id": "<uuid>"
 }
 ```
 
@@ -188,111 +193,3 @@ curl -H "X-Forwarded-For: 192.168.1.100" \
      -d '{"test": "data"}' \
      http://localhost:8080/webhooks/secure-endpoint
 ```
-
-## Common Use Cases
-
-### 1. Restrict to Corporate Network
-
-```yaml
-ip_filtering:
-  allowlist:
-    - "10.0.0.0/8"        # Private network
-    - "172.16.0.0/12"     # Private network
-    - "192.168.0.0/16"    # Private network
-```
-
-### 2. Allow Specific Service Providers
-
-```yaml
-ip_filtering:
-  allowlist:
-    - "140.82.112.0/20"   # GitHub webhook IPs (example)
-    - "192.30.252.0/22"   # GitHub webhook IPs (example)
-```
-
-### 3. Block Known Bad Actors
-
-```yaml
-ip_filtering:
-  blocklist:
-    - "203.0.113.0/24"    # Example bad network
-    - "198.51.100.50"     # Specific bad IP
-```
-
-### 4. Development vs Production
-
-```yaml
-# Development - allow local testing
-ip_filtering:
-  allowlist:
-    - "127.0.0.1"
-    - "192.168.1.0/24"
-
-# Production - restrict to known sources
-ip_filtering:
-  allowlist:
-    - "10.0.0.0/8"
-  blocklist:
-    - "10.0.0.100"  # Compromised internal host
-```
-
-## Best Practices
-
-1. **Start Restrictive**: Begin with a narrow allowlist and expand as needed
-2. **Monitor Logs**: Watch for legitimate traffic being blocked
-3. **Layer Security**: Use IP filtering alongside other security measures
-4. **Document Changes**: Keep track of why specific IPs or ranges are allowed/blocked
-5. **Regular Review**: Periodically review and update your IP filtering rules
-6. **Test Thoroughly**: Always test configuration changes in a non-production environment first
-7. **Consider Automation**: For dynamic environments, consider using network-level controls instead
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Wrong IP Header**: Verify your proxy/load balancer sets the correct IP header
-2. **CIDR Notation**: Ensure CIDR ranges are correctly formatted
-3. **Header Case**: The service performs case-insensitive header lookup
-4. **Multiple IPs**: Only the first IP in comma-separated headers is checked
-5. **IPv6 Support**: The service supports IPv6 addresses and ranges
-
-### Debug Steps
-
-1. Check server logs for IP filtering messages
-2. Verify the client IP being detected matches expectations
-3. Test with known good/bad IPs
-4. Confirm endpoint vs global configuration precedence
-5. Validate CIDR range calculations
-
-## Performance Considerations
-
-- IP filtering adds minimal overhead to request processing
-- CIDR matching is optimized for common use cases
-- Consider the number of rules - hundreds of rules may impact performance
-- Invalid IP patterns in configuration are silently skipped
-
-## Migration from Auth Plugins
-
-If you're currently using custom auth plugins for IP filtering, you can migrate to the built-in IP filtering feature:
-
-**Before (Custom Auth Plugin):**
-```yaml
-path: /webhook
-handler: my_handler
-auth:
-  type: my_ip_filtering_plugin
-opts:
-  allowed_ips:
-    - "192.168.1.1"
-```
-
-**After (Built-in IP Filtering):**
-```yaml
-path: /webhook
-handler: my_handler
-ip_filtering:
-  allowlist:
-    - "192.168.1.1"
-```
-
-The built-in IP filtering provides better performance, more features (CIDR support, blocklists), and consistent error handling across all endpoints.