Comienza a usar YARA-L

Se admite en los siguientes sistemas operativos:

YARA-L 2.0 es el lenguaje de consultas único y altamente estructurado que impulsa Google Security Operations para todas las búsquedas, los paneles y la detección de amenazas basada en reglas. Este documento te ayuda a comprender la estructura principal de YARA-L y proporciona pasos prácticos para usarla, ya sea que seas un analista de seguridad que busca amenazas o un ingeniero de detección que crea una nueva lógica sólida.

En este documento, se explica YARA-L y su sintaxis, y se muestra cómo puedes usarlo para expresar desde una consulta de filtro básica hasta una regla que busca patrones complejos. Usa las secciones de una consulta de YARA-L para admitir funciones de agregación y lógica de condiciones, y agregar contexto a través de uniones, coincidencias de patrones y mucho más.

Antes de comenzar

Comprende la estructura de YARA-L

Cada consulta de YARA-L se segmenta en secciones distintas con nombre, que dictan el comportamiento de la consulta.

Esta estructura es la que permite el análisis y la correlación de varias etapas.

Pedido Sección Reglas Búsqueda/Paneles Descripción
1 meta Obligatorio Opcional Establece metadatos descriptivos para la regla, como el autor, la descripción y la gravedad. Por ejemplo, autor (security team), descripción (Detects multiple failed user logins within 10-minute windows) y gravedad (High).Consulta la sintaxis de la sección meta.
2 events Obligatorio Obligatorio Define y filtra los eventos que se deben hacer un seguimiento: accesos de usuarios, accesos de usuarios fallidos (variables de eventos) y vínculos a la variable de coincidencia del usuario (variables de marcador de posición). Declara todas las fuentes de datos (principalmente eventos) que se deben tener en cuenta y las filtra con los campos de UDM. Consulta la sintaxis de la sección events.
3 match Obligatorio Opcional Agrupa por eventos y te permite especificar el período admitido (por ejemplo, by 5m). En algunos casos, es obligatorio para las búsquedas estadísticas en las que se produce la agregación. Se requiere para las consultas de correlación de varios eventos. La especificación de tiempo es obligatoria en match para las reglas y opcional para la búsqueda y los paneles. Consulta la sintaxis de la sección match.

Nota: Si excluyes una sección match, la regla puede coincidir con un solo evento.
4 outcome Opcional Opcional Calcula métricas esenciales y obtiene estadísticas (por ejemplo, count(), avg()). Consulta la sintaxis de la sección outcome.
5 condition Obligatorio Opcional Define la lógica que se debe cumplir para mostrar resultados (en la búsqueda) o activar una alerta (en una regla). Evalúa los criterios de las variables de búsqueda para determinar si se aplica un resultado (por ejemplo, $event >5). Consulta la sintaxis de la sección condition.
6 options Opcional Opcional Permite habilitar o inhabilitar el comportamiento de reglas específicas. Consulta la sintaxis de la sección options.
7 dedup N/A Opcional Quita los eventos duplicados agrupándolos según variables clave o rutas de eventos (por ejemplo, target.user.userid, target.ip, principal.hostname o variables, como $host, $user). Obtén más información sobre las variables de eventos y cómo usar la anulación de duplicación en la Búsqueda y los paneles.
8 order N/A Opcional Ordena los resultados definidos por campos específicos (por ejemplo, asc). Obtén más información sobre las variables de eventos. Opcional (solo se aplica cuando se usa match).
9 limit N/A Opcional Restringe la cantidad máxima de eventos devueltos por la búsqueda.
10 select N/A Opcional Especifica la lista de campos de UDM que se incluirán en los resultados de la consulta.
11 unselect N/A Opcional Especifica la lista de campos de UDM que se excluirán de los resultados de la consulta.

Disponibilidad de la fuente de datos de YARA-L

