Scanner Ban Bundle Laravel Package

Product Decisions This Supports

• Build vs. buy for edge request filtering. This package covers a narrow but real slice of the "who gets to talk to our app" problem — User-Agent blocklisting plus an IP allowlist — inside the Laravel request lifecycle. That is enough to avoid writing and maintaining custom middleware for bot/scanner noise, but not enough to replace a WAF, CDN ruleset, or API gateway. PM decision: adopt as a cheap first line of defense, keep the WAF budget line intact.
• Deployment and reliability roadmap. The headline change in v1.0.1 is a product decision dressed as a bug fix: loopback traffic is now unconditionally allowed regardless of allowed_ips. Without it, post-deployment health checks and probes hitting http://localhost return 403, and a healthy release is reported as a failed deployment. If your roadmap includes canary releases, blue/green deploys, or automated rollback on health-check failure, this behavior is a prerequisite, not a nicety. Treat "loopback is invariant" as a stated requirement in any deployment-automation epic.
• Support-cost and incident-response planning. The failure mode this fixes is one of the most expensive kinds of false positive: an alert that fires when nothing is actually wrong. Engineering time spent triaging phantom deploy failures is a recurring cost that is invisible on a roadmap and easy to under-budget. This release removes one class of that noise.
• Use cases this reasonably serves. Internal tools and admin panels behind an IP allowlist; small-to-mid Laravel apps fending off commodity scanners and misbehaving crawlers; staging environments that should only be reachable from known addresses.
• Use cases this should not be sold against. It is not authentication, not rate limiting, and not a substitute for per-user authorization. User-Agent blocklists are trivially spoofed by any motivated actor — position it as hygiene, not as a security control you would cite in a compliance document.
• Configuration-surface discipline. The loopback change is explicitly framed as "an invariant rather than a setting." That is a good signal for a PM: the maintainer is choosing safe-by-default behavior over knobs. Support this direction, and push back on future requests to make loopback configurable — every added toggle is a future misconfiguration and a future support ticket.

When to Consider This Package

Consider adoption when:

• You run Laravel and want request filtering enforced in-process, with no new infrastructure, no vendor contract, and no DNS or proxy changes.
• Your threat model is opportunistic traffic — scanners, junk User-Agents, crawlers hitting endpoints they have no business hitting — rather than targeted adversaries.
• You already set framework.trusted_proxies, or are willing to. This is a hard dependency of the package's design: it assumes real client addresses are recovered correctly behind a reverse proxy. If your proxy setup is incomplete or unknown, the allowlist will silently evaluate the proxy's address and the whole model degrades.
• Your deployment pipeline includes health checks or probes that originate from inside the container. v1.0.1 makes this work out of the box; earlier behavior required you to remember to include loopback in allowed_ips, which is exactly the kind of tribal knowledge that breaks during an on-call handoff.
• You want the behavior to be boring and stable. The release is small, scoped, and non-breaking.

Look elsewhere when:

• You need geo-blocking, rate limiting, bot scoring, TLS termination, or DDoS absorption. Those belong at the edge, not in PHP middleware — doing them in-process means you pay CPU for every blocked request and you cannot absorb volumetric attacks at all.
• You need auditable, compliance-grade access control. A spoofable header check will not survive a security review; you want network-level controls with logging you can hand to an auditor.
• You operate a multi-tenant or high-traffic service where per-request middleware overhead matters at the margin.
• You are not on Laravel, or you are on a version this package does not track.

How to Pitch It (Stakeholders)

For executives: This is a small, free, in-application filter that keeps junk traffic and scanners away from our Laravel services without adding a vendor or infrastructure. The latest release fixes a specific and costly failure: automated post-deployment health checks were being blocked by the filter itself, so healthy releases could be reported as failed deployments. That is now fixed by design — internal traffic is always permitted, external traffic is still filtered exactly as before. No breaking changes, no configuration work required on our side, and no change to our security posture. It does not replace our WAF or our authentication; it reduces noise in front of them.

For engineering: v1.0.1 makes loopback an invariant: requests from inside the container — health checks, post-deploy probes, the app calling itself — are allowed regardless of what allowed_ips contains. These arrive with a curl or absent User-Agent, which the blocklist would otherwise reject, so a probe against http://localhost returned 403 and failed the deploy while the app was healthy. This exempts no external traffic, because visitors through the reverse proxy carry their own address as long as framework.trusted_proxies is configured — which the package already requires. The release also drops phpstan-baseline.neon from the distribution archive, joining the other tooling files already excluded; its only referent, phpstan.neon.dist, was excluded already, so nothing in the runtime changes. Upgrade is safe: patch release, no API or config changes. Two things to confirm on our side before rollout: that framework.trusted_proxies is correctly set in every environment (otherwise the allowlist evaluates the proxy's address), and that no environment relied on the old behavior of blocking loopback — which would only ever have been accidental.