418 I'm a teapot: letting the app ban IPs across the whole cluster
Every Laravel app ends up with code that knows, for certain, that a request is malicious. Someone changed a value the browser never lets you change. Someone is working through a pile of stolen email links. A login script is still hammering away after twenty "too many requests" answers.
And then what? The app returns a 403 or a 429, the attacker shrugs and sends the next request, and every one of them still costs a PHP worker. Blocking in the app is the weakest place to block: by the time your middleware runs, you've already paid for the request.
What I want is this: the application decides, the edge enforces. The app recognises the attack. The ingress bans the IP, on every site in the cluster, before the next request reaches PHP. The question is how the app tells the edge, without an API call, a shared queue or another moving part.
The answer is a joke from 1998.
Why 418
418 I'm a teapot comes from RFC 2324, the Hyper Text Coffee Pot
Control Protocol, an April Fools' RFC. RFC 9110 now
marks 418 as reserved and unused: it must not be assigned to anything real, because too many implementations
already know the joke.
That makes it the perfect signal:
- Nothing else in the stack ever sends it. Not nginx, not Cloudflare, not PHP, not Laravel, not a load balancer. A 418 in the access log can only mean one thing: the app recognised an attack.
- It's already in the access logs, which every log pipeline reads anyway. The app doesn't call anything, so there's nothing new that can time out or fail.
- One exact filter,
status == 418, with no paths to list and no patterns to keep up to date. A new attack type is a newifin the app; the ban rule never changes.
Check your own logs first. If anything already answers 418, for example an upstream API you proxy, pick another unused code. The idea doesn't depend on the number, only on nothing else using it.
The shape of it