YARA-L tiene acceso a diferentes fuentes de datos, según dónde te encuentres en la plataforma. Eventos, entidades (ECG) y tablas de datos están disponibles por completo en la búsqueda, los paneles y las reglas. Para obtener detalles sobre las consultas de muestra, consulta Fuentes de datos compatibles.

En la siguiente tabla, se enumeran las funciones disponibles en YARA-L:

Función Disponible en
Casos y historial de casos Paneles
Tablas de datos Búsqueda, paneles y reglas
Entidades (ECG) Búsqueda, paneles y reglas
Métricas de transferencia Paneles
Coincidencias de IoC Paneles
Detecciones de reglas Paneles y reglas
Conjuntos de reglas Paneles
Eventos Búsqueda, paneles y reglas
Métricas de UEBA Búsqueda, paneles

En Google SecOps, todos los datos se buscan con dos métodos principales según tus objetivos: la búsqueda con filtros y la búsqueda estadística (agregaciones).

El método de búsqueda de filtros te permite aislar eventos específicos del flujo de telemetría más amplio sin la sobrecarga de la agregación estadística. Este método usa criterios para reducir grandes volúmenes de datos de seguridad (como registros o tráfico de red) a un conjunto de resultados segmentado. La lógica solo requiere que especifiques eventos en la sección events.

Para crear tu primera búsqueda con filtros de YARA-L, sigue estos pasos para buscar usuarios con accesos fallidos:

  1. En Google SecOps, ve a la página de búsqueda.
  2. Filtra los eventos de acceso:
    metadata.event_type = "USER_LOGIN"

    Nota: Puedes omitir el encabezado de la sección events: en tus búsquedas. De forma predeterminada, la sintaxis de búsqueda implica esta sección.

  3. Agrega acciones de event para los accesos fallidos de usuarios que no tienen un userid vacío. 
    metadata.event_type = "USER_LOGIN"
security_result.action = "FAIL"
principal.user.userid != ""
  4. Ejecuta esta búsqueda para ver los resultados.

Usa variables de marcador de posición

Usa variables de marcador de posición para extraer valores específicos de tus eventos, como un nombre de usuario o una dirección IP. Estas variables actúan como anclajes temporales que te permiten comparar datos entre diferentes eventos o mostrar esos valores en tu resultado final.

Aplicas variables de marcador de posición para hacer lo siguiente:

  • Datos de puente: Usa marcadores de posición, como $userid o $ip, para encontrar coincidencias entre diferentes variables de eventos (por ejemplo, puedes usar $userid para vincular el identificador del usuario en los eventos de acceso y cierre de sesión).
  • Agrupa los resultados: En la sección match, usa variables de marcador de posición para definir la ventana de salida de tu consulta, como match: $userid over 1h.
  • Crear resultados: Usa marcadores de posición para capturar y mostrar puntos de datos específicos en el resultado de tu búsqueda.

Por ejemplo, si asignas $user = principal.user.userid, la variable $user ahora contiene el valor específico extraído del evento. Luego, usa $user en la sección match para agrupar toda la actividad relacionada con ese usuario específico.

El método de búsqueda estadística te ayuda a obtener estadísticas, tendencias o anomalías realizando cálculos en conjuntos de eventos. En lugar de mostrar una lista de registros individuales, proporciona resúmenes agregados de tus datos. La lógica usa la sección match (para agrupar) y la sección outcome (para los cálculos). La sección outcome admite funciones de agregación, como count(), sum(), avg(), max(), min() y stddev().

En el siguiente ejemplo, se usa la siguiente lógica de consulta:

  • events: Filtra los datos sin procesar para los intentos de acceso fallidos.
  • match: Define los eventos de agrupación (por userid).
  • outcome: Realiza la agregación estadística (recuento de eventos por usuario).

Ejemplo: Agrega la actividad de acceso fallida con las funciones outcome

En el siguiente ejemplo, se usan las funciones de agregación de la sección outcome (como count() o sum()) para resumir la actividad de acceso fallido.

  1. Usa la sección match para agrupar los eventos de acceso con errores por userid:

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

