Fonctions de métriques pour les règles d'analyse des risques

Ce document décrit les principaux éléments des nouvelles fonctionnalités de syntaxe YARA-L pour Risk Analytics. Pour en savoir plus sur YARA-L, consultez la syntaxe du langage YARA-L 2.0.

Fonctions de métrique YARA-L

Google Security Operations est compatible avec un certain nombre de fonctions de métriques, qui peuvent agréger de grandes quantités de données historiques.

La fonction de métrique ne peut être utilisée que dans la section "Résultat". Tous les exemples d'appels de fonction supposent une utilisation dans une règle multi-événements.

Toutes les règles qui utilisent la fonction de métrique sont automatiquement classées comme règles multi-événements, même si elles ne comportent pas de section de correspondance et n'utilisent qu'une seule variable d'événement. Cela signifie qu'elles seront comptabilisées dans le quota de règles multi-événements.

Paramètres de fonction de métrique

Les fonctions de métriques peuvent être utilisées pour les règles qui effectuent des analyses comportementales des entités.

Par exemple, la règle suivante indique le nombre maximal d'octets quotidiens qu'une adresse IP spécifique a envoyés au cours du mois dernier. L'adresse IP spécifique est représentée par une variable d'espace réservé, $ip dans cet exemple. Pour en savoir plus sur les variables d'espace réservé, consultez Déclarations de variables.

$max_bytes_per_day = max(metrics.network_bytes_outbound(
    period:1d, window:30d,
    metric:value_sum,
    agg:max,
    principal.asset.ip:$ip
))

En raison du grand nombre d'arguments utilisés dans ces fonctions, elles utilisent des paramètres nommés, qui peuvent être spécifiés dans n'importe quel ordre. Les paramètres sont les suivants :

Période

Durée pendant laquelle les événements de journaux individuels sont combinés dans une même observation. Les seules valeurs autorisées sont 1h et 1d.

Window

Durée pendant laquelle les observations individuelles sont agrégées dans une même valeur, par exemple la moyenne et le maximum. Les valeurs autorisées pour window dépendent de la période de la métrique. Le mappage valide est le suivant :

period:1h : window:today

period:1d : window:30d

Par exemple, la règle suivante indique le nombre maximal de tentatives d'authentification ayant échoué pour un utilisateur spécifique (Alice) au cours d'une journée donnée, au cours des 30 derniers jours :

$user = "alice"
$max_fail = max(metrics.auth_attempts_fail(
    period:1d, window:30d,
        metric:event_count_sum,
        agg:max,
        target.user.userid:$user
))

Une combinaison d'une métrique horaire et d'une métrique quotidienne peut être utilisée pour les types de détection first-seen. Par exemple, la règle suivante vous indique si un utilisateur s'est connecté à cette application pour la première fois :

events:
    $e.metadata.event_type = "USER_LOGIN"
    $e.security_result.action = "ALLOW"
    $userid = $e.target.user.userid
    $app = $e.target.application
match:
    // find events from now - 4h ago, which is the recommended look-back period
    $userid, $app over 4h
outcome:
    // check hourly analytics until daily analytics are available
    $first_seen_today = max(metrics.auth_attempts_success(
        period:1h, window:today, metric:first_seen, agg:max,
        target.user.userid:$userid, target.application:$app))
    $first_seen_monthly = max(metrics.auth_attempts_success(
        period:1d, window:30d, metric:first_seen, agg:max,
        target.user.userid:$userid, target.application:$app))
condition:
    $e and ($first_seen_today = 0) and ($first_seen_monthly = 0)

Métrique

Dans chaque période, chaque observation possède un certain nombre de métriques qui lui est associé. Vous devez en sélectionner une pour l'agrégation sur l'intégralité de la fenêtre. Cinq types de metric sont acceptés :

event_count_sum : nombre d'événements de journaux uniques au cours de chaque période.

first_seen : code temporel de la première occurrence d'un événement de journal correspondant dans chaque période.

last_seen : horodatage de la dernière occurrence d'un événement de journal correspondant dans chaque période.

value_sum : représente la somme du nombre d'octets dans tous les événements de journaux combinés au cours de la période. Vous ne pouvez utiliser cette valeur que pour une fonction de métrique dont le nom contient bytes.

