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

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.
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.
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.
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 Authentifizierung, Objektverweise und das Schema des gewählten Endpunkts prüfen. Endpunktnamen ähneln der UI, sind aber nicht immer identisch.

Dokumentationsstand 29. Oktober 2026, SFOS 23.0: Die generierte API-Referenz nennt die Basis https://<firewall-host>:<port>/api/firewall-config/v1. Die allgemeine Einstiegsseite nennt dagegen einen Pfad ohne /api und zeigt beim ersten Aufruf sogar APIController. Das ist keine verlässliche Anleitung zum Ausprobieren verschiedener Pfade. Für die eigene Firewall gilt die vollständige Server-URL aus ihrem heruntergeladenen Schema; ohne passende lokale Operation wird der folgende Pilot nicht ausgeführt.

Erster lesender Aufruf: angewendete Hotfixes abfragen

Die offizielle Operation GET /system/security-updates liest die angewendeten Hotfix-Sicherheitsupdates. Sie startet weder eine Aktualisierung noch eine Konfigurationsänderung. Vor dem Aufruf im lokalen Schema kontrollieren, dass genau dieser Pfad mit Methode GET vorhanden ist, und die vollständige Basis-URL übernehmen.

Das Beispiel läuft mit Python 3 auf dem freigegebenen Administrations- oder Automationshost, nicht in der Device Console. firewall.example.com, Port 4444 und der CA-Dateipfad sind Austauschwerte. Der Hostname muss zum Zertifikat passen; 4444 ist nur der hier gewählte HTTPS-Adminport. Die PEM-Datei enthält die vertrauenswürdige ausstellende CA, kein privates Schlüsselmaterial. Bei einer im Python-Truststore bereits vertrauenswürdigen Zertifikatskette kann ca_file = None verwendet werden. Nicht auf eine beliebige heruntergeladene CA vertrauen.

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

Der Schlüssel wird verdeckt abgefragt, nicht als Befehlsargument oder als Literal im Skript gespeichert. Der Client akzeptiert nur HTTPS und folgt keinen Weiterleitungen: Bei einer unerwarteten 3xx-Antwort stoppt er, statt den Bearer-Header an ein anderes Ziel zu senden. Während des Piloten keine Shell-/Client-Debugprotokollierung einschalten; auch die ausgegebenen Gerätedaten gehören nicht ungeprüft in Tickets. Für einen unbeaufsichtigten Job wird später der vorgesehene Secret Store verwendet.

Antwort und typische Fehler einordnen

Bei einer erfolgreichen Anfrage wird HTTP 200 erwartet. Die Daten sollen die angewendeten Hotfix-Sicherheitsupdates beschreiben. Anzahl und Inhalt werden mit dem bekannten Gerätestand und dem Antwortschema dieser Firmware abgeglichen; ein gültiger JSON-Body allein beweist weder Vollständigkeit noch einen bestimmten Patchstand.

401: Die Referenz verlangt eine Authentifizierung. Bearer-Header, richtigen Schlüssel, Ablauf und Löschung prüfen, ohne das Geheimnis zu protokollieren.
403: Die Referenz verlangt eine Berechtigung. Erstellerkonto und dessen Rechte für die Operation prüfen, statt pauschal volle Administratorrechte zu vergeben.
3xx: Nicht weiterleiten. Die bestätigte Server-URL, einen vorgeschalteten Proxy und dessen Weiterleitungsregeln prüfen; den Schlüssel nicht an das Weiterleitungsziel übernehmen.
404: Für diese Operation ist 404 nicht als fachliche Antwort dokumentiert. Adminport, vollständige Schema-Basis, Pfad, Firmware und einen möglichen vorgeschalteten Proxy prüfen. Nicht automatisch auf den XML-Endpunkt oder einen zweiten REST-Präfix wechseln.
400 oder 500: Die Referenz unterscheidet ungültige Anfrage und internen Serverfehler. Methode und Schema beziehungsweise Gerätezustand und bereinigte Diagnose prüfen.
Kein HTTP-Status: DNS, Route, Verbindung, Timeout und TLS-Zertifikatskette untersuchen. Bei Zertifikatsfehlern Hostname, Vertrauenskette und Gültigkeit korrigieren; die Prüfung nicht mit -k oder einem ungeprüften SSL-Kontext abschalten.

Lesetest und Betriebskontrolle

Zuerst den erlaubten Pfad vom echten Automationshost abnehmen. Für den Quellen-Negativtest dieselbe reine Leseanfrage nur von einem zusätzlich freigegebenen Testhost ausführen, der bereits ausserhalb der API-Quellenliste liegt. Er darf keine Konfiguration oder Hotfix-Daten erhalten. Der konkrete Abweisungsstatus ist nicht zugesichert; eine Antwort mit Daten wäre ein fehlgeschlagener Negativtest. Keine Produktionsfreigabe entfernen und kein fremdes Netz für den Test verwenden.

Die TLS-Negativprüfung erfolgt ebenfalls ohne Schutzabsenkung: Ein gezielt nicht zum Zertifikat passender, ausdrücklich freigegebener Testhostname muss vor dem Erhalt von API-Daten an der Zertifikatsprüfung scheitern. Dafür weder produktives DNS ändern noch eine zusätzliche Netzwerkfreigabe anlegen. Ohne geeigneten Testnamen bleibt dieser Teil der Abnahme offen. Zeitpunkt, Quellhost, Firmware, verwendete Schema-Version, HTTP-/TLS-Ergebnis und fachlichen Datenabgleich dokumentieren, niemals den Schlüssel.

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.