README

Filament Scanner Guard

Filament UI for jeffersongoncalves/laravel-scanner-guard: list, filter and unban vulnerability-scanner IPs directly from your admin panel. This plugin ships a read-only Resource over the scanner_guard_bans table, an active/expired filter, and unban / bulk unban actions.

Version Compatibility

Filament	Branch	Version
v3	`1.x`	`^1.0`
v4	`2.x`	`^2.0`
v5	`3.x`	`^3.0`

Note: every branch requires PHP 8.3+ and Laravel 12+ because the underlying jeffersongoncalves/laravel-scanner-guard (via jeffersongoncalves/laravel-visitor-fingerprint) only supports Laravel 12/13. Branch 1.x (Filament v3) is pinned to Laravel 12 in CI — Filament v3.3.x installs against Laravel 13 but breaks at runtime ($getRecordActions / SubNavigationPosition errors), a limitation of Filament v3 itself, not of this plugin.

Installation

You can install the package via composer:

composer require jeffersongoncalves/filament-scanner-guard

This plugin depends on jeffersongoncalves/laravel-scanner-guard, which owns the scanner_guard_bans table, config, middleware and export command. Follow its installation instructions first (publish config, run the migration, attach the scanner-guard middleware to your routes).

Usage

use JeffersonGoncalves\Filament\ScannerGuard\ScannerGuardPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            ScannerGuardPlugin::make(),
        ]);
}

This registers a Scanner Guard Bans resource (list only — rows are written by the scanner-guard middleware, not by admins) and a Metrics page, with:

Columns: ip_hash, reason (badge), matched_value, hit_count, banned_at, expires_at, is_active
A Status filter (active vs expired)
An Unban row action and an Unban selected bulk action — both delete the ban row (this is an audit-trail model, not a flag on an arbitrary model)
A Metrics page with total, active, expired and hit-count stats

Both share one navigation group, Scanner Guard by default — override it with ->navigationGroup():

ScannerGuardPlugin::make()->navigationGroup('Security');

Using the actions standalone

If you'd rather wire the table yourself:

use JeffersonGoncalves\Filament\ScannerGuard\Actions\UnbanAction;
use JeffersonGoncalves\Filament\ScannerGuard\Actions\UnbanBulkAction;

$table
    ->recordActions([
        UnbanAction::make(),
    ])
    ->toolbarActions([
        UnbanBulkAction::make(),
    ]);

Development

# Run static analysis
composer analyse

# Run tests
composer test

# Format code
composer format

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

jeffersongoncalves / filament-scanner-guard

Package info

Security

Fund package maintenance!

Statistics