Extensions d'analyseur

Compatible avec:

Ce document explique comment créer des extensions d'analyseur pour extraire des champs à partir de données de journal brutes et les mapper sur des champs de destination UDM (Unified Data Model) dans la plate-forme Google Security Operations.

Le document décrit le processus de création d'une extension d'analyseur:

Créer des extensions d'analyseur

Les extensions de l'analyseur offrent un moyen flexible d'étendre les fonctionnalités des analyseurs par défaut (et personnalisés) existants. Ils ne remplacent pas les analyseurs par défaut (et personnalisés), mais permettent de personnaliser facilement le pipeline d'analyseur, ce qui permet d'utiliser une nouvelle logique d'analyse, ainsi que d'extraire, de manipuler et de mapper des champs.

Une extension d'analyseur n'est pas la même chose qu'un analyseur personnalisé. Vous pouvez créer un analyseur personnalisé pour un type de journal qui ne dispose pas d'un analyseur par défaut ou désactiver les mises à jour de l'analyseur.

Processus d'extraction et de normalisation du parseur

Google SecOps reçoit les données de journal d'origine sous forme de journaux bruts. Les analyseurs par défaut (et personnalisés) extraient et normalisent les principaux champs de journal dans des champs UDM structurés dans les enregistrements UDM. Il ne représente qu'un sous-ensemble des données de journal brutes d'origine. Vous pouvez définir des extensions d'analyseur pour extraire les valeurs de journal non gérées par les analyseurs par défaut. Une fois activées, les extensions d'analyseur font partie du processus d'extraction et de normalisation des données Google SecOps.

Workflow d'ingestion et de normalisation

Définir de nouvelles extensions d'analyseur

Les analyseurs par défaut contiennent des ensembles prédéfinis d'instructions de mappage qui spécifient comment extraire, transformer et normaliser les valeurs de sécurité de base. Vous pouvez créer des extensions d'analyseur en définissant des instructions de mappage à l'aide de l'approche sans code (Mappage des champs de données) ou de l'approche par extrait de code:

  • Approche sans code

    L'approche sans code est idéale pour les extractions simples à partir de journaux bruts au format JSON, XML ou CSV natif. Il vous permet de spécifier des champs de source de journaux bruts et de mapper les champs de destination UDM correspondants.

    Par exemple, pour extraire des données de journal JSON avec jusqu'à 10 champs, en utilisant des comparaisons d'égalité simples.

  • Approche Extrait de code

    L'approche par extrait de code vous permet de définir des instructions pour extraire et transformer les valeurs du journal brut, puis de les attribuer aux champs UDM. Les extraits de code utilisent la même syntaxe Logstash que l'analyseur par défaut (ou personnalisé).

    Cette approche s'applique à tous les formats de journaux compatibles. Il est particulièrement adapté aux scénarios suivants:

    • Extractions de données complexes ou logique complexe
    • Données non structurées nécessitant des analyseurs basés sur Grok
    • Les formats autres que JSON, tels que CSV et XML.

    Les extraits de code utilisent des fonctions pour extraire des données spécifiques des données de journal brutes. Par exemple, Grok, JSON, KV et XML.

    Dans la plupart des cas, il est préférable d'utiliser l'approche de mappage des données utilisée dans l'analyseur par défaut (ou personnalisé).

Fusionner les valeurs nouvellement extraites dans les champs UDM

Une fois activées, les extensions d'analyseur fusionnent les valeurs nouvellement extraites dans des champs UDM désignés de l'enregistrement UDM correspondant, conformément à des principes de fusion prédéfinis. Exemple :

  • Écraser les valeurs existantes: les valeurs extraites écrasent les valeurs existantes dans les champs UDM de destination.

    La seule exception concerne les champs répétés, pour lesquels vous pouvez configurer l'extension de l'analyseur pour ajouter de nouvelles valeurs lorsque vous écrivez des données dans un champ répété dans l'enregistrement UDM.

  • L'extension de l'analyseur prévaut: les instructions de mappage des données dans une extension d'analyseur prévalent sur celles de l'analyseur par défaut (ou personnalisé) pour ce type de journal. En cas de conflit dans les instructions de mappage, l'extension de l'analyseur écrase la valeur définie par défaut.

    Par exemple, si l'analyseur par défaut mappe un champ de journal brut sur le champ UDM event.metadata.description et que l'extension de l'analyseur mappe un champ de journal brut différent sur ce même champ UDM, l'extension de l'analyseur écrase la valeur définie par l'analyseur par défaut.

Limites

  • Une seule extension d'analyseur par type de journal: vous ne pouvez créer qu'une seule extension d'analyseur par type de journal.
  • Une seule approche d'instruction de mappage de données: vous pouvez créer une extension d'analyseur à l'aide de l'approche sans code ou de l'approche par extrait de code, mais pas les deux approches combinées.
  • Échantillons de journaux pour la validation: des échantillons de journaux des 30 derniers jours sont nécessaires pour valider une extension d'analyseur UDM. Pour en savoir plus, consultez S'assurer qu'un analyseur est actif pour le type de journal.
  • Erreurs de l'analyseur de base: les erreurs de l'analyseur de base ne sont pas identifiables ni corrigibles dans les extensions de l'analyseur.
  • Champs répétés dans les extraits de code: soyez prudent lorsque vous remplacez des objets entiers répétés dans des extraits de code pour éviter toute perte de données accidentelle. Pour en savoir plus, consultez En savoir plus sur le sélecteur de champs répétés.
  • Événements sans ambiguïté: les extensions d'analyseur ne peuvent pas gérer les journaux contenant plusieurs événements uniques dans un seul enregistrement, par exemple, un tableau Google Drive.
  • XML et sans code: l'approche sans code n'est pas recommandée pour le XML en raison de problèmes d'encodage potentiels. Utilisez l'approche par extrait de code pour le code XML.
  • Aucune donnée rétroactive: vous ne pouvez pas analyser les données de journal brutes rétroactivement.

