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

L’API Sophos Fusion 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é en lecture seule suffit pour l’inventaire.

Le chemin rapide et sûr consiste à utiliser des identifiants d’API avec le rôle minimal, obtenir un jeton par le flux OAuth2 d’identifiants client, identifier l’ID du tenant et l’hôte régional, tester d’abord GET /endpoint/v1/endpoints, puis traiter chaque page et chaque erreur.

Limite avec Fusion Admin et les autres APIs

La création, le stockage, la rotation et la suppression des Service Principals sont des tâches Fusion Admin communes. Le processus complet figure donc dans Gérer les identifiants d’API Sophos Fusion 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 Fusion (anciennement 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

L’article de référence lié définit exclusivement le contrat de requête et de réponse du jeton, whoami, les listes Partner/Enterprise, la validation de l’hôte et le traitement des secrets. Reprendre sans modification SOPHOS_ACCESS_TOKEN, SOPHOS_TENANT_ID et SOPHOS_API_HOST. scope=token ne remplace pas l’autorisation : rôle du Service Principal, accès au tenant, licence et permission Endpoint s’appliquent aussi ; Partner Assistance ou Enterprise Admin Management doit autoriser le tenant cible.

Effectuer un appel de lecture sans danger

Cet exemple n’invente ni jeton 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 jeton doit parvenir au processus depuis un coffre de secrets, jamais depuis le script, l’historique du shell, les arguments de commande, un ticket ou un journal de débogage. La configuration fournie sur l’entrée standard évite d’exposer l’en-tête Bearer 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 statut HTTP de succès 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

Endpoint v1 comprend notamment les chemins suivants :

• 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 ;
• POST /endpoint/v1/endpoints/tamper-protection pour modifier Tamper Protection de manière ciblée sur un maximum de 200 appareils ;
• POST /endpoint/v1/endpoints/reset-health pour réinitialiser l’état de santé et les alertes sur un maximum de 500 appareils pris en charge ;
• /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.

Utiliser la méthode HTTP et le chemin complet indiqués ci-dessus, sans les remplacer par d’anciens chemins de nom similaire. Avant toute écriture, vérifier schéma, rôle et droit requis, limites de plateforme et de licence, codes de statut et limite de débit propre à l’opération.

Modifier Tamper Protection et l’état de santé de manière ciblée par requête groupée

Les deux opérations groupées complètent les appels Endpoint v1 existants ; elles n’imposent aucune migration. Toutes deux utilisent l’hôte régional identifié, le jeton Bearer, le X-Tenant-ID du tenant cible et Content-Type: application/json. L’autorisation requise pour chacune est endpoint-state:update. Une identité en lecture seule ne suffit pas ; vérifier au préalable que le rôle du Service Principal inclut cette autorisation dans le tenant cible.

Tamper Protection : Le corps JSON de POST /endpoint/v1/endpoints/tamper-protection contient ids avec 1–200 UUID d’endpoints uniques et au moins l’un des champs booléens enabled ou regeneratePassword. enabled: true demande l’activation ; enabled: false, la désactivation. regeneratePassword: true demande de nouveaux mots de passe d’appareil. Le schéma utilise anyOf, et non oneOf : les deux champs peuvent donc être fournis ensemble. Pour assurer la traçabilité de la maintenance, planifier néanmoins séparément le changement d’état et la régénération des mots de passe, et n’envoyer que les champs voulus. La régénération d’un mot de passe n’est ni un override local de quatre heures ni un mot de passe commun à tous les appareils.

Avant de désactiver la protection : Utiliser uniquement l’ensemble d’ID approuvé et consigner, pour chaque appareil, l’état initial, la fin de maintenance et la personne responsable. Aucun retour automatique après quatre heures n’est documenté pour la désactivation par API. Après la maintenance, demander l’activation des seuls appareils désactivés et en vérifier l’effet. Les méthodes de maintenance locales et par appareil restent souvent préférables pour les appareils individuels.

Lire d’abord GET /endpoint/v1/endpoints/{endpointId}?view=full et ne retenir que les appareils dont tamperProtectionSupported: true est confirmé ; l’absence de valeur ne vaut pas autorisation. Le périmètre Windows/Linux du reset de santé ne constitue pas une prise en charge de ces plateformes par Tamper Protection. Contrôler le réglage global avec GET /endpoint/v1/settings/tamper-protection : s’il est désactivé, activer des appareils individuellement ne rétablit pas la protection. GET /endpoint/v1/endpoints/{endpointId}/tamper-protection renvoie l’état prévu enabled, mais aussi password et, le cas échéant, previousPasswords. Ne pas journaliser cette réponse intégralement. Les mots de passe ne doivent figurer ni dans les tickets ni dans les journaux de débogage ; une rotation ne peut pas être annulée en réécrivant l’ancien mot de passe.

Reset Health : POST /endpoint/v1/endpoints/reset-health attend un corps JSON contenant le champ obligatoire ids : 1–500 UUID d’endpoints uniques. Les ordinateurs Windows, les serveurs Windows et Linux sont pris en charge, mais pas macOS.

Avant le reset : L’opération fait passer l’état de santé au vert et supprime toutes les alertes des endpoints concernés. Sauvegarder au préalable les constats pertinents, les détails des alertes et les preuves d’audit hors de la vue qui sera vidée, et obtenir une autorisation explicite de suppression. Le reset n’élimine aucun malware et ne répare pas un service de protection défaillant. Un état vert après cette intervention ne prouve pas que la cause a été corrigée ; le contrat du reset ne prévoit aucune opération d’annulation permettant de restaurer les alertes supprimées.

Après une requête pilote approuvée, relire les détails des appareils, contrôler l’état de santé et les alertes dans Sophos Fusion, puis vérifier séparément le fonctionnement réel de la protection. Analyser les nouvelles alertes au lieu de les masquer par des resets répétés.

Acceptation ne signifie pas exécution

Pour les deux opérations groupées, HTTP 202 signifie uniquement que la requête a été traitée et que son acceptation a été évaluée par ID. items contient les demandes acceptées avec id, status: requested et requestedAt ; errors contient les demandes refusées avec id, errorCode et errorMessage. requestedAt n’est pas une date d’achèvement. Rapprocher chaque ID envoyé de ces résultats ; les correspondances absentes ou contradictoires restent non résolues, même si le statut HTTP indique un succès.

Les codes d’erreur sont notFound, notSupported, conflict, permissionDenied et internalError. Pour les quatre premiers, corriger d’abord, selon le cas, l’ID/le tenant, la prise en charge de l’appareil, son état ou les autorisations. Même internalError n’autorise pas à renvoyer tout le lot. En cas d’erreur HTTP, examiner la réponse d’erreur ; un 202 peut contenir à la fois des ID acceptés et refusés.

Confirmer ensuite l’effet séparément : après un contact réussi de l’appareil, lire les détails de l’endpoint avec view=full et, pour Tamper Protection, les paramètres également, puis contrôler la protection localement. Examiner lastSeenAt, tamperProtectionEnabled ou, selon le cas, health.overall, health.threats et health.services. La simple relecture d’un état prévu ne confirme pas son application sur un appareil hors ligne. Définir un intervalle de vérification borné et un délai d’arrêt global ; faute de confirmation, consigner l’exécution comme non terminée et examiner la connectivité de l’appareil ou les erreurs.

Après un délai d’attente dépassé ou une rupture de connexion, une demande d’écriture peut déjà avoir été acceptée. Ne pas la répéter aveuglément : rapprocher d’abord l’état et les preuves disponibles pour chaque ID. Sinon, une nouvelle rotation de mot de passe ou un nouveau reset d’alertes pourrait modifier des états apparus entre-temps. N’autoriser une nouvelle tentative que pour les sous-ensembles dont le refus est établi et dont la répétition est sûre après correction ; réserver les ID non résolus à une vérification manuelle.

Groupes, Tags, logiciels et Policies

Les groupes pilotent l’attribution des stratégies et restent dans la hiérarchie du tenant. Les étiquettes complètent l’inventaire et la recherche. Une clé d’étiquette contient 1 à 40 caractères et une valeur 0 à 40, sans deux-points dans les deux cas. Un Endpoint accepte au plus 15 étiquettes et chaque clé ne peut avoir qu’une seule valeur sur cet Endpoint. Une requête accepte au plus 1 000 UUID et peut renvoyer des erreurs partielles par Endpoint ; le client doit donc évaluer chaque état d’Endpoint renvoyé.

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 identifiants logiciels valides dépendent de l’Endpoint, du catalogue et de la licence. Utiliser uniquement les IDs renvoyés par une lecture préalable de cet Endpoint précis ; ne pas appliquer All, None ni des IDs supposés sans validation.

Pour les stratégies, sauvegarder type, paramètres, attributions et priorité avant modification. Les stratégies de base et les stratégies supplémentaires n’acceptent pas les mêmes opérations. Modifier uniquement les champs que l’objet actuel du tenant présente comme modifiables et non verrouillés. Un PATCH ne contient que les clés contrôlées ; un ancien objet complet ne doit pas écraser des paramètres ajoutés ultérieurement.

Pagination, limites et traitement des erreurs

Les listes d’Endpoints utilisent une pagination par clé : 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 groupes Endpoint. Suivre le schéma exact et ne terminer qu’en l’absence de clé ou de page suivante.

Les limites globales des APIs Sophos Fusion 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 identifiants d’API, au compte et à l’IP source ; le quota journalier s’applique au compte et aux identifiants d’API, pas à l’IP. Ne pas multiplier les identifiants d’API ou les adresses IP pour contourner une limite.

Pour les appels de lecture qu’il est sûr de répéter, traiter 429 Too Many Requests et 5xx avec un nombre limité de tentatives, un délai exponentiel et une variation aléatoire. Cela ne s’applique pas systématiquement aux écritures : si l’acceptation est incertaine, vérifier d’abord l’effet par objet. Pour 400, 401, 403, 404 et 409, corriger d’abord la requête, le jeton, le rôle, l’ID ou l’état. Les endpoints groupés peuvent renvoyer des listes d’erreurs malgré HTTP 200 ou 202 ; évaluer donc les succès et les erreurs par objet et ne renvoyer que les parties en échec qu’il est sûr de répéter.

Introduire les écritures en sécurité

1. Vérifier tenant, hôte régional, pagination et filtres avec des identifiants en lecture seule.
2. Choisir le rôle et la permission documentés les plus restreints pour l’opération.
3. Lire et conserver l’état actuel et les IDs concernés comme preuve de changement.
4. Effectuer exactement une modification sur un groupe pilote ou un appareil de test.
5. Traiter toute la réponse et vérifier l’effet sur l’appareil ou dans Central.
6. Élargir ensuite seulement ; prévoir le retour arrière, l’expiration des identifiants d’API, 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