Download the PHP package justinholtweb/craft-fail2ban without Composer

Fail2Ban for Craft CMS

Your web server log shows a 200 for a wrong password and a 200 for a right one. fail2ban is very good at banning addresses and has no way to tell those apart. Craft knows the difference.

This plugin says it out loud — in the format fail2ban already understands — and lets the firewall do the banning, at the edge, before PHP is involved at all.

It is the Craft equivalent of wp-fail2ban, including the log-line convention — craft(host)[pid]: is the shape fail2ban's own common.conf already parses, and it is deliberately the same shape wp(host)[pid]: has, so an admin who runs both knows what these lines are before reading a word of documentation.

Requirements

Craft CMS 5.3+ and PHP 8.2+. No runtime dependencies, no build step, no outbound requests.

fail2ban itself is optional. See Without fail2ban.

Installation

Setting it up

1. Settings → Plugins → Fail2Ban. The defaults are working defaults: every authentication event that matters is on, lines go to the auth syslog facility and to storage/logs/fail2ban.log, and the client address is taken from the socket.

2. Fail2Ban → Setup. Copy the generated files onto the machine running fail2ban:

   With shell access on the Craft server, sudo php craft fail2ban/configs/write does the same thing.

3. Prove it works, before you need it to:

What it logs

Every event carries a jail, or none. The jail is what a ban is counted against.

Lite

Pro

path.probe is the one with no WordPress equivalent, for the obvious reason: on a Craft site, /wp-login.php, /xmlrpc.php, /.env and /vendor/phpunit are requests nobody makes by accident. The default list has thirty-odd of them, and paths are matched as whole segments, so /news/how-we-left-wp-admin-behind is somebody reading an article.

The jails

The numbers live in the plugin's settings and are written into both the generated jail.local and the built-in blocker, so the firewall and the plugin cannot come to different conclusions about the same traffic.

Blocked usernames

Craft has never shipped an account called admin, so a login offering that name did not come from anyone who has ever seen your site — it came from a list.

There are two readings of a list like that, and the difference between them is a lockout:

• "These names do not exist here." The default. The event fires only when nothing matched the name, so an install whose administrator genuinely is called admin is never touched by the admin entry.
• "These names must never sign in." enforceBlockedUsernames, off until you turn it on. A refused login fails exactly the way a wrong password fails, so nothing is confirmed to whoever is guessing. The settings screen names every real account the switch would shut out before you throw it.

Who is asking

Whatever address this plugin names in a log line can end up dropped at your firewall. So:

Proxy headers are not trusted by default. X-Forwarded-For is a string the client picked, and a plugin that logged it out of the box would hand anyone on the internet a way to get an address of their choosing banned — your office, your monitoring, Googlebot — by typing it into a header.

Turn on Trust forwarded-for headers only if the site genuinely sits behind a proxy you control, and then list the proxies. The chain is then read right to left, discarding your own hops and stopping at the first address that is not one of them.

ignoreIps is exempt from logging and from banning, and is written into the generated jail as ignoreip, so the plugin and fail2ban agree about who is exempt rather than each keeping a list.

Privacy

Turn on Hash usernames in the log and the log channels get a stable, keyed, one-way hash instead of a name. A jail can still count five failures against one account; /var/log stops being a directory of your customers' email addresses. The control panel keeps the real name.

Query-string values are never logged — only the parameter names — because a scanner's query string is frequently the payload, and a live password-reset token is frequently in it.

Without fail2ban

Plenty of Craft sites live on hosting with no shell, where the log this plugin writes has no reader. Pro's built-in blocker enforces the same jails in PHP: one indexed lookup at EVENT_BEFORE_REQUEST, and a 403 for anything already banned.

Leave it off wherever fail2ban can be run. A firewall drop costs the attacker a TCP timeout and costs you one iptables rule; this costs a database read on every request and still hands PHP-FPM a worker for every attempt.

Raising your own events

The interesting security events on a real site are not all Craft's.

They go through the same channels, into the same jails, with the same exemptions.

To filter or veto events in PHP:

Console

Why the filters are generated

Every hand-written fail2ban integration ends up in the same state: the application changed a log line, the filter did not, and because a jail that matches nothing looks exactly like a site nobody is attacking, it is discovered months later.

Here there is nothing to keep in step. Each event type owns one template — 'Authentication failure for {user} from {ip}' — and that single string renders the log line and compiles the failregex. php craft fail2ban/configs/verify proves it, by generating a line for every event type and matching the generated pattern against it. Put it in CI if you like.

Editions

Lite is free. Pro is $59, with an optional $29/year renewal for updates.

Lite is the whole authentication story: every event in the first table, all three channels, the blocked-username list, the generated filters and jails, the verification, and the console commands.

Pro adds user enumeration, path probes, HTTP status logging, GraphQL failures, registrations, the built-in blocker and ban notifications.

Licence

Commercial, one licence per Craft installation. See LICENSE.md.