# 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](deployment.en.md#token-based-node-enrollment-recommended) is
enough — particularly relevant for the community and services-company
cases, where the servers belong to different parties.

## Where to go next

- [Installation](installation.en.md) — development setup, first
  production node.
- [Production deployment](deployment.en.md) — master, token-based node
  enrollment, databases, reverse proxy, alternatives to systemd.
- [Reference](reference.en.md) — MQTT topics, master commands, custom
  fail2ban jails.