Sophos Central Endpoint API veilig automatiseren
De Sophos Central API is geschikt voor terugkerende inventarisatie, gecontroleerde bulkwijzigingen en integratie met eigen beheerprocessen. Het is echter geen tweede reporting-interface zonder gevolgen. Afhankelijk van de rol kan een toepassing endpoints scannen, groepen wijzigen, beleidsregels bewerken, software toewijzen, apparaten migreren of Live Discover-query’s starten.
Veilige automatisering begint daarom met drie vragen: welke tenant is betrokken, welke minimale machtiging is nodig en hoe kan elke wijziging worden aangetoond en teruggedraaid?
API Credentials als eigen identiteit
Onder Global Settings > Access Control > API Credentials maakt een Super Admin een Service Principal aan. Naam en beschrijving vermelden toepassing, verantwoordelijke, doel en vervaldatum. Persoonlijke beheerdersreferenties of een Super-Admin-account horen niet in scripts.
Sophos biedt meerdere rollen. Voor Endpoint-taken zijn vooral deze relevant:
| Rol | Geschikt doel | Belangrijke beperking |
|---|---|---|
| Service Principal Read-Only | inventaris, status en rapportage | geen wijzigingen, geen Live Discover-query’s |
| Service Principal Management | apparaten, gebruikers, beleidsregels en beveiligingsbeheer | geen forensische query’s |
| Service Principal Forensics | Live Discover | geen algemeen Endpoint-beheer |
| Service Principal Active Directory Sync | AD-synchronisatie | uitsluitend directorysynchronisatie |
| Service Principal Super Admin | uitzonderingen waarvoor volledige toegang expliciet nodig is | grootst mogelijke schade bij misbruik |
De Client Secret wordt slechts één keer weergegeven en onmiddellijk in een Secret Store opgeslagen. Sophos verstuurt geen waarschuwing voordat een API Credential verloopt. Na afloop wordt de vermelding automatisch verwijderd en kan de toepassing zich pas weer aanmelden met nieuw aangemaakte credentials. Bewaking van de geldigheid en rotatie moeten daarom buiten Central plaatsvinden.
Legacy API Tokens voor de SIEM Integration API worden vervangen. Bestaande tokens werken alleen tot hun vervaldatum; nieuwe integraties gebruiken API Credentials.
Authenticatie en de juiste API-host
Sophos gebruikt OAuth2 met de Client Credentials Flow. De toepassing stuurt Client ID en Client Secret naar het Sophos ID-endpoint en ontvangt een tijdelijk Bearer Token. Het token, de secret en volledige requestheaders worden niet in tickets of onbeveiligde logs geschreven.
Na de aanmelding wordt eerst de globale Who-Am-I-interface opgevraagd. Het antwoord bevat de tenant-ID en de API-host van de dataregio. Pas daarna roept de toepassing een regionaal endpoint aan, zoals api-eu01.central.sophos.com of api-eu02.central.sophos.com. Naast het Bearer Token vereist het regionale request de header X-Tenant-ID.
Voor een handmatige controle toont Central de regio ook onder Profile > Support settings. De regio is eventueel ook te herkennen aan de hostname van een downloadlink voor de installer. Automatiseringen gebruiken desondanks Who Am I, omdat een uit de interface afgelezen regio geen betrouwbaar multi-tenantmechanisme is.
Belangrijk: De regio wordt niet afgeleid van de bedrijfslocatie of taal. Een vast in het script opgenomen host kan bij de volgende tenant onjuist zijn. Who Am I of de tenantlijst is de bindende bron.
Partner- en Enterprise-automatiseringen werken met meerdere tenants. Ze bepalen eerst de partner- of organisatie-ID, lezen alle tenants inclusief dataregio en voeren het eigenlijke request daarna per tenant uit met diens regionale host en tenant-ID.
Wat de Endpoint API’s afdekken
De officiële interfaces omvatten onder meer:
- apparaten inventariseren en acties zoals een scan starten,
- Endpoint-groepen maken, wijzigen en apparaten toewijzen,
- aanvullende beleidsregels maken, klonen, prioriteren en instellingen wijzigen,
- Protection, Device Encryption of ZTNA als apparaatsoftware toewijzen,
- beschikbare Recommended-, Fixed-, LTS- en Support-pakketten opvragen,
- apparaten met key-value-tags organiseren,
- Endpoint-migraties tussen tenants aansturen,
- Account Health-resultaten lezen en ondersteunde correcties starten,
- Audit Events, Alerts, XDR Cases en Detections evalueren,
- opgeslagen of eigen Live Discover-query’s starten.
Niet elke licentie en rol kan elke bewerking uitvoeren. Voor een schrijvende automatisering wordt met een Read-Only-request gecontroleerd of tenant, object-ID’s, licentie en verwachte huidige toestand overeenkomen.
Sommige APIs hebben beperktere grenzen dan hun naam doet vermoeden. De Cases API kan momenteel alleen self-managed cases maken en wijzigen. Sophos noemt daarnaast een soft limit van 100 requests per tenant per 24 uur en 10 requests per gebruiker per minuut. Bij het ophalen van case detections levert een page size boven 50 een 400 Bad Request op. De Endpoint Software API kan alleen packages voor Windows-computers en -servers tonen en vereist momenteel de rol Service Principal Super Admin. Controleer zulke API-specifieke voorwaarden vóór implementatie in de betreffende reference en leid ze niet af uit algemene rollen of limieten.
Groepen, tags en softwaretoewijzing
Groepen blijven het middel voor beleidstoewijzingen. Tags vullen ze aan voor inventaris, zoeken en externe workflows. Een tag bestaat uit een key en een optionele waarde. Key en waarde mogen elk maximaal 40 tekens bevatten en geen dubbele punt gebruiken. Per endpoint zijn maximaal 15 tags mogelijk en dezelfde key kan op een apparaat slechts één waarde hebben.
Een tag- of software-request kan maximaal 1'000 Endpoint-UUID’s bevatten. Een HTTP-200-antwoord betekent bij bulkbewerkingen niet noodzakelijk dat elk object is gewijzigd. De toepassing verwerkt daarom ook de gedeeltelijke fouten per apparaat en herhaalt niet blind de volledige opdracht.
Bij de Device Software API zijn Protection, Encryption en ZTNA afzonderlijke categorieën. All wijst alleen binnen de opgegeven categorie de hoogst gelicentieerde variant toe, None verwijdert alleen die categorie. De beschikbare software-ID’s worden op het concrete endpoint opgevraagd; ze zijn case-sensitive en hangen af van licentie en apparaatcatalogus.
Beleidsregels niet als tekstbestanden behandelen
De Endpoint Policy API kan Base Policies en aanvullende beleidsregels lezen. Aanvullende beleidsregels kunnen worden gemaakt, gekloond, bijgewerkt en verwijderd. Bij de Base Policy kunnen alleen de instellingen worden gewijzigd, niet de naam, prioriteit of activeringsstatus.
Voor een update worden beleidstype, huidige prioriteit, toewijzingen en bestaande instellingen opgeslagen. Een PATCH bevat alleen bewust gewijzigde keys. Een automatisering mag onbekende of nieuw door Sophos toegevoegde instellingen niet overschrijven met een oud volledig object.
Schrijvende policy-requests hebben aanvullende Rate Limits per tenant. Een syntactisch geslaagd request bewijst bovendien niet dat de wijziging operationeel verantwoord is. Net als in de GUI zijn een pilotgroep, wijzigingsvenster, Audit Log en rollback nodig.
Paginering, Rate Limits en herhalingen
Lijsten moeten volledig over alle pagina’s worden gelezen. Sophos API’s gebruiken afhankelijk van de interface offset- of key-based paginering. Een script dat alleen de eerste antwoordpagina verwerkt, kan een onvolledige inventaris als volledig rapporteren.
Voor API-gebruik noemt Sophos als richtwaarden of limieten 10 requests per seconde, 100 per minuut, 1'000 per uur en 200'000 per dag. Afzonderlijke API’s kunnen strengere limieten hebben. Bij 429 Too Many Requests en tijdelijke 5xx-fouten wordt opnieuw geprobeerd met exponentiële back-off en willekeurige jitter. Bij authenticatie-, machtigings- of validatiefouten is een ongewijzigde oneindige lus onjuist.
Elke uitvoering registreert minimaal tenant-ID, bewerking, aantal objecten, geslaagde en mislukte ID’s, requesttijdstip en een eigen correlatie-ID. Secrets, Bearer Tokens en gevoelige response-inhoud worden uit de logs verwijderd.
Veilige introductieprocedure
Een nieuwe automatisering begint met een testtenant of kleine pilotgroep. Eerst draait dezelfde workflow uitsluitend lezend en maakt hij een controleerbaar plan. Daarna wordt exact één gecontroleerde wijziging uitgevoerd en zowel via de API als in Central op het apparaat, in het effectieve beleid en in het Audit Log geverifieerd.
Pas nadat gedeeltelijke fouten, paginering, Rate Limits, het verlopen van credentials en rollback zijn getest, wordt de scope uitgebreid. Voor eenmalige projecten worden API Credentials na afloop verwijderd; permanente integraties krijgen een eigenaar, rotatie, bewaking en gedocumenteerde uitschakelprocedure.
Gerelateerde artikelen
De concrete Endpoint-migratie tussen Central-tenants gebruikt een eigen Receiving- en Sending-workflow. Voor Endpoint-groepen en apparaatinventaris, beleidsvolgorde en Live Discover gelden dezelfde inhoudelijke regels, ongeacht of de wijziging via GUI of API plaatsvindt.