Sophos Firewall XML API Zugriff absichern

Die XML API der Sophos Firewall ist praktisch für Automatisierung, Monitoring, Backups, Auswertungen und Integrationen. Mit ihr lässt sich dieselbe Konfiguration auch reproduzierbar auf mehrere Firewalls anwenden, wenn der Prozess eng begrenzt und getestet ist. Genau deshalb gehört sie aber auch zur Management-Angriffsfläche. Wer API-Zugriff erlaubt, gibt einem System die Möglichkeit, Konfigurationsdaten zu lesen oder je nach Berechtigung Änderungen vorzunehmen.

API-Zugriff sollte deshalb nicht breit aus internen Netzen oder von beliebigen Quellen erlaubt werden. Besser ist ein kleines, dokumentiertes Set aus Management-Netzen, Automations-Hosts oder festen Partnerzugängen.

Seit SFOS 22 hat Sophos die API-Zugriffskontrolle erweitert. Die API access settings befinden sich unter Administration > API access, und erlaubte Quellen können als IP Hosts definiert werden. Dadurch lassen sich nicht nur einzelne IP-Adressen, sondern auch IP ranges und Netzwerke sauber modellieren.

Auf älteren SFOS-Versionen lag die API-Konfiguration unter Backup and firmware > API. Bei gemischten Kundenumgebungen sollte man deshalb zuerst die SFOS-Version prüfen, bevor man eine Anleitung oder ein Skript unverändert übernimmt.

Wann XML API Zugriff sinnvoll ist

Die XML API ist kein Standardzugang für normale Admin-Arbeit. Sinnvoll ist der Einsatz, wenn ein konkreter technischer Prozess dahintersteht.

Typische Anwendungsfälle:

• Monitoring oder Inventarisierung.
• Automatisierte Konfigurationsprüfungen.
• Backup- oder Dokumentationsprozesse.
• MSP- oder Integrationsplattformen.
• Skripte für wiederkehrende administrative Aufgaben.
• Vorbereitete Änderungen aus Tools wie Sophos Firewall Config Studio.

Wenn ein Prozess auch ohne API auskommt, sollte API-Zugriff nicht vorsorglich aktiviert bleiben. Jede zusätzliche Schnittstelle braucht einen Besitzer, eine Quelle, ein Zugriffskonzept und eine Kontrolle.

Was sich mit SFOS 22 geändert hat

Mit SFOS 22 wurde die XML API Zugriffskontrolle für den Betrieb deutlich besser handhabbar:

• Die API access settings wurden in das Menü Administration > API access verschoben.
• API access ist standardmässig deaktiviert und muss bewusst eingeschaltet werden.
• API access kann auf IP Hosts beschränkt werden.
• Als Quellen sind dadurch IP-Adressen, IP ranges und Netzwerke möglich.
• Bis zu 64 IP Hosts können erlaubt werden.
• Beim Upgrade werden bisher erlaubte IP-Adressen automatisch in IP Host Objekte umgewandelt.
• Migrierte Objekte erhalten den Prefix apiconfig.

Das ist für den Betrieb hilfreich, weil API-Quellen nicht mehr nur als lose Einzeladressen gepflegt werden müssen. Man kann ein Management-Netz, einen Automations-Host oder eine dedizierte Host-Gruppe sauber benennen und später in Reviews wiedererkennen.

Grundregel: API nur aus definierten Quellen erlauben

API access sollte nach dem gleichen Prinzip behandelt werden wie WebAdmin oder SSH: so eng wie möglich, so breit wie nötig.

Sinnvolle Quellen sind zum Beispiel:

• ein dedizierter Automationsserver,
• ein Monitoring-System,
• ein Konfigurationsmanagement-Host,
• ein internes Management-Netz,
• ein VPN- oder Admin-Netz,
• eine klar definierte Partner- oder MSP-Quelladresse.

Nicht sinnvoll sind:

• ganze Client-Netze,
• Gast- oder IoT-Netze,
• Any,
• unklare “Servernetz komplett”-Freigaben,
• temporäre Test-IP-Adressen, die später vergessen werden.

Wenn externe Dienstleister API-Zugriff brauchen, sollte die Quelle so spezifisch wie möglich definiert werden. Zusätzlich sollte dokumentiert sein, wofür der Zugriff verwendet wird und wann er wieder entfernt wird.

Empfohlener Ablauf

Der genaue UI-Pfad kann je nach SFOS-Version leicht variieren. In SFOS 22 liegt die API-Konfiguration unter Administration > API access.

Praktischer Ablauf:

