Créer des analyseurs et des extensions d'analyseur personnalisés avec Gemini

Compatible avec :

Ce guide aide les analystes de sécurité et les ingénieurs de détection à utiliser l'analyse par IA dans Google Security Operations pour créer des analyseurs personnalisés à partir de zéro ou des extensions d'analyseur qui complètent les analyseurs existants. À l'aide de requêtes en langage naturel et de la documentation du fournisseur, vous pouvez mapper des journaux bruts au modèle de données unifié (UDM) sans écrire de syntaxe d'analyseur complexe ni d'expressions régulières.

Choisir entre les analyseurs personnalisés IA et les extensions d'analyseur IA

Le tableau suivant compare les fonctionnalités "Créer un analyseur avec l'IA" et "Écrire une extension avec l'IA" de l'analyse par IA :

Aspect de la caractéristique Créer un analyseur avec l'IA Écrire une extension avec l'IA
Sortie Un analyseur personnalisé complet et autonome Une extension superposée à un analyseur existant
Cas d'utilisation principal Nouvelles sources de journaux ou sources non compatibles, ou réécriture complète de l'analyseur Ajouter ou corriger des champs spécifiques sur un analyseur syntaxique fonctionnel
Entrée Type de journal, journaux bruts ingérés et liens facultatifs vers la documentation Type de journal, exemple de journal brut et prompt décrivant les champs à mapper

