Automatiser l’API Sophos Central Endpoint en sécurité

L’API Sophos Central Endpoint est l’API de tenant pour les ressources Endpoint et serveur. Elle inventorie les appareils et peut, selon l’endpoint et l’autorisation, gérer notamment les scans, l’isolation, les groupes, les Policies, les exclusions, les Tags et les attributions de logiciels. Les écritures ont un effet sur la protection ; une identité Read-Only suffit pour l’inventaire.

Le chemin rapide et sûr consiste à utiliser une API Credential avec le rôle minimal, obtenir un Token par le Client Credentials Flow OAuth2, identifier le Tenant ID et l’hôte régional, tester d’abord GET /endpoint/v1/endpoints, puis traiter chaque page et chaque erreur.

Limite avec Central Admin et les autres APIs

La création, le stockage, la rotation et la suppression des Service Principals sont des tâches Central Admin communes. Le processus complet figure donc dans Gérer les API Credentials Sophos Central en sécurité et n’est pas dupliqué ici.

Les listes de tenants Partner et Organization, les Alerts, Audit Events, Account Health, Cases et Live Discover n’appartiennent pas automatiquement à l’Endpoint API. Sophos Central fournit des APIs distinctes avec leurs propres rôles et limites. Cet article couvre uniquement les requêtes sous le chemin régional /endpoint/v1.

Authentification et contexte de la requête

Sophos documente OAuth2 avec le Client Credentials Flow. La requête de Token est un POST vers https://id.sophos.com/api/v2/oauth2/token, de type application/x-www-form-urlencoded, avec grant_type=client_credentials, client_id, client_secret et scope=token. Le JWT temporaire est envoyé sous la forme Authorization: Bearer <token>.

Une Tenant Credential appelle ensuite GET https://api.central.sophos.com/whoami/v1. La réponse détermine le Tenant ID et l’hôte régional. Les applications Partner et Enterprise obtiennent plutôt ces valeurs dans leurs listes paginées de tenants. Une requête régionale exige :

l’hôte fourni par Sophos, par exemple https://api-eu02.central.sophos.com, et non une région déduite du lieu ou de la langue ;
le Header X-Tenant-ID avec l’ID exact de ce tenant.

scope=token est le Scope OAuth de la requête de Token documentée. Il ne remplace pas l’autorisation : rôle du Service Principal, accès au tenant, licence et permissions propres à l’endpoint déterminent l’opération permise. Partner Assistance ou Enterprise Admin Management doit aussi autoriser l’accès requis au tenant cible.

Effectuer un appel de lecture sans danger

Cet exemple n’invente ni Token ni données de tenant. Il attend trois valeurs issues de votre propre processus d’identification et écrit la première page dans un fichier local :

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

Reprendre SOPHOS_API_HOST sans modification depuis whoami ou la liste des tenants. Le Token doit parvenir au processus depuis un Secret Store, jamais depuis le script, l’historique Shell, les arguments de commande, un ticket ou un Debug Log. La configuration fournie sur l’entrée standard évite d’exposer le Bearer Header développé dans la liste des arguments de curl ; umask 077 limite les droits du nouveau fichier de sortie. --fail-with-body rend l’erreur HTTP visible ; le fichier reste néanmoins un inventaire potentiellement sensible.

Un HTTP Status réussi ne confirme que la requête. Vérifier ensuite que le fichier contient un JSON valide, que le tenant attendu a été interrogé et que les appareils recherchés sont présents. Aucune réponse fictive susceptible d’être prise pour une observation réelle n’est présentée ici.

Choisir consciemment les chemins Endpoint

La référence Endpoint v1 actuelle comprend notamment :

GET /endpoint/v1/endpoints et GET /endpoint/v1/endpoints/{endpointId} pour l’inventaire et les détails ;
POST /endpoint/v1/endpoints/{endpointId}/scans pour demander un Scan ;
/endpoint/v1/endpoint-groups pour les groupes Computer et Server ;
/endpoint/v1/policies pour les Policies Endpoint, Server et Device Encryption ;
POST /endpoint/v1/tags/assignment pour attribuer des Tags ;
des endpoints pour l’isolation, les éléments autorisés ou bloqués, les exclusions, Web Control, les packages logiciels et les migrations Endpoint.