num_unique_filter_values : métrique qui n'est pas précalculée par Google SecOps, mais qui peut l'être lors de l'exécution d'une règle. Pour en savoir plus et connaître les exigences, consultez Métriques "Nombre unique".

Agg

Agrégation appliquée à la métrique. Les agrégations sont appliquées sur l'intégralité de la fenêtre (par exemple, la valeur quotidienne la plus élevée au cours des 30 derniers jours). Les valeurs autorisées sont les suivantes :

avg : valeur moyenne par période. Il s'agit d'une moyenne statistique qui n'inclut pas les valeurs nulles.

max : valeur la plus élevée par période.

min : la plus petite valeur par période.

num_metric_periods : nombre de périodes au cours de la période où la valeur de la métrique était non nulle.

stddev : écart type de la valeur par période. Il s'agit d'un écart-type statistique qui n'inclut pas les valeurs nulles.

sum : somme de chaque valeur par période, sur l'ensemble de la période.

Par exemple, la règle suivante indique le nombre moyen de tentatives d'authentification ayant échoué pour un utilisateur spécifique (Alice) au cours des 30 derniers jours :

$user = "alice"
$avg_fail = max(metrics.auth_attempts_fail(
        period:1d, window:30d,
        metric:event_count_sum,
        agg:avg,
        target.user.userid:$user
))

La règle suivante indique le nombre d'authentifications réussies d'un utilisateur spécifique au cours des 30 derniers jours :

$total_success = max(metrics.auth_attempts_success(
        period:1d, window:30d,
        metric:event_count_sum,
        agg:sum,
        target.user.userid:$user
))

La règle suivante vous indique si un utilisateur spécifique s'est connecté au moins une fois au cours des 30 derniers jours :

$days_success = max(metrics.auth_attempts_success(
        period:1d, window:30d,
        metric:event_count_sum,
        agg:num_metric_periods,
        target.user.userid:$user
))

La règle suivante vous indique la première ou la dernière fois qu'un utilisateur spécifique s'est connecté avec succès :

$first_seen = max(metrics.auth_attempts_success(
        period:1d, window:30d,
        metric:first_seen,
        agg:min,
        target.user.userid:$user
))
$last_seen = max(metrics.auth_attempts_success(
        period:1d, window:30d,
        metric:last_seen,
        agg:max,
        target.user.userid:$user
))

La règle suivante indique le nombre maximal d'octets envoyés par un utilisateur au cours d'un jour donné au cours des 30 derniers jours :

$max_daily_bytes = max(metrics.network_bytes_outbound(
        period:1d, window:30d,
        metric:value_sum,
        agg:max,
        target.user.userid:$user
))

Filtre

Les filtres permettent de filtrer une métrique avant l'agrégation en fonction d'une valeur dans la métrique précalculée (voir les valeurs dans Métrique). Les filtres peuvent être n'importe quelle expression d'événement valide (une seule ligne dans la section "Événements") qui ne contient aucun champ ni espace réservé d'événement. Les seuls types de variables pouvant être inclus dans cette condition sont les types de métriques.

La règle suivante n'inclut que les métriques où value_sum > 10 AND event_count_sum > 2 :

$max_bytes_per_day = max(metrics.network_bytes_outbound(
    period:1d, window:30d,
    metric:value_sum,
    agg:max,
    principal.asset.ip:$ip
    filter:value_sum > 10 AND event_count_sum > 2
))

Exemples de filtres valides

filter:value_sum > 10 AND event_count_sum != 5
filter:event_count_sum = 100 OR event_count_sum > 1000
filter:timestamp.get_day_of_week(first_seen) = 3

Exemples de filtres non valides

// No placeholders in filter expressions.
filter:value_sum > $ph

// No event fields in filter expressions.
filter:event_count_sum + $e.field > 10

// No event fields in filter expressions.
filter:timestamp.subtract(first_seen, $e.metadata.timestamp)

Champs UDM

Une métrique est filtrée par un, deux ou trois champs UDM, selon la fonction. Pour en savoir plus, consultez Fonctions.

Les types de champs UDM suivants sont utilisés pour les fonctions de métriques :

