Sintaxis de la sección de coincidencias

Compatible con:

Google SecOps SIEM

En YARA-L 2.0, la sección match proporciona el mecanismo para la correlación de varios eventos. Define la lógica para agrupar eventos en una sola detección vinculando atributos comunes, como usuarios, direcciones IP o hashes de archivos, dentro de un límite temporal específico.

Usas la sección match para los siguientes casos de uso:

Vincular dos o más eventos distintos dentro de una regla
Agrega datos en la Búsqueda y los paneles, como el recuento de intentos de acceso fallidos durante un período específico.

Cómo definir criterios de correlación

Úsalo para definir los criterios de esta correlación especificando lo siguiente:

Campos de agrupación (claves): Son variables (como $user o $ip) que deben tener valores idénticos en todos los eventos (definidos en la sección events) para activar una coincidencia.
Restricción de tiempo: Es el período durante el cual deben ocurrir los eventos agrupados para satisfacer la regla o la agregación. En Rules, define el período de detección; en Search y Dashboards, define el período de agregación o correlación.

Comparar los requisitos de las funciones

En la siguiente tabla, se detallan las comparaciones de las reglas de búsqueda y los paneles.

Función	Requisito de reglas	Compatibilidad con la búsqueda y los paneles
Tipos de variables	Se deben usar los marcadores de posición definidos en la sección `events`.	Admite tanto marcadores de posición como campos de UDM directos.
Período	Define el límite de detección.	Define el bucket de agregación o correlación.
Sintaxis	`over <number><m/h/d>` (por ejemplo, `10m`, `2h`, `1d`)	`over <number><m/h/d>`
Límites	Mín.: `1m` / Máx.: `48h`	Mín.: `1m` / Máx.: `48h`

Tipos de ventanas admitidos

YARA-L 2.0 usa diferentes comportamientos de ventanas para determinar cómo se segmenta el tiempo y cómo se agrupan los eventos. Puedes agrupar los campos y marcadores de posición de eventos en la sección match según una granularidad temporal especificada con una de las siguientes ventanas admitidas.

Tipo de ventana admitido	Sintaxis	Descripción	Caso de uso común
Hop	`$key over <duration>`	Intervalos de tiempo superpuestos (comportamiento predeterminado).	Correlación general de múltiples eventos.
Tumbling	`$key by <duration>`	Intervalos de tiempo continuos, de tamaño fijo y sin superposición.	Cuantificar la actividad en bloques de hasta 1 hora (por ejemplo, `$user by 30m`)
Deslizamiento	`$key over <duration> [before\|after] $pivot`	Son intervalos de tiempo anclados a un evento "pivote" específico.	Secuenciación estricta (por ejemplo, `File Download after Login`)

Ejemplo de sintaxis:

match:
  $user, $source_ip over 5m  // Groups events by user and IP within a 5-minute window

Ventana de salto

Una ventana de salto es el comportamiento predeterminado para las reglas de varios eventos. Crea intervalos de tiempo superpuestos para garantizar que no se pierdan los eventos que ocurren cerca de los límites de una ventana.

Sintaxis: $key over <duration> (por ejemplo, $user over 30m)
Caso de uso: Es mejor para la detección cuando necesitas asegurarte de que se capte una situación específica, independientemente de cuándo comience o finalice exactamente el intervalo de la ventana.
Compatibilidad: Compatible con la agregación en la búsqueda y los paneles (por ejemplo, count).

De forma predeterminada, las consultas de YARA-L con una sección match usan ventanas de salto para correlacionar varios eventos a lo largo del tiempo. El período de ejecución de la consulta se divide en un conjunto de períodos de salto fijos y superpuestos. Si bien la duración de estos períodos se especifica en la sección match, el intervalo de superposición y la alineación de los períodos se definen por el sistema y no se pueden configurar por el usuario. Luego, se correlacionan los eventos dentro de cada una de estas ventanas predeterminadas.

Ejemplo: Ventanas de salto superpuestas para la correlación continua

En el siguiente ejemplo, se muestra una búsqueda que se ejecuta en el intervalo de tiempo [1:00, 2:00], con una sección match $user over 30m, en la que un posible conjunto de ventanas de salto superpuestas que se podrían generar es [1:00, 1:30], [1:03, 1:33] y [1:06, 1:36].