Concepts de l'analyseur

Les documents suivants expliquent des concepts importants concernant l'analyseur:

Prérequis

Conditions préalables à la création d'une extension d'analyseur:

  • Un analyseur par défaut (ou personnalisé) doit être actif pour le type de journal.
  • Google SecOps doit pouvoir ingérer et normaliser les journaux bruts à l'aide d'un analyseur par défaut (ou personnalisé).
  • Assurez-vous que l'analyseur par défaut (ou personnalisé) actif pour votre type de journal cible a ingéré les données de journal brutes au cours des 30 derniers jours. Ces données doivent contenir un échantillon des champs que vous prévoyez d'extraire ou d'utiliser pour filtrer les enregistrements de journal. Il sera utilisé pour valider vos nouvelles instructions de mappage des données.

Premiers pas

Avant de créer une extension d'analyseur, procédez comme suit:

  1. Vérifiez les conditions préalables :

    Assurez-vous qu'un analyseur est actif pour le type de journal. Si aucun analyseur n'est encore disponible, créez-en un.

  2. Identifiez les champs à extraire des journaux bruts:

    Identifiez les champs que vous souhaitez extraire des journaux bruts.

  3. Sélectionnez les champs UDM appropriés:

    Sélectionnez les champs UDM correspondants appropriés pour mapper les champs de journal brut extraits.

  4. Choisissez une approche de définition de l'extension de l'analyseur:

    Choisissez l'une des deux approches d'extension (approches de mappage des données) pour créer l'extension de l'analyseur.

Vérifier les conditions préalables

Assurez-vous qu'un analyseur est actif pour le type de journal que vous souhaitez étendre, comme décrit dans les sections suivantes:

Assurez-vous qu'un analyseur est actif pour le type de journal.

Assurez-vous qu'un analyseur par défaut (ou personnalisé) est actif pour le type de journal que vous souhaitez étendre.

Recherchez votre type de journal dans ces listes:

Assurez-vous qu'un analyseur personnalisé existe pour le type de journal

Pour vous assurer qu'un analyseur personnalisé existe pour un type de journal:

  1. Dans la barre de navigation, sélectionnez Paramètres du SIEM > Analyseurs.

  2. Dans le tableau Analyseurs, recherchez le type de journal que vous souhaitez étendre.

Vérifier que l'analyseur est actif pour le type de journal

Pour vérifier si un analyseur est actif pour un type de journal, procédez comme suit:

  1. Dans la barre de navigation, sélectionnez Paramètres du SIEM > Analyseurs.

  2. Dans le tableau Analyseurs, recherchez le type de journal que vous souhaitez étendre.

    Si l'analyseur du type de journal n'est pas actif, activez-le:

Identifier les champs à extraire des journaux bruts

Analysez le journal brut à partir duquel vous souhaitez extraire des données pour identifier les champs non extraits par l'analyseur par défaut (ou personnalisé). Notez comment l'analyseur par défaut (ou personnalisé) extrait les champs de journal bruts et les met en correspondance avec leurs champs UDM correspondants.

Pour identifier les champs spécifiques que vous souhaitez extraire des journaux bruts, vous pouvez utiliser les outils de recherche:

Pour en savoir plus sur la recherche dans les journaux bruts, consultez les ressources suivantes:

Sélectionner les champs UDM appropriés

Maintenant que vous avez identifié les champs cibles spécifiques à extraire, vous pouvez les faire correspondre aux champs UDM de destination correspondants. Établissez une mise en correspondance claire entre les champs de la source de journal brut et leurs champs de destination UDM. Vous pouvez mapper des données sur n'importe quel champ UDM compatible avec les types de données standards ou les champs répétés.

Choisir le bon champ UDM

Les ressources suivantes peuvent vous aider à simplifier le processus:

Familiarisez-vous avec les principaux concepts de UDM

Comprendre le mappage des données utilisé par l'analyseur existant

Nous vous recommandons de comprendre le mappage de données existant utilisé par l'analyseur par défaut (ou personnalisé), entre les champs de source de journal bruts et leurs champs de destination UDM.

Pour afficher le mappage des données entre les champs de source de journal bruts et les champs de destination UDM utilisés dans l'analyseur par défaut (ou personnalisé) existant:

  1. Dans la barre de navigation, sélectionnez Paramètres du SIEM > Analyseurs.
  2. Dans le tableau Analyseurs, recherchez le type de journal que vous souhaitez étendre.

  3. Accédez à cette ligne, puis cliquez sur  Menu > Affichage.

    L'onglet Code de l'analyseur affiche le mappage des données entre les champs de source de journal bruts et les champs de destination de l'UDM utilisés dans l'analyseur par défaut (ou personnalisé) existant.

Utiliser l'outil de recherche UDM

Utilisez l'outil de recherche UDM pour identifier les champs UDM correspondant aux champs de la source de journal brut.

Google SecOps fournit l'outil de recherche UDM pour vous aider à trouver rapidement les champs UDM de destination. Pour accéder à l'outil de recherche UDM, accédez à Investigation > Recherche dans le SIEM.

Pour savoir comment utiliser l'outil de recherche UDM, consultez les articles suivants:

Exemple d'utilisation de l'outil de recherche UDM

