Utiliser des extensions d'analyseur

Google Security Operations propose plusieurs méthodes pour définir comment les données des journaux bruts d'origine sont analysées et normalisées en enregistrement Unified Data Model (UDM).

• Analyseurs par défaut: instructions de mappage de données prédéfinies gérées par Google Security Operations qui mappent les données de journaux brutes d'origine sur les champs UDM.
• Analyseurs personnalisés: instructions de mappage de données personnalisées créées et gérées par un client et répondant aux besoins spécifiques de ce dernier en matière d'analyse des données.
• Extensions d'analyseur: instructions de mappage de données supplémentaires qui étendent un analyseur par défaut ou personnalisé pour mapper des champs supplémentaires dans le journal brut d'origine. Cela ne remplace pas complètement un analyseur par défaut ou personnalisé, mais étend les instructions de mappage existantes dans un analyseur par défaut ou personnalisé.

Ce document explique comment utiliser les extensions d'analyseur.

Avant de commencer

Les documents suivants expliquent les concepts préalables importants à connaître lorsque vous travaillez avec des extensions d'analyseur:

• Présentation du modèle de données unifié
• Présentation de l'analyse des journaux
• Documentation de référence sur la syntaxe de l'analyseur

À propos des extensions d'analyseur

Une extension d'analyseur vous permet de créer des instructions de mappage supplémentaires en plus de celles définies dans un analyseur par défaut ou personnalisé pour répondre à un cas d'utilisation unique. Cette fonctionnalité vise à étendre un analyseur par défaut ou personnalisé existant. Une extension d'analyseur ne remplace pas un analyseur par défaut ou personnalisé. Vous ne pouvez pas créer d'analyseur à l'aide d'une extension d'analyseur.

L'extension d'analyseur lit le journal brut d'origine et insère les valeurs extraites dans des champs spécifiques de l'enregistrement UDM. L'enregistrement UDM contient des données définies à la fois par l'analyseur par défaut ou personnalisé et par l'extension de l'analyseur.

Les instructions de mappage des données dans une extension d'analyseur prévalent sur celles d'un analyseur par défaut ou personnalisé. En cas de conflit dans les instructions de mappage, l'extension de l'analyseur écrase une valeur définie par l'analyseur par défaut ou personnalisé. 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 autre champ de journal brut sur le même champ UDM, l'extension de l'analyseur écrase la valeur définie par l'analyseur par défaut. Une exception concerne les champs répétés. Vous pouvez configurer l'extension de l'analyseur pour ajouter des valeurs lorsque vous écrivez des données dans un champ répété.

Vous créez une extension d'analyseur par type de journal. Chaque type de journal est identifié par un libellé d'ingestion unique. Pour obtenir la liste des types de journaux, consultez la section Analyseurs par défaut compatibles.

Pour créer une extension d'analyseur, Google Security Operations doit pouvoir ingérer et normaliser les journaux bruts d'origine à l'aide d'un analyseur par défaut ou personnalisé. L'extension d'analyseur extrait des données supplémentaires du journal brut d'origine, puis les fusionne dans l'enregistrement UDM.

Les extensions d'analyseur acceptent les types d'instructions de mappage suivants:

• Type d'extrait de code: vous écrivez du code d'analyseur semblable aux analyseurs par défaut et personnalisés. Les journaux bruts d'origine peuvent être dans l'un des formats de données compatibles pour le type de journal.
• Type de champ de données: vous spécifiez les champs d'origine et de destination dans l'interface de l'application. Les journaux bruts d'origine doivent être mis en forme dans l'un des formats suivants :
  • JSON natif, XML natif ou CSV
  • En-tête Syslog, plus JSON natif, XML natif ou CSV. Vous pouvez créer une instruction de mappage de type de champ de données pour un sous-ensemble de types de journaux dans Analyseurs par défaut compatibles. Recherchez les éléments au format JSON, XML, CSV, SYSLOG + JSON, SYSLOG + XML et SYSLOG + CSV.

Tenez compte des points suivants lorsque vous créez une extension d'analyseur:

• Les données peuvent être mappées sur n'importe quel champ UDM compatible avec les types de données standards et les valeurs répétées.
• Vous ne pouvez pas mapper de données sur les champs UDM suivants :
  • event.idm.read_only_udm.additional
  • event.idm.graph.entity.additional
• Avant de créer une instruction de mappage des données, assurez-vous que votre instance Google Security Operations a ingéré des journaux bruts d'origine au cours des 30 derniers jours pour le type de journal et que ces journaux bruts contiennent le champ que vous prévoyez de définir dans les critères de précondition. Ces journaux bruts d'origine sont utilisés pour valider les instructions de mappage des données.
• Une fois une extension d'analyseur mise en ligne, elle commence à analyser les données entrantes. Vous ne pouvez pas analyser les données de journaux brutes rétroactivement.

Cycle de vie d'une extension d'analyseur

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

