Premiers pas : YARA-L 2.0 dans SecOps

Compatible avec :

YARA-L 2.0 est un langage de requête unique et très structuré qui alimente Google Security Operations pour toutes les recherches, tous les tableaux de bord et la détection des menaces basée sur des règles. Ce document vous aide à comprendre la structure de base de YARA-L et vous fournit des étapes pratiques pour l'utiliser, que vous soyez un analyste de sécurité à la recherche de menaces ou un ingénieur en détection qui crée une nouvelle logique robuste.

Avant de commencer

Comprendre la structure de YARA-L

Chaque requête YARA-L est segmentée en sections distinctes et nommées, qui dictent le comportement de la requête.

Cette structure permet l'analyse et la corrélation en plusieurs étapes.

Commande Action Facultatif | Obligatoire
meta Définit des métadonnées descriptives pour la règle, telles que l'auteur, la description et le niveau de gravité. Facultatif pour la recherche et les tableaux de bord. Requis uniquement pour les règles.
events Ce composant définit et filtre les événements. Déclare toutes les sources de données (principalement les événements) à prendre en compte et les filtre à l'aide des champs UDM. Obligatoire (logique de base de la requête) pour la recherche, les tableaux de bord et les règles.
match Regroupe les événements et vous permet de spécifier la période acceptée (par exemple, by 5m). Requis dans certains cas pour les recherches statistiques où une agrégation a lieu. Obligatoire pour les requêtes de corrélation multi-événements. La spécification de l'heure est obligatoire dans match pour les règles, et facultative pour la recherche et les tableaux de bord.
outcome Calcule les métriques essentielles et obtient des insights (par exemple, count(), avg()). Facultatif.
condition Définit la logique à respecter pour renvoyer des résultats (dans la recherche) ou déclencher une alerte (dans une règle). Évalue les critères de la variable de requête pour déterminer si un résultat s'applique (par exemple, $event >5). Facultatif dans la recherche et les tableaux de bord. Requis uniquement pour les règles.
dedup Supprime les événements en double en les regroupant en fonction de variables clés ou de chemins d'événements (par exemple, target.user.userid, target.ip, principal.hostname ou des variables telles que $host, $user). En savoir plus sur les variables d'événement Facultatif. Non disponible dans les règles.
order Trie les résultats définis par des champs spécifiques (par exemple, asc). Facultatif (ne s'applique que lorsque match est utilisé). Non disponible dans les règles.
limit Limite le nombre maximal d'événements renvoyés par la requête. Facultatif. Non disponible dans les règles.
select Spécifie la liste des champs UDM à inclure dans les résultats de la requête. Facultatif. Non disponible dans les règles.
unselect Spécifie la liste des champs UDM à exclure des résultats de la requête. Facultatif. Non disponible dans les règles.

Disponibilité des sources de données YARA-L

YARA-L a accès à différentes sources de données, selon l'endroit où vous vous trouvez sur la plate-forme. Les événements, les entités (ECG) et les tableaux de données sont entièrement disponibles dans la recherche, les tableaux de bord et les règles.

Le tableau suivant répertorie les fonctionnalités disponibles dans YARA-L :

Fonctionnalité Disponible dans
Demandes et historique des demandes Tableaux de bord
Tables de données Recherche, tableaux de bord, règles
Entités (ECG) Recherche, tableaux de bord, règles
Métriques d'ingestion Tableaux de bord
Correspondances IoC Tableaux de bord
Détections de règles Tableaux de bord, règles
Ensembles de règles Tableaux de bord
Événements Recherche, tableaux de bord, règles
Métriques UEBA Recherche, tableaux de bord

Dans Google SecOps, toutes les données sont recherchées à l'aide de deux méthodes principales en fonction de vos objectifs : la recherche par filtre et la recherche statistique (agrégations).

La méthode de recherche de filtres vous permet d'isoler des événements spécifiques du flux de télémétrie plus large, sans la surcharge de l'agrégation statistique. Cette méthode utilise des critères pour réduire d'énormes volumes de données de sécurité (telles que les journaux ou le trafic réseau) en un ensemble de résultats ciblés. La logique ne vous oblige à spécifier des événements que dans la section events.

Pour créer votre première recherche de filtre YARA-L, suivez ces étapes pour rechercher les utilisateurs dont la connexion a échoué :

  1. Dans Google SecOps, accédez à la page Recherche.
  2. Filtrez les événements de connexion :
    metadata.event_type = "USER_LOGIN"

    Conseil : Vous pouvez omettre l'en-tête de section events: dans vos recherches. Par défaut, la syntaxe de recherche implique cette section.

  3. Ajoutez des actions event pour les échecs de connexion des utilisateurs qui ne disposent pas d'un userid vide. 
    metadata.event_type = "USER_LOGIN"
security_result.action = "FAIL"
principal.user.userid != ""
  4. Exécutez cette recherche pour afficher les résultats.

Utiliser des variables d'espace réservé

Utilisez des variables d'espace réservé pour extraire des valeurs spécifiques de vos événements, comme un nom d'utilisateur ou une adresse IP. Ces variables servent d'ancres temporaires qui vous permettent de comparer des données entre différents événements ou d'afficher ces valeurs dans votre résultat final.

Vous pouvez appliquer des variables d'espace réservé pour effectuer les opérations suivantes :

  • Données de pont : utilisez des espaces réservés, tels que $userid ou $ip, pour trouver des correspondances entre différentes variables d'événement (par exemple, vous pouvez utiliser $userid pour associer l'identifiant utilisateur aux événements de connexion et de déconnexion).
  • Regrouper les résultats : dans la section match, utilisez des variables d'espace réservé pour définir la fenêtre de sortie de votre requête, par exemple match: $userid over 1h.
  • Créer des résultats : utilisez des espaces réservés pour capturer et afficher des points de données spécifiques dans le résultat de votre requête.

