Sintaxis de la sección de resultados

Se admite en los siguientes sistemas operativos:

La sección outcome de una consulta en YARA-L define las variables de resultado que especifican el resultado de una búsqueda y una consulta de panel, además de contexto e información adicionales para una detección cuando se activa una regla. Estas variables se pueden usar para diversos fines, como mostrar datos relevantes en los paneles y crear puntuaciones de riesgo.

Sección Define outcome

Usa el carácter $, seguido de un nombre de variable, para definir una variable de resultado en la sección outcome de una sola consulta. Puedes definir hasta 20 variables de resultado. Los nombres de las variables en sí son arbitrarios. En el caso de las reglas, los valores de resultado se calculan y agregan en función de cada detección.

A cada variable de resultado se le asigna un valor con una expresión.

Esta regla busca inicios de sesión fallidos desde una ubicación nueva:

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
}

La sección outcome realiza agregaciones en las variables de eventos y marcadores de posición: cuenta los inicios de sesión fallidos, cuenta las IPs distintas y obtiene la hora en que ocurrió la falla.

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

Si incluyes y completas la variable de resultado especial $risk_score, su valor (número entero o de punto flotante) se mostrará en la página Alertas y IoCs para las alertas generadas por la búsqueda.

Si no incluyes una variable $risk_score en la sección outcome de una búsqueda, se establecerá uno de los siguientes valores predeterminados:

  • Si la búsqueda está configurada para generar una alerta, $risk_score se establece en 40.

  • Si la consulta no está configurada para generar una alerta, $risk_score se establece en 15.

El valor de $risk_score se almacena en el campo security_result.risk_score del UDM.

Variable de resultado de la puntuación de riesgo

El análisis de riesgo de Google SecOps asocia automáticamente las detecciones y las alertas a las entidades relacionadas con ellas. La variable de resultado risk_score se usa para asignar un importe de riesgo. Si no se establece este valor, se usa el valor predeterminado de detección o alerta. Puedes configurar valores predeterminados en Configuración.

Para garantizar la coherencia en toda la plataforma, te recomendamos que uses los siguientes rangos de puntuación cuando asignes un risk_score a tus detecciones personalizadas. Esta alineación ayuda a estandarizar la priorización de alertas y los flujos de trabajo de respuesta.

Gravedad Rango de puntuación Descripción Ejemplo
Alerta: Crítica 90 a 100 Compromiso activo con el potencial de tener un impacto más allá de una sola cuenta de usuario o endpoint. Requiere revisión inmediata. Se ejecutó Mimikatz en el controlador de dominio.
Alerta: Alta 80 a 89 Compromiso activo de un solo extremo o entidad Debe recibir una revisión inmediata. El servidor de producción llama a un C2 conocido y reciente.
Alertas: nivel medio 50 a 79 Posible problema de seguridad que requiere investigación. No se confirmó un ataque, pero es posible derivar el caso. Una credencial expuesta sin indicios de uso inadecuado.
Sin alertas: baja 20 a 49 Es un evento de seguridad de bajo impacto que, cuando se combina con otros indicadores u observaciones, podría generar un incidente más significativo. Por lo general, no se necesita revisión y se puede combinar con otras detecciones a través de reglas compuestas para crear una alerta. Análisis de puertos internos
Observaciones sin alertas 1 a 19 Por lo general, son detecciones basadas en información que tienen como objetivo generar conciencia situacional sobre una amenaza. Por lo general, no requiere revisión y se puede combinar con otras detecciones a través de reglas compuestas para generar alertas. Un evento de acceso, sin indicios de uso inadecuado.

Dado que risk_score es una variable de resultado, tus reglas pueden expresar matices según factores como la inteligencia sobre amenazas o cualquier otra condición simultánea.

Las puntuaciones de riesgo de entidad se pueden usar para generar alertas basadas en el riesgo casi en tiempo real. Para obtener más información, consulta la Descripción general de Risk Analytics.