1. Prüfen, welches System API-Zugriff benötigt.
2. Unter Hosts and services > IP host ein eindeutiges IP Host Objekt für dieses System erstellen.
3. Wenn mehrere Quellen nötig sind, IP Hosts, IP ranges oder Netzwerke sauber benennen.
4. Unter Administration > API access API access aktivieren.
5. Unter Allowed IP hosts nur diese Objekte erlauben.
6. Apply anklicken.
7. Keine breiten Client- oder Servernetze eintragen.
8. Zugriff vom echten Automations- oder Monitoring-Host testen, nicht vom Admin-Notebook.
9. Nicht mehr benötigte Quellen wieder entfernen.
10. Änderung im Change-Prozess dokumentieren.

Bei bestehenden Installationen nach einem Upgrade auf SFOS 22 sollte man zusätzlich nach Objekten mit dem Prefix apiconfig suchen. Diese Objekte wurden aus älteren API-Allow-Einträgen erzeugt und sollten geprüft, benannt oder bereinigt werden.

Zugriff gezielt testen

Der API-Endpunkt liegt typischerweise unter:

https://<Firewall-IP-oder-Hostname>:<Port>/webconsole/APIController

Der Port ist der HTTPS-Port der WebAdmin Console. Wenn der Admin-Port unter Administration > Admin settings angepasst wurde, muss das API-Tool denselben Port verwenden. Die API arbeitet mit XML-Payloads über HTTP POST, nicht wie eine klassische REST-API mit getrennten GET-, POST-, PUT- und DELETE-Endpunkten.

HTTPS schützt Anmeldedaten nur dann zuverlässig vor Manipulation und Mitlesen, wenn der Client das Zertifikat der Firewall validiert. Das Automationssystem sollte deshalb den Namen aus dem Zertifikat verwenden, der ausstellenden CA vertrauen und bei Zertifikats- oder Hostnamenfehlern abbrechen. Optionen wie curl -k umgehen diese Prüfung und gehören nicht in produktive Jobs.

Ein sinnvoller Test beantwortet nicht nur die Frage, ob ein Login grundsätzlich möglich ist. Er sollte zeigen, ob die richtige Quelle erlaubt ist, ob das Konto die benötigte Operation ausführen darf und ob das Ergebnis im Audit- oder Change-Prozess nachvollziehbar bleibt.

Für die Abnahme sollte man diese Punkte getrennt prüfen:

• Quelle: Der Test läuft vom echten Automations-, Monitoring- oder Integrationshost, nicht vom Admin-Notebook.
• Zugriff: Die Firewall akzeptiert die Quell-IP nur, wenn das passende IP Host Objekt in API access erlaubt ist.
• Negativtest: Vom kontrollierten Testhost, der bewusst nicht unter Allowed IP hosts steht, denselben ungefährlichen Lese-Request senden und prüfen, dass die API ihn ohne Konfigurationsdaten ablehnt. Für diesen Test keine produktive Freigabe lockern oder entfernen.
• Konto: Das verwendete API- oder Servicekonto hat nur die benötigten Rechte.
• Secret: Benutzername, Passwort oder Token landen nicht in Shell-History, Tickets, Chatverläufen oder Screenshots.
• Audit: Der Zugriff oder die Änderung ist im Audit- oder Change-Prozess nachvollziehbar.
• Rollback: Vor Schreiboperationen existieren Backup, Rollback-Punkt und ein ungefährlicher Lesetest.

Gerade curl-Beispiele mit Benutzername und Passwort in der URL sind schnell kopiert und später schwer wieder aus Protokollen zu entfernen. Besser ist ein kurzer Test mit dediziertem Servicekonto, temporärem Test-Secret, sicherer Ablage und anschliessender Rotation, wenn ein Secret in einem unsicheren Kontext verwendet wurde.

Für strukturierte Tests ist eine Postman-Collection oft sauberer als ein schnell kopierter Shell-Befehl. Auch dort sollten Firewall-Adresse, Port, Benutzername, Passwort und Objektwerte als Variablen oder Secrets gepflegt werden, nicht hart in Requests, Screenshots oder Tickets stehen. Die Collection ist kein Sicherheitskonzept, hilft aber, Lese- und Schreiboperationen reproduzierbarer zu testen.

Eine API, die erreichbar ist, ist noch kein Beweis, dass die geplante Änderung fachlich sicher ist. Vor produktiven Schreiboperationen sollte deshalb zuerst eine ungefährliche Leseabfrage funktionieren und danach eine kleine, kontrollierte Änderung getestet werden.

XML-Requests bewusst aufbauen und auswerten

Versionsgrenze: Die SFOS-22-Anleitung nennt Browser als mögliche XML-Clients. Ab SFOS 23.0 schliesst die konkrete Anleitung zum Senden von XML-Anfragen Browser ausdrücklich aus; für diese POST-Anfragen Postman oder eine kontrollierte Linux-Kommandozeile verwenden. Der allgemeine XML-Überblick nennt weiterhin Browser. Daraus keine Freigabe für Browser-POST in SFOS 23.0 ableiten. Die lokale REST API mit Administrator-Schlüsseln ist eine separate Schnittstelle, kein neues Authentifizierungsverfahren für diese XML-Payloads.

