Automatizzare in sicurezza Sophos Fusion Endpoint API

La Sophos Fusion Endpoint API è l’API del tenant per le risorse Endpoint e server. Inventaria i dispositivi e, in base all’endpoint e ai permessi, può gestire scansioni, isolamento, gruppi, Policy, esclusioni, Tag e assegnazioni software. L’accesso in scrittura incide sulla protezione; per l’inventario basta un’identità Read-Only.

Il percorso rapido e sicuro è: usare un’API Credential con ruolo minimo, ottenere un Token tramite OAuth2 Client Credentials Flow, individuare Tenant ID e host regionale, provare prima GET /endpoint/v1/endpoints ed elaborare tutte le pagine e tutti gli errori.

Confine con Sophos Fusion Admin e altre API

Creazione, conservazione, rotazione ed eliminazione dei Service Principal sono attività condivise di Sophos Fusion Admin. La procedura completa è quindi descritta in Gestire in sicurezza le credenziali API di Sophos Fusion, senza duplicarla qui.

Anche elenchi Tenant di Partner e Organization, Alerts, Audit Events, Account Health, Cases e Live Discover non appartengono automaticamente all’Endpoint API. Sophos Fusion (in precedenza Sophos Central) offre API separate, con ruoli e limiti propri. Questo articolo tratta solo richieste sotto il percorso regionale /endpoint/v1.

Autenticazione e contesto della richiesta

L’articolo di riferimento collegato definisce in modo esclusivo la richiesta del token e il formato della risposta, whoami, elenchi Partner/Enterprise, validazione dell’host e gestione dei secret. Riutilizzare senza modifiche SOPHOS_ACCESS_TOKEN, SOPHOS_TENANT_ID e SOPHOS_API_HOST. scope=token non sostituisce l’autorizzazione: contano anche ruolo Service Principal, accesso tenant, licenza e permesso Endpoint; Partner Assistance o Enterprise Admin Management deve consentire il tenant di destinazione.

Eseguire una lettura innocua

L’esempio non inventa Token o dati tenant. Attende tre valori dal proprio processo di credenziali e discovery e salva la prima pagina in un file locale:

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

Usare SOPHOS_API_HOST senza modifiche da whoami o dall’elenco Tenant. Il Token deve arrivare al processo da un Secret Store, non da script, Shell History, argomenti della riga di comando, ticket o Debug Log. La configurazione tramite standard input evita che il Bearer Header espanso compaia nell’elenco degli argomenti di curl; umask 077 limita i permessi del nuovo file di output. --fail-with-body rende visibile un errore HTTP, ma il file salvato resta un inventario potenzialmente sensibile.

Un HTTP Status positivo conferma solo la richiesta. Verificare poi JSON valido, tenant atteso e presenza dei dispositivi necessari. Non viene mostrata una Response fittizia che potrebbe essere scambiata per un risultato osservato.

Scegliere consapevolmente i percorsi Endpoint

Endpoint v1 include tra l’altro questi percorsi:

• GET /endpoint/v1/endpoints e GET /endpoint/v1/endpoints/{endpointId} per inventario e dettagli;
• POST /endpoint/v1/endpoints/{endpointId}/scans per richiedere una scansione;
• POST /endpoint/v1/endpoints/tamper-protection per modifiche mirate a Tamper Protection su un massimo di 200 dispositivi;
• POST /endpoint/v1/endpoints/reset-health per il reset dello stato di integrità e degli alert su un massimo di 500 dispositivi supportati;
• /endpoint/v1/endpoint-groups per gruppi Computer e Server;
• /endpoint/v1/policies per Policy Endpoint, Server e Device Encryption;
• POST /endpoint/v1/tags/assignment per assegnare Tag;
• endpoint per isolamento, elementi consentiti o bloccati, esclusioni, Web Control, pacchetti software e migrazioni Endpoint.

Usare il metodo HTTP e il percorso completo indicati sopra, senza sostituirli con vecchi percorsi dal nome simile. Prima di scrivere verificare schema, ruolo e autorizzazione necessari, confini di piattaforma e licenza, Status Code e Rate Limit specifico dell’operazione.

Modificare Tamper Protection e stato di integrità in modo mirato con richieste bulk

Le due operazioni bulk integrano le chiamate Endpoint v1 esistenti; non impongono una migrazione. Entrambe usano l’host regionale individuato, il token Bearer, X-Tenant-ID del tenant di destinazione e Content-Type: application/json. Il permesso richiesto per entrambe è endpoint-state:update. Un’identità di sola lettura non basta; verificare prima che il ruolo del Service Principal includa questo permesso nel tenant di destinazione.