Tipos de datos de las variables de resultado

Cada variable de resultado puede tener un tipo de datos diferente, que se determina según la expresión que se usa para calcularla. En Google SecOps, se admiten los siguientes tipos de datos de resultados:

  • integer
  • flota
  • cadena
  • Listas de números enteros
  • Listas de números de punto flotante
  • listas de cadenas

Lógica condicional

Puedes usar la lógica condicional para calcular el valor de un resultado. Las condiciones se especifican con el siguiente patrón de sintaxis:

if(BOOL_CLAUSE, THEN_CLAUSE)
if(BOOL_CLAUSE, THEN_CLAUSE, ELSE_CLAUSE)

Puedes leer una expresión condicional como "si BOOL_CLAUSE es verdadero, devuelve THEN_CLAUSE; de lo contrario, devuelve ELSE_CLAUSE".

BOOL_CLAUSE debe evaluarse como un valor booleano. Una expresión BOOL_CLAUSE adopta una forma similar a las expresiones de la sección events. Por ejemplo, puede contener lo siguiente:

  • Nombres de campos de UDM con operador de comparación:

    if($context.graph.entity.user.title = "Vendor", 100, 0)

  • Variable de marcador de posición que se definió en la sección events:

    if($severity = "HIGH", 100, 0)

  • Otra variable de resultado definida en la sección outcome:

    if($risk_score > 20, "HIGH", "LOW")

  • Funciones que devuelven un valor booleano:

    if(re.regex($e.network.email.from, `.*altostrat.com`), 100, 0)

  • Buscar en una lista de referencia:

    if($u.principal.hostname in %my_reference_list_name, 100, 0)

  • Comparación de la agregación:

    if(count($login.metadata.event_timestamp.seconds) > 5, 100, 0)

THEN_CLAUSE y ELSE_CLAUSE deben tener el mismo tipo de datos. Admitimos números enteros, números de punto flotante y cadenas.

Puedes omitir ELSE_CLAUSE si el tipo de datos es un número entero o un número de punto flotante. Si se omite, ELSE_CLAUSE se evalúa como 0. Por ejemplo:

`if($e.field = "a", 5)` is equivalent to `if($e.field = "a", 5, 0)`

Debes proporcionar ELSE_CLAUSE si el tipo de datos es una cadena o si THEN_CLAUSE es una variable de marcador de posición o una variable de resultado.

Operaciones matemáticas

Puedes usar operaciones matemáticas para calcular el tipo de datos de número entero o de número de punto flotante en las secciones outcome y events de una consulta. Google Security Operations admite la suma, la resta, la multiplicación, la división y el módulo como operadores de nivel superior en un cálculo.

El siguiente fragmento es un ejemplo de cálculo en la sección outcome:

outcome:
  $risk_score = max(100 + if($severity = "HIGH", 10, 5) - if($severity = "LOW", 20, 0))

Se permiten las operaciones matemáticas en los siguientes tipos de operandos, siempre y cuando cada operando y la expresión aritmética completa se agreguen correctamente (consulta Agregaciones):

  • Campos de eventos numéricos
  • Variables de marcador de posición numéricas definidas en la sección events
  • Variables de resultado numéricas definidas en la sección outcome
  • Funciones que devuelven números enteros o de punto flotante
  • Agregaciones que devuelven números enteros o de punto flotante

El módulo no se permite en números de punto flotante.

Variables de marcador de posición en los resultados

Cuando calcules las variables de resultado, puedes usar variables de marcador de posición que se definieron en la sección de eventos de tu consulta. En este ejemplo, supón que $email_sent_bytes se definió en la sección de eventos de la regla:

Ejemplo: Evento único sin sección de coincidencias

// No match section, so this is a single-event query.

outcome:
  // Use placeholder directly as an outcome value.
  $my_outcome = $email_sent_bytes

  // Use placeholder in a conditional.
  $other_outcome = if($file_size > 1024, "SEVERE", "MODERATE")

