Aller au contenu
Avanet
Mon compte
Mon compte

Chargement …

Interroger le Data Lake Sophos Fusion avec la Search GraphQL API

La Search GraphQL API v1 permet à une application personnalisée d’interroger le Data Lake historique de Sophos Fusion (anciennement Sophos Central) avec QL. Le traitement est asynchrone : lancer la recherche, conserver sa Search-URN, vérifier son achèvement et le résultat de l’exécution, puis lire toutes les pages de résultats. COMPLETE ne signifie pas à lui seul que toutes les parties de la recherche ont réussi.

L’API est publiée depuis le 12 octobre 2026. Elle complète les API existantes sans imposer de transition immédiate depuis la XDR Query API, qui reste disponible. Elle ne remplace pas non plus Live Endpoint Search (LES) : LES interroge les endpoints connectés avec du SQL de type osquery. La distinction entre Classic Live Discover, Data Lake Search et LES aide à choisir le bon chemin de données.

Avant la première requête

Il faut un tenant contenant les données historiques recherchées, des API Credentials adaptés, l’UUID unique du tenant et un client HTTP capable d’envoyer des requêtes POST JSON et d’enregistrer les réponses intégrales. Pour cet exemple, le tenant doit contenir des événements de processus. Sans ces données, une recherche techniquement réussie peut être vide.

Gérer les identifiants API en toute sécurité explique l’identité machine, le flux OAuth avec client_credentials, l’association au tenant et la rotation. Un identifiant de partenaire ou d’organisation n’est pas un UUID de tenant. Avec plusieurs tenants, choisir la cible à partir d’une correspondance univoque approuvée, et non de son seul nom d’affichage.

Le rôle minimal exact et les droits d’accès requis pour le client Search concerné doivent être clarifiés avant son autorisation en production. Le nom d’un rôle générique de principal de service ne confirme pas une permission Search. En cas de refus, ne pas attribuer Super Admin par précaution.

Avant le lancement, définir la question d’investigation, la période et les champs nécessaires. Les données de processus peuvent contenir des noms d’utilisateur, des chemins et des lignes de commande confidentiels. Requêtes et exports doivent rester dans un environnement approuvé, avec des droits d’accès et de conservation définis. Ni les jetons ni le Client Secret ne doivent figurer dans les journaux de requêtes, les tickets ou les fichiers d’exemple enregistrés. Les lignes de résultats complètes ne doivent pas non plus être journalisées sans contrôle.

Utiliser l’hôte cible propre à l’API

Les opérations suivantes partagent le même contrat de requête :

POST https://api.taegis.sophos.com/graphql
Authorization: Bearer <access-token>
X-Tenant-ID: <tenant-uuid>
X-GraphQL-Schema: default
Content-Type: application/json

Dans le client HTTP, remplacer <access-token> par le jeton d’accès OAuth actuel et <tenant-uuid> par l’UUID vérifié. URL et en-têtes restent identiques pour chacun des corps JSON suivants. Adapter ces modèles de requête au tenant et contrôler les réponses réellement reçues.

L’hôte REST régional provenant de apiHosts.dataRegion n’est pas l’hôte cible de ce contrat Search. Inversement, ne pas basculer globalement les clients REST existants vers l’hôte GraphQL. Ce nom d’hôte ne garantit ni lieu de stockage ni résidence des données ; ces exigences se clarifient selon les dispositions contractuelles et celles du tenant.

Lancer et suivre une recherche sans ambiguïté

Créer une nouvelle exécution avec createSearch

Le modèle suivant recherche les événements de processus de la dernière heure et limite les champs d’événement sélectionnés. -1h est une fenêtre relative pour un premier contrôle fonctionnel ; pour une comparaison ultérieure avec un autre client, définir des bornes temporelles explicites identiques.

{
  "operationName": "CreateSearch",
  "query": "mutation CreateSearch($input: CreateSearchInput) { createSearch(input: $input) { urn status } }",
  "variables": {
    "input": {
      "text": "from process where earliest = -1h | fields host_id, commandline, image_path"
    }
  }
}

Avant l’envoi, vérifier tenant, période et périmètre des données. createSearch crée et lance une nouvelle recherche, sans modifier la configuration de protection des endpoints. L’exécution peut générer du travail dans le service et des résultats sensibles. Une erreur client ne doit donc pas déclencher automatiquement une série illimitée de nouvelles recherches.