Par exemple, si vous disposez d'un champ source dans le journal brut nommé "packets", utilisez l'outil de recherche UDM pour trouver les champs UDM de destination potentiels contenant le nom "packets" :

  1. Accédez à Investigation > Recherche dans le SIEM.

  2. Sur la page Recherche dans le SIEM, saisissez "packets" (paquets) dans le champ Look up UDM fields by value (Rechercher des champs UDM par valeur), puis cliquez sur UDM Lookup (Recherche UDM).

    La boîte de dialogue UDM Lookup (Recherche UDM) s'ouvre. L'outil de recherche fait correspondre les champs UDM par nom de champ ou par valeur de champ:

    • Rechercher par nom de champ : fait correspondre la chaîne de texte que vous saisissez aux noms de champ contenant ce texte.
    • Rechercher par valeur de champ : fait correspondre la valeur que vous saisissez aux champs qui la contiennent dans leurs données de journal stockées.

  3. Dans la boîte de dialogue Recherche UDM, sélectionnez Champs UDM.

    La fonction de recherche affiche une liste de champs UDM potentiels contenant le texte "paquets" dans leurs noms de champs UDM.

  4. Cliquez sur chaque ligne une par une pour afficher la description de chaque champ UDM.

Remarques importantes concernant la gestion des identités utilisateur pour éviter les erreurs

  • Champs similaires: la structure hiérarchique de l'UDM peut entraîner des champs aux noms similaires. Pour en savoir plus, consultez les analyseurs par défaut. Pour en savoir plus, consultez la section Comprendre le mappage de données utilisé par l'analyseur existant.
  • Mappage de champ arbitraire: utilisez l'objet additional pour les données qui ne sont pas mappées directement sur un champ UDM. Pour en savoir plus, consultez Mappage de champs arbitraires dans UDM.
  • Champs répétés: soyez prudent lorsque vous travaillez avec des champs répétés dans des extraits de code. Le remplacement d'un objet entier peut écraser les données d'origine. L'approche sans code offre un meilleur contrôle des champs répétés. Pour en savoir plus, consultez En savoir plus sur le sélecteur de champs répétés.
  • Champs UDM obligatoires pour les types d'événements UDM: lorsque vous attribuez un champ metadata.event_type UDM à un enregistrement UDM, chaque event_type nécessite un ensemble différent de champs associés dans l'enregistrement UDM. Pour en savoir plus, consultez En savoir plus sur l'attribution de champs metadata.event_type UDM.
  • Problèmes liés au moteur d'analyse de base: les extensions du moteur d'analyse ne peuvent pas corriger les erreurs du moteur d'analyse de base. L'analyseur de base est l'analyseur par défaut (ou personnalisé) qui a créé l'enregistrement UDM. Envisagez des options telles que l'amélioration de l'extension de l'analyseur, la modification de l'analyseur de base ou le préfiltrage des journaux.
Mappage de champ arbitraire dans UDM

Lorsque vous ne trouvez pas de champ UDM standard adapté pour stocker vos données, utilisez l'objet additional pour stocker les données sous la forme d'une paire clé-valeur personnalisée. Vous pouvez ainsi stocker des informations précieuses dans l'enregistrement UDM, même s'il ne comporte pas de champ UDM correspondant.

Choisir une approche de définition de l'extension de l'analyseur

Avant de choisir une approche de définition d'extension d'analyseur, vous devez avoir lu les sections suivantes:

Les étapes suivantes consistent à ouvrir la page Extensions du parseur et à sélectionner l'approche d'extension à utiliser pour définir l'extension du parseur:

Ouvrir la page "Extensions de l'analyseur"

La page Extensions de l'analyseur vous permet de définir la nouvelle extension de l'analyseur.

Vous pouvez ouvrir la page Extensions d'analyseur de l'une des manières suivantes, depuis le menu Paramètres, une recherche de journal brut ou une ancienne recherche de journal brut:

Ouvrir depuis le menu Paramètres

Pour ouvrir la page Extensions d'analyseur à partir du menu Paramètres:

  1. Dans la barre de navigation, sélectionnez Paramètres du SIEM > Analyseurs.

    Le tableau Analyseurs affiche la liste des analyseurs par défaut par type de journal.

  2. Recherchez le type de journal que vous souhaitez étendre, puis cliquez sur Menu > Créer une extension.

    La page Extensions du débogueur s'ouvre.

Pour ouvrir la page Extensions du débogueur à partir d'une recherche dans les journaux bruts:

  1. Accédez à Investigation > Recherche dans le SIEM.
  2. Dans le champ de recherche, ajoutez le préfixe raw = à votre argument de recherche et placez le terme de recherche entre guillemets. Exemple :raw = "example.com"
  3. Cliquez sur Exécuter la recherche. Les résultats s'affichent dans le panneau Journaux bruts.
  4. Cliquez sur un journal (ligne) dans le panneau Journaux bruts. Le panneau Vue d'événement s'affiche.
  5. Cliquez sur l'onglet Journal brut dans le panneau Vue des événements. Le journal brut s'affiche.

  6. Cliquez sur Gérer l'analyseur > Créer une extension > Suivant.

    La page Extensions du débogueur s'ouvre.

Pour ouvrir la page Extensions d'analyseur à partir d'une ancienne recherche de journaux bruts:

  1. Utilisez l'ancienne recherche de journaux bruts pour rechercher des enregistrements similaires à ceux qui seront analysés.
  2. Sélectionnez un événement dans le panneau Événements > Chronologie.
  3. Développez le panneau Données d'événement.

  4. Cliquez sur Gérer l'analyseur > Créer une extension > Suivant.

    La page Extensions d'analyseur s'ouvre.

Page des extensions d'analyseur