condition:
  $e

Ejemplo: Evento múltiple con sección de partidos

match:
  // This is a multi event query with a match section.
  $hostname over 5m

outcome:
  // Use placeholder directly in an aggregation function.
  $max_email_size = max($email_sent_bytes)

  // Use placeholder in a mathematical computation.
  $total_bytes_exfiltrated = sum(
    1024
    + $email_sent_bytes
    + $file_event.principal.file.size
  )

condition:
  $email_event and $file_event

Variables de resultado en expresiones de asignación de resultados

Las variables de resultado se pueden usar para derivar otras variables de resultado, de manera similar a las variables de marcador de posición definidas en la sección events. Puedes hacer referencia a una variable de resultado en la asignación de otra variable de resultado con un token $ seguido del nombre de la variable. Las variables de resultado se deben definir antes de que se pueda hacer referencia a ellas en el texto de la búsqueda. Cuando se usan en una expresión de asignación, las variables de resultado no deben agregarse (consulta Agregaciones).

En el siguiente ejemplo, la variable de resultado $risk_score deriva su valor de la variable de resultado $event_count:

Ejemplo: Variable de resultado derivada de otra variable de resultado

match:
  // This is a multi event query with a match section.
  $hostname over 5m

outcome:
  // Aggregates all timestamp on login events in the 5 minute match window.
  $event_count = count($login.metadata.event_timestamp.seconds)

  // $event_count cannot be aggregated again.
  $risk_score = if($event_count > 5, "SEVERE", "MODERATE")

  // This is the equivalent of the 2 outcomes combined.
  $risk_score2 = if(count($login.metadata.event_timestamp.seconds) > 5, "SEVERE", "MODERATE")

condition:
  $e

Las variables de resultado se pueden usar en cualquier tipo de expresión en el lado derecho de una asignación de resultado, excepto en las siguientes expresiones:

  • Agregaciones
  • Llamadas a la función Arrays.length()
  • Con modificadores any o all

Agregaciones

Los campos de eventos repetidos son valores no escalares. Es decir, una sola variable apunta a varios valores. Por ejemplo, la variable de campo del evento $e.target.ip es un campo repetido y puede tener cero, uno o muchos valores de IP. Es un valor no escalar. Mientras que la variable de campo del evento $e.principal.hostname no es un campo repetido y solo tiene 1 valor (es decir, un valor escalar).

Del mismo modo, tanto los campos de eventos no repetidos como los campos de eventos repetidos que se usan en la sección outcome de una consulta con una ventana de coincidencia son valores no escalares.

Ejemplo: Agrupa eventos con una sección de coincidencias y un campo no repetido

La siguiente consulta agrupa eventos con una sección "match" y hace referencia a un campo de evento no repetido en la sección "outcome":

rule OutcomeAndMatchWindow{
  ...
  match:
    $userid over 5m
  outcome:
    $hostnames = array($e.principal.hostname)
  ...
}

Cualquier período de 5 minutos durante el que se ejecute la consulta puede contener cero, uno o muchos eventos. La sección de resultados funciona con todos los eventos de un período de correlación. Cualquier variable de campo de evento a la que se haga referencia en la sección de resultados puede apuntar a cero, uno o muchos valores del campo en cada evento del período de correlación. Por ejemplo, si un período de 5 minutos contiene 5 eventos $e, $e.principal.hostname en la sección de resultados apunta a cinco nombres de host diferentes. La variable de campo del evento $e.principal.hostname se trata como un valor no escalar en la sección outcome de esta consulta.

Dado que las variables de resultado siempre deben producir un solo valor escalar, cualquier valor no escalar del que dependa una asignación de resultado debe agregarse para producir un solo valor escalar. En una sección de resultados, los siguientes son valores no escalares y se deben agregar:

  • Campos de eventos (repetidos o no repetidos) cuando la búsqueda usa una sección match
  • Marcadores de posición de eventos (repetidos o no repetidos) cuando la búsqueda usa una sección match
  • Campos de eventos repetidos cuando la consulta no usa una sección match
  • Marcadores de posición de eventos repetidos cuando la búsqueda no usa una sección match

