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

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

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.
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.
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.
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 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.

État documentaire au 29 octobre 2026, SFOS 23.0 : la référence API générée indique la base https://<firewall-host>:<port>/api/firewall-config/v1. La page d’introduction générale indique au contraire un chemin sans /api et montre même APIController pour le premier appel. Ce n’est pas une instruction fiable pour essayer différents chemins. Pour le pare-feu utilisé, prendre l’URL serveur complète dans son schéma téléchargé ; sans opération locale correspondante, ne pas exécuter le pilote suivant.

Premier appel en lecture : interroger les hotfixes appliqués

L’opération officielle GET /system/security-updates lit les mises à jour de sécurité hotfix appliquées. Elle ne déclenche ni mise à jour ni modification de configuration. Avant l’appel, vérifier dans le schéma local que ce chemin précis existe avec la méthode GET, puis reprendre l’URL de base complète.

Avant l’appel : confirmer le chemin dans le schéma local et utiliser une clé destinée à la lecture. Évaluer la réponse réellement reçue avant de poursuivre.

L’exemple s’exécute avec Python 3 sur l’hôte d’administration ou d’automatisation approuvé, pas dans la Device Console. firewall.example.com, le port 4444 et le chemin du fichier CA sont des valeurs à remplacer. Le nom d’hôte doit correspondre au certificat ; 4444 est simplement le port d’administration HTTPS choisi pour cet exemple. Le fichier PEM contient la CA émettrice de confiance, pas de clé privée. Si la chaîne est déjà reconnue par le truststore Python, ca_file = None peut être utilisé. Ne pas faire confiance à une CA quelconque téléchargée au hasard.

python3 - <<'PY'
import getpass
import json
import ssl
import urllib.error
import urllib.request

# Vollständige servers-URL des lokalen Schemas übernehmen.
# Dieser Beispielpfad entspricht der generierten Referenz.
api_base = "https://firewall.example.com:4444/api/firewall-config/v1"
ca_file = "/pfad/zur/management-ca.pem"
if not api_base.startswith("https://"):
    raise SystemExit("Nur die bestätigte HTTPS-Server-URL verwenden.")
context = ssl.create_default_context(cafile=ca_file)

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

opener = urllib.request.build_opener(
    NoRedirect(), urllib.request.HTTPSHandler(context=context)
)
api_key = getpass.getpass("Freigegebener REST-API-Schlüssel: ")
request = urllib.request.Request(
    api_base.rstrip("/") + "/system/security-updates",
    method="GET",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer " + api_key,
    },
)
try:
    with opener.open(request, timeout=30) as response:
        status = response.status
        body = response.read()
except urllib.error.HTTPError as error:
    raise SystemExit(f"HTTP {error.code}: Ursache vor erneutem Aufruf prüfen.")
except urllib.error.URLError as error:
    raise SystemExit(f"Verbindungs- oder TLS-Fehler: {error.reason}")

print(f"HTTP {status}")
if status != 200 or not body:
    raise SystemExit("Noch keine Abnahme: Status und Body mit dem Schema abgleichen.")
try:
    data = json.loads(body)
except (json.JSONDecodeError, UnicodeDecodeError):
    raise SystemExit("Kein gültiger JSON-Body; Zielpfad und Antwort prüfen.")
print(json.dumps(data, indent=2, ensure_ascii=False))
PY

La clé est saisie sans affichage, pas stockée comme argument de commande ni comme valeur littérale dans le script. Le client accepte uniquement HTTPS et ne suit aucune redirection : une réponse 3xx inattendue l’arrête au lieu de transmettre l’en-tête Bearer à une autre destination. Ne pas activer de logs de débogage shell/client pendant le pilote ; les données d’appareil affichées ne doivent pas non plus être copiées sans vérification dans des tickets. Pour une tâche sans surveillance, utiliser ensuite le Secret Store prévu.

Interpréter la réponse et les erreurs courantes

Une requête réussie doit renvoyer HTTP 200. Les données doivent décrire les mises à jour de sécurité hotfix appliquées. Comparer nombre et contenu à l’état connu de l’appareil et au schéma de réponse de ce firmware ; un corps JSON valide ne prouve ni exhaustivité ni niveau de correctifs particulier.

401 : la référence exige une authentification. Vérifier en-tête Bearer, bonne clé, expiration et suppression, sans consigner le secret.
403 : la référence exige une autorisation. Vérifier compte créateur et droits pour l’opération plutôt que d’accorder globalement tous les droits administrateur.
3xx : ne pas suivre la redirection. Vérifier URL serveur confirmée, éventuel proxy amont et règles de redirection ; ne pas transmettre la clé à la cible proposée.
404 : cette réponse n’est pas documentée comme réponse fonctionnelle de l’opération. Vérifier port administrateur, base complète du schéma, chemin, firmware et éventuel proxy amont. Ne pas basculer automatiquement vers le point XML ou un second préfixe REST.
400 ou 500 : la référence distingue requête invalide et erreur interne du serveur. Vérifier méthode et schéma, ou état de l’appareil et diagnostic expurgé.
Aucun statut HTTP : examiner DNS, route, connexion, timeout et chaîne du certificat TLS. En cas d’erreur de certificat, corriger nom d’hôte, chaîne de confiance et validité ; ne pas désactiver la vérification avec -k ou un contexte SSL non vérifié.

Test de lecture et contrôle opérationnel

Valider d’abord le chemin autorisé depuis l’hôte d’automatisation réel. Pour le contre-test de source, exécuter la même requête en lecture uniquement depuis un hôte de test supplémentaire approuvé, déjà extérieur à la liste des sources API. Il ne doit recevoir ni configuration ni données hotfix. Le statut précis de refus n’est pas garanti ; une réponse contenant des données serait un contre-test échoué. Ne supprimer aucune autorisation de production et ne pas utiliser de réseau tiers pour ce test.

La contre-épreuve TLS s’effectue aussi sans abaisser la protection : un nom d’hôte de test expressément approuvé et volontairement non conforme au certificat doit échouer lors de la vérification du certificat avant réception de données API. Ne modifier ni DNS de production ni autorisation réseau supplémentaire à cette fin. Sans nom de test adapté, cette partie de la validation reste ouverte. Documenter heure, hôte source, firmware, version de schéma utilisée, résultat HTTP/TLS et comparaison fonctionnelle des données, jamais la clé.

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.