Par exemple, si vous attribuez $user = principal.user.userid, la variable $user contient désormais la valeur spécifique extraite de l'événement. Vous utilisez ensuite $user dans la section match pour regrouper toutes les activités liées à cet utilisateur spécifique.

La méthode de recherche statistique vous aide à obtenir des insights, des tendances ou des anomalies en effectuant des calculs sur des ensembles d'événements. Au lieu de renvoyer une liste de journaux individuels, il fournit des récapitulatifs agrégés de vos données. La logique utilise la section match (pour le regroupement) et la section outcome (pour les calculs). La section outcome est compatible avec les fonctions d'agrégation, telles que count(), sum(), avg(), max(), min() et stddev().

L'exemple suivant utilise la logique de requête suivante :

  • events : filtre les données brutes pour les tentatives de connexion ayant échoué.
  • match : définit les événements de regroupement (par userid).
  • outcome : effectue l'agrégation statistique (nombre d'événements par utilisateur).

Exemple : agréger l'activité de connexion ayant échoué à l'aide des fonctions outcome

L'exemple suivant utilise les fonctions d'agrégation de la section outcome (comme count() ou sum()) pour récapituler l'activité des échecs de connexion.

  1. Utilisez la section match pour regrouper les événements d'échec de connexion par userid :

    metadata.event_type = "USER_LOGIN"
security_result.action = "FAIL"
principal.user.userid != ""

match:
  principal.user.userid

  2. Utilisez le count des échecs de connexion pour chaque utilisateur ($failed_login_count), défini par la variable outcome :

    metadata.event_type = "USER_LOGIN"
security_result.action = "FAIL"
principal.user.userid != ""

match:
  principal.$user.userid

outcome:
  $failed_login_count = count(metadata.id)

  3. Exécutez cette recherche pour afficher les résultats.

  4. Facultatif : Ajoutez un élément temporel à la section match (dans ce cas, day). Ensuite, mettez à jour la variable outcome pour la rendre plus explicite ($daily_failed_login_count) :

    metadata.event_type = "USER_LOGIN"
security_result.action = "FAIL"
principal.user.userid != ""
$user =principal.user.userid

match:
  principal.$user.userid by day

outcome:
  $daily_failed_login_count = count(metadata.id)

Créer un widget de tableau de bord à partir de votre recherche

Vous pouvez créer un widget de tableau de bord à partir de recherches agrégées, comme indiqué dans l'exemple de création de votre première recherche.

