Filament Firewall Laravel Package

Technical Evaluation

Architecture Fit

• Middleware-Based Design: The package leverages Laravel’s middleware system, which aligns well with Filament’s modular architecture. It integrates seamlessly into Filament’s request lifecycle without requiring invasive changes to core logic.
• Role-Based Access Control (RBAC) Extension: Complements Filament’s built-in auth by adding granular IP/geolocation-based restrictions, useful for high-security environments (e.g., enterprise SaaS, government portals).
• Event-Driven Hooks: Supports Filament’s event system (e.g., Filament\Actions\ActionRegistered) for dynamic firewall rule application, reducing hardcoding.

Integration Feasibility

• Low Coupling: Middleware pattern ensures minimal dependency on Filament internals, reducing risk of breaking changes during Filament updates.
• Config-Driven: Rules (whitelists/blacklists) are configurable via config/filament-firewall.php, enabling environment-specific policies (e.g., dev/staging/prod).
• Geolocation Support: Uses geoip2 (via league/geoip2), requiring minimal setup if not already in the stack.

Technical Risk

• Geolocation Dependency: Relies on MaxMind’s GeoIP2 database (commercial license for production). Cost and maintenance of database updates must be accounted for.
• Performance Overhead: IP/geolocation lookups add latency (~5–50ms per request). Caching (e.g., Redis) is recommended for high-traffic apps.
• Filament Version Lock: Last release in 2026 may indicate compatibility risks with older Filament versions (e.g., <2.x). Test against target Filament version early.
• No Rate Limiting: Lacks DDoS protection; pair with Laravel’s throttle middleware if needed.

Key Questions

1. Security Requirements:
   • Are IP/geolocation restrictions mandatory, or is this a supplementary layer?
   • Do we need integration with existing auth systems (e.g., LDAP, OAuth) for hybrid rules?
2. Performance:
   • What’s the expected request volume? Will caching (Redis) be implemented?
3. Compliance:
   • Does the geolocation database meet GDPR/regional data residency laws?
4. Maintenance:
   • Who will manage GeoIP2 database updates and license costs?
5. Testing:
   • How will we validate rules without breaking CI/CD (e.g., mock geolocation in tests)?

Integration Approach

Stack Fit

• Laravel 10+ / Filament 3.x: Confirmed compatibility (package targets Filament 3.x). For older versions, check middleware signature changes.
• Geolocation Stack:
  • Required: league/geoip2 (v3.x), MaxMind GeoLite2 database.
  • Optional: spatie/geoip (alternative) or cloud-based services (e.g., IP2Location).
• Caching Layer:
  • Redis recommended for caching IP/geolocation lookups (reduce MaxMind API calls).
  • Use Illuminate\Support\Facades\Cache with TTL (e.g., 1 hour).

Migration Path

1. Pre-Integration:
   • Audit existing auth middleware (e.g., auth, verified) to avoid conflicts.
   • Set up GeoIP2 database (download from MaxMind).
2. Installation:

   composer require solution-forest/filament-firewall
   php artisan vendor:publish --provider="SolutionForest\FilamentFirewall\FilamentFirewallServiceProvider"
   

3. Configuration:
   • Define rules in config/filament-firewall.php:

     'whitelist' => [
         '192.168.1.0/24', // Office subnet
         'US', 'GB',       // Countries (requires GeoIP2)
     ],
     'blacklist' => [
         '1.2.3.4',       // Malicious IP
         'RU', 'CN',       // Restricted countries
     ],
     

4. Middleware Registration:
   • Add to app/Http/Kernel.php (global) or Filament-specific routes:

     protected $middleware = [
         \SolutionForest\FilamentFirewall\Middleware\Firewall::class,
     ];
     

5. Dynamic Rules:
   • Extend via Filament events (e.g., Filament\Contracts\Plugin hooks) for runtime rule updates.

Compatibility

• Filament Plugins: Works alongside Filament plugins (e.g., filament/spatie-laravel-permission) if rules are merged logically.
• Custom Middleware: Can be wrapped or extended (e.g., add logging):

  $firewall->extend(function ($request) {
      \Log::info("Firewall check for IP: {$request->ip()}");
  });
  

• Testing:
  • Use filament/testing to mock requests:

    $response = $this->actingAs($user)
        ->withHeaders(['X-Forwarded-For' => '192.168.1.100'])
        ->get('/admin');
    

Sequencing

1. Phase 1: Implement static rules (whitelist/blacklist) in staging.
2. Phase 2: Add geolocation support with caching.
3. Phase 3: Integrate with monitoring (e.g., log blocked requests to Sentry).
4. Phase 4: Automate GeoIP2 updates via cron or CI.

Operational Impact

Maintenance

• GeoIP2 Updates:
  • Schedule monthly database updates (MaxMind releases new versions quarterly).
  • Automate via script or use spatie/laravel-geoip for managed updates.
• Rule Management:
  • Use Filament’s Pages\Settings to expose a UI for admins to edit rules (extend the package or build a custom panel).
  • Version-control config/filament-firewall.php via Git.
• Dependency Updates:
  • Monitor solution-forest/filament-firewall for Filament 4.x compatibility.
  • Pin league/geoip2 to avoid breaking changes.

Support

• Blocked User Flow:
  • Customize the 403 response (extend Firewall::class) to include helpful messages (e.g., "Access denied from your location").
  • Example:

    public function handle($request, Closure $next)
    {
        if ($this->isBlocked($request)) {
            return response()->view('filament::firewall.blocked', [], 403);
        }
        return $next($request);
    }
    

• Logging:
  • Log blocked attempts with context (IP, country, user agent) for forensics:

    \Log::channel('security')->info('Firewall blocked', [
        'ip' => $request->ip(),
        'country' => $this->getCountry($request),
        'user_agent' => $request->userAgent(),
    ]);
    

• Alerting:
  • Integrate with tools like Datadog or Sentry to alert on unusual patterns (e.g., repeated blocks from a new IP).

Scaling

• Performance:
  • Caching: Cache GeoIP2 lookups in Redis with a 1-hour TTL to reduce MaxMind API calls.

    $country = Cache::remember("geoip:{$ip}", 3600, function () use ($ip) {
        return $this->geoip->getCountry($ip);
    });
    

  • Load Testing: Simulate 10K RPS to validate latency impact (target <100ms p99).
• Distributed Systems:
  • Deploy GeoIP2 database locally in each region (avoid cross-region latency).
  • Use spatie/geoip for cloud-based lookups if multi-region.
• Database:
  • For large-scale whitelists, store IPs in a firewall_rules table and query via Eloquent (avoid regex in middleware).

Failure Modes

Ramp-Up

• Onboarding:
  • Developers: 2-hour workshop on middleware extension and GeoIP2 setup.
  • DevOps: Document GeoIP2 update process and caching configuration.