Die hier gezeigten Konfigurationsabfragen und Änderungen verwenden HTTP POST an denselben APIController. Ob SFOS liest, anlegt, aktualisiert oder löscht, steht nicht in der HTTP-Methode, sondern im XML-Payload. Ein XML-<Get> bezeichnet eine Leseoperation, nicht automatisch HTTP GET; auch die als «API GET request» bezeichnete Object-Usage-Abfrage wird per HTTP POST gesendet. Der separate Zertifikatsexport weiter unten ist ein dokumentierter HTTP-GET-Sonderfall. Der äussere Aufbau besteht aus <Request>, <Login> und genau der benötigten Operation:

• <Set operation="add"> legt unterstützte Objekte, Regeln oder Policies an.
• <Set operation="update"> ändert Einstellungen, die nicht neu angelegt werden können.
• <Get> liest Konfigurationen oder Statusdaten.
• <Remove> löscht unterstützte Objekte. Feste Einstellungen wie die SSL/TLS-Inspection-Konfiguration lassen sich nicht entfernen, sondern nur aktualisieren.
• <Filter> begrenzt eine Leseabfrage. Die allgemeinen Kriterien sind =, != und like; einzelne Statistikabfragen unterstützen weitere Kriterien.

Fehlt bei <Set> die Angabe operation, behandelt SFOS den Request als add. Das ist kein harmloser Default: Bei einer eigentlich geplanten Aktualisierung kann der Request fehlschlagen oder am falschen Objekt arbeiten. APIXMLTags dokumentiert das optionale alphanumerische Attribut transactionid an <Set>; es erleichtert die Zuordnung eines Requests zur Antwort. Für spezialisierte Operationen ist das Objektbeispiel in API help des eingesetzten SFOS-Builds massgebend. Das Zertifikatsbeispiel setzt transactionid an <Certificate>; dieser Sonderfall ist keine allgemeine Regel für die Platzierung an Objekt-Tags innerhalb von <Set>.

Die optionale Angabe APIVersion in <Request> verwendet versionsspezifische Syntax. Die exakten Objekt-Tags, Attribute, Statuscodes und Beispielkonfigurationen müssen deshalb aus API help des eingesetzten SFOS-Builds stammen; Payloads werden nicht ungeprüft zwischen Versionen übernommen.

Ein kleiner Lese-Request sieht schematisch so aus:

<Request>
  <Login>
    <Username>api-reader</Username>
    <Password>SECRET</Password>
  </Login>
  <Get>
    <IPHost></IPHost>
  </Get>
</Request>

api-reader und SECRET sind Platzhalter. Das echte Secret gehört in den geschützten Secret Store des Tools und nicht in die XML-Datei im Repository. Erfolgreich ist der Test erst, wenn die Antwort unter <Response> den erwarteten Inhalt und unter <Status> einen passenden Status meldet. Ein HTTP-Erfolg oder die Meldung Send successful in Postman allein beweist nicht, dass SFOS die gewünschte Operation ausgeführt hat. Bei Schreiboperationen zusätzlich das Zielobjekt in WebAdmin und die Änderung im Audit Trail kontrollieren.

Offizielle Postman-Collection sicher verwenden

Aktuelle Postman-Collection herunterladen und importieren. Die Collection deckt nur einen Teil der unterstützten Requests ab; die lokale API help der Firewall zeigt den vollständigen Funktionsumfang sowie zum Build passende Beispielkonfigurationen und Objektdefinitionen. Vor dem ersten Request müssen in den Collection Variables alle vier mitgelieferten Beispielwerte apiadmin, Admin@12345, 172.16.16.16 und 4444 durch username, password, firewall-ip und firewall-port der eigenen Umgebung ersetzt werden. Auch die enthaltenen Objektwerte sind Beispiele und dürfen nicht ungeprüft gesendet werden.

Für einen eigenen Request wird die Methode POST, der oben gezeigte Endpoint und unter Body > form-data der Key reqxml verwendet. Zuerst Authenticate > Sign in und danach eine ungefährliche <Get>-Abfrage testen. Erst wenn Quellfreigabe, Konto, Antwort und Audit stimmen, folgt eine kleine Schreiboperation mit vorbereitetem Rollback.

