Utiliser l'interface utilisateur des flux

Compatible avec :

Ce document explique comment créer, dépanner et gérer des flux dans l'interface utilisateur de gestion des flux. Il fournit également des instructions pour les modifier, les activer et les supprimer.

Avant de commencer

Chaque flux de données nécessite des conditions préalables spécifiques avant d'être configuré dans Google Security Operations. Pour connaître les exigences concernant votre flux, consultez Configuration par type de source et recherchez votre source de données spécifique.

Formats de compression et tailles de fichier acceptés

Les formats de compression acceptés pour l'ingestion de flux sont .gz, .tar.gz, .tar et solr.gz. Le tableau suivant présente les différentes tailles de fichiers compatibles avec la transformation des flux Google SecOps :

Opération Type d'entrée Taille recommandée Durée attendue Taille maximale
Modélisation de données CSV < 5 Go < 7 min 10 Go
Modélisation de données CSV < 5 Go ~30 min 10 Go
Modélisation de données CSV À déterminer À déterminer 2 GB
Modélisation de données XML / JSON < 1 Go < 10 min 2 GB
Modélisation de données XLS / XLSX < 50 Mo 1 min environ 50 Mo
Fusionner des fichiers Tous < 1 Go Varie en fonction du nombre de fichiers 100 Go
Décompresser des fichiers Non-ZIP < 5 Go Varie en fonction du nombre de fichiers 10 Go (non compressés)
Décompresser des fichiers ZIP - Varie en fonction du nombre de fichiers 4 Go (non compressés)

Limites et délimiteurs des lignes de journaux

Lorsque vous ingérez des journaux textuels (JSON, CSV ou Syslog), assurez-vous que vos données respectent les limites d'ingestion spécifiques suivantes :

  • Taille maximale des lignes : une ligne de journal ne peut pas dépasser 4 Mo. Si une seule ligne dépasse cette limite, le flux échoue et génère l'erreur MaxLogLineSize4MBExceeded.
  • Délimiteurs acceptés : les délimiteurs "Nouvelle ligne" (\n) et "Retour chariot + Nouvelle ligne" (\r\n) sont acceptés.

Impact de la modification de votre projet Cloud associé sur les flux de données

Si vous mettez à jour le projet Google Cloud associé à votre instance Google SecOps, tous les flux qui ingèrent des données à l'aide des connecteurs suivants s'arrêteront et devront être recréés manuellement :

  • AMAZON_S3_V2
  • AMAZON_SQS_V2
  • GOOGLE_CLOUD_STORAGE_V2
  • AZURE_BLOBSTORE_V2
  • GOOGLE_CLOUD_STORAGE_EVENT_DRIVEN

Pour tous les autres flux qui n'utilisent pas ces connecteurs, l'ingestion se poursuit sans interruption. Aucune action n'est requise de la part des clients.

Déroulement de la migration

Pour les flux concernés, vous constaterez les modifications suivantes :

  • État des flux : les flux créés avant la migration cesseront immédiatement d'extraire des données en direct et deviendront en lecture seule.
  • Données existantes : toutes les données déjà transférées vers Google SecOps avant la migration seront ingérées automatiquement. Aucune donnée ne sera perdue.
  • Messages d'erreur : si vous essayez de modifier ou de supprimer un ancien flux, le message suivant s'affiche : This feed is read-only because this SecOps has now moved to a new Google Cloud Project (BYOP). To continue ingesting data from this source, please create a new feed.

Actions requises pour les clients

Pour assurer l'ingestion continue des données, vous devez recréer manuellement vos flux dans le nouvel environnement. Pour minimiser les perturbations, procédez comme suit :

  1. Recréez les flux : vous devez créer des flux pour remplacer ceux qui existaient avant la migration.
  2. Configurer l'âge maximal du fichier : lorsque vous configurez vos nouveaux flux, définissez l'âge maximal du fichier sur environ deux heures avant le début de la mise à jour BYOP. Cette marge de temps permet une transition fluide.

  3. Gérer les données en double : selon l'âge maximal des fichiers que vous sélectionnez, il est possible que des données en double soient transférées. Pour en savoir plus sur la manière dont Google SecOps filtre ces journaux redondants, consultez Éviter la déduplication.

  4. Enregistrez et supprimez les flux existants (avant la migration) : avant de commencer la migration BYOP, enregistrez les paramètres de configuration de tous les flux existants qui utilisent les connecteurs concernés (par exemple, Amazon S3 V2), puis supprimez les flux. Si vous ne supprimez pas les flux créés avant la migration, ils deviendront ingérables et resteront dans l'interface Web Google SecOps en tant que paramètres orphelins.

Configurer des flux

Les clients Google SecOps peuvent configurer un flux dans la plate-forme de deux manières. Utilisez la méthode qui convient le mieux à votre environnement :

  • Paramètres SIEM > Flux (standard)
  • Plate-forme de contenu > Packs de contenu (premium)

Configurer vos flux

Cette section explique comment configurer vos flux de manière générale, en commençant par le flux de procédure standard. Les flux de données listés sur la page Flux incluent tous les flux que Google a configurés pour votre compte, y compris ceux que vous avez configurés.

Ajouter un flux

Pour ajouter un flux à votre compte Google SecOps, procédez comme suit :

  1. Dans le menu Google SecOps, sélectionnez Paramètres SIEM > Flux.

  2. Cliquez sur Add New Feed (Ajouter un flux).

  3. Sur la page suivante, cliquez sur Configurer un seul flux. Remarque : Cette étape ne concerne pas les clients qui utilisent la plate-forme autonome Google SecOps SIEM.

  4. Ajoutez un nom au flux.

  5. Dans la liste Type de source, sélectionnez le type de source pour importer des données dans Google SecOps. Vous pouvez choisir parmi les types de sources de flux suivants :

    • Amazon Data Firehose
    • Amazon S3 (obsolète)
    • Amazon S3 (V2)
    • Amazon SQS (obsolète)
    • Amazon SQS (V2)
    • Azure Blob Storage (obsolète)
    • Azure Blob Storage (V2)
    • API personnalisée
    • Google Cloud Pub/Sub
    • Cloud Storage (obsolète)
    • Cloud Storage (V2)
    • Cloud Storage Event Driven
    • API tierce
    • Webhook

    Important :

    • Lorsque vous utilisez les flux Amazon S3 (obsolète), Amazon SQS (obsolète), Azure Blob Storage (obsolète) et Google Cloud Cloud Storage (obsolète), assurez-vous d'avoir un chemin d'accès au répertoire valide.
    • Lorsque vous utilisez Amazon SQS (obsolète) ou Amazon SQS (V2), accordez explicitement les autorisations Google SecOps pour supprimer les messages de la file d'attente Amazon SQS.
    • Lorsque vous utilisez des flux Amazon SQS (obsolètes), assurez-vous qu'un seul flux consomme les messages de la file d'attente. Les messages lus par une autre application ou un autre flux ne sont pas ingérés dans le flux actuel.
    • L'utilisation d'Amazon SQS (obsolète) comme type de source de flux n'est compatible qu'avec les journaux dans les buckets Amazon S3.

  6. Dans la liste Type de journal, sélectionnez le type de journal correspondant à ceux que vous souhaitez ingérer. Les journaux disponibles varient en fonction du type de source que vous avez sélectionné précédemment.

    Si vous sélectionnez Cloud Storage comme type de source, utilisez l'option Obtenir un compte de service pour obtenir un compte de service unique. Consultez l'exemple de configuration du flux Google Cloud Storage.

  7. Cliquez sur Suivant.

  8. Spécifiez les paramètres nécessaires dans l'onglet Paramètres d'entrée. Les options présentées ici varient en fonction de la source et du type de journal sélectionnés dans l'onglet Définir les propriétés. Pointez sur l'icône en forme de point d'interrogation pour chaque champ afin d'obtenir des informations supplémentaires sur ce que vous devez fournir.

  9. Facultatif : Vous pouvez spécifier un espace de noms dans l'onglet Définir les propriétés. Pour en savoir plus sur les espaces de noms, consultez Utiliser les espaces de noms des composants.

  10. Cliquez sur Suivant.

  11. Vérifiez la configuration de votre nouveau flux dans l'onglet Finaliser.

  12. Cliquez sur Envoyer. Google SecOps effectue un contrôle de validation du nouveau flux. Si le flux réussit la vérification, un nom est généré pour le flux, il est envoyé à Google SecOps, et Google SecOps commence à tenter de récupérer les données.

    Finaliser la demande de flux

Configurer plusieurs flux pour une famille de produits (clients Google SecOps uniquement)

