Automatisera Sophos Central Endpoint API säkert
Sophos Central API lämpar sig för återkommande inventering, kontrollerade massändringar och integrering med egna driftprocesser. Det är dock inte ett andra rapportgränssnitt utan konsekvenser. Beroende på roll kan en applikation skanna endpoints, ändra grupper, redigera policyer, tilldela programvara, migrera enheter eller starta Live Discover-frågor.
Säker automatisering börjar därför med tre frågor: Vilken tenant berörs, vilken minsta behörighet krävs och hur kan varje ändring dokumenteras och återställas?
API Credentials som separat identitet
Under Global Settings > Access Control > API Credentials skapar en Super Admin en service principal. Namn och beskrivning anger applikation, ansvarig, syfte och utgångsdatum. Personliga administratörsuppgifter eller ett Super Admin-konto hör inte hemma i skript.
Sophos tillhandahåller flera roller. Följande är särskilt relevanta för Endpoint-uppgifter:
| Roll | Lämpligt syfte | Viktig begränsning |
|---|---|---|
| Service Principal Read-Only | Inventering, status och rapportering | inga ändringar, inga Live Discover-frågor |
| Service Principal Management | Hantering av enheter, användare, policyer och skydd | inga forensiska frågor |
| Service Principal Forensics | Live Discover | ingen allmän Endpoint-hantering |
| Service Principal Active Directory Sync | AD-synkronisering | endast katalogsynkronisering |
| Service Principal Super Admin | Specialfall som uttryckligen kräver full åtkomst | största möjliga skada vid missbruk |
Client Secret visas bara en gång och ska omedelbart lagras i ett hemlighetslager. Sophos skickar ingen varning innan ett API Credential upphör att gälla. Därefter tas posten bort automatiskt och applikationen kan inte logga in igen förrän nya uppgifter har skapats. Övervakning av giltighetstid och rotation måste därför ske utanför Central.
Äldre API Tokens för SIEM Integration API ersätts. Befintliga tokens fungerar bara tills de går ut; nya integrationer använder API Credentials.
Autentisering och rätt API-värd
Sophos använder OAuth2 med client credentials flow. Applikationen skickar Client ID och Client Secret till Sophos ID-endpointen och får en tidsbegränsad bearer token. Token, hemlighet och fullständiga request headers får inte skrivas i ärenden eller oskyddade loggar.
Efter inloggningen anropas först den globala Who Am I-endpointen. Svaret innehåller tenant-ID och API-värden för dataregionen. Först därefter anropas en regional endpoint som api-eu01.central.sophos.com eller api-eu02.central.sophos.com. Utöver bearer token kräver den regionala förfrågan headern X-Tenant-ID.
För en manuell kontroll visar Central även regionen under Profile > Support settings. Den kan också identifieras i hostname för en downloadlänk till installern. Automatiseringar använder ändå Who Am I, eftersom en region som lästs av i gränssnittet inte är en tillförlitlig multi-tenantmekanism.
Viktigt: Regionen får inte härledas från företagets plats eller språk. En hårdkodad värd i ett skript kan vara fel för nästa tenant. Who Am I eller tenantlistan är den auktoritativa källan.
Partner- och Enterprise-automatiseringar arbetar med flera tenants. De fastställer först partner- eller organisations-ID, läser alla tenants inklusive dataregion och utför sedan själva förfrågan för varje tenant med dess regionala värd och tenant-ID.
Vad Endpoint API:erna omfattar
De officiella gränssnitten kan bland annat:
- inventera enheter och utlösa åtgärder som en skanning,
- skapa och ändra Endpoint-grupper och tilldela enheter,
- skapa, klona och prioritera ytterligare policyer samt ändra deras inställningar,
- tilldela Protection, Device Encryption eller ZTNA som enhetsprogramvara,
- fråga efter tillgängliga Recommended-, Fixed-, LTS- och Support-paket,
- organisera enheter med nyckel-värde-taggar,
- styra Endpoint-migrering mellan tenants,
- läsa Account Health-resultat och utlösa korrigeringar som stöds,
- utvärdera Audit Events, varningar, XDR Cases och Detections,
- starta sparade eller egna Live Discover-frågor.
Alla licenser och roller kan inte utföra alla operationer. Innan en skrivande automatisering körs används ett Read-Only-anrop för att bekräfta att tenant, objekt-ID:n, licens och förväntat aktuellt tillstånd stämmer.
Vissa APIs har snävare gränser än namnet antyder. Cases API kan för närvarande endast skapa och ändra self-managed cases. Sophos anger dessutom en mjuk gräns på 100 requests per tenant och 24 timmar samt 10 requests per användare och minut. När case detections hämtas ger en page size över 50 svaret 400 Bad Request. Endpoint Software API kan endast visa packages för Windows-datorer och -servrar och kräver för närvarande rollen Service Principal Super Admin. Sådana API-specifika krav kontrolleras i respektive reference före implementationen och härleds inte från allmänna roller eller gränser.
Grupper, taggar och programvarutilldelning
Grupper är fortsatt mekanismen för policytilldelning. Taggar kompletterar dem för inventering, sökning och externa arbetsflöden. En tagg består av en nyckel och ett valfritt värde. Nyckel och värde får vardera innehålla högst 40 tecken och inget kolon. Varje endpoint kan ha högst 15 taggar och samma nyckel kan bara ha ett värde på en enhet.
En tagg- eller programvaruförfrågan kan innehålla upp till 1 000 Endpoint-UUID:n. Ett HTTP 200-svar vid massoperationer betyder inte nödvändigtvis att alla objekt ändrades. Applikationen måste även utvärdera partiella fel per enhet och får inte blint upprepa hela uppdraget.
I Device Software API är Protection, Encryption och ZTNA separata kategorier. All tilldelar endast den högsta licensierade varianten inom den angivna kategorin, medan None bara tar bort denna kategori. Fråga efter tillgängliga programvaru-ID:n för den konkreta endpointen. De är skiftlägeskänsliga och beror på licens och enhetskatalog.
Behandla inte policyer som textfiler
Endpoint Policy API kan läsa Base Policies och ytterligare policyer. Ytterligare policyer kan skapas, klonas, uppdateras och tas bort. För en Base Policy kan endast inställningarna ändras, inte namn, prioritet eller aktiveringsstatus.
Spara policytyp, aktuell prioritet, tilldelningar och befintliga inställningar före en uppdatering. En PATCH ska endast innehålla medvetet ändrade nycklar. Automatisering får inte skriva över okända inställningar eller nya inställningar som Sophos har lagt till med ett gammalt fullständigt objekt.
Skrivande policyförfrågningar har ytterligare hastighetsgränser per tenant. En syntaktiskt lyckad förfrågan bevisar inte heller att ändringen är driftmässigt säker. Precis som i GUI:t behövs en pilotgrupp, ett ändringsfönster, Audit Log och en återställningsplan.
Sidindelning, hastighetsgränser och nya försök
Listor måste läsas fullständigt över alla sidor. Beroende på gränssnitt använder Sophos API:er offset- eller nyckelbaserad sidindelning. Ett skript som bara bearbetar den första svarssidan kan rapportera en ofullständig inventering som komplett.
Sophos anger riktvärden eller gränser på 10 förfrågningar per sekund, 100 per minut, 1 000 per timme och 200 000 per dag. Enskilda API:er kan ha striktare gränser. För 429 Too Many Requests och tillfälliga 5xx-fel görs nya försök med exponentiell backoff och slumpmässig jitter. En oförändrad oändlig loop är fel vid autentiserings-, behörighets- eller valideringsfel.
Varje körning loggar minst tenant-ID, operation, antal objekt, lyckade och misslyckade ID:n, tidpunkt och ett eget korrelations-ID. Hemligheter, bearer tokens och känsligt svarsinnehåll tas bort från loggarna.
Säker introduktion
Ny automatisering börjar med en testtenant eller liten pilotgrupp. Först körs samma arbetsflöde skrivskyddat och skapar en spårbar plan. Därefter genomförs exakt en kontrollerad ändring och verifieras både via API och i Central på enheten, i den effektiva policyn och i Audit Log.
Utöka omfattningen först när partiella fel, sidindelning, hastighetsgränser, utgångna uppgifter och återställning har testats. API Credentials för engångsprojekt tas bort efteråt; permanenta integrationer behöver en ansvarig, rotation, övervakning och en dokumenterad avstängningsväg.
Relaterade artiklar
Den konkreta Endpoint-migreringen mellan Central-tenants använder ett eget receiving- och sending-arbetsflöde. Samma fackmässiga regler gäller för Endpoint-grupper och enhetsinventering, policyordning och Live Discover, oavsett om ändringen görs via GUI eller API.