Sensible XML-Importe: Vor einem Import mit Passwörtern oder anderen sensiblen Werten in API help des installierten Builds prüfen, ob die konkrete Operation SecureStorageMasterKey und das Attribut Token an <Request> benötigt und welche Eingaben dafür gültig sind. Im SFOS-23-POST-Beispiel ist SecureStorageMasterKey eine separate Body-Eingabe; Token steht an <Request> im XML des Body-Felds reqxml. Nur die für diese Operation bestätigten Eingaben an den freigegebenen POST-Body-/XML-Stellen übergeben. Schlüssel, Passwörter und Tokens dabei aus URLs, Shell-History und Logs fernhalten; daraus keine Token-Pflicht für jede XML-Abfrage ableiten.

Die Dokumentation enthält daneben weiterhin ein widersprüchliches URL-Beispiel für den Master Key. Solange Quellenkonflikt, benötigte Eingabe oder deren Interpretation für den installierten Build ungeklärt sind, den sensiblen Import nicht ausführen und die Klärung mit Support veranlassen. Der gesondert abgesicherte HTTP-GET-Zertifikatsexport weiter unten bleibt ein eigener Sonderfall.

Eine exportierte Collection kann Credentials oder Umgebungswerte enthalten. Deshalb Collections vor dem Teilen bereinigen, Secrets nicht als Klartext in Initial Values speichern und Testpasswörter nach einem Leak rotieren.

Object Usage vor Änderungen abfragen

Die API kann für unterstützte Objekte Namen und Usage Count liefern. Dafür werden Statistik-Tags wie <IPHostStatistics> statt des normalen Objekt-Tags verwendet. Ein Filter auf IP-Host-Namen sieht beispielsweise so aus:

<Request>
  <Login>
    <Username>api-reader</Username>
    <Password>SECRET</Password>
  </Login>
  <Get>
    <IPHostStatistics>
      <Filter>
        <key name="Name" criteria="like">branch</key>
      </Filter>
    </IPHostStatistics>
  </Get>
</Request>

SFOS 22 unterstützt diese Usage-Abfrage für IP Hosts, IP Host Groups, MAC Hosts, FQDN Hosts und Gruppen, Country Groups, Services und Service Groups sowie Interfaces, Zones, Gateways und SD-WAN Profiles. Namensfilter unterstützen unter anderem like, not like, startswith, in, = und !=; der Usage Count zusätzlich >, >= und Zahlenlisten mit in.

Die Antwort enthält aktuell nur Objektname und Anzahl der Verwendungen, nicht die abhängigen Konfigurationen. Ein Usage Count von 3 sagt also nicht, welche drei Regeln oder Profile betroffen sind. Vor Update oder Remove deshalb zusätzlich Object usage in WebAdmin beziehungsweise Config Studio prüfen. Ein Count von 0 ist ebenfalls kein Freipass für eine unkontrollierte Löschung: Backup, Abhängigkeitsprüfung und ein enger Test bleiben Pflicht.

Live Users per API an- und abmelden

SFOS kann einen Benutzer per API als Live User an- oder abmelden. Das eignet sich für eine klar verantwortete Integration mit einem externen Authentifizierungssystem, ist aber keine allgemeine Abkürzung, um die normale Benutzeranmeldung zu umgehen. Ein falsch gesetzter Login ordnet Traffic einer Identität zu und kann dadurch benutzerbezogene Firewall- oder Web-Regeln beeinflussen.

Für den ausführenden Administrator muss unter Profiles > Device access > Identity die Berechtigung Manage live users auf Read-write stehen. Der dafür vorgesehene Endpoint lautet:

https://<Firewall-IP-oder-FQDN>:<Port>/xmlapi/v1/authentication/networkuser

Dieser Endpoint verarbeitet An- und Abmeldungen parallel. Der allgemeine APIController kann dieselben Operationen seriell verarbeiten. Eine bestehende Integration sollte deshalb nicht allein wegen des unterschiedlichen Verhaltens ungeprüft umgestellt werden.

Ein Login-Payload kann so aufgebaut sein:

<Request>
  <LiveUserLogin>
    <Admin>
      <UserName>api-liveusers</UserName>
      <Password>ADMIN_SECRET</Password>
    </Admin>
    <UserName>testuser</UserName>
    <IPAddress>192.0.2.25</IPAddress>
    <MacAddress>AA-BB-CC-DD-EE-FF</MacAddress>
  </LiveUserLogin>
</Request>

Zum Abmelden wird derselbe fachliche Benutzer mit LiveUserLogout gesendet:

<Request>
  <LiveUserLogout>
    <Admin>
      <UserName>api-liveusers</UserName>
      <Password>ADMIN_SECRET</Password>
    </Admin>
    <UserName>testuser</UserName>
    <IPAddress>192.0.2.25</IPAddress>
    <MacAddress>AA-BB-CC-DD-EE-FF</MacAddress>
  </LiveUserLogout>
</Request>