Après la requête, évaluer d’abord le statut HTTP et le tableau GraphQL errors de premier niveau. Une réponse HTTP 200 peut aussi contenir des erreurs GraphQL. Conserver data.createSearch.urn seulement après ce contrôle. Utiliser l’URN renvoyée sans modification pour le statut et les résultats ; ne pas décomposer ni reconstruire son format. Le statut initial peut varier.

Pour chaque exécution, le client conserve au moins l’UUID du tenant, le texte de la requête, la référence temporelle, la Search-URN et l’heure de début. Une Search-URN désigne l’exécution entière. Une Partition-URN désigne une sous-tâche, tandis qu’un Event Resource Name désigne un événement individuel. Ces identifiants ne sont pas interchangeables.

Réutiliser délibérément des recherches existantes

Si une recherche appropriée, déjà en cours ou terminée, peut être utilisée, getOrCreateSearch constitue une alternative :

{
  "operationName": "GetOrCreateSearch",
  "query": "mutation GetOrCreateSearch($input: CreateSearchInput) { getOrCreateSearch(input: $input) { urn status } }",
  "variables": {
    "input": {
      "text": "from process where earliest = -1h | fields host_id, commandline, image_path"
    }
  }
}

Ici, reprendre l’URN de data.getOrCreateSearch.urn. La correspondance tient compte des données d’entrée et compare les requêtes selon leur représentation structurée canonique, pas seulement selon un texte identique. La réutilisation ne garantit pas des résultats récents et ne doit pas être présentée par le client comme une nouvelle exécution. Si la tâche exige une nouvelle exécution, utiliser délibérément createSearch.

Si un délai d’attente fait perdre la réponse après createSearch, la recherche peut néanmoins être en cours. Une répétition aveugle peut créer une autre exécution. Enregistrer cet état comme « création incertaine » et décider de la reprise selon les exigences de réutilisation et de fraîcheur définies auparavant. getOrCreateSearch ne prouve pas a posteriori que l’exécution perdue a précisément été retrouvée.

Vérifier achèvement, échecs partiels et expiration

Interroger l’état avec la Search-URN conservée. Remplacer <search-urn> uniquement par la valeur réellement renvoyée :

{
  "operationName": "SearchDiagnostics",
  "query": "query SearchDiagnostics($urn: URN!) { search(urn: $urn) { urn status errors expireTime outcome { success errors { urn errors } } searchPartitions { urn schemaType status errors } } }",
  "variables": {
    "urn": "<search-urn>"
  }
}

Tant que status vaut QUEUED ou IN_PROGRESS, le client attend entre les interrogations. outcome.success: UNKNOWN est attendu avant l’achèvement. Un intervalle de cinq secondes, par exemple, est un choix du client possible, et non une limite garantie du service. Chaque requête doit aussi avoir un délai d’attente, et le traitement complet une échéance adaptée à la charge. Après cette échéance, l’exécution reste non résolue ; arrêter l’interrogation locale n’annule pas la recherche côté serveur.

Lorsque status: COMPLETE, évaluer séparément outcome.success :

ValeurSignification
ALLToutes les partitions ont réussi.
PARTIALSeule une partie des partitions a réussi.
NONEAucune partition n’a réussi.

Pour PARTIAL, définir avant l’utilisation en production si des résultats partiels sont acceptables et pour quel usage. Un rapport d’investigation complet ne doit pas les présenter implicitement comme un constat global. Avec NONE, aucun périmètre de recherche réussi ne permet de conclure à l’absence de menace. outcome.errors associe les messages aux partitions ; searchPartitions fournit leur schéma, leur statut et leurs erreurs. Même après une exécution réussie, errors peut contenir des avertissements au niveau de la recherche ou des partitions.

Utiliser aussi expireTime pour vérifier le calendrier de récupération : lire les résultats nécessaires avant cette échéance et les sauvegarder dans son propre système approuvé s’ils doivent être conservés plus longtemps. Conserver une URN ou un curseur ne prolonge pas leur disponibilité. Aucune TTL fixe n’est déduite ici d’un exemple isolé.

Lire toutes les pages de résultats

Après achèvement et évaluation du résultat de l’exécution, demander la première page sans cursor dans les variables :

