Automatisera Sophos Fusion Endpoint API säkert

Sophos Fusion Endpoint API är tenant-API:t för endpoint- och serverresurser. Det inventerar enheter och kan, beroende på endpoint och behörighet, hantera skanning, isolering, grupper, policyer, undantag, taggar och programvarutilldelning. Skrivåtkomst påverkar skyddet; en Read-Only-identitet räcker för inventering.

Den säkra kortversionen är: använd en API Credential med minsta roll, hämta en token via OAuth2 Client Credentials Flow, identifiera tenant-ID och regional värd, testa först GET /endpoint/v1/endpoints och behandla alla sidor och fel.

Gräns mot Fusion Admin och andra API:er

Att skapa, lagra, rotera och ta bort Service Principals är en gemensam Fusion Admin-uppgift. Hela processen beskrivs därför i Hantera Sophos Fusion API Credentials säkert och upprepas inte här.

Tenantlistor för Partner och Organization, Alerts, Audit Events, Account Health, Cases och Live Discover ingår inte heller automatiskt i Endpoint API. Sophos Fusion (tidigare Sophos Central) har separata API:er med egna roller och gränser. Den här artikeln behandlar bara anrop under den regionala bassökvägen /endpoint/v1.

Autentisering och requestkontext

Kontraktet för tokenbegäran och svar, whoami, tenantlistor för Partner och Enterprise, validering av värdnamn och hantering av hemligheter definieras uteslutande i den länkade huvudartikeln. Återanvänd SOPHOS_ACCESS_TOKEN, SOPHOS_TENANT_ID och SOPHOS_API_HOST oförändrade. scope=token ersätter inte auktorisering: Service Principal-roll, tenantåtkomst, licens och Endpoint-behörighet gäller också; Partner Assistance eller Enterprise Admin Management måste tillåta måltenant.

Gör ett ofarligt läsanrop

Exemplet hittar inte på någon token eller tenantdata. Det förväntar tre värden från den egna processen för API-autentiseringsuppgifter och identifiering av tenant och regional värd och skriver första sidan till en lokal fil:

: "${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

Ta SOPHOS_API_HOST oförändrad från whoami eller tenantlistan. Token ska tillföras processen från ett säkert hemlighetslager, inte ligga i skript, skalhistorik, kommandoradsargument, ärenden eller felsökningsloggar. Konfigurationen via standardindata håller det expanderade Bearer-huvudet borta från curls argumentlista; umask 077 begränsar rättigheterna för den nya utdatafilen. --fail-with-body visar ett HTTP-fel, men filen måste fortfarande skyddas som potentiellt känslig inventeringsdata.

En lyckad HTTP-status bekräftar bara anropet. Kontrollera sedan giltig JSON, förväntad tenant och att de sökta enheterna finns. Inget påhittat svar visas som skulle kunna misstas för ett observerat resultat.

Välj Endpointsökvägar medvetet

Endpoint v1 omfattar bland annat dessa sökvägar:

• GET /endpoint/v1/endpoints och GET /endpoint/v1/endpoints/{endpointId} för inventering och detaljer;
• POST /endpoint/v1/endpoints/{endpointId}/scans för att begära en skanning;
• POST /endpoint/v1/endpoints/tamper-protection för riktade Tamper Protection-ändringar på högst 200 enheter;
• POST /endpoint/v1/endpoints/reset-health för återställning av hälsostatus och larm på högst 500 enheter som stöds;
• /endpoint/v1/endpoint-groups för dator- och servergrupper;
• /endpoint/v1/policies för Endpoint-, Server- och Device Encryption-policyer;
• POST /endpoint/v1/tags/assignment för taggtilldelning;
• endpoints för isolering, tillåtna eller blockerade objekt, undantag, Web Control, programvarupaket och Endpoint-migrering.

Använd HTTP-metoden och den fullständiga sökvägen ovan; ersätt dem inte med äldre sökvägar med liknande namn. Kontrollera före skrivning schema, nödvändig roll och behörighet, plattforms- och licensgräns, statuskoder och operationsspecifik anropsgräns.

Ändra Tamper Protection och hälsostatus selektivt med bulkanrop

De två bulkåtgärderna kompletterar befintliga Endpoint v1-anrop; de kräver ingen migrering. Båda använder den identifierade regionala värden, bearer-token, måltenantens X-Tenant-ID och Content-Type: application/json. Båda kräver behörigheten endpoint-state:update. En skrivskyddad identitet räcker inte; kontrollera först att Service Principal-rollen omfattar denna behörighet i måltenanten.