api-liveusers, ADMIN_SECRET, testuser, 192.0.2.25 und die MAC-Adresse sind Musterwerte. Benutzername, IP und MAC müssen zur tatsächlichen Sitzung passen. Das Admin-Secret gehört in den geschützten Secret Store und in den HTTP-POST-Body, nicht in eine URL, Shell-History, Protokolldatei oder Collection, die weitergegeben wird.

Nach dem Login muss der Benutzer unter Current activities > Live users mit Client type API client erscheinen. Ein kontrollierter Test prüft danach den erwarteten benutzerbezogenen Regelentscheid. Nach dem Logout darf die Sitzung dort nicht mehr als aktiver API-Client stehen. Bleibt der Benutzer sichtbar, zuerst Payload, Benutzername, IP, MAC und API-Antwort prüfen; keine fremde Live-User-Sitzung auf Verdacht abmelden.

Zertifikate über die API übertragen oder exportieren

Zertifikate sind ein Sonderfall, weil neben XML auch Dateien übertragen werden. Zum Anlegen oder Aktualisieren wird in der Postman-Desktop-App ein form-data-Request mit drei Teilen verwendet: Zertifikatsdatei, Private-Key-Datei und reqxml mit einem <Set><Certificate>...</Certificate></Set>-Payload. Dateinamen, Format, Aktion und Zertifikatsname im XML müssen zu den hochgeladenen Dateien passen.

Private Keys gehören nur auf den geschützten Admin-Endpunkt und dürfen weder in eine Cloud-Collection noch in ein Ticket oder Repository gelangen. Nach Send zuerst <Response> und <Status> auswerten und danach unter Certificates > Certificates prüfen, ob genau das erwartete Zertifikat mit passendem Key und richtiger Kette vorhanden ist. Den vollständigen Automationsweg von der öffentlichen CA über den build-spezifischen Upload bis zur Dienstzuweisung und externen Prüfung beschreibt Sophos Firewall Zertifikat per XML API erneuern und Dienste prüfen. Der manuelle Zuweisungsablauf steht unter Zertifikate auf Sophos Firewall importieren und zuweisen.

Ein <Get><Certificate/></Get> liefert kein normales XML-Ergebnis, sondern ein .tar-Archiv mit Zertifikaten, Private Keys und Entities.xml. Deshalb funktioniert dieser Abruf nicht als normaler Postman-Response. Die spezielle Zertifikatsanleitung dokumentiert HTTP GET aus einer Linux-Kommandozeile oder einem Browser; in beiden Varianten stehen die Credentials im reqxml der URL.

SFOS 23.0: Diese spezielle GET-Anleitung nennt weiterhin Browser, während die POST-Anleitung Browser ausschliesst. Das ist keine Grundlage für ein pauschales Verbot sämtlicher HTTP-GET-Aufrufe, aber auch kein auf dieser Firmware getesteter Browser-Export. Für SFOS 23.0 keinen Browser-Export aus älteren Anleitungen übernehmen und nicht vermuten, dass POST denselben Download liefert. Vor einem benötigten Export den CLI-GET-Weg und die sichere Credential-Handhabung für den installierten Build mit Support oder in einem freigegebenen Testsystem verifizieren; ohne diesen Nachweis den Export nicht ausführen.

Für einen verifizierten Export nur ein temporäres, eng berechtigtes Konto auf einem geschützten Managementhost verwenden, URL und Kommando nicht protokollieren und das Secret danach rotieren. TLS-Zertifikat und Hostname prüfen; die -k-Option der Herstellerbeispiele nicht in Produktionsjobs übernehmen. Auch das Archiv ist hochsensibel: verschlüsselt und zugriffsgeschützt ablegen, kontrolliert extrahieren und nicht benötigte Kopien sicher entfernen.

API-Zugriff und Benutzerrechte

Eine Quell-IP allein ist kein vollständiges Sicherheitskonzept. Die Einschränkung begrenzt nur, von wo die API erreichbar ist. Zusätzlich muss klar sein, mit welchem Konto der API-Zugriff erfolgt und welche Rechte dieses Konto hat.

Für produktive Umgebungen sollte man prüfen:

• Wird ein eigenes API- oder Servicekonto verwendet?
• Hat das Konto nur die benötigten Berechtigungen?
• Ist klar dokumentiert, welche Person oder welches Team für das Konto verantwortlich ist?
• Wird das Passwort oder Secret sicher gespeichert?
• Wird der Zugriff entfernt, wenn die Integration nicht mehr genutzt wird?
• Sind Änderungen über Audit Logs nachvollziehbar?

Geteilte Admin-Konten sind für API-Prozesse problematisch. Wenn mehrere Systeme oder Personen denselben Account verwenden, wird die Nachvollziehbarkeit schwächer. Für Change-Analysen ist Sophos Firewall Audit Trail Logs prüfen relevant.