Terminologie clé

  • Analyse par IA : suite de fonctionnalités d'analyse assistée par IA dans Google SecOps, y compris la génération d'analyseurs personnalisés par IA (Créer un analyseur avec l'IA) et les extensions d'analyseur par IA (Écrire une extension avec l'IA).
  • Modèle de données unifié (UDM) : structure de données standard utilisée dans Google SecOps pour stocker et analyser les données de journaux.

Avant de commencer

Avant d'utiliser l'analyse syntaxique par IA, vérifiez que les conditions préalables suivantes sont remplies :

  • Vérifiez que les fonctionnalités d'analyse de l'IA sont activées pour votre instance Google SecOps. Si vous ne voyez pas les options Créer un analyseur avec l'IA ou Écrire une extension avec l'IA, contactez votre représentant Google SecOps.
  • Pour les extensions d'analyseur IA, vérifiez que le type de journal cible dispose déjà d'un analyseur prédéfini ou personnalisé actif, et préparez un exemple de journal brut pour tester votre extraction.
  • Pour générer un analyseur personnalisé d'IA, ingérez un échantillon représentatif de la source de journaux avant de commencer. L'agent d'analyseur apprend à partir des journaux que vous avez déjà ingérés pour le type de journal sélectionné. Si aucun journal n'est trouvé pour le type de journal, la génération ne peut pas démarrer. Les tentatives de démarrage infructueuses ne sont pas décomptées de votre quota.
  • Pour la génération d'analyseurs personnalisés par IA, préparez un à cinq liens accessibles au public vers la documentation de référence du format de journal du fournisseur, comme un dictionnaire de champs, un schéma d'événement ou une page d'exemples de journaux (recommandé). Une documentation complète est le facteur le plus important pour la qualité de l'analyseur.

Créer un analyseur personnalisé avec l'IA

"Créer un analyseur avec l'IA" crée un analyseur personnalisé complet pour une source de journaux à partir de zéro. Vous sélectionnez un type de journal et fournissez éventuellement des liens vers la documentation du fournisseur sur les journaux. L'agent d'analyseur échantillonne vos journaux ingérés, recherche le schéma des journaux, planifie le mappage des champs bruts vers l'UDM et écrit le code de l'analyseur en JavaScript. Vous examinez ensuite le résultat et l'affinez à l'aide d'instructions en anglais simple qui font référence aux noms de champs bruts et aux champs UDM. Une fois le résultat prêt, vous envoyez l'analyseur comme n'importe quel autre analyseur personnalisé.

La génération d'analyseurs personnalisés par IA vous permet d'effectuer les opérations suivantes :

  • Intégrez une source de journaux qui ne dispose pas d'analyseur prédéfini ou dont l'analyseur prédéfini ne correspond pas au format de vos journaux.
  • Générez un analyseur complet qui couvre tous les formats de journaux distincts trouvés dans vos données ingérées, plutôt qu'un seul échantillon.
  • Affinez l'analyseur généré à l'aide de prompts de suivi sans écrire vous-même le code de l'analyseur.

Créer un analyseur personnalisé généré par l'IA

  1. Dans Google SecOps, accédez à Paramètres SIEM > Analyseurs.
  2. Cliquez sur Ajouter un analyseur.
  3. Dans la boîte de dialogue Créer un analyseur personnalisé, sélectionnez la source de journaux que vous souhaitez analyser (par exemple, GCP DNS).
  4. Sous Comment allez-vous créer l'analyseur ?, sélectionnez Créer un analyseur avec l'IA.
  5. Cliquez sur Créer.

Ajouter la documentation produit et lancer la génération

  1. Facultatif : dans le volet Agent d'analyse, dans le champ Ajouter un lien vers le produit, collez un lien vers la documentation du fournisseur sur les journaux, puis cliquez sur Ajouter. Vous pouvez ajouter jusqu'à cinq liens. Le compteur Documentation indique le nombre de liens que vous avez ajoutés.
  2. Cliquez sur Générer l'analyseur.

Pour améliorer la couverture des champs dans l'analyseur généré, suivez ces consignes lorsque vous sélectionnez des liens vers la documentation :

  • Fournissez uniquement des liens publics vers la documentation du fournisseur. Si un lien est privé ou inaccessible, l'agent d'analyse l'ignore et effectue une recherche sur le Web sans que la génération échoue.
  • Lien vers des pages décrivant les champs de journal et les types d'événements, comme un schéma de journal, un dictionnaire de champs ou une documentation de référence sur les événements. Évitez les pages marketing ou les présentations de produits.
  • Sélectionnez les pages qui correspondent au format de journal que vous ingérez. Par exemple, si vous ingérez des journaux d'audit JSON, ajoutez un lien vers la documentation de référence sur les journaux d'audit JSON plutôt que vers celle sur syslog.
  • Ajoutez un lien pour chaque catégorie d'événements si le fournisseur documente différentes catégories d'événements sur des pages distinctes (par exemple, les requêtes DNS, les événements de pare-feu et l'activité des administrateurs).

Suivre la progression de la génération

Lorsque la génération de l'analyseur personnalisé commence, l'état passe à GÉNÉRATION EN COURS. Le processus de génération comprend les étapes suivantes :

Étape Action de l'agent Sortie transmise à l'étape suivante
Récupérer des journaux bruts L'agent échantillonne les journaux ingérés pour le type de journal. Il regroupe les journaux pour sélectionner un ensemble d'exemples de journaux couvrant chaque format de journal et chaque forme d'événement distincts. Exemples de journaux représentatifs
Documentation de recherche L'agent lit les liens vers la documentation que vous avez fournis ou effectue une recherche sur le Web si vous n'avez pas fourni de liens. Il combine ces informations avec les exemples de journaux pour créer un schéma de journal et un dictionnaire de champs. Schéma de journal et dictionnaire de champs
Créer un plan de mappage L'agent identifie chaque type d'événement dans les journaux et planifie la mise en correspondance de chaque champ de journal brut avec le champ UDM correspondant. Plan de mappage du champ brut au champ UDM pour chaque type d'événement
Générer le code de l'analyseur L'agent convertit le plan de mappage en code d'analyseur JavaScript. Il teste le code par rapport aux exemples de journaux et résout les erreurs jusqu'à ce que l'analyseur s'exécute correctement. Analyseur prêt à être examiné

Si la génération de l'analyseur échoue, car aucun journal n'est trouvé pour le type de journal sélectionné, ingérez des journaux bruts pour ce type de journal avant de relancer la génération. Pour tout autre échec de génération, aucune option de tri manuel n'est disponible. Déclenchez une nouvelle session de génération. Si l'échec persiste, contactez l'assistance pour ouvrir une demande d'assistance.

Examiner et affiner l'analyseur personnalisé

Une fois la génération de l'analyseur personnalisé terminée, l'état passe à GÉNÉRÉ PAR IA et la page affiche les volets suivants :

  • Agent d'analyseur : affiche le champ de prompt Affiner l'analyseur avec l'IA, dans lequel vous pouvez saisir des instructions de suivi.
  • Code de l'analyseur : affiche le code de l'analyseur JavaScript généré pour examen. Le code généré est en lecture seule avant l'envoi. Pour modifier la logique, saisissez une requête dans le champ Affiner l'analyseur avec l'IA.
  • Journal brut : affiche des exemples de journaux bruts pour le type de journal. Vous pouvez cliquer sur Modifier pour coller votre propre ligne de journal, ou sur Actualiser pour charger d'autres exemples.
  • Afficher la sortie UDM : exécute le code de l'analyseur actuel sur le journal brut et affiche l'événement UDM obtenu afin que vous puissiez vérifier chaque mappage.

Examiner le résultat généré

Avant d'activer l'analyseur, examinez les mappages générés dans vos exemples de journaux :

  1. Chargez plusieurs journaux bruts, y compris chaque type d'événement que vous souhaitez analyser, puis cliquez sur Afficher la sortie UDM pour chaque journal.
  2. Vérifiez que l'analyseur mappe les champs de journaux bruts sur les champs UDM appropriés et renseigne leurs valeurs avec précision (par exemple, les métadonnées d'événement, les champs d'entité tels que principal et target, et les champs de résultat de sécurité).
  3. Vérifiez si des champs bruts importants ne sont pas mappés.

Affiner l'analyseur personnalisé avec l'IA

Si un mappage est incorrect ou manquant, saisissez une instruction dans le champ Affiner l'analyseur avec l'IA, puis cliquez sur Confirmer. L'agent d'analyseur met à jour l'analyseur existant au lieu de recommencer et conserve tous les mappages que vous n'avez pas mentionnés. Chaque affinement crée une version du code de l'analyseur que vous pouvez examiner.

Suivez ces consignes pour créer des prompts d'affinage efficaces :

  1. Indiquez à la fois le champ source brut (ou un exemple de valeur du journal) et le chemin d'accès exact du champ UDM cible.
  2. Regroupez les modifications associées et évitez de mélanger des corrections sans rapport dans une seule longue requête.
  3. Placez les chaînes exactes du journal brut entre guillemets simples, par exemple 'NXDOMAIN' ou 'allow'.
  4. Indiquez explicitement les mappages conditionnels à l'aide d'une structure if ... then ... otherwise ... lorsqu'un mappage dépend d'une valeur de champ.
  5. Demandez à l'agent de mapper les attributs spécifiques au fournisseur qui n'ont pas de champ UDM correspondant à additional.fields avec un nom de clé clair.

Le tableau suivant fournit des exemples de requêtes d'affinage pour les journaux GCP DNS :

Objectif Exemple de prompt
Corriger un mappage incorrect "Map jsonPayload.sourceIP to principal.ip instead of target.ip."
Ajouter un champ manquant "Map jsonPayload.vmInstanceName to principal.hostname."
Mapper une valeur imbriquée ou répétée "Map jsonPayload.queryName to network.dns.questions.name and jsonPayload.queryType to network.dns.questions.type."
Appliquez la logique conditionnelle "If jsonPayload.responseCode is 'NXDOMAIN', set security_result.summary to 'Domain does not exist'. Otherwise, leave it empty."
Définir le type d'événement "Set metadata.event_type to NETWORK_DNS for all DNS query logs."
Mapper un champ spécifique au fournisseur "Map jsonPayload.alias_query_response_code to additional.fields with key 'alias_query_response_code'."
Supprimer un mappage "Stop mapping jsonPayload.protocol to network.application_protocol."

Envoyer et activer l'analyseur personnalisé

Lorsque la sortie UDM est exacte, cliquez sur Envoyer pour enregistrer et activer l'analyseur personnalisé généré.

Pour abandonner l'analyseur brouillon, cliquez sur Supprimer. Pour supprimer ultérieurement un analyseur personnalisé généré par l'IA que vous avez enregistré, ouvrez l'analyseur, puis cliquez sur Supprimer sous Supprimer l'analyseur personnalisé.

Résoudre les problèmes de génération d'analyseurs personnalisés par l'IA

Le tableau suivant liste les problèmes courants que vous pouvez rencontrer lors de la génération d'un analyseur personnalisé avec l'IA et comment les résoudre :

Problème ou symptôme Solution
L'option Créer un analyseur avec l'IA ne s'affiche pas. La fonctionnalité n'est pas activée pour votre instance. Contactez votre représentant Google SecOps.
La génération échoue, car aucun journal n'est trouvé pour le type de journal. L'agent d'analyse nécessite des journaux bruts ingérés pour le type de journal sélectionné. Ingérez les journaux bruts pour le type de journal avant de relancer la génération.
La génération échoue pour une autre raison. Aucune option de tri manuel n'est disponible pour une génération ayant échoué. Déclenchez à nouveau la génération. Si l'échec persiste, contactez l'assistance pour ouvrir une demande d'assistance.
La génération prend beaucoup de temps. La génération prend généralement entre 30 et 90 minutes. Les sources de journaux complexes comportant de nombreux formats distincts ou des schémas volumineux prennent plus de temps. Vous pouvez fermer la page et revenir à Paramètres du SIEM > Analyseurs plus tard.
De nombreux champs ne sont pas mappés. Ajoutez des liens du document décrivant les champs de journal et démarrez une nouvelle session, ou utilisez des prompts d'affinage pour mapper les champs manquants.
Une requête d'affinement a modifié un mappage non lié. Décrivez la correction dans un prompt de suivi (par exemple, "Revert the change to principal.ip and map jsonPayload.sourceIP to it again."). Vous pouvez également envoyer et activer l'analyseur pour modifier le code manuellement.
Certains journaux ne sont pas analysés dans Afficher la sortie UDM. Collez le journal défaillant dans le volet Journal brut et envoyez un prompt d'affinement qui cite la partie non analysée du journal.

Créer une extension d'analyseur avec l'IA

Lorsqu'un analyseur de journaux par défaut dans Google SecOps analyse votre source de journaux, il peut omettre les attributs personnalisés spécifiques au client, les champs facultatifs ou la télémétrie spécialisée. L'utilisation d'extensions d'analyseur IA (Écrire une extension avec l'IA) vous permet d'effectuer les opérations suivantes :

  • Extrayez des champs supplémentaires des journaux bruts et mappez-les à des champs UDM standards ou à des champs additional.fields personnalisés.
  • Appliquez une logique conditionnelle et des transformations de valeurs, par exemple en mappant des actions de chaîne à des types énumérés UDM.
  • Affinez les extensions générées de manière interactive lors de sessions de chat multitours sans partir de zéro.

Bonnes pratiques pour créer des prompts

Pour obtenir des extensions d'analyseur précises, suivez ces consignes de prompt :

  1. Indiquez clairement quelle partie du journal brut extraire et quel chemin de champ UDM exact elle remplit (par exemple, principal.ip, target.user.email_addresses ou security_result.action).
  2. Placez les chaînes littérales, les délimiteurs ou les exemples de valeurs dans les journaux non structurés entre guillemets simples, par exemple '198.51.100.0' ou 'allow'.
  3. Demandez à l'IA de mapper les attributs propriétaires ou spécifiques au fournisseur qui n'ont pas de champ UDM dédié dans additional.fields avec un nom de clé clair (par exemple, additional.fields["application"]).

Générer une extension d'analyseur

Vous pouvez démarrer le workflow d'extension d'analyseur à partir de l'un des emplacements suivants dans Google SecOps :

  • Accédez à Paramètres SIEM> Analyseurs pour sélectionner et étendre un analyseur de journaux existant.
  • Ouvrez le flux de création d'extension directement à partir d'un événement comportant des champs non analysés lorsque vous examinez les journaux sur la page Recherche.

Pour générer une extension d'analyseur à partir de la page Analyseurs, procédez comme suit :

  1. Dans Google SecOps, accédez à Paramètres SIEM > Analyseurs.
  2. Recherchez dans la table Analyseurs le type de journal que vous souhaitez étendre.
  3. Sur la ligne de l'analyseur, cliquez sur Menu, puis sélectionnez Étendre l'analyseur > Créer une extension.
  4. Dans le volet Journal brut, vérifiez l'exemple de journal brut ou cliquez sur Modifier pour coller un exemple du journal que vous souhaitez analyser.
  5. Dans le volet Extension, sous Méthode d'extension, sélectionnez Écrire une extension avec l'IA.
  6. Dans le champ de prompt, saisissez une description en anglais simple des champs que vous souhaitez extraire.

  7. Cliquez sur Confirmer.

    Le système génère le code de l'extension et met à jour le volet Sortie UDM.

Affiner l'extension d'analyseur

Vous pouvez créer et affiner votre extension d'analyseur de manière itérative au cours de sessions de chat multitours. Lorsque vous envoyez une requête de suivi, l'IA applique vos nouvelles instructions en plus de l'extension générée précédemment. Les mappages et la logique conditionnelle existants des tours précédents sont automatiquement conservés, sauf si vous demandez explicitement de les remplacer ou de les supprimer.

  1. Dans le champ de prompt, saisissez une instruction complémentaire pour ajuster le code généré.
  2. Cliquez sur Confirmer.
  3. Après chaque prompt, prévisualisez le code d'extension généré, inspectez les exemples de sorties UDM, puis confirmez ou ajustez la logique.

L'exemple de workflow suivant montre comment l'affinement itératif crée une extension d'analyseur sur plusieurs tours :

  1. Tour 1 (extraction initiale) :
    • Prompt de l'utilisateur : "Extract source IP '198.51.100.0' to principal.ip and destination IP '198.51.100.1' to target.ip."
    • Résultat : l'IA génère une extension mappant principal.ip et target.ip.
  2. Tour 2 (mappage additif) :
    • Prompt de l'utilisateur : "Also map virtual system string 'vsys1' to observer.administrative_domain."
    • Résultat : l'IA met à jour l'extension pour mapper observer.administrative_domain tout en conservant les mappages d'adresses IP du tour 1.
  3. Tour 3 (affinement conditionnel) :
    • Prompt de l'utilisateur : "In addition, map action string 'allow' to security_result[0].action as ALLOW."
    • Résultat : l'IA intègre le mappage d'énumération de l'action conditionnelle en plus de toutes les extractions précédentes.

Valider l'extension d'analyseur

  1. Cliquez sur Valider.
  2. Examinez les métriques de validation une fois le processus terminé.

Accéder aux informations de référence

Utilisez les exemples suivants pour créer des requêtes précises pour les extensions d'analyseur.

Requêtes de journaux structurés

Pour les journaux structurés où les données sont organisées en clés, attributs ou balises XML nommés, spécifiez les noms ou les chemins des champs dans votre requête.

Exemple de journal structuré au format JSON
{
  "insertId": "u0mlpdesys",
  "logName": "projects/sample-project-id/logs/cloudaudit.googleapis.com%2Fdata_access",
  "protoPayload": {
    "authenticationInfo": {
      "principalEmail": "analyst@example-domain.com"
    },
    "methodName": "GenerateAccessToken",
    "requestMetadata": {
      "callerIp": "203.0.113.195",
      "callerSuppliedUserAgent": "google-cloud-sdk gcloud/392.0.0"
    },
    "resourceName": "projects/-/serviceAccounts/110649196922301550006",
    "serviceName": "iamcredentials.googleapis.com"
  }
}
Exemples de prompts pour les journaux structurés
Instruction de prompt Champ ou clé source Champ UDM cible
"Map principalEmail to principal.user.email_addresses." principalEmail principal.user.email_addresses
"Extract callerIp to principal.ip and methodName to metadata.product_event_type." callerIp, methodName principal.ip, metadata.product_event_type
"Map resourceName to target.resource.name and serviceName to target.application." resourceName, serviceName target.resource.name, target.application
"From XML tags, map /Event/System/Hostname to principal.hostname." /Event/System/Hostname principal.hostname

Requêtes de journaux non structurés

Pour les journaux non structurés, spécifiez des valeurs littérales directement à partir de l'exemple de journal, des références de position ou des étiquettes descriptives.

Exemple de message syslog non structuré
<14>Nov  9 18:52:45 198.51.100.1 1,2021/11/09 18:52:45,007051000184334,TRAFFIC,start,2561,2021/11/09 18:52:45,198.51.100.0,198.51.100.1,0.0.0.0,0.0.0.0,any allow,,,ping,vsys1,LAN,LAN,ethernet1/2,ethernet1/2,LFPpan,2021/11/09 18:52:45,9729,6,0,0,2048,0,0x100000,icmp,allow,444,444,0,6
Exemples de prompts pour les journaux non structurés
Instruction de prompt Exemple de valeur littérale ou de description Champ UDM cible
"Extract source IP '198.51.100.0' to principal.ip and destination IP '198.51.100.1' to target.ip." '198.51.100.0', '198.51.100.1' principal.ip, target.ip
"Extract the application string 'ping' from the log and map it to additional.fields['application']." 'ping' additional.fields["application"]
"Map rule name 'any allow' to security_result.rule_id." 'any allow' security_result[0].rule_id
"Extract sent bytes and received bytes into network.sent_bytes and network.received_bytes." Compteurs d'octets numériques dans le journal network.sent_bytes, network.received_bytes

Prompts de logique conditionnelle

Décrire la logique conditionnelle pour normaliser les valeurs de journaux bruts en énumérations UDM spécifiques.

  • Normalisation de l'énumération : "If the firewall action in the log is 'allow', set security_result.action to ALLOW; otherwise set security_result.action to BLOCK."
  • Mappage de champs conditionnel : "If the protocol is 'icmp', map the ICMP type and code into network.icmp.type and network.icmp.code."
  • Mappage d'état : "When the log status contains 'success' or '0', set security_result.severity to INFO; if it contains 'error', set it to ERROR."

Limites d'utilisation

Pour maintenir des performances et une disponibilité des ressources optimales, les fonctionnalités d'analyse de l'IA appliquent les quotas d'utilisation par défaut suivants :

  • Vous pouvez lancer jusqu'à 10 sessions de génération d'analyseurs personnalisés par IA ou d'extension d'analyseurs par IA par instance sur une période glissante de 24 heures. Pour les analyseurs personnalisés, chaque clic sur Générer l'analyseur pour un nouvel analyseur démarre une session.
  • Chaque session applique les limites d'interaction suivantes :
    • Pour la génération d'analyseurs personnalisés par IA, chaque session accepte jusqu'à six tours au total, ce qui inclut la génération initiale et jusqu'à cinq requêtes d'affinement.
    • Pour les extensions d'analyseur IA, chaque session accepte jusqu'à cinq messages au total, ce qui inclut votre requête initiale et les requêtes d'affinage suivantes.

Si vous atteignez la limite de tours ou de messages pour une session, vous pouvez envoyer ou enregistrer votre travail en cours, ou démarrer une nouvelle session (dans la limite du quota de sessions quotidien). Pour les analyseurs personnalisés, une fois que vous avez envoyé et activé l'analyseur, vous pouvez modifier son code manuellement comme n'importe quel autre analyseur personnalisé.

Étapes suivantes

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