Vous pouvez configurer plusieurs flux par famille de produits, en fonction du type de journal.

  • Types de journaux de référence : marqués comme recommandés. Ces types de journaux sont recommandés pour les fonctionnalités de base de la plate-forme.
  • Types de journaux supplémentaires : marqués comme facultatifs. Ces types de journaux fournissent un contexte supplémentaire.

Pour simplifier la configuration, la plate-forme fournit des instructions de configuration spécifiques et des paramètres prédéfinis pour chaque configuration. Par exemple, pour CrowdStrike Falcon, vous pouvez créer plusieurs flux uniques sous les types de journaux recommandés et facultatifs pour vous assurer d'avoir une couverture de données suffisamment complète.

Configurer le flux pour CrowdStrike EDR

Suivez ces étapes pour configurer un flux de journaux pour CrowdStrike EDR.

  1. Dans Paramètres > Flux, cliquez sur Ajouter un flux.
    1. Cliquez sur le produit CrowdStrike Falcon :
    2. Sélectionnez le type de journal CrowdStrike EDR.
  2. Vous pouvez également cliquer sur le produit CrowdStrike Falcon depuis Hub de contenu> Packs de contenu :
    1. Cliquez sur Commencer.
    2. Sélectionnez le type de journal CrowdStrike EDR.

  3. Indiquez les valeurs des champs suivants :

    Champ Description
    Source Type Amazon SQS
    Region Région AWS S3 associée à l'URI.
    Queue Name Nom de la file d'attente SQS à partir de laquelle lire les données.
    Account Number Numéro de compte SQS.
    Source Deletion Option Indique s'il faut supprimer les fichiers et les répertoires après le transfert.
    Queue Access Key ID Clé d'accès alphanumérique de 20 caractères pour le compte, par exemple AKIAOSFOODNN7EXAMPLE.
    Queue Secret Access Key Clé d'accès secrète alphanumérique de 40 caractères pour le compte, par exemple wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY.

  4. (Facultatif) Configurez les paramètres suivants :

    • Nom du flux : nom unique prérempli du flux.
    • Espace de noms de l'élément : espace de noms associé au flux.
    • Libellés d'ingestion : libellés appliqués aux événements de ce flux.

  5. Cliquez sur Créer un flux.

Vous pouvez répéter cette procédure pour créer d'autres flux pour le même type de journaux. Vous pouvez également configurer des flux pour d'autres types de journaux disponibles directement sur cette page. Une fois l'opération terminée, accédez à la page Gestion des flux pour afficher un récapitulatif détaillé de tous les types de journaux configurés.

Liste d'autorisation d'adresses IP

Activez la liste d'autorisation et ajoutez les plages d'adresses IP Google pour tous les types de journaux qui ingèrent des données provenant d'API tierces.

Supprimer les fichiers sources

L'option de suppression de la source vous permet de supprimer les objets de source de flux (fichiers et dossiers) du stockage après un transfert réussi. Cette option n'est disponible que pour certains types de sources de flux, y compris Cloud Storage. Ces types de sources de flux incluent le champ OPTION DE SUPPRESSION DE LA SOURCE dans leurs workflows Ajouter un flux et Modifier le flux.

Options de suppression des sources

  • Pour les types de sources de flux compatibles, y compris Cloud Storage, le champ OPTION DE SUPPRESSION DE LA SOURCE propose les options suivantes :

    • Ne jamais supprimer les fichiers
    • Supprimer les fichiers transférés et les répertoires vides
    • Supprimer les fichiers transférés

  • Microsoft Azure Blob Storage (AZURE_BLOBSTORE) ne permet pas de supprimer les fichiers sources. Dans le champ OPTION DE SUPPRESSION DE LA SOURCE, sélectionnez uniquement l'option Ne jamais supprimer les fichiers.

  • Pour les sources de flux suivantes ("feedSourceType") : GOOGLE_CLOUD_STORAGE_V2, GOOGLE_CLOUD_STORAGE_EVENT_DRIVEN, AMAZON_S3_V2, AMAZON_SQS_V2 et AZURE_BLOBSTORE_V2, le champ OPTION DE SUPPRESSION DE LA SOURCE propose deux options :

    • JAMAIS : ne supprime jamais aucun fichier après les transferts.
    • ON_SUCCESS : supprime tous les fichiers et répertoires vides après le transfert.

Configuration et autorisations spécifiques à la source

Différents types de sources nécessitent des configurations d'authentification et de mise en réseau spécifiques pour communiquer avec Google SecOps. Cette section explique comment configurer les autorisations et les comptes de service. La configuration décrite se concentre sur l'ingestion Cloud Storage (extraction), l'ingestion multicloud (extraction cross-cloud) et l'ingestion basée sur l'envoi (API ou en temps réel).

Exemple de configuration d'un flux Google Cloud Storage

  1. Dans le menu Google SecOps, sélectionnez Settings (Paramètres), puis cliquez sur Feeds (Flux).
  2. Cliquez sur Add New Feed (Ajouter un flux).
  3. Sur la page suivante, cliquez sur Configurer un seul flux. Cette étape ne s'applique pas si vous utilisez la plate-forme autonome Google SecOps SIEM.
  4. Sélectionnez Cloud Storage V2 pour Type de source.
  5. Sélectionnez le type de journal. Par exemple, pour créer un flux pour les journaux d'audit Google Kubernetes Engine, sélectionnez Journaux d'audit Google Kubernetes Engine comme Type de journal.
  6. Cliquez sur Obtenir un compte de service. Google SecOps fournit un compte de service unique que Google SecOps utilise pour ingérer les données. Vous pouvez également obtenir ce compte de service de manière programmatique à l'aide de l'API. Consultez Récupérer un compte de service.
  7. Facultatif : configurez le compte de service. Pour en savoir plus, consultez Accorder l'accès au compte de service Google SecOps.
  8. Cliquez sur Suivant.

  9. En fonction de la configuration Cloud Storage que vous avez créée, spécifiez des valeurs pour les champs suivants :

    • URI du bucket de stockage

    • Option de suppression de la source

    Pour savoir comment configurer des buckets Cloud Storage, consultez Créer des buckets.

  10. Cliquez sur Suivant, puis sur Envoyer.

Accorder l'accès au compte de service Google SecOps

  1. Dans la console Google Cloud , accédez à la page Buckets de Cloud Storage.

    Accéder à la page "Buckets"

  2. Accordez au compte de service l'accès aux objets Cloud Storage concernés.

    • Pour accorder l'autorisation de lecture à un fichier spécifique, procédez comme suit :

      1. Sélectionnez le fichier, puis cliquez sur Modifier l'accès.
      2. Cliquez sur Ajouter un compte principal.
      3. Dans le champ Nouveaux comptes principaux, saisissez le nom du compte de service Google SecOps.
      4. Attribuez un rôle contenant l'autorisation de lecture au compte de service Google SecOps. Par exemple, Lecteur des objets Storage (roles/storage.objectViewer). Vous ne pouvez le faire que si vous n'avez pas activé l'accès uniforme au niveau du bucket.
      5. Cliquez sur Enregistrer.

    • Pour accorder l'autorisation de lecture à plusieurs fichiers, accordez l'accès au niveau du bucket comme suit :

      • Pour "feedSourceType": "GOOGLE_CLOUD_STORAGE" :

        1. Ajoutez le compte de service Google SecOps en tant que compte principal à votre bucket Storage et accordez-lui le rôle IAM Lecteur des objets Storage (roles/storage.objectViewer).
        2. Si vous configurez le flux pour supprimer les fichiers sources, vous devez ajouter le compte de service Google SecOps en tant que compte principal dans votre bucket et lui attribuer le rôle IAM Administrateur des objets de l'espace de stockage (roles/storage.objectAdmin).

      • Pour "feedSourceType": "GOOGLE_CLOUD_STORAGE_V2", attribuez les rôles suivants :

        1. Attribuez ce rôle :

          • Lecteur des objets Storage (roles/storage.objectViewer) si le transfert se fait vers un autre bucket Cloud Storage.

        2. Attribuez l'un des rôles suivants, en fonction de l'option que vous avez sélectionnée pour Option de suppression de la source. Si vous sélectionnez En cas de réussite, accordez le rôle Rédacteur de bucket Storage Legacy. Si vous sélectionnez Jamais, accordez le rôle Lecteur des anciens buckets de l'espace de stockage :

          • Rédacteur des anciens buckets Storage (roles/storage.legacyBucketWriter) si une autorisation de suppression d'objet est requise.
          • Lecteur des anciens buckets Storage (roles/storage.legacyBucketReader) si l'autorisation de suppression des objets n'est pas requise.

      • Pour "feedSourceType": "GOOGLE_CLOUD_STORAGE_EVENT_DRIVEN" :

        1. Attribuez l'un des rôles suivants :

          • Lecteur des objets Storage (roles/storage.objectViewer) si le transfert se fait vers un autre bucket Cloud Storage.
          • Créateur des objets de l'espace de stockage (roles/storage.objectCreator) si le transfert concerne un système de fichiers.

        2. Attribuez l'un des rôles suivants :

          • Rédacteur des anciens buckets Storage (roles/storage.legacyBucketWriter) si une autorisation de suppression d'objet est requise.
          • Lecteur des anciens buckets Storage (roles/storage.legacyBucketReader) si l'autorisation de suppression des objets n'est pas requise.

