Laravel Firewall Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require akaunting/laravel-firewall
   php artisan vendor:publish --provider="Akaunting\Firewall\FirewallServiceProvider" --tag="config"
   

   • Publishes the default config (config/firewall.php).

2. Basic Configuration Edit config/firewall.php to define rules:

   'rules' => [
       'block' => [
           'ip-ranges' => [
               '192.168.1.0/24', // Block entire subnet
           ],
           'user-agents' => [
               'BadBot', // Block requests with this UA
           ],
       ],
       'allow' => [
           'ip-ranges' => [
               '10.0.0.0/8', // Whitelist internal network
           ],
       ],
   ],
   

3. First Use Case

   • Test a blocked request:

     curl -A "BadBot" http://your-app.test
     

     Should return a 403 Forbidden response if configured.

Implementation Patterns

Rule-Based Workflows

1. Dynamic Rule Loading Override config/firewall.php rules via environment variables or cached config:

   'rules' => env('FIREWALL_RULES', []),
   

   • Useful for staging/production parity.

2. Middleware Integration Manually trigger checks in custom middleware:

   use Akaunting\Firewall\Facades\Firewall;
   
   public function handle($request, Closure $next) {
       if (Firewall::isBlocked($request)) {
           abort(403, 'Access denied by firewall.');
       }
       return $next($request);
   }
   

3. Rate Limiting Combine with Laravel’s rate limiter:

   'rules' => [
       'rate-limit' => [
           'max' => 100, // Requests per minute
           'key' => 'ip', // 'ip' or 'user'
       ],
   ],
   

Advanced Patterns

• Geoblocking Use geoip2 extension to block countries:

  'rules' => [
      'block' => [
          'countries' => ['RU', 'CN'], // ISO codes
      ],
  ],
  

  Requires geoip2/geoip2 and config:

  'geoip' => [
      'database' => database_path('GeoLite2-Country.mmdb'),
  ],
  

• API-Specific Rules Apply rules only to API routes via route middleware:

  Route::middleware(['firewall:api'])->group(function () {
      // API routes here
  });
  

Gotchas and Tips

Common Pitfalls

1. Rule Precedence

   • allow rules override block rules. Order matters:

     'rules' => [
         'block' => ['ip-ranges' => ['192.168.1.0/24']],
         'allow' => ['ip-ranges' => ['192.168.1.100']], // Whitelists 192.168.1.100
     ],
     

2. Performance Impact

   • GeoIP lookups are slow. Cache results:

     'geoip' => [
         'cache' => true, // Uses Laravel cache
     ],
     

   • User-agent checks can be resource-intensive for high traffic. Limit regex complexity.

3. Logging

   • Enable debug logs for blocked requests:

     'logging' => [
         'enabled' => true,
         'path' => storage_path('logs/firewall.log'),
     ],
     

Debugging Tips

• Check Blocked Requests

  tail -f storage/logs/firewall.log
  

• Test Rules Locally Use tinker to inspect rules:

  use Akaunting\Firewall\Facades\Firewall;
  Firewall::getRules(); // Dump all active rules
  

Extension Points

1. Custom Rule Providers Extend rule loading via FirewallServiceProvider:

   public function register() {
       $this->app->bind('firewall.rules', function () {
           return [
               'block' => ['custom' => ['your_logic_here']],
           ];
       });
   }
   

2. Event Hooks Listen for firewall.blocked events:

   Event::listen('firewall.blocked', function ($request, $rule) {
       // Custom logic (e.g., notify admin)
   });
   

3. Whitelisting Entire Routes Use route middleware with except:

   Route::middleware(['firewall:api'])->group(function () {
       // ...
   })->except(['admin.*']); // Skip firewall for admin routes