Sophos Firewall REST API: Zugriff und API-Schlüssel sicher verwalten

Die lokale REST API in SFOS 23.0 erlaubt automatisierte Konfigurationsabfragen und Änderungen direkt auf der Firewall. Der sichere Einstieg ist: eigenen Administrator mit engen Rechten anlegen, nur den Automationshost erlauben, unter diesem Konto einen Schlüssel erzeugen und zuerst eine lesende Anfrage prüfen. Die Verfügbarkeit der Dokumentation ist keine Aussage zum GA-Termin oder zur Verfügbarkeit auf einer älteren Firmware.

Drei Schnittstellen, drei Identitäten

• Lokale REST API: Ein API-Schlüssel des Firewall-Administrators dient als Bearer-Token; seine Rechte entsprechen dem Administratorprofil.
• Lokale XML API: XML-Payloads und Administrator-Anmeldedaten, normalerweise per HTTP POST an APIController. Ein XML-<Get> ist kein REST-Aufruf.
• Sophos Central Konfigurations-API: Cloud-Service-Principal, kurzlebiges Zugriffstoken, Tenant und regionaler API-Host. Ein lokaler Firewall-Schlüssel ersetzt diese Zugangsdaten nicht.

Zugriff und Administrator vorbereiten

1. Unter Profiles > Device access ein Profil mit nur den benötigten Funktionsrechten anlegen; für reine Inventarisierung nur passende Leserechte vorsehen. Unter Authentication > Users ein dediziertes Administratorkonto mit diesem Profil erstellen. Die Planung von Administratoren und Profilen erklärt die Rollenwahl. Nicht das persönliche Konto oder den voll berechtigten Standard-admin für Jobs verwenden.
2. Unter Hosts and services > IP host den tatsächlichen Automationshost erfassen, etwa api-inventory mit 192.0.2.20. Name und Dokumentationsadresse durch die eigenen Werte ersetzen. Eine einzelne feste Quelle ist enger als ein gesamtes Managementnetz; bei NAT zählt die auf der Firewall sichtbare Quelle.
3. Unter Administration > API access das standardmässig ausgeschaltete API access einschalten, unter Allowed IP hosts nur die benötigten Quellen auswählen und Apply klicken. IP-Adressen, Bereiche und Netze sind möglich, maximal 64 Einträge. Beim Upgrade auf SFOS 22.0 oder später migrierte Quellen mit apiconfig prüfen.
4. Unter Administration > Device access den WebAdmin-Zugriff aus der betreffenden Zone prüfen. Device Access und die API-Quellenliste sind getrennte Kontrollschichten; den WAN-Zugriff nicht pauschal öffnen.

Schlüssel erzeugen und einmalig sichern

Mit dem dedizierten Administratorkonto anmelden. Unter Administration > API access > REST API keys auf Add API key klicken, einen nachvollziehbaren Namen wie inventory-prod-2026-10 eingeben und mit Add API key erzeugen.

Vor Close: Den Schlüssel in den geschützten Secret Store des Jobs kopieren. Nach dem Schliessen des Pop-ups wird er nie wieder angezeigt. Keine Screenshots, Tickets, Repository-Dateien oder ungeschützten Collection-Exporte mit dem Schlüssel erstellen.

Der Schlüssel gilt ein Jahr und erbt die Rechte seines Erstellers. Administratoren können eigene Schlüssel erstellen und löschen; alle Administratoren sehen die Schlüsselliste, nicht erneut das Geheimnis. Der Standard-admin kann auch Schlüssel anderer Administratoren löschen. Grenzen: 10 Schlüssel je Administrator, 1024 insgesamt. Schlüssel nicht zwischen Administratoren teilen.

Anfrage aus dem Firewall-Schema aufbauen

Unter REST API help die OpenAPI.yaml dieser Firewall herunterladen und in Postman oder Swagger importieren. Unter REST API guide die Basis-URL, Authentifizierung, Objektverweise und das Schema des gewählten Endpunkts prüfen. Endpunktnamen ähneln der UI, sind aber nicht immer identisch.

Die Referenz nennt diese Basis und diesen Header; Pfad, Methode und Parameter der eigentlichen Anfrage kommen aus dem passenden Schema:

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

Hostname und HTTPS-Adminport durch die eigenen Werte ersetzen; den Schlüssel über die Secret-Funktion des Clients einsetzen. TLS-Zertifikat und Hostname prüfen, nicht mit -k umgehen. Die Einstiegsreferenz enthält auch Beispiele mit dem XML-Pfad APIController; diese nicht ungeprüft als REST-Rezept übernehmen. Ohne passenden Endpunkt im Firewall-Schema keinen Pfad erraten.

