# Référence

## Topics MQTT

| Topic | Sens | Rôle |
|---|---|---|
| `fail2ban/<noeud>/ban` | noeud → master | événement de ban/notice publié par ce noeud |
| `fail2ban/<noeud>/heartbeat` | noeud → master | preuve de vie périodique (indépendante de toute activité de ban) |
| `fail2ban/<noeud>/ack` | noeud → master | accusé de réception après exécution d'une commande reçue du master |
| `fail2ban/<noeud>/action` | master → noeud | commande adressée spécifiquement à ce noeud |
| `fail2ban/broadcast/action` | master → tous les noeuds | commande diffusée à tous les noeuds abonnés |
| `fail2ban/broadcast/roster` | master → tous les noeuds | liste des noeuds connus + compteurs jail/pays globaux, périodique |

`<noeud>` dans le segment de topic est le CN du certificat client mTLS
(imposé par l'ACL du broker) — l'identifiant interne du noeud
(`uuid.getnode()`) voyage dans le corps du message, pas dans le topic.

## Commandes du master

| Commande | Effet sur le noeud qui la reçoit | Déclenchement |
|---|---|---|
| `SYNC_BAN` | Ban total (toutes ports) via une jail dédiée | Automatique : le master publie systématiquement un `SYNC_BAN` pour chaque ban qu'il ingère |
| `ESCALATE` | Ban **permanent** via une jail dédiée | Automatique : le master corrèle — une IP bannie indépendamment sur plusieurs noeuds distincts en 24h déclenche une escalade |
| `BAN_ALLPORTS` | Ban total (toutes ports), même mécanisme que `SYNC_BAN` | Manuel (décision humaine ciblée) |
| `WHITELIST` | Ajout à `ignoreip` sur toutes les jails actives + débannit — en mémoire, non persistant | Manuel |
| `RATE_LIMIT` | Throttle (10 req/s, burst 20) au lieu d'un blocage total | Manuel — cas limite, faux positifs probables |
| `NOTIFY_ONLY` | Aucune action réseau, juste une notification visible sur le tableau de bord | Manuel — mode observation |
| `REPORT_ABUSE` | Signalement à AbuseIPDB — **pas diffusé aux noeuds**, soumis directement par le master (un rapport par IP suffit) | Manuel, dry-run tant que `ABUSEIPDB_ENABLED`/`ABUSEIPDB_API_KEY` ne sont pas configurés |

Les commandes manuelles se déclenchent sur le master, à la main :

```sh
emitter/.venv/bin/python emitter/manage.py publish_command WHITELIST 203.0.113.5
emitter/.venv/bin/python emitter/manage.py publish_command BAN_ALLPORTS 203.0.113.5
emitter/.venv/bin/python emitter/manage.py publish_command RATE_LIMIT 203.0.113.5
emitter/.venv/bin/python emitter/manage.py publish_command REPORT_ABUSE 203.0.113.5
```

La géolocalisation des IP bannies est automatique (asynchrone, dès
l'ingestion d'un événement) ; pour relancer celles restées sans
coordonnées (échec d'API, IP privée) :

```sh
emitter/.venv/bin/python emitter/manage.py retry_geolocation           # tous les événements non géolocalisés
emitter/.venv/bin/python emitter/manage.py retry_geolocation --ip <ip>  # une IP précise
```

## Jails fail2ban personnalisées

| Jail | Rôle |
|---|---|
| `emitter-admin-auth` | Verrouillage `/admin/` du tableau de bord (django-axes) → ban réseau |
| `master-sync` | Réception d'un `SYNC_BAN`/`BAN_ALLPORTS` — jamais déclenchée par un log, seulement par injection manuelle depuis le relais master |
| `master-ratelimit` | Réception d'un `RATE_LIMIT` |
| `master-escalate` | Réception d'un `ESCALATE` — ban permanent |

`emitter-admin-auth` suit un gabarit réutilisable
(`generic/fail2ban/jail.d/app-auth.conf.template` +
`generic/fail2ban/filter.d/app-auth.conf`) pour protéger de la même façon
n'importe quelle autre application exposée sur le même serveur, pas
seulement ce tableau de bord.