rule hop_window_brute_force_example {
meta:
  description = "Detects multiple failed logins within a shifting 30-minute window."
  severity = "Medium"

events:
  $login.metadata.event_type = "USER_LOGIN"
  $login.extensions.auth.auth_status = "FAILURE"
  $login.principal.user.userid = $user

match:
  // This creates the overlapping windows (e.g., 1:00-1:30, 1:03-1:33)
  $user over 30m

condition:
  // This will trigger if 10 or more failures fall into any single 30m hop
  #login >= 10
}

Ejemplo: Correlación de varios eventos con una ventana de salto

En el siguiente ejemplo, se representa el valor predeterminado para la mayoría de las reglas de varios eventos. Captura los eventos que ocurren dentro del mismo período general.

rule hop_window_example {
meta:
  description = "Detect a user with a failed login followed by a success within 30m"

events:
  $e1.metadata.event_type = "USER_LOGIN"
  $e1.extensions.auth.auth_status = "FAILURE"
  $e1.principal.user.userid = $user

  $e2.metadata.event_type = "USER_LOGIN"
  $e2.extensions.auth.auth_status = "SUCCESS"
  $e2.principal.user.userid = $user

match:
  $user over 30m  // This is a hop window

condition:
  $e1 and $e2
}

Ejemplo: Comparación de ventanas de salto

Para identificar un intento de ataque de fuerza bruta, una ventana de 10m agrupa todos los errores de USER_LOGIN. Luego, condition evalúa si el recuento (#e) dentro de ese bucket específico de 10 minutos supera tu umbral.

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

condition:
  #e >= 5
}

La sección match encuentra a los usuarios que no pudieron acceder a su cuenta en una ubicación nueva durante un intervalo de 10 minutos (10m):

match:
  $user over 10m

Ventanas de saltos de tamaño constante

Una ventana de saltos de tamaño constante segmenta un flujo de datos en intervalos de tiempo continuos, de tamaño fijo y sin superposición. La marca de tiempo de cada evento se incluye en exactamente una ventana. No hay superposición entre las ventanas de saltos de tamaño constante. Esto contrasta con una ventana deslizante o de salto, que puede tener intervalos de tiempo superpuestos.

Para implementar una ventana rotativa, usa el operador by en la sección match.

Las ventanas de saltos de tamaño constante dividen el tiempo en bloques continuos y consecutivos. Por ejemplo:

by 1h: Crea ventanas para cada hora (por ejemplo, [00:00:00-00:59:59], [01:00:00-01:59:59], etcétera).
by 10m: Crea ventanas para cada intervalo de 10 minutos (por ejemplo, [00:00:00-00:09:59], [00:10:00-00:19:59], etcétera).

Casos de uso

Usa ventanas continuas cuando necesites hacer lo siguiente:

Analiza los eventos en bloques de tiempo distintos y que no se superpongan.
Asegúrate de que solo se produzca una detección para una entidad determinada (según lo definen las variables de coincidencia) dentro de cada intervalo de tiempo fijo, independientemente de cuántas veces ocurra el evento.
Contar entidades únicas en períodos fijos

Comportamiento de anulación de duplicación

Una característica clave de las ventanas continuas es cómo se manejan las detecciones dentro de cada ventana para el mismo conjunto de variables de coincidencia:

Una detección por ventana: Para un conjunto determinado de valores de las variables de coincidencia (por ejemplo, un $userid específico), se genera, como máximo, una detección para cualquier ventana rotativa única.
El primer evento que llega gana: Los primeros eventos que se transfieren y que satisfacen las condiciones de la regla para ese conjunto de variables de coincidencia dentro de una ventana específica activan la detección.
Eliminación de duplicados: Los eventos posteriores que coincidan con los criterios dentro de la misma instancia de la ventana no generarán detecciones adicionales.

Sintaxis

La sintaxis en la sección match es la siguiente:

match:
  $variable by <duration>

Donde:

$variable es la variable de marcador de posición con la que realizas la correlación.
<duration> es un número seguido de una unidad de tiempo:
- m: minuto
- h: hora
- d: día
Especifica un mínimo de un minuto y un máximo de 72 horas o tres días.

Ejemplo

La siguiente regla agrupa los inicios de sesión por $userid en ventanas no superpuestas de 1 hora (por ejemplo, [00:00:00-00:59:59], [01:00:00-01:59:59], etcétera):

