Aller au contenu
Avanet

API REST Sophos Firewall : sécuriser l’accès et les clés API

Sophos Firewall

L’API REST locale de SFOS 23.0 permet de lire et modifier la configuration directement sur le pare-feu. Commencer par un administrateur dédié aux droits limités, autoriser uniquement l’hôte d’automatisation, générer une clé avec ce compte et vérifier d’abord une requête de lecture. La présence de documentation ne confirme ni une date de disponibilité générale ni la prise en charge sur un ancien firmware.

Trois interfaces, trois identités

  • API REST locale : la clé d’un administrateur du pare-feu sert de jeton Bearer ; ses droits proviennent du profil administrateur.
  • API XML locale : charges utiles XML et identifiants administrateur, généralement par HTTP POST vers APIController. XML <Get> n’est pas une requête REST.
  • API de configuration Sophos Central : principal de service cloud, jeton temporaire, tenant et hôte API régional. Une clé locale ne remplace pas ces identifiants.

Préparer l’accès et l’administrateur

  1. Dans Profiles > Device access, créer un profil limité aux fonctions nécessaires ; un inventaire nécessite les droits de lecture appropriés. Dans Authentication > Users, créer un administrateur dédié avec ce profil. La planification des administrateurs et profils explique les rôles. Ne pas utiliser un compte personnel ou le compte admin par défaut, pleinement privilégié, pour les tâches.
  2. Dans Hosts and services > IP host, définir l’hôte réel, par exemple api-inventory avec 192.0.2.20. Remplacer le nom et l’adresse de documentation. Une source fixe est plus restrictive qu’un réseau de gestion entier ; avec NAT, retenir la source vue par le pare-feu.
  3. Dans Administration > API access, activer API access, désactivé par défaut, sélectionner uniquement les sources nécessaires dans Allowed IP hosts, puis cliquer sur Apply. Adresses, plages et réseaux sont possibles, avec 64 entrées au maximum. Vérifier les sources apiconfig migrées lors d’une mise à niveau vers SFOS 22.0 ou ultérieur.
  4. Dans Administration > Device access, vérifier l’accès WebAdmin depuis la zone concernée. Device Access et la liste des sources API sont distincts ; ne pas ouvrir largement l’accès WAN.

Générer et capturer la clé une seule fois

Se connecter avec l’administrateur dédié. Dans Administration > API access > REST API keys, cliquer sur Add API key, donner un nom explicite comme inventory-prod-2026-10, puis générer avec Add API key.

Avant Close : copier la clé dans le stockage de secrets protégé de la tâche. Après fermeture de la fenêtre, elle ne sera jamais réaffichée. Ne pas l’inclure dans des captures, tickets, fichiers de dépôt ou exports de collections non protégés.

La clé est valable un an et hérite des droits de son créateur. Les administrateurs créent et suppriment leurs propres clés ; tous voient la liste, mais ne peuvent pas récupérer le secret. Le compte admin par défaut peut aussi supprimer celles des autres. Limites : 10 clés par administrateur, 1024 au total. Ne pas partager les clés entre administrateurs.

Construire la requête à partir du schéma du pare-feu

Dans REST API help, télécharger OpenAPI.yaml depuis ce pare-feu et l’importer dans Postman ou Swagger. Dans REST API guide, vérifier URL de base, authentification, références d’objets et schéma du point de terminaison choisi. Les noms ressemblent à ceux de l’interface, sans être toujours identiques.

La référence indique cette base et cet en-tête ; chemin, méthode et paramètres de la requête proviennent du schéma correspondant :

https://<firewall-host>:<port>/firewall-config/v1
Authorization: Bearer <API_KEY>

Remplacer hôte et port HTTPS administrateur ; insérer la clé via la fonction de secrets du client. Valider certificat TLS et nom d’hôte, sans contourner les contrôles avec -k. L’introduction contient aussi des exemples utilisant le chemin XML APIController ; ne pas les reprendre sans vérification comme procédure REST. Sans point de terminaison correspondant dans le schéma, ne pas inventer de chemin.

Test de lecture et contrôle opérationnel

Depuis l’hôte réel, envoyer une lecture sans effet de bord conforme au schéma. Vérifier réponse et données attendues, pas seulement le succès HTTP. Refaire le test depuis une source contrôlée non autorisée : aucune configuration ne doit être renvoyée. Ne pas retirer une autorisation de production pour ce test.

Avant toute écriture, préparer une sauvegarde et un retour arrière, tester une petite modification approuvée, puis contrôler l’objet dans WebAdmin et l’Audit Trail. Après un délai dépassé en écriture, lire l’état réel avant de réessayer. Des lectures lentes, notamment les signatures IPS, peuvent nécessiter un délai client supérieur.

Expiration, remplacement et suppression

Documenter compte, tâche, source autorisée, date de création, expiration et équipe responsable, jamais la clé. Prévoir rappels et remplacement avant expiration, sans supposer de renouvellement automatique. Réserver un emplacement libre pour une rotation avec chevauchement. À 10 clés propres ou 1024 au total, identifier d’abord les clés inutiles avec leur responsable, sans révoquer arbitrairement les tâches actives.

Pour un remplacement planifié, générer et capturer une nouvelle clé sous le même compte, modifier la tâche et vérifier une lecture. Supprimer ensuite l’ancienne clé détenue et contrôler que la nouvelle fonctionne et que l’ancienne n’autorise plus l’accès. Ne pas considérer les clés supprimées comme récupérables. Remplacer également une clé dont l’affichage unique a été perdu. En cas de fuite présumée, révoquer immédiatement, même au prix d’une interruption. Pour supprimer la clé d’un autre administrateur, solliciter le responsable du admin par défaut. Lors de l’arrêt d’une intégration, supprimer clés et sources inutiles, après vérification des sources partagées.

Limites de SFOS 23.0

Le périmètre actuel exclut de cette API REST :

  • Web : Captive portal, Direct proxy authentication, Web filter notification settings, Advanced settings.
  • Toutes les fonctions Email, Wireless et RED.
  • Network : DDNS et IP tunnels ; SD-WAN profiles.
  • VPN : IPsec routes, GRE routes, L2TP, PPTP, clients et serveurs SSL VPN site-to-site.
  • Authentication : Guest users et clientless users ; Firewall rule groups.
  • Let’s Encrypt certificates ; High availability et TAP mode ; System time.
  • Informations d’état, par exemple baux DHCP, état HA et stockage de données.

La liste n’est ni exhaustive ni une promesse pour une future version. Vérifier chaque opération dans le schéma actuel ; un menu visible ne prouve pas sa prise en charge par API. XML ou cloud n’est pas un remplacement automatiquement équivalent.

Si la tâche échoue

Pour la connexion, vérifier source après NAT, routage, port administrateur, TLS, autorisation API et Device Access. Pour l’authentification ou les droits, vérifier clé, expiration, suppression, compte créateur et profil plutôt que donner tous les droits. Pour le schéma, comparer méthode, chemin, champs obligatoires et références dépendantes. Une clé perdue se remplace ; elle ne se réaffiche pas.

Pour l’escalade, conserver firmware, version du schéma, heure, point de terminaison, statut HTTP et réponse nettoyée, sans secrets. Sophos prend en charge l’API officielle et les scripts non modifiés, pas le conseil ou le dépannage d’intégrations personnalisées. Celles-ci nécessitent un responsable interne ; solliciter un partenaire ou Sophos Professional Services si nécessaire.