Für ein dediziertes API-Konto ist ein enger Ablauf besser als ein schnell kopierter Volladmin. Die allgemeine Planung persönlicher Konten und eingeschränkter Profile erklärt Sophos Firewall Administratoren und Profile sicher einrichten; für Automationen bleibt das hier beschriebene separate Servicekonto massgebend. In der Sophos-Dokumentation taucht dafür sinngemäss der Baustein Allow API access to administrators auf: Nicht nur die Quelle wird erlaubt, sondern auch der Administrator beziehungsweise das Profil muss den passenden Zugriff besitzen.

1. Unter Profiles > Device access ein Administratorprofil mit den benötigten Rechten erstellen.
2. Unter Authentication > Users einen Administratorbenutzer für den API-Prozess anlegen.
3. Das passende Administratorprofil zuweisen.
4. Wenn der Zugriff nur temporär gebraucht wird, Access time begrenzen.
5. Wenn möglich Login restriction for device access auf die vorgesehenen Quellen begrenzen.
6. Danach API access und Device Access passend zur Quelle freigeben.

Im offiziellen Beispiel erhält das Profil Read-write für Objects und Network. Das ist keine pauschale Empfehlung: Für reine Leseintegrationen und andere API-Aufgaben bleiben nicht benötigte Bereiche auf None oder Read-only; eine Schreibberechtigung wird erst nach einem kontrollierten Lesetest vergeben.

Sophos unterstützt die offiziellen APIs und unveränderte Beispielskripte. Der technische Sophos Support leistet jedoch keine Beratung oder Fehleranalyse für kundenspezifische Integrationen; Sophos verweist dafür auf den zuständigen Sophos Partner oder Sophos Professional Services. Eigene Integrationen, Wrapper und Automationen brauchen deshalb einen internen Besitzer, Tests und ein Rollback-Konzept. Ein “funktioniert im Lab” reicht für produktive Schreiboperationen nicht.

MFA und API-Benutzer nach SFOS 22

MFA ist für interaktive Administratorzugänge wichtig. Für API- und Automationsprozesse muss man aber bewusst planen, wie Authentifizierung funktionieren soll. Ein Skript, Monitoring-Tool oder Integrationssystem kann nicht ohne Weiteres einen OTP-Code eingeben, wenn der verwendete Benutzer MFA erzwingt.

Die aktuelle Known-Issues-Liste dokumentiert NC-177609 für SFOS 22.0.0 GA Respin Build 411: Nach einem Upgrade können API-basierte Konfigurationsänderungen bei migrierten Benutzern fehlschlagen, wenn MFA aktiv ist und kein One-time Token übergeben wird. Nicht migrierte Benutzer folgen bis zum MFA-Onboarding dem früheren Verhalten. Der offizielle Workaround ist ein eigenes API-Konto ohne MFA beziehungsweise dessen Ausnahme von MFA. Das ist keine Begründung, MFA für interaktive Administratoren abzuschalten; für neuere Builds zuerst Release Notes und Known Issues prüfen.

Empfohlener Ansatz:

1. Für API-Prozesse ein eigenes Servicekonto verwenden.
2. Das Konto nur mit den benötigten Rechten ausstatten.
3. API access zusätzlich auf feste IP Hosts oder Management-Netze begrenzen.
4. Prüfen, ob MFA für dieses Konto technisch und betrieblich sinnvoll ist.
5. Wenn MFA für das API-Konto nicht praktikabel ist, das Konto besonders eng über Quelle, Rechte, Secret-Ablage und Audit Trail kontrollieren.
6. Nach einem SFOS-22-Upgrade alle API-Prozesse mit Lese- und Schreiboperationen testen.

⚠️ API-Benutzer ohne MFA sind kein Freipass für breite Rechte. Wenn ein API-Konto aus technischen Gründen ohne MFA betrieben wird, müssen Quell-IP, Rechte, Passwortablage, Verantwortlichkeit und Auditierbarkeit enger kontrolliert werden.

Besonders wichtig ist dieser Punkt bei Automationen, die nicht nur lesen, sondern Konfiguration ändern.

Vor produktiven API-Änderungen sollte man mindestens drei Dinge prüfen:

• Ein aktuelles Backup der Sophos Firewall ist vorhanden.
• Das geplante API-Konto kann eine ungefährliche Leseabfrage erfolgreich ausführen.
• Bei vorbereiteten Massenänderungen aus Sophos Firewall Config Studio funktionieren die erzeugten API- oder curl-Aufrufe mit dem geplanten Konto.

Abgrenzung zu Device Access