Los campos de eventos escalares, los marcadores de posición de eventos escalares y las constantes se pueden incluir en funciones de agregación en consultas que no incluyen una sección match. Sin embargo, en la mayoría de los casos, estas agregaciones devuelven el valor ajustado, lo que las hace innecesarias. Una excepción es la agregación array(), que puedes usar para convertir de forma explícita un valor escalar en un array.

Las variables de resultado se tratan como agregaciones: no se deben volver a agregar cuando se hace referencia a ellas en otra asignación de resultado.

Puedes usar las siguientes funciones de agregación:

Función de agregación Descripción
max() Devuelve el máximo de todos los valores posibles. Solo funciona con números enteros y de punto flotante.
min() Genera el mínimo de todos los valores posibles. Solo funciona con números enteros y de punto flotante.
sum() Genera la suma de todos los valores posibles. Solo funciona con números enteros y de punto flotante.
count_distinct() Recopila todos los valores posibles y, luego, genera el recuento de los valores distintos posibles.
count() Se comporta como "count_distinct()", pero devuelve un recuento no distinto de los valores posibles.
array_distinct() Recopila todos los valores distintos posibles y, luego, genera una lista de estos valores. Trunca la lista de valores distintos a 1,000 elementos aleatorios. Primero, se aplica la eliminación de duplicados para obtener una lista distinta y, luego, se aplica el truncamiento.
array() Se comporta como array_distinct(), pero devuelve una lista de valores no distintos. También trunca la lista de valores a 1,000 elementos aleatorios.

La función de agregación es importante cuando una regla incluye una sección condition que especifica que deben existir varios eventos, ya que la función de agregación operará en todos los eventos que generaron la detección.

Ejemplo: Condición para varios eventos

A continuación, se muestra un ejemplo de una condición para varios eventos. Si la sección de resultado y condición contiene lo siguiente:

outcome:
  $asset_id_count = count($event.principal.asset_id)
  $asset_id_distinct_count = count_distinct($event.principal.asset_id)

  $asset_id_list = array($event.principal.asset_id)
  $asset_id_distinct_list = array_distinct($event.principal.asset_id)

condition:
  #event > 1

Dado que la sección "condition" requiere que haya más de un "event" para cada detección, las funciones de agregación operarán en varios eventos. Supongamos que los siguientes eventos generaron una detección:

event:
  // UDM event 1
  asset_id="asset-a"

event:
  // UDM event 2
  asset_id="asset-b"

event:
  // UDM event 3
  asset_id="asset-b"

Entonces, los valores de tus resultados serán los siguientes:

    $asset_id_count = 3
    $asset_id_distinct_count = 2
    $asset_id_list = `["asset-a", "asset-b", "asset-b"]
    $asset_id_distinct_list = `["asset-a", "asset-b"]

Limitaciones

  • La sección outcome no puede hacer referencia a una nueva variable de marcador de posición que no se haya definido ya en la sección events o en la sección outcome.

  • La sección outcome no puede usar variables de eventos que no se hayan definido en la sección events.

  • La sección outcome puede usar un campo de evento que no se usó en la sección events, siempre que la variable de evento a la que pertenece el campo de evento ya se haya definido en la sección events.

  • La sección outcome solo puede correlacionar variables de eventos que ya se correlacionaron en la sección events. Las correlaciones se producen cuando se igualan dos campos de eventos de diferentes variables de eventos.

Consulta la Descripción general de YARA-L 2.0 para ver ejemplos de la sección outcome.

Consulta Crea estadísticas basadas en el contexto para obtener detalles sobre la deduplicación de detecciones con la sección outcome.

¿Qué sigue?

Información adicional

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