match:
  principal.user.userid

  2. Usa la count de los accesos fallidos para cada usuario ($failed_login_count), definida por 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. Ejecuta esta búsqueda para ver los resultados.

  4. Opcional: Agrega un elemento de tiempo a la sección match (en este caso, day). Luego, actualiza la variable outcome para que sea más explícita ($daily_failed_login_count):

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

match:
  $user by day

outcome:
  $daily_failed_login_count = count(metadata.id)

Crea un widget de panel a partir de tu búsqueda

Puedes crear un widget de panel a partir de búsquedas agregadas, como se muestra en el ejemplo de tu primera búsqueda.

Una vez que se valide la búsqueda, puedes guardarla como un widget y agregarla a tu panel de la siguiente manera:

  1. Cuando veas los resultados, haz clic en la pestaña Visualizar > Agregar al panel.
  2. Configura el widget:
    1. Asigna un nombre al widget (por ejemplo, "Daily Failed Login").
    2. Selecciona un período.
    3. Elige si deseas agregarlo a un panel existente o nuevo.
    4. Haz clic en Agregar.
  3. Opcional: Crea consultas directamente en tus paneles. Como alternativa, puedes copiar paneles seleccionados y modificar las ediciones de las consultas que contienen como punto de partida.
  4. Opcional: Puedes crear un panel personalizado y agregarle widgets con YARA-L. Para obtener más detalles, consulta Crea un panel personalizado.

Configure un panel

Cuando creas un panel nuevo, la sección events es un punto de partida obligatorio. Desde allí, puedes usar match (para agrupar resultados) o outcome (para calcular resultados y agregaciones).

Por ejemplo, puedes tener un panel con secciones de events y match, en el que se muestre la gravedad ($severity) de las detecciones agrupadas en buckets de by hour.

Ejemplo: Agrega series temporales por gravedad

  • Puedes crear un panel con las secciones events y match para mostrar la gravedad ($severity) de las detecciones agrupadas en buckets hour:

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

match:
  $severity by hour

Ejemplo: Impacto crítico total agregado

  • De manera similar, puedes crear un panel con las secciones events y outcome para hacer un seguimiento de las detecciones de gravedad alta:

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

outcome:
  $detection_count = count_distinct($severity)

Ejemplo: Visualiza el volumen de detecciones por gravedad a lo largo del tiempo

  • En el siguiente ejemplo, puedes contar las detecciones críticas y especificar el intervalo de tiempo a través de la consola. En muchos casos, usarás las secciones match y outcome cuando crees una visualización en un panel:

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

match:
  $severity by hour

outcome:
  $detection_count = count_distinct(detection.id)

Ejemplo: Calcula la frecuencia de acceso de los usuarios

  • En el siguiente ejemplo, se calcula el login_count para usuarios específicos con las secciones match y outcome:

    events:
  metadata.event_type = "USER_LOGIN"

match:
  target.user.userid

outcome:
  $login_count = count(metadata.id)

Crea una regla

Una regla requiere las siguientes secciones:

  • meta: Contiene el nombre de la regla y detalles descriptivos.
  • events: Define tus fuentes de datos y filtros con variables de eventos.
  • condition: Especifica qué variables de evento deben existir para que se active la regla.

Define y usa variables de eventos

Las variables de eventos actúan como un contenedor lógico que agrupa tus filtros para que puedas hacer referencia a esa actividad específica en toda tu búsqueda, regla o panel.

Cuando defines la lógica en la sección events, puedes usar variables de evento (como $e) para representar un evento específico (o un grupo de eventos) que coincidan con tus criterios.

Ejemplo: Define y filtra variables de eventos

  • Para definir una variable de evento (por ejemplo, $e), usa un prefijo en la sección events de tu consulta. Esto declara que esos eventos están representados por la variable. Por ejemplo, la expresión $e.principal.hostname = "dev" evalúa cada evento para determinar si el nombre de host es una coincidencia exacta.

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