• DRAFT: extension d'analyseur nouvellement créée qui n'a pas encore été envoyée.
• VALIDATING: Google Security Operations 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é.

Ouvrir la page "Extensions de l'analyseur"

Suivez la procédure décrite dans l'une des sections suivantes pour accéder à la page Extensions d'analyseur.

Démarrer depuis la barre de navigation

1. Dans la barre de navigation, sélectionnez Settings (Paramètres), SIEM Settings (Paramètres du SIEM), puis Parsers (Analyseurs).
2. Identifiez le type de journal que vous souhaitez étendre dans le tableau Analyseurs.
3. Accédez à cette ligne, puis cliquez sur le menu more_vert.
4. Cliquez sur Créer une extension.

Commencer à partir de la recherche dans les journaux bruts

1. Utilisez la recherche dans les 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 le bouton Gérer l'analyseur.
5. Dans la boîte de dialogue Gérer l'analyseur, sélectionnez Créer une extension, puis cliquez sur Suivant. La page Extensions d'analyseur s'ouvre en mode édition. Vous pouvez commencer à définir l'extension de l'analyseur.

Créer une extension d'analyseur

Cette section explique comment créer une extension d'analyseur après avoir ouvert la page "Extensions d'analyseur". Les champs disponibles sur la page Extensions d'analyseur varient en fonction de la structure du journal brut.

1. Examinez l'exemple de signe brut dans le panneau Journal brut pour vous assurer qu'il représente les journaux que l'extension d'analyseur traitera. Utilisez l'exemple de journal brut comme référence lorsque vous créez l'extension de l'analyseur.

   • Si vous avez accédé à la page Extensions d'analyseur à partir de la recherche de journaux bruts, le panneau affiche le journal brut d'origine que vous avez sélectionné dans les résultats de recherche.

   • Si vous avez accédé à la page Extensions d'analyseur dans la barre de navigation, un exemple de journal brut pour ce type de journal s'affiche.

2. Sélectionnez la méthode d'extension. Sélectionnez l'une des options suivantes :

   • Mappez les champs de données: créez un mappage des champs de données. Utilisez les champs d'application pour définir le champ de journal brut d'origine et le champ UDM de destination.

   • Écrire un extrait de code: créez un extrait de code pour tous les formats de journal compatibles. L'extrait de code utilise la même syntaxe d'analyseur que les analyseurs par défaut et personnalisés. Pour en savoir plus sur la syntaxe de l'analyseur, consultez la section Syntaxe de l'analyseur.

Passez à l'une des sous-sections suivantes, spécifiques à la méthode d'extension sélectionnée.

• Créer une instruction de mappage de champs de données
• Créer une instruction de mappage d'extrait de code

Créer une instruction de mappage de champs de données

Créez une instruction de mappage de champ de données lorsque les journaux bruts entrants sont au format JSON, XML, CSV, en-tête Syslog plus JSON, en-tête Syslog plus XML ou en-tête Syslog plus CSV. Définissez le chemin d'accès au nom du champ d'origine et au champ UDM de destination dans l'instruction de mappage des données.

1. Dans le sélecteur Champs répétés, spécifiez comment l'extension de l'analyseur enregistre une valeur dans les champs compatibles avec un tableau de valeurs.

   • Ajouter des valeurs: la valeur est ajoutée à l'ensemble de valeurs existant stocké dans le champ.
   • Remplacer les valeurs: la nouvelle valeur remplace toutes les valeurs précédemment stockées.

   Certains champs UDM, tels que principal.ip et entity.asset.hostname, stockent un tableau de valeurs. Ces champs répétés sont identifiés par le libellé repeated dans la liste des champs du modèle de données unifié. Pour en savoir plus, consultez la section Sélecteur de champs répétés.

2. Si les champs Syslog et Cible s'affichent, Google Security Operations a détecté que le journal brut inclut un en-tête Syslog.

   Si Google Security Operations identifie que l'exemple de journal brut n'est pas au format JSON natif, XML natif ou CSV et qu'il comporte un en-tête Syslog, les champs Syslog et Cible s'affichent. Utilisez les champs suivants pour définir un Grok et des modèles d'expression régulière qui prétraitent l'en-tête Syslog et extraient la partie structurée du journal. La partie structurée du journal peut être mappée à l'aide de champs de données.

   • Champ Syslog: 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.
   • Champ Cible: spécifiez le nom de la variable dans le modèle d'extraction qui stocke la partie structurée du journal.

   Pour savoir comment définir un modèle d'extraction à l'aide de Grok et d'expressions régulières, consultez Définir les champs de l'extracteur Syslog.

   L'image suivante montre comment ajouter un modèle d'extraction et un nom de variable aux champs Syslog et Cible, respectivement.

   

   Les champs Syslog et Cible sont obligatoires et fonctionnent ensemble pour séparer l'en-tête Syslog de la partie structurée du journal.

