Export API du SOC : vérifier la pagination avant de conclure
Une requête réussie ne garantit pas un export complet. Vérifiez les pages, le périmètre accessible et les reprises avant de conclure à une absence d’événement.
Périmètre des intégrations : Seculogik utilise une architecture indépendante des sources pour ingérer les alertes et événements de sécurité via son propre modèle de données. Wazuh et OpenSearch sont les premières intégrations. Les autres sources citées correspondent à des connecteurs prévus ; leur disponibilité doit être confirmée pour chaque évaluation.
Un analyste demande les événements d’une période. L’API répond sans erreur, un fichier est créé et la recherche dans ce fichier ne trouve rien de suspect. Mais le fichier contient-il tous les résultats accessibles, ou seulement la première page ? La réussite d’une requête et l’achèvement d’une extraction sont deux constats différents.
Ce guide propose une méthode de vérification indépendante du fournisseur. Elle s’applique aux collectes, exports d’investigation et outils d’assistance qui interrogent une API. Les exemples documentés ne constituent pas une promesse de connecteur Seculogik disponible. Nos recommandations portent sur la qualité de la preuve obtenue, sans demander de nouveaux droits ni l’export de données inutiles.
1. Définir ce que l’export doit couvrir
Notre recommandation : écrire le contrat de recherche avant l’extraction. Précisez l’organisation, les ressources visées, la famille d’événements, la période avec son fuseau, le filtre et l’identité technique utilisée. Identifiez aussi le champ temporel interrogé : heure de l’événement ou heure de réception, par exemple. Une période correctement parcourue sur le mauvais champ ne répond pas forcément à la question de l’enquête.
Séparez ensuite trois conclusions : la requête a été acceptée ; le parcours des résultats est terminé selon le contrat de l’API ; les résultats couvrent les éléments nécessaires à l’enquête. La deuxième ne démontre pas la troisième. Les droits effectifs, les filtres, la conservation et les sources indisponibles peuvent limiter ce qui est accessible.
Si le besoin dépasse l’accès autorisé, documentez la limite et faites traiter la demande par le responsable habilité. N’élargissez pas les droits uniquement pour faire disparaître un résultat vide. Le dossier doit expliquer ce qui a été cherché et ce qui ne pouvait pas l’être.
2. Identifier le signal de continuation documenté
Microsoft Graph fournit, pour ses réponses paginées concernées, une propriété @odata.nextLink à suivre jusqu’à sa disparition. Sa documentation demande d’utiliser l’URL entière retournée, plutôt que d’en extraire un fragment pour reconstruire une autre requête. Le comportement précis dépend de l’API interrogée. Source : Microsoft Graph
GitHub REST illustre un autre contrat : les liens de pagination se trouvent dans l’en-tête link, et la relation next désigne la page suivante. Un traitement qui ne consulte que le corps de réponse peut donc manquer une information de continuation. Source : GitHub Docs
Notre recommandation : pour chaque opération utilisée, noter où se trouve ce signal, comment le suivre et quel état signifie réellement « terminé ». Contrôlez le comportement de votre bibliothèque ou connecteur ; ne supposez pas qu’il parcourt automatiquement toutes les pages parce qu’il retourne une liste.
La consigne AIP-158 de Google autorise même une page vide avant la fin, avec une continuation. Une petite page, ou une page vide, n’est donc pas une preuve universelle de fin de collection. Ce texte est un guide de conception d’API : vérifiez le contrat propre au service utilisé avant de lui appliquer ce comportement. Source : Google AIP-158
3. Conserver une trace du parcours et des interruptions
Nous recommandons un relevé d’exécution proportionné : référence de la recherche, début et fin, nombre de pages reçues, nombre d’éléments enregistrés, erreurs et motif d’arrêt. Distinguez une fin normale d’un arrêt sur délai, limite locale, refus, expiration du curseur ou intervention de l’opérateur. Un fichier partiel peut rester utile s’il est identifié comme tel.
Le point de reprise doit correspondre aux éléments effectivement enregistrés. Si le traitement avance son curseur puis échoue avant de conserver les données, la reprise peut les sauter. S’il recommence une page déjà enregistrée, elle peut être livrée deux fois. Testez ces deux situations au lieu de supposer qu’une simple relance répare tout.
Les liens de continuation et curseurs peuvent contenir des informations sensibles. Gardez les valeurs nécessaires à la reprise dans un stockage autorisé ; ne les recopiez pas dans un commentaire public ou dans tous les logs de diagnostic. Pour le suivi courant, une référence interne contrôlée et l’état « continuation présente » peuvent suffire.
Prévoyez aussi une limite de sécurité contre les boucles de continuation, puis un état d’échec explicite si elle est atteinte. Cette limite protège l’exécution ; elle ne doit pas transformer silencieusement une extraction interrompue en export complet.
4. Tenir compte des données qui changent pendant le parcours
Dans Elasticsearch, la documentation explique qu’un rafraîchissement entre des recherches successives peut modifier l’ordre des résultats. Un point dans le temps peut préserver l’état de l’index pendant le parcours ; les règles de tri et de départage restent à respecter. Cette possibilité appartient à Elasticsearch et ne garantit rien pour une autre API. Source : Elastic, pagination des recherches
Notre recommandation : déterminer si la source fournit une vue stable, une continuation cohérente ou une liste susceptible d’évoluer. Fixer une borne de fin de recherche aide à définir la demande, mais ne fige pas nécessairement les données : une arrivée tardive, une modification ou une suppression peuvent encore affecter le résultat.
Sans garantie de vue stable, documentez la limite et définissez avec le propriétaire de la source une méthode de rapprochement adaptée. Un second passage peut servir à rechercher des écarts ; il ne prouve pas automatiquement l’exhaustivité. Si vous recouvrez des périodes pour absorber des arrivées tardives, vérifiez l’identité des événements avant de dédupliquer.
5. Tester les chemins qui produisent un faux succès
Avant de valider une collecte ou un export, nous recommandons des essais contrôlés avec des données synthétiques, sans secret. Écrivez les résultats attendus puis vérifiez au moins ces situations :
- Plusieurs pages sont nécessaires, avec un événement témoin dans la dernière.
- Une page courte ou vide contient encore un signal de continuation, lorsque le contrat le permet.
- Une erreur survient après une page déjà enregistrée.
- L’enregistrement échoue avant la validation du point de reprise.
- Un curseur expire ou un lien de continuation se répète.
- Les données changent pendant le parcours, selon le comportement documenté de la source.
Exemple entièrement fictif : un jeu d’essai contient trois pages et un événement témoin uniquement sur la troisième. Un premier export s’arrête après la deuxième sur un délai. Il doit être déclaré partiel et ne peut soutenir une conclusion d’absence du témoin. Après une reprise contrôlée, vérifiez que le témoin est présent, que les pages attendues sont conservées et que la page rejouée n’a pas créé une nouvelle occurrence artificielle.
Ne jugez pas le test uniquement au volume final. Vérifiez l’identité du témoin, les limites temporelles, les ressources couvertes et le motif d’arrêt. Contrôlez également que les données d’une autre organisation ne sont pas incluses. Un total plausible peut masquer un trou, un doublon ou un mélange de périmètres.
6. Rédiger une conclusion qui respecte le périmètre
Dans le dossier, indiquez séparément l’état de l’extraction et son résultat d’analyse. Une formulation défendable serait : « Aucun événement correspondant dans les pages conservées pour cette recherche ; extraction interrompue avant le signal de fin. » Après un parcours achevé, précisez encore la période, les filtres et les limites d’accès ou de visibilité connues.
Le critère de réception d’un export devrait permettre à un autre analyste de retrouver la demande, comprendre l’arrêt et vérifier un échantillon des résultats. Il ne suffit pas qu’un fichier existe ou qu’une commande se termine sans erreur.
Pour compléter ces contrôles, consultez notre guide sur les doublons de logs et les retransmissions. Parcourir toutes les pages accessibles et compter correctement les événements sont deux vérifications complémentaires.