Syntaxe de la section "Conditions"

Compatible avec :

Ce document explique comment utiliser la section condition d'une requête YARA-L. La section condition est utilisée dans la recherche et les tableaux de bord. Elle est requise pour les règles et contient une logique permettant de filtrer davantage les résultats. Lorsqu'il est utilisé dans une requête de recherche ou de tableau de bord, il n'affiche que les résultats qui répondent aux conditions. Lorsqu'elles sont utilisées dans une règle de détection, les conditions doivent être remplies pour déclencher une alerte.

Dans la section condition, vous pouvez utiliser des opérateurs booléens, des opérateurs de comparaison et les résultats des variables outcome pour déterminer si la requête doit être déclenchée.

Définir la section condition

Définissez les expressions de condition pour les événements et les variables d'espace réservé dans la section condition. Vous pouvez également spécifier une condition de correspondance pour les événements et les espaces réservés définis dans la section events, et utiliser éventuellement le mot clé and pour spécifier une condition de correspondance à l'aide des variables de résultat définies dans la section outcome (voir Syntaxe de la section "Résultats").

Vous pouvez joindre les expressions à l'aide des mots clés and ou or :

  • Utilisez and entre les conditions.

  • Utilisez or uniquement lorsque la requête contient une seule variable d'événement.

Utilisez le caractère # dans la section condition avant tout nom d'événement ou de variable d'espace réservé pour représenter le nombre d'événements ou de valeurs distincts qui remplissent toutes les conditions de la section events. Exemple :

#c > 1 signifie que la variable c doit se produire plus d'une fois.

Utilisez le caractère $ dans la section condition avant le nom de toute variable de résultat pour représenter la valeur de ce résultat. S'il est utilisé avant un nom de variable d'événement ou d'espace réservé (par exemple, $event), il représente #event > 0.

Cet exemple de règle renvoie une détection lorsqu'il y a plus de cinq tentatives de connexion infructueuses (comme défini dans la section condition) pour chaque utilisateur dans une fenêtre de 10 minutes (comme défini dans la section match) :

rule failed_logins
{
  meta:
   author = "Security Team"
   description = "Detects multiple failed user logins within 10-minute windows."
   severity = "HIGH"

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

  match:
   $user over 10m

  outcome:
   $failed_login_count = count($e.metadata.id)
   $first_fail_time = min($e.metadata.event_timestamp.seconds)

  condition:
    #e >= 5
}

Conditions limitées et illimitées