rule TumblingWindowExample {
  meta:
    description = "Example using a 1-hour tumbling window"
  events:
    $e.metadata.event_type = "USER_LOGIN"
    $e.principal.user.userid = $userid
  match:
    $userid by 1h
  condition:
    $e
}

A continuación, se muestra un ejemplo del comportamiento de detección de user = "alex":

Evento 1: Alex accede a las 00:30. Esto se encuentra dentro del período de [00:00:00-00:59:59]. Se genera una detección para Alex en esta ventana.
Evento 2: Otro usuario, "taylor", accede a las 00:45. Esto también se incluye en [00:00:00-00:59:59], pero, como el $userid es diferente, se genera una detección separada para Taylor en este período.
Evento 3: Alex vuelve a acceder a las 00:40. Esto sigue dentro del período de [00:00:00-00:59:59]. Dado que ya existe una detección para Alex en este período, se quita el duplicado de este evento. No se genera una detección nueva.
Evento 4: Alex accede a las 1:20 a.m. Esto se incluye en la siguiente ventana, [01:00:00-01:59:59]. Se genera una nueva detección para Alex en esta ventana nueva.

Aunque el evento 1 y el evento 4 de Alice ocurrieron con menos de una hora de diferencia, se incluyen en detecciones separadas porque el evento 4 cruza el límite de la ventana fija.

Ventana deslizante

Usa una ventana deslizante cuando necesites buscar eventos que ocurren en un orden estricto y relativo (por ejemplo, e1 ocurre hasta dos minutos después de e2). A diferencia de las ventanas fijas, una ventana deslizante se activa con cada ocurrencia del $pivot_event designado con esta sintaxis:

after: La ventana comienza en la marca de tiempo del evento de pivote y se extiende hacia adelante.
before: La ventana finaliza en la marca de tiempo del evento de pivote y se extiende hacia atrás.

Especifica ventanas deslizantes en la sección match de una consulta de la siguiente manera:

<match-var-1>, <match-var-2>, ... over <duration> [before|after] <pivot-event-var>

Sintaxis: $key over <duration> before|after $<pivot_event>
Claves de agrupación: Son campos comunes (por ejemplo, $user, $ip) que se usan para vincular eventos.
Duración: Desplazamiento temporal desde el evento pivote (por ejemplo, 5m, 1h).
Casos de uso:
- Secuencia estricta: Detecta una cadena de ataque en la que se requiere un orden (por ejemplo, la creación de un usuario seguida de una elevación de privilegios).
- Tiempo relativo: Busca un evento que ocurra dentro de un desplazamiento específico de un "activador" (por ejemplo, un evento Process Start seguido de un evento Network Connection en un plazo de 30 segundos).
- Detección de ausencia: Identifica cuándo no se produce un evento de "limpieza" o "latido" requerido después de un evento de inicio (por ejemplo, un Database Backup Start sin un evento End correspondiente).

Ejemplos válidos de ventanas deslizantes

En los siguientes ejemplos, se muestran ventanas deslizantes válidas:

$var1, $var2 over 5m after $e1 $user over 1h before $e2 $host, $ip over 1h before $e2

Ejemplo: Correlación prospectiva con ventanas deslizantes (`after`)

En el siguiente ejemplo, se muestra cómo detectar una secuencia de eventos en la que el segundo evento debe ocurrir dentro de un período específico después de un evento principal de "activación" o pivote. Esto es útil para detectar movimientos laterales rápidos o acciones de seguimiento automatizadas.

rule sliding_window_after_example {
meta:
  description = "Detect a network connection occurring within 1 minute after a suspicious process launch."
  severity = "High"

events:
  $proc.metadata.event_type = "PROCESS_LAUNCH"
  $proc.principal.hostname = $host

  $net.metadata.event_type = "NETWORK_HTTP"
  $net.principal.hostname = $host

match:
  // $proc is the pivot; the 1-minute window starts at the $proc timestamp
  $host over 1m after $proc

condition:
  $proc and $net
}

Ejemplo: Correlación retrospectiva con ventanas deslizantes (`before`)

Usa una ventana deslizante "before" para investigar la actividad que generó una alerta específica. A menudo, se usa en el análisis de causa raíz para identificar lo que sucedió inmediatamente antes de una detección crítica.