3. 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:

   • Opération réussie: 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.

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

   L'instruction de précondition ne permet d'identifier qu'un sous-ensemble des journaux bruts d'origine 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, c'est-à-dire que les valeurs correspondent, 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: 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: saisissez la valeur qui doit correspondre aux données du champ Champ de précondition.

5. Définissez l'instruction de mappage des données:

   • Champ de données brutes: 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.
   • Champ de destination: saisissez le nom complet du champ UDM dans lequel la valeur sera stockée, par exemple udm.metadata.collected_timestamp.seconds.

6. Cliquez sur Envoyer pour enregistrer l'instruction de mappage.

7. Google Security Operations valide l'instruction de mise en correspondance.

   • Si le processus de validation réussit, l'état passe à En service et l'instruction de mappage commence à traiter les données de journal entrantes.
   • Si le processus de validation échoue, l'état devient É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"}
   

Pour obtenir la liste de tous les champs possibles dans une extension d'analyseur, consultez la section Champs dans une instruction de mappage de données.

Champs dans une instruction de mappage de données

Cette section décrit tous les champs pouvant être définis dans une extension d'analyseur.

Créer une instruction de mappage d'extrait de code

Un extrait de code utilise une syntaxe semblable à Logstash pour définir comment extraire et transformer les valeurs du journal brut d'origine, puis les attribuer à l'enregistrement UDM. Un extrait de code utilise la même syntaxe et les mêmes sections de l'instruction qu'un analyseur par défaut ou personnalisé. Les sections d'un extrait de code sont les suivantes:

• Section 1. Extrayez les données du journal d'origine.
• 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.

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 extrait de code qui mappe la valeur de jsonPayload.packets_sent au champ UDM network.sent_bytes.

mutate {
 replace => {
    "jsonPayload.packets_sent" => ""
 }
}

filter {
    # Section 1. extract the data from the original 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"
                    }
                }
            }
        }
    }
}

1. Cliquez sur Envoyer pour enregistrer l'instruction de mappage.

2. Google Security Operations valide l'instruction de mise en correspondance.

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

Afficher une extension d'analyseur existante

1. Dans la barre de navigation, sélectionnez Settings (Paramètres), SIEM Settings (Paramètres du SIEM), puis Parsers (Analyseurs).
2. Dans la liste des analyseurs, identifiez le type de journal avec une extension d'analyseur. Il est identifié par le texte EXTENSION à côté du nom.
3. Accédez à cette ligne, puis cliquez sur le menu more_vert.
4. Cliquez sur Afficher l'extension.
5. L'onglet Extension de l'explorateur Afficher l'explorateur personnalisé/prédéfini s'affiche avec des informations sur l'extension de l'explorateur. 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". Pour savoir comment ouvrir la page, consultez 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 du lecteur.
   • Pour annuler la modification et supprimer les modifications, cliquez sur Supprimer le brouillon.
4. Lorsque vous avez terminé de modifier l'extension d'analyseur, cliquez sur Envoyer.

5. Si vous envoyez la modification, 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". Pour savoir comment ouvrir cette page, consultez Afficher une extension d'analyseur existante.

2. Cliquez sur le bouton Modifier l'extension. La page Extensions d'analyseur s'affiche.

3. Cliquez sur le bouton Supprimer l'extension.

Lorsque vous modifiez une extension d'analyseur, vous pouvez la supprimer à tout moment. Cliquez sur l'une des options suivantes:

• Supprimer le brouillon
• Supprimer l'extension ayant échoué

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

Certains champs UDM stockent un tableau de valeurs, tels que principal.ip et Entity.asset.hostname. Si vous créez une extension d'analyseur pour stocker des données dans un champ répété, cette option vous permet de contrôler si la valeur est ajoutée au tableau ou si elle remplace toutes les valeurs existantes définies par l'analyseur par défaut. Les champs répétés sont identifiés par l'étiquette répétée dans la liste des champs du modèle de données unifié.

Si l'option Appends values (Ajout des valeurs) est sélectionnée, l'extension de l'analyseur ajoute la valeur extraite au tableau des valeurs existantes dans le champ UDM. Si l'option Replace Values (Remplacer les valeurs) est sélectionnée, l'extension de l'analyseur remplace le tableau des valeurs existantes dans le champ UDM par la valeur extraite. Le sélecteur Champs répétés n'a aucune incidence sur la façon dont les données sont stockées dans les champs qui ne sont pas répétés.

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. Par 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é. Le mappage de valeurs sur udm.intermediary.hostname n'est pas accepté, 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 des champs répétés sur l'enregistrement UDM généré.

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'expressions régulières. L'expression inclut un nom de variable qui identifie la partie structurée du journal brut. Dans le champ Target (Cible), vous spécifiez le nom de cette 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"}

L'image suivante montre les champs Syslog et Cible remplis:

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

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

De nouvelles autorisations sont disponibles pour contrôler qui peut afficher et gérer les extensions d'analyseur. Par défaut, les extensions d'analyseur sont accessibles aux utilisateurs disposant du rôle Administrateur. 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 Security Operations sont résumés dans le tableau suivant.