README

Responds with HTTP 418 I'm a Teapot when a request hits a teapot path. Use with fail2ban to ban those IPs.

How it works

You list path patterns in config/teapot.php.
If the request path matches, the app returns 418 (via the fallback for unmatched URLs).
Your server logs 418; fail2ban reads the log and bans the IP.

Installation

composer require aureola/laravel-teapot

Nothing else to do; the package registers itself.

Configuration

Publish and edit the config:

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

paths is an array of regex alternatives matched from the start of the request path, case-insensitively. Laravel supplies the path without a leading slash. Escape special characters for literals: \. for a dot, \/ for a slash.

'paths' => [
    '(?:.*\/)?\.env(?:\..*)?$',
    '(?:.*\/)?\.git(?:\/|$)',
    '(?:.*\/)?wp-login\.php$',
    // ...
],

ignore_logged_in – when true, authenticated users are never treated as teapot hits.

Choosing paths safely

The bundled defaults deliberately target high-confidence vulnerability probes. A teapot response is commonly connected to a one-hit fail2ban jail, so broad extension patterns can ban legitimate visitors and crawlers.

Avoid patterns that classify all archives, database files, or standardized public endpoints as attacks. In particular, routes such as /.well-known/*, /robots.txt, /security.txt, /crossdomain.xml, and /sitemap.xml.gz can be legitimate. Prefer a sensitive filename plus an end anchor, such as backup\.sql$, instead of every .*\.sql request.

Published configuration belongs to the application and is not overwritten by package updates. Review an application's existing config/teapot.php when adopting newer defaults, and add broader rules only when they are safe for that application's routes and files.

Fail2ban

This repo includes fail2ban configs in fail2ban/:

Nginx: copy fail2ban/filter.d/nginx-teapot.conf and fail2ban/jail.d/nginx-teapot.conf to /etc/fail2ban/filter.d/ and /etc/fail2ban/jail.d/.
Apache: copy fail2ban/filter.d/apache-teapot.conf and fail2ban/jail.d/apache-teapot.conf instead. Adjust logpath in the jail if your access log is elsewhere.

Then restart fail2ban: sudo fail2ban-client restart

What the package registers

A fallback for unmatched URLs: 418 if the path matches a teapot pattern, 404 otherwise.

Statamic Compatibility

This package is compatible with Statamic CMS. When Statamic is installed, the package automatically adds the CheckTeapot middleware to the statamic.web middleware group, ensuring teapot paths are checked on all Statamic web requests.

Requirements

PHP 8.1+ (PHP 8.3+ for Laravel 13)
Laravel 10.x, 11.x, 12.x, or 13.x

aureola / laravel-teapot

Package info

Security

Statistics