Une fois la recherche validée, vous pouvez l'enregistrer en tant que widget et l'ajouter à votre tableau de bord :

  1. Lorsque les résultats s'affichent, cliquez sur l'onglet Visualiser > Ajouter au tableau de bord.
  2. Configurez le widget :
    1. Nommez le widget (par exemple, "Daily Failed Login").
    2. Sélectionnez une période.
    3. Choisissez de l'ajouter à un tableau de bord existant ou nouveau.
    4. Cliquez sur Ajouter.
  3. Facultatif : Créez des requêtes directement dans vos tableaux de bord. Vous pouvez également copier des tableaux de bord sélectionnés et modifier les requêtes qu'ils contiennent pour vous aider à démarrer.
  4. Facultatif : Vous pouvez créer un tableau de bord personnalisé et y ajouter des widgets à l'aide de YARA-L. Pour en savoir plus, consultez Créer un tableau de bord personnalisé.

Configurer un tableau de bord

Lorsque vous créez un tableau de bord, la section events est un point de départ obligatoire. Vous pouvez ensuite utiliser match (pour regrouper les résultats) ou outcome (pour calculer les sorties et les agrégations).

Par exemple, vous pouvez créer un tableau de bord avec des sections events et match, où la gravité ($severity) des détections est regroupée dans des buckets by hour.

Exemple : Agréger les séries temporelles par gravité

Vous pouvez créer un tableau de bord à l'aide des sections events et match pour afficher la gravité ($severity) des détections regroupées dans des buckets hour :

detection.detection.severity != "UNKNOWN_SEVERITY"
$severity = detection.detection.severity

match:
  $severity by hour

Exemple : agrégation de l'impact critique total

De même, vous pouvez créer un tableau de bord à l'aide des sections events et outcome pour suivre les détections de gravité élevée :

detection.detection.severity = "CRITICAL"
$severity = detection.detection.severity

outcome:
  $detection_count = count_distinct($severity)

Exemple : Visualiser le volume de détections par niveau de gravité au fil du temps

Dans l'exemple suivant, vous pouvez compter les détections critiques et spécifier la plage de temps dans la console. Dans de nombreux cas, vous utiliserez les sections match et outcome lorsque vous créerez une visualisation dans un tableau de bord :

detection.detection.severity != "UNKNOWN_SEVERITY"
$severity = detection.detection.severity

match:
  $severity by hour

outcome:
  $detection_count = count_distinct(detection.id)

Exemple : Calculer la fréquence de connexion des utilisateurs

L'exemple suivant se concentre sur le calcul de login_count pour des utilisateurs spécifiques à l'aide des sections match et outcome :

events:
  metadata.event_type = "USER_LOGIN"

match:
  target.user.userid

outcome:
  $login_count = count(metadata.id)

Créer une règle

Une règle doit comporter les sections suivantes :

  • meta : contient le nom de la règle et des informations descriptives.
  • events : définit vos sources de données et vos filtres à l'aide de variables d'événement.
  • condition : spécifie les variables d'événement qui doivent exister pour que la règle se déclenche.

Définir et utiliser des variables d'événement

Les variables d'événement agissent comme un conteneur logique, regroupant vos filtres afin que vous puissiez faire référence à cette activité spécifique dans votre recherche, votre règle ou votre tableau de bord.

Lorsque vous définissez une logique dans la section events, vous pouvez utiliser des variables d'événement (telles que $e) pour représenter un événement spécifique (ou un groupe d'événements) correspondant à vos critères.

Exemple : Définir et filtrer des variables d'événement

Pour définir une variable d'événement (par exemple, $e), utilisez un préfixe dans la section events de votre requête. Cela déclare que ces événements doivent être représentés par la variable. Par exemple, l'expression $e.principal.hostname = "dev" évalue chaque événement pour déterminer si le nom d'hôte correspond exactement.

$e.principal.hostname = "dev"
$e.metadata.event_type = "USER_LOGIN"

Vous pouvez ensuite utiliser cette variable dans d'autres sections de la requête pour faire référence à ce groupe d'événements spécifique (dans les sections match, outcome et condition) et à leurs champs de données.

Organiser la structure et la syntaxe des règles

Utilisez la structure et la syntaxe de règle suivantes pour définir vos variables, la logique de regroupement et les seuils de déclenchement :

