Laravel Teapot Laravel Package

Product Decisions This Supports

• Feature/roadmap input for security hardening: Provides a cheap, well-scoped way to add a scanner-trap endpoint ("teapot" returning HTTP 418) to a Laravel app, useful for detection/observability rather than enforcement. It supports a roadmap item around defense-in-depth and abuse detection without committing to a WAF contract.
• Build vs. buy: The package's real value is as a reference implementation of a pattern (a 418 canary route + structured logging + fail2ban filter). Because the code surface is tiny, the practical decision is often "adopt now, or copy the ~dozen lines in-house later." Treat it as an accelerant, not a platform.
• Use cases it enables: (1) trap scanners probing /wp-login.php, /admin, /.env, /.git; (2) emit parseable log lines for fail2ban auto-banning; (3) produce attacker-IP telemetry for security dashboards; (4) demonstrate "active defense" posture for audits/compliance narratives.
• Signals for other decisions: Whether your app needs edge-level bot protection (WAF/CDN) versus app-level tarpitting; whether fail2ban is already in the operational stack (if not, this package's value drops sharply).

When to Consider This Package

Adopt it when:

• You run a public-facing Laravel app and want a low-effort, low-cost canary that surfaces probe traffic.
• You already have (or are willing to add) fail2ban and are comfortable with log-parsing pipelines.
• You want a fast proof-of-concept for scanner detection before investing in a WAF.
• You can pin, vendor, or fork a small, low-maturity dependency (2 stars, 0 dependents, ~0.01 score) — i.e., you're comfortable owning it if upstream goes quiet.
• You accept it as complementary to, not a replacement for, rate limiting, auth hardening, and an edge WAF.

Look elsewhere when:

• You need production-grade threat intelligence, SLAs, or a maintained/audited package.
• You have no fail2ban or log-shipping infrastructure — the integration payoff largely disappears.
• You already sit behind a mature WAF/CDN that covers scanner detection; the marginal value is low.
• You need precise blocking semantics — a 418 tarpit detects, it doesn't reliably prevent; combine with real controls.
• Policy forbids pulling low-popularity security-adjacent dependencies without heavy review.

How to Pitch It (Stakeholders)

For executives: A near-zero-cost, low-risk "active defense" add-on for our Laravel app. It exposes a tripwire endpoint that scanners will hit; each hit is logged and can auto-ban the source IP via fail2ban. It's a detection layer, not a silver bullet — it complements (doesn't replace) our WAF and auth hardening. Expected outcome: earlier visibility into probing activity and a small, measurable drop in nuisance traffic. Because the package is tiny and early-stage, we should pin or vendor it to avoid maintenance risk.

For engineering: Minimal integration — a route + middleware returning 418 and emitting a structured log line, plus a fail2ban filter.d/jail.local entry. The package itself is small enough to audit or reimplement in an afternoon, so treat it as a scoped spike: wire it behind a feature flag, measure log volume and false positives (careful not to ban legitimate clients that trip the canary), and only promote to production after validating ban accuracy.