Activer l'accès STS pour Amazon S3 et Azure Storage

Le STS est utilisé par les flux Google Cloud Storage suivants pour transférer des données depuis les magasins d'objets blob Amazon S3 et Azure Storage vers Google SecOps :

  • Amazon S3 (V2)
  • Amazon SQS (V2)
  • Azure Blob Storage (V2)

Le STS envoie des demandes de transfert de données aux services de stockage Amazon S3 et Azure à partir d'un ensemble de plages d'adresses IP STS définies. Ces plages d'adresses IP STS sont publiées dans le fichier JSON suivant : Plages d'adresses IP

Pour utiliser ces types de sources de flux STS, vous devrez peut-être ajuster les restrictions d'accès aux adresses IP afin de permettre à STS d'accéder à vos services de stockage Amazon S3 et Azure :

  1. Extrayez les dernières plages d'adresses IP du fichier JSON.

    Nous vous recommandons de lire les données de ce fichier JSON au moins une fois par semaine pour que votre configuration de sécurité reste à jour. Lorsqu'une nouvelle plage est ajoutée au fichier, le système attend au moins sept jours avant de l'utiliser pour les demandes provenant de STS.

    Pour obtenir un exemple de script Python qui récupère les plages d'adresses IP à partir d'un fichier JSON, consultez Adresses IP pour les domaines par défaut.

  2. Comparez la plage d'adresses IP actuelle creationTime à la plage d'adresses IP creationTime lue à partir du fichier JSON précédent. Si elles diffèrent, mettez à jour les restrictions d'accès aux adresses IP dans les magasins d'objets blob Amazon S3 et Azure Storage.

    • Pour Amazon S3

      Pour mettre à jour les restrictions d'accès aux adresses IP dans votre blobstore Amazon S3 :

      Si votre projet AWS utilise des restrictions d'adresse IP pour accéder au stockage, vous devez ajouter les plages d'adresses IP utilisées par les nœuds de calcul STS à votre liste d'adresses IP autorisées.

      Pour ajouter ces plages en tant qu'adresses IP autorisées, utilisez le champ Condition dans un bucket policy, comme décrit dans la documentation AWS S3 : Gérer l'accès en fonction d'adresses IP spécifiques.

    • Pour Azure Storage

      Pour mettre à jour les restrictions d'accès aux adresses IP dans votre blobstore Azure Storage :

      Si vous limitez l'accès à vos ressources Azure à l'aide d'un pare-feu Azure Storage, vous devez ajouter les plages d'adresses IP utilisées par les nœuds de calcul STS à votre liste d'adresses IP autorisées.

      Pour ajouter ces plages en tant qu'adresses IP autorisées, suivez ces instructions : Configurer les pare-feu et les réseaux virtuels Azure Storage.

Configurer un flux push Pub/Sub

Pour configurer un flux push Pub/Sub :

  1. Créez un flux push Pub/Sub.
  2. Spécifiez l'URL du point de terminaison dans un abonnement Pub/Sub.

Créer un flux push Pub/Sub

  1. Dans le menu Google SecOps, sélectionnez Paramètres, puis cliquez sur Flux.
  2. Cliquez sur Ajouter.
  3. Dans le champ Nom du flux, saisissez un nom pour le flux.
  4. Dans la liste Type de source, sélectionnez Google Cloud Pub/Sub Push.
  5. Sélectionnez le type de journal. Par exemple, pour créer un flux pour l'Open Cybersecurity Schema Framework, sélectionnez Open Cybersecurity Schema Framework (OCSF) comme Type de journal.
  6. Cliquez sur Suivant.
  7. Facultatif : Spécifiez les valeurs des paramètres d'entrée suivants :
    • Délimiteur de fractionnement : délimiteur utilisé pour séparer les lignes de journaux. Vous ne pouvez utiliser que \n.
    • Espace de noms de l'élément : espace de noms de l'élément.
    • Libellés d'ingestion : libellé à appliquer aux événements de ce flux.
  8. Cliquez sur Suivant.
  9. Vérifiez la configuration de votre nouveau flux sur l'écran Finaliser, puis cliquez sur Envoyer.
  10. Dans l'onglet Détails, copiez l'URL du point de terminaison du flux à partir du champ Informations sur le point de terminaison. Vous avez besoin de cette URL de point de terminaison pour créer un abonnement push dans Pub/Sub.
  11. Facultatif : Cliquez sur le bouton Flux activé pour désactiver le flux. Le flux est activé par défaut.
  12. Cliquez sur OK.

Spécifier l'URL du point de terminaison

Après avoir créé un flux push Pub/Sub, spécifiez l'URL du point de terminaison comme suit :

  1. Dans Pub/Sub, créez un abonnement push. Pour savoir comment créer un abonnement push, consultez Créer des abonnements push.
  2. Spécifiez l'URL du point de terminaison, qui est disponible dans le flux push Pub/Sub Google Cloud .
  3. Sélectionnez Activer l'authentification, puis sélectionnez un compte de service.
  4. Désactivez les options Unwrapping de la charge utile push et Unwrapping de la charge utile push : métadonnées d'écriture de message.

Configurer un flux Amazon Data Firehose

Pour configurer un flux Amazon Data Firehose :

  1. Créez un flux Amazon Data Firehose, puis copiez l'URL du point de terminaison et la clé secrète.
  2. Créez une clé API pour vous authentifier auprès de Google SecOps. Vous pouvez également réutiliser votre clé API existante pour vous authentifier auprès de Google SecOps.
  3. Spécifiez l'URL du point de terminaison dans Amazon Data Firehose.

Créer un flux Amazon Data Firehose

  1. Dans le menu Google SecOps, sélectionnez Paramètres, puis cliquez sur Flux.
  2. Cliquez sur Ajouter.
  3. Dans le champ Nom du flux, saisissez un nom pour le flux.
  4. Dans la liste Type de source, sélectionnez Amazon Data Firehose.
  5. Sélectionnez le type de journal. Par exemple, pour créer un flux pour l'Open Cybersecurity Schema Framework, sélectionnez Open Cybersecurity Schema Framework (OCSF) comme Type de journal.
  6. Cliquez sur Suivant.
  7. Facultatif : Spécifiez les valeurs des paramètres d'entrée suivants :
    • Délimiteur de fractionnement : délimiteur utilisé pour séparer les lignes de journaux. Vous ne pouvez utiliser que \n.
    • Espace de noms de l'élément : espace de noms de l'élément.
    • Libellés d'ingestion : libellé à appliquer aux événements de ce flux.
  8. Cliquez sur Suivant.
  9. Vérifiez la configuration de votre nouveau flux sur l'écran Finaliser, puis cliquez sur Envoyer.
  10. Cliquez sur Générer une clé secrète pour générer une clé secrète permettant d'authentifier ce flux.
  11. Copiez et stockez la clé secrète, car vous ne pourrez plus l'afficher. Vous pouvez générer une nouvelle clé secrète, mais l'ancienne deviendra obsolète.
  12. Dans l'onglet Détails, copiez l'URL du point de terminaison du flux à partir du champ Informations sur le point de terminaison. Vous aurez besoin de cette URL de point de terminaison lorsque vous spécifierez les paramètres de destination de votre flux de diffusion dans Amazon Data Firehose.
  13. Facultatif : Cliquez sur le bouton Flux activé pour désactiver le flux. Le flux est activé par défaut.
  14. Cliquez sur OK.

Créer une clé API pour le flux Amazon Data Firehose

Pour créer une clé API pour le flux Amazon Data Firehose :

  1. Accédez à la page Identifiants de la console Google Cloud .
  2. Cliquez sur Créer des identifiants et sélectionnez Clé API.
  3. Restreignez l'accès à l'API Chronicle avec la clé API.

Spécifier l'URL du point de terminaison

Dans Amazon Data Firehose, spécifiez le point de terminaison HTTPS et la clé d'accès, comme suit :

  1. Ajoutez la clé API à l'URL du point de terminaison du flux et spécifiez cette URL comme URL du point de terminaison HTTP au format suivant :

      ENDPOINT_URL?key=API_KEY

    Remplacez les éléments suivants :

    • ENDPOINT_URL : URL du point de terminaison du flux.
    • API_KEY : clé API pour s'authentifier auprès de Google SecOps.

  2. Pour la clé d'accès, spécifiez la clé secrète que vous avez obtenue lorsque vous avez créé le flux Amazon Data Firehose.

