Automatizzare in sicurezza Sophos Central Endpoint API
Sophos Central API è adatta per inventari ricorrenti, modifiche di massa controllate e integrazione nei processi operativi. Non è però una seconda interfaccia di reporting priva di conseguenze. A seconda del ruolo, un’applicazione può eseguire scansioni degli Endpoint, modificare gruppi e Policy, assegnare software, migrare dispositivi o avviare query Live Discover.
Un’automazione sicura parte quindi da tre domande: quale Tenant è interessato, qual è l’autorizzazione minima necessaria e come documentare e annullare ogni modifica?
API Credentials come identità separata
In Global Settings > Access Control > API Credentials, un Super Admin crea un Service Principal. Nome e descrizione indicano applicazione, responsabile, scopo e data di scadenza. Le credenziali personali di un amministratore o un account Super Admin non devono essere inseriti negli script.
Sophos offre diversi ruoli. Per le attività Endpoint sono particolarmente rilevanti i seguenti:
| Ruolo | Scopo adatto | Limite importante |
|---|---|---|
| Service Principal Read-Only | inventario, stato e reporting | nessuna modifica, nessuna query Live Discover |
| Service Principal Management | dispositivi, utenti, Policy e gestione della protezione | nessuna query forense |
| Service Principal Forensics | Live Discover | nessuna gestione Endpoint generale |
| Service Principal Active Directory Sync | sincronizzazione AD | esclusivamente sincronizzazione della directory |
| Service Principal Super Admin | casi particolari che richiedono esplicitamente accesso completo | massimo danno possibile in caso di abuso |
Il Client Secret viene mostrato una sola volta e deve essere archiviato immediatamente in un Secret Store. Sophos non invia avvisi prima della scadenza di un’API Credential. Alla scadenza, la voce viene rimossa automaticamente e l’applicazione può autenticarsi di nuovo solo con credenziali appena create. Monitoraggio della scadenza e rotazione devono quindi avvenire fuori da Central.
I Legacy API Token per SIEM Integration API vengono sostituiti. I Token esistenti funzionano solo fino alla scadenza; le nuove integrazioni utilizzano API Credentials.
Autenticazione e host API corretto
Sophos utilizza OAuth2 con Client Credentials Flow. L’applicazione invia Client ID e Client Secret all’Endpoint Sophos ID e riceve un Bearer Token con validità limitata. Token, Secret e Request Header completi non devono essere inseriti in ticket o Log non protetti.
Dopo l’autenticazione viene interrogata per prima l’interfaccia globale Who Am I. La risposta fornisce Tenant ID e host API della regione dati. Solo in seguito l’applicazione richiama un Endpoint regionale, ad esempio api-eu01.central.sophos.com o api-eu02.central.sophos.com. Oltre al Bearer Token, la Request regionale richiede l’Header X-Tenant-ID.
Per un controllo manuale, Central mostra la regione anche in Profile > Support settings. In alternativa può essere riconosciuta nell’hostname di un link per il download dell’installer. Le automazioni utilizzano comunque Who Am I, perché una regione letta dall’interfaccia non è un meccanismo multi-tenant affidabile.
Importante: la regione non si deduce dalla sede dell’azienda o dalla lingua. Un host inserito direttamente nello script può essere errato per il Tenant successivo. Who Am I o l’elenco dei Tenant è la fonte vincolante.
Le automazioni Partner ed Enterprise operano su più Tenant. Determinano prima il Partner ID o l’Organization ID, leggono tutti i Tenant con le rispettive regioni dati e poi eseguono la Request effettiva per ogni Tenant usando il relativo host regionale e Tenant ID.
Ambito delle Endpoint API
Le interfacce ufficiali comprendono tra l’altro:
- inventariare i dispositivi ed eseguire azioni come una scansione,
- creare e modificare gruppi Endpoint e assegnare dispositivi,
- creare, clonare e prioritizzare Policy aggiuntive e modificarne le impostazioni,
- assegnare Protection, Device Encryption o ZTNA come software del dispositivo,
- interrogare i pacchetti Recommended, Fixed, LTS e Support disponibili,
- organizzare dispositivi con Tag Key-Value,
- controllare migrazioni Endpoint tra Tenant,
- leggere i risultati di Account Health e avviare correzioni supportate,
- analizzare Audit Events, Alerts, XDR Cases e Detections,
- avviare query Live Discover salvate o personalizzate.
Non tutte le licenze e non tutti i ruoli consentono ogni operazione. Prima di un’automazione in scrittura, verificare con una chiamata Read-Only che Tenant, Object ID, licenza e stato attuale previsto coincidano.
Alcune APIs hanno limiti più ristretti di quanto suggerisca il loro nome. La Cases API può attualmente creare e modificare solo cases self-managed. Sophos indica inoltre un limite flessibile di 100 requests per tenant ogni 24 ore e 10 requests per utente al minuto. Durante il recupero delle case detections, una page size superiore a 50 restituisce 400 Bad Request. L’Endpoint Software API può elencare packages solo per computer e server Windows e richiede attualmente il ruolo Service Principal Super Admin. Questi prerequisiti specifici dell’API devono essere verificati nella relativa reference prima dell’implementazione e non dedotti da ruoli o limiti generali.
Gruppi, Tag e assegnazione software
I gruppi rimangono lo strumento per assegnare le Policy. I Tag li completano per inventario, ricerca e Workflow esterni. Un Tag è composto da una Key e da un valore opzionale. Key e valore possono contenere al massimo 40 caratteri ciascuno e non possono includere i due punti. Sono consentiti al massimo 15 Tag per Endpoint e la stessa Key può avere un solo valore sul dispositivo.
Una Request per Tag o software può contenere fino a 1'000 UUID Endpoint. In un’operazione Bulk, una risposta HTTP 200 non significa necessariamente che ogni oggetto sia stato modificato. L’applicazione valuta quindi anche gli errori parziali per dispositivo e non ripete alla cieca l’intera operazione.
Nell’API Device Software, Protection, Encryption e ZTNA sono categorie separate. All assegna solo la variante con licenza più elevata all’interno della categoria indicata, mentre None rimuove solo tale categoria. Gli ID software disponibili vengono interrogati sull’Endpoint concreto; sono case-sensitive e dipendono dalla licenza e dal catalogo del dispositivo.
Non trattare le Policy come file di testo
Endpoint Policy API può leggere Base Policy e Policy aggiuntive. Le Policy aggiuntive possono essere create, clonate, aggiornate ed eliminate. Per la Base Policy è possibile modificare solo le impostazioni, non nome, priorità o stato di attivazione.
Prima di un aggiornamento, salvare tipo di Policy, priorità attuale, assegnazioni e impostazioni esistenti. Una Request PATCH contiene solo le chiavi modificate consapevolmente. Un’automazione non deve sovrascrivere impostazioni sconosciute o aggiunte recentemente da Sophos usando un vecchio oggetto completo.
Le Request di scrittura sulle Policy hanno Rate Limit aggiuntivi per Tenant. Una sintassi valida non dimostra inoltre che la modifica sia sostenibile operativamente. Come nella GUI, servono gruppo pilota, finestra di Change, Audit Log e Rollback.
Paginazione, Rate Limit e tentativi
Gli elenchi devono essere letti integralmente su tutte le pagine. A seconda dell’interfaccia, le Sophos API utilizzano paginazione basata su Offset o Key. Uno script che elabora solo la prima pagina può dichiarare completo un inventario incompleto.
Per l’uso delle API, Sophos indica come valori orientativi o limiti 10 Request al secondo, 100 al minuto, 1'000 all’ora e 200'000 al giorno. Singole API possono avere limiti più severi. In caso di 429 Too Many Requests e di errori temporanei 5xx, riprovare con Backoff esponenziale e Jitter casuale. Per errori di autenticazione, autorizzazione o validazione è errato ripetere all’infinito la stessa Request.
Ogni esecuzione registra almeno Tenant ID, operazione, numero di oggetti, ID riusciti e non riusciti, orario della Request e un Correlation ID proprio. Secret, Bearer Token e contenuti sensibili delle Response vengono rimossi dai Log.
Procedura di introduzione sicura
Una nuova automazione inizia in un Tenant di test o con un piccolo gruppo pilota. Per prima cosa, lo stesso Workflow viene eseguito in sola lettura e produce un piano verificabile. Viene quindi effettuata una sola modifica controllata, verificandola sia tramite API sia in Central sul dispositivo, sulla Policy effettiva e nell’Audit Log.
L’ambito viene ampliato solo dopo aver testato errori parziali, paginazione, Rate Limit, scadenza delle credenziali e Rollback. Per progetti una tantum, le API Credentials vengono eliminate al termine; le integrazioni permanenti ricevono Owner, rotazione, Monitoring e una procedura documentata di disattivazione.
Articoli correlati
La procedura specifica per la migrazione Endpoint tra Tenant Central utilizza un Workflow Receiving e Sending dedicato. Per gruppi Endpoint e inventario dispositivi, ordine delle Policy e Live Discover valgono le stesse regole operative, indipendentemente dal fatto che la modifica avvenga tramite GUI o API.