La page affiche les panneaux Journal brut et Définition de l'extension:

  • Panneau Journal brut:

    Cela affiche des exemples de données de journal brutes pour le type de journal sélectionné. Si vous avez ouvert la page à partir de la recherche de journaux bruts, les données d'exemple sont le résultat de votre recherche. Vous pouvez mettre en forme l'exemple à l'aide du menu Afficher sous forme (RAW, JSON, CSV, XML, etc.) et de la case à cocher Mettre en forme le texte.

    1. Vérifiez que l'échantillon de données de journal brutes affiché est représentatif des journaux que l'extension d'analyseur traitera.

    2. Cliquez sur Preview UDM Output (Aperçu de la sortie UDM) pour afficher la sortie UDM de l'échantillon de données de journal brutes.

  • Panneau Définition de l'extension:

    Vous pouvez ainsi définir une extension d'analyseur à l'aide de l'une des deux approches d'instruction de mappage: Mappez les champs de données (sans code) ou Écrivez un extrait de code. Vous ne pouvez pas utiliser les deux approches dans la même extension d'analyseur.

    Selon l'approche que vous choisissez, vous pouvez spécifier les champs de données de journal source à extraire des journaux bruts entrants et les mapper sur les champs UDM correspondants, ou vous pouvez écrire un extrait de code pour effectuer ces tâches et plus encore.

Sélectionner l'approche d'extension

Sur la page Extensions de l'analyseur, dans le panneau Définition de l'extension, dans le champ Méthode d'extension, sélectionnez l'une des approches suivantes pour créer l'extension de l'analyseur:

  • Approche sans code consistant à mapper des champs de données:

    Cette approche vous permet de spécifier les champs du journal brut et de les mapper sur les champs UDM de destination.

    Cette approche fonctionne avec les formats de journaux bruts suivants:

    • JSON natif, XML natif ou CSV
    • En-tête Syslog, plus JSON natif, XML natif ou CSV. Vous pouvez créer des instructions de mappage de type de champ de données pour les journaux bruts dans les formats suivants : JSON, XML, CSV, SYSLOG + JSON, SYSLOG + XML et SYSLOG + CSV.

    Consultez les étapes suivantes : Instructions de création sans code (champs de données cartographiques).

  • Approche Écrire un extrait de code:

    Cette approche vous permet d'utiliser une syntaxe semblable à Logstash pour spécifier des instructions d'extraction et de transformation des valeurs du journal brut, puis de les attribuer aux champs UDM de l'enregistrement UDM.

    • Les extraits de code utilisent la même syntaxe et les mêmes sections que les analyseurs par défaut (ou personnalisés). Pour en savoir plus, consultez la section Syntaxe de l'analyseur.

    • Cette approche fonctionne avec tous les formats de données compatibles pour ce type de journal.

    Consultez les étapes suivantes : Instructions pour créer un extrait de code.

Créer des instructions sans code (champs de données cartographiques)

L'approche sans code (également appelée méthode Map data fields (Map des champs de données)) vous permet de spécifier les chemins des champs de journal bruts et de les mapper sur les champs UDM de destination correspondants.

Avant de créer une extension d'analyseur à l'aide de l'approche sans code, vous devez avoir lu les sections suivantes:

Pour définir l'extension de l'analyseur, procédez comme suit:

  1. Définir le sélecteur de champs répétés
  2. Définir une instruction de mappage des données pour chaque champ
  3. Envoyer et activer l'extension d'analyseur

Définir le sélecteur de champs répétés

Dans le panneau Définition de l'extension, dans le champ Champs répétés, définissez la manière dont l'extension de l'analyseur doit enregistrer une valeur dans les champs répétés (champs compatibles avec un tableau de valeurs, par exemple principal.ip):

  • Ajouter des valeurs: la valeur nouvellement extraite est ajoutée à l'ensemble de valeurs existant stocké dans le champ de tableau UDM.
  • Remplacer les valeurs: la valeur nouvellement extraite remplace l'ensemble de valeurs existant dans le champ de tableau UDM, précédemment stocké par l'analyseur par défaut.

Les paramètres du sélecteur Champs répétés n'affectent pas les champs non répétés.

Pour en savoir plus, consultez En savoir plus sur le sélecteur de champs répétés.

Définir une instruction de mappage des données pour chaque champ

Définissez une instruction de mappage des données pour chaque champ que vous souhaitez extraire du journal brut. L'instruction doit spécifier le chemin d'accès du champ d'origine dans le journal brut et le mapper sur le champ UDM de destination.

  1. Si l'exemple de journal brut affiché dans le panneau Journal brut contient un en-tête Syslog, les champs Syslog et Cible s'affichent. (Certains formats de journaux ne contiennent pas d'en-tête Syslog, par exemple le format JSON natif, le format XML natif ou le format CSV.)

    Google SecOps a besoin des champs Syslog et Cible pour prétraiter l'en-tête Syslog afin d'extraire la partie structurée du journal.

    1. Définissez les champs suivants:

      • Syslog: modèle défini par l'utilisateur qui prétraite et sépare un en-tête Syslog de la partie structurée d'un journal brut.

        Spécifiez le modèle d'extraction, à l'aide de Grok et d'expressions régulières, qui identifie l'en-tête Syslog et le message de journal brut. Pour en savoir plus, consultez Définir les champs de l'extracteur Syslog.

      • Cible: nom de la variable dans le champ Syslog qui stocke la partie structurée du journal.

        Spécifiez le nom de la variable dans le modèle d'extraction qui stocke la partie structurée du journal.

      Voici un exemple de modèle d'extraction et de nom de variable pour les champs Syslog et Cible, respectivement.

      Champs de l'extracteur Syslog

    2. Après avoir saisi des valeurs dans les champs Syslog et Cible, cliquez sur le bouton Valider.

      Le processus de validation vérifie à la fois les erreurs de syntaxe et d'analyse, puis renvoie l'un des éléments suivants:

      • Réussite: les champs de mappage des données s'affichent. Définissez le reste de l'extension de l'analyseur.
      • Échec: un message d'erreur s'affiche. Corrigez la condition d'erreur avant de continuer.

  2. Vous pouvez éventuellement définir une instruction de précondition.

    Une instruction de précondition identifie un sous-ensemble des journaux bruts que l'extension d'analyseur traite en faisant correspondre une valeur statique à un champ du journal brut. Si un journal brut entrant répond aux critères de précondition, l'extension de l'analyseur applique l'instruction de mappage. Si les valeurs ne correspondent pas, l'extension de l'analyseur n'applique pas l'instruction de mappage.

    Remplissez les champs suivants :

    • Champ de précondition: identifiant du champ dans le journal brut contenant la valeur à comparer. Saisissez le chemin d'accès complet au champ si le format de données de journalisation est JSON ou XML, ou la position de la colonne si le format de données est CSV.
    • Opérateur de précondition: sélectionnez EQUALS ou NOT EQUALS.
    • Valeur de précondition: valeur statique qui sera comparée au champ de précondition dans le journal brut.

    Pour obtenir un autre exemple d'instruction de précondition, consultez Sans code : extraire des champs avec une valeur de précondition.

  3. Mappez le champ de données de journal brutes sur le champ UDM de destination:

    • Champ de données brutes: saisissez le chemin d'accès complet au champ si le format de données de journal est JSON (par exemple: jsonPayload.connection.dest_ip) ou XML (par exemple: /Event/Reason-Code), ou la position de la colonne si le format de données est CSV (remarque: les positions d'index commencent à 1).

    • Champ de destination: saisissez le nom complet du champ UDM dans lequel la valeur sera stockée, par exemple udm.metadata.collected_timestamp.seconds.

  4. Pour ajouter d'autres champs, cliquez sur Ajouter, puis saisissez toutes les instructions de mappage pour le champ suivant.

