Laravel Scanner Guard Laravel Package

Getting Started

The first decision on this release is no longer "install and migrate" — it is which driver you run. Look at config/scanner-guard.php and the new driver key (env SCANNER_GUARD_DRIVER) before touching anything else:

• database — the pre-1.3 behaviour. You still need php artisan migrate for the audit and daily-stats tables.
• cache — no migrations, no tables. Bans live only in the configured cache store for ban_duration.
• http — bans live in the local cache and are also forwarded to a central app after the response.

Minimal start for the common case (single app, full audit trail):

1. composer require the package, then publish the config and run migrations.
2. Leave SCANNER_GUARD_DRIVER unset (defaults to database) and confirm your cache/session setup is normal Laravel.
3. Hit a protected route with a scanner-ish user agent and check that a row lands in the bans table and that ScannerGuard::ban() returned a ScannerGuardBan model.

If you already publish the config, add the new driver and http keys manually — the package won't merge them for you, and a missing key means the new code paths fall back or error depending on how you read config.

First use case to wire up: the guard on your login, contact and search endpoints, then a single ScannerGuard::ban($request) call at the detection point. From there the driver determines what "ban" actually costs you.

Implementation Patterns

Pick the driver per environment, not per project. A very natural split: database locally and on your primary app, cache in CI and ephemeral review apps (no migrations to run, no tables to seed), http on satellites that should not own a database. Set SCANNER_GUARD_DRIVER in .env / .env.testing rather than editing the config, so the same image runs everywhere.

Treat ban() as fire-and-forget. It now returns ?ScannerGuardBan: a model for database, null for cache and http. Any call site that used the return value — to log an ID, redirect to an admin page, or assert in a test — needs a null-safe path. The idiomatic shape is:

$ban = ScannerGuard::ban($request);
// don't branch on $ban unless you're on the database driver

Central aggregation topology (http driver). Satellites forward a HMAC-signed POST; the central app opts in with SCANNER_GUARD_HTTP_SERVER_ENABLED=true, which registers POST scanner-guard/bans. On the central side you get the same artefacts as a local ban: its own salted ip_hash, daily stats, and a raw IP held only in cache — which means the central app's scanner-guard:export-denylist covers every satellite in one nginx file. That is the real payoff: one denylist to distribute, many edges reporting into it.

Signing details you'll actually implement. The signature is hash_hmac('sha256', X-Timestamp.body, secret), sent as X-Signature. So the secret is shared out-of-band between satellite and central, and the timestamp must be inside the central app's freshness window. Build a small helper or config value for the secret rather than inlining env() calls (which return null once config is cached).

Testing. Under cache the driver is fast and stateless — ideal for feature tests that assert "this request gets banned" without touching a database. Assert on the cache key/TTL rather than on a model. Keep a separate database-driver test for anything that depends on stats or the export command.

Gotchas and Tips

• The scheduled commands silently stop doing work. scanner-guard:aggregate-and-prune and scanner-guard:export-denylist are not scheduled by the package, and they skip with a notice unless the driver is database. If you switch a production app to cache or http, your nginx denylist quietly stops updating. Watch for the skip notice in scheduler output, and remember that aggregation/pruning only ever happens on a database node — for an http fleet that node is the central app.
• Forwarding failures are logged, not retried. The request happens after the response with a short timeout, and a failure costs you the ban record, not the user's page load. That is the right trade-off, but it means a central app outage creates a silent gap in the fleet's denylist. Alert on the log channel, and don't expect queue-style durability.
• 409 is success, not failure. Replays are rejected with 409. If you ever add retry logic, resending the identical body with the same X-Timestamp will 409 forever — treat it as "already recorded" and move on.
• 403 usually means clock drift. Stale timestamps are rejected. Satellites without NTP will intermittently fail to forward and you'll only see it in logs. Also verify the central route is exempt from CSRF and any signature-verifying middleware ordering, since it is an API endpoint registered by the package.
• Cache-driver bans are as durable as your cache. Redis eviction under memory pressure, cache:clear, and deploy-time flushes all drop active bans. Use a dedicated store for scanner-guard if bans must survive deploys, and keep ban_duration short enough that the TTL semantics are obvious to whoever reads the config.
• IP hashes are salted per app, on purpose. The central app computes its own hash, so you cannot join satellite records to central records by hash, and you can't correlate the same attacker across two independently-salted installations. Aggregation works for "how many bans today", not for per-IP forensics. Raw IPs exist only in the central cache — factor that into your retention story.
• Upgrade checklist for published configs: add driver and the http block, set the shared secret and central URL on satellites, share the same secret on the central app, and run config:cache fresh. If ban() returning null breaks a type hint somewhere, the failure shows up only on non-database drivers — grep for ScannerGuardBan before you flip the env var.
• Extension point worth knowing: because the signature input is timestamp + '.' + body, you can construct and verify forward requests yourself for custom transports (queues, log shippers) without forking the package — just keep the header names and signing string identical.