Introducing Laravel Teapot

A few years ago I wrote about a simple idea: instead of maintaining huge fail2ban regexes for every weird scanner path, let your Laravel app return a very specific HTTP status code when a request clearly looks like automated probing, then let fail2ban ban the IP based on that status code.

Now that approach is packaged as aureola/laravel-teapot.

The idea in one paragraph

Vulnerability scanners usually poke the same places again and again: .env, .git, wp-admin, and similar. The package lets you define a list of path patterns, and if a request matches, Laravel responds with HTTP 418. Your web server logs that response, and fail2ban bans the IP.

How Laravel Teapot works

• You define path patterns in config/teapot.php.

• If the request path matches, the app returns 418 using a fallback for unmatched URLs.

• fail2ban watches your access log for 418 and bans the IP.

This is basically the same mechanism from my 2021 post, just turned into a reusable, tested package instead of copy paste app code.

Installation and Setup

Install:

composer require aureola/laravel-teapot

Publish config:

php artisan vendor:publish --tag=teapot-config

Then add your patterns, for example:

• \.env

• \.git\/

• wp-admin

For fail2ban, the repo includes ready-made configs for Nginx and Apache in fail2ban/ (copy filter and jail files into /etc/fail2ban/ and restart fail2ban).

When to use this method

Use Laravel Teapot when:

• You host multiple sites on one server and want different “trap paths” per app without juggling a monster global fail2ban regex set.

• You want the behavior versioned, testable, deployable: configure once in your app, then just ship updates.

• You prefer app-level clarity over maintaining increasingly complex fail2ban filters.

Use plain fail2ban when:

• You mainly need classic rules like SSH brute force, repeated login failures, rate-limiting, or other patterns that are already well covered by standard fail2ban jails.

• You want protection that is fully independent from the application layer (for example, you also want to ban before PHP even runs).

Pros

• Works well with multiple sites on one server (different configs per site).

• Testable and deployable: set up once, then update your application.

• Easier to maintain than complicated fail2ban filters.

Cons and caveats

• You can accidentally ban Googlebot (or other legit crawlers) if your domain previously hosted WordPress and old links like wp-admin are still being hit. Be careful with broad patterns and consider allowing known good bots at the web server or fail2ban level.

• An unusual HTTP code like 418 can confuse some CDNs, WAFs, or monitoring assumptions. Make sure your edge layer treats it as a normal response and still logs it correctly.

Small practical tips

• Start with high-confidence patterns like \.env and \.git\/ before adding broader ones like wp-admin.

• Keep an eye on your access log for a day or two after rollout, then adjust the patterns.

• If you run Statamic, the package automatically integrates by attaching its check middleware to Statamic’s web middleware group.