I use CrowdSec on Kubernetes: agents read the ingress controllers' access logs, the
central API stores the decisions, and a bouncer inside the ingress controller refuses banned IPs. The bouncer sees
the real client address (with realip set up for your CDN), so a ban works through Cloudflare and on direct
hostnames alike. The same idea works with fail2ban on one box: a filter for 418 in the nginx log and a ban
action.
The app side: one helper
Every ban signal goes through one place, so they all log the same way:
<?php
namespace App\Security;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;
/**
* The application's ban signal. Answer 418 only to a request that a real browser
* never makes. The cluster bans the client IP on the first 418 it sees in the
* access logs, on every site at once.
*/
final class Teapot
{
public static function brew(Request $request, string $reason): never
{
Log::warning("[HACK] {$reason}", [
'ip' => $request->ip(),
'method' => $request->method(),
'path' => $request->path(),
'user_agent' => $request->userAgent(),
]);
abort(418);
}
}
The [HACK] prefix makes the reasons easy to find later. The ban itself only needs the 418, but when someone asks
"why was I blocked?", the log line answers it.
The rule for when to call it is strict: only for a request a real browser never makes. Not "suspicious". Not "unusual". Impossible for a person clicking around your site. Everything below follows that rule.
Case 1: parameters that can't change
Some values only change if someone edits the request by hand. Livewire is a good example: a #[Locked] property
can't be updated, and Livewire's JavaScript only calls methods that exist on the component. If either happens,
someone is replaying edited payloads:
// bootstrap/app.php: a tampered Livewire request. A browser running Livewire's own
// JavaScript can't change a #[Locked] property or call a method that doesn't exist.
use App\Security\Teapot;
use Illuminate\Http\Request;
use Livewire\Exceptions\MethodNotFoundException;
use Livewire\Features\SupportLockedProperties\CannotUpdateLockedPropertyException;
->withExceptions(function (Exceptions $exceptions) {
$exceptions->render(fn (CannotUpdateLockedPropertyException $e, Request $request) =>
Teapot::brew($request, 'Livewire: locked property updated'));
$exceptions->render(fn (MethodNotFoundException $e, Request $request) =>
Teapot::brew($request, 'Livewire: unknown method called'));
})
Payment flows have them too. During Apple Pay merchant validation, Apple's own JavaScript hands the page a
validation URL, and it's always an https URL on apple.com. Your server then calls that URL with your merchant
certificate. Anything else in that field means someone is trying to make your server call their URL, which is a
textbook SSRF attempt:
// A controller: Apple Pay merchant validation. Apple's JavaScript only ever hands
// the page an https URL on apple.com, so anything else was typed by a person.
public function validateMerchant(Request $request)
{
$url = (string) $request->input('validationUrl');
$host = parse_url($url, PHP_URL_HOST);
if (parse_url($url, PHP_URL_SCHEME) !== 'https' || ! is_string($host)
|| ($host !== 'apple.com' && ! str_ends_with($host, '.apple.com'))) {
Teapot::brew($request, 'Apple Pay: validationUrl outside apple.com');
}
// ... call Apple with the merchant certificate
}
The same goes for signed hidden fields, IDs that belong to another account, or enum values that aren't in the
<select>. If the UI can't produce it, the person sending it isn't using the UI.
Case 2: stolen email links being walked through
Login links, unsubscribe links, email confirmations: signed URLs that say "whoever holds this link is this user". When a mailbox leaks, or someone scrapes links out of forwarded emails, they get tried one after another, often with the signature or the ID edited to see what else opens.
One bad signature from an IP is nothing. Email clients mangle links, people copy half a URL, links expire. So the app counts, and only a pattern turns into a 418:
<?php
namespace App\Http\Middleware;
use App\Security\Teapot;
use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\RateLimiter;
/**
* Signed links from emails: login links, unsubscribe, email confirmation.
* One bad signature is a mangled or expired link. Many from one IP is someone
* walking through links they stole or guessed.
*/
final class SignedLinks
{
private const MAX_BAD = 5;
private const WINDOW = 600; // seconds
public function handle(Request $request, Closure $next)
{
if ($request->hasValidSignature()) {
return $next($request);
}
$key = 'bad-signature:'.$request->ip();
RateLimiter::hit($key, self::WINDOW);
if (RateLimiter::attempts($key) > self::MAX_BAD) {
Teapot::brew($request, 'Signed links: '.RateLimiter::attempts($key).' bad signatures');
}
// A normal user gets the normal page: "this link has expired, request a new one".
abort(403);
}
}
A real person with a broken link sees the normal "this link has expired" page. Somebody on their sixth bad signature in ten minutes gets the teapot, and from then on gets nothing from any site in the cluster.
The counting has to happen in the app, not in the log pipeline. Requests are spread over several ingress pods,
and each CrowdSec agent only sees the logs of its own node, so a "5 bad signatures in 10 minutes" bucket on one
agent rarely fills. The app has a shared cache (Redis, or the database), so it sees all of them. That's also why
the CrowdSec scenario is a trigger: the app already did the counting, so the first 418 bans.
Case 3: brute force that ignores 429
Rate-limiting the login form is standard. But a 429 only works on clients that listen. A person who gets "too many attempts, try again in a minute" waits. A credential-stuffing script just keeps sending passwords, happily collecting 429s, waiting for you to reset the counter.
So count what happens after the 429:
<?php
namespace App\Http\Controllers\Auth;
use App\Security\Teapot;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\RateLimiter;
use Illuminate\Validation\ValidationException;
final class LoginController
{
public function store(Request $request)
{
$key = 'login:'.mb_strtolower((string) $request->input('email')).'|'.$request->ip();
if (RateLimiter::tooManyAttempts($key, 5)) {
// We already said "too many attempts". A person waits; a script keeps going.
$ignored = 'login-ignored-429:'.$request->ip();
RateLimiter::hit($ignored, 900);
if (RateLimiter::attempts($ignored) > 20) {
Teapot::brew($request, 'Login: kept going after 429');
}
abort(429, 'Too many login attempts. Try again in '.RateLimiter::availableIn($key).' seconds.');
}
if (! Auth::attempt($request->only('email', 'password'))) {
RateLimiter::hit($key, 60);
throw ValidationException::withMessages(['email' => __('auth.failed')]);
}
RateLimiter::clear($key);
$request->session()->regenerate();
return redirect()->intended();
}
}
Five failed logins get a 429. Twenty more attempts while being told to stop get the teapot. No browser and no human does that.
The cluster side
The whole CrowdSec configuration for this is one scenario, one ban profile and a whitelist:
# CrowdSec Helm chart values (crowdsec/crowdsec)
config:
scenarios:
# Any 418 in the ingress access logs bans the client IP: nothing else in the
# stack answers 418, so there's no path to match and no threshold to tune.
attack-signal.yaml: |
type: trigger
name: local/attack-signal
description: "The application answered 418: an attack it recognised"
filter: "evt.Meta.service == 'http' && evt.Meta.http_status == '418'"
groupby: evt.Meta.source_ip
blackhole: 5m
labels:
service: http
confidence: 3
spoofable: 0
behavior: "http:exploit"
label: "Attack recognised by the application"
remediation: true
# 4 hours for the first ban, 4 more for every repeat, capped at 7 days.
profiles.yaml: |
name: default_ip_remediation
filters:
- Alert.Remediation == true && Alert.GetScope() == "Ip"
decisions:
- type: ban
duration: 4h
duration_expr: "GetDecisionsCount(Alert.GetValue()) >= 41 ? '168h' : Sprintf('%dh', (GetDecisionsCount(Alert.GetValue()) + 1) * 4)"
on_success: break
parsers:
s02-enrich:
# Never ban yourself: your NAT gateways, office, payment provider callbacks.
whitelist.yaml: |
name: local/whitelist
description: "IPs that must never be banned"
whitelist:
reason: "own infrastructure"
ip:
- "203.0.113.10"
cidr:
- "10.0.0.0/16"
type: triggerbans on the first 418. The app already made the decision; CrowdSec only carries it out.- Bans grow on repeats: 4 hours, then 8, then 12, up to a week. Most bots move on after the first one. The ones that come back after every ban stay blocked for most of the time.
- The whitelist matters. Your own NAT gateways, so pods calling public hostnames never ban the cluster. Your office. Payment provider callbacks. Anything that must never be locked out, whatever the app says.
Unbanning someone is one command, and it's live within seconds:
cscli decisions delete --ip 198.51.100.7
Things to be careful about
- Shared IPs. Mobile carriers and corporate networks put thousands of people behind one address (CGNAT). A ban hits all of them. That's why the rule is "a browser never does this", and why the thresholds in cases 2 and 3 are generous. Ban durations that start short limit the damage of a mistake.
- Don't 418 anything a buggy client might do. A broken mobile app version, a retrying SDK, a monitoring
probe. If you're not sure, log
[HACK]with a 403 for a week, read the log, and switch it to 418 when only attackers show up. - Don't explain yourself to the attacker. The 418 body is empty, and the ban page is a plain 403. The reason lives in your logs, not in the response.
- Watch it. A dashboard of bans per scenario and per country, and an alert when the agents stop parsing logs. A ban system that silently stopped working looks exactly like one with nothing to ban.
Why I like it
It's a tiny contract between two layers that otherwise know nothing about each other. The app doesn't know CrowdSec exists. CrowdSec doesn't know what Livewire, Apple Pay or a signed URL is. One status code, one log line, and the most expensive requests in the cluster turn into a 403 at the ingress.
The teapot finally has a job.