Miscellaneous » WP fail2ban Blocklist » How Blocklist works
TL;DR
The Blocklist add-on uses your site's existing Freemius connection to register with the network. The service then exchanges selected attack-source observations and current addresses through the WordPress REST API.
Received addresses are written as events for fail2ban and the host firewall to enforce. The standard WP fail2ban configuration can match them, while a custom Blocklist jail gives hosting providers a cleaner and more efficient path.
Update times move from one pass to the next because the service changes the order in which it visits participating sites. That variability is expected.
Register without another account
WP fail2ban already uses Freemius, so the Blocklist add-on uses the same connection to register your site with the network. You do not need to create or manage another account for the service.
Without the Freemius connection, the service cannot identify the participating site and Blocklist does not run.
Exchange selected warnings through WordPress
The service contacts each participant through the WordPress REST API. It collects source addresses from selected WP fail2ban security events and returns current addresses observed elsewhere that are still useful to the site.
The Blocklist route must remain reachable. If another security plugin or a server rule blocks it, the service cannot collect observations or deliver updates.
Blocklist shares the client address attached to the event. When your site is behind a proxy or CDN, correct client-IP handling prevents the network edge address being mistaken for the source.
More about getting the real client IP behind a proxy.
Receive the addresses your site can use
Blocklist selects results for each site rather than distributing one global list. It can avoid sending your site an address it has already observed locally and concentrate on current sources it has not yet seen.
That means two participating sites may receive different numbers of addresses and both be working normally. WP fail2ban Free receives a reduced set; Premium receives the full current Blocklist intelligence available to the site.
If a trusted campus, VPN, or shared network address should not be blocked on your site, the Blocklist ignore list can discard a matching address when it arrives.
Expect the update time to vary
The service processes participating sites in a new random order on each pass. That makes it harder to predict where an observation will be sent next and keeps distribution fair across the network. Your site will therefore receive updates at varying times rather than at the same minute every hour.
In normal operation, a warning about a newly active address will typically reach a site within about an hour, although an individual update can take closer to two. The moving schedule is expected behaviour rather than a sign that the service has stopped.
Give Blocklist a direct path to the firewall
The add-on writes each received address as a syslog event. The standard WP fail2ban configuration can match that event, but a custom Blocklist jail gives it a dedicated route to the firewall.
You can enable the custom jail in WordPress admin or define WP_FAIL2BAN_ADDON_BLOCKLIST_CUSTOM_JAIL. The add-on then changes the message format so only the wpf2b-blocklist-hard filter matches it. With maxretry = 1, each network warning can be enforced immediately instead of being mixed with another jail's threshold.
The jail and its firewall action do the blocking. If the host does not provide that enforcement path, the add-on can receive a warning but cannot stop the address before it reaches WordPress.
Once the firewall has blocked an address, any later connection attempt is rejected before WordPress runs. WP fail2ban records the Blocklist warning, but it cannot see whether the address subsequently tried to connect. Any evidence of that attempt belongs to the firewall, so WP fail2ban cannot honestly count how many attacks Blocklist prevented.
