Sophos Central Endpoint API sicher automatisieren
Die Sophos Central API eignet sich für wiederkehrende Inventarisierung, kontrollierte Massenänderungen und die Anbindung an eigene Betriebsprozesse. Sie ist jedoch kein zweites, folgenloses Reporting-Interface. Je nach Rolle kann eine Anwendung Endpoints scannen, Gruppen verändern, Policies bearbeiten, Software zuweisen, Geräte migrieren oder Live-Discover-Abfragen starten.
Eine sichere Automation beginnt deshalb mit drei Fragen: Welcher Tenant ist betroffen, welche kleinste Berechtigung wird benötigt und wie lässt sich jede Änderung nachweisen und zurücknehmen?
API Credentials als eigene Identität
Unter Global Settings > Access Control > API Credentials erstellt ein Super Admin einen Service Principal. Name und Beschreibung nennen Anwendung, Verantwortlichen, Zweck und Ablaufdatum. Persönliche Administrator-Credentials oder ein Super-Admin-Konto gehören nicht in Skripte.
Sophos stellt mehrere Rollen bereit. Für Endpoint-Aufgaben sind vor allem diese relevant:
| Rolle | Geeigneter Zweck | Wichtige Grenze |
|---|---|---|
| Service Principal Read-Only | Inventar, Status und Reporting | keine Änderungen, keine Live-Discover-Queries |
| Service Principal Management | Geräte, Benutzer, Policies und Schutzverwaltung | keine Forensik-Queries |
| Service Principal Forensics | Live Discover | keine allgemeine Endpoint-Verwaltung |
| Service Principal Active Directory Sync | AD-Synchronisation | ausschliesslich Verzeichnissynchronisation |
| Service Principal Super Admin | Sonderfälle mit ausdrücklich benötigtem Vollzugriff | grösster möglicher Schaden bei Missbrauch |
Der Client Secret wird nur einmal angezeigt und sofort in einem Secret Store abgelegt. Sophos versendet keine Warnung vor dem Ablauf eines API Credential. Nach Ablauf wird der Eintrag automatisch entfernt und die Anwendung kann sich erst mit neu erstellten Credentials wieder anmelden. Ablaufüberwachung und Rotation müssen daher ausserhalb von Central stattfinden.
Legacy API Tokens für die SIEM Integration API werden abgelöst. Bestehende Tokens funktionieren nur bis zu ihrem Ablauf; neue Integrationen verwenden API Credentials.
Authentifizierung und richtiger API-Host
Sophos verwendet OAuth2 mit dem Client-Credentials-Flow. Die Anwendung sendet Client ID und Client Secret an den Sophos-ID-Endpunkt und erhält ein zeitlich begrenztes Bearer Token. Das Token, der Secret und vollständige Request-Header werden weder in Tickets noch in ungeschützte Logs geschrieben.
Nach der Anmeldung wird zuerst die globale Who-Am-I-Schnittstelle abgefragt. Ihre Antwort liefert die Tenant-ID und den API-Host der Datenregion. Erst danach ruft die Anwendung einen regionalen Endpoint wie api-eu01.central.sophos.com oder api-eu02.central.sophos.com auf. Der regionale Request benötigt zusätzlich zum Bearer Token den Header X-Tenant-ID.
Für eine manuelle Kontrolle zeigt Central die Region auch unter Profile > Support settings. Alternativ lässt sie sich im Hostnamen eines Installer-Downloadlinks erkennen. Automationen verwenden trotzdem Who Am I, weil eine aus der Oberfläche abgelesene Region kein belastbarer Multi-Tenant-Mechanismus ist.
Wichtig: Die Region wird nicht aus dem Firmenstandort oder der Sprache abgeleitet. Ein fest im Skript eingetragener Host kann beim nächsten Tenant falsch sein. Who Am I beziehungsweise die Tenant-Liste ist die verbindliche Quelle.
Partner- und Enterprise-Automationen arbeiten mit mehreren Tenants. Sie ermitteln zuerst Partner- oder Organisations-ID, lesen alle Tenants inklusive Datenregion und führen den eigentlichen Request anschliessend für jeden Tenant mit dessen regionalem Host und Tenant-ID aus.
Was die Endpoint APIs abdecken
Die offiziellen Schnittstellen umfassen unter anderem:
- Geräte inventarisieren und Aktionen wie einen Scan auslösen,
- Endpoint-Gruppen erstellen, ändern und Geräte zuordnen,
- zusätzliche Policies erstellen, klonen, priorisieren und Einstellungen ändern,
- Protection, Device Encryption oder ZTNA als Gerätesoftware zuweisen,
- verfügbare Recommended-, Fixed-, LTS- und Support-Pakete abfragen,
- Geräte mit Key-Value-Tags organisieren,
- Endpoint-Migrationen zwischen Tenants steuern,
- Account-Health-Ergebnisse lesen und unterstützte Korrekturen auslösen,
- Audit Events, Alerts, XDR Cases und Detections auswerten,
- gespeicherte oder eigene Live-Discover-Queries starten.
Nicht jede Lizenz und nicht jede Rolle kann jede Operation ausführen. Vor einer schreibenden Automation wird mit einem Read-Only-Aufruf geprüft, ob Tenant, Objekt-IDs, Lizenz und erwarteter Ist-Zustand zusammenpassen.
Einige APIs haben enger gefasste Grenzen als ihre Bezeichnung vermuten lässt. Die Cases API kann derzeit nur selbstverwaltete Cases erstellen und verändern. Für sie nennt Sophos zusätzlich ein weiches Limit von 100 Requests pro Tenant und 24 Stunden sowie 10 Requests pro Benutzer und Minute. Beim Abruf der Case-Detections führt eine Seitengrösse über 50 zu 400 Bad Request. Die Endpoint Software API kann nur Pakete für Windows-Computer und -Server anzeigen und verlangt aktuell die Rolle Service Principal Super Admin. Solche API-spezifischen Voraussetzungen werden vor der Implementierung in der jeweiligen Referenz geprüft und nicht aus den allgemeinen Rollen oder Limits abgeleitet.
Gruppen, Tags und Softwarezuweisung
Gruppen bleiben das Mittel für Policy-Zuweisungen. Tags ergänzen sie für Inventar, Suche und externe Workflows. Ein Tag besteht aus einem Key und einem optionalen Wert. Key und Wert dürfen je höchstens 40 Zeichen enthalten und keinen Doppelpunkt verwenden. Pro Endpoint sind höchstens 15 Tags möglich, und derselbe Key kann auf einem Gerät nur einen Wert besitzen.
Ein Tag- oder Software-Request kann bis zu 1'000 Endpoint-UUIDs enthalten. Eine HTTP-200-Antwort bedeutet bei Bulk-Operationen nicht zwingend, dass jedes Objekt geändert wurde. Die Anwendung wertet deshalb auch Teilfehler pro Gerät aus und wiederholt nicht blind den gesamten Auftrag.
Bei der Device-Software-API sind Protection, Encryption und ZTNA getrennte Kategorien. All weist nur innerhalb der angegebenen Kategorie die höchste lizenzierte Variante zu, None entfernt nur diese Kategorie. Die verfügbaren Software-IDs werden am konkreten Endpoint abgefragt; sie sind case-sensitive und hängen von Lizenz sowie Gerätekatalog ab.
Policies nicht wie Textdateien behandeln
Die Endpoint Policy API kann Base Policies und zusätzliche Policies lesen. Zusätzliche Policies lassen sich erstellen, klonen, aktualisieren und löschen. Bei der Base Policy können nur die Einstellungen verändert werden, nicht Name, Priorität oder Aktivierungsstatus.
Vor einem Update werden Policy-Typ, aktuelle Priorität, Zuweisungen und vorhandene Einstellungen gesichert. Ein PATCH enthält nur bewusst veränderte Schlüssel. Eine Automation darf unbekannte oder neu von Sophos ergänzte Einstellungen nicht durch ein altes vollständiges Objekt überschreiben.
Schreibende Policy-Requests besitzen zusätzliche Rate Limits pro Tenant. Eine erfolgreiche Syntax beweist zudem nicht, dass die Änderung betrieblich verträglich ist. Wie in der GUI werden Pilotgruppe, Change-Fenster, Audit Log und Rollback benötigt.
Pagination, Rate Limits und Wiederholungen
Listen müssen vollständig über alle Seiten gelesen werden. Sophos APIs verwenden je nach Schnittstelle Offset- oder Key-basierte Pagination. Ein Skript, das nur die erste Antwortseite verarbeitet, kann einen unvollständigen Bestand als vollständig melden.
Für die API-Nutzung nennt Sophos als Richtwerte beziehungsweise Grenzen 10 Requests pro Sekunde, 100 pro Minute, 1'000 pro Stunde und 200'000 pro Tag. Einzelne APIs können strengere Grenzen besitzen. Bei 429 Too Many Requests und vorübergehenden 5xx-Fehlern wird mit exponentiellem Backoff und zufälligem Jitter erneut versucht. Bei Authentifizierungs-, Berechtigungs- oder Validierungsfehlern ist eine unveränderte Endlosschleife falsch.
Jeder Lauf protokolliert mindestens Tenant-ID, Operation, Objektanzahl, erfolgreiche und fehlgeschlagene IDs, Request-Zeitpunkt und eine eigene Korrelations-ID. Secrets, Bearer Tokens und sensible Response-Inhalte werden aus den Logs entfernt.
Sicherer Einführungsablauf
Eine neue Automation startet mit einem Testtenant oder einer kleinen Pilotgruppe. Zuerst läuft derselbe Workflow nur lesend und erzeugt einen nachvollziehbaren Plan. Danach wird genau eine kontrollierte Änderung durchgeführt und sowohl über die API als auch in Central am Gerät, an der effektiven Policy und im Audit Log verifiziert.
Erst wenn Teilfehler, Pagination, Rate Limits, Credential-Ablauf und Rollback getestet sind, wird der Umfang erweitert. Für einmalige Projekte werden API Credentials nach Abschluss gelöscht; dauerhafte Integrationen erhalten Owner, Rotation, Monitoring und einen dokumentierten Abschaltweg.
Verwandte Artikel
Die konkrete Endpoint-Migration zwischen Central-Tenants verwendet einen eigenen Receiving- und Sending-Workflow. Für Endpoint-Gruppen und Gerätebestand, Policy-Reihenfolge und Live Discover gelten dieselben fachlichen Regeln unabhängig davon, ob die Änderung per GUI oder API erfolgt.