Ce guide décrit un agent externe qui récupère les publications HTTP de l'application et les applique à un pare-feu local.
Il ne s'agit pas d'une fonctionnalité REST de l'application : les routes Phase 19 sont des fichiers publics, hors /api/v1, et ne nécessitent ni clé API ni session.
1. Endpoints consommés
Pour un profil all :
GET /blocklists/all.txt
GET /blocklists/all/ipv4.txt
GET /blocklists/all/ipv6.txt
Même modèle pour ssh, web, mail, rdp, tcp-22, tcp-25, tcp-443, tcp-3389 ou tout profil personnalisé publié.
Le synchroniseur fourni utilise de préférence les représentations séparées :
/blocklists/{slug}/ipv4.txt
/blocklists/{slug}/ipv6.txt
Cela évite de devoir séparer les familles côté client avant de remplir les structures du pare-feu.
2. Contrat HTTP à exploiter
Une publication valide renvoie :
- HTTP
200; Content-Type: text/plain; charset=utf-8;- une IP ou un CIDR par ligne ;
ETag;Last-Modified.
Une liste vide en HTTP 200 est valide.
Pour revalider sans retélécharger :
If-None-Match: "etag-recu"
Une publication inchangée peut alors renvoyer HTTP 304 sans corps.
Cas d'erreur à traiter explicitement :
404: profil/publication absente ;503: publication présente mais illisible ou corrompue côté serveur ;- erreur réseau / TLS ;
- contenu non conforme côté client.
3. Politique recommandée : last-known-good
Ne videz jamais automatiquement le pare-feu parce que le téléchargement échoue.
Comportement recommandé :
- conserver la version active ;
- télécharger/revalider la nouvelle publication ;
- valider tout le contenu ;
- préparer une nouvelle structure de pare-feu hors chemin actif ;
- basculer seulement si toute la préparation réussit ;
- en cas d'erreur, conserver l'ancienne version.
Cette politique est parfois appelée fail-static ou last-known-good. Elle est préférable ici à :
- un « fail-open » qui supprimerait la protection lors d'une panne du serveur de listes ;
- un « fail-closed » extrême qui bloquerait tout le trafic si la source est indisponible.
4. Validation locale avant application
Même si l'application vérifie l'intégrité de sa publication avant de la servir, le client doit refuser un contenu inattendu.
Le script fourni vérifie notamment :
- UTF-8 valide ;
- pas de NUL ;
- pas de commentaires ;
- pas d'espaces parasites ;
- syntaxe IP/CIDR valide ;
- famille correcte pour le fichier IPv4/IPv6 ;
- CIDR normalisé ;
- maximum local de 100 000 entrées par famille ;
- taille maximale locale de 8 Mio.
Une validation échouée ne modifie pas le pare-feu.
5. Installation Linux
install -m 0755 sync/blocklist-sync.py /usr/local/sbin/blocklist-sync.py
install -d -m 0700 /etc/blocklist-sync /var/lib/blocklist-sync
Choisir ensuite un backend.
nftables
install -m 0600 sync/config-nftables.json.example /etc/blocklist-sync/config.json
ipset
install -m 0600 sync/config-ipset.json.example /etc/blocklist-sync/config.json
Modifier au minimum :
{
"base_url": "https://blocklist.example.net",
"slug": "all"
}
Aucune clé API n'est nécessaire pour Phase 19.
6. Premier test sans planification
Avant d'activer le timer :
/usr/local/sbin/blocklist-sync.py --config /etc/blocklist-sync/config.json --verbose
Puis inspecter le backend :
nft list table inet blocklist
ou :
ipset list blocklist4
ipset list blocklist6
7. ETag et cache local
Le synchroniseur stocke :
/var/lib/blocklist-sync/{slug}-4.txt
/var/lib/blocklist-sync/{slug}-6.txt
/var/lib/blocklist-sync/{slug}-http.json
Le fichier d'état conserve notamment les ETags précédents. Lors du prochain passage :
- si le serveur répond 304, le cache local validé est réutilisé ;
- si le serveur répond 200, la nouvelle représentation est validée puis mise en cache ;
- si l'une des familles échoue, aucune mise à jour de pare-feu n'est appliquée.
8. systemd
Installer :
install -m 0644 systemd/blocklist-sync.service /etc/systemd/system/blocklist-sync.service
install -m 0644 systemd/blocklist-sync.timer /etc/systemd/system/blocklist-sync.timer
systemctl daemon-reload
systemctl enable --now blocklist-sync.timer
Vérifier :
systemctl status blocklist-sync.timer
systemctl list-timers blocklist-sync.timer
journalctl -u blocklist-sync.service
Le timer d'exemple effectue une revalidation toutes les 5 minutes avec un léger délai aléatoire. Ce rythme est un choix client, pas une exigence de l'application. Grâce à ETag, une liste inchangée produit normalement très peu de trafic.
9. Mise à jour manuelle
systemctl start blocklist-sync.service
journalctl -u blocklist-sync.service -n 50 --no-pager
10. Changer de profil
Pour ne bloquer que les réseaux publiés pour SSH :
{
"base_url": "https://blocklist.example.net",
"slug": "ssh",
"backend": "nftables"
}
Pour un serveur mail, mail peut être plus adapté que all selon votre politique de sécurité.
Attention : le profil reflète les décisions et présences sélectionnées lors de la génération, après Never Block/allowlist. Les reports seuls ne sont jamais inclus directement dans les fichiers générés.
11. Publication et fraîcheur
Les exports sont des instantanés. Une modification de profil, de bloc, de protection ou d'allowlist dans l'application ne change pas la ressource servie tant qu'une nouvelle génération/publication n'a pas été effectuée.
Le synchroniseur ne doit donc jamais supposer que Phase 19 est une vue SQL temps réel.
12. TLS
En production :
- publier l'application en HTTPS ;
- utiliser une chaîne de certification approuvée par le système ;
- ne pas désactiver la vérification TLS ;
- ne pas permettre de redirection vers HTTP dans une implémentation personnalisée ;
- utiliser un DNS et un certificat correspondant au nom de service attendu.
Le fichier d'exemple refuse HTTP par défaut. allow_http=true ne doit servir qu'en laboratoire ou sur un réseau de confiance explicitement assumé.
13. Rollback
Le rollback normal consiste à conserver la dernière structure active en cas d'échec de synchronisation.
Pour revenir manuellement à une ancienne liste, gardez vos propres snapshots côté client ou récupérez une publication précédente depuis votre système de sauvegarde. L'API publique ne fournit pas de route d'historique des versions publiées.