mirror of
https://github.com/deunix-educ/Fail2banMqttActionBanishment.git
synced 2026-08-24 03:11:58 +02:00
61 lines
2.8 KiB
Markdown
61 lines
2.8 KiB
Markdown
# 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.
|