API

Pare-feux

Filtrer ce qui entre et sort de vos machines : règles réutilisables, appliquées avant la machine, rattachées en un appel.

Un pare-feu est un jeu de règles réutilisable, en entrée comme en sortie, que vous rattachez à vos machines. Il est appliqué par notre réseau, avant que le trafic n'atteigne le système : rien à installer, il marche pareil sous Linux, Windows et BSD, et une erreur dans la machine ne peut pas le désactiver.

Ce qu'il filtre

  • Une machine sans pare-feu accepte tout le trafic entrant, comme avant.
  • Dès qu'une machine a au moins un pare-feu, le trafic entrant qu'aucune règle n'autorise est jeté. Les règles sont lues dans l'ordre, et la première qui correspond l'emporte.
  • Les réponses aux connexions de la machine passent toujours : mises à jour, téléchargements et appels d'API sortants ne demandent aucune règle.
  • Ses réseaux privés restent ouverts, sauf si un de ses pare-feux filtre aussi le réseau privé. La console web du panneau atteint la machine même si toutes les règles sont fermées.
  • Le trafic sortant est libre tant qu'aucun pare-feu de la machine n'a de règle de sortie.

Créer un pare-feu

Une règle autorise (ou refuse, voir plus bas) un protocole (tcp, udp, icmp pour le ping en IPv4 et IPv6, ou any), sur des ports ("22", "80,443", une plage "8000-8100" ; absent : tous les ports), depuis des sources (adresses ou plages IPv4 et IPv6 ; absent : partout).

bash
curl -s -X POST https://api.ffxf.net/v1/firewalls \
     -H "Authorization: Bearer $FFXF_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "name": "web",
           "rules": [
             {"protocol": "tcp", "ports": "22", "sources": ["203.0.113.0/24", "2001:db8::/32"], "description": "SSH depuis le bureau"},
             {"protocol": "tcp", "ports": "80,443", "description": "Web"},
             {"protocol": "icmp", "description": "Ping"}
           ]
         }'
bash
{
  "data": {
    "id": 7,
    "name": "web",
    "rules": [
      { "direction": "in", "action": "allow", "enabled": true, "protocol": "tcp", "ports": "22", "sources": ["203.0.113.0/24", "2001:db8::/32"], "description": "SSH depuis le bureau" },
      { "direction": "in", "action": "allow", "enabled": true, "protocol": "tcp", "ports": "80,443", "sources": ["0.0.0.0/0", "::/0"], "description": "Web" },
      { "direction": "in", "action": "allow", "enabled": true, "protocol": "icmp", "ports": null, "sources": ["0.0.0.0/0", "::/0"], "description": "Ping" }
    ],
    "private_network": false,
    "members": []
  }
}

Sans rules, le pare-feu démarre avec SSH (TCP 22) et le ping ouverts depuis partout ; envoyez "rules": [] pour n'en avoir aucune. Les adresses sont ramenées à leur adresse de réseau (203.0.113.7/24 devient 203.0.113.0/24). Dix pare-feux par compte, cinquante règles par pare-feu, vingt sources par règle.

Gardez une porte d'entrée. Un pare-feu qui n'ouvre pas TCP 22 (ou 3389 sous Windows) coupe SSH (ou le bureau à distance) sur toutes les machines qu'il protège. La console web marche toujours, mais un script ou un agent qui travaille en SSH perd sa machine.

Protéger une machine

bash
curl -s -X POST https://api.ffxf.net/v1/firewalls/7/members \
     -H "Authorization: Bearer $FFXF_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"vm": 4821}'
bash
{ "data": { "vm": 4821, "hostname": "web-1", "status": "applied" } }

Les règles sont écrites quand l'appel répond, et appliquées dans la dizaine de secondes qui suit. Rattacher un pare-feu déjà rattaché répond 200 : un script peut rejouer sa configuration sans risque. Jusqu'à cinq pare-feux par machine. Une machine sans adresse publique n'en reçoit pas : elle n'a rien à filtrer (409).

Changer les règles

PUT /firewalls/{id} avec rules remplace toute la liste : décrivez l'état voulu, l'API l'applique à chaque machine rattachée avant de répondre. Envoyez toutes les règles que vous gardez, pas seulement la nouvelle.

bash
curl -s -X PUT https://api.ffxf.net/v1/firewalls/7 \
     -H "Authorization: Bearer $FFXF_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"rules": [{"protocol": "tcp", "ports": "22"}, {"protocol": "tcp", "ports": "443"}]}'