Configurer un flux de webhook HTTPS

Avant de commencer :

Pour configurer un flux de webhook HTTPS :

  1. Créez un flux de webhook HTTPS, puis copiez l'URL du point de terminaison et la clé secrète.
  2. Créez une clé API spécifiée avec l'URL du point de terminaison. Vous pouvez également réutiliser votre clé API existante pour vous authentifier auprès de Google SecOps.
  3. Spécifiez l'URL du point de terminaison dans votre application.

Envoyer plusieurs événements dans une seule requête de webhook

L'exemple de code suivant montre comment mettre en forme un corps de requête unique avec plusieurs objets JSON séparés par des sauts de ligne après l'élément curl --location :

--header 'Content-Type: application/json' \
--header 'X-goog-api-key: API_KEY' \
--header 'X-Webhook-Access-Key: SECRET' \
--data '{"principal": {"asset_id": "asset 123"}, "metadata": {"event_type": "GENERIC_EVENT", "product_name": "Product Acme"}}
{"principal": {"asset_id": "asset 123"}, "metadata": {"event_type": "GENERIC_EVENT", "product_name": "Product Acme"}}'

Créer un flux de webhook HTTPS

  1. Dans le menu Google SecOps, sélectionnez Paramètres, puis cliquez sur Flux.
  2. Cliquez sur Ajouter.
  3. Dans le champ Nom du flux, saisissez un nom pour le flux.
  4. Dans la liste Type de source, sélectionnez Webhook.
  5. Sélectionnez le type de journal. Par exemple, pour créer un flux pour l'Open Cybersecurity Schema Framework, sélectionnez Open Cybersecurity Schema Framework (OCSF) comme Type de journal.
  6. Cliquez sur Suivant.
  7. Facultatif : Spécifiez les valeurs des paramètres d'entrée suivants :
    • Délimiteur de fractionnement : délimiteur utilisé pour séparer les lignes de journaux. Vous ne pouvez utiliser que \n.
    • Espace de noms de l'élément : espace de noms de l'élément.
    • Libellés d'ingestion : libellé à appliquer aux événements de ce flux.
  8. Cliquez sur Suivant.
  9. Vérifiez la configuration de votre nouveau flux sur l'écran Finaliser, puis cliquez sur Envoyer.
  10. Cliquez sur Générer une clé secrète pour générer une clé secrète permettant d'authentifier ce flux.
  11. Copiez et stockez la clé secrète, car vous ne pourrez plus l'afficher. Vous pouvez générer une nouvelle clé secrète, mais l'ancienne deviendra obsolète.
  12. Dans l'onglet Détails, copiez l'URL du point de terminaison du flux à partir du champ Informations sur le point de terminaison. Vous devez spécifier cette URL de point de terminaison dans votre application cliente.
  13. Facultatif : Cliquez sur le bouton Flux activé pour désactiver le flux. Le flux est activé par défaut.
  14. Cliquez sur OK.

Créer une clé API pour le flux de webhook

  1. Accédez à la page Identifiants de la console Google Cloud .
  2. Cliquez sur Créer des identifiants, puis sélectionnez Clé API.
  3. Restreignez l'accès à l'API Chronicle avec la clé API.

Spécifier l'URL du point de terminaison

  1. Dans votre application cliente, spécifiez le point de terminaison HTTPS, qui est disponible dans le flux de webhook.

  2. Activez l'authentification en spécifiant la clé API et la clé secrète dans l'en-tête personnalisé au format suivant :

    X-goog-api-key = API_KEY

    X-Webhook-Access-Key = SECRET

    Nous vous recommandons de spécifier la clé API en tant qu'en-tête plutôt que dans l'URL. Si votre client de webhook n'accepte pas les en-têtes personnalisés, vous pouvez spécifier la clé API et la clé secrète à l'aide de paramètres de requête au format suivant :

      ENDPOINT_URL?key=API_KEY&secret=SECRET

    Remplacez les éléments suivants :

    • ENDPOINT_URL : URL du point de terminaison du flux.
    • API_KEY : clé API pour s'authentifier auprès de Google SecOps.
    • SECRET : clé secrète que vous avez générée pour authentifier le flux.

Configurer un flux d'API personnalisée

Les flux d'API personnalisés Google Security Operations (également appelés "connecteurs sans code") vous permettent d'ingérer la télémétrie à partir d'API REST tierces à l'aide d'un modèle flexible basé sur la configuration. Vous pouvez configurer les extractions de données en définissant des points de terminaison, l'authentification, des stratégies de pagination et la gestion de l'état directement dans la console.

Principaux avantages

  • Accélérez l'intégration : intégrez de nouvelles sources de télémétrie en quelques minutes grâce à un assistant guidé, sans attendre les mises à jour du backend.
  • Point de contrôle avec état : assurez-vous qu'il n'y a pas de duplication de données ni de journaux manquants lors des cycles d'interrogation.
  • Distribution ramifiée parent-enfant : compatible avec les workflows de découverte à deux niveaux, comme la liste des ressources et la récupération de leur télémétrie associée.
  • Résilience et limitation du débit automatisées : empêchent la limitation du débit et l'épuisement du quota par les fournisseurs. Pour une ingestion fiable et ininterrompue, le flux de l'API personnalisée gère automatiquement les réponses HTTP 429 avec un délai exponentiel, rythme les requêtes avec une limitation du débit et un échelonnement du délai des tâches configurables, et applique des mesures de sécurité. Pour en savoir plus, consultez Consignes de limitation du débit et de l'étranglement.

Prérequis

