Laravel Scanner Guard Laravel Package

Product Decisions This Supports

• Deployment architecture: SQL-backed vs. database-free. The 1.3.0 driver split turns a single package into three deployment tiers:
  • database: full audit trail, daily stats, and nginx denylist export — the right default for customer-facing or regulated environments where post-incident review matters.
  • cache: zero-migration, zero-DB adoption for side projects, edge nodes, or services where a short-lived ban is the entire product requirement.
  • http: a satellite/central topology for fleets of Laravel apps that need one consolidated denylist without giving every node database credentials or running aggregation jobs on each.
• Build vs. buy for edge abuse protection. The cache driver lowers the cost of trying the package to a config change, which makes "build a bespoke rate-limiter" or "buy a WAF" easier to defer. The http driver is the stronger argument: it converts the package into a lightweight centralized ban bus, a capability usually purchased as a commercial WAF/edge product.
• Roadmap and scope. The release establishes a clear product boundary: detection and ban enforcement stay per-node; aggregation and export are central-app responsibilities. Future roadmap items (richer central dashboards, per-tenant stats, export formats beyond nginx) now have an obvious home rather than being bolted onto every satellite.
• Operational decisions. scanner-guard:aggregate-and-prune and scanner-guard:export-denylist self-disable with a notice unless the driver is database — a deliberate ops decision that scheduled jobs cannot silently break non-DB deployments. For cache/http teams, that means accepting "no audit trail" as a documented product tradeoff, not a bug to file later.
• Security and data-handling decisions. HMAC-signed forwarding with X-Signature over X-Timestamp + body, plus stale-timestamp (403) and replay (409) rejection, means the central app must own secret distribution and clock hygiene. The central store keeps its own salted ip_hash and holds raw IP only in cache — a decision point for privacy reviews and GDPR-style data-minimization positions.
• Public API contract. ScannerGuard::ban() now returns ?ScannerGuardBan and yields null under cache/http. Any product surface that reads the returned ban model (admin UI, event listeners, audit display) must be specced to handle null; treat this as a minor breaking change when scoping integration work.
• Use cases unlocked: multi-region or multi-tenant Laravel estates sharing one denylist; ephemeral/serverless-style deployments with no persistent SQL; staging and preview environments where running migrations is undesirable; incremental rollout where satellites start on cache and graduate to http without code changes.

When to Consider This Package

Consider adoption when:

• You need per-IP ban enforcement inside a Laravel app and want it configurable rather than bespoke.
• You operate more than one Laravel service and want a single nginx-exportable denylist — the http driver is the deciding feature here.
• You have an environment that cannot or should not run a SQL database (serverless, edge, read-only filesystem, ephemeral containers) — the cache driver removes migrations entirely.
• You want a low-commitment pilot: start on cache, no schema changes, no scheduled jobs, and revisit database if audit requirements appear.
• You can host a central Laravel app for the http mode and can manage a shared HMAC secret plus synchronized clocks across satellites.

Look elsewhere or defer when:

• Audit, compliance, or forensics are hard requirements at the satellite level. cache and http intentionally produce no local audit trail or stats; only the central app on database has them. If each node must independently retain evidence, stay on database or choose a different tool.
• You need sub-second, strongly consistent ban propagation. Forwarding is fire-and-forget after the response with a short timeout, and failures are only logged — satellites can drift from the central view during partial outages. This is eventual consistency by design.
• You require guaranteed delivery of ban events. There is no queue, retry, or dead-letter path described; a timeout silently loses the forward.
• Your cache store is not shared or not durable enough for ban_duration (e.g., per-process array cache), or eviction under memory pressure would silently shorten bans.
• You cannot centralize secret rotation and replay protection — the HMAC scheme is only as strong as the key management around it.
• You need an out-of-the-box WAF, managed rulesets, or bot scoring — this is ban storage and export, not detection.
• You are already deep into a commercial edge/WAF whose denylist you can drive via API; duplicating that logic adds a second source of truth.

How to Pitch It (Stakeholders)

To executives: This release removes the package's biggest adoption blocker — the mandatory SQL database — and adds a way to consolidate bans from many applications into one place. In practice that means we can protect small and edge services without standing up a database per service, and we can run a single central denylist feeding every app's nginx export instead of maintaining one per service. It is a low-cost capability expansion on an existing dependency, not a new platform purchase, and it gives us a credible answer to "should we buy a WAF?" for the IP-banning slice of that problem. Main caveats to note: the lightweight modes deliberately keep no audit history, and forwarding is best-effort, so anything compliance-sensitive stays on the database-backed mode.

To engineering: Driver is selected by scanner-guard.driver / SCANNER_GUARD_DRIVER. Default database is unchanged — no upgrade action required beyond adding the new driver and http keys if the config was published. cache needs no migrations and no scheduled jobs; http forwards bans post-response to POST scanner-guard/bans on a central app (enabled via SCANNER_GUARD_HTTP_SERVER_ENABLED=true), signed with hash_hmac('sha256', X-Timestamp.body, secret), with 403 on bad signature or stale timestamp and 409 on replay. The central app records bans like local ones using its own salted ip_hash, keeps raw IPs in cache only, and its nginx export therefore covers all satellites. aggregate-and-prune and export-denylist now no-op with a notice unless the driver is database, so scheduling them is harmless. One contract change to handle: ScannerGuard::ban() returns ?ScannerGuardBan and is null on cache/http — audit any caller that dereferences the result. Watch items: secret distribution and rotation, clock skew versus the timestamp staleness window, and the fact that failed forwards are logged only, with no retry.