Tamper Protection: JSON-kroppen för POST /endpoint/v1/endpoints/tamper-protection innehåller ids med 1–200 unika endpoint-UUID:n och minst ett av de booleska fälten enabled eller regeneratePassword. enabled: true begär aktivering, enabled: false inaktivering. regeneratePassword: true begär nya enhetslösenord. Schemat använder anyOf, inte oneOf: båda fälten får alltså även skickas tillsammans. Planera ändå tillståndsändringar och lösenordsregenerering separat för spårbara underhållsändringar, och skicka bara de avsedda fälten. Lösenordsregenerering är varken en lokal fyratimmars Override eller ett gemensamt lösenord för alla enheter.

Före inaktivering: Använd bara den godkända ID-mängden och dokumentera utgångsläge, underhållets sluttid och ansvarig person för varje enhet. För inaktivering via API finns ingen dokumenterad automatisk återaktivering efter fyra timmar. Begär efter underhållet aktivering av exakt de enheter som inaktiverades och verifiera effekten. De lokala och enhetsspecifika underhållsmetoderna är ofta fortfarande ett bättre val för enskilda enheter.

Läs först GET /endpoint/v1/endpoints/{endpointId}?view=full och inkludera bara enheter med bekräftat tamperProtectionSupported: true; ett saknat värde innebär inte ett godkännande. Hälsoåterställningens avgränsning till Windows/Linux bekräftar inte plattformsstöd för Tamper Protection. Kontrollera den globala inställningen med GET /endpoint/v1/settings/tamper-protection: om den är avstängd återställs inte skyddet genom att enskilda enheter aktiveras. GET /endpoint/v1/endpoints/{endpointId}/tamper-protection returnerar det avsedda tillståndet enabled, men även password och eventuellt previousPasswords. Logga inte hela svaret. Lösenord hör varken hemma i ärenden eller felsökningsloggar; en rotation kan inte ångras genom att det gamla lösenordet skrivs tillbaka.

Reset Health: POST /endpoint/v1/endpoints/reset-health förväntar sig en JSON-kropp med det obligatoriska fältet ids: 1–500 unika endpoint-UUID:n. Windows-datorer, Windows-servrar och Linux stöds, men inte macOS.

Före återställningen: Åtgärden sätter hälsostatus till grönt och raderar alla larm för berörda endpoints. Spara därför relevanta fynd, larmdetaljer och revisionsunderlag utanför den vy som ska tömmas, och inhämta ett uttryckligt godkännande av raderingen i förväg. Återställningen tar inte bort skadlig kod och reparerar inte en trasig skyddstjänst. En grön status efter ingreppet bevisar inte att orsaken har åtgärdats; återställningskontraktet erbjuder ingen ångra-åtgärd för att återställa raderade larm.

Läs efter ett godkänt pilotanrop enhetsdetaljerna igen, kontrollera hälsostatus och larm i Sophos Fusion och verifiera skyddets faktiska funktion separat. Utred nya larm i stället för att dölja dem med upprepade återställningar.

Accepterat är inte detsamma som utfört

För båda bulkåtgärderna betyder HTTP 202 bara att begäran har behandlats och att acceptans har bedömts per ID. items innehåller accepterade begäranden med id, status: requested och requestedAt; errors innehåller avvisade begäranden med id, errorCode och errorMessage. requestedAt är ingen sluttidpunkt. Stäm av varje skickat ID mot dessa resultat; saknade eller motstridiga kopplingar förblir outredda även om HTTP-statusen visar att anropet lyckades.

Felkoderna är notFound, notSupported, conflict, permissionDenied och internalError. För de fyra första ska först ID/tenant, enhetsstöd, tillstånd respektive behörighet korrigeras efter behov. Inte heller internalError ger klartecken att skicka om hela batchen. Vid HTTP-fel ska felsvaret granskas; ett 202 kan innehålla både accepterade och avvisade ID:n.

Bekräfta sedan effekten separat: läs efter lyckad enhetskontakt endpointdetaljer med view=full och för Tamper Protection även inställningarna, och kontrollera därefter skyddet lokalt. Utvärdera lastSeenAt, tamperProtectionEnabled eller, beroende på åtgärd, health.overall, health.threats och health.services. Enbart ett återläst önskat tillstånd bekräftar inte att ändringen har genomförts på en offline-enhet. Ange ett begränsat kontrollintervall och en total tidsgräns för avbrott; dokumentera körningen som öppen om bekräftelse saknas och utred enhetskontakten eller felen.