Vérifiez les conditions préalables suivantes avant de créer un flux d'API personnalisé :

  • Autorisations : pour créer ou modifier des flux, vous devez disposer du rôle Administrateur de l'API Chronicle (roles/chronicle.admin) ou Éditeur de l'API Chronicle (roles/chronicle.editor).
  • Exigences concernant les API tierces :
    • URL de base de l'API valide (doit utiliser https://).
    • Identifiants API (clé API, identifiants d'authentification de base ou ID/code secret du client OAuth 2.0).
    • Documentation de l'API du fournisseur détaillant les chemins d'accès aux points de terminaison, les paramètres de requête, les structures de réponse JSON et les limites de débit.
  • Accès à Secret Manager : les identifiants sont chiffrés et gérés de manière sécurisée dans Secret Manager. L'identité de service qui exécute le connecteur interagit automatiquement avec Secret Manager (roles/secretmanager.secretAccessor et roles/secretmanager.admin).

Configurer un flux d'API personnalisé

Pour configurer un flux d'API personnalisé :

  1. Accédez à Paramètres SIEM > Flux.
  2. Cliquez sur Ajouter un flux.
  3. Cliquez sur Configurer un flux unique.
  4. Dans le champ Nom du flux, saisissez un nom descriptif unique (par exemple, 1Password-Audit-Events).
  5. Dans la liste Type de source, sélectionnez API personnalisée.
  6. Dans la liste Type de journal, sélectionnez le type de journal Google SecOps cible.
  7. Cliquez sur Suivant.

  8. Sous Paramètres généraux, configurez les éléments suivants :

    • URL de base : saisissez l'hôte principal (par exemple, https://events.1password.com). Il doit commencer par https://. N'ajoutez pas de sous-chemins ni de barres obliques à la fin.

    • Fréquence d'interrogation : indiquez la fréquence à laquelle la plate-forme vérifie si l'API contient de nouvelles données de télémétrie, en minutes. Plage acceptée : de 5 à 2 880 minutes (par défaut : 15 minutes). Pour les flux API standard (séquentielle), 10 à 15 minutes sont généralement suffisantes. Pour les flux Liste et détails (parent-enfant), 30 à 60 minutes sont recommandées pour permettre l'exécution complète des tâches de distribution ramifiée sans chevauchement.

  9. Sous Authentification, sélectionnez l'une des méthodes d'authentification compatibles, puis configurez les champs requis :

    • Authentification de base : saisissez le nom d'utilisateur (identité du compte API) et le code secret (mot de passe ou jeton secret).
    • Identifiants client OAuth 2.0 : authentifiez-vous à l'aide du flux d'attribution des identifiants client OAuth 2.0. Google SecOps demande, met en cache et actualise automatiquement les jetons d'accès du porteur avant chaque cycle d'ingestion. Saisissez le point de terminaison du jeton OAuth (par exemple, https://auth.vendor.com/oauth/token), l'ID client OAuth et le secret client OAuth.
    • En-têtes de requête de clé API : authentifiez-vous à l'aide de clés API personnalisées injectées dans les en-têtes de requête (le modèle REST d'entreprise le plus courant). Saisissez le nom de l'en-tête (par exemple, Authorization ou X-API-Key) et la valeur de l'en-tête (par exemple, Bearer <SECRET_TOKEN> ou <SECRET_KEY>).
    • Paramètres de requête de clé API : authentifiez-vous à l'aide de clés API personnalisées injectées dans les paramètres de requête d'URL. Saisissez le nom du paramètre de requête (par exemple, api_key) et la valeur du paramètre de requête (par exemple, <SECRET_KEY>).

  10. Sélectionnez le modèle de connecteur utilisé par votre API personnalisée :

    • API standard (séquentielle) : flux d'interrogation linéaire où chaque interrogation s'appuie directement sur l'état de la précédente. Dans ce modèle, la prochaine interrogation utilise un curseur, un jeton ou un code temporel extrait de l'interrogation précédente pour n'extraire que les nouvelles données. Sélectionnez cette fiche lorsque le fournisseur fournit un point de terminaison qui renvoie directement les enregistrements d'événements de télémétrie (par exemple, 1Password, Okta, SentinelOne, GitHub ou Slack).
    • Liste et détails (parent-enfant) : parcours de découverte à deux niveaux. Le flux effectue un appel initial (parent) pour récupérer une liste de ressources ou d'objets (par exemple, une liste d'ID utilisateur ou de zones). Le flux génère ensuite automatiquement des appels de suivi dépendants (enfants) pour récupérer la télémétrie détaillée de chaque ressource identifiée. Sélectionnez cette fiche lorsque l'API du fournisseur nécessite un modèle de découverte à deux niveaux : d'abord en appelant un point de terminaison pour récupérer une liste dynamique d'entités (par exemple, des zones, des comptes, des projets ou des appareils), puis en exécutant des demandes de détails de suivi par entité pour récupérer la télémétrie (par exemple, Cloudflare, AWS CloudWatch ou Tenable).

  11. Si vous avez sélectionné API standard (séquentielle), procédez comme suit :

    1. Sous Point de terminaison de l'API, configurez les paramètres suivants pour définir l'itinéraire technique et le rythme de diffusion de la demande :
      • Chemin du point de terminaison : route d'API spécifique ajoutée à l'URL de base (par exemple, /api/v1/auditevents). Elle définit la ressource de télémétrie exacte à interroger.
      • Méthode HTTP : sélectionnez GET pour récupérer des données à l'aide de paramètres de requête d'URL ou POST pour envoyer une charge utile de recherche ou un corps de filtre.
    2. Corps de la requête : pour les requêtes POST, fournissez la charge utile des données JSON. Vous pouvez intégrer des variables de point de contrôle dynamiques telles que {"limit": 100, "start_time": "{{.last_timestamp}}"}.
    3. Nombre maximal de requêtes par minute : saisissez le nombre maximal de requêtes à envoyer par minute. Il s'agit d'un limiteur de débit côté client permettant de respecter les limites de débit des API des fournisseurs (par défaut, 5 requêtes par minute, soit une requête toutes les 12 secondes). Ce paramètre empêche l'épuisement du quota lors de la pagination sur plusieurs pages.
    4. Facultatif : Sous En-têtes personnalisés, configurez le Nom de l'en-tête et la Valeur, puis cliquez sur Ajouter pour définir les en-têtes HTTP spécialisés requis par l'API cible (par exemple, Content-Type: application/json, Accept: application/json).
    5. Facultatif : Sous Paramètres de requête, configurez la clé et la valeur, puis cliquez sur Ajouter pour spécifier des filtres ou des options supplémentaires ajoutés à la chaîne de requête de l'URL (par exemple, count=1000, status=active) ou pour lier des variables de modèle dynamiques (par exemple, start={{.last_run_time}}).
    6. Sous Stratégie de pagination, sélectionnez le mécanisme de pagination requis par l'API tierce pour gérer les ensembles de résultats multipages, puis configurez les champs requis :
      • Aucun : récupère les données en une seule requête sans pagination.
      • Pagination par jeton : utilisez des jetons (clés personnalisées) pour obtenir la page suivante. Saisissez le chemin JSON du jeton de page suivante (par exemple, meta.next_cursor) et le nom du paramètre de requête de pagination du jeton (par exemple, cursor).
      • Pagination des liens : suivez les URL fournies dans la réponse pour obtenir plus de données. Saisissez le chemin JSON du lien vers la page suivante (par exemple, links.next ou @odata.nextLink).
      • Pagination par décalage : ignorez un nombre défini d'enregistrements pour obtenir l'ensemble suivant. Saisissez le nom du paramètre de requête de décalage (par exemple, offset).
      • Pagination par numéro de page : accédez au numéro de page séquentiel suivant. Saisissez le nom du paramètre de requête du numéro de page (par exemple, page).

    7. Sous Point de contrôle, configurez les paramètres qui permettent au connecteur de se souvenir de l'endroit où il s'est arrêté entre les cycles d'interrogation récurrents :

      • Stratégie : choisissez l'une des stratégies suivantes et configurez les champs requis :
        • Aucun : récupérez toutes les données disponibles sans suivre la progression au cours des cycles.
        • Dernier code temporel : suivez le code temporel du dernier enregistrement. Saisissez le chemin JSON de la valeur du point de contrôle (par exemple, timestamp ou event_time) et la variable du point de contrôle (par exemple, last_run_time, référencée dans les sondages suivants sous la forme {{.last_run_time}}).
        • Dernier enregistrement : suivez l'ID d'enregistrement le plus élevé pour n'extraire que les nouveaux enregistrements. Saisissez le chemin JSON de la valeur du point de contrôle (par exemple, id ou event_id) et la variable du point de contrôle (par exemple, last_id, référencée sous la forme {{.last_id}}).
        • Jeton d'itérateur : utilisez les jetons de continuation persistants fournis par l'API. Saisissez le chemin JSON de la valeur du point de contrôle et la variable du point de contrôle (par exemple, iterator_token, référencée sous la forme {{.iterator_token}}).

    8. Sous Mappage des réponses, fournissez des règles indiquant à la plate-forme comment localiser et extraire les journaux :

      • Chemin JSON des données cibles : saisissez le chemin exact dans la charge utile de la réponse de l'API où se trouve la liste des entrées de journal cibles. Pour les tableaux encapsulés dans un objet (par exemple, {"items": [...]}), saisissez items. Pour les API renvoyant directement un tableau JSON racine (par exemple, [{...}, {...}]), laissez ce champ complètement vide ([]).

  12. Si vous avez sélectionné Liste et détails (parent-enfant), procédez comme suit :

    1. Requête parente (découverte) : configurez le point de terminaison qui renvoie une liste d'éléments :
      1. Sous Point de terminaison de l'API, configurez les paramètres suivants pour définir l'itinéraire technique et le rythme de diffusion de la demande :
        • Chemin du point de terminaison : route d'API spécifique ajoutée à l'URL de base (par exemple, /api/v1/auditevents). Elle définit la ressource de télémétrie exacte à interroger.
        • Méthode HTTP : sélectionnez GET pour récupérer des données à l'aide de paramètres de requête d'URL ou POST pour envoyer une charge utile de recherche ou un corps de filtre.
        • Corps de la requête : pour les requêtes POST, fournissez la charge utile des données JSON. Vous pouvez intégrer des variables de point de contrôle dynamiques telles que {"limit": 100, "start_time": "{{.last_timestamp}}"}.
      2. Nombre maximal de requêtes par minute : saisissez le nombre maximal de requêtes à envoyer par minute. Il s'agit d'un limiteur de débit côté client permettant de respecter les limites de débit des API des fournisseurs (par défaut, 5 requêtes par minute, soit une requête toutes les 12 secondes). Ce paramètre empêche l'épuisement du quota lors de la pagination sur plusieurs pages.
      3. Facultatif : Sous En-têtes personnalisés, configurez le Nom de l'en-tête et la Valeur, puis cliquez sur Ajouter pour définir les en-têtes HTTP spécialisés requis par l'API cible (par exemple, Content-Type: application/json, Accept: application/json).
      4. Facultatif : Sous Paramètres de requête, configurez la clé et la valeur, puis cliquez sur Ajouter pour spécifier des filtres ou des options supplémentaires ajoutés à la chaîne de requête de l'URL (par exemple, count=1000, status=active) ou pour lier des variables de modèle dynamiques (par exemple, start={{.last_run_time}}).
      5. Sous Stratégie de pagination, sélectionnez le mécanisme de pagination requis par l'API tierce pour gérer les ensembles de résultats multipages, puis configurez les champs requis :
        • Aucun : récupère les données en une seule requête sans pagination.
        • Pagination par jeton : utilisez des jetons (clés personnalisées) pour obtenir la page suivante. Saisissez le chemin JSON du jeton de page suivante (par exemple, meta.next_cursor) et le nom du paramètre de requête de pagination du jeton (par exemple, cursor).
        • Pagination des liens : suivez les URL fournies dans la réponse pour obtenir plus de données. Saisissez le chemin JSON du lien vers la page suivante (par exemple, links.next ou @odata.nextLink).
        • Pagination par décalage : ignorez un nombre défini d'enregistrements pour obtenir l'ensemble suivant. Saisissez le nom du paramètre de requête de décalage (par exemple, offset).
        • Pagination par numéro de page : accédez au numéro de page séquentiel suivant. Saisissez le nom du paramètre de requête du numéro de page (par exemple, page).
      6. Sous Point de contrôle, configurez les paramètres qui permettent au connecteur de se souvenir de l'endroit où il s'est arrêté entre les cycles d'interrogation récurrents :
        • Stratégie : choisissez l'une des stratégies suivantes et configurez les champs requis :
          • Aucun : récupérez toutes les données disponibles sans suivre la progression au cours des cycles.
          • Dernier code temporel : suivez le code temporel du dernier enregistrement. Saisissez le chemin JSON de la valeur du point de contrôle (par exemple, timestamp ou event_time) et la variable du point de contrôle (par exemple, last_run_time, référencée dans les sondages suivants sous la forme {{.last_run_time}}).
          • Dernier enregistrement : suivez l'ID d'enregistrement le plus élevé pour n'extraire que les nouveaux enregistrements. Saisissez le chemin JSON de la valeur du point de contrôle (par exemple, id ou event_id) et la variable du point de contrôle (par exemple, last_id, référencée sous la forme {{.last_id}}).
          • Jeton d'itérateur : utilisez les jetons de continuation persistants fournis par l'API. Saisissez le chemin JSON de la valeur du point de contrôle et la variable du point de contrôle (par exemple, iterator_token, référencée sous la forme {{.iterator_token}}).
    2. Extraction des données (le pont) : configurez les éléments suivants :
      • Chemin JSON de l'identifiant de l'élément : champ spécifique de la réponse parente qui identifie de manière unique une entité individuelle (par exemple, id ou zone_id). Le connecteur extrait cet identifiant de chaque élément du tableau parent.
      • Nom de la variable du modèle : spécifiez un nom de variable personnalisé pour contenir l'ID extrait (par exemple, zone_id). L'UI affiche un badge dynamique : Utilisez {{.zone_id}} dans votre requête enfant ci-dessous.
    3. Requête enfant (détails) : configurez le point de terminaison qui renvoie des journaux détaillés pour chaque élément :
      1. Sous Point de terminaison de l'API, configurez les paramètres suivants pour définir l'itinéraire technique et le rythme de diffusion de la demande :
        • Chemin du point de terminaison : route d'API spécifique ajoutée à l'URL de base (par exemple, /client/v4/zones/{{.zone_id}}/logs/received). Elle définit la ressource de télémétrie exacte à interroger.
        • Méthode HTTP : sélectionnez GET pour récupérer des données à l'aide de paramètres de requête d'URL ou POST pour envoyer une charge utile de recherche ou un corps de filtre.
        • Corps de la requête : pour les requêtes POST, fournissez la charge utile des données JSON. Vous pouvez intégrer des variables de point de contrôle dynamiques telles que {"limit": 100, "start_time": "{{.last_timestamp}}"}.
      2. Nombre maximal de requêtes par minute : saisissez le nombre maximal de requêtes à envoyer par minute. Il s'agit d'un limiteur de débit côté client permettant de respecter les limites de débit des API des fournisseurs (par défaut, 5 requêtes par minute, soit une requête toutes les 12 secondes). Ce paramètre empêche l'épuisement du quota lors de la pagination sur plusieurs pages.
      3. Facultatif : Sous En-têtes personnalisés, configurez le Nom de l'en-tête et la Valeur, puis cliquez sur Ajouter pour définir les en-têtes HTTP spécialisés requis par l'API cible (par exemple, Content-Type: application/json, Accept: application/json).
      4. Facultatif : Sous Paramètres de requête, configurez la clé et la valeur, puis cliquez sur Ajouter pour spécifier des filtres ou des options supplémentaires ajoutés à la chaîne de requête de l'URL (par exemple, count=1000, status=active) ou pour lier des variables de modèle dynamiques (par exemple, start={{.last_run_time}}).
      5. Sous Stratégie de pagination, sélectionnez le mécanisme de pagination requis par l'API tierce pour gérer les ensembles de résultats multipages, puis configurez les champs requis :
        • Aucun : récupère les données en une seule requête sans pagination.
        • Pagination par jeton : utilisez des jetons (clés personnalisées) pour obtenir la page suivante. Saisissez le chemin JSON du jeton de page suivante (par exemple, meta.next_cursor) et le nom du paramètre de requête de pagination du jeton (par exemple, cursor).
        • Pagination des liens : suivez les URL fournies dans la réponse pour obtenir plus de données. Saisissez le chemin JSON du lien vers la page suivante (par exemple, links.next ou @odata.nextLink).
        • Pagination par décalage : ignorez un nombre défini d'enregistrements pour obtenir l'ensemble suivant. Saisissez le nom du paramètre de requête de décalage (par exemple, offset).
        • Pagination par numéro de page : accédez au numéro de page séquentiel suivant. Saisissez le nom du paramètre de requête du numéro de page (par exemple, page).
      6. Sous Point de contrôle, configurez les paramètres qui permettent au connecteur de se souvenir de l'endroit où il s'est arrêté entre les cycles d'interrogation récurrents :
        • Stratégie : choisissez l'une des stratégies suivantes et configurez les champs requis :
          • Aucun : récupérez toutes les données disponibles sans suivre la progression au cours des cycles.
          • Dernier code temporel : suivez le code temporel du dernier enregistrement. Saisissez le chemin JSON de la valeur du point de contrôle (par exemple, timestamp ou event_time) et la variable du point de contrôle (par exemple, last_run_time, référencée dans les sondages suivants sous la forme {{.last_run_time}}).

  13. Configurez les paramètres suivants dans Planification et libellés :

    • Fréquence d'interrogation : sélectionnez un intervalle standard (par exemple, 5m ou 1h).
    • Espace de noms : balise organisationnelle facultative.
    • Libellés d'ingestion : paires clé/valeur pour le contrôle des accès basé sur les rôles pour les données.

  14. Cliquez sur Envoyer. Google SecOps effectue une vérification automatisée des identifiants et des points de terminaison. Si la validation réussit, le flux commence à interroger.

