De Sophos Fusion Endpoint API veilig automatiseren

De Sophos Fusion Endpoint API is de tenant-API voor endpoint- en serverresources. De API inventariseert apparaten en kan, afhankelijk van endpoint en machtiging, scans, isolatie, groepen, beleidsregels, uitzonderingen, tags en softwaretoewijzingen beheren. Schrijftoegang beïnvloedt de beveiliging; voor inventarisatie volstaat een Read-Only-identiteit.

De veilige korte route: gebruik een API Credential met de minimale rol, verkrijg een token via de OAuth2 Client Credentials Flow, ontdek tenant-ID en regionale host, test eerst GET /endpoint/v1/endpoints en verwerk alle pagina’s en fouten.

Grens met Sophos Fusion Admin en andere API’s

Service Principals maken, opslaan, roteren en verwijderen is een gedeelde Sophos Fusion Admin-taak. De volledige procedure staat daarom in Sophos Fusion API Credentials veilig beheren en wordt hier niet herhaald.

Tenantlijsten van Partner en Organization, Alerts, Audit Events, Account Health, Cases en Live Discover behoren evenmin automatisch tot de Endpoint API. Sophos Fusion biedt hiervoor afzonderlijke API’s met eigen rollen en limieten. Dit artikel behandelt uitsluitend requests onder het regionale basispad /endpoint/v1.

Authenticatie en requestcontext

Het gekoppelde Owner-artikel definieert exclusief het tokenrequest en responsecontract, whoami, Partner-/Enterprise-tenantlijsten, hostvalidatie en secretbehandeling. Neem SOPHOS_ACCESS_TOKEN, SOPHOS_TENANT_ID en SOPHOS_API_HOST ongewijzigd over. scope=token vervangt autorisatie niet: Service Principal-rol, tenanttoegang, licentie en Endpoint-machtiging gelden eveneens; Partner Assistance of Enterprise Admin Management moet de doeltenant toestaan.

Een onschadelijke leesaanroep uitvoeren

Dit voorbeeld verzint geen token of tenantgegevens. Het verwacht drie waarden uit het eigen credential- en discoveryproces en schrijft de eerste pagina naar een lokaal bestand:

: "${SOPHOS_ACCESS_TOKEN:?Bearer token is missing}"
: "${SOPHOS_TENANT_ID:?Tenant ID is missing}"
: "${SOPHOS_API_HOST:?Regional API host is missing}"
umask 077

curl --fail-with-body --silent --show-error --get \
  "${SOPHOS_API_HOST}/endpoint/v1/endpoints" \
  --header "X-Tenant-ID: ${SOPHOS_TENANT_ID}" \
  --data-urlencode "pageSize=50" \
  --output endpoints-page.json \
  --config - <<EOF
header = "Authorization: Bearer ${SOPHOS_ACCESS_TOKEN}"
EOF

Neem SOPHOS_API_HOST ongewijzigd over uit whoami of de tenantlijst. Lever het token vanuit een Secret Store aan het proces; plaats het niet in het script, de Shell History, opdrachtregelargumenten, tickets of Debug Logs. De configuratie via standaardinvoer houdt de uitgewerkte Bearer Header buiten de argumentenlijst van curl; umask 077 beperkt de rechten van het nieuwe uitvoerbestand. --fail-with-body maakt een HTTP-fout zichtbaar, maar bescherm het bestand nog steeds als mogelijk gevoelige inventarisdata.

Een geslaagde HTTP-status bevestigt alleen het request. Controleer daarna geldige JSON, de verwachte tenant en aanwezigheid van de benodigde apparaten. Er wordt geen verzonnen response getoond die voor een waargenomen resultaat kan worden aangezien.

Endpointpaden bewust kiezen

Endpoint v1 omvat onder meer deze paden:

• GET /endpoint/v1/endpoints en GET /endpoint/v1/endpoints/{endpointId} voor inventaris en details;
• POST /endpoint/v1/endpoints/{endpointId}/scans om een scan aan te vragen;
• POST /endpoint/v1/endpoints/tamper-protection voor gerichte Tamper Protection-wijzigingen op maximaal 200 apparaten;
• POST /endpoint/v1/endpoints/reset-health voor een health-/alert-reset op maximaal 500 ondersteunde apparaten;
• /endpoint/v1/endpoint-groups voor computer- en servergroepen;
• /endpoint/v1/policies voor Endpoint-, Server- en Device Encryption-beleid;
• POST /endpoint/v1/tags/assignment voor tagtoewijzingen;
• endpoints voor isolatie, toegestane of geblokkeerde items, uitzonderingen, Web Control, softwarepakketten en endpointmigraties.

Gebruik de HTTP-methode en het volledige pad hierboven; vervang ze niet door oudere paden met een vergelijkbare naam. Controleer vóór schrijven requestschema, vereiste rol en toestemming, platform- en licentiegrens, statuscodes en bewerkingsspecifieke Rate Limit.