Efter en timeout eller bruten anslutning kan en skrivbegäran redan ha accepterats. Upprepa den inte blint: stäm först av tillstånd och tillgängliga underlag per ID. Annars kan ytterligare en lösenordsrotation eller larmåterställning ändra tillstånd som har uppstått under tiden. Godkänn bara nya försök för delmängder som bevisligen avvisats och som säkert kan upprepas efter korrigering; lämna outredda ID:n till manuell kontroll.

Grupper, taggar, programvara och policyer

Grupper styr policytilldelning och stannar inom tenantens hierarki. Taggar kompletterar inventering och sökning. En taggnyckel är 1–40 tecken lång och ett värde 0–40 tecken, båda utan kolon. En endpoint får ha högst 15 taggar, och varje nyckel får bara ha ett värde på samma endpoint. Ett anrop accepterar högst 1 000 UUID:n och kan returnera partiella fel per endpoint; klienten måste därför utvärdera varje returnerad endpointstatus.

I Device Software är Protection, Encryption och ZTNA separata kategorier. Datorer stöder alla tre; servrar i detta arbetsflöde endast Protection. Varje computer- eller server-block accepterar högst 1 000 ID:n. Giltiga programvaru-ID:n beror på endpoint, katalog och licens. Använd endast ID:n som ett tidigare läsanrop returnerade för exakt denna endpoint; använd inte All, None eller gissade ID:n utan validering.

Spara typ, inställningar, tilldelningar och prioritet innan policyer ändras. Baspolicyer och ytterligare policyer stöder inte samma operationer. Ändra endast fält som det aktuella tenantobjektet visar som skrivbara och olåsta. En PATCH innehåller bara granskade nycklar; ett gammalt komplett objekt får inte skriva över inställningar som lagts till senare.

Sidindelning, gränser och felhantering

Endpointlistor använder nyckelbaserad sidindelning: första sidan utan pageFromKey, följande sidor med pages.nextKey från föregående svar. Andra resurser använder sidnummer. Maximalt pageSize varierar: Endpoint har standard 50, Endpoint Groups högst 500. Följ det konkreta schemat och avsluta först när nästa nyckel eller sida saknas.

Globala gränser för Sophos Fusion API:er:

• 10 anrop per sekund: rekommenderat;
• 100 per minut: tillämpas, korta toppar upp till 300 tillåts;
• 1 000 per timme: rekommenderat;
• 200 000 per dag: tillämpas.

Striktare operationsgränser har företräde. Sophos tillämpar de första tre separat på API-autentiseringsuppgifter, konto och käll-IP; dagskvoten gäller konto och API-autentiseringsuppgifter, inte IP. Använd inte flera API-autentiseringsuppgifter eller IP-adresser för att kringgå en gräns.

Hantera 429 Too Many Requests och 5xx med begränsade återförsök, exponentiell backoff och slumpmässig jitter för läsanrop som säkert kan upprepas. Detta gäller inte generellt för skrivningar: kontrollera först effekten per objekt om acceptansen är oklar. Vid 400, 401, 403, 404 och 409 måste först begäran, token, roll, ID eller tillstånd korrigeras. Bulkendpoints kan innehålla fellistor trots HTTP 200 eller 202; utvärdera därför framgång och fel per objekt och skicka bara om misslyckade delar som säkert kan upprepas.

Inför skrivåtkomst säkert

1. Verifiera tenant, regional värd, sidindelning och filter med API-autentiseringsuppgifter med skrivskyddad roll.
2. Välj den minsta dokumenterade rollen och behörigheten för exakt operation.
3. Läs och spara aktuellt tillstånd och berörda ID:n som ändringsunderlag.
4. Gör exakt en ändring på en pilotgrupp eller testenhet.
5. Utvärdera hela svaret och kontrollera effekten på enheten eller i Central.
6. Utöka först därefter; planera i förväg för återställning, utgångsdatum för API-autentiseringsuppgifterna, 429 och partiella fel.

De särskilda reglerna för Endpoint-grupper och enhetsinventering, policyordning och Live Discover gäller fortfarande. Den stödda processen för att flytta redan skyddade endpoints till en annan tenant beskrivs separat och får inte härledas ur ett generellt API-exempel.

Vanliga frågor