Exemple de configuration 1 : événements d'audit 1Password (modèle d'API standard (séquentiel))

La configuration JSON déclarative suivante illustre un modèle d'API standard (séquentielle), avec un point de contrôle basé sur le curseur pour 1Password :

{
  "base_url": "https://events.1password.com",
  "polling_frequency": 15,
  "header_auth": {
    "header_key_values": [
      {
        "key": "Authorization",
        "value": "Bearer <SECRET_STORED_IN_SECRET_MANAGER>"
      }
    ]
  },
  "primary_request": {
    "request_settings": {
      "endpoint_path": "/api/v1/auditevents",
      "http_method": "POST",
      
      "request_body": "{\"limit\": 1000, \"start_time\": \"{{.last_run_time}}\"}",
      
      "custom_headers": [
        {
          "key": "Content-Type",
          "value": "application/json"
        }
      ],
      "max_requests_per_minute": 5
    },
    "pagination_strategy": {
      "token": {
        "next_page_token_json_path": "additional_items_url",
        "query_param": "cursor"
      }
    },
    "checkpointing": {
      "latest_timestamp_strategy": {
        "checkpoint_value_path": "timestamp",
        "checkpoint_variable": "last_run_time"
      }
    },
    "response_mapping": {
      "target_data_path": ["items"]
    }
  }
}

Exemple concret de configuration 2 : Télémétrie de zone Cloudflare (modèle Liste et détails (parent-enfant))

La configuration JSON déclarative suivante illustre un modèle de distribution ramifiée Liste et détails (parent-enfant) pour Cloudflare :