• Dimensions : (obligatoire) différentes combinaisons sont listées dans cette documentation. Vous ne pouvez pas joindre une métrique avec une valeur par défaut ("" pour la chaîne et 0 pour l'entier).
• Espaces de noms : (facultatif) vous ne pouvez utiliser des espaces de noms que pour les entités que vous spécifiez dans les dimensions. Par exemple, si vous utilisez principal.asset.hostname filter, vous pouvez également utiliser principal.namespace filter. Si vous n'incluez pas de filtre d'espace de noms, les données de tous les espaces de noms sont agrégées. Vous pouvez utiliser une valeur par défaut comme filtre d'espace de noms.

Calculs de fenêtres

Google Security Operations calcule les métriques à l'aide d'une fenêtre de métriques quotidienne ou horaire.

Périodes quotidiennes

Toutes les fenêtres quotidiennes, comme 30d, sont déterminées de la même manière. Google Security Operations utilise les dernières données de métriques disponibles qui ont été générées et qui ne chevauchent pas la plage de temps de la règle. Le calcul des métriques quotidiennes peut prendre jusqu'à six heures et ne commence qu'à la fin de la journée en UTC. Les données de métriques de la veille seront disponibles à 6h00 UTC ou avant chaque jour.

Par exemple, pour une règle qui s'exécute sur des données d'événement du 31/10/2023 à 4h00 UTC au 31/10/2023 à 7h00 UTC, les métriques quotidiennes du 31/10/2023 auront probablement été générées. Le calcul des métriques utilisera donc les données du 01/10/2023 au 30/10/2023 (inclus). En revanche, pour une règle qui s'exécute sur des données d'événement du 31/10/2023 à 1h00 UTC au 31/10/2023 à 3h00 UTC, les métriques quotidiennes du 30/10/2023 n'auront probablement pas été générées. Le calcul des métriques utilisera donc les données du 30/09/2023 au 29/10/2023 (inclus).

Période de today heures

La période de la métrique horaire est calculée différemment de celle des métriques quotidiennes. La période de métrique horaire de today n'est pas une taille statique comme la période 30d pour les métriques quotidiennes. La fenêtre de métriques horaires today remplit autant de données que possible entre la fin de la fenêtre quotidienne et le début de la fenêtre temporelle de la règle.

Par exemple, pour une règle qui s'exécute sur des données d'événement du 31/10/2023 à 4h00:00 UTC au 31/10/2023 à 7h00:00 UTC, le calcul des métriques quotidiennes utilisera les données du 01/10/2023 au 30/10/2023 (inclus), et la fenêtre de métriques horaires utilisera les données du 31/10/2023 à 0h00:00 UTC au 31/10/2023 à 4h00:00 UTC.

Métriques "Nombre unique"

Il existe un type spécial de métrique num_unique_filter_values qui n'est pas précalculé par Google SecOps, mais qui est calculé lors de l'exécution d'une règle. Pour ce faire, il faut agréger une dimension existante dans une métrique précalculée. Par exemple, la métrique daily total count of distinct countries that a user attempted to authenticate peut être dérivée de la métrique précalculée auth_attempts_total sur les dimensions target.user.userid et principal.ip_geo_artifact.location.country_or_region en effectuant une agrégation "Nombre unique" sur la dernière dimension.

L'exemple de règle suivant comptabilise les métriques uniques :

$outcome_variable = max(metrics.auth_attempts_total(
    period: 1d,
    window: 30d,
    // This metric type indicates any filter with a wildcard value should be
    // aggregated over each day to produce a new metric on-the-fly.
    metric: num_unique_filter_values,
    agg: max,
    target.user.userid: $userid,
    // Filter whose value should be counted over each day to produce the
    // num_unique_filter_values metric.
    principal.ip_geo_artifact.location.country_or_region: *
))

Cette fonctionnalité présente la limite suivante :

• Le calcul du nombre unique de métriques ne peut être agrégé que sur une dimension de filtre. Pour ce faire, utilisez le jeton générique * comme valeur de filtre.

Fonctions

Cette section inclut la documentation sur les fonctions de métriques spécifiques compatibles avec Google Security Operations.

Événements d'alerte

metrics.alert_event_name_count précalcule les valeurs historiques des événements UDM pour lesquels des alertes ont été générées par Carbon Black, CrowdStrike Falcon, les alertes de l'API Microsoft Graph ou Microsoft Sentinel.

Tentatives d'authentification

metrics.auth_attempts_total précalcule les valeurs historiques des événements UDM avec un USER_LOGIN event type.

metrics.auth_attempts_success exige également que l'événement ait au moins un SecurityResult.Action de ALLOW.

metrics.auth_attempts_fail exige plutôt qu'aucun des SecurityResult.Actions n'ait été ALLOW.

Octets DNS sortants

metrics.dns_bytes_outbound précalcule les valeurs historiques pour les événements UDM où network.sent_bytes est supérieur à 0 et où le port cible est 53/udp, 53/tcp ou 3000/tcp. network.sent_bytes est disponible en tant que value_sum.

Requêtes DNS

metrics.dns_queries_total précalcule les valeurs historiques des événements UDM qui ont une valeur dans network.dns.id.

metrics.dns_queries_success exige également que network.dns.response_code était 0 (NoError).

metrics.dns_queries_fail ne prend en compte que les événements avec un network.dns.response_code supérieur à 0.

Exécutions de fichiers

metrics.file_executions_total précalcule les valeurs historiques des événements UDM avec un PROCESS_LAUNCH event type.

metrics.file_executions_success exige également que l'événement ait au moins un SecurityResult.Action de ALLOW.

metrics.file_executions_fail exige qu'aucun des SecurityResult.Actions n'ait été ALLOW.

Requêtes HTTP

metrics.http_queries_total précalcule les valeurs historiques des événements UDM qui ont une valeur dans network.http.method.

metrics.http_queries_success exige également que network.http.response_code est inférieur à 400.

metrics.http_queries_fail ne prend en compte que les événements avec un network.http.response_code est supérieur ou égal à 400.

Octets réseau

metrics.network_bytes_inbound précalcule les valeurs historiques des événements UDM dont la valeur network est non nulle.received_bytes, et rend ce champ disponible sous la forme value_sum.

metrics.network_bytes_outbound nécessite une valeur non nulle pour network.sent_bytes et rend ce champ disponible sous la forme value_sum.

metrics.network_bytes_total prend en compte les événements dont la valeur est non nulle pour network.received_bytes ou network.sent_bytes (ou les deux), et met la somme de ces deux champs à disposition sous la forme value_sum.

Création de ressources

metrics.resource_creation_total précalcule les valeurs historiques des événements UDM avec une RESOURCE_CREATION event type ou une USER_RESOURCE_CREATION event type.

Pour obtenir la liste des types d'événements équivalents, consultez Types d'événements de métadonnées.

metrics.resource_creation_success exige également que l'événement comporte au moins un SecurityResult.Action de ALLOW.

Suppression de ressources

metrics.resource_deletion_success précalcule les valeurs historiques des événements UDM avec un RESOURCE_DELETION event type et exige en outre que l'événement comporte au moins un SecurityResult.Actions de ALLOW.

Lecture de ressources

metrics.resource_read_success précalcule les valeurs historiques des événements UDM avec un RESOURCE_READ event type et exige en outre que l'événement comporte au moins un SecurityResult.Action de ALLOW.

metrics.resource_read_fail exige qu'aucun des SecurityResult.Actions ne soit ALLOW.

Limites

Lorsque vous créez des règles YARA-L avec des métriques, tenez compte des limites suivantes :

• Vous ne pouvez pas joindre une métrique avec une valeur par défaut ("" pour les chaînes et 0 pour les entiers).
• Valeurs par défaut :
  • Si aucune donnée de métrique ne correspond à un événement, la valeur renvoyée par la fonction de métrique est 0.
  • Si un événement de la détection ne comporte aucune donnée de métrique, l'utilisation de min pour agréger la fonction peut renvoyer 0.
  • Pour vérifier si des données sont disponibles pour un événement, vous pouvez utiliser l'agrégation de métriques num_metric_periods sur ce même événement avec les mêmes filtres.
• Les fonctions de métrique ne peuvent être utilisées que dans la section "Résultat".
• Étant donné que les fonctions de métrique ne sont utilisées que dans la section "Résultat", elles doivent être agrégées comme n'importe quelle autre valeur dans les règles comportant une section "Correspondance".

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