Syntaxe de la section "Events" (Événements)

Compatible avec :

Dans une règle, la section events doit immédiatement suivre la section meta. Elle définit les événements que la requête doit examiner et les attributs spécifiques que ces événements doivent posséder pour être considérés comme pertinents pour une détection potentielle.

La section events est obligatoire pour les règles, mais facultative pour la recherche et les tableaux de bord.

Utilisez la section events pour lister les prédicats spécifiant les éléments suivants :

  • Déclarations de variables
  • Filtres de variables d'événement
  • Jointures de variables d'événement

Section "Définir des événements"

Les règles et les requêtes qui ne sont axées que sur un seul type d'événement peuvent inclure une seule variable d'événement, par exemple :

events:
  $e.metadata.event_type = "USER_LOGIN" // 'e' is the common convention for a single event

Les règles et les requêtes qui nécessitent une corrélation entre deux types d'événements distincts ou plus (par exemple, une connexion utilisateur suivie d'une modification de fichier) nécessitent une variable pour chaque type d'événement :

events:
  $login.metadata.event_type = "USER_LOGIN" // Event 1: User Login
  $file_op.metadata.event_type = "FILE_MODIFICATION" // Event 2: File Modification

Une fois qu'une variable d'événement est déclarée, vous l'utilisez comme préfixe pour accéder à des champs spécifiques de ce type d'événement. Par exemple, la section event suivante filtre les événements d'échec de connexion provenant d'Okta :

events:
   $e.metadata.vendor_name = "Okta"
   $e.metadata.event_type = "USER_LOGIN"
   $e.security_result.action = "FAIL"

Déclarations de variables

Pour les déclarations de variables, utilisez la syntaxe suivante :

  • <EVENT_FIELD> = <VAR>
  • <VAR> = <EVENT_FIELD>

Les deux sont équivalents, comme le montrent les exemples suivants :

  • $e.source.hostname = $hostname
  • $userid = $e.principal.user.userid

Cette déclaration indique que cette variable représente le champ spécifié pour la variable d'événement. Lorsque le champ d'événement est un champ répété, la variable match peut représenter n'importe quelle valeur du tableau. Vous pouvez également attribuer plusieurs champs d'événement à une seule variable de correspondance ou d'espace réservé. C'est ce qu'on appelle une condition de jointure transitive.

Par exemple, cette agrégation :

  • $e1.source.ip = $ip
  • $e2.target.ip = $ip

Équivaut à :

  • $e1.source.ip = $ip
  • $e1.source.ip = $e2.target.ip

Lorsqu'une variable est utilisée, elle doit être déclarée. Si une variable est utilisée sans déclaration, une erreur de compilation est déclenchée.

Pour en savoir plus sur les variables, consultez Expressions, opérateurs et autres constructions.

Filtres de variables d'événement

Une expression booléenne qui agit sur une seule variable d'événement est considérée comme un filtre.

Jointures de variables d'événement

Toutes les variables d'événement utilisées dans une règle doivent être associées à toutes les autres variables d'événement de l'une des manières suivantes :

  • Directement via une comparaison d'égalité entre les champs d'événement des deux variables d'événement jointes, par exemple : $e1.field = $e2.field. L'expression ne doit pas inclure d'opérations arithmétiques (telles que $\text{+, -, *, /}$).

  • Indirectement, par le biais d'une jointure transitive n'impliquant qu'un champ d'événement (voir Déclaration de variable pour la définition de "jointure transitive"). L'expression ne doit pas inclure d'arithmétique.

Par exemple, en supposant que $e1, $e2 et $e3 sont utilisés dans la règle, les sections events suivantes sont valides :

events:
  $e1.principal.hostname = $e2.src.hostname // $e1 joins with $e2
  $e2.principal.ip = $e3.src.ip // $e2 joins with $e3

events:
  // $e1 joins with $e2 using function to event comparison
  re.capture($e1.src.hostname, ".*") = $e2.target.hostname

events:
  // $e1 joins with $e2 using an `or` expression
  $e1.principal.hostname = $e2.src.hostname
  or $e1.principal.hostname = $e2.target.hostname
  or $e1.principal.hostname = $e2.principal.hostname

events:
  // all of $e1, $e2 and $e3 are transitively joined using the placeholder variable $ip
  $e1.src.ip = $ip
  $e2.target.ip = $ip
  $e3.about.ip = $ip

events:
  // $e1 and $e2 are transitively joined using function to event comparison
  re.capture($e2.principal.application, ".*") = $app
  $e1.principal.hostname = $app

Toutefois, les exemples suivants montrent des sections events non valides.

events:
  // Event to arithmetic comparison is an invalid join condition for $e1 and $e2.
  $e1.principal.port = $e2.src.port + 1

events:
  $e1.src.ip = $ip
  $e2.target.ip = $ip
  $e3.about.ip = "192.1.2.0" //$e3 is not joined with $e1 or $e2.

events:
  $e1.src.port = $port

  // Arithmetic to placeholder comparison is an invalid transitive join condition.
  $e2.principal.port + 800 = $port

Étapes suivantes

Informations supplémentaires

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