Tamper Protection: Il corpo JSON di POST /endpoint/v1/endpoints/tamper-protection contiene ids con 1–200 UUID di endpoint univoci e almeno uno dei campi booleani enabled o regeneratePassword. enabled: true richiede l’attivazione, enabled: false la disattivazione. regeneratePassword: true richiede nuove password dei dispositivi. Lo schema usa anyOf, non oneOf: ammette quindi anche entrambi i campi insieme. Per rendere tracciabili le modifiche di manutenzione, pianificare comunque separatamente i cambi di stato e la rigenerazione delle password, inviando solo i campi voluti. La rigenerazione delle password non è né un override locale di quattro ore né una password comune a tutti i dispositivi.

Prima della disattivazione: Usare solo l’insieme di ID approvato e registrare per ciascun dispositivo lo stato iniziale, la fine della manutenzione e la persona responsabile. Per la disattivazione tramite API non è documentata una riattivazione automatica dopo quattro ore. Dopo la manutenzione, richiedere l’attivazione esattamente dei dispositivi disattivati e verificarne l’effetto. I metodi di manutenzione locali e per singolo dispositivo restano spesso la scelta migliore per i singoli dispositivi.

Leggere prima GET /endpoint/v1/endpoints/{endpointId}?view=full e includere solo i dispositivi con tamperProtectionSupported: true confermato; un valore assente non costituisce un’autorizzazione. Il limite Windows/Linux del reset dello stato di integrità non indica che Tamper Protection supporti quelle piattaforme. Controllare l’interruttore globale con GET /endpoint/v1/settings/tamper-protection: se è disattivato, l’attivazione dei singoli dispositivi non ripristina la protezione. GET /endpoint/v1/endpoints/{endpointId}/tamper-protection restituisce lo stato previsto enabled, ma anche password ed eventualmente previousPasswords. Non registrare integralmente questa risposta nei log. Le password non devono comparire nei ticket né nei log di debug; una rotazione non può essere annullata riscrivendo la vecchia password.

Reset Health: POST /endpoint/v1/endpoints/reset-health richiede un corpo JSON con il campo obbligatorio ids: 1–500 UUID di endpoint univoci. Sono supportati computer Windows, server Windows e Linux, ma non macOS.

Prima del reset: L’operazione imposta lo stato di integrità su verde ed elimina tutti gli alert degli endpoint interessati. Salvare quindi prima i riscontri rilevanti, i dettagli degli alert e le prove di audit al di fuori della vista che verrà svuotata, e ottenere un’autorizzazione esplicita all’eliminazione. Il reset non rimuove malware e non ripara un servizio di protezione guasto. Uno stato verde dopo questo intervento non dimostra che la causa sia stata risolta; il contratto del reset non prevede un’operazione di annullamento per recuperare gli alert eliminati.

Dopo una richiesta pilota approvata, rileggere i dettagli dei dispositivi, controllare stato di integrità e alert in Sophos Fusion e verificare separatamente il funzionamento effettivo della protezione. Analizzare i nuovi alert invece di nasconderli con reset ripetuti.

Accettata non significa eseguita

Per entrambe le operazioni bulk, HTTP 202 indica soltanto che la richiesta è stata elaborata e che l’accettazione è stata valutata per ogni ID. items contiene le richieste accettate con id, status: requested e requestedAt; errors contiene quelle rifiutate con id, errorCode e errorMessage. requestedAt non è un timestamp di completamento. Confrontare ogni ID inviato con questi risultati; le corrispondenze mancanti o contraddittorie restano irrisolte anche se lo stato HTTP indica un esito positivo.

I codici di errore sono notFound, notSupported, conflict, permissionDenied e internalError. Per i primi quattro, correggere prima ID/tenant, supporto del dispositivo, stato o permessi, a seconda del caso. Nemmeno internalError autorizza a reinviare l’intero batch. In caso di errori HTTP, analizzare la risposta di errore; un 202 può contenere contemporaneamente ID accettati e rifiutati.

Confermare poi separatamente l’effetto: dopo un contatto riuscito del dispositivo, leggere i dettagli dell’endpoint con view=full e, per Tamper Protection, anche le impostazioni, quindi controllare la protezione localmente. Valutare lastSeenAt, tamperProtectionEnabled oppure, secondo il caso, health.overall, health.threats e health.services. La sola rilettura di uno stato previsto non ne conferma l’applicazione su un dispositivo offline. Definire un intervallo di verifica limitato e un tempo massimo complessivo; in assenza di conferma, documentare l’esecuzione come ancora aperta e indagare connettività del dispositivo o errori.

