Automatiser l’API Sophos Central Endpoint en sécurité
La Sophos Central API convient aux inventaires récurrents, aux modifications en masse contrôlées et à l’intégration avec les processus d’exploitation internes. Elle n’est toutefois pas une seconde interface de reporting sans conséquences. Selon son rôle, une application peut analyser des Endpoints, modifier des groupes, éditer des Policies, attribuer des logiciels, migrer des appareils ou lancer des Live Discover Queries.
Une automatisation sécurisée commence donc par trois questions : quel tenant est concerné, quelle est l’autorisation minimale nécessaire et comment chaque modification peut-elle être prouvée et annulée ?
API Credentials comme identité distincte
Sous Global Settings > Access Control > API Credentials, un Super Admin crée un Service Principal. Le nom et la description indiquent l’application, le responsable, l’objectif et la date d’expiration. Les identifiants personnels d’un administrateur ou un compte Super Admin ne doivent pas être utilisés dans des scripts.
Sophos fournit plusieurs rôles. Les suivants sont particulièrement pertinents pour les tâches Endpoint :
| Rôle | Usage adapté | Limite importante |
|---|---|---|
| Service Principal Read-Only | inventaire, état et reporting | aucune modification ni Live Discover Query |
| Service Principal Management | appareils, utilisateurs, Policies et gestion de la protection | aucune Forensics Query |
| Service Principal Forensics | Live Discover | aucune gestion Endpoint générale |
| Service Principal Active Directory Sync | synchronisation AD | exclusivement la synchronisation d’annuaire |
| Service Principal Super Admin | cas particuliers nécessitant expressément un accès complet | dommages potentiels maximaux en cas d’abus |
Le Client Secret n’est affiché qu’une seule fois et est immédiatement enregistré dans un Secret Store. Sophos n’envoie aucun avertissement avant l’expiration d’une API Credential. Après expiration, l’entrée est automatiquement supprimée et l’application ne peut se reconnecter qu’avec de nouveaux identifiants. La surveillance de l’expiration et la rotation doivent donc être gérées en dehors de Central.
Les Legacy API Tokens de la SIEM Integration API sont progressivement remplacés. Les Tokens existants ne fonctionnent que jusqu’à leur expiration. Les nouvelles intégrations utilisent des API Credentials.
Authentification et API Host correct
Sophos utilise OAuth2 avec le Client Credentials Flow. L’application envoie le Client ID et le Client Secret au Sophos ID Endpoint et reçoit un Bearer Token temporaire. Le Token, le Secret et les Request Headers complets ne sont consignés ni dans des tickets ni dans des Logs non protégés.
Après l’authentification, l’interface globale Who Am I est d’abord interrogée. Sa réponse fournit le Tenant ID et l’API Host de la région des données. Ce n’est qu’ensuite que l’application appelle un Endpoint régional comme api-eu01.central.sophos.com ou api-eu02.central.sophos.com. En plus du Bearer Token, la requête régionale nécessite le Header X-Tenant-ID.
Pour un contrôle manuel, Central affiche également la région sous Profile > Support settings. Elle peut aussi être reconnue dans le hostname d’un lien de téléchargement de l’installer. Les automatisations utilisent néanmoins Who Am I, car une région lue dans l’interface ne constitue pas un mécanisme multi-tenant fiable.
Important : la région n’est pas déduite de l’emplacement de l’entreprise ni de la langue. Un Host codé en dur dans le script peut être incorrect pour le tenant suivant. Who Am I ou la Tenant List constitue la source de référence.
Les automatisations Partner et Enterprise travaillent avec plusieurs tenants. Elles déterminent d’abord le Partner ID ou l’Organization ID, lisent tous les tenants avec leur région de données, puis exécutent la requête pour chacun d’eux avec son Regional Host et son Tenant ID.
Fonctions couvertes par les Endpoint APIs
Les interfaces officielles permettent notamment de :
- inventorier les appareils et déclencher des actions comme un Scan,
- créer et modifier des Endpoint Groups et leur attribuer des appareils,
- créer, cloner et prioriser des Policies supplémentaires et modifier leurs paramètres,
- attribuer Protection, Device Encryption ou ZTNA comme Device Software,
- consulter les packages Recommended, Fixed, LTS et Support disponibles,
- organiser les appareils avec des Key-Value Tags,
- contrôler les migrations Endpoint entre tenants,
- lire les résultats Account Health et déclencher les corrections prises en charge,
- évaluer les Audit Events, Alerts, XDR Cases et Detections,
- lancer des Live Discover Queries enregistrées ou personnalisées.
Toutes les licences et tous les rôles ne permettent pas chaque opération. Avant une automatisation avec écriture, un appel Read-Only confirme que le tenant, les Object IDs, la licence et l’état actuel attendu correspondent.
Certaines APIs ont des limites plus étroites que leur nom ne le laisse penser. La Cases API ne peut actuellement créer et modifier que des cases self-managed. Sophos indique en outre une limite souple de 100 requests par tenant et par 24 heures ainsi que 10 requests par utilisateur et par minute. Lors de la récupération des case detections, une taille de page supérieure à 50 renvoie 400 Bad Request. L’Endpoint Software API ne peut afficher les packages que pour les ordinateurs et serveurs Windows et exige actuellement le rôle Service Principal Super Admin. Ces prérequis propres à chaque API doivent être vérifiés dans la référence concernée avant l’implémentation, et non déduits des rôles ou limites généraux.
Groupes, Tags et attribution de logiciels
Les groupes restent le moyen d’attribuer les Policies. Les Tags les complètent pour l’inventaire, la recherche et les workflows externes. Un Tag comprend une Key et une Value facultative. La Key et la Value sont limitées à 40 caractères chacune et ne peuvent pas contenir de deux-points. Un Endpoint accepte au maximum 15 Tags, et une même Key ne peut avoir qu’une Value par appareil.
Une Tag Request ou Software Request peut contenir jusqu’à 1'000 UUID d’Endpoints. Lors d’une Bulk Operation, une réponse HTTP 200 ne signifie pas nécessairement que tous les objets ont été modifiés. L’application évalue donc également les erreurs partielles par appareil et ne répète pas aveuglément toute l’opération.
Dans la Device Software API, Protection, Encryption et ZTNA sont des catégories distinctes. All attribue uniquement la variante sous licence la plus élevée dans la catégorie indiquée, et None supprime uniquement cette catégorie. Les Software IDs disponibles sont interrogés sur l’Endpoint concerné. Ils sont case-sensitive et dépendent de la licence ainsi que du Device Catalog.
Ne pas traiter les Policies comme des fichiers texte
L’Endpoint Policy API peut lire les Base Policies et les Policies supplémentaires. Les Policies supplémentaires peuvent être créées, clonées, mises à jour et supprimées. Pour une Base Policy, seuls les paramètres peuvent être modifiés, pas le nom, la priorité ni l’état d’activation.
Avant une mise à jour, le Policy Type, la priorité actuelle, les attributions et les paramètres existants sont sauvegardés. Un PATCH ne contient que les Keys volontairement modifiées. Une automatisation ne doit pas remplacer des paramètres inconnus ou récemment ajoutés par Sophos par un ancien objet complet.
Les Policy Requests avec écriture ont des Rate Limits supplémentaires par tenant. Une syntaxe valide ne prouve pas non plus que la modification est acceptable en production. Comme dans la GUI, un Pilot Group, une Change Window, l’Audit Log et un Rollback sont nécessaires.
Pagination, Rate Limits et nouvelles tentatives
Les listes doivent être lues intégralement sur toutes les pages. Selon l’interface, les Sophos APIs utilisent une pagination basée sur l’Offset ou sur une Key. Un script qui traite uniquement la première page de réponse peut présenter un inventaire incomplet comme complet.
Pour l’utilisation de l’API, Sophos indique comme valeurs de référence ou limites 10 Requests par seconde, 100 par minute, 1'000 par heure et 200'000 par jour. Certaines APIs peuvent avoir des limites plus strictes. Pour 429 Too Many Requests et les erreurs 5xx temporaires, une nouvelle tentative est effectuée avec Exponential Backoff et Jitter aléatoire. En cas d’erreur d’authentification, d’autorisation ou de validation, une boucle infinie inchangée est incorrecte.
Chaque exécution consigne au minimum le Tenant ID, l’opération, le nombre d’objets, les IDs réussis et échoués, l’heure de la Request et une Correlation ID propre. Les Secrets, Bearer Tokens et contenus sensibles des réponses sont retirés des Logs.
Déploiement sécurisé
Une nouvelle automatisation commence dans un tenant de test ou un petit Pilot Group. Le même workflow est d’abord exécuté en lecture seule et produit un plan vérifiable. Une seule modification contrôlée est ensuite effectuée, puis confirmée par l’API et dans Central sur l’appareil, l’Effective Policy et l’Audit Log.
Le périmètre n’est élargi qu’après avoir testé les erreurs partielles, la Pagination, les Rate Limits, l’expiration des identifiants et le Rollback. Pour les projets ponctuels, les API Credentials sont supprimées à la fin. Les intégrations permanentes disposent d’un Owner, d’une Rotation, d’un Monitoring et d’une procédure de désactivation documentée.
Articles associés
La migration Endpoint entre tenants Central utilise ses propres Receiving et Sending Workflows. Les mêmes règles techniques s’appliquent aux groupes Endpoint et à l’inventaire des appareils, à l’ordre des Policies et à Live Discover, que la modification soit effectuée dans la GUI ou par API.