Tamper Protection en health gericht wijzigen met bulkrequests

De twee bulkbewerkingen vullen bestaande Endpoint v1-aanroepen aan; ze verplichten niet tot een migratie. Beide gebruiken de vastgestelde regionale host, het bearer-token, de X-Tenant-ID van de doeltenant en Content-Type: application/json. Voor beide is de machtiging endpoint-state:update vereist. Een alleen-lezen-identiteit volstaat niet; controleer vooraf of de Service Principal-rol deze machtiging in de doeltenant omvat.

Tamper Protection: De JSON-body voor POST /endpoint/v1/endpoints/tamper-protection bevat ids met 1–200 unieke endpoint-UUID’s en minstens één van de booleaanse velden enabled of regeneratePassword. enabled: true vraagt inschakeling aan, enabled: false uitschakeling. regeneratePassword: true vraagt nieuwe apparaatwachtwoorden aan. Het schema gebruikt anyOf, niet oneOf: beide velden mogen dus ook samen worden verstuurd. Plan voor traceerbare onderhoudswijzigingen toestandswijzigingen en wachtwoordregeneratie toch afzonderlijk en verstuur alleen de bedoelde velden. Wachtwoordregeneratie is geen lokale vieruurs-override en levert ook geen gedeeld wachtwoord voor alle apparaten op.

Vóór uitschakeling: Gebruik alleen de goedgekeurde ID-set en leg per apparaat de begintoestand, het onderhoudseinde en de verantwoordelijke persoon vast. Voor uitschakeling via de API is geen automatische terugkeer na vier uur gedocumenteerd. Vraag na het onderhoud inschakeling aan voor precies de uitgeschakelde apparaten en controleer het effect. De lokale en apparaatgerichte onderhoudsmethoden blijven voor afzonderlijke apparaten vaak de betere keuze.

Lees vooraf GET /endpoint/v1/endpoints/{endpointId}?view=full en neem alleen apparaten op waarvoor tamperProtectionSupported: true is bevestigd; een ontbrekende waarde is geen toestemming. De Windows/Linux-afbakening van de health-reset betekent niet dat Tamper Protection die platforms ondersteunt. Controleer de globale schakelaar met GET /endpoint/v1/settings/tamper-protection: als die uitstaat, herstelt inschakeling van afzonderlijke apparaten de bescherming niet. GET /endpoint/v1/endpoints/{endpointId}/tamper-protection retourneert de beoogde toestand enabled, maar ook password en eventueel previousPasswords. Log dit antwoord niet volledig. Wachtwoorden horen niet in tickets of debuglogs; een rotatie kan niet ongedaan worden gemaakt door het oude wachtwoord terug te schrijven.

Reset Health: POST /endpoint/v1/endpoints/reset-health verwacht een JSON-body met het verplichte veld ids: 1–500 unieke endpoint-UUID’s. Windows-computers, Windows-servers en Linux worden ondersteund, macOS niet.

Vóór de reset: De bewerking zet de health-status op groen en verwijdert alle alerts van de betrokken endpoints. Bewaar relevante bevindingen, alertdetails en auditbewijs daarom vooraf buiten de weergave die wordt leeggemaakt en laat de verwijdering expliciet goedkeuren. De reset verwijdert geen malware en repareert geen defecte beveiligingsservice. Een groene status na deze ingreep bewijst niet dat de oorzaak is verholpen; het resetcontract biedt geen undo-bewerking om verwijderde alerts terug te halen.

Lees na een goedgekeurd pilotrequest de apparaatdetails opnieuw, controleer health-status en alerts in Sophos Fusion en toets de daadwerkelijke beveiligingsfunctie afzonderlijk. Onderzoek nieuwe alerts opnieuw in plaats van ze met herhaalde resets te verbergen.

Geaccepteerd is nog niet uitgevoerd

Voor beide bulkbewerkingen betekent HTTP 202 alleen dat het request is verwerkt en de acceptatie per ID is beoordeeld. items bevat geaccepteerde aanvragen met id, status: requested en requestedAt; errors bevat afgewezen aanvragen met id, errorCode en errorMessage. requestedAt is geen voltooiingstijdstip. Vergelijk iedere verstuurde ID met deze resultaten; ontbrekende of tegenstrijdige koppelingen blijven onopgelost, ook als de HTTP-status succes aangeeft.

De foutcodes zijn notFound, notSupported, conflict, permissionDenied en internalError. Corrigeer bij de eerste vier eerst de ID/tenant, apparaatondersteuning, toestand of machtiging, afhankelijk van de fout. Ook internalError geeft geen toestemming om de hele batch opnieuw te versturen. Beoordeel bij HTTP-fouten het foutantwoord; een 202 kan zowel geaccepteerde als afgewezen ID’s bevatten.