Luego, puedes usar esa variable en otras secciones de la consulta para hacer referencia a ese grupo específico de eventos (en las secciones match, outcome y condition) y sus campos de datos.

Organiza la estructura y la sintaxis de las reglas

Usa la siguiente estructura y sintaxis de reglas para definir tus variables, la lógica de agrupación y los umbrales de activación:

Elemento Descripción Ejemplo
Estructura de la regla Encapsula tu búsqueda en un bloque rule y le asigna un nombre único para identificar la detección. rule DailyFailedLoginAttempts { }
Sección meta Obligatorio. Incluye metadatos descriptivos (como "autor", "descripción" y "gravedad") para mejorar la administración de reglas y proporcionar contexto a tu equipo. Se recomienda como práctica recomendada para la administración de reglas. author = "Alex"
severity = "Medium"
Variable de evento En una búsqueda de reglas, cada campo de la sección events tiene un prefijo con una variable de evento (como $e) para representar un evento específico (o un grupo de eventos) que coincida con tus criterios. Actúan como grupos lógicos de filtros.

En el ejemplo Convierte tu búsqueda en una regla de YARA-L, $e representa todos los accesos fallidos de los usuarios.		 $e.metadata.event_type = "USER_LOGIN"
Variable de marcador de posición Asigna un evento a un nombre común al que puedes hacer referencia más adelante en la consulta. Para obtener más información, consulta Usa variables de marcador de posición. $userid = $e.principal.user.userid
Sección match Define tus agrupaciones y especifica un período compatible. En el ejemplo Convierte tu búsqueda en una regla de YARA-L, la agrupación match: $userid over day agrupa correctamente los eventos por ID de usuario dentro de cada período de 24 horas (1d).

Cuando escribes una regla, debes especificar un período de tiempo admitido para definir tu período de visualización. Puedes implementar una ventana de salto, deslizante o tumbling según tus requisitos lógicos. El uso del operador over crea explícitamente una ventana de salto. 		$userid over 1d
Sección outcome Realiza agregaciones estadísticas o captura variables específicas para que las alertas resultantes sean más informativas.

Usa la función count() en $e.metadata.id para agregar eventos dentro de cada grupo match. También puedes asignar variables, como $userid, para capturar campos específicos del UDM y proporcionar más contexto en el resultado de detección.		 $failed_count = count($e.metadata.id)
Sección condition Es obligatorio para que una regla genere una detección.

Define tu umbral de detección en la sección condition. Por ejemplo, para usar #e > 5, el recuento de eventos debe superar los cinco (5) para activar una alerta. Si no realizas cálculos, de todas maneras necesitas una sección condition y debes indicar la existencia de la variable de evento (por ejemplo, #e).

Analiza el modelo de referencia de tu entorno para establecer umbrales que detecten la actividad sospechosa y, al mismo tiempo, minimicen los falsos positivos. Si no realizas cálculos, aún necesitas una sección condition y declarar la existencia de la variable del evento, como #e.		 #e > 5 o $e

Para comprender cómo funciona esta estructura, consulta el siguiente ejemplo.

Ejemplo: Detecta ataques de fuerza bruta (múltiples accesos fallidos)

  • En el siguiente ejemplo, se detectan varios intentos de acceso fallidos para un solo usuario en un período de 24 horas:

    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
}