Pour un autre exemple de mappage des champs, consultez Sans code : extraire des champs.

Envoyer et activer l'extension de l'analyseur

Une fois que vous avez défini des instructions de mappage des données pour tous les champs que vous souhaitez extraire du journal brut, envoyez et activez l'extension d'analyseur.

Cliquez sur Envoyer pour enregistrer et valider l'instruction de mappage.

Google SecOps valide les instructions de mappage:

  • Si le processus de validation réussit, l'état passe à En service et les instructions de mappage commencent à traiter les données de journal entrantes.

  • Si le processus de validation échoue, l'état passe à Échec et une erreur s'affiche dans le champ "Journal brut".

    Voici un exemple d'erreur de validation:

      ERROR: generic::unknown: pipeline.ParseLogEntry failed: LOG_PARSING_CBN_ERROR:
  "generic::invalid_argument: pipeline failed: filter mutate (7) failed: copy failure:
  copy source field \"jsonPayload.dest_instance.region\" must not be empty
  (try using replace to provide the value before calling copy)

  "LOG: {"insertId":"14suym9fw9f63r","jsonPayload":{"bytes_sent":"492",
  "connection":{"dest_ip":"10.12.12.33","dest_port":32768,"protocol":6,
  "src_ip":"10.142.0.238","src_port":22},"end_time":"2023-02-13T22:38:30.490546349Z",
  "packets_sent":"15","reporter":"SRC","src_instance":{"project_id":"example-labs",
  "region":"us-east1","vm_name":"example-us-east1","zone":"us-east1-b"},
  "src_vpc":{"project_id":"example-labs","subnetwork_name":"default",
  "vpc_name":"default"},"start_time":"2023-02-13T22:38:29.024032655Z"},
  "logName":"projects/example-labs/logs/compute.googleapis.com%2Fvpc_flows",
  "receiveTimestamp":"2023-02-13T22:38:37.443315735Z","resource":{"labels":
  {"location":"us-east1-b","project_id":"example-labs",
    "subnetwork_id":"00000000000000000000","subnetwork_name":"default"},
    "type":"gce_subnetwork"},"timestamp":"2023-02-13T22:38:37.443315735Z"}

    États du cycle de vie d'une extension d'analyseur

    Les extensions d'analyseur ont les états de cycle de vie suivants:

  • DRAFT: extension d'analyseur nouvellement créée qui n'a pas encore été envoyée.

  • VALIDATING: Google SecOps valide les instructions de mappage par rapport aux journaux bruts existants pour s'assurer que les champs sont analysés sans erreur.

  • LIVE: l'extension de l'analyseur a réussi la validation et est désormais en production. Il extrait et transforme les données des journaux bruts entrants en enregistrements UDM.

  • FAILED: la validation de l'extension de l'analyseur a échoué.

En savoir plus sur le sélecteur de champs répétés

Certains champs UDM stockent un tableau de valeurs, comme le champ principal.ip. Le sélecteur Champs répétés vous permet de contrôler la façon dont votre extension d'analyseur stockera les données nouvellement extraites dans un champ répété:

  • Ajouter des valeurs:

    L'extension d'analyseur ajoute la valeur nouvellement extraite au tableau des valeurs existantes du champ UDM.

  • Remplacer des valeurs:

    L'extension de l'analyseur remplacera le tableau des valeurs existantes du champ UDM par la valeur nouvellement extraite.

Une extension d'analyseur ne peut mapper des données sur un champ répété que lorsque le champ répété se trouve au niveau le plus bas de la hiérarchie. Exemple :

  • Le mappage de valeurs sur udm.principal.ip est accepté, car le champ ip répété se trouve au niveau le plus bas de la hiérarchie et principal n'est pas un champ répété.
  • Il n'est pas possible de mapper des valeurs sur udm.intermediary.hostname, car intermediary est un champ répété et ne se trouve pas au niveau le plus bas de la hiérarchie.

Le tableau suivant fournit des exemples de l'impact de la configuration du sélecteur Champs répétés sur l'enregistrement UDM généré.