{
 "base_url": "https://api.cloudflare.com",
 "polling_frequency": 30,
 "header_auth": {
   "header_key_values": [
     {
       "key": "Authorization",
       "value": "Bearer <SECRET_STORED_IN_SECRET_MANAGER>"
     }
   ]
 },

 "primary_request": {
   "request_settings": {
     "endpoint_path": "/client/v4/zones",
     "http_method": "GET"
   },
   "response_mapping": {
     "target_data_path": ["result"]
   },
   "pagination_strategy": {
     "none": {}
   },
   "checkpointing": {
     "none_strategy": {}
   },
   "dependent_requests_config": {
     "item_id_json_path": "id",
     "item_id_variable": "zone_id",
     "dependent_requests": [
       {
         "request_settings": {
           "endpoint_path": "/client/v4/zones/{{.zone_id}}/logs/received",
           "http_method": "GET",
           "query_parameters": [
             {
               "key": "start",
               "value": "{{.last_run_time}}"
             },
             {
               "key": "count",
               "value": "1000"
             }
           ],
           "max_requests_per_minute": 5
         },

         "pagination_strategy": {
           "none": {}
         },
         "checkpointing": {
           "latest_timestamp_strategy": {
             "checkpoint_value_path": "EdgeStartTimestamp",
             "checkpoint_variable": "last_run_time"
           }
         },
         "response_mapping": {
           "target_data_path": []
         }
       }
     ]
   }
 }
}

Bonnes pratiques concernant les API personnalisées

  • Conseils sur la fréquence d'interrogation :
    • Commencez par des intervalles d'interrogation modérés : définissez l'intervalle d'interrogation initial sur 15 ou 30 minutes pour les points de terminaison à volume élevé afin d'observer le comportement du quota d'API du fournisseur avant de le réduire à 5 minutes.
    • Optimiser pour une distribution ramifiée à grand volume : pour les flux parent-enfant (liste et détails) qui découvrent des dizaines ou des centaines de ressources, Google vous recommande vivement de définir la fréquence d'interrogation sur 30 à 60 minutes afin de permettre à toutes les tâches enfants rythmées de se terminer correctement avant le début du prochain cycle de découverte.
  • Validez les chemins d'ingestion : utilisez la documentation du fournisseur ou des outils de test d'API pour confirmer le nom exact du champ JSON pour les codes temporels avant de configurer le checkpointing d'état.
  • Décomposer les API à plusieurs enfants : si une API tierce nécessite de récupérer les alertes et les journaux d'audit pour une seule liste d'utilisateurs, créez deux flux à un seul enfant distincts (un pour les alertes et un pour les journaux d'audit) afin de maintenir une isolation optimale.

Garde-fous pour la limitation du débit et des requêtes

Pour éviter que les configurations de flux client ne dépassent les quotas des fournisseurs tiers ou ne monopolisent les ressources système, le type de flux "API personnalisée" implémente les mesures de protection automatisées suivantes :

  • Rythme de requête configurable (limitation du débit) : le rythme des requêtes HTTP sortantes est automatiquement ajusté pour éviter de dépasser les limites de débit des fournisseurs. Le rythme par défaut est de cinq requêtes par minute (une requête toutes les 12 secondes). Vous pouvez ajuster ce paramètre pour chaque point de terminaison à l'aide du champ Nombre maximal de requêtes par minute dans les paramètres du point de terminaison afin de l'adapter aux quotas d'API publiés par votre fournisseur.
  • Plafond de requêtes enfant : pour les flux Parent-enfant (liste et détails), une requête de découverte peut envoyer jusqu'à 500 requêtes enfant par cycle d'interrogation.
  • Profondeur de distribution ramifiée à un seul niveau : le connecteur applique strictement une profondeur de distribution ramifiée maximale d'un niveau (découverte du parent → détails de l'enfant). Les requêtes dépendantes imbriquées (appels enfants) ne sont pas acceptées.
  • Taille maximale de la charge utile de réponse : la taille maximale autorisée pour une réponse HTTP à une requête ou une page est de 50 Mo. Si une API non paginée renvoie une réponse de plus de 50 Mo, la récupération échoue et une erreur de ressources épuisées s'affiche. Pour éviter cela, configurez toujours les paramètres de requête de pagination (tels que limit ou page_size) afin de récupérer les enregistrements par lots plus petits.
  • Reprise automatique HTTP 429 : si une API de fournisseur tiers répond avec HTTP 429 (nombre de requêtes trop élevé), Google SecOps capture automatiquement l'état et lance une période de reprise exponentielle, en mettant en pause l'exécution de la tâche jusqu'à ce que la fenêtre de quota du fournisseur soit rechargée.

Limites des API personnalisées

Lorsque vous planifiez vos chemins d'ingestion, notez que le type de flux "API personnalisée" présente les limites suivantes :

  • Prise en charge stricte de JSON : seules les réponses de l'API JSON sont acceptées. Les autres formats tels que XML, CSV, Parquet et Avro ne sont pas acceptés.
  • Pas de signature dynamique des requêtes : les API nécessitant des signatures cryptographiques dynamiques par requête ne sont pas prises en charge (par exemple, AWS SigV4, Akamai ou Oracle OCI).
  • Pas d'authentification en plusieurs étapes : les API qui nécessitent un appel de connexion programmatique initial pour échanger des identifiants contre un jeton de session temporaire (comme Saviynt) avant l'interrogation ne sont pas prises en charge.
  • Pas de WebSockets ni d'ingestion Push : les flux d'API personnalisés sont compatibles avec l'interrogation par extraction HTTPS standard. Les connexions de streaming persistantes (WebSockets) et les webhooks entrants ne sont pas acceptés.
  • Pas de TLS mutuel (mTLS) : l'authentification doit reposer sur des clés API, l'authentification de base ou des identifiants client OAuth 2.0 standards. Les négociations de certificats côté client ne sont pas acceptées.

Résoudre les problèmes liés aux flux d'API personnalisés

Pour examiner les erreurs liées aux flux d'API personnalisés dans l'explorateur de journaux Cloud Logging, utilisez les requêtes suivantes :

resource.type="gce_instance" OR resource.type="generic_task"
jsonPayload.service="gopher"
jsonPayload.feed_id="FEED_ID"

Remplacez FEED_ID par l'ID de votre flux.

Pour filtrer spécifiquement les requêtes HTTP ayant échoué, utilisez la requête suivante :

jsonPayload.service="gopher"
jsonPayload.feed_id="FEED_ID"
jsonPayload.http_status_code >= 400

Remplacez FEED_ID par l'ID de votre flux.

Modes d'échec courants et solutions

Symptôme / Erreur Origine du problème Solution / Remède
HTTP 401 (Non autorisé) / HTTP 403 (Interdit) Clé API, mot de passe ou identifiants OAuth expirés ou non valides. Modifiez le flux, saisissez de nouveau des identifiants valides, puis cliquez sur Envoyer.
HTTP 404 Introuvable Le modèle d'URL de base ou de chemin de point de terminaison est incorrect. Consultez le point de terminaison dans la documentation de l'API du fournisseur. Assurez-vous que l'URL de base se termine correctement et que le chemin du point de terminaison commence par "/".
HTTP 429 Trop de requêtes Vous avez dépassé les limites de débit de l'API du fournisseur. Augmentez la fréquence d'interrogation ou réduisez le paramètre limit dans les paramètres de requête.
Erreur d'extraction JSON (chemin d'accès aux éléments vide) Chemin de configuration de la réponse incorrect. Vérifiez la structure de la charge utile de la réponse de l'API et mettez à jour le chemin JSON des données cibles.
Ingestion de données en double Horodatage de configuration d'état ou chemin d'extracteur d'ID non valides. Vérifiez le nom du champ d'enregistrement du journal pour l'horodatage et mettez à jour le chemin de l'extracteur.

Gérer les flux

Une fois vos flux de données configurés, utilisez les outils de gestion pour surveiller l'état de l'ingestion, modifier les paramètres existants et gérer le cycle de vie des flux. Cette section explique comment interpréter les états des flux et effectuer les tâches de maintenance essentielles pour assurer la visibilité continue des données.

La page Flux fournit plusieurs outils pour vous aider à parcourir et à organiser votre liste de flux configurés :

  • Recherche : utilisez la barre de recherche pour trouver un flux par son nom, son ID ou son type de source.

  • Filtrer : cliquez sur l'icône de filtre pour affiner la liste en fonction d'attributs de flux spécifiques.

  • Télécharger au format CSV : cliquez sur Télécharger au format CSV pour exporter la liste actuelle des flux dans un fichier CSV.

  • Pagination : utilisez les commandes de pagination pour :

    • Modifiez le nombre de lignes par page.

    • Parcourez plusieurs pages de flux à l'aide des onglets et des flèches.

  • Heure de la dernière actualisation : consultez le code temporel pour savoir quand la liste des flux a été actualisée pour la dernière fois.

Afficher les flux configurés