Lesetest und Betriebskontrolle

Vom echten Automationshost eine harmlose, schema-konforme Leseanfrage senden. Antwort und erwartete Objektdaten prüfen, nicht nur den HTTP-Erfolg. Von einer kontrollierten, nicht erlaubten Quelle dieselbe Anfrage testen: Sie darf keine Konfiguration liefern. Produktionsfreigaben dafür nicht entfernen.

Vor Schreiboperationen Backup und Rückweg vorbereiten, nur eine kleine freigegebene Änderung testen und das Zielobjekt in WebAdmin sowie den Audit Trail kontrollieren. Bei Zeitüberschreitung einer Änderung zuerst den tatsächlichen Objektzustand lesen, nicht blind wiederholen. Langsame Abfragen, etwa IPS-Signaturen, können längere Client-Timeouts benötigen.

Ablauf, Ersatz und Löschung

Je Schlüssel Konto, Job, erlaubte Quelle, Erstellungsdatum, Ablaufdatum und verantwortliches Team dokumentieren, niemals den Schlüssel selbst. Einen Erinnerungs- und Ersatztermin vor Ablauf setzen; automatische Verlängerung nicht voraussetzen. Für überlappende Rotation einen freien Schlüsselplatz einplanen. Bei 10 eigenen oder 1024 gesamten Schlüsseln zuerst mit dem Verantwortlichen unbenötigte Schlüssel identifizieren, nicht wahllos aktive Jobs sperren.

Für geplanten Ersatz unter demselben Konto einen neuen Schlüssel erzeugen, sichern, im Job einsetzen und mit einer Leseanfrage prüfen. Erst danach den alten eigenen Schlüssel löschen und kontrollieren, dass der neue funktioniert und der alte keinen Zugriff mehr erhält. Gelöschte Schlüssel nicht als wiederherstellbar behandeln. Bei Verlust der einmaligen Anzeige ebenfalls ersetzen. Bei vermutetem Leak hat die sofortige Sperrung Vorrang vor unterbrechungsfreier Rotation. Für fremde Schlüssel den Standard-admin-Verantwortlichen einbeziehen. Bei Stilllegung Schlüssel löschen und unbenötigte API-Quellen entfernen; gemeinsam genutzte Quellen vorher prüfen.

Grenzen in SFOS 23.0

Nicht über diese REST API verfügbar sind laut aktuellem Funktionsumfang:

• Web: Captive portal, Direct proxy authentication, Web filter notification settings, Advanced settings.
• Alle Email-, Wireless- und RED-Funktionen.
• Network: DDNS und IP tunnels; SD-WAN profiles.
• VPN: IPsec routes, GRE routes, L2TP, PPTP, SSL VPN site-to-site clients und servers.
• Authentication: Guest users und clientless users; Firewall rule groups.
• Let’s Encrypt certificates; High availability und TAP mode; System time.
• Statusinformationen, beispielsweise DHCP-Leases, HA-Status und Datenspeicherung.

Die Liste ist nicht vollständig und keine Zusage für eine künftige Version. Jede benötigte Operation im aktuellen Schema prüfen; aus einem sichtbaren UI-Menü folgt keine API-Unterstützung. XML oder Cloud sind kein automatisch gleichwertiger Ersatz.

Wenn der Job scheitert

Bei Verbindungsfehlern Quelle nach NAT, Routing, Adminport, TLS, API-Freigabe und Device Access prüfen. Bei Authentifizierungs- oder Rechtefehlern richtigen Schlüssel, Ablauf, Löschung, Erstellerkonto und dessen Profil prüfen, statt volle Rechte zu vergeben. Bei Schemafehlern Methode, Pfad, Pflichtfelder und abhängige Objektverweise abgleichen. Schlüsselverlust durch Ersatz lösen, nicht durch Suche nach einer erneuten Anzeige.

Für eine Eskalation Firmware, Schema-Version, Zeitpunkt, Endpunkt, HTTP-Status und bereinigte Antwort sichern; keine Geheimnisse weitergeben. Sophos unterstützt die offizielle REST API und unveränderte Skripte, nicht Beratung oder Troubleshooting eigener Integrationen. Diese benötigen einen eigenen Verantwortlichen; bei Bedarf Partner oder Sophos Professional Services einbeziehen.