Problemas conocidos de YARA-L 2.0
Este documento está dirigido a los ingenieros de detección que desean depurar la lógica de las reglas y optimizar la ejecución de YARA-L 2.0. En él, se explica cómo controlar los comportamientos no estándar del motor, como la anulación de anidamiento de campos, la expansión del producto cartesiano en las agregaciones y la coherencia eventual del enriquecimiento. Si sigues estos métodos, puedes evitar errores de lógica que generen valores de resultados inflados o detecciones omitidas.
YARA-L 2.0 usa un modelo de ejecución que expande los campos repetidos en filas de eventos individuales durante la evaluación. Debido a que esta transformación se produce a nivel del motor, hacer referencia a varios campos repetidos o realizar operaciones aritméticas en tipos de modelo de datos unificado (UDM) sin firma requiere soluciones de sintaxis para evitar errores del compilador, errores de tiempo de ejecución o conjuntos de resultados incorrectos. En este documento, se describen estas restricciones técnicas y los patrones lógicos que las resuelven.
Antes de comenzar
Asegúrate de que tu cuenta tenga los siguientes derechos técnicos antes de probar o modificar las reglas de YARA-L 2.0:
Roles de IAM obligatorios
roles/chronicle.viewer(Visualizador de operaciones de seguridad): Permite ver las reglas existentes y los metadatos de detección.roles/chronicle.editor(Editor de operaciones de seguridad): Para modificar la lógica de la regla y guardar los cambios.
Permisos necesarios
chronicle.rules.runTest: Es obligatorio para ejecutar la función Ejecutar prueba en los datos históricos.chronicle.detections.get: Para inspeccionar el resultado de los eventos no anidados en el panel de detección.
Terminología clave
- UDM (modelo de datos unificado): Es el esquema normalizado que se usa para estructurar toda la telemetría de seguridad transferida en la plataforma.
- Anulación de anidamiento: Es la expansión a nivel del motor de un solo evento de UDM que contiene un campo repetido (array) en varias filas. Cada fila representa un elemento único del array, lo que puede generar una multiplicación de filas durante la evaluación de la regla.
- T₀ (ejecución inicial): Es la primera ejecución de una regla en la telemetría entrante. Esto ocurre durante la fase de "transmisión", a menudo antes de que finalicen los procesos de enriquecimiento en segundo plano (como las correcciones de GeoIP o ASN).
Agregaciones de resultados con desanidación de campos repetidos
Cuando una regla hace referencia a un campo repetido en una variable de evento con varios elementos, cada elemento se divide en una fila de evento independiente.
Por ejemplo, las dos direcciones IP del campo repetido target.ip en el evento $e se dividen en dos instancias de $e, cada una con un valor de target.ip diferente.
rule outbound_ip_per_app {
meta:
events:
$e.principal.application = $app
match:
$app over 10m
outcome:
$outbound_ip_count = count($e.target.ip) // yields 2.
condition:
$e
}
Registros de eventos: antes y después de anular la anidación
En las tablas de esta sección, se muestra cómo un solo evento que contiene un array de direcciones IP se transforma en dos registros distintos.
Antes de anular la anidación
En la siguiente tabla, se muestra el registro de eventos antes de anular la anidación del campo repetido:
| metadata.id | principal.application | target.ip |
|---|---|---|
aaaaaaaaa |
Google SecOps |
[192.0.2.20, 192.0.2.28] |
Después de anular la anidación,
En la siguiente tabla, se muestra el registro de eventos después de anular la anidación del campo repetido:
| metadata.id | principal.application | target.ip |
|---|---|---|
aaaaaaaaa |
Google SecOps |
192.0.2.20 |
aaaaaaaaa |
Google SecOps |
192.0.2.28 |
Campos repetidos anidados (producto cartesiano)
Cuando una regla hace referencia a un campo repetido anidado dentro de otro, como security_results.action, la anulación del anidamiento se produce en ambos niveles (superior y secundario) de forma simultánea. Esto genera un producto cartesiano de todos los elementos.
En el siguiente ejemplo, un evento $e con dos valores repetidos en security_results y dos valores repetidos
en security_results.actions se desanidan en cuatro instancias.
rule security_action_per_app {
meta:
events:
$e.principal.application = $app
match:
$app over 10m
outcome:
$security_action_count = count($e.security_results.actions) // yields 4.
condition:
$e
}
Registro de eventos antes de la anulación de anidación
El registro original almacena las acciones dentro de una estructura de array anidada.
| metadata.id | principal.application | security_results |
|---|---|---|
aaaaaaaaa |
Google SecOps |
[ { actions: [ ALLOW, FAIL ] }, { actions: [ CHALLENGE, BLOCK ] } ] |
Registros de eventos después de la anidación anidada
Después de la expansión, cada acción única se convierte en su propia fila, lo que puede generar recuentos inesperados en agregaciones no distintas.
| metadata.id | principal.application | security_results.actions |
|---|---|---|
aaaaaaaaa |
Google SecOps |
PERMITIR |
aaaaaaaaa |
Google SecOps |
REPROBADA |
aaaaaaaaa |
Google SecOps |
DESAFÍO |
aaaaaaaaa |
Google SecOps |
BLOQUEAR |
Impacto en campos no relacionados
Este comportamiento de anulación de anidamiento en la evaluación de reglas puede producir agregaciones de resultados inesperadas cuando la regla hace referencia a uno o más campos repetidos con un campo superior que también es un campo repetido. Las agregaciones no distintas,
como sum(), array() y count(), no pueden tener en cuenta los valores duplicados en
otros campos del mismo evento que produce el comportamiento de anulación de anidamiento.
En el siguiente ejemplo, el evento $e tiene un solo nombre de host (google.com), pero el resultado (hostnames)
se agrega en cuatro instancias sin anidar del mismo evento $e, cada una con un valor
principal.hostname duplicado. Este resultado genera cuatro nombres de host (en lugar de uno)
debido a la anulación de la anidación de valores repetidos en security_results.actions.
rule security_action_per_app {
meta:
events:
$e.principal.application = $app
match:
$app over 10m
outcome:
$hostnames = array($e.principal.hostname) // yields 4.
$security_action_count = count($e.security_results.action) // yields 4.
condition:
$e
}
Registro de eventos antes de la anulación de la anidación con campos no relacionados
El nombre de host es un valor único, pero se encuentra junto a los resultados de seguridad repetidos.
| metadata.id | principal.application | principal.hostname | security_results |
|---|---|---|---|
aaaaaaaaa |
Google SecOps |
google.com |
[ { action: [ ALLOW, FAIL ] }, { action: [ CHALLENGE, BLOCK ] } ] |
Registro de eventos después de anular el anidamiento con campos no relacionados
El nombre de host ahora se duplica en cuatro filas, lo que hace que la función array() lo recoja cuatro veces.
| metadata.id | principal.application | principal.hostname | security_results.action |
|---|---|---|---|
aaaaaaaaa |
Google SecOps |
google.com |
PERMITIR |
aaaaaaaaa |
Google SecOps |
google.com |
REPROBADA |
aaaaaaaaa |
Google SecOps |
google.com |
DESAFÍO |
aaaaaaaaa |
Google SecOps |
google.com |
BLOQUEAR |
Solución alternativa para el comportamiento de anidación
Para asegurarte de que los valores de los resultados sean precisos cuando se produzca la anidación, usa la versión distinta de la agregación seleccionada. Las siguientes funciones ignoran las filas duplicadas que se crean cuando se anulan los anidamientos:
max()min()array_distinct()count_distinct()
Agregaciones de resultados con múltiples variables de eventos
Si una regla contiene varias variables de evento, hay un elemento independiente en la agregación para cada combinación de eventos que se incluye en la detección. Por ejemplo, si la siguiente regla de ejemplo se ejecuta en los eventos de la lista:
events:
$e1.field = $e2.field
$e2.somefield = $ph
match:
$ph over 1h
outcome:
$some_outcome = sum(if($e1.otherfield = "value", 1, 0))
condition:
$e1 and $e2
event1:
// UDM event 1
field="a"
somefield="d"
event2:
// UDM event 2
field="b"
somefield="d"
event3:
// UDM event 3
field="c"
somefield="d"
La suma se calcula sobre cada combinación de eventos, lo que te permite usar ambas variables de evento en los cálculos del valor del resultado. En el cálculo, se usan los siguientes elementos:
1: $e1 = event1, $e2 = event2
2: $e1 = event1, $e2 = event3
3: $e1 = event2, $e2 = event1
4: $e1 = event2, $e2 = event3
5: $e1 = event3, $e2 = event1
5: $e1 = event3, $e2 = event2
Esto genera una suma máxima potencial de 6, aunque $e2 solo puede corresponder a 3 eventos distintos.
Esto afecta a la suma, el recuento y el array. Para el recuento y el array, usar count_distinct
o array_distinct puede resolver el problema, pero no hay una solución alternativa
para la suma.
Paréntesis al comienzo de una expresión
No se admite comenzar una expresión con paréntesis, ya que se genera un error de análisis en el editor de reglas.
Sintaxis no válida
parsing: error with token: ")"
invalid operator in events predicate
En el siguiente ejemplo, se genera este tipo de error:
($event.metadata.ingested_timestamp.seconds -
$event.metadata.event_timestamp.seconds) / 3600 > 1
Variaciones de sintaxis válidas
Las siguientes variaciones de sintaxis devuelven el mismo resultado, pero con una sintaxis válida:
$event.metadata.ingested_timestamp.seconds / 3600 -
$event.metadata.event_timestamp.seconds / 3600 > 1
1 / 3600 * ($event.metadata.ingested_timestamp.seconds -
$event.metadata.event_timestamp.seconds) > 1
1 < ($event.metadata.ingested_timestamp.seconds -
$event.metadata.event_timestamp.seconds) / 3600
El array de índices en el resultado requiere agregación
No se permite indexar directamente un array dentro de la sección outcome para campos repetidos. Requiere una variable de marcador de posición temporal.
outcome:
$principal_user_dept = $suspicious.principal.user.department[0]
Solución alternativa
Captura el índice de array específico en una variable de marcador de posición dentro de la sección events y, luego, haz referencia a ese marcador de posición en tu resultado.
events:
$principal_user_dept = $suspicious.principal.user.department[0]
outcome:
$principal_user_department = $principal_user_dept
Condición OR con inexistencia
Si aplicas una condición OR entre dos variables de evento independientes y la regla coincide con la inexistencia, la regla se compila correctamente, pero puede producir detecciones de falsos positivos.
Por ejemplo, la siguiente sintaxis de regla puede coincidir con eventos que tienen $event_a.field = "something", aunque no debería:
events:
not ($event_a.field = "something" **or** $event_b.field = "something")
condition:
$event_a and #event_b >= 0
Solución alternativa
Separa las verificaciones de inexistencia en bloques individuales para cada variable para mantener la integridad de la lógica.
events:
not ($event_a.field = "something")
not ($event_b.field = "something")
condition:
$event_a and #event_b >= 0
Aritmética con campos de eventos sin firma
Si usas un literal de número entero en una operación aritmética (+, -, *) o de módulo (%)
con un campo de UDM de número entero sin firma, se produce un error. Los literales de números enteros estándar se establecen de forma predeterminada en números enteros de 64 bits con firma (INT64), que son incompatibles con los campos de UDM definidos como números enteros de 64 bits sin firma (UINT64), como network.received_bytes, network.sent_bytes y principal.file.size.
Esta restricción de escritura estricta se aplica a las secciones events y outcome,
incluidas las agregaciones sum() o max() y las expresiones
divisorias. El verificador de sintaxis de YARA-L trata los números enteros con signo y sin signo
como un tipo int genérico. Como resultado, una regla que mezcla campos de UDM UINT64 y
literales enteros INT64 podría pasar la validación de sintaxis en el momento de guardarla, pero fallar durante
la ejecución de la regla o cuando haces clic en Ejecutar prueba. Cuando la regla falla, genera
un "Error de regla" genérico
(cannot complete [arithmetic/mod] operation between unsigned and signed integer).
Por ejemplo, la siguiente comparación de events pasa la validación de sintaxis cuando
se guarda, pero falla durante la ejecución porque $e.network.received_bytes (UINT64)
se multiplica por el literal de número entero con signo 2 (INT64):
events:
$total_bytes = $e.network.total_bytes
$total_bytes = $e.network.received_bytes * 2
Soluciones alternativas
Puedes resolver esta discrepancia de tipos con cualquiera de los siguientes métodos:
- Conversión de números enteros explícitos (
cast.as_int()ocast.as_uint()): Convierte el campo de UDM sin firma en un número entero con firma concast.as_int()o convierte el literal de número entero en un número entero sin firma concast.as_uint(). Usa este método cuando necesites un resultado de número entero o cuando uses el operador de módulo (%), que solo acepta operandos de números enteros. - Coerción de punto flotante: Fuerza a la constante de número entero a comportarse como un
floatcon un literal de punto flotante, como2.0o100.0. En las expresiones sin otros operadores de división en la misma línea, también puedes usar una operación de división, como(2/1). En las expresiones que ya contienen operadores de división (/), usa literales de punto flotante ocast.as_int()en lugar de la coerción de división(N/1). Varios caracteres/en la misma línea se pueden interpretar como un literal de expresión regular, lo que provoca un error de análisis durante la compilación o interrumpe el resaltado de sintaxis en el editor de reglas.
Solución alternativa en la sección events
Usa cast.as_int(), un literal de punto flotante o una coerción de división para corregir el
error en la sección events:
Usa
cast.as_int():events: $total_bytes = $e.network.total_bytes $total_bytes = cast.as_int($e.network.received_bytes) * 2Usa un literal de punto flotante:
events: $total_bytes = $e.network.total_bytes $total_bytes = $e.network.received_bytes * 2.0Usa la coerción de división:
events: $total_bytes = $e.network.total_bytes $total_bytes = $e.network.received_bytes * (2/1)
Solución alternativa en la sección outcome
La siguiente expresión outcome se guarda sin un error de sintaxis, pero falla en
el entorno de ejecución porque sum($e.network.sent_bytes) y
sum($e.network.received_bytes) devuelven valores UINT64 que se combinan con
los literales INT64 con signo 100 y 1:
outcome:
// Saves, but fails at runtime:
$upload_ratio_pct = sum($e.network.sent_bytes) * 100 / (sum($e.network.received_bytes) + 1)
Vuelve a escribir la expresión con literales de punto flotante o cast.as_int() para que
se guarde y ejecute sin errores:
Usa literales de punto flotante:
outcome: $upload_ratio_pct = sum($e.network.sent_bytes) * 100.0 / (sum($e.network.received_bytes) + 1.0)Usa
cast.as_int():outcome: $upload_ratio_pct = sum(cast.as_int($e.network.sent_bytes)) * 100 / (sum(cast.as_int($e.network.received_bytes)) + 1)
Variables de búsqueda y coincidencia de cadenas que no distinguen mayúsculas de minúsculas
En la búsqueda de Google Security Operations, las consultas no distinguen mayúsculas de minúsculas de forma predeterminada.
Cuando ejecutas una consulta estadística (con match: y outcome:) con la búsqueda que no distingue mayúsculas de minúsculas habilitada, las variables de cadena en la sección match: se convierten automáticamente en minúsculas (strings.to_lower()) para agruparlas durante la compilación de la consulta.
Como resultado, las columnas match: de los resultados de tus estadísticas contienen valores en minúsculas,
en lugar de las mayúsculas y minúsculas originales almacenadas. Este comportamiento puede ser destructivo
para los campos de cadena que distinguen mayúsculas de minúsculas, como las líneas de comandos codificadas en Base64, los tokens,
las URLs o las rutas de acceso que distinguen mayúsculas de minúsculas, lo que impide la decodificación o evaluación adecuadas.
Para solucionar este comportamiento, realiza una de las siguientes acciones:
- Proyecta campos sin procesar en los resultados: Los campos proyectados en la sección
outcome:con agregaciones comoarray_distinct(...),max(...)omin(...)no se convierten en minúsculas y conservan su uso de mayúsculas original. Si necesitas ver las mayúsculas y minúsculas originales de las cadenas agrupadas, proyecta el campo sin procesar en la secciónoutcome:conarray_distinct(...). - Usa la búsqueda que distingue mayúsculas de minúsculas: Como alternativa, puedes cambiar el modo de Búsqueda a
Distingue mayúsculas de minúsculas. Ten en cuenta que esto también hace que la agrupación
match:distinga mayúsculas de minúsculas.
Enriquecimiento de GeoIP y coherencia eventual
El sistema prioriza la velocidad por sobre la exactitud inmediata en las etapas iniciales de enriquecimiento (transmisión y sensible a la latencia), lo que puede generar datos faltantes y posibles falsos positivos. El sistema sigue enriqueciendo los datos en segundo plano, pero es posible que no estén disponibles cuando se ejecute la regla. Esto forma parte del proceso normal de coherencia eventual.
Para evitar falsos positivos causados por el retraso en el enriquecimiento, verifica de forma explícita que el campo no esté vacío antes de evaluar su valor.
Por ejemplo, considera este evento de regla:
$e.principal.ip_geo_artifact.network.asn = "16509" AND
$e.principal.ip_geo_artifact.location.country_or_region = "United Kingdom"
La regla se basa en el hecho de que el evento debe tener $e.principal.ip_geo_artifact.network.asn = "16509" Y $e.principal.ip_geo_artifact.location.country_or_region = "United Kingdom", que son campos enriquecidos. Si el enriquecimiento no se completa a tiempo, la regla producirá un falso positivo.
Para evitar esto, una mejor verificación de esta regla sería la siguiente:
$e.principal.ip_geo_artifact.network.asn != "" AND
$e.principal.ip_geo_artifact.network.asn = "16509" AND
$e.principal.ip_geo_artifact.location.country_or_region != "" AND
$e.principal.ip_geo_artifact.location.country_or_region = "United Kingdom"
Esta regla elimina la posibilidad de que el evento se active por IPs con el ASN 16509, pero ubicadas fuera del Reino Unido. Esto mejora la precisión general de la regla.
Obtén más información para solucionar problemas del retraso de enriquecimiento.
Soluciona problemas
En esta sección, se describen las expectativas de rendimiento y se proporcionan correcciones de autoservicio para problemas comunes en los que el comportamiento de la detección en vivo difiere de los resultados de las pruebas.
Eventos con fecha futura
Las reglas de varios eventos están diseñadas para procesar eventos en orden cronológico en relación con la transferencia. Si especificas y activas una regla de varios eventos, no se crean detecciones para eventos con marcas de tiempo futuras, por ejemplo, cuando el event.timestamp tiene una fecha y hora establecidas después de la ingest.timestamp.
Retraso de enriquecimiento
Google SecOps prioriza la velocidad de transferencia para exponer las alertas iniciales lo más rápido posible. Sin embargo, los procesos de enriquecimiento en segundo plano, como la resolución de metadatos de GeoIP, ASN o UDM, siguen un modelo de coherencia eventual.
Ejecución inicial (T₀)
Es posible que el motor en vivo evalúe una regla antes de que se complete el enriquecimiento en segundo plano. Según si tu lógica se basa en campos enriquecidos para detecciones o exclusiones, esto puede generar las siguientes discrepancias temporales:
Falsos negativos (retraso en la detección): Este es un resultado común. Si una regla depende de un campo enriquecido para activarse (por ejemplo,
target.user.department == "Finance") y ese campo esnull, la regla no coincide durante la ejecución inicial.Falsos positivos (omisión de exclusión): Si tu regla usa campos enriquecidos para filtrar la actividad conocida como buena (por ejemplo,
NOT target.ip_geo_country == "US"), la regla puede activar un falso positivo porque los datos de "exclusión" aún no se aplicaron.
Ejecuciones de regularización
Estas ejecuciones en segundo plano vuelven a evaluar los datos después de un retraso (por ejemplo, 4 o 30 horas). Esto "ajusta" los estados de detección de la siguiente manera:
Detecciones tardías: Son los eventos que eran "falsos negativos" en T₀ y que ahora producen una detección una vez que se finaliza el enriquecimiento.
Corrección: Los falsos positivos de T₀ permanecen en el sistema, pero los datos enriquecidos por completo se pueden ver en el visualizador de UDM para la clasificación manual.
Discrepancia en la prueba de ejecución
La herramienta Ejecutar prueba opera con datos históricos que ya se conciliaron. Como los datos están completamente enriquecidos cuando ejecutas una prueba manual, puedes ver los resultados de "ajuste" de inmediato. Esto significa que no verás los falsos negativos de T₀ ni los falsos positivos basados en exclusiones que se produjeron durante la ejecución inicial en vivo.
Corrección de errores
Usa la siguiente tabla para resolver las discrepancias entre las alertas en vivo y los resultados de las pruebas.
| Problema | Descripción | Corrección práctica |
|---|---|---|
| Falla de exclusión | Se activa una regla a pesar de una exclusión (por ejemplo, != "ASN_123") porque el campo era nulo durante la ejecución inicial. |
Agrega una verificación de valor no nulo a la sección de eventos para asegurarte de que los datos se enriquezcan antes de la evaluación, por ejemplo:$e.principal.ip_geo_artifact.network.asn != ""
|
| Comparación entre el partido en vivo y el de prueba | Las reglas activas activan alertas, pero la opción Ejecutar prueba en los mismos datos muestra "No Results". |
Agrega $e.field != "", que verifica todos los campos enriquecidos (GeoIP, ASN, File Path) para sincronizar el comportamiento histórico y en vivo. |
| Faltan metadatos | Las detecciones aparecen en el panel con campos GeoIP o File Path vacíos. |
Esto es lo que se espera para las ejecuciones de T0. Para solucionar este problema, incluye una verificación de field != "" o configura un retraso de liquidación en tu programa de reglas para permitir más tiempo para la transferencia.
|
Validación y prueba
Para verificar que una regla controle correctamente el enriquecimiento retrasado, haz lo siguiente:
Identifica el retraso: Busca una detección que creas que es un falso positivo. En la columna Tipo de detección, busca el ícono
<span class="material-icons">lightbulb</span>. Las alertas sin este ícono provienen de la ejecución principal, en la que el retraso de enriquecimiento es más común.Actualiza la lógica de la regla: Agrega una verificación de
field != ""para todos los datos enriquecidos que se usan en tu lógica.
Ejemplo (ruta de acceso del archivo):
$e.target.process.parent_process.file.full_path != ""Prueba y verifica:
- Usa la función Ejecutar prueba para asegurarte de que tu lógica aún coincida con los datos históricos previstos.
- Verifica que la regla ahora solo se active (o excluya correctamente) durante las ejecuciones de ajuste una vez que se propaguen los campos de enriquecimiento.
Para obtener más información, consulta Información sobre la programación de la ejecución de reglas y Configura programaciones personalizadas para las reglas.
¿Necesitas más ayuda? Obtén respuestas de miembros de la comunidad y profesionales de Google SecOps.