{
  "operationName": "SearchResults",
  "query": "query SearchResults($urn: URN!, $limit: Int, $cursor: String) { searchResults(urn: $urn, limit: $limit, cursor: $cursor) { fields { name baseType originSchemaTypes } values totals { total { value } subtotals { schemaType value } } nextCursor } }",
  "variables": {
    "urn": "<search-urn>",
    "limit": 2
  }
}

limit: 2 facilite la vérification de la succession des pages pendant le pilote. Il limite les lignes par page, pas le nombre total de correspondances. Pour un client de production, adapter la taille des pages au traitement, sans en déduire une limite maximale documentée ou une limite du résultat global.

Après chaque récupération, vérifier le statut HTTP, les errors GraphQL et le chemin de réponse attendu. Traiter la page seulement ensuite. Même après COMPLETE, la récupération peut encore prendre du temps ; un délai de lecture dépassé ne prouve pas l’échec de la recherche. Réessayer les erreurs de lecture transitoires avec un backoff limité, en conservant les mêmes Search-URN et curseur. Le consommateur doit empêcher qu’une page relue soit exportée deux fois.

Si data.searchResults.nextCursor contient une valeur, la reprendre sans modification dans les variables de la même requête SearchResults :

{
  "urn": "<search-urn>",
  "limit": 2,
  "cursor": "<next-cursor>"
}

Il s’agit uniquement du remplacement de la partie variables, pas d’un corps GraphQL complet. <next-cursor> provient de la page immédiatement précédente traitée avec succès. Chaque curseur reste lié à la Search-URN qui l’a fourni. Ne pas l’interpréter, le modifier ou le transférer à une autre exécution. Continuer jusqu’à ce que nextCursor soit null ou absent. Un curseur répété ou le dépassement de l’échéance client constitue une erreur de récupération, pas une fin réussie.

Distinguer valeurs, métadonnées et totaux

values contient des objets JSON représentant les lignes, pas une liste de colonnes SQL ni une chaîne additionalColumns encodée en JSON comme dans le format de résultat LES. Les entrées peuvent contenir des objets et listes imbriqués. fields décrit les noms et types des champs disponibles ; une métadonnée ne garantit pas une valeur renseignée dans chaque ligne. Traiter aussi bien les champs absents que les valeurs null explicites, sans les assimiler systématiquement à une chaîne vide ou à zéro correspondance.

baseType sert à interpréter les valeurs. Par exemple, TIMESTAMP_SECONDS distingue les secondes de TIMESTAMP_MILLISECONDS et TIMESTAMP_MICROSECONDS ; TIMESTAMP_ISO_8601 désigne une chaîne ISO-8601. Traiter les types liste et map comme des collections, pas comme un scalaire unique. expireTime est également un horodatage ISO-8601. Les métadonnées peuvent nommer des champs imbriqués en notation pointée, comme process_file_hash.md5. Le parseur ne doit donc pas supposer que chaque nom de ce type est une clé plate dans l’objet de ligne.

Les indications facultatives totals.total et totals.subtotals concernent respectivement l’ensemble des résultats et ses schémas, pas la longueur de la liste values actuelle. Pour une récupération complète, traiter toutes les pages et rapprocher les lignes collectées des totaux disponibles. L’absence de totaux ne justifie pas d’inventer un nombre ; la fin des curseurs et la documentation du périmètre récupéré restent nécessaires. Même une pagination complète ne rend pas un résultat PARTIAL entièrement réussi.

Préserver projection QL et enrichissement

Dans l’exemple, | fields host_id, commandline, image_path limite les champs d’événement de la requête QL. L’ensemble de sélection GraphQL détermine, lui, l’inclusion de parties de réponse comme fields, totals ou nextCursor. values est un scalaire JSON : ses champs de ligne individuels ne peuvent pas être choisis par un ensemble de sélection GraphQL imbriqué.

L’enrichissement ajoute des informations dérivées. hostname et enrichSummary ne doivent pas figurer directement dans | fields. Conserver host_id pour résoudre le nom d’hôte. Même ainsi, un nom résoluble n’est pas garanti. Les champs d’entrée de enrichSummary dépendent de l’événement ; une projection plus étroite peut raccourcir le résumé. Avant toute réduction, comparer des événements représentatifs avec les enrichissements nécessaires au consommateur.

Une projection peut réduire la taille de la réponse. Elle ne démontre ni un coût de scan inférieur ni une exécution plus rapide. Omettre les parties de réponse inutiles ne doit surtout pas entraîner la perte de nextCursor, et donc de la possibilité de tout récupérer.