Élément Description Exemple
Structure des règles Encapsule votre requête dans un bloc rule et attribue un nom unique pour identifier la détection. rule DailyFailedLoginAttempts { }
Section meta Obligatoire. Inclut des métadonnées descriptives (telles que "auteur", "description" et "gravité") pour améliorer la gestion des règles et fournir du contexte à votre équipe. Bonne pratique recommandée pour la gestion des règles. author = "Alex"
severity = "Medium"
Variable d'événement Dans une requête de règles, chaque champ de la section events est précédé d'une variable d'événement (comme $e) pour représenter un événement spécifique (ou un groupe d'événements) correspondant à vos critères. Ils agissent comme des groupements logiques de filtres.

 Dans l'exemple Convertir votre recherche en règle YARA-L, $e représente tous les échecs de connexion des utilisateurs.		 $e.metadata.event_type = "USER_LOGIN"
Variable d'espace réservé Attribue un événement à un nom commun que vous pourrez référencer ultérieurement dans la requête. Pour en savoir plus, consultez Utiliser des variables d'espace réservé. $userid = $e.principal.user.userid
Section match Définit vos regroupements et spécifie une période acceptée. Dans l'exemple Convertir votre recherche en règle YARA-L, le regroupement match: $userid over day regroupe correctement les événements par ID utilisateur au cours de chaque période de 24 heures (1d).

Lorsque vous écrivez une règle, vous devez spécifier une période compatible pour définir votre période d'analyse. Vous pouvez implémenter une fenêtre hop, sliding ou tumbling en fonction des exigences de votre logique. L'utilisation explicite de l'opérateur over crée une fenêtre de saut. 		$userid over 1d
Section outcome Effectue des agrégations statistiques ou capture des variables spécifiques pour rendre les alertes plus informatives.

Utilisez la fonction count() sur $e.metadata.id pour agréger les événements dans chaque groupe match. Vous pouvez également attribuer des variables, telles que $userid, pour capturer des champs UDM spécifiques et fournir plus de contexte dans le résultat de la détection.		 $failed_count = count($e.metadata.id)
Section condition Obligatoire pour qu'une règle génère une détection.

Définit votre seuil de détection dans la section condition. Par exemple, l'utilisation de #e > 5 nécessite que le nombre d'événements dépasse cinq (5) pour déclencher une alerte. Même si vous n'effectuez pas de calculs, vous avez toujours besoin d'une section condition et vous devez indiquer l'existence de la variable d'événement (par exemple, #e).

Analysez la référence de votre environnement pour définir des seuils qui détectent les activités suspectes tout en minimisant les faux positifs. Même si vous n'effectuez pas de calculs, vous avez toujours besoin d'une section condition. Il vous suffit d'indiquer l'existence de la variable d'événement, par exemple #e.		 #e > 5 ou $e

Pour comprendre le fonctionnement de cette structure, consultez l'exemple suivant.

Exemple : Détecter la force brute (plusieurs échecs de connexion)

L'exemple suivant détecte plusieurs tentatives de connexion ayant échoué pour un même utilisateur au cours d'une période de 24 heures :

rule DailyFailedLoginAttempts {
  meta:
    author = "Alex"
    description = "Detects multiple failed login attempts for a single user within a day."
    severity = "Medium"

  events:
    $e.metadata.event_type = "USER_LOGIN"
    $e.security_result.action = "FAIL"
    $e.principal.user.userid != ""
    $userid = $e.principal.user.userid

  match:
    $userid over 1d

  outcome:
    $daily_failed_login_count = count($e.metadata.id)

  condition:
    $daily_failed_login_count > 5
}

Pour convertir une requête de recherche finalisée en règle fiable permettant de générer des détections, vous devez généralement suivre les étapes suivantes :

  1. Dans Google SecOps, accédez à l'éditeur de règles.
  2. Créez une règle.
  3. Collez la requête de recherche et modifiez-la pour qu'elle corresponde à la structure de la règle, y compris :
    • Section meta : définit la règle de métadonnées, y compris le nom, l'auteur et le niveau de gravité de la règle.
    • Section event : obligatoire. Contrairement à la recherche, vous devez avoir un en-tête de section event nommé.
    • Variables d'événement : déclare et référence des événements spécifiques (ou des groupes d'événements) dans votre logique.
    • Section match avec périodes acceptées : spécifie vos clés de regroupement et définit les paramètres temporels (par exemple, 5m ou 1d). Remarque : Si vous utilisez une section match dans les règles, vous devez ajouter une période.
    • Section condition : définit la logique ou le seuil final à respecter pour déclencher une règle.