La page Flux affiche tous les flux que vous avez configurés.

  1. Accédez à Paramètres SIEM> Flux. La page principale affiche tous les flux que vous avez configurés.
  2. Pointez sur chaque ligne pour afficher le menu more_vert Plus.
  3. Dans le menu, vous pouvez afficher les détails du flux, le modifier, le désactiver ou le supprimer.

Surveiller l'état du flux

Vous pouvez surveiller l'état du flux sur la page Flux initiale. Les flux peuvent avoir les états suivants :

  • Actif : le flux est configuré et prêt à ingérer des données dans votre compte Google SecOps.
  • InProgress : Google SecOps tente d'extraire les données du tiers configuré.
  • Terminé : les données ont bien été récupérées par ce flux.
  • Archivée : flux désactivé.

  • Échec : le flux ne parvient pas à récupérer les données. Cela est probablement dû à un problème de configuration. Cliquez sur la question pour afficher l'erreur de configuration. Une fois l'erreur corrigée et le flux renvoyé, revenez à la page Flux pour déterminer si le flux fonctionne désormais.

Modifier des flux existants

Sur la page Flux, vous pouvez modifier un flux existant comme suit :

  1. Pointez sur un flux existant, puis cliquez sur more_vert dans la colonne de droite.

  2. Cliquez sur Modifier le flux. Vous pouvez désormais modifier les paramètres d'entrée du flux et le renvoyer à Google SecOps, qui tentera d'utiliser le flux mis à jour.

Activer (reprendre) et désactiver (mettre en veille) les flux

Lorsque vous désactivez un flux, Google SecOps cesse d'ingérer de nouvelles données à partir de cette source. Pour arrêter immédiatement l'ingestion de données, vous devez supprimer le flux. Les transferts actifs ou limités existants se poursuivent jusqu'à leur terme. Lorsque vous réactivez le flux, Google SecOps peut récupérer les données qui ont été manquées pendant que le flux était désactivé. Cette fonctionnalité est appelée "remplissabilité".

Dans la colonne État, les flux activés sont indiqués comme Actifs, En cours, Terminés ou Échec. Les champs désactivés sont libellés Archivé. Pour obtenir une description, consultez Surveiller l'état du flux.

Sur la page Flux, vous pouvez activer (reprendre) ou désactiver (mettre en veille) l'un des flux existants :

  1. Pointez sur un flux existant, puis cliquez sur more_vert dans la colonne de droite.

  2. Facultatif : Cliquez sur le bouton Flux activé pour activer le flux.

  3. Facultatif : Cliquez sur le bouton Désactiver le flux pour désactiver le flux. Le flux est désormais marqué comme Archivé.

Récupération des données lorsque vous réactivez les flux (rétrocompatibilité)

La possibilité pour Google SecOps de compléter les données dépend de la nature de votre flux : basé sur l'extraction (compatible) ou basé sur l'envoi (non compatible).

Flux basés sur l'extraction

Grâce à ces flux, Google SecOps extrait des données de sources externes. Les flux d'extraction incluent :

  • Buckets de stockage cloud, tels qu'Amazon S3, Google Cloud Storage, Azure Blob Storage
  • Serveurs SFTP

  • API tierces, telles que Microsoft 365, Okta et Proofpoint

    Lorsque vous réactivez les flux basés sur l'extraction, Google SecOps peut récupérer les données générées lorsque le flux était désactivé.

Flux basés sur le push

Grâce à ces flux, les systèmes externes "envoient" des données à Google SecOps. Les flux push incluent :

  • Webhooks HTTPS
  • Google Cloud  Pub/Sub
  • Amazon Kinesis Data Firehose
  • Ingestions directes d'API/d'agents, comme Bindplane

Google SecOps ne peut pas lancer automatiquement le remplissage des données à partir de flux basés sur le push. Lorsque le flux est désactivé et que votre système envoie des données, Google SecOps renvoie une erreur HTTP 403 Forbidden ou une erreur 4xx générique.

Si votre système ne stocke pas les données et ne tente pas de les renvoyer à Google SecOps, elles seront perdues. De plus, si votre système est configuré pour "supprimer en cas d'échec" ou vider son tampon, les données sont définitivement perdues pour la période concernée. Pour éviter toute perte de données, vous devez configurer votre système pour qu'il mette en mémoire tampon et renvoie les données une fois qu'un flux est réactivé. Google SecOps peut ensuite ingérer les données manquantes lorsque le flux est repris.

Remarques concernant le remplissage

  • Limites du système source : la quantité de données historiques que Google SecOps peut réinjecter à partir de flux basés sur l'extraction est limitée par la durée de conservation des données par le système source et par ce que son API autorise. Par exemple, certaines API ne donnent accès qu'aux données des sept derniers jours.
  • Tampon Google SecOps : pour la récupération automatisée, le tampon interne de Google SecOps pour les flux basés sur l'extraction conserve les données pendant 90 jours maximum, après quoi elles sont supprimées.
  • Restrictions liées au locataire : les locataires non payants, tels que les preuves de concept, peuvent être soumis à des restrictions concernant le remplissage des données plus anciennes.
  • Quotas d'ingestion : pour éviter d'impacter l'ingestion de données en temps réel, les données de remplissage sont traitées avec une priorité inférieure à celle des données en direct. Le remplissage des données basé sur l'extraction est également limité en termes de fréquence, généralement à un tiers (33%) de la limite de rafale de votre locataire par type de journal. Cela permet de s'assurer que les flux critiques basés sur le push, tels que les agents EDR, ne sont pas affectés de manière négative.
  • Limitation limitation du débit : si le remplissage consomme tout le quota d'extraction disponible, l'ingestion est suspendue pour le reste de l'intervalle de cinq minutes et reprend automatiquement lorsque l'intervalle redémarre.
  • Stockage cloud : vous pouvez utiliser les paramètres du flux pour contrôler le remplissage, par exemple les filtres pour les fichiers nouveaux ou modifiés, ou les filtres de plage de dates, comme "Âge maximal du fichier".
  • Files d'attente volumineuses : si une file d'attente volumineuse d'un flux basé sur l'extraction pose problème lors de la réactivation, vous pouvez contacter l'assistance Google pour la vider. Cela signifie que le flux ne commencera à ingérer que les nouvelles données à venir, et que les données manquantes ne seront pas réinjectées.
  • Modification des flux désactivés : toute modification de configuration apportée à un flux lorsqu'il est désactivé sera appliquée dès qu'il sera réactivé.

Supprimer des flux

Sur la page Flux, vous pouvez également supprimer un flux existant :

  1. Pointez sur un flux existant, puis cliquez sur more_vert dans la colonne de droite.

  2. Cliquez sur Supprimer le flux. La fenêtre SUPPRIMER LE FLUX s'ouvre. Pour supprimer définitivement le flux, cliquez sur Oui, le supprimer.

Pour les flux d'API personnalisés, une boîte de dialogue s'affiche avec une case à cocher facultative : Supprimer les données en attente.

  • Non cochée (par défaut) : la configuration et les identifiants du flux sont supprimés, mais les données en attente en file d'attente peuvent être traitées jusqu'à l'ingestion.
  • Coché : la configuration du flux, les identifiants et toutes les données en attente sont supprimés définitivement.

Contrôler le taux d'ingestion

Lorsque le taux d'ingestion de données d'un locataire atteint un certain seuil, Google Security Operations limite le taux d'ingestion des nouveaux flux de données pour éviter qu'une source à taux d'ingestion élevé n'affecte le taux d'ingestion d'une autre source de données. Dans ce cas, il y a un délai, mais aucune donnée n'est perdue. Le seuil est déterminé par le volume d'ingestion et l'historique d'utilisation du locataire.

Vous pouvez demander une augmentation de la limite de débit en contactant Cloud Customer Care.

Résoudre les problèmes liés aux flux ayant échoué

Sur la page Flux, vous pouvez afficher des informations telles que le type de source, le type de journal, l'ID du flux et l'état des flux existants :

  1. Pointez sur un flux existant, puis cliquez sur more_vert dans la colonne de droite.

  2. Cliquez sur Afficher le flux. Une boîte de dialogue contenant les détails du flux s'affiche. En cas d'échec d'un flux, vous trouverez des informations sur les erreurs sous Détails > État.

Pour un flux ayant échoué, les détails incluent la cause de l'erreur et les étapes à suivre pour la corriger.

Consultez le tableau Erreurs de source et d'ingestion pour connaître les messages d'erreur que vous pouvez rencontrer lorsque vous utilisez des flux de données.

Pour une analyse détaillée et le dépannage de l'activité des flux, vous pouvez afficher les journaux dans Cloud Logging. Consultez Analyser l'activité des flux avec Cloud Logging.

Vous avez encore besoin d'aide ? Obtenez des réponses auprès des membres de la communauté et des professionnels Google SecOps.