First commit

docs/reference.md

@@ -0,0 +1,61 @@
+# 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.