Bevestig het effect daarna afzonderlijk: lees na succesvol apparaatcontact endpointdetails met view=full en bij Tamper Protection ook de instellingen, en controleer vervolgens de bescherming lokaal. Beoordeel daarbij lastSeenAt, tamperProtectionEnabled of, afhankelijk van de bewerking, health.overall, health.threats en health.services. Alleen een teruggelezen gewenste toestand bevestigt nog geen uitvoering op een offline apparaat. Stel een begrensd controle-interval en een totale afbreektijd in; documenteer de uitvoering zonder bevestiging als openstaand en onderzoek apparaatcontact of fouten.

Na een timeout of verbroken verbinding kan een schrijfrequest al zijn geaccepteerd. Herhaal het niet blind: vergelijk eerst toestand en beschikbaar bewijs per ID. Anders kan een volgende wachtwoordrotatie of alert-reset inmiddels ontstane toestanden wijzigen. Keur alleen een nieuwe poging goed voor aantoonbaar afgewezen subsets die na correctie veilig herhaalbaar zijn; houd onopgeloste ID’s apart voor handmatige controle.

Groepen, tags, software en beleid

Groepen sturen beleidstoewijzing en blijven binnen de tenanthiërarchie. Tags vullen inventaris en zoeken aan. Een tagkey telt 1–40 tekens en een waarde 0–40, beide zonder dubbele punt. Per endpoint zijn maximaal 15 tags mogelijk en één key kan maar één waarde hebben. Eén request accepteert maximaal 1.000 endpoint-UUID’s en kan gedeeltelijke fouten per endpoint teruggeven; de client moet daarom elke geretourneerde endpointstatus beoordelen.

Bij Device Software zijn Protection, Encryption en ZTNA afzonderlijke categorieën. Computers ondersteunen alle drie; servers in deze workflow alleen Protection. Elk computer- of server-blok accepteert maximaal 1.000 ID’s. Geldige software-ID’s hangen af van endpoint, catalogus en licentie. Gebruik alleen ID’s die een eerdere leesaanroep voor precies dat endpoint heeft teruggegeven; pas All, None of gegiste ID’s niet zonder validatie toe.

Bewaar bij beleidsregels type, instellingen, toewijzingen en prioriteit vóór een wijziging. Base Policies en aanvullende beleidsregels ondersteunen niet dezelfde bewerkingen. Wijzig alleen velden die het actuele tenantobject als schrijfbaar en niet vergrendeld toont. Een PATCH bevat alleen bewust gecontroleerde keys; een oud volledig object mag later toegevoegde instellingen niet overschrijven.

Paginering, limieten en foutafhandeling

Endpointlijsten gebruiken key-based paginering: laad de eerste pagina zonder pageFromKey en volgende pagina’s met pages.nextKey uit het vorige antwoord. Andere Endpoint-resources gebruiken paginanummers. Het maximum van pageSize verschilt: endpoints hebben standaard 50, Endpoint Groups maximaal 500. Volg het schema en stop pas zonder volgende key of pagina.

De globale Sophos Fusion API-limieten zijn:

• 10 aanroepen per seconde: aanbevolen;
• 100 per minuut: afgedwongen, korte bursts tot 300 toegestaan;
• 1.000 per uur: aanbevolen;
• 200.000 per dag: afgedwongen.

Strengere operationspecifieke limieten gaan voor. Sophos past de eerste drie afzonderlijk toe op credentials, account en bron-IP; het dagquotum geldt voor account en credentials, niet bron-IP. Gebruik geen meerdere credentials of IP’s om limieten te omzeilen.

Behandel 429 Too Many Requests en 5xx bij veilig herhaalbare leesaanroepen met begrensde exponentiële back-off en willekeurige jitter. Dit geldt niet zonder meer voor schrijftoegang: controleer bij onduidelijke acceptatie eerst het effect per object. Corrigeer bij 400, 401, 403, 404 en 409 eerst request, token, rol, ID of toestand. Bulk-endpoints kunnen ondanks HTTP 200 of 202 foutlijsten bevatten; evalueer succes en fouten per object en verstuur alleen mislukte, veilig herhaalbare delen opnieuw.

Schrijftoegang veilig invoeren

1. Verifieer tenant, regionale host, paginering en filters met een Read-Only-credential.
2. Kies de kleinste gedocumenteerde rol en machtiging voor de precieze bewerking.
3. Lees en bewaar de huidige toestand en betrokken ID’s als wijzigingsbewijs.
4. Voer exact één wijziging op een pilotgroep of testapparaat uit.
5. Evalueer het volledige antwoord en controleer het effect op apparaat of in Central.
6. Breid pas daarna uit; handel rollback, verloopdatum, 429 en gedeeltelijke fouten vooraf af.

De vakinhoudelijke regels voor Endpoint-groepen en apparaatinventaris, beleidsvolgorde en Live Discover blijven gelden. Het ondersteunde proces om reeds beveiligde endpoints naar een andere tenant te verplaatsen staat apart en mag niet uit een algemeen API-voorbeeld worden afgeleid.

Veelgestelde vragen