Avancé : créer une règle multi-événements

Vous utilisez une règle multi-événements pour corréler différents types d'activité qui se produisent au cours d'une période spécifique. Au lieu d'examiner un seul événement, vous pouvez connecter plusieurs événements (par exemple, un utilisateur se connecte, puis télécharge immédiatement un fichier inhabituel) pour identifier les menaces complexes.

Une règle multi-événements nécessite les sections suivantes :

  • meta : contient le nom de la règle et des informations descriptives.
  • events : définit vos sources de données et vos filtres à l'aide de variables d'événement.
  • match : définit le délai et la variable d'espace réservé utilisés pour relier vos événements.
  • outcome Capture le contexte supplémentaire de l'alerte. Les règles multi-événements nécessitent une fonction d'agrégation.
  • condition : spécifie les variables d'événement qui doivent exister pour que la règle se déclenche.

Pour créer une règle multi-événements :

  1. Définissez vos variables d'événement : dans la section "Événements", définissez $e1 pour capturer les événements "PROCESS_LAUNCH" et $e2 pour capturer les hachages de fichiers malveillants spécifiques.
  2. Corréler avec des espaces réservés : utilisez la variable d'espace réservé $user pour associer ces deux flux d'événements distincts à l'aide d'un ID utilisateur principal commun (par exemple, $user = $e1.principal.user.userid and $user = $e2.principal.user.userid).
  3. Regroupez la correspondance : dans la section match, vous spécifiez que ces événements doivent se produire pour le même $user dans un laps de temps défini, par exemple cinq minutes (5m).

Exemple : Créer une règle multi-événements

Dans l'exemple suivant, $e1 représente un événement PROCESS_LAUNCH et $e2 représente un événement avec un hachage malveillant spécifique. La variable d'espace réservé $user met en corrélation ces événements avec le même ID utilisateur principal.

rule MultiEventExample {
  meta:
    author = "Alex"
    description = "Detects a bad hash execution or a process launch from a specific IP for the same user."

  events:
    $e1.principal.ip = "1.1.1.1"
    $e1.metadata.event_type = "PROCESS_LAUNCH"
    $e2.target.file.sha256 = "badhash..."
    $user = $e1.principal.user.userid
    $user = $e2.principal.user.userid

  match:
    $user over 5m

  condition:
    $e1 or $e2
}

Les composants de règle suivants décrivent la logique utilisée dans l'exemple :

  • Variables d'événement : deux variables d'événement ont été définies, $e1 et $e2. Utilisez la variable d'espace réservé $user pour joindre ces événements au champ userid commun.
  • Section match : une section match a été incluse pour cette règle multi-événements afin de regrouper les événements par utilisateur et de spécifier une période de temps de saut de cinq minutes (5m) pour corréler les événements.
  • Section condition : définition de la logique de déclenchement de l'alerte. Cet exemple déclenche une alerte si le premier ou le deuxième événement existe.

Utiliser d'autres outils pour créer votre requête

Ces outils sont essentiels pour écrire et valider des règles YARA-L, et pour accélérer l'adoption de ce langage :

  • Outil de recherche UDM : recherchez et consultez rapidement les noms, les définitions et les types de données des champs UDM directement dans l'UI. Si l'ID du champ est inconnu, vérifiez d'abord cette référence.
  • Recherche en langage naturel vers YARA-L : dans la barre de recherche, saisissez des descriptions pour rédiger votre requête initiale, ou obtenir ou traduire les suggestions YARA-L correspondantes.
  • Traducteur SPL → YARA-L (outil Labs) : si vous migrez depuis des plates-formes concurrentes, utilisez cet outil (disponible dans la section Labs) pour convertir les anciennes requêtes SPL Splunk en YARA-L. Cela génère un point de départ structuré, ce qui accélère votre migration et affine votre logique de détection. Pour utiliser l'outil Labs dans Google SecOps, accédez à yourinstancename.chronicle.security/labs.

Étapes suivantes

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