Toujours reprendre la méthode HTTP et le chemin complet dans la référence actuelle. Des guides similaires peuvent afficher un ancien chemin. Avant toute écriture, vérifier sur l’endpoint choisi le schéma, le rôle et la permission requis, les limites de plateforme et de licence, les Status Codes et le Rate Limit spécifique.

Groupes, Tags, logiciels et Policies

Les groupes pilotent l’attribution des Policies ; les Tags complètent l’inventaire et la recherche. Une Tag Key contient 1 à 40 caractères et une Value 0 à 40, sans deux-points. Un Endpoint accepte au plus 15 Tags et une Key une seule Value. Une requête accepte au plus 1 000 UUID et peut renvoyer des erreurs partielles par Endpoint.

Pour Device Software, Protection, Encryption et ZTNA sont des catégories distinctes. Un Computer prend en charge les trois ; un Server, seulement Protection dans ce workflow. Chaque bloc computer ou server accepte au plus 1 000 IDs. Les Software IDs valides dépendent de l’Endpoint, du catalogue et de la licence ; ne pas employer All, None ou un ID sans lecture préalable.

Pour les Policies, sauvegarder type, paramètres, attributions et priorité avant modification. Les Base Policies et Additional Policies n’acceptent pas les mêmes opérations. Un PATCH ne contient que les Keys contrôlées ; un ancien objet complet ne doit pas écraser des paramètres ajoutés ensuite par Sophos.

Pagination, limites et traitement des erreurs

Les listes d’Endpoints utilisent une Pagination par Key : charger la première page sans pageFromKey, puis transmettre le pages.nextKey de la réponse précédente. D’autres ressources utilisent une Pagination par page. Le maximum de pageSize dépend de l’opération : 50 par défaut pour les Endpoints et 500 au maximum pour les Endpoint Groups. Suivre le schéma exact et ne terminer qu’en l’absence de Key ou de page suivante.

Les limites globales des APIs Sophos Central sont :

10 appels par seconde : recommandé ;
100 par minute : imposé, avec de courtes pointes jusqu’à 300 ;
1 000 par heure : recommandé ;
200 000 par jour : imposé.

Une limite plus stricte propre à l’opération prévaut. Sophos applique les trois premières séparément aux Credentials, au compte et à l’IP source ; le quota journalier s’applique au compte et aux Credentials, pas à l’IP. Ne pas multiplier Credentials ou IPs pour contourner une limite.

Pour 429 Too Many Requests et 5xx, réessayer un nombre limité de fois avec Exponential Backoff et Jitter aléatoire. Pour 400, 401, 403, 404 et 409, corriger d’abord requête, Token, rôle, ID ou état. Un Bulk Endpoint peut renvoyer une liste d’erreurs malgré HTTP 200 : évaluer chaque objet et ne répéter que les éléments en échec qu’il est sûr de rejouer.

Introduire les écritures en sécurité

Vérifier tenant, hôte régional, Pagination et filtres avec une Read-Only Credential.
Choisir le rôle et la permission documentés les plus restreints pour l’opération.
Lire et conserver l’état actuel et les IDs concernés comme preuve de Change.
Effectuer exactement une modification sur un Pilot Group ou un appareil de test.
Traiter toute la réponse et vérifier l’effet sur l’appareil ou dans Central.
Élargir ensuite seulement ; prévoir Rollback, expiration, 429 et erreurs partielles.

Les règles propres aux groupes Endpoint et à l’inventaire, à l’ordre des Policies et à Live Discover restent applicables. La procédure prise en charge pour déplacer des Endpoints déjà protégés vers un autre tenant est décrite séparément et ne doit pas être déduite d’un exemple API générique.

Questions fréquentes

scope=token suffit-il pour chaque requête Endpoint ?

Non. scope=token appartient à la requête OAuth. Rôle, accès au tenant, licence et permissions propres à l’opération déterminent également si Sophos autorise la requête.

Pourquoi des appareils manquent-ils malgré la réussite de la première requête ?

Souvent, seule la première page a été traitée ou un filtre était actif. Vérifier pages.nextKey, les filtres, le Tenant ID et l’hôte régional, puis lire toutes les pages.

Peut-on répéter intégralement une Bulk Request en échec ?

Pas aveuglément. Examiner les erreurs par objet et déterminer si l’opération est idempotente ou sûre à répéter. Ne pas réexécuter involontairement les changements déjà réussis.