Die API-Zugriffskontrolle ist nicht dasselbe wie Device Access, beide Kontrollen greifen aber ineinander. Device Access steuert lokale Firewall-Dienste wie WebAdmin, SSH, User Portal, VPN Portal, DNS oder Ping. Die API access settings steuern zusätzlich, welche IP Hosts die XML API nutzen dürfen. Wichtig: Die Device-Access-Berechtigungen für die WebAdmin Console gelten auch für API-Zugriffe.

Für die Praxis bedeutet das: API access muss erlaubt sein, die Quelle muss in den API access settings zugelassen sein, und der lokale Managementzugriff zur Firewall darf nicht durch Device Access blockiert werden. Jede Schicht begrenzt einen anderen Teil der Angriffsfläche:

• Device Access richtig konfigurieren: begrenzt lokale Firewall-Dienste wie WebAdmin, SSH, User Portal, VPN Portal, DNS oder Ping.
• API access control: begrenzt die IP Hosts, die die XML API zusätzlich nutzen dürfen.
• MFA für Sophos Firewall WebAdmin, VPN Portal und Remote Access aktivieren: schützt interaktive Logins für WebAdmin, VPN Portal und Remote Access.
• Named Admins und klare Rollen: verbessern Nachvollziehbarkeit und begrenzen den Schadensradius von Admin- und Servicekonten.

Wenn ein Admin-Netz WebAdmin, SSH und API nutzen darf, sollte dieses Netz besonders gut geschützt sein. Ein kompromittierter Client im Management-Netz ist sonst ein direkter Einstieg in die Firewall-Verwaltung.

Bei WAN-Zugriff sollte man nicht die ganze WAN-Zone für HTTPS/WebAdmin öffnen. Wenn externer API- oder Admin-Zugriff wirklich nötig ist, gehört er in eine Local service ACL exception rule mit enger Source, passendem Service HTTPS, definierter Regelposition und dokumentiertem Zeitraum.

HA: Zugriff nach einem Failover prüfen

In einem HA-Cluster wird die Firewall-Konfiguration vom Primary zum Auxiliary synchronisiert; dedizierter HA-Link und Administration Ports sind davon ausgenommen. API-Clients sollten deshalb den vorgesehenen Cluster-Namen beziehungsweise die gemeinsame Schnittstellenadresse verwenden und nicht unbemerkt an einer node-spezifischen Administration-IP hängen.

Nach HA-Einrichtung, Zertifikatswechsel oder Failover je einen Lese- und Negativtest wiederholen. Dabei DNS-Auflösung, Zertifikatsname, Quell-IP, Admin-Port, API access und Device Access kontrollieren. Ein synchronisiertes Host-Objekt allein beweist nicht, dass der komplette Netzwerk- und TLS-Pfad nach dem Rollenwechsel funktioniert.

Betrieb und Review

API-Zugriff sollte regelmässig überprüft werden. Besonders nach Migrationen, Dienstleisterwechseln, Automationsprojekten oder Firewall-Upgrades bleiben oft alte Quellen stehen.

Sinnvolle Review-Fragen:

• Welche IP Hosts dürfen aktuell API access nutzen?
• Gibt es Objekte mit dem Prefix apiconfig?
• Sind diese Objekte noch notwendig?
• Stimmen Namen und Beschreibungen mit dem tatsächlichen Zweck überein?
• Gibt es dokumentierte Verantwortliche?
• Werden API-Zugriffe in einem Change- oder Audit-Prozess berücksichtigt?
• Gibt es ein aktuelles Backup vor grösseren API-basierten Änderungen?

Vor API-basierten Änderungen sollte immer ein Backup vorhanden sein. Der Artikel Sophos Firewall Backup erstellen oder wiederherstellen beschreibt, worauf man bei Backup, Restore und Kompatibilität achten sollte.

Typische Fehler