pending_machines compte les machines sur lesquelles les nouvelles règles n'ont pas encore pu être appliquées ; elles portent "status": "error" dans members et sont reprises automatiquement en quelques minutes.

Ordre, refus et règles désactivées

Les règles sont lues de haut en bas, dans l'ordre de la liste. La première qui correspond au paquet l'emporte. Une règle avec "action": "deny" le refuse (il est jeté sans réponse). Placez-la au-dessus de l'autorisation qu'elle doit contrer. Ici, SSH n'est ouvert qu'au bureau :

bash
{
  "rules": [
    {"protocol": "tcp", "ports": "22", "sources": ["203.0.113.0/24"], "description": "SSH du bureau"},
    {"protocol": "tcp", "ports": "22", "action": "deny", "description": "SSH ailleurs"},
    {"protocol": "tcp", "ports": "8080", "enabled": false, "description": "Essai, coupé"}
  ]
}

Une règle avec "enabled": false reste dans la liste, mais elle n'est pas appliquée : pratique pour une ouverture temporaire, qu'on rallume sans la réécrire. Avec plusieurs pare-feux sur une machine, ils sont lus l'un après l'autre, dans l'ordre de création. Dans la console, chaque règle a ses boutons Modifier, Activer ou Désactiver, et ses flèches pour la déplacer. Par l'API, renvoyez la liste entière avec le changement.

Réseau privé et VPN site à site

Par défaut, un pare-feu ne filtre que l'accès public : tout ce qui arrive par la carte du réseau privé entre sans filtre, y compris le trafic d'un VPN site à site, qui passe par cette carte. Avec "private_network": true, les règles d'entrée du pare-feu valent aussi pour le réseau privé.

bash
curl -s -X PUT https://api.ffxf.net/v1/firewalls/7 \
     -H "Authorization: Bearer $FFXF_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"private_network": true}'
  • Ouvrez alors ce dont le réseau privé a besoin, par exemple RDP (TCP 3389) depuis la plage de votre bureau (192.168.77.0/24) ou SSH depuis la plage du VPC.
  • Les répartiteurs de charge qui visent la machine restent admis sur le port de leur cible, sans règle à écrire.
  • Sur une machine qui a aussi des pare-feux sans cette case, les règles de ceux-ci ne valent plus que pour l'accès public.
  • La sortie vers le réseau privé reste toujours ouverte.

Détacher, supprimer

ActionAppelÀ savoir
DétacherDELETE /firewalls/{id}/members/{vm}Les règles du pare-feu quittent la machine. Sans autre pare-feu, elle accepte de nouveau tout le trafic entrant.
RenommerPUT /firewalls/{id} avec nameRègles inchangées si rules est absent.
SupprimerDELETE /firewalls/{id}Refusé (409) tant qu'il protège une machine : le supprimer les ouvrirait toutes d'un coup.

Règles de sortie

Une règle avec "direction": "out" porte sur le trafic sortant, vers des destinations au lieu de venir de sources. Tant qu'aucun pare-feu d'une machine n'a de règle de sortie active qui autorise, tout peut sortir (des refus de sortie seuls ne bloquent que ce qu'ils visent). Dès qu'il y en a une, seul sort ce que les règles de sortie autorisent, plus ce qui reste toujours permis :

  • le DNS (port 53) vers les résolveurs que FFxF configure sur la machine ;
  • les réponses aux connexions entrantes que le pare-feu a laissées passer ;
  • le réseau privé.
bash
{
  "rules": [
    {"protocol": "tcp", "ports": "22"},
    {"direction": "out", "protocol": "tcp", "ports": "80,443", "description": "Mises à jour et HTTPS"},
    {"direction": "out", "protocol": "tcp", "ports": "5432", "destinations": ["198.51.100.20"], "description": "Base externe"}
  ]
}

La première règle de sortie ferme tout le reste : sans la règle 80,443 ci-dessus, les mises à jour de paquets et les téléchargements s'arrêtent. Des sources sur une règle de sortie, ou des destinations sur une règle d'entrée, sont refusées (validation_failed) plutôt qu'ignorées. Sur une machine sans IPv4, une destination IPv4 autorise aussi son adresse NAT64 (64:ff9b::/96), par laquelle cette machine joint l'IPv4. Le port 25 reste fermé, quoi que disent les règles.

Détails utiles

Les lectures demandent la portée vms.read ; créer, modifier, rattacher et supprimer demandent network.write. Le serveur MCP expose les mêmes actions : voir Outils MCP.

Support & discussions

Questions techniques, retours d'incidents ou discussions d'infrastructure, l'équipe est présente sur Discord, Telegram, X, Instagram, Reddit et IRC.