Scanner Ban Bundle Laravel Package

Getting Started

The package filters incoming HTTP requests at the middleware layer: it refuses clients whose User-Agent matches its blocklist (curl, empty/absent agents, scripted clients), and lets everything else through unless constrained by allowed_ips.

Minimal setup:

1. Install and let the service provider auto-register; publish config if you need to override allowed_ips.
2. Confirm framework.trusted_proxies is set for your topology (see Gotchas — as of v1.0.1 this is effectively a hard requirement, not a nicety).
3. Hit the app with curl from outside to see the 403, then hit it with a browser to confirm pass-through.

First use case to verify: your post-deploy smoke test. Before v1.0.1 a curl http://localhost/health from inside the container returned 403 and made healthy deploys look broken. On v1.0.1 loopback (127.0.0.1 / ::1) is unconditionally allowed, so health checks, probes, and self-calls work with no config change. This is the first thing to re-test after upgrading, and the first thing to look at if you previously worked around it by putting loopback into allowed_ips — that entry is now redundant.

Implementation Patterns

Treat loopback allowance as an invariant, not a knob. Do not add 127.0.0.1 to allowed_ips going forward; it is ignored for this purpose and adding it just creates config that lies about what it does. If your deployed config carries that entry from an older workaround, remove it in the same PR as the version bump.

Keep self-calls on loopback deliberately. Internal callers (queue workers hitting your own API, scheduler pings, sidecar health probes) should target http://localhost or http://127.0.0.1 so they inherit the exemption. If an internal caller instead goes out through the public hostname, it re-enters as external traffic and is subject to the blocklist — including its curl-ish User-Agent.

Set a real User-Agent on any internal HTTP client you own. Loopback is exempt, but anything crossing a network boundary is not. Http::withHeaders(['User-Agent' => 'myapp-internal/1.0'])->post(...) is cheaper than debugging a 403 in a queue worker.

Configure trusted proxies where the framework expects it. On Laravel 11+ that is ->withMiddleware(fn ($m) => $m->trustProxies(at: '*')) or an explicit CIDR list in bootstrap/app.php; on older versions, the TrustProxies middleware. This is what makes $request->ip() the real client address rather than the proxy's, and it is the single point of failure for both allowed_ips and the new loopback exemption.

Wire the health endpoint into your deploy pipeline as the canary. curl -fsS http://localhost/health || exit 1 immediately after rollout, before the probe timeout, gives you a fast signal that the middleware is loaded and behaving.

Gotchas and Tips

The loopback exemption is a security hole if your proxy is on loopback. If nginx, Envoy, or a sidecar terminates traffic and forwards to PHP over 127.0.0.1, and that proxy is not in trusted_proxies, then $request->ip() is 127.0.0.1 for every external visitor. On v1.0.1 all of them are exempt from the blocklist — the filter silently stops filtering and nothing in the logs says so. Verify after upgrading: log $request->ip() for one external request and confirm it is the visitor's address, not loopback. This is the highest-risk interaction in the release.

You cannot opt out of the loopback exemption. It is not overridable via allowed_ips or any setting. If you have a genuine requirement to block localhost (multi-tenant host, shared container network), the package no longer supports it — you need an outer layer, or a fork.

Reverse-proxy visitors still carry their own address, but only if trusted proxies is right. The release note's claim that "this exempts no external traffic" is conditional on that config. Treat it as a deployment prerequisite and assert it in a test rather than trusting it.

Debugging a 403: the blocklist decision is User-Agent-driven, so start there — reproduce with curl -H 'User-Agent: Mozilla/5.0 ...' versus bare curl. If both 403, the request is not arriving as loopback and you are looking at an allowed_ips/proxy problem, not a blocklist problem. If bare curl passes from inside the container but fails from your laptop, that is the exemption working as designed.

phpstan-baseline.neon dropped from the archive is tooling-only. No runtime effect. It matters only if you vendor dependencies and run static analysis over vendor/, or if you had CI pinned to the shipped baseline — you may now see suppressed errors resurface against this package. Not a reason to hold the upgrade.

Extension point: the loopback check now runs before the blocklist, so any custom middleware you stack ahead of it that rewrites REMOTE_ADDR will defeat the exemption. Keep header/address manipulation in TrustProxies and nowhere else.