Dopo un timeout o un’interruzione della connessione, una richiesta di scrittura potrebbe essere già stata accettata. Non ripeterla alla cieca: confrontare prima stato e prove disponibili per ogni ID. Altrimenti, un’ulteriore rotazione delle password o un nuovo reset degli alert potrebbe modificare stati creatisi nel frattempo. Autorizzare un nuovo tentativo solo per sottoinsiemi il cui rifiuto è dimostrato e che, dopo la correzione, possono essere ripetuti in sicurezza; riservare gli ID irrisolti alla verifica manuale.

Gruppi, Tag, software e Policy

I gruppi controllano l’assegnazione delle Policy e restano entro la gerarchia del tenant. I Tag completano inventario e ricerca. Una chiave ha 1–40 caratteri e un valore 0–40, entrambi senza due punti. Ogni Endpoint ammette al massimo 15 Tag e una chiave un solo valore. Una richiesta accetta al massimo 1.000 UUID e può restituire errori parziali per Endpoint; il client deve quindi valutare ogni stato Endpoint restituito.

In Device Software, Protection, Encryption e ZTNA sono categorie separate. I Computer supportano tutte e tre; i Server, in questo flusso, solo Protection. Ogni blocco computer o server accetta al massimo 1.000 ID. Gli ID validi dipendono da Endpoint, catalogo e licenza. Usare solo ID restituiti da una lettura precedente per quello specifico Endpoint; non applicare All, None o ID ipotizzati senza validarli.

Per le Policy, salvare tipo, impostazioni, assegnazioni e priorità prima di modificare. Base Policy e Policy aggiuntive non supportano le stesse operazioni. Modificare solo i campi che l’oggetto corrente del tenant espone come scrivibili e non bloccati. Un PATCH contiene solo chiavi verificate; un vecchio oggetto completo non deve sovrascrivere impostazioni aggiunte successivamente.

Paginazione, limiti e gestione degli errori

Gli elenchi Endpoint usano una paginazione basata su chiavi: prima pagina senza pageFromKey, pagine successive con pages.nextKey della risposta precedente. Altre risorse usano una paginazione per numero di pagina. Il massimo di pageSize varia: 50 è il default per gli Endpoint, 500 il massimo documentato per Endpoint Groups. Seguire lo schema specifico e terminare solo quando non esiste una chiave o pagina successiva.

Limiti globali delle Sophos Fusion API:

• 10 chiamate al secondo: raccomandato;
• 100 al minuto: applicato, con brevi burst fino a 300;
• 1.000 all’ora: raccomandato;
• 200.000 al giorno: applicato.

Prevalgono limiti operativi più severi. Sophos applica i primi tre separatamente a Credentials, account e IP sorgente; la quota giornaliera vale per account e Credentials, non per IP. Non usare più Credentials o IP per aggirare un limite.

Per le letture che possono essere ripetute in sicurezza, gestire 429 Too Many Requests e 5xx con tentativi limitati, backoff esponenziale e jitter casuale. Questo non vale indiscriminatamente per le scritture: se l’accettazione è incerta, verificare prima l’effetto per ogni oggetto. Per 400, 401, 403, 404 e 409, correggere prima richiesta, token, ruolo, ID o stato. Gli endpoint bulk possono restituire elenchi di errori nonostante HTTP 200 o 202; valutare quindi successi ed errori per oggetto e reinviare solo le parti fallite che è sicuro ripetere.

Introdurre le scritture in sicurezza

1. Verificare tenant, host regionale, paginazione e filtri con una Read-Only Credential.
2. Scegliere ruolo e permesso documentati più limitati per l’operazione.
3. Leggere e conservare stato attuale e ID interessati come prova del Change.
4. Effettuare esattamente una modifica su gruppo pilota o dispositivo di test.
5. Valutare l’intera risposta e verificare l’effetto sul dispositivo o in Central.
6. Ampliare solo dopo; gestire prima Rollback, scadenza delle credenziali, 429 ed errori parziali.

Restano valide le regole specifiche per gruppi Endpoint e inventario, ordine delle Policy e Live Discover. Il processo supportato per spostare Endpoint già protetti in un altro tenant è descritto separatamente e non va dedotto da un esempio API generico.

Domande frequenti