Sélection des champs répétés Exemple de journal Configuration de l'extension de l'analyseur Résultat généré
Ajouter des valeurs {"protoPayload":{"@type":"type.AuditLog","authenticationInfo":{"principalEmail":"admin@cmmar.co"},"requestMetadata":{"callerIp":"1.1.1.1, 2.2.2.2"}}} Champ de précondition: protoPayload.requestMetadata.callerIp
Valeur de précondition: " "
Opérateur de précondition: NOT_EQUALS
Champ de données brutes: protoPayload.requestMetadata.callerIp
Champ de destination: event.idm.read_only_udm.principal.ip 		metadata:{event_timestamp:{}.....}principal:{Ip:"1.1.1.1, 2.2.2.2"} } }
Ajouter des valeurs {"protoPayload":{"@type":"type.AuditLog","authenticationInfo":{"principalEmail":"admin@cmmar.co"},"requestMetadata":{"callerIp":"2.2.2.2, 3.3.3.3", "name":"Akamai Ltd"}}} Condition préalable 1 :
Champ de condition préalable:protoPayload.requestMetadata.callerIp
Valeur de la condition préalable: " "
Opérateur de condition préalable: NOT_EQUALS
Champ de données brutes: protoPayload.requestMetadata.callerIp
Champ de destination: event.idm.read_only_udm.principal.ip

Condition préalable 2 :
Champ de données brutes: protoPayload.requestMetadata.name
Champ de destination: event.idm.read_only_udm.metadata.product_name

 Événements générés par l'analyseur prédéfini avant l'application de l'extension.
metadata:{event_timestamp:{} ... principal:{ip:"1.1.1.1"}}}

Résultat après application de l'extension.
timestamp:{} idm:{read_only_udm:{metadata:{event_timestamp:{} .... product_name: "Akamai Ltd"}principal:{ip:"1.1.1.1, 2.2.2.2, 3.3.3.3"}}}