Vous pouvez utiliser des conditions limitées ou illimitées dans une requête :

  • Les conditions limitées forcent l'existence de la variable d'événement associée, ce qui signifie qu'au moins une occurrence de l'événement doit apparaître dans la détection. Voici des exemples de conditions limitées :

    $var // equivalent to #var > 0

    #var > n // where n >= 0

    #var >= m // where m > 0

  • Les conditions non liées peuvent être utilisées pour détecter l'absence d'un événement sur une période donnée (par exemple, un événement de menace sans événement d'atténuation dans un délai de 10 minutes). Les conditions non liées permettent à la variable d'événement associée de ne pas exister (requêtes de non-existence). Cela signifie qu'il est possible qu'aucune occurrence de l'événement n'apparaisse dans une détection et que toute référence à des champs sur la variable d'événement génère une valeur nulle.

    Voici des exemples de conditions non liées :

    !$var // equivalent to #var = 0

    #var >= 0

    #var < n // where n > 0

    #var <= m // where m >= 0

Exigences concernant les requêtes d'inexistence

Pour qu'une requête d'inexistence soit compilée, elle doit répondre aux exigences suivantes :

  • Au moins un événement UDM doit avoir une condition limitée (c'est-à-dire qu'au moins un événement UDM doit exister).
  • Si un espace réservé comporte une condition illimitée, il doit être associé à au moins un événement UDM limité.
  • Si une entité est associée à une condition illimitée, elle doit être associée à au moins un événement UDM limité.

Exemple : requête d'inexistence

Prenons l'exemple de requête suivant, dont la section de condition a été supprimée :

rule NonexistenceExample {
  meta:
      author = "Google Security"
      description = "Example: non-existence query."
  events:
      $u1.metadata.event_type = "NETWORK_CONNECTION" // $u1 is a UDM event.
      $u2.metadata.event_type = "NETWORK_CONNECTION" // $u2 is a UDM event.
      $e1.graph.metadata.entity_type = "FILE"        // $e1 is an entity.
      $e2.graph.metadata.entity_type = "FILE"        // $e2 is an entity.

      $user = $u1.principal.user.userid // Match variable is required for multi-event query.

      // Placeholder Associations:
      //   u1        u2
      //   |  \    /
      // port   ip
      //   |       \
      //   e1        e2
      $u1.target.port = $port
      $e1.graph.entity.port = $port
      $u1.principal.ip = $ip
      $u2.target.ip = $ip
      $e2.graph.entity.ip = $ip

      // UDM-Entity Associations:
      // u1 - u2
      // |  \  |
      // e1   e2
      $u1.metadata.event_type = $u2.metadata.event_type
      $e1.graph.entity.hostname = $u1.principal.hostname
      $e2.graph.entity.hostname = $u1.target.hostname
      $e2.graph.entity.hostname = $u2.principal.hostname

  match:
    $user over 5m

  condition:
      //Add valid condition
}

Section de conditions valides

Voici des exemples valides pour la section "Condition" :

  • $u1 and !$u2 and $e1 and $e2
    • Tous les événements et entités UDM sont présents dans la section "Condition".
    • Au moins un événement UDM est limité.
  • $u1 and !$u2 and $e1 and !$e2
    • $e2est illimité et autorisé, car il est associé à $u1, qui est limité. Si $e2 n'était pas associé à $u1, cela ne serait pas valide.
  • #port > 50 and #ip = 0
    • Aucun événement ni aucune entité UDM n'est présent dans la section "Condition". Toutefois, les espaces réservés présents couvrent tous les événements et entités UDM.
    • $ip est attribué à $u1 et $u2, et #ip = 0 est une condition non limitée. Toutefois, les conditions limitées sont plus strictes que les conditions non limitées. Étant donné que $port est attribué à $u1 et que #port > 50 est une condition limitée, $u1 reste limité.

Section de condition non valide

Voici des exemples non valides pour la section "Condition" :

  • $u1 and $e1
    • Chaque événement et entité UDM figurant dans la section events doit figurer dans la section condition (ou avoir un espace réservé qui lui est attribué et qui apparaît dans la section condition).
  • $u1, $u2, $e1, $u2, #port > 50
    • Les virgules ne sont pas autorisées comme séparateurs de conditions.
  • !$u1 and !$u2 and $e1 and $e2
    • Ne respecte pas la première exigence, à savoir qu'au moins un événement UDM doit être limité.
  • ($u1 or #port < 50) and $u2 and $e1 and $e2
    • Le mot clé or n'est pas compatible avec les conditions non limitées.
  • ($u1 or $u2) and $e1 and $e2
    • Le mot clé or n'est pas compatible entre différentes variables d'événement.
  • not $u1 and $u2 and $e1 and $e2
    • Le mot clé not n'est pas autorisé pour les conditions d'événement et d'espace réservé.
  • #port < 50 and #ip = 0
    • Bien que les espaces réservés fassent référence à tous les événements et entités UDM, chaque condition associée est illimitée. Cela signifie qu'aucun des événements UDM n'est limité, ce qui entraîne l'échec de la compilation de la règle.

Conditions de résultat

Vous pouvez inclure des conditions pour les variables de résultat dans la section condition, jointes avec le mot clé and ou or, ou précédées du mot clé not.

Les conditions de résultat sont spécifiées différemment selon le type de variable de résultat :

  • integer : comparer à un littéral entier avec les opérateurs =, >, >=, <, <=, != Par exemple : $risk_score > 10

  • float : comparer à un littéral float avec les opérateurs =, >, >=, <, <=, != Par exemple : $risk_score <= 5.5

  • string : comparer à un littéral de chaîne avec = ou != Par exemple : $severity = "HIGH"

  • Liste d'entiers ou de tableaux : spécifiez la condition à l'aide de la fonction arrays.contains. Par exemple : arrays.contains($event_ids, "id_1234")

Si vous spécifiez une condition de résultat dans une requête comportant une section match, la requête est classée comme requête multi-événements pour le quota de requêtes. Pour en savoir plus sur les classifications d'événements uniques et multiples, consultez la syntaxe de correspondance.

Restrictions

  • Évitez d'utiliser une variable match dans la section condition. Il s'agit d'une erreur sémantique, car les événements sont regroupés par valeur de la variable match.

  • Évitez de spécifier uniquement des conditions non liées sur toutes les variables event auxquelles une variable match est attribuée. Il s'agit d'une erreur sémantique. Pour qu'une valeur de variable match soit renvoyée, au moins un événement doit exister et contenir la valeur.

  • Si vous utilisez une fenêtre glissante, la variable d'événement pivot doit être impliquée dans au moins une condition limitée.

Étape suivante

Informations supplémentaires

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