rule sliding_window_before_example {
meta:
  description = "Identify file modifications occurring in the 5 minutes before a ransomware alert."
  severity = "Critical"

events:
  $file.metadata.event_type = "FILE_MODIFICATION"
  $file.principal.hostname = $host

  $alert.metadata.event_type = "ANTIVIRUS_DETECTION"
  $alert.metadata.product_name = "Premium_AV"
  $alert.principal.hostname = $host

match:
  // $alert is the pivot; the 5-minute window ends at the $alert timestamp
  $host over 5m before $alert

condition:
  $file and $alert
}

Rendimiento y prácticas recomendadas

Las ventanas deslizantes requieren más capacidad de procesamiento que las ventanas estándar (de salto) porque se calculan para cada ocurrencia del evento pivote y pueden generar un rendimiento más lento.

Sigue estos lineamientos para obtener un rendimiento óptimo en las reglas, las búsquedas y los paneles:

Prioriza las ventanas de salto: Usa la ventana de salto predeterminada, a menos que la secuencia específica de eventos (pedido A y, luego, pedido B) sea necesaria para la lógica de detección. Solo usa ventanas deslizantes cuando la secuencia de eventos sea fundamental o cuando busques eventos faltantes.
Usa filtros de marcas de tiempo para mejorar el rendimiento: Si solo necesitas asegurarte de que un evento ocurrió después de otro, una comparación de marcas de tiempo en la sección events o condition suele ser más eficiente que una ventana deslizante, por ejemplo:

$e1.metadata.event_timestamp.seconds < $e2.metadata.event_timestamp.seconds

Diseño de varios eventos: Evita usar ventanas deslizantes para las búsquedas de un solo evento. Las ventanas deslizantes están diseñadas para la correlación de múltiples eventos. En el caso de la lógica de eventos únicos, se aplican los siguientes lineamientos:
- Usa varias variables de evento y actualiza la sección condition.
- Quita la sección match por completo si no se requiere correlación.
- De manera opcional, considera agregar filtros de marcas de tiempo en lugar de usar una ventana deslizante, por ejemplo:
  $permission_change.metadata.event_timestamp.seconds < $file_creation.metadata.event_timestamp.seconds

Comprende el límite temporal

La sección match particiona los eventos en grupos según tus claves de agrupación. La duración especificada define el límite temporal para cada grupo:

Inclusión: Solo los eventos dentro de la ventana se pasan a la evaluación de condition para esa coincidencia específica.
Exclusión: Los eventos fuera del período se ignoran para ese grupo de coincidencias específico, lo que evita que los eventos no relacionados activen un falso positivo.

Valores cero en la sección `match`

Google SecOps filtra de forma implícita los valores cero para todos los marcadores de posición que se usan en la sección match ("" para cadenas, 0 para números, false para booleanos y el valor en la posición 0 para tipos enumerados).

Ejemplo: Filtra los valores cero

En el siguiente ejemplo, se ilustran las consultas que filtran los valores cero.

rule ZeroValuePlaceholderExample {

events:
  // Because $host is used in the match section, the query behaves
  // as if the following predicate was added to the events section:
  // $host != ""
  $host = $e.principal.hostname

  // Because $otherPlaceholder was not used in the match,
  // there is no implicit filtering of zero values for $otherPlaceholder.
  $otherPlaceholder = $e.principal.ip

match:
  $host over 5m

condition:
  $e
}

Sin embargo, si se asigna un marcador de posición a una función, las búsquedas no filtran de forma implícita los valores cero de los marcadores de posición que se usan en la sección match.

Para inhabilitar el filtrado implícito de valores cero, puedes usar la opción allow_zero_values en la sección de opciones. La opción allow_zero_values solo está disponible en Rules.

Ejemplo: Permite valores cero

En el siguiente ejemplo, se ilustran las consultas que no filtran de forma implícita los valores cero de los marcadores de posición que se usan en la sección match:

rule AllowZeroValuesExample {

events:
  // Because allow_zero_values is set to true, there is no implicit filtering
  // of zero values for $host.
  $host = $e.principal.hostname

  // Because $otherPlaceholder was not used in the match,
  // there is no implicit filtering of zero values for $otherPlaceholder.
  $otherPlaceholder = $e.principal.ip

match:
  $host over 5m

condition:
  $e

options:
  allow_zero_values = true
}

¿Qué sigue?

Explora los siguientes recursos para continuar con tu lógica de YARA-L o profundizar en las funciones de consulta avanzadas:

Sintaxis y lógica

Referencias y ejemplos

¿Necesitas más ayuda? Obtén respuestas de miembros de la comunidad y profesionales de Google SecOps.