Comparer un client XDR Query existant de manière contrôlée

Passer du SQL historique à Search-QL ne consiste ni à remplacer une URL ni à traduire mécaniquement le SQL. Inventorier d’abord les requêtes existantes, les champs requis et les rapports en aval. La distinction générale entre API XDR reste séparément pertinente pour Cases, Detections et les autres processus.

Pour chaque requête historique, effectuer la comparaison dans cet ordre :

  1. Consigner la question métier et les sources nécessaires. Une table SQL ne justifie pas une correspondance directe avec un schéma QL de même nom ; vérifier chaque schéma et nom de champ.
  2. Fixer des bornes explicites earliest et latest identiques pour les deux recherches et documenter la référence temporelle. Deux requêtes successives « dernière heure » ne constituent pas une comparaison d’égalité rigoureuse.
  3. Vérifier comparaisons de chaînes, sensibilité à la casse et expressions régulières. QL ne prend pas en charge les jointures SQL ; jointures et colonnes dérivées exigent un processus fonctionnel repensé. Ne pas basculer sans équivalence clarifiée.
  4. Vérifier d’abord la requête QL de façon interactive sous Security Operations > Data Lake Search. Exécuter ensuite l’appel API avec les mêmes conditions fonctionnelles.
  5. Comparer des enregistrements représentatifs, les champs obligatoires, types, horodatages et enrichissements, pas seulement les nombres de correspondances. Les deux clients doivent lire intégralement leurs résultats respectifs.
  6. Adapter le nouveau consommateur à values/fields, à la Search-URN et aux curseurs. Ne pas associer aveuglément les anciens états REST finished et succeeded à un seul champ de statut GraphQL : COMPLETE et outcome.success restent des contrôles séparés.

Avant la bascule, la politique d’échec partiel, les répétitions limitées, la gestion d’une création incertaine, l’expiration et la conservation des exports doivent aussi fonctionner. Le pilote tenant approuvé journalise la requête, la fenêtre temporelle, les champs requis et toutes les pages, mais aucun secret. Une recherche vide n’est interprétée qu’après vérification de la source, de la période, des filtres, du résultat d’exécution et des résultats lus intégralement ; ce n’est pas un constat général d’absence de menace.

Jusqu’à l’acceptation, le client XDR Query existant reste le chemin opérationnel convenu. Si le nouveau processus échoue, arrêter la transition ou ramener l’application vers ce client préalablement conservé. Cela ne supprime pas les données déjà exportées et ne répare pas les lacunes de preuve apparues. Une nouvelle recherche ultérieure peut différer de la première en raison d’autres références temporelles ou de données devenues indisponibles.

Isoler les erreurs méthodiquement

  • Requête refusée : Vérifier URL, X-GraphQL-Schema: default, corps JSON, validité du jeton Bearer et UUID du tenant. Clarifier séparément authentification et autorisation propre à l’opération ; ne pas chercher une région par essais. Exclure les secrets des diagnostics.
  • HTTP 200, mais pas de data exploitable : Lire les errors de premier niveau. Vérifier requête, types des variables et champs demandés avant de traiter les données en aval.
  • COMPLETE avec PARTIAL ou NONE : Évaluer outcome.errors, les erreurs de recherche et les searchPartitions concernées. Traiter l’export comme incomplet ou le retenir selon la règle de résultats partiels approuvée auparavant ; ne pas confondre avec zéro correspondance.
  • Nom d’hôte absent ou résumé plus court : Vérifier projection et type d’événement. Conserver host_id pour résoudre le nom d’hôte ; ne pas remplacer les entrées d’enrichissement manquantes par hostname ou enrichSummary dans | fields.
  • Récupération bloquée ou arrêt prématuré : Vérifier délai de requête, échéance globale, URN inchangée, dernière page traitée avec succès et association du curseur. Un petit limit n’est pas une limite globale de résultats.
  • Une URN conservée ne renvoie plus de résultats ultérieurement : Vérifier expireTime et les données déjà sauvegardées. Ni URN ni curseur n’est une archive permanente. Si une nouvelle exécution est nécessaire, la documenter comme telle, pas comme une restauration du résultat initial.

L’API continue d’évoluer. Limiter le client aux opérations documentées createSearch, getOrCreateSearch, search et searchResults, ainsi qu’aux champs pris en charge. Les champs supplémentaires issus de l’introspection ne constituent pas une autorisation automatique d’implémentation.