• API access für ein ganzes Client-Netz erlaubt: Jeder kompromittierte Client aus diesem Netz kann die API erreichen.
• Alte apiconfig Objekte nicht geprüft: Migrierte Altfreigaben bleiben unbemerkt aktiv.
• Servicekonto nutzt volle Adminrechte: Ein kompromittiertes Secret hat unnötig grossen Schadenradius.
• API-Automation nutzt einen MFA-pflichtigen Admin: Skript oder Tool kann nach SFOS-Upgrade bei Schreiboperationen fehlschlagen.
• Falscher Port im Tool: Der Admin-HTTPS-Port wurde geändert, das Tool nutzt aber weiter den alten Port.
• REST-Logik erwartet: Das Tool sendet REST-Methoden statt XML-Payload über HTTP POST an APIController.
• Nur den HTTP-Status geprüft: Die eigentliche API-Operation ist fehlgeschlagen, obwohl der Transport erfolgreich war. <Response> und <Status> auswerten.
• Set ohne Operation gesendet: SFOS behandelt den Request als add, obwohl eine Aktualisierung geplant war.
• MFA-Einstellungen oder Token lassen sich nicht importieren: Im Payload muss das leere Element <tokenid/> enthalten sein.
• Benutzer lässt sich nicht löschen: Im <Remove>-Payload den exakten Benutzernamen als <Name>username</Name> angeben. Vor dem Request Konto, Abhängigkeiten, Backup und Rollback kontrollieren.
• Usage Count als vollständige Abhängigkeit verstanden: Die Statistik liefert Anzahl und Name, aber nicht die betroffenen Regeln oder Profile.
• Live User ohne Sitzungsabgleich angemeldet: Benutzername, IP und MAC passen nicht zur wirklichen Sitzung; benutzerbezogene Regeln können dadurch falsch entscheiden.
• Zertifikatsarchiv ungeschützt abgelegt: Der API-Export kann Private Keys enthalten und gehört nicht in Downloads, Tickets oder gemeinsame Ablagen.
• Temporäre Dienstleister-IP bleibt aktiv: Externer Zugriff bleibt länger möglich als geplant.
• Keine Dokumentation zum Zweck: Spätere Admins wissen nicht, ob eine Freigabe noch gebraucht wird.
• API-Änderungen ohne Backup: Fehlerhafte Automatisierung ist schwerer zurückzurollen.

Troubleshooting

Wenn ein Tool die XML API nicht erreicht, sollte man strukturiert prüfen:

1. Stimmt die Quell-IP aus Sicht der Firewall?
2. Ist die Quelle als IP Host, IP range oder Netzwerk erlaubt?
3. Wurde nach einem Upgrade ein apiconfig Objekt erzeugt, aber nicht passend angepasst?
4. Erlaubt Device Access den lokalen WebAdmin/API-Zugriff aus dieser Zone?
5. Verwendet das Tool die richtige Firewall-Adresse und den richtigen Admin-HTTPS-Port?
6. Stimmen Benutzername, Passwort oder Secret?
7. Hat das Konto die benötigten Rechte?
8. Erzwingt das Konto MFA, obwohl das Tool keinen One-time Token übergeben kann?
9. Gibt es Routing-, NAT- oder Proxy-Effekte zwischen Tool und Firewall?
10. Wurde der Zugriff absichtlich durch eine Härtungsmassnahme entfernt?
11. Wurde vom richtigen Quellsystem getestet oder nur vom Admin-Client?

Wenn eine API-Änderung unerwartete Auswirkungen hat, zuerst das letzte Backup sichern und danach Audit Trail, Config Studio Vergleich und betroffene Firewall-Objekte prüfen. Bei Live-Traffic-Problemen helfen Log Viewer und Packet Capture eher als die API selbst.

Bei einer abgelehnten oder fehlerhaften XML-Operation immer zuerst <Response> und <Status> sichern. Danach unter Diagnostics > Troubleshooting logs apiparser.log sowie validation.log und validationError.log prüfen; Sophos ordnet diese Dateien der API-Übersetzung beziehungsweise API-Validierung zu. Der Ablauf zum Filtern und Exportieren steht unter Sophos Firewall Service- und Logdateien. Secrets vor dem Teilen eines Logausschnitts entfernen.

Checkliste

Vor Aktivierung:

• Zweck des API-Zugriffs dokumentieren.
• Quellsystem eindeutig bestimmen.
• IP Host Objekt mit sprechendem Namen erstellen.
• Servicekonto und Berechtigungen prüfen.
• MFA-Verhalten des API-Kontos bewusst festlegen.
• Backup- und Rollback-Prozess festlegen.
• Testmethode ohne Secret-Leak festlegen.
• Geplante XML-Operation und erwarteten <Status> dokumentieren.

Beim Betrieb:

• API access nur für definierte Quellen erlauben.
• Keine breiten Client-, Gast- oder IoT-Netze freigeben.
• apiconfig Objekte nach Upgrades prüfen.
• Dienstleisterzugänge zeitlich und fachlich kontrollieren.
• Secrets geschützt speichern und bei Personal- oder Toolwechsel erneuern.
• Secrets rotieren, wenn sie in Shell-History, Tickets oder unsicheren Ablagen gelandet sind.
• API-Lese- und Schreiboperationen nach SFOS-Upgrades gezielt testen.
• Vor Update oder Remove die Object Usage und abhängigen Konfigurationen prüfen.
• API-basierte Live-User-Anmeldungen mit API client, Regelentscheidung und sauberem Logout abnehmen.
• Zertifikatsdateien, Private Keys und API-Exporte nur geschützt verarbeiten.

Beim Review:

• Erlaubte API-Quellen regelmässig prüfen.
• Nicht mehr benötigte IP Hosts entfernen.
• Änderungen mit Audit Trail und Change-Tickets abgleichen.
• Automationsprozesse nach Firmware-Updates testen.

FAQ