Filament Scanner Guard Laravel Package

Technical Evaluation

Architecture fit filament-scanner-guard is a Filament panel plugin for detecting and banning vulnerability-scanner/bot traffic, with an admin UI and a bans-per-day chart. It fits Laravel applications that already run a Filament admin panel and want in-app visibility and manual/automatic ban controls. It is a poor fit for API-only services, non-Filament backends, or teams expecting an edge/WAF-grade control — this is application-level detection, not a replacement for Cloudflare/AWS WAF/nginx limits.

Architecturally it introduces three concerns into the request path: a middleware-style request inspection layer, persistent ban state (DB tables), and admin-panel UI/widgets for reporting. That is a reasonable fit for a monolith or a small platform team; it is a weaker fit for distributed services where each node needs consistent ban state and low-latency lookups.

Integration feasibility Standard Composer install, config/migration publishing, and plugin registration in the PanelProvider. Integration effort is low-to-moderate — likely under a day for a developer familiar with Filament, plus staging observation time. The main unknowns are runtime version constraints (see risk), migration behaviour on existing ban tables, and how the package resolves client IPs behind proxies/CDNs.

Technical risk

• Single-maintainer / low bus factor. The package is small and maintained by one author. Treat it as "adopt with a fork option," not a strategic dependency.
• 1.2.0 is non-breaking. Changes are dependency bumps, CI workflow standardization, and one functional bug fix. No deprecations or API changes are indicated.
• The functional fix changes data-retention semantics. "Keep bans-per-day chart history after purge/unban" implies purge/unban previously destroyed reporting data. Post-1.2.0, historical ban records (or an aggregate/archive representation) persist beyond the ban's active lifetime. That is good for reporting but is a privacy/compliance and storage-growth consideration if IPs or request metadata are retained.
• The testbench bump to ^11.0 is dev-only. It widens the test harness but does not by itself demonstrate runtime support for a newer Laravel/Filament line. Verify composer.json runtime constraints before planning an upgrade.
• 1.x maturity. Expect limited production hardening around edge cases: trusted proxies, IPv6, allowlists, admin lockout, multi-tenant scoping.

Key questions

1. Does 1.2.0 ship a migration, and does purge now soft-delete bans or write to a separate history/aggregate table?
2. What exactly is retained after purge/unban — full IP + user agent + path, or aggregated counts only? What is the growth rate per 1k bans?
3. What runtime constraints (illuminate/*, filament/*, PHP) are declared? Is Laravel 12 / Filament v4 actually supported, or only tested in dev?
4. How is the client IP resolved? Does it honour TrustProxies, X-Forwarded-For, Cloudflare headers? Misresolution can ban a CDN or load-balancer IP and take the site down.
5. Is there an allowlist, admin self-exemption, and a dry-run/detection-only mode?
6. Does detection perform a DB query on every request, and is there caching/indexing for the IP lookup?
7. Is ban state scoped per tenant where multi-tenancy is used?
8. What is the fail-open/fail-closed behaviour if the DB or cache is unavailable?
9. Test coverage and CI signal — the workflow was standardized, but what is actually covered?

Integration Approach

Stack fit Best fit: Laravel 10/11/12 monolith or modular monolith with Filament v3/v4 admin, PHP 8.2+, behind a known reverse proxy/CDN. Weak fit: headless/API-only, multi-region active-active, or teams without a Filament admin surface.

Migration path

1. Pin the exact version (1.2.0) and review the diff between 1.1.0 and 1.2.0, specifically the chart-history change and any migration files.
2. Install in staging: composer require, publish config and migrations, run migrations against a copy of production-sized ban data.
3. Register the plugin in the Filament panel provider and enable detection-only mode first — do not enable automatic banning on day one.
4. Configure trusted proxies/CDN handling and populate the allowlist (office IPs, monitoring, admin/VPN egress, payment/provider webhooks) before enabling enforcement.
5. Add a dashboard review of the bans-per-day chart and confirm the post-purge history behaviour matches expectations.
6. Roll out to production with auto-ban initially off; enable after a 1–2 week observation window.

Compatibility Treat the orchestra/testbench ^10.0 || ^11.0 change as a testing-matrix widening only. Confirm declared runtime support in composer.json and test against the exact Laravel/Filament versions in use. Filament major-version compatibility is the most likely breakage point on future upgrades.

Sequencing (a) Version pin and diff review → (b) staging migration and detection-only run → (c) proxy/IP-resolution validation → (d) allowlist and runbook → (e) enable auto-ban → (f) define a retention policy for the now-persistent history → (g) monitor table growth and query latency for one release cycle before considering upgrades beyond 1.2.x.

Operational Impact

Maintenance Low code footprint but a single-maintainer dependency with dependabot-driven releases. Budget for periodic review of each bump; assume you may need to fork or vendor-patch. Pin versions and avoid floating constraints.

Support Community OSS, no SLA. Name an internal owner (platform/backend lead) and document escalation as "fork and patch." Support desk needs a documented unban procedure and a clear "who to call" when a legitimate user or admin is banned.

Scaling Per-request inspection plus a ban lookup is the primary cost. On high-traffic sites, ensure the IP lookup is indexed and cached (Redis) and that the middleware short-circuits cheaply. The 1.2.0 history-retention fix increases stored data — plan indexes and a purge/archive job for historical chart data, and monitor bans-table growth.

Failure modes

• False-positive bans blocking customers, partners, or admins (including locking out the person who can unban). Mitigate with allowlist, admin exemption, and conservative thresholds.
• Proxy/CDN misconfiguration causing the edge or load-balancer IP to be banned, resulting in site-wide outage.
• Middleware exception escalating to 500s on every request; confirm fail-open behaviour and wrap in a circuit-breaker/log-only fallback.
• DB/cache unavailability degrading request latency or breaking the ban check.
• Migration failure on large existing ban tables during the 1.2.0 upgrade.
• Unexpected data retention from the chart-history fix — a compliance/GDPR concern if full IPs are retained indefinitely after purge.

Ramp-up Developer integration: ~0.5–1 day for a Filament-fluent engineer. Operations/SRE: ~1 day to document proxy behaviour, allowlist management, retention policy, and the unban runbook. Security/privacy review: 0.5 day to confirm what is logged and for how long, given the retention change in 1.2.0. Total realistic time-to-safe-production: 2–3 weeks including the detection-only observation window.