Fail2banMqttActionBanishment/docs/index.en.md

Fail2banActionBanisher

Distributed malicious-host banishing system built on fail2ban and iptables, with event propagation over MQTT.

Each node detects and bans locally (fail2ban + iptables), publishes the event to a local Mosquitto broker, then relays it to a private master broker (mTLS). The master centralizes the decision (multi-node correlation, global recidive detection, shared reputation) and republishes the actions to be executed to all subscribed nodes.

Target machine: Debian 13 VPS.

Architecture (overview)

[node] fail2ban/iptables → local mosquitto (1883) → master mosquitto (8883, TLS)
                                                              │
                                                    decision / correlation
                                                              │
[node] ◄──────────────── MQTT action (BAN, SYNC_BAN, UNBAN, ...) ◄──────────

A Django dashboard (real-time, WebSocket) runs on every node and on the master, with an aggregated multi-node view on the master side.

Use cases

The master/nodes model doesn't assume any ownership relationship between the protected servers — only that they share a common decision authority. That makes the architecture relevant beyond a single operator running their own VPSes:

• A set of sites (several VPSes run by the same operator, each hosting one or more services): an IP attacking one site gets banned everywhere via SYNC_BAN, without manual per-site monitoring.
• A community (several independent administrators, each responsible for their own server, who agree to pool their detections): every member keeps their own node and their own local fail2ban — only ban propagation is shared through the common master. No member gets SSH access to another member's server.
• An IT services company managing several clients' sites: a centralized master gives an aggregated view (jail/country counters, per-node history, per-client aliases) without mixing client data — each node only sees its own events, the master sees everything.

In all three cases, a new server joins the set without ever handing out SSH access to the others: a single-use token-based enrollment is enough — particularly relevant for the community and services-company cases, where the servers belong to different parties.

Where to go next

• Installation — development setup, first production node.
• Production deployment — master, token-based node enrollment, databases, reverse proxy, alternatives to systemd.
• Reference — MQTT topics, master commands, custom fail2ban jails.