Remplacer des valeurs {"protoPayload":{"@type":"type..AuditLog","authenticationInfo":{"principalEmail":"admin@cmmar.co"},"requestMetadata":{"callerIp":"2.2.2.2"}}} Champ de précondition: protoPayload.authenticationInfo.principalEmail
Valeur de précondition: " "
Opérateur de précondition: NOT_EQUALS
Champ de données brutes: protoPayload.authenticationInfo.principalEmail
Champ de destination: event.idm.read_only_udm.principal.ip 		Événements UDM générés par l'analyseur prédéfini avant l'application de l'extension.
timestamp:{} idm:{read_only_udm:{metadata:{event_timestamp:{} ... principal:{ip:"1.1.1.1"}}}

Sortie UDM après application de l'extension timestamp:{} idm:{read_only_udm:{metadata:{event_timestamp:{} ....} principal:{ip:"2.2.2.2"}}}

En savoir plus sur les champs de l'extracteur Syslog

Les champs de l'extracteur Syslog vous permettent de séparer l'en-tête Syslog d'un journal structuré en définissant Grok, une expression régulière, ainsi qu'un jeton nommé dans le format d'expression régulière pour stocker la sortie.

Définir les champs de l'extracteur Syslog

Les valeurs des champs Syslog et Cible fonctionnent ensemble pour définir la façon dont l'extension de l'analyseur sépare l'en-tête Syslog de la partie structurée d'un journal brut. Dans le champ Syslog, vous définissez une expression à l'aide d'une combinaison de syntaxe Grok et d'expression régulière. L'expression inclut un nom de variable qui identifie la partie structurée du journal brut. Dans le champ Target (Cible), vous spécifiez ce nom de variable.

L'exemple suivant illustre la synergie entre ces champs.

Voici un exemple de journal brut:

<13>1 2022-09-14T15:03:04+00:00 fieldname fieldname - - - {"timestamp": "2021-03-14T14:54:40.842152+0000","flow_id": 1885148860701096, "src_ip": "10.11.22.1","src_port": 51972,"dest_ip": "1.2.3.4","dest_port": 55291,"proto": "TCP"}

Le journal brut contient les sections suivantes:

  • En-tête Syslog: <13> 2022-09-14T15:03:04+00:00 fieldname fieldname - - -

  • Événement au format JSON: {"timestamp": "2021-03-14T14:54:40.842152+0000","flow_id": 1885148860701096, "src_ip": "10.11.22.1","src_port": 51972,"dest_ip": "1.2.3.4","dest_port": 55291,"proto": "TCP"}

Pour séparer l'en-tête Syslog de la partie JSON du journal brut, utilisez l'exemple d'expression suivant dans le champ Syslog: %{TIMESTAMP_ISO8601} %{WORD} %{WORD} ([- ]+)?%{GREEDYDATA:msg}

  • Cette partie de l'expression identifie l'en-tête Syslog : %{TIMESTAMP\_ISO8601} %{WORD} %{WORD} ([- ]+)?
  • Cette partie de l'expression capture le segment JSON du journal brut : %{GREEDYDATA:msg}

Cet exemple inclut le nom de variable msg. Vous choisissez le nom de la variable. L'extension de l'analyseur extrait le segment JSON du journal brut et l'attribue à la variable msg.

Dans le champ Target (Cible), saisissez le nom de la variable msg. La valeur stockée dans la variable msg est transmise aux instructions de mappage des champs de données que vous créez dans l'extension de l'analyseur.

À l'aide de l'exemple de journal brut, le segment suivant est saisi dans l'instruction de mappage des données:

{"timestamp": "2021-03-14T14:54:40.842152+0000","flow_id": 1885148860701096, "src_ip": "10.11.22.1","src_port": 51972,"dest_ip": "1.2.3.4","dest_port": 55291,"proto": "TCP"}

Vous trouverez ci-dessous les champs Syslog et Cible remplis:

Champs de l&#39;extracteur Syslog

Le tableau suivant fournit d'autres exemples avec des exemples de journaux, le modèle d'extraction Syslog, le nom de la variable Target (Cible) et le résultat.

Exemple de journal brut Champ Syslog Champ cible Résultat
<13>1 2022-07-14T15:03:04+00:00 suricata suricata - - - {\"timestamp\": \"2021-03-14T14:54:40.842152+0000\",\"flow_id\": 1885148860701096,\"in_iface\": \"enp94s0\",\"event_type\": \"alert\",\"vlan\": 522,\"src_ip\": \"1.1.2.1\",\"src_port\": 51972,\"dest_ip\": \"1.2.3.4\",\"dest_port\": 55291,\"proto\": \"TCP\"}" %{TIMESTAMP_ISO8601} %{WORD} %{WORD} ([- ]+)?%{GREEDYDATA:msg} msg field_mappings { field: "msg" value: "{\"timestamp\": \"2021-03-14T14:54:40.842152+0000\",\"flow_id\": 1885148860701096,\"in_iface\": \"enp94s0\",\"event_type\": \"alert\",\"vlan\": 522,\"src_ip\": \"1.1.2.1\",\"src_port\": 51972,\"dest_ip\": \"1.2.3.4\",\"dest_port\": 55291,\"proto\": \"TCP\"}" }
<13>1 2022-07-14T15:03:04+00:00 suricata suricata - - - {\"timestamp\": \"2021-03-14T14:54:40.842152+0000\"} - - - {\"timestamp\": \"2021-03-14T14:54:40.842152+0000\",\"flow_id\": 1885148860701096,\"in_iface\": \"enp94s0\",\"event_type\": \"alert\",\"vlan\": 522,\"src_ip\": \"1.1.2.1\",\"src_port\": 51972,\"dest_ip\": \"1.2.3.4\",\"dest_port\": 55291,\"proto\": \"TCP\"} %{TIMESTAMP_ISO8601} %{WORD} %{WORD} ([- ]+)?%{GREEDYDATA:msg1} ([- ]+)?%{GREEDYDATA:msg2} msg2 field_mappings { field: "msg2" value: "{\"timestamp\": \"2021-03-14T14:54:40.842152+0000\",\"flow_id\": 1885148860701096,\"in_iface\": \"enp94s0\",\"event_type\": \"alert\",\"vlan\": 522,\"src_ip\": \"1.1.2.1\",\"src_port\": 51972,\"dest_ip\": \"1.2.3.4\",\"dest_port\": 55291,\"proto\": \"TCP\"}" }
"<13>1 2022-07-14T15:03:04+00:00 suricata suricata - - - {\"timestamp\": \"2021-03-14T14:54:40.842152+0000\"} - - - {\"timestamp\": \"2021-03-14T14:54:40.842152+0000\",\"flow_id\": 1885148860701096,\"in_iface\": \"enp94s0\",\"event_type\": \"alert\",\"vlan\": 522,\"src_ip\": \"1.1.2.1\",\"src_port\": 51972,\"dest_ip\": \"1.2.3.4\",\"dest_port\": 55291,\"proto\": \"TCP\"}" %{TIMESTAMP_ISO8601} %{WORD} %{WORD} ([- ]+)?%{GREEDYDATA:message} ([- ]+)?%{GREEDYDATA:msg2} msg2 Error - message already exists in state and not overwritable.

En savoir plus sur l'attribution de champs metadata.event_type UDM

Lorsque vous attribuez un champ metadata.event_type UDM à un enregistrement UDM, il est validé pour s'assurer que les champs associés requis sont présents dans l'enregistrement UDM. Chaque metadata.event_type UDM nécessite un ensemble différent de champs associés. Par exemple, un événement USER_LOGIN sans user n'est pas utile.

Si un champ associé obligatoire est manquant, la validation UDM renvoie une erreur:

  "error": {
    "code": 400,
    "message": "Request contains an invalid argument.",
    "status": "INVALID_ARGUMENT"
  }

Un analyseur grok renvoie une erreur plus détaillée:

  generic::unknown: 
  invalid event 0: LOG_PARSING_GENERATED_INVALID_EVENT: 
  "generic::invalid_argument: udm validation failed: target field is not set"

Pour trouver les champs obligatoires d'un event_type UDM que vous souhaitez attribuer, utilisez les ressources suivantes:

  • Documentation Google SecOps : Guide d'utilisation du format UDM : champs UDM obligatoires et facultatifs pour chaque type d'événement

  • Ressources tierces non officielles: Validation des événements UDM

    Lorsque le guide d'utilisation de la gestion des identités et des droits d'accès ne fournit pas suffisamment de détails, ce document complète la documentation officielle en fournissant les champs UDM obligatoires minimaux nécessaires pour renseigner un metadata.event_type UDM donné.

    Par exemple, ouvrez le document et recherchez le type d'événement GROUP_CREATION.

    Les champs UDM minimaux suivants doivent s'afficher, présentés sous la forme d'un objet UDM:

    {
    "metadata": {
        "event_timestamp": "2023-07-03T13:01:10.957803Z",
        "event_type": "GROUP_CREATION"
    },
    "principal": {
        "user": {
            "userid": "pinguino"
        }
    },
    "target": {
        "group": {
            "group_display_name": "foobar_users"
        }
    }
}

Créer des instructions pour un extrait de code

L'approche par extrait de code vous permet d'utiliser une syntaxe semblable à Logstash pour définir comment extraire et transformer les valeurs du journal brut, et les attribuer aux champs UDM de l'enregistrement UDM.

Avant de créer une extension d'analyseur à l'aide de l'approche par extrait de code, vous devez avoir lu les sections suivantes:

Pour définir l'extension de l'analyseur, procédez comme suit:

  1. Pour obtenir des conseils et des bonnes pratiques, consultez Conseils et bonnes pratiques pour écrire des instructions d'extrait de code.
  2. Créer une instruction d'extrait de code
  3. Envoyer une instruction d'extrait de code

Conseils et bonnes pratiques pour écrire des instructions d'extrait de code

Les instructions d'extrait de code peuvent échouer en raison de problèmes tels que des modèles Grok incorrects, des opérations de renommage ou de remplacement échouées, ou des erreurs de syntaxe. Pour obtenir des conseils et des bonnes pratiques, consultez les éléments suivants:

Créer une instruction d'extrait de code

Les instructions d'extrait de code utilisent la même syntaxe et les mêmes sections que l'analyseur par défaut (ou personnalisé) :

  • Section 1. Extrayez les données du journal brut.
  • Section 2. Transformez les données extraites.
  • Section 3. Attribuez une ou plusieurs valeurs à un champ UDM.
  • Section 4. Liez les champs d'événement UDM à la clé @output.

Pour créer une extension d'analyseur à l'aide de l'approche par extrait de code, procédez comme suit:

  1. Sur la page Extensions d'analyseur, dans le panneau Extrait de code CBN, saisissez un extrait de code pour créer l'extension d'analyseur.
  2. Cliquez sur Valider pour valider les instructions de mise en correspondance.

Exemples d'instructions d'extraits de code

L'exemple suivant illustre un extrait de code.

Voici un exemple de journal brut:

  {
      "insertId": "00000000",
      "jsonPayload": {
          ...section omitted for brevity...
          "packets_sent": "4",
          ...section omitted for brevity...
      },
      "timestamp": "2022-05-03T01:45:00.150614953Z"
  }

Voici un exemple d'extrait de code qui mappe la valeur dans jsonPayload.packets_sent au champ UDM network.sent_bytes:

mutate {
 replace => {
    "jsonPayload.packets_sent" => ""
 }
}
filter {
    # Section 1. extract data from the raw JSON log
    json {
        source => "message"
        array_function => "split_columns"
        on_error => "_not_json"
    }
    if [_not_json] {
        drop {
            tag => "TAG_UNSUPPORTED"
        }
    } else {
        # Section 2. transform the extracted data
        if [jsonPayload][packets_sent] not in ["",0] {
            mutate {
                convert => {
                    "jsonPayload.packets_sent" => "uinteger"
                }
            }
            # Section 3. assign the value to a UDM field
            mutate {
                copy => {
                    "udm.network.sent_bytes" => "jsonPayload.packets_sent"
                }
                on_error => "_exception"
            }
            if ![_exception] {
                # Section 4. Bind the UDM fields to the @output key
                mutate {
                    merge => {
                        "@output" => "event"
                    }
                }
            }
        }
    }
}

Envoyer une instruction d'extrait de code

  1. Cliquez sur Envoyer pour enregistrer les instructions de mappage.

  2. Google SecOps valide les instructions de mappage.

    • Si le processus de validation réussit, l'état passe à En service et les instructions de mappage commencent à traiter les données de journal entrantes.
    • Si le processus de validation échoue, l'état passe à Échec et une erreur s'affiche dans le champ "Journal brut".

Gérer les extensions d'analyseur existantes

Vous pouvez afficher, modifier, supprimer et contrôler l'accès aux extensions d'analyseur existantes.

Afficher une extension d'analyseur existante

  1. Dans la barre de navigation, sélectionnez Paramètres du SIEM > Analyseurs.
  2. Dans la liste "Analyseurs", recherchez l'analyseur (type de journal) que vous souhaitez afficher. Les analyseurs avec une extension d'analyseur sont indiqués par le texte EXTENSION à côté de leur nom.

  3. Accédez à cette ligne, puis cliquez sur Menu > Afficher l'extension.

    L'onglet Afficher l'analyseur personnalisé/prédéfini > Extension s'affiche et fournit des informations sur l'extension de l'analyseur. Le panneau récapitulatif affiche l'extension d'analyseur LIVE par défaut.

Modifier une extension d'analyseur

  1. Ouvrez Afficher l'analyseur personnalisé/prédéfini > Onglet "Extension", comme décrit dans la section Afficher une extension d'analyseur existante.

  2. Cliquez sur le bouton Modifier l'extension.

    La page Extensions d'analyseur s'affiche.

  3. Modifiez l'extension de l'analyseur.

    • Pour annuler la modification et supprimer les modifications, cliquez sur Supprimer le brouillon.

    • Pour supprimer l'extension d'analyseur à tout moment, cliquez sur Supprimer l'extension non réussie.

    • Lorsque vous avez terminé de modifier l'extension d'analyseur, cliquez sur Envoyer.

      Le processus de validation s'exécute pour valider la nouvelle configuration.

Supprimer une extension d'analyseur

  1. Ouvrez Afficher l'analyseur personnalisé/prédéfini > Onglet "Extension", comme décrit dans la section Afficher une extension d'analyseur existante.

  2. Cliquez sur le bouton Supprimer l'extension.

Contrôler l'accès aux extensions de l'analyseur

Par défaut, les utilisateurs disposant du rôle Administrateur peuvent accéder aux extensions d'analyseur. Vous pouvez contrôler qui peut afficher et gérer les extensions d'analyseur. Pour en savoir plus sur la gestion des utilisateurs et des groupes, ou sur l'attribution de rôles, consultez la section Contrôle des accès basé sur les rôles.

Les nouveaux rôles de Google SecOps sont résumés dans le tableau suivant.

Fonctionnalité Action Description
Analyseur Supprimer Supprimez les extensions de l'analyseur.
Analyseur Modifier Créer et modifier des extensions d'analyseur
Analyseur Afficher Afficher les extensions de l'analyseur.

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