Para convertir una búsqueda finalizada en una regla confiable para generar detecciones, generalmente sigues estos pasos:

  1. En Google SecOps, ve al Editor de reglas.
  2. Inicia una regla nueva.
  3. Pega la búsqueda y modifícala para que se ajuste a la estructura de la regla, incluidos los siguientes elementos:
    • Sección meta: Define la regla de metadatos, incluido el nombre, el autor y el nivel de gravedad de la regla.
    • Sección event: Obligatoria. A diferencia de la búsqueda, debes tener un encabezado de sección event con nombre.
    • Variables de evento: Declaran y hacen referencia a eventos específicos (o grupos de eventos) dentro de tu lógica.
    • Sección match con períodos admitidos: Especifica tus claves de agrupación y define los parámetros de tiempo (por ejemplo, 5m o 1d). Nota: Si usas una sección match en las reglas, debes agregar un período.
    • Sección condition: Define la lógica o el umbral final que se debe cumplir para activar una regla.

Avanzado: Crea una regla de varios eventos

Usas una regla de varios eventos para correlacionar diferentes tipos de actividad que ocurren en un período específico. En lugar de analizar un solo evento, conectas varios eventos, como el acceso de un usuario y, luego, la descarga inmediata de un archivo inusual, para identificar amenazas complejas.

Una regla de varios eventos requiere las siguientes secciones:

  • meta: Contiene el nombre de la regla y los detalles descriptivos.
  • events: Define tus fuentes de datos y filtros con variables de eventos.
  • match: Establece el período y la variable de marcador de posición que se usa para conectar tus eventos.
  • outcomeCaptura contexto adicional para la alerta. Las reglas de eventos múltiples requieren una función de agregación.
  • condition: Especifica qué variables de evento deben existir para que se active la regla.

Para crear una regla de varios eventos, haz lo siguiente:

  1. Define tus variables de evento: En la sección de eventos, define $e1 para capturar eventos de "PROCESS_LAUNCH" y $e2 para capturar hashes de archivos maliciosos específicos.
  2. Correlaciona con marcadores de posición: Usa la variable de marcador de posición $user para conectar estos dos flujos de eventos distintos con un ID de usuario principal compartido (por ejemplo, $user = $e1.principal.user.userid and $user = $e2.principal.user.userid).
  3. Agrupa la coincidencia: En la sección match, especificas que estos eventos deben ocurrir para el mismo $user dentro de un período establecido, como 5 minutos (5m).

Ejemplo: Crea una regla de varios eventos

  • En el siguiente ejemplo, $e1 representa un evento PROCESS_LAUNCH y $e2 representa un evento con un hash malicioso específico. La variable de marcador de posición $user correlaciona estos eventos con el mismo ID de usuario 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
}

Los siguientes componentes de la regla describen la lógica que se usa en el ejemplo:

  • Variables de eventos: Se definieron dos variables de eventos, $e1 y $e2. Se usó la variable de marcador de posición $user para unir estos eventos en el campo común userid.
  • Sección match: Se incluyó una sección match para esta regla de varios eventos para agrupar por usuario y especificar un período de salto de cinco minutos (5m) para correlacionar los eventos.
  • Sección condition: Se define la lógica para activar la alerta. En este ejemplo, se activa una alerta si existe el primer o el segundo evento.

Usa otras herramientas para crear tu búsqueda

Estas herramientas son complementos esenciales para escribir, validar y acelerar la adopción de YARA-L:

  • Herramienta de búsqueda de UDM: Busca y consulta rápidamente nombres de campos, definiciones y tipos de datos de UDM directamente en la IU. Si el ID del campo es desconocido, prioriza la verificación de esta referencia.
  • Búsqueda de lenguaje natural a YARA-L: En la barra de búsqueda, ingresa descripciones para redactar tu consulta inicial, obtener sugerencias de YARA-L correspondientes o traducirlas.
  • Traductor de SPL a YARA-L (herramienta de Labs): Si estás migrando desde plataformas de la competencia, usa esta herramienta (disponible en la sección Labs) para convertir las consultas heredadas de SPL de Splunk a YARA-L. Esto genera un punto de partida estructurado, lo que acelera la migración y define mejor la lógica de detección. Para usar la herramienta de Labs, en Google SecOps, ve a yourinstancename.chronicle.security/labs.

¿Qué sigue?

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