Filament Security Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require wallacemartinss/filament-security
   

   Publish the config and migrations:

   php artisan vendor:publish --provider="WallaceMartinss\FilamentSecurity\FilamentSecurityServiceProvider" --tag="filament-security-config"
   php artisan vendor:publish --provider="WallaceMartinss\FilamentSecurity\FilamentSecurityServiceProvider" --tag="filament-security-migrations"
   php artisan migrate
   

2. Register Plugin: Add to app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \WallaceMartinss\FilamentSecurity\FilamentSecurityPlugin::make(),
           ]);
   }
   

3. First Use Case: Enable honeypot in config/filament-security.php:

   'honeypot' => [
       'enabled' => true,
       'field_name' => 'fake_field',
   ],
   

   Add a hidden field with name="fake_field" to your Filament form. Bots filling this will be blocked.

Implementation Patterns

Core Workflows

1. Email Validation:

   • Disposable Email Blocking: Integrate with Filament\Forms\Components\TextInput:

     TextInput::make('email')
         ->rules([
             function ($livewire) {
                 return \WallaceMartinss\FilamentSecurity\Facades\FilamentSecurity::isDisposableEmail($livewire->email);
             },
         ])
         ->afterStateUpdated(function ($state, $set) {
             if (\WallaceMartinss\FilamentSecurity\Facades\FilamentSecurity::isDisposableEmail($state)) {
                 $set('email', null);
                 $this->addError('email', 'Disposable emails are not allowed.');
             }
         }),
     

   • DNS/MX Verification: Use the facade to validate during registration:

     if (!\WallaceMartinss\FilamentSecurity\Facades\FilamentSecurity::validateEmailDomain($email)) {
         throw ValidationException::withMessages(['email' => 'Domain does not exist.']);
     }
     

2. Cloudflare IP Blocking:

   • Whitelist IPs in config/filament-security.php:

     'cloudflare' => [
         'enabled' => true,
         'whitelisted_ips' => ['192.168.1.1', '10.0.0.1'],
     ],
     

   • Check IP in middleware:

     use WallaceMartinss\FilamentSecurity\Facades\FilamentSecurity;
     
     public function handle(Request $request, Closure $next)
     {
         if (FilamentSecurity::isCloudflareIpBlocked($request->ip())) {
             abort(403, 'Access denied.');
         }
         return $next($request);
     }
     

3. Single Session Enforcement:

   • Apply to Filament users via policy:

     public function handle(Request $request, Closure $next)
     {
         if (\WallaceMartinss\FilamentSecurity\Facades\FilamentSecurity::hasMultipleSessions($request->user())) {
             auth()->logoutOtherDevices($request->user()->id);
         }
         return $next($request);
     }
     

4. Security Dashboard:

   • Access via /admin/security (auto-registered). Monitor blocked IPs, disposable emails, and honeypot triggers in real-time.

Integration Tips

• Custom Validation Rules: Extend the package’s validation logic by publishing and modifying the rules.php config file:

  'email' => [
      'disposable_providers' => [
          'temp-mail.org',
          'guerrillamail.com',
      ],
  ],
  

• Event Listeners: Listen for security events (e.g., DisposableEmailBlocked) to log or notify admins:

  \WallaceMartinss\FilamentSecurity\Events\DisposableEmailBlocked::class => [
      \App\Listeners\LogSecurityEvent::class,
  ],
  

• RDAP Domain Age Check: Enable in config and validate during registration:

  'rdap' => [
      'enabled' => true,
      'min_domain_age_days' => 30,
  ],
  

  if (!\WallaceMartinss\FilamentSecurity\Facades\FilamentSecurity::isDomainOldEnough($domain)) {
      throw ValidationException::withMessages(['email' => 'Domain too new.']);
  }
  

Gotchas and Tips

Pitfalls

1. DNS/MX Validation Latency:

   • External DNS lookups can slow down registration. Cache results in config/filament-security.php:

     'dns' => [
         'cache_ttl_minutes' => 60,
     ],
     

   • Use a local DNS resolver (e.g., dns_get_record) for offline testing.

2. Cloudflare IP Blocking:

   • Ensure CF-Connecting-IP header is passed if behind Cloudflare. Configure middleware to parse it:

     $ip = $request->header('CF-Connecting-IP') ?? $request->ip();
     

   • Test with FilamentSecurity::isCloudflareIpBlocked($ip) before deploying.

3. Honeypot False Positives:

   • Avoid naming fields starting with honeypot_ or fake_ in other forms to prevent accidental triggers.
   • Exclude specific routes from honeypot checks in config:

     'honeypot' => [
         'excluded_routes' => ['admin.pages.*'],
     ],
     

4. RDAP API Limits:

   • RDAP queries may fail under high load. Implement a fallback (e.g., assume domain is valid if RDAP fails):

     try {
         $isValid = FilamentSecurity::isDomainOldEnough($domain);
     } catch (\Exception $e) {
         $isValid = true; // Fallback
     }
     

5. Session Enforcement Conflicts:

   • Single session enforcement may disrupt user experience. Notify users before logging out other devices:

     if (FilamentSecurity::hasMultipleSessions($user)) {
         $user->notify(new OtherDevicesActive($user->otherDevices()));
     }
     

Debugging

• Log Security Events: Enable logging in config/filament-security.php:

  'logging' => [
      'enabled' => true,
      'channel' => 'security',
  ],
  

  Check logs for blocked requests or validation failures.

• Test Disposable Email List: Use the FilamentSecurity::isDisposableEmail() method to test emails:

  \WallaceMartinss\FilamentSecurity\Facades\FilamentSecurity::isDisposableEmail('test@temp-mail.org'); // Returns true
  

• Dashboard Debugging: The dashboard shows blocked IPs, disposable emails, and honeypot triggers. Use it to verify configurations:

  • Top Offending IPs: Identify bots or malicious actors.
  • Event Table: Filter by event type (e.g., honeypot_triggered).

Extension Points

1. Custom Security Layers:

   • Add new validation rules by extending the FilamentSecurity facade or creating a decorator:

     \WallaceMartinss\FilamentSecurity\Facades\FilamentSecurity::extend(function ($security) {
         $security->addRule('custom_rule', function ($value) {
             return str_contains($value, 'malicious');
         });
     });
     

2. Override Default Policies:

   • Replace the default SecurityPolicy by binding your own in AppServiceProvider:

     $this->app->bind(
         \WallaceMartinss\FilamentSecurity\Contracts\SecurityPolicy::class,
         \App\Policies\CustomSecurityPolicy::class
     );
     

3. Custom Event Handlers:

   • Extend the SecurityEvent class to add custom data:

     class CustomSecurityEvent extends \WallaceMartinss\FilamentSecurity\Events\SecurityEvent
     {
         public function __construct(
             public string $customData,
             array $extra = []
         ) {
             parent::__construct($extra);
         }
     }
     

4. Modify Dashboard Widgets:

   • Override the dashboard plugin by publishing and extending the FilamentSecurityPlugin:

     \WallaceMartinss\FilamentSecurity\FilamentSecurityPlugin::make()
         ->modifyQueryUsing(fn (Builder $query) => $query->where('created_at', '>', now()->subDays(7)))