Sintaxis del lenguaje YARA-L 2.0

En esta sección, se describen los principales elementos de la sintaxis de YARA-L. Consulta también la descripción general del lenguaje YARA-L 2.0.

Estructura de la regla

En YARA-L 2.0, debes especificar las declaraciones, las definiciones y los usos de las variables en el siguiente orden:

1. meta
2. de Innovators Live
3. coincidencia (opcional)
4. resultado (opcional)
5. de transición
6. Opciones (opcional)

En el siguiente ejemplo, se ilustra la estructura genérica de una regla:

rule <rule Name>
{
    meta:
    // Stores arbitrary key-value pairs of rule details, such as who wrote
    // it, what it detects on, version control, etc.

  events:
    // Conditions to filter events and the relationship between events.

  match:
    // Values to return when matches are found.

  outcome:
    // Additional information extracted from each detection.

  condition:
    // Condition to check events and the variables used to find matches.

  options:
    // Options to turn on or off while executing this rule.
}

Sintaxis de la sección de metadatos

La sección de metadatos se compone de varias líneas, en las que cada una define un par clave-valor. Una parte de clave debe ser una cadena sin comillas, y una parte de valor debe ser una cadena entre comillas:

<key> = "<value>"

A continuación, se muestra un ejemplo de una línea de sección meta válida:

meta:
    author = "Google"
    severity = "HIGH"

Sintaxis de la sección de eventos

En la sección events, enumera los predicados para especificar lo siguiente:

• Declaraciones de variables
• Filtros de variables de eventos
• Uniones de variables de eventos

Declaraciones de variables

Para las declaraciones de variables, usa la siguiente sintaxis:

• <EVENT_FIELD> = <VAR>
• <VAR> = <EVENT_FIELD>

Ambos son equivalentes, como se muestra en los siguientes ejemplos:

• $e.source.hostname = $hostname
• $userid = $e.principal.user.userid

Esta declaración indica que esta variable representa el campo especificado para la variable del evento. Cuando el campo del evento es un campo repetido, la variable de coincidencia puede representar cualquier valor del array. También es posible asignar varios campos de eventos a una sola variable de coincidencia o de marcador de posición. Esta es una condición de unión transitiva.

Por ejemplo:

• $e1.source.ip = $ip
• $e2.target.ip = $ip

Son equivalentes a lo siguiente:

• $e1.source.ip = $ip
• $e1.source.ip = $e2.target.ip

Cuando se usa una variable, esta se debe declarar a través de la declaración de variables. Si se usa una variable sin ninguna declaración, se considera un error de compilación.

Filtros de variables de eventos

Una expresión booleana que actúa sobre una sola variable de evento se considera un filtro.

Uniones de variables de eventos

Todas las variables de evento que se usan en la regla deben unirse con todas las demás variables de evento de una de las siguientes maneras:

• Directamente a través de una comparación de igualdad entre los campos de eventos de las dos variables de eventos unidas, por ejemplo: $e1.field = $e2.field La expresión no debe incluir aritmética.

• Indirectamente, a través de una unión transitiva que solo involucra un campo de evento (consulta la declaración de variables para obtener una definición de "unión transitiva"). La expresión no debe incluir aritmética.

Por ejemplo, si se supone que se usan $e1, $e2 y $e3 en la regla, las siguientes secciones de events son válidas.

events:
  $e1.principal.hostname = $e2.src.hostname // $e1 joins with $e2
  $e2.principal.ip = $e3.src.ip // $e2 joins with $e3

events:
  // $e1 joins with $e2 via function to event comparison
  re.capture($e1.src.hostname, ".*") = $e2.target.hostname

events:
  // $e1 joins with $e2 via an `or` expression
  $e1.principal.hostname = $e2.src.hostname
  or $e1.principal.hostname = $e2.target.hostname
  or $e1.principal.hostname = $e2.principal.hostname

events:
  // all of $e1, $e2 and $e3 are transitively joined via the placeholder variable $ip
  $e1.src.ip = $ip
  $e2.target.ip = $ip
  $e3.about.ip = $ip

events:
  // $e1 and $e2 are transitively joined via function to event comparison
  re.capture($e2.principal.application, ".*") = $app
  $e1.principal.hostname = $app

Sin embargo, estos son ejemplos de secciones events no válidas.

events:
  // Event to arithmetic comparison is an invalid join condition for $e1 and $e2.
  $e1.principal.port = $e2.src.port + 1

events:
  $e1.src.ip = $ip
  $e2.target.ip = $ip
  $e3.about.ip = "192.1.2.0" //$e3 is not joined with $e1 or $e2.

events:
  $e1.src.port = $port

  // Arithmetic to placeholder comparison is an invalid transitive join condition.
  $e2.principal.port + 800 = $port

Sintaxis de la sección de coincidencias

En la sección match, enumera las variables de coincidencia para los eventos de grupo antes de verificar las condiciones de coincidencia. Esos campos se muestran con cada coincidencia.

• Especifica qué representa cada variable de coincidencia en la sección events.
• Especifica la duración del período que se usará para correlacionar eventos después de la palabra clave over. Se ignoran los eventos que se encuentran fuera del período.

• Usa la siguiente sintaxis para especificar la duración: <number><m/h/d>

  Aquí m/h/d significa minutos, horas y días, respectivamente.

• El tiempo mínimo que puedes especificar es 1 minuto.

• El tiempo máximo que puedes especificar es de 48 horas.

A continuación, se muestra un ejemplo de un objeto match válido:

$var1, $var2 over 5m

Esta instrucción devuelve $var1 y $var2 (definidos en la sección events) cuando la regla encuentra una coincidencia. El tiempo especificado es de 5 minutos. Los eventos que tienen una diferencia de más de 5 minutos no se correlacionan y, por lo tanto, la regla los ignora.

A continuación, se muestra otro ejemplo de una sección match válida:

$user over 1h

Esta instrucción devuelve $user cuando la regla encuentra una coincidencia. El período especificado es de 1 hora. No se correlacionan los eventos que tienen más de una hora de diferencia. La regla no los considera como una detección.

A continuación, se muestra otro ejemplo de una sección match válida:

$source_ip, $target_ip, $hostname over 2m

Esta instrucción devuelve $source_ip, $target_ip y $hostname cuando la regla encuentra una coincidencia. El período especificado es de 2 minutos. Los eventos que están separados por más de 2 minutos no se correlacionan. La regla no los considera como una detección.

En los siguientes ejemplos, se ilustran secciones match no válidas:

• var1, var2 over 5m // invalid variable name
• $user 1h // missing keyword

Control de valores cero en la sección de coincidencias

El motor de reglas filtra de forma implícita los valores cero para todos los marcadores de posición que se usan en la sección de coincidencias ("" para cadenas, 0 para números, false para valores booleanos y el valor en la posición 0 para tipos enumerados). En el siguiente ejemplo, se ilustran reglas que filtran los valores cero.

rule ZeroValuePlaceholderExample {
  meta:
  events:
    // Because $host is used in the match section, the rule 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 section,
    // 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 reglas no filtran de forma implícita los valores cero de los marcadores de posición que se usan en la sección de coincidencia. En el siguiente ejemplo, se ilustran reglas que filtran los valores cero:

rule ZeroValueFunctionPlaceholder {
  meta:
  events:
    // Even though $ph is used in the match section, there is no
    // implicit filtering of zero values for $ph, because $ph is assigned to a function.
    $ph = re.capture($e.principal.hostname, "some-regex")

  match:
    $ph over 5m

  condition:
    $e
}

Para inhabilitar el filtrado implícito de valores cero, puedes usar la opción allow_zero_values en la sección de opciones.

Ventana de salto

De forma predeterminada, las reglas de YARA-L 2.0 con una sección de coincidencia se evalúan con ventanas de salto. El período de ejecución de la regla se divide en un conjunto de ventanas de salto superpuestas, cada una con la duración especificada en la sección match. Luego, los eventos se correlacionan dentro de cada ventana de salto.

Por ejemplo, para una regla que se ejecuta en el intervalo de tiempo [1:00, 2:00], con una sección match sobre 30m, 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]. Estas ventanas se usan para correlacionar varios eventos.

Ventana deslizante

El uso de ventanas de salto no es una forma eficaz de buscar eventos que ocurren en un orden específico (por ejemplo, e1 ocurre hasta 2 minutos después de e2). Una ocurrencia del evento e1 y una ocurrencia del evento e2 se correlacionan solo si se producen en la misma ventana de salto generada.

Una forma más eficaz de buscar esas secuencias de eventos es usar ventanas deslizantes. Las ventanas deslizantes con la duración especificada en la sección match se generan cuando comienzan o terminan con una variable de evento de referencia especificada. Luego, los eventos se correlacionan dentro de cada ventana deslizante. Esto permite buscar eventos que ocurren en un orden específico (por ejemplo, e1 ocurre dentro de los 2 minutos posteriores a e2). Una ocurrencia del evento e1 y una ocurrencia del evento e2 se correlacionan si el evento e1 ocurre dentro de la duración de la ventana deslizante después del evento e2.

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

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

La variable de evento de pivote es la variable de evento en la que se basan las ventanas deslizantes. Si usas la palabra clave before, se generan ventanas deslizantes que finalizan con cada ocurrencia del evento pivote. Si se usa la palabra clave after, se generan ventanas deslizantes a partir de cada ocurrencia del evento pivote.

A continuación, se muestran ejemplos de usos válidos de la ventana deslizante:

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

Consulta un ejemplo de regla de ventana deslizante.

No recomendamos usar ventanas deslizantes para las reglas de un solo evento, ya que están diseñadas para detectar varios eventos. Si una de tus reglas pertenece a esta categoría, te recomendamos una de las siguientes soluciones:

• Convierte la regla para que use varias variables de evento y actualiza la sección de condiciones si la regla requiere más de una ocurrencia del evento.
  • Opcionalmente, 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
• Quita la ventana deslizante.

Sintaxis de la sección de resultados

En la sección outcome, puedes definir hasta 20 variables de resultado con nombres arbitrarios. Estos resultados se almacenarán en las detecciones que genere la regla. Cada detección puede tener valores diferentes para los resultados.

El nombre del resultado, $risk_score, es especial. De manera opcional, puedes definir un resultado con este nombre y, si lo haces, debe ser de tipo entero o flotante. Si se completa, el risk_score se mostrará en la vista de estadísticas de Enterprise para las alertas que provienen de las detecciones de reglas.

Si no incluyes una variable $risk_score en la sección de resultados de una regla, se establecerá uno de los siguientes valores predeterminados:

• Si la regla está configurada para generar una alerta, $risk_score se establece en 40.
• Si la regla 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.

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 utilizada para calcularla. Admitimos los siguientes tipos de datos de resultados:

• integer
• flota
• string
• 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 del UDM con operador de comparación, por ejemplo:

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

• variable de marcador de posición que se definió en la sección events, por ejemplo:

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

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

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

• Funciones que devuelven un valor booleano, por ejemplo:

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

• Buscar en una lista de referencia, por ejemplo:

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

• Comparación de agregaciones, por ejemplo:

  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 regla. 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 regla. En este ejemplo, supón que $email_sent_bytes se definió en la sección de eventos de la regla:

Ejemplo de un solo evento:

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

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 de varios eventos:

match:
  // This is a multi event rule 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 regla. 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 de varios eventos:

match:
  // This is a multi event rule 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 above 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 de 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 de resultados de una regla con una ventana de coincidencia son valores no escalares. Por ejemplo, la siguiente regla agrupa eventos con una sección de coincidencia y hace referencia a un campo de evento no repetido en la sección de resultado:

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

Cualquier período de 5 minutos durante el que se ejecute la regla puede contener cero, uno o muchos eventos. La sección de resultados funciona en 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 regla.

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 deben agregarse:

• Campos de eventos (repetidos o no repetidos) cuando la regla usa una sección de coincidencia
• Marcadores de posición de eventos (repetidos o no repetidos) cuando la regla usa una sección de coincidencia
• Campos de eventos repetidos cuando la regla no usa una sección de coincidencia
• Marcadores de posición de eventos repetidos cuando la regla no usa una sección de coincidencia

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 reglas que no incluyen una sección de coincidencias. 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 explícitamente 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:

• max(): Genera el valor máximo entre todos los valores posibles. Solo funciona con números enteros y de punto flotante.
• min(): Genera el valor 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 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. Truncará la lista de valores distintos a 1,000 elementos aleatorios. Primero, se aplica la deduplicación 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.
• period_start_for_max(): Es el inicio del período en el que se produjo el máximo del valor indicado.
• period_start_for_min(): Es el inicio del período en el que se produjo el mínimo del valor indicado.

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.

Por ejemplo, si tus secciones outcome y condition contienen 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 de condiciones 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"]

Aspectos que debes tener en cuenta cuando uses la sección de resultados:

Otras notas y restricciones:

• 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, dado que la variable de evento a la que pertenece el campo de evento ya se definió 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.

Puedes encontrar un ejemplo en la sección de resultados en la Descripción general de YARA-L 2.0. Consulta Crea estadísticas basadas en el contexto para obtener detalles sobre la deduplicación de detecciones con la sección de resultados.

Sintaxis de la sección Condition

• especificar una condición de coincidencia para los eventos y los marcadores de posición definidos en la sección events Consulta la siguiente sección, Condicionales de eventos y marcadores de posición, para obtener más detalles.
• (Opcional) Usa la palabra clave and para especificar una condición de coincidencia con las variables de resultado definidas en la sección outcome. Consulta la siguiente sección, Condicionales de resultados, para obtener más detalles.

Carácter de recuento

El carácter # es un carácter especial en la sección condition. Si se usa antes de cualquier evento o nombre de variable de marcador de posición, representa la cantidad de eventos o valores distintos que satisfacen todas las condiciones de la sección events.

Por ejemplo, #c > 1 significa que la variable c debe aparecer más de 1 vez.

Carácter de valor

El carácter $ es un carácter especial en la sección condition. Si se usa antes del nombre de cualquier variable de resultado, representa el valor de ese resultado.

Si se usa antes de cualquier nombre de variable de evento o marcador de posición (por ejemplo, $event), representa #event > 0.

Condicionales de eventos y marcadores de posición

Enumera los predicados de condición para los eventos y las variables de marcador de posición con las palabras clave and o or. Puedes usar and para unir cualquier combinación de condiciones. Sin embargo, solo puedes usar or cuando todas las condiciones hacen referencia a la misma variable de evento.

Un ejemplo válido del uso de or entre dos marcadores de posición en el mismo evento:

rule ValidConditionOr {
  meta:
  events:
      $e.metadata.event_type = "NETWORK_CONNECTION"

      // Note that all placeholders use the same event variable.
      $ph = $e.principal.user.userid  // Define a placeholder variable to put in match section.
      $ph2 = $e.principal.ip  // Define a second placeholder variable to put in condition section.
      $ph3 = $e.principal.hostname  // Define a third placeholder variable to put in condition section.

  match:
    $ph over 5m

  condition:
    $ph2 or $ph3
}

Un ejemplo no válido del uso de or entre dos condiciones en diferentes eventos:

rule InvalidConditionOr {
  meta:
  events:
      $e.metadata.event_type = "NETWORK_CONNECTION"
      $e2.graph.metadata.entity_type = "FILE"
      $e2.graph.entity.hostname  = $e.principal.hostname

      $ph = $e.principal.user.userid  // Define a placeholder variable to put in match section.

  match:
    $ph over 5m

  condition:
    $e or $e2 // This line will cause an error because there is an or between events.
}

Condiciones delimitadas y no delimitadas

Las siguientes condiciones son condiciones acotadas. Obligan a que exista la variable de evento asociada, lo que significa que debe aparecer al menos una ocurrencia del evento en cualquier detección.

• $var // equivalent to #var > 0
• #var > n // where n >= 0
• #var >= m // where m > 0

Las siguientes condiciones son condiciones no acotadas. Permiten que la variable del evento asociado no exista, lo que significa que es posible que no aparezca ninguna ocurrencia del evento en una detección y que cualquier referencia a los campos de la variable del evento arroje un valor cero. Las condiciones no acotadas se pueden usar para detectar la ausencia de un evento durante un período. Por ejemplo, un evento de amenaza sin un evento de mitigación en un período de 10 minutos. Las reglas que usan condiciones no acotadas se denominan reglas de no existencia.

• !$var // equivalent to #var = 0
• #var >= 0
• #var < n // where n > 0
• #var <= m // where m >= 0

Requisitos para la no existencia

Para que se compile una regla con no existencia, debe satisfacer los siguientes requisitos:

1. Al menos un evento del UDM debe tener una condición delimitada (es decir, debe existir al menos un evento del UDM).
2. Si un marcador de posición tiene una condición no acotada, debe estar asociado con al menos un evento de UDM acotado.
3. Si una entidad tiene una condición no acotada, debe estar asociada con al menos un evento de UDM acotado.

Considera la siguiente regla con la sección de condición omitida:

rule NonexistenceExample {
  meta:
  events:
      $u1.metadata.event_type = "NETWORK_CONNECTION" // $u1 is a UDM event.
      $u2.metadata.event_type = "NETWORK_CONNECTION" // $u2 is a UDM event.
      $e1.graph.metadata.entity_type = "FILE"        // $e1 is an Entity.
      $e2.graph.metadata.entity_type = "FILE"        // $e2 is an Entity.

      $user = $u1.principal.user.userid // Match variable is required for Multi-Event Rule.

      // Placeholder Associations:
      //   u1        u2
      //   |  \    /
      // port   ip
      //   |       \
      //   e1        e2
      $u1.target.port = $port
      $e1.graph.entity.port = $port
      $u1.principal.ip = $ip
      $u2.target.ip = $ip
      $e2.graph.entity.ip = $ip

      // UDM-Entity Associations:
      // u1 - u2
      // |  \  |
      // e1   e2
      $u1.metadata.event_type = $u2.metadata.event_type
      $e1.graph.entity.hostname = $u1.principal.hostname
      $e2.graph.entity.hostname = $u1.target.hostname
      $e2.graph.entity.hostname = $u2.principal.hostname

  match:
    $user over 5m

  condition:
      <condition_section>
}

A continuación, se muestran ejemplos válidos para <condition_section>:

• $u1 and !$u2 and $e1 and $e2
  • Todos los eventos y entidades del UDM están presentes en la sección de condiciones.
  • Al menos un evento de UDM está delimitado.
• $u1 and !$u2 and $e1 and !$e2
  • $e2no está acotada, lo que se permite porque está asociada a $u1, que sí está acotada. Si $e2 no se asoció con $u1, esto no sería válido.
• #port > 50 and #ip = 0
  • No hay eventos ni entidades de UDM presentes en la sección de condiciones. Sin embargo, los marcadores de posición presentes abarcan todos los eventos y entidades de UDM.
  • $ip se asigna a $u1 y $u2, y #ip = 0 es una condición no acotada. Sin embargo, las condiciones acotadas son más sólidas que las no acotadas. Como $port se asigna a $u1 y #port > 50 es una condición acotada, $u1 sigue siendo acotada.

Los siguientes son ejemplos no válidos para <condition_section>:

• $u1 and $e1
  • Cada evento y entidad del UDM que aparezca en la sección Eventos debe aparecer en la sección Condición (o tener un marcador de posición asignado que aparezca en la sección Condición).
• $u1, $u2, $e1, $u2, #port > 50
  • No se permiten comas como separadores de condiciones.
• !$u1 and !$u2 and $e1 and $e2
  • Incumple el primer requisito de que al menos un evento de UDM esté delimitado.
• ($u1 or #port < 50) and $u2 and $e1 and $e2
  • La palabra clave or no se admite con condiciones no acotadas.
• ($u1 or $u2) and $e1 and $e2
  • La palabra clave or no se admite entre diferentes variables de eventos.
• not $u1 and $u2 and $e1 and $e2
  • No se permite la palabra clave not para las condiciones de eventos y marcadores de posición.
• #port < 50 and #ip = 0
  • Los marcadores de posición presentes abarcan todos los eventos y entidades del UDM. Sin embargo, todas las condiciones son ilimitadas. Esto significa que ninguno de los eventos de UDM está delimitado, lo que provoca que la regla no se compile.

Condicionales de resultados

Aquí se enumeran los predicados de condición para las variables de resultado, unidos con la palabra clave and o or, o precedidos por la palabra clave not.

Especifica los condicionales de resultado de manera diferente según el tipo de variable de resultado:

• integer: Compara con un literal entero con operadores =, >, >=, <, <=, !=, por ejemplo:

  $risk_score > 10

• float: Compara con un literal de número de punto flotante con operadores =, >, >=, <, <=, !=, por ejemplo:

  $risk_score <= 5.5

• string: Compara con un literal de cadena con = o !=, por ejemplo:

  $severity = "HIGH"

• Lista de números enteros o arrays: Especifica la condición con la función arrays.contains, por ejemplo:

  arrays.contains($event_ids, "id_1234")

Clasificación de reglas

Especificar un resultado condicional en una regla que tiene una sección de coincidencia significa que la regla se clasificará como una regla de varios eventos para la cuota de reglas. Consulta regla de evento único y regla de evento múltiple para obtener más información sobre las clasificaciones de eventos únicos y múltiples.

Sintaxis de la sección de opciones

En la sección options, puedes especificar las opciones de la regla. A continuación, se muestra un ejemplo de cómo especificar la sección de opciones:

rule RuleOptionsExample {
  // Other rule sections

  options:
    allow_zero_values = true
}

Puedes especificar opciones con la sintaxis key = value, en la que key debe ser un nombre de opción predefinido y value debe ser un valor válido para la opción, como se especifica para las siguientes opciones:

allow_zero_values

Los valores válidos para esta opción son true y false, que determinan si esta opción está habilitada o no. El valor predeterminado es false. Esta opción se inhabilita si no se especifica en la regla.

Para habilitar este parámetro de configuración, agrega lo siguiente a la sección de opciones de tu regla: allow_zero_values = true. Si lo haces, evitarás que la regla filtre de forma implícita los valores cero de los marcadores de posición que se usan en la sección de coincidencia, como se describe en Manejo de valores cero en la sección de coincidencia.

suppression_window

La opción suppression_window te permite controlar la frecuencia con la que una regla activa una detección. Evita que la misma regla genere varias detecciones dentro de un período especificado, incluso si las condiciones de la regla se cumplen varias veces. El sistema de ventanas de supresión usa un enfoque de ventanas de saltos de tamaño constante, que suprime los duplicados en una ventana de tamaño fijo y sin superposiciones.

De manera opcional, puedes proporcionar un suppression_key para definir con mayor precisión qué instancias de la regla se suprimen dentro del período de supresión. Si no se especifica, se suprimirán todas las instancias de la regla. Esta clave se define como una variable de resultado.

En el siguiente ejemplo, suppression_window se establece en 5m y suppression_key se establece en la variable $hostname. Después de que la regla activa una detección para $hostname, se suprimen las detecciones posteriores para $hostname durante los próximos cinco minutos. Sin embargo, si la regla se activa en un evento con un nombre de host diferente, se crea una detección.

El valor predeterminado de suppression_window es 0, es decir, la ventana de supresión está inhabilitada de forma predeterminada. Esta opción solo funciona para las reglas de un solo evento que no tienen una sección match.

Ejemplo:

rule SuppressionWindowExample {
  // Other rule sections

  outcome:
    $suppression_key = $hostname

  options:
    suppression_window = 5m
}

Reglas de detección compuestas

La detección compuesta en Google SecOps implica conectar varias reglas de YARA-L. En esta sección, se explica cómo compilar una regla compuesta. Para obtener una descripción general de las detecciones compuestas, consulta Descripción general de las detecciones compuestas.

Estructura de la regla

Las reglas de detección compuestas siempre son reglas de varios eventos y siguen la misma estructura y sintaxis. Se aplican los siguientes requisitos a las reglas de detección compuestas:

• Las reglas compuestas deben usar una sección match para definir las condiciones del activador de detección.
• Las reglas que usan tanto los campos de detección como los eventos del UDM deben unir explícitamente estas fuentes de datos.

Para obtener información sobre las limitaciones de las reglas, consulta Limitaciones.

Usa las detecciones como entrada para las reglas

Las reglas compuestas pueden hacer referencia a las detecciones de reglas generadas por cualquier regla personalizada o seleccionada. Google SecOps proporciona dos métodos para hacerlo.

Contenido de detección de referencias con variables de resultado, variables de coincidencia o metaetiquetas

Para acceder a los datos de una detección sin hacer referencia a los eventos originales del UDM, usa las variables outcome, las variables match o las etiquetas meta. Recomendamos este enfoque porque proporciona mayor flexibilidad y mejor compatibilidad en diferentes tipos de reglas.

Por ejemplo, varias reglas pueden almacenar una cadena (como una URL, un nombre de archivo o una clave de registro) en una variable outcome común si buscas esa cadena en diferentes contextos. Para acceder a esta cadena desde una regla compuesta, comienza con detection y busca la información pertinente con elementos del recurso Collection.

Ejemplo: Por ejemplo, supongamos que una regla de detección produce la siguiente información:

• Variable de resultado: dest_domain = "cymbal.com"
• Campo de UDM: target.hostname = "cymbal.com"

En la regla compuesta, puedes acceder a estos datos con las siguientes rutas:

• detection.detection.outcomes["dest_domain"] para acceder a la variable de resultado dest_domain
• detection.collection_elements.references.event.target.hostname para acceder al campo target.hostname de UDM
• detection.time_window.start_time.seconds para acceder a la marca de tiempo de detección

La API de Collection y la API de SecurityResult proporcionan acceso a lo siguiente:

• Valores de metadatos y resultados de detección (detection.detection)
• Eventos de UDM subyacentes de las reglas a las que se hace referencia (collection_elements)

Cómo hacer referencia al contenido de detección con el ID o el nombre de la regla

Puedes hacer referencia a una regla por su nombre o ID. Recomendamos este enfoque cuando tu lógica de detección depende de reglas específicas. Hacer referencia a las reglas pertinentes por su nombre o ID mejora el rendimiento y evita los tiempos de espera, ya que reduce la cantidad de datos analizados. Por ejemplo, puedes consultar directamente campos como target.url o principal.ip a partir de una detección anterior conocida.

• Haz referencia a una regla por su ID (recomendado): Usa el campo detection.detection.rule_id para hacer referencia a una regla por su ID. Puedes encontrar el ID de la regla en la URL de la regla en Google SecOps. Las reglas generadas por el usuario tienen IDs en el formato ru_UUID, mientras que las detecciones seleccionadas tienen IDs en el formato ur_UUID. Por ejemplo:

  detection.detection.rule_id = "ru_e0d3f371-6832-4d20-b0ad-1f4e234acb2b"

• Hacer referencia a una regla por su nombre: Usa el campo detection.detection.rule_name para hacer referencia a una regla por su nombre. Puedes especificar el nombre exacto de la regla o usar una expresión regular para que coincida. Por ejemplo:

  • detection.detection.rule_name = "My Rule Name"
  • detection.detection.rule_name = "/PartOfName/"

Nota: Te recomendamos que uses los IDs de reglas para hacer referencia, ya que son únicos y no cambian. Los nombres de las reglas se pueden modificar, lo que podría interrumpir la detección compuesta.

Combina eventos y detecciones

Las reglas compuestas pueden combinar diferentes fuentes de datos, incluidos los eventos del UDM, los datos del gráfico de entidades y los campos de detección. Deben aplicarse las siguientes pautas:

• Usa variables distintas por fuente: Asigna variables de eventos únicas a cada fuente de datos (por ejemplo, $e para eventos y $d para detecciones), en la que la fuente de datos incluya eventos, entidades y detecciones.
• Unir fuentes en un contexto compartido: Conecta fuentes de datos con valores comunes, como IDs de usuario, direcciones IP o nombres de dominio en las condiciones de tu regla.
• Define un período de coincidencia: Siempre incluye una cláusula match con un período que no supere las 48 horas.

Por ejemplo:

rule CheckCuratedDetection_with_EDR_and_EG {
  meta:
    author = "noone@cymbal.com"
  events:
    $d.detection.detection.rule_name = /SCC: Custom Modules: Configurable Bad Domain/
    $d.detection.collection_elements.references.event.network.dns.questions.name = $domain
    $d.detection.collection_elements.references.event.principal.asset.hostname = $hostname

    $e.metadata.log_type = "LIMACHARLIE_EDR"
    $e.metadata.product_event_type = "NETWORK_CONNECTIONS"
    $domain = re.capture($e.principal.process.command_line, "\\s([a-zA-Z0-9.-]+\\.[a-zA-Z0-9.-]+)$")
    $hostname = re.capture($e.principal.hostname, "([^.]*)")

    $prevalence.graph.metadata.entity_type = "DOMAIN_NAME"
    $prevalence.graph.metadata.source_type = "DERIVED_CONTEXT"
    $prevalence.graph.entity.hostname = $domain
    $prevalence.graph.entity.domain.prevalence.day_count = 10
    $prevalence.graph.entity.domain.prevalence.rolling_max <= 5
    $prevalence.graph.entity.domain.prevalence.rolling_max > 0

  match:
    $hostname over 1h

  outcome:
    $risk_score = 80
    $CL_target = array($domain)

  condition:
    $e and $d and $prevalence
}

Crea detecciones compuestas secuenciales

Las detecciones compuestas secuenciales identifican patrones de eventos relacionados en los que la secuencia de detecciones es importante, como la detección de un intento de acceso por fuerza bruta, seguido de un acceso exitoso. Estos patrones pueden combinar varias detecciones básicas, eventos sin procesar del UDM o ambos.

Para crear una detección compuesta secuencial, debes aplicar ese orden en tu regla. Para aplicar la secuencia esperada, usa uno de los siguientes métodos:

• Ventanas deslizantes: Define la secuencia de detecciones con ventanas deslizantes en tus condiciones match.
• Comparaciones de marcas de tiempo: Compara las marcas de tiempo de las detecciones dentro de la lógica de tu regla para verificar que ocurran en el orden seleccionado.

Por ejemplo:

events:
    $d1.detection.detection.rule_name = "fileEvent_rule"
    $userid = $d1.detection.detection.outcomes["user"]
    $hostname = $d1.detection.detection.outcomes["hostname"]

    $d2.detection.detection.rule_name = "processExecution_rule"
    $userid = $d2.detection.detection.outcomes["user"]
    $hostname = $d2.detection.detection.outcomes["hostname"]

    $d3.detection.detection.rule_name = "networkEvent_rule"
    $userid = $d3.detection.detection.outcomes["user"]
    $hostname = $d3.detection.detection.outcomes["hostname"]

$d3.detection.collection_elements.references.event.metadata.event_timestamp.seconds > $d2.detection.collection_elements.references.event.metadata.event_timestamp.seconds

  match:
    $userid over 24h after $d1

Expresiones booleanas

Las expresiones booleanas son expresiones con un tipo booleano.

Comparaciones

Para usar una expresión binaria como condición, usa la siguiente sintaxis:

• <EXPR> <OP> <EXPR>

La expresión puede ser un campo de evento, una variable, un literal o una función.

Por ejemplo:

• $e.source.hostname = "host1234"
• $e.source.port < 1024
• 1024 < $e.source.port
• $e1.source.hostname != $e2.target.hostname
• $e1.metadata.collected_timestamp.seconds > $e2.metadata.collected_timestamp.seconds
• $port >= 25
• $host = $e2.target.hostname
• "google-test" = strings.concat($e.principal.hostname, "-test")
• "email@google.org" = re.replace($e.network.email.from, "com", "org")

Si ambos lados son literales, se considera un error de compilación.

Funciones

Algunas expresiones de función devuelven un valor booleano, que se puede usar como un predicado individual en la sección events. Estas funciones son las siguientes:

• re.regex()
• net.ip_in_range_cidr()

Por ejemplo:

• re.regex($e.principal.hostname, `.*\.google\.com`)
• net.ip_in_range_cidr($e.principal.ip, "192.0.2.0/24")

Expresiones de listas de referencia

Puedes usar listas de referencia en la sección de eventos. Consulta la sección sobre Listas de referencia para obtener más detalles.

Expresiones lógicas

Puedes usar los operadores lógicos and y or en la sección events, como se muestra en los siguientes ejemplos:

• $e.metadata.event_type = "NETWORK_DNS" or $e.metadata.event_type = "NETWORK_DHCP"
• ($e.metadata.event_type = "NETWORK_DNS" and $e.principal.ip = "192.0.2.12") or ($e.metadata.event_type = "NETWORK_DHCP" and $e.principal.mac = "AB:CD:01:10:EF:22")
• not $e.metadata.event_type = "NETWORK_DNS"

De forma predeterminada, el orden de prioridad de mayor a menor es not, and y or.

Por ejemplo, "a or b and c" se evalúa como "a or (b and c)" cuando los operadores or y and se definen de forma explícita en la expresión.

En la sección events, los predicados se unen con el operador and si no se define un operador de forma explícita.

El orden de evaluación puede ser diferente si el operador and está implícito en la expresión.

Por ejemplo, considera las siguientes expresiones de comparación en las que or se define de forma explícita. El operador and está implícito.

$e1.field = "bat"
or $e1.field = "baz"
$e2.field = "bar"

Este ejemplo se interpreta de la siguiente manera:

($e1.field = "bat" or $e1.field = "baz")
and ($e2.field = "bar")

Como or se define de forma explícita, los predicados que rodean a or se agrupan y evalúan primero. El último predicado, $e2.field = "bar", se une de forma implícita con and. El resultado es que cambia el orden de evaluación.

Tipos enumerados

Puedes usar los operadores con tipos enumerados. Se puede aplicar a las reglas para simplificar y optimizar el rendimiento (usar operadores en lugar de listas de referencia).

En el siguiente ejemplo, "USER_UNCATEGORIZED" y "USER_RESOURCE_DELETION" corresponden a 15000 y 15014, por lo que la regla buscará todos los eventos enumerados:

$e.metadata.event_type >= "USER_CATEGORIZED" and $e.metadata.event_type <= "USER_RESOURCE_DELETION"

Lista de eventos:

• USER_RESOURCE_DELETION
• USER_RESOURCE_UPDATE_CONTENT
• USER_RESOURCE_UPDATE_PERMISSIONS
• USER_STATS
• USER_UNCATEGORIZED

Modificador nocase

Cuando tienes una expresión de comparación entre valores de cadena o una expresión regular, puedes agregar nocase al final de la expresión para ignorar el uso de mayúsculas.

• $e.principal.hostname != "http-server" nocase
• $e1.principal.hostname = $e2.target.hostname nocase
• $e.principal.hostname = /dns-server-[0-9]+/ nocase
• re.regex($e.target.hostname, `client-[0-9]+`) nocase

No se puede usar cuando un tipo de campo es un valor enumerado. Los siguientes ejemplos no son válidos y generarán errores de compilación:

• $e.metadata.event_type = "NETWORK_DNS" nocase
• $e.network.ip_protocol = "TCP" nocase

Campos repetidos

En el Modelo de datos unificado (UDM), algunos campos se etiquetan como repetidos, lo que indica que son listas de valores o de otros tipos de mensajes.

Campos repetidos y expresiones booleanas

Existen 2 tipos de expresiones booleanas que actúan sobre los campos repetidos:

1. Modificado
2. Sin modificar

Considera el siguiente evento:

event_original {
  principal {
    // ip is a repeated field
    ip: [ "192.0.2.1", "192.0.2.2", "192.0.2.3" ]

    hostname: "host"
  }
}

Expresiones modificadas

En las siguientes secciones, se describen el propósito y el uso de los modificadores any y all en las expresiones.

cualquiera

Si algún elemento del campo repetido satisface la condición, el evento en su totalidad satisface la condición.

• event_original satisface any $e.principal.ip = "192.0.2.1".
• event_original falla any $e.repeated_field.field_a = "9.9.9.9.

todos

Si todos los elementos del campo repetido satisfacen la condición, el evento en su totalidad satisface la condición.

• event_original satisface net.ip_in_range_cidr(all $e.principal.ip, "192.0.2.0/8").
• event_original falla all $e.principal.ip = "192.0.2.2".

Cuando escribas una condición con any o all, ten en cuenta que negar la condición con not podría no tener el mismo significado que usar el operador negado.

Por ejemplo:

• not all $e.principal.ip = "192.168.12.16" verifica si no todas las direcciones IP coinciden con 192.168.12.16, lo que significa que la regla verifica si al menos una dirección IP no coincide con 192.168.12.16.
• all $e.principal.ip != "192.168.12.16" verifica si todas las direcciones IP no coinciden con 192.168.12.16, lo que significa que la regla verifica que ninguna dirección IP coincida con 192.168.12.16.

Restricciones:

• Los operadores any y all solo son compatibles con los campos repetidos (no con los campos escalares).
• any y all no se pueden usar para unir dos campos repetidos. Por ejemplo, any $e1.principal.ip = $e2.principal.ip no es válido.
• Los operadores any y all no se admiten con la expresión de la lista de referencia.

Expresiones sin modificar

Con expresiones sin modificar, cada elemento del campo repetido se trata de forma individual. Si el campo repetido de un evento contiene n elementos, la regla se aplica a n copias del evento, en las que cada copia tiene uno de los elementos del campo repetido. Estas copias son transitorias y no se almacenan.

La regla se aplica a las siguientes copias:

Si alguna copia del evento satisface todas las condiciones sin modificar en el campo repetido, el evento en su totalidad satisface todas las condiciones. Esto significa que, si tienes varias condiciones en un campo repetido, la copia del evento debe satisfacer todas ellas. En los siguientes ejemplos de reglas, se usa el conjunto de datos de ejemplo anterior para demostrar este comportamiento.

La siguiente regla devuelve una coincidencia cuando se ejecuta en el conjunto de datos de ejemplo de event_original, ya que event_copy_1 satisface todos los predicados de eventos:

rule repeated_field_1 {
  meta:
  events:
    net.ip_in_range_cidr($e.principal.ip, "192.0.2.0/8") // Checks if IP address matches 192.x.x.x
    $e.principal.ip = "192.0.2.1"
  condition:
    $e
}

La siguiente regla no devuelve una coincidencia cuando se ejecuta en el conjunto de datos de ejemplo de event_original, ya que no hay ninguna copia del evento en $e.principal.ip que satisfaga todos los predicados del evento.

rule repeated_field_2 {
  meta:
  events:
    $e.principal.ip = "192.0.2.1"
    $e.principal.ip = "192.0.2.2"
  condition:
    $e
}

Las expresiones modificadas en campos repetidos son compatibles con las expresiones sin modificar en campos repetidos porque la lista de elementos es la misma para cada copia del evento. Ten en cuenta la siguiente regla:

rule repeated_field_3 {
  meta:
  events:
    any $e.principal.ip = "192.0.2.1"
    $e.principal.ip = "192.0.2.3"
  condition:
    $e
}

La regla se aplica a las siguientes copias:

En este caso, todas las copias satisfacen any $e.principal.ip = "192.0.2.1", pero solo event_copy_3 satisface $e.principal.ip = "192.0.2.3". Como resultado, el evento en su totalidad coincidiría.

Otra forma de pensar en estos tipos de expresiones es la siguiente:

• Las expresiones en campos repetidos que usan any o all operan en la lista en event_original.
• Las expresiones en campos repetidos que no usan any ni all operan en eventos event_copy_n individuales.

Campos repetidos y marcadores de posición

Los campos repetidos funcionan con las asignaciones de marcadores de posición. Al igual que con las expresiones sin modificar en los campos repetidos, se crea una copia del evento para cada elemento. Con el mismo ejemplo de event_copy, el marcador de posición toma el valor del campo repetido de event_copy_n para cada una de las copias del evento en las que n es el número de copia del evento. Si el marcador de posición se usa en la sección de coincidencias, esto puede generar varias coincidencias.

En el siguiente ejemplo, se genera una coincidencia. El marcador de posición $ip es igual a 192.0.2.1 para event_copy_1, lo que satisface los predicados de la regla. Las muestras de eventos del partido contienen un solo elemento, event_original.

// Generates 1 match.
rule repeated_field_placeholder1 {
  meta:
  events:
    $ip = $e.principal.ip
    $ip = "192.0.2.1"
    $host = $e.principal.hostname

  match:
    $host over 5m

  condition:
    $e
}

En el siguiente ejemplo, se generan tres coincidencias. El marcador de posición $ip es igual a diferentes valores para cada una de las diferentes copias de event_copy_n. La agrupación se realiza en $ip, ya que se encuentra en la sección de coincidencias. Por lo tanto, obtienes tres coincidencias, en las que cada una tiene un valor diferente para la variable de coincidencia $ip. Cada coincidencia tiene la misma muestra de eventos: un solo elemento, event_original.

// Generates 3 matches.
rule repeated_field_placeholder2 {
  meta:
  events:
    $ip = $e.principal.ip
    net.ip_in_range_cidr($ip, "192.0.2.0/8") // Checks if IP matches 192.x.x.x

  match:
    $ip over 5m

  condition:
    $e
}

Resultados que usan marcadores de posición asignados a campos repetidos

Los marcadores de posición se asignan a cada elemento de cada campo repetido, no a toda la lista. Por lo tanto, cuando se usan en la sección de resultados, el resultado se calcula solo con los elementos que satisficieron las secciones anteriores.

Ten en cuenta la siguiente regla:

rule outcome_repeated_field_placeholder {
  meta:
  events:
    $ip = $e.principal.ip
    $ip = "192.0.2.1" or $ip = "192.0.2.2"
    $host = $e.principal.hostname

  match:
    $host over 5m

  outcome:
    $o = array_distinct($ip)

  condition:
    $e
}

Esta regla tiene 4 etapas de ejecución. La primera etapa es la copia de eventos:

Luego, la sección de eventos filtrará las filas que no coincidan con los filtros:

Se filtra event_copy_3 porque "192.0.2.3" no satisface $ip = "192.0.2.1" or $ip = "192.0.2.2".

Luego, la sección de coincidencias se agrupará por variables de coincidencia y la sección de resultados realizará la agregación en cada grupo:

$o = array_distinct($ip) se calcula con $ip del paso anterior y no con el paso de copia del evento.

Por último, la sección de condiciones filtrará cada grupo. Dado que esta regla solo verifica la existencia de $e, la fila anterior producirá una sola detección.

$o no contiene todos los elementos de $e.principal.ip porque no todos los elementos cumplieron con todas las condiciones de la sección de eventos. Sin embargo, todos los elementos de e.principal.ip aparecerán en la muestra del evento porque esta usa event_original.

Indexación de arreglos

Puedes realizar la indexación de arrays en campos repetidos. Para acceder al n-ésimo elemento del campo repetido, usa la sintaxis de lista estándar (los elementos tienen un índice que comienza en 0). Un elemento fuera de los límites devuelve el valor predeterminado.

• $e.principal.ip[0] = "192.168.12.16"
• $e.principal.ip[999] = "" Si hay menos de 1,000 elementos, esto se evalúa como true.

Restricciones:

• Un índice debe ser un literal de número entero no negativo. Por ejemplo, $e.principal.ip[-1] no es válido.
• No se tienen en cuenta los valores que tienen un tipo int (por ejemplo, un marcador de posición establecido en int).
• La indexación de arrays no se puede combinar con any ni all. Por ejemplo, any $e.intermediary.ip[0] no es válido.
• La indexación de arrays no se puede combinar con la sintaxis de mapas. Por ejemplo, $e.additional.fields[0]["key"] no es válido.
• Si la ruta de acceso al campo contiene varios campos repetidos, todos los campos repetidos deben usar la indexación de arrays. Por ejemplo, $e.intermediary.ip[0] no es válido porque intermediary y ip son campos repetidos, pero solo hay un índice para ip.

Mensajes repetidos

Cuando se repite un campo message, se reduce la probabilidad de una coincidencia, lo que no es el efecto deseado. Esto se ilustra en los siguientes ejemplos.

Considera el siguiente evento:

event_repeated_message {
  // about is a repeated message field.
  about {
    // ip is a repeated string field.
    ip: [ "192.0.2.1", "192.0.2.2", "192.0.2.3" ]

    hostname: "alice"
  }
  about {
    hostname: "bob"
  }
}

Como se indicó para las expresiones sin modificar en los campos repetidos, se crea una copia temporal del evento para cada elemento del campo repetido. Ten en cuenta la siguiente regla:

rule repeated_message_1 {
  meta:
  events:
    $e.about.ip = "192.0.2.1"
    $e.about.hostname = "bob"
  condition:
    $e
}

La regla se aplica a las siguientes copias:

El evento no coincide con la regla porque no existe ninguna copia del evento que satisfaga todas las expresiones.

Mensajes repetidos e indexación de arrays

Otro comportamiento inesperado puede ocurrir cuando se usa la indexación de arrays con expresiones sin modificar en campos de mensajes repetidos. Considera la siguiente regla de ejemplo que usa la indexación de arrays:

rule repeated_message_2 {
  meta:
  events:
    $e.about.ip = "192.0.2.1"
    $e.about[1].hostname = "bob"
  condition:
    $e
}

La regla se aplica a las siguientes copias:

Dado que event_copy_1 satisface todas las expresiones en repeated_message_2, el evento coincide con la regla.

Esto puede generar un comportamiento inesperado porque la regla repeated_message_1 no tenía indexación de array y no produjo coincidencias, mientras que la regla repeated_message_2 sí usó la indexación de array y produjo una coincidencia.

Comentarios

Designa comentarios con dos caracteres de barra (// comment) o comentarios de varias líneas establecidos con caracteres de asterisco y barra (/* comment */), como lo harías en C.

Literales

Se admiten números enteros y de punto flotante no negativos, cadenas, valores booleanos y literales de expresiones regulares.

Literales de cadena y de expresión regular

Puedes usar cualquiera de los siguientes caracteres de comillas para encerrar cadenas en YARA-L 2.0. Sin embargo, el texto entre comillas se interpreta de manera diferente según el que uses.

1. Comillas dobles ("): Se usan para las cadenas normales. Debe incluir caracteres de escape.
   Por ejemplo: "hola\tmundo" —\t se interpreta como una tabulación

2. Comillas inversas (`): Se usan para interpretar todos los caracteres de forma literal.
   Por ejemplo: "hola\tmundo" —\t no se interpreta como una tabulación

En el caso de las expresiones regulares, tienes dos opciones.

Si deseas usar expresiones regulares directamente sin la función re.regex(), usa /regex/ para los literales de expresión regular.

También puedes usar literales de cadena como literales de expresión regular cuando usas la función re.regex(). Ten en cuenta que, para los literales de cadena entre comillas dobles, debes escapar los caracteres de barra inversa con caracteres de barra inversa, lo que puede parecer extraño.

Por ejemplo, las siguientes expresiones regulares son equivalentes:

• re.regex($e.network.email.from, `.*altostrat\.com`)
• re.regex($e.network.email.from, ".*altostrat\\.com")
• $e.network.email.from = /.*altostrat\.com/

Google recomienda usar caracteres de comillas inversas para las cadenas en expresiones regulares para facilitar la legibilidad.

Operadores

Puedes usar los siguientes operadores en YARA-L:

Variables

En YARA-L 2.0, todas las variables se representan como $<variable name>.

Puedes definir los siguientes tipos de variables:

• Variables de eventos: Representan grupos de eventos en formato normalizado (UDM) o eventos de entidades. Especifica las condiciones para las variables de eventos en la sección events. Las variables de eventos se identifican con un nombre, una fuente de eventos y campos de eventos. Las fuentes permitidas son udm (para eventos normalizados) y graph (para eventos de entidades). Si se omite la fuente, se establece udm como la fuente predeterminada. Los campos de eventos se representan como una cadena de .<nombre de campo> (por ejemplo, $e.field1.field2). Las cadenas de campos de eventos siempre comienzan desde la fuente de nivel superior (UDM o entidad).

• Variables de coincidencia: Se declaran en la sección match. Las variables de coincidencia se convierten en campos de agrupación para la consulta, ya que se devuelve una fila para cada conjunto único de variables de coincidencia (y para cada período). Cuando la regla encuentra una coincidencia, se devuelven los valores de las variables de coincidencia. Especifica qué representa cada variable de coincidencia en la sección events.

• Variables de marcador de posición: Se declaran y definen en la sección events. Las variables de marcador de posición son similares a las variables de coincidencia. Sin embargo, puedes usar variables de marcador de posición en la sección condition para especificar condiciones de coincidencia.

Usa variables de coincidencia y variables de marcador de posición para declarar relaciones entre los campos de eventos a través de condiciones de unión transitivas (consulta la sintaxis de la sección de eventos para obtener más detalles).

Palabras clave

Las palabras clave en YARA-L 2.0 no distinguen mayúsculas de minúsculas. Por ejemplo, and y AND son equivalentes. Los nombres de las variables no deben entrar en conflicto con las palabras clave. Por ejemplo, $AND o $outcome no son válidos.

Las siguientes son palabras clave para las reglas del motor de detección: rule, meta, match, over, events, condition, outcome, options, and, or, not, nocase, in, regex, cidr, before, after, all, any, if, max, min, sum, array, array_distinct, count, count_distinct, is y null.

Maps

YARA-L admite el acceso a mapas para Structs y Labels.

Estructuras y etiquetas

Algunos campos del UDM usan el tipo de datos Struct o Label.

Para buscar un par clave-valor específico en Struct y Label, usa la sintaxis de mapa estándar:

// A Struct field.
$e.udm.additional.fields["pod_name"] = "kube-scheduler"
// A Label field.
$e.metadata.ingestion_labels["MetadataKeyDeletion"] = "startup-script"

El acceso al mapa siempre devuelve una cadena.

Casos admitidos

A continuación, se indican los casos de uso de las palabras clave admitidas.

Sección de eventos y resultados

// Using a Struct field in the events section
events:
  $e.udm.additional.fields["pod_name"] = "kube-scheduler"

// Using a Label field in the outcome section
outcome:
  $value = array_distinct($e.metadata.ingestion_labels["MetadataKeyDeletion"])

Asignar un valor de mapa a un marcador de posición

$placeholder = $u1.metadata.ingestion_labels["MetadataKeyDeletion"]

Usa un campo de mapa en una condición de unión

// using a Struct field in a join condition between two udm events $u1 and $u2
$u1.metadata.event_type = $u2.udm.additional.fields["pod_name"]

Casos no admitidos

Los mapas no son compatibles en los siguientes casos.

Combinación de palabras clave de any o all con un mapa

Por ejemplo, no se admite lo siguiente:

all $e.udm.additional.fields["pod_name"] = "kube-scheduler"

Otros tipos de valores

La sintaxis del mapa solo puede devolver un valor de cadena. En el caso de los tipos de datos Struct, la sintaxis de mapa solo puede acceder a las claves cuyos valores son cadenas. No es posible acceder a claves cuyos valores son otros tipos primitivos, como números enteros.

Control de valores duplicados

Los accesos al mapa siempre devuelven un solo valor. En el caso poco común en que el acceso al mapa pueda hacer referencia a varios valores, el acceso al mapa devolverá de forma determinística el primer valor.

Esto puede suceder en cualquiera de los siguientes casos:

• Una etiqueta tiene una clave duplicada.

  La estructura de la etiqueta representa un mapa, pero no aplica la unicidad de la clave. Por convención, un mapa debe tener claves únicas, por lo que Google SecOps no recomienda completar una etiqueta con claves duplicadas.

  El texto de la regla $e.metadata.ingestion_labels["dupe-key"] devolvería el primer valor posible, val1, si se ejecuta en el siguiente ejemplo de datos:

  // Disrecommended usage of label with a duplicate key:
  event {
    metadata{
      ingestion_labels{
        key: "dupe-key"
        value: "val1" // This is the first possible value for "dupe-key"
      }
      ingestion_labels{
        key: "dupe-key"
        value: "val2"
      }
    }
  }
  

• Una etiqueta tiene un campo repetido de elemento superior.

  Un campo repetido puede contener una etiqueta como campo secundario. Dos entradas diferentes en el campo repetido de nivel superior pueden contener etiquetas que tienen la misma clave. El texto de la regla $e.security_result.rule_labels["key"] devolvería el primer valor posible, val3, si se ejecutara en el siguiente ejemplo de datos:

  event {
    // security_result is a repeated field.
    security_result {
      threat_name: "threat1"
      rule_labels {
        key: "key"
        value: "val3" // This is the first possible value for "key"
      }
    }
    security_result {
      threat_name: "threat2"
      rule_labels {
        key: "key"
        value: "val4"
      }
    }
  }
  

Funciones

En esta sección, se describen las funciones de YARA-L 2.0 que puedes usar en las reglas y la búsqueda del motor de detección.

Estas funciones se pueden usar en las siguientes partes de una regla de YARA-L:

• Sección events
• BOOL_CLAUSE de una condición en la sección de resultados.

arrays.concat

arrays.concat(string_array, string_array)

Descripción

Devuelve un nuevo array de cadenas copiando elementos de los arrays de cadenas originales.

Tipos de datos de parámetros

ARRAY_STRINGS, ARRAY_STRINGS

Tipo de datos que se muestra

ARRAY_STRINGS

Muestras de código

Ejemplo 1

En el siguiente ejemplo, se concatenan dos arrays de cadenas diferentes.

arrays.concat(["test1", "test2"], ["test3"]) = ["test1", "test2", "test3"]

Ejemplo 2

En el siguiente ejemplo, se concatenan arrays con una cadena vacía.

arrays.concat([""], [""]) = ["", ""]

Ejemplo 3

En el siguiente ejemplo, se concatenan arrays vacíos.

arrays.concat([], []) = []

arrays.join_string

arrays.join_string(array_of_strings, optional_delimiter)

Descripción

Convierte un array de cadenas en una sola cadena separada por el parámetro opcional. Si no se proporciona un delimitador, se usa la cadena vacía.

Tipos de datos de parámetros

ARRAY_STRINGS, STRING

Tipo de datos que se muestra

STRING

Muestras de código

Estos son algunos ejemplos de cómo usar la función:

Ejemplo 1

En este ejemplo, se une un array con elementos que no son nulos y un delimitador.

arrays.join_string(["foo", "bar"], ",") = "foo,bar"

Ejemplo 2

En este ejemplo, se une un array con un elemento nulo y un delimitador.

arrays.join_string(["foo", NULL, "bar"], ",") = "foo,bar"

Ejemplo 3

En este ejemplo, se une un array con elementos que no son nulos y sin delimitador.

arrays.join_string(["foo", "bar"]) = "foobar"

arrays.length

arrays.length(repeatedField)

Descripción

Devuelve la cantidad de elementos del campo repetido.

Tipos de datos de parámetros

LIST

Tipo de datos que se muestra

NUMBER

Muestras de código

Ejemplo 1

Devuelve la cantidad de elementos del campo repetido.

arrays.length($e.principal.ip) = 2

Ejemplo 2

Si hay varios campos repetidos a lo largo de la ruta, devuelve la cantidad total de elementos de campo repetidos.

arrays.length($e.intermediary.ip) = 3

arrays.max

arrays.max(array_of_ints_or_floats)

Descripción

Devuelve el elemento más grande de un array o cero si el array está vacío.

Tipos de datos de parámetros

ARRAY_INTS|ARRAY_FLOATS

Tipo de datos que se muestra

FLOAT

Muestras de código

Estos son algunos ejemplos de cómo usar la función:

Ejemplo 1

En este ejemplo, se devuelve el elemento mayor en un array de números enteros.

arrays.max([10, 20]) = 20.000000

Ejemplo 2

En este ejemplo, se devuelve el elemento mayor en un array de números de punto flotante.

arrays.max([10.000000, 20.000000]) = 20.000000

arrays.min

arrays.min(array_of_ints_or_floats[, ignore_zeros=false])

Descripción

Devuelve el elemento más pequeño de un array o cero si el array está vacío. Si el segundo argumento opcional se establece en verdadero, se ignoran los elementos iguales a cero.

Tipos de datos de parámetros

ARRAY_INTS|ARRAY_FLOATS, BOOL

Tipo de datos que se muestra

FLOAT

Muestras de código

Estos son algunos ejemplos de cómo usar la función:

Ejemplo 1

En este ejemplo, se muestra el elemento más pequeño de un array de números enteros.

arrays.min([10, 20]) = 10.000000

Ejemplo 2

En este ejemplo, se muestra el elemento más pequeño en un array de números de punto flotante.

arrays.min([10.000000, 20.000000]) = 10.000000

Ejemplo 3

En este ejemplo, se muestra el elemento más pequeño en un array de números de punto flotante, a la vez que se ignoran los ceros.

arrays.min([10.000000, 20.000000, 0.0], true) = 10.000000

arrays.size

arrays.size( array )

Descripción

Muestra el tamaño del arreglo. Muestra 0 para un arreglo vacío.

Tipos de datos de parámetros

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS

Tipo de datos que se muestra

INT

Muestras de código

Ejemplo 1

En este ejemplo, se usa un array de cadenas que contiene dos elementos.

arrays.size(["test1", "test2"]) = 2

Ejemplo 2

En este ejemplo, se usa un array de números enteros que contiene 3 elementos.

arrays.size([1, 2, 3]) = 3

Ejemplo 3

En este ejemplo, se usa un array de números de punto flotante que contiene 1 elemento.

arrays.size([1.200000]) = 1

Ejemplo 4

En este ejemplo, se usa un array vacío.

arrays.size([]) = 0

arrays.index_to_float

arrays.index_to_float(array, index)

Descripción

Devuelve el elemento en el índice determinado de un array. El elemento en ese índice se devuelve como un número de punto flotante.

El índice es un valor entero que representa la posición de un elemento en el array. De forma predeterminada, el primer elemento de un array tiene un índice de 0 y el último elemento tiene un índice de n-1, donde n es el tamaño del array. La indexación negativa permite acceder a los elementos del array en relación con el final del array. Por ejemplo, un índice de -1 hace referencia al último elemento del array y un índice de -2 hace referencia al penúltimo elemento del array.

Tipos de datos de parámetros

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS, INT

Tipo de datos que se muestra

FLOAT

Muestras de código

Ejemplo 1

En el siguiente ejemplo, se recupera un elemento en el índice 1 de un array de números de punto flotante.

arrays.index_to_float([1.2, 2.1, 3.5, 4.6], 1) // 2.1

Ejemplo 2

En el siguiente ejemplo, se recupera un elemento en el índice -1 de un array de números de punto flotante.

arrays.index_to_float([1.2, 2.1, 3.5, 4.6], 0-1) // 4.6

Ejemplo 3

En el siguiente ejemplo, se recupera un elemento para un índice mayor que el tamaño del array.

arrays.index_to_float([1.2, 2.1, 3.5, 4.6], 6) // 0.0

Ejemplo 4

En el siguiente ejemplo, se recupera un elemento de un array vacío.

arrays.index_to_float([], 0) // 0.0

Ejemplo 5

En el siguiente ejemplo, se recupera un elemento en el índice 1 de un array de cadenas.

arrays.index_to_float(["1.2", "3.3", "2.4"], 1) // 3.3

Ejemplo 6

En el siguiente ejemplo, se recupera un elemento en el índice 2 de un array de números enteros.

arrays.index_to_float([1, 3, 2], 2) // 2.0

arrays.index_to_int

arrays.index_to_int(array_of_inputs, index)

Descripción

Devuelve el valor en un índice determinado de un array como un número entero.

El índice es un valor entero que representa la posición de un elemento en el array. De forma predeterminada, el primer elemento de un array tiene un índice de 0 y el último elemento tiene un índice de n-1, donde n es el tamaño del array. La indexación negativa permite acceder a los elementos del array en relación con el final del array. Por ejemplo, un índice de -1 hace referencia al último elemento del array y un índice de -2 hace referencia al penúltimo elemento del array.

Tipos de datos de parámetros

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS, INT

Tipo de datos que se muestra

INT

Muestras de código

Ejemplo 1

Esta llamada a la función devuelve 0 cuando el valor en el índice es una cadena no numérica.

arrays.index_to_int(["str0", "str1", "str2"], 1) = 0

Ejemplo 2

Esta función devuelve el elemento en el índice -1.

arrays.index_to_int(["44", "11", "22", "33"], 0-1) = 33

Ejemplo 3

Devuelve 0 para el elemento fuera de los límites.

arrays.index_to_int(["44", "11", "22", "33"], 5) = 0

Ejemplo 4

Esta función recupera el elemento del array de números de punto flotante en el índice 1.

arrays.index_to_int([1.100000, 1.200000, 1.300000], 1) = 1

Ejemplo 5

Esta función recupera el elemento del array de números enteros en el índice 0.

arrays.index_to_int([1, 2, 3], 0) = 1

arrays.index_to_str

arrays.index_to_str(array, index)

Descripción

Devuelve el elemento en el índice determinado del array como una cadena. El índice es un valor entero que representa la posición de un elemento en el array. De forma predeterminada, el primer elemento de un array tiene un índice de 0 y el último elemento tiene un índice de n-1, donde n es el tamaño del array. La indexación negativa permite acceder a los elementos del array desde el final del array. Por ejemplo, un índice de -1 hace referencia al último elemento del array y un índice de -2 hace referencia al penúltimo elemento del array.

Tipos de datos de parámetros

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS, INT

Tipo de datos que se muestra

STRING

Muestras de código

Ejemplo 1

En el siguiente ejemplo, se recupera un elemento en el índice 1 de un array de cadenas.

arrays.index_to_str(["test1", "test2", "test3", "test4"], 1) // "test2"

Ejemplo 2

En el siguiente ejemplo, se recupera un elemento en el índice -1 (último elemento del array) de un array de cadenas.

arrays.index_to_str(["test1", "test2", "test3", "test4"], 0-1) // "test4"

Ejemplo 3

En el siguiente ejemplo, se recupera un elemento para un índice mayor que el tamaño del array, lo que devuelve una cadena vacía.

arrays.index_to_str(["test1", "test2", "test3", "test4"], 6) // ""

Ejemplo 4

En el siguiente ejemplo, se recupera un elemento de un array vacío.

arrays.index_to_str([], 0) // ""

Ejemplo 5

En el siguiente ejemplo, se recupera un elemento en el índice 0 de un array de números de punto flotante. El resultado se devuelve como una cadena.

arrays.index_to_str([1.200000, 3.300000, 2.400000], 0) // "1.2"

Ejemplo 6

En el siguiente ejemplo, se recupera un elemento en el índice 2 de un array de números enteros. El resultado se muestra en forma de una cadena.

arrays.index_to_str([1, 3, 2], 2) // "2"

cast.as_bool

cast.as_bool(string_or_int)

Descripción

La función convierte un valor int o string en un valor bool. Las llamadas a funciones con valores que no se pueden convertir devolverán FALSE. Devuelve VERDADERO solo para el número entero 1 y la cadena "true" que no distingue mayúsculas de minúsculas.

Tipos de datos de parámetros

INT|STRING

Tipo de datos que se muestra

BOOL

Muestras de código

Ejemplo 1

En este ejemplo, se muestra cómo convertir una cadena no booleana

cast.as_bool("123") = false

Ejemplo 2

Número entero verdadero (1)

cast.as_bool(1) = true

Ejemplo 3

Cadena verdadera

cast.as_bool("true") = true

Ejemplo 4

Cadena verdadera con mayúsculas

cast.as_bool("TRUE") = true

Ejemplo 5

Número entero negativo

cast.as_bool(0-1) = false

Ejemplo 6

Número entero falso (0)

cast.as_bool(0) = false

Ejemplo 7

string vacía

cast.as_bool("") = false

cast.as_float

cast.as_float(string_to_cast)

Descripción

Convierte una cadena numérica en un número de punto flotante. Cualquier llamada a una función con valores que no se puedan convertir devolverá 0. Los números de punto flotante mantienen la precisión hasta 7 dígitos decimales.

Tipos de datos de parámetros

STRING

Tipo de datos que se muestra

FLOAT

Muestras de código

Ejemplo 1

Si se convierte una cadena no numérica, se devuelve 0.

cast.as_float("str") = 0.0000000

Ejemplo 2

La conversión de una cadena vacía devuelve 0.

cast.as_float("") = 0.0000000

Ejemplo 3

Si se convierte una cadena numérica válida, se devuelve un valor de número de punto flotante.

cast.as_float("1.012345678") = 1.0123456

cast.as_string

cast.as_string(int_or_bytes_or_bool, optional_default_string)

Descripción

La función cast.as_string transforma un valor de INT, BYTES o BOOL en su representación de cadena. Puedes proporcionar un argumento default_string opcional para controlar los casos en los que falla la transmisión. Si omites el argumento default_string o si la entrada es una secuencia de bytes UTF-8 o BASE64 no válida, la función devuelve una cadena vacía.

Tipos de datos de parámetros

INT|BYTES|BOOL, STRING

Tipo de datos que se muestra

STRING

Muestras de código

Conversión de números enteros a cadenas

La función convierte el número entero 123 en la cadena "123".

cast.as_string(123) = "123"

Conversión de flotante a cadena

La función convierte el número de punto flotante 2.25 en la cadena "2.25".

cast.as_string(2.25) = "2.25"

Conversión de bytes a cadena

La función convierte el b'01 binario sin procesar en la cadena "\x01".

cast.as_string(b'01, "") = "\x01"

Conversión de booleano a cadena

La función convierte el valor booleano true en la cadena "true".

cast.as_string(true, "") = "true"

Conversión fallida (se establece de forma predeterminada en la cadena proporcionada de forma opcional)

La función usa de forma predeterminada la cadena "casting error" cuando el valor proporcionado no es válido.

cast.as_string(9223372036854775808, "casting error") = "casting error"

Fingerprint

hash.fingerprint2011(byteOrString)

Descripción

Esta función calcula el hash fingerprint2011 de una secuencia de bytes o una cadena de entrada. Esta función devuelve un valor INT sin signo en el rango [2, 0xFFFFFFFFFFFFFFFF].

Tipos de datos de parámetros

BTYE, STRING

Tipo de datos que se muestra

INT

Muestra de código

id_fingerprint = hash.fingerprint2011("user123")

grupo

group(field1, field2, field3, ...)

Descripción

Agrupa los campos de un tipo similar en una variable de marcador de posición.

En la búsqueda de UDM, se usan campos agrupados para buscar en varios campos de un tipo similar. La función de grupo es similar a los campos agrupados, excepto que te permite seleccionar qué campos deseas agrupar para activar una detección. Puedes usar la función group para recopilar información sobre una entidad específica (por ejemplo, un nombre de host, una dirección IP o un ID de usuario) en diferentes tipos de sustantivos.

Muestras de código

Ejemplo 1

Agrupa todas las direcciones IP y proporciona un recuento descendente de la dirección IP más frecuente en el período analizado.

$ip = group(principal.ip, about.ip, target.ip)
$ip != ""
match:
  $ip
outcome:
  $count = count_distinct(metadata.id)
order:
  $count desc

hash.sha256

hash.sha256(string)

Descripción

Devuelve un hash SHA-256 de la cadena de entrada.

Tipos de datos de parámetros

STRING

Tipo de datos que se muestra

STRING

Muestras de código

Ejemplo 1

En este ejemplo, se muestra el hash SHA-256 cuando la entrada es una cadena válida.

hash.sha256("str") = "8c25cb3686462e9a86d2883c5688a22fe738b0bbc85f458d2d2b5f3f667c6d5a"

Ejemplo 2

En este ejemplo, se muestra el hash SHA-256 cuando la entrada es una cadena vacía.

hash.sha256("") = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

math.abs

math.abs(numericExpression)

Descripción

Devuelve el valor absoluto de una expresión de número entero o de punto flotante.

Tipos de datos de parámetros

NUMBER

Tipo de datos que se muestra

NUMBER

Muestras de código

Ejemplo 1

En este ejemplo, se devuelve True si el evento ocurrió más de 5 minutos después de la hora especificada (en segundos desde la época de Unix), independientemente de si el evento ocurrió antes o después de la hora especificada. Una llamada a math.abs no puede depender de varias variables o marcadores de posición. Por ejemplo, no puedes reemplazar el valor de tiempo codificado de 1643687343 en el siguiente ejemplo por $e2.metadata.event_timestamp.seconds.

300 < math.abs($e1.metadata.event_timestamp.seconds - 1643687343)

math.ceil

math.ceil(number)

Descripción

Devuelve el número entero más pequeño que no es menor que el número determinado (redondeo hacia arriba). Devolverá 0 si la entrada es nula o demasiado grande para caber en un int64.

Tipos de datos de parámetros

FLOAT

Tipo de datos que se muestra

INT

Muestras de código

En esta sección, se incluyen ejemplos del uso de math.ceil.

Ejemplo 1

En este ejemplo, se devuelve el valor de ceil de un número entero.

math.ceil(2.000000) = 2

Ejemplo 2

En este ejemplo, se devuelve el valor de ceil de un número negativo.

math.ceil(0-1.200000) = -1

Ejemplo 3

En este ejemplo, se devuelve 0 como el límite superior de un número demasiado grande para un número entero de 64 bits.

math.ceil(184467440737095516160.0) = 0

math.floor

math.floor(float_val)

Descripción

Devuelve el valor entero más grande que no es mayor que el valor proporcionado (redondeo hacia abajo). Devuelve 0 si la entrada es nula o demasiado grande para caber en un int64.

Tipos de datos de parámetros

FLOAT

Tipo de datos que se muestra

INT

Muestras de código

Ejemplo 1

En este ejemplo, se muestra un caso de número positivo.

math.floor(1.234568) = 1

Ejemplo 2

En este ejemplo, se muestra un caso de número negativo.

math.floor(0-1.234568) = -2

Ejemplo 3

En este ejemplo, se muestra un caso de cero.

math.floor(0.000000) = 0

math.geo_distance

math.geo_distance(longitude1, latitude1, longitude2, latitude2))

Descripción

Devuelve la distancia entre dos ubicaciones geográficas (coordenadas) en metros. Devuelve -1 si las coordenadas no son válidas.

Tipos de datos de parámetros

FLOAT, FLOAT, FLOAT, FLOAT

Tipo de datos que se muestra

FLOAT

Muestras de código

Ejemplo 1

En el siguiente ejemplo, se devuelve la distancia cuando todos los parámetros son coordenadas válidas:

math.geo_distance(-122.020287, 37.407574, -122.021810, 37.407574) = 134.564318

Ejemplo 2

En el siguiente ejemplo, se muestra la distancia cuando uno de los parámetros es una coordenada truncada:

math.geo_distance(-122.000000, 37.407574, -122.021810, 37.407574) = 1926.421905

Ejemplo 3

En el siguiente ejemplo, se devuelve -1 cuando uno de los parámetros es una coordenada no válida:

math.geo_distance(0-122.897680, 37.407574, 0-122.021810, 97.407574) = -1.000000

Ejemplo 4

El siguiente ejemplo devuelve 0 cuando las coordenadas son las mismas:

math.geo_distance(-122.897680, 37.407574, -122.897680, 37.407574) = 0.000000

math.is_increasing

math.is_increasing(num1, num2, num3)

Descripción

Toma una lista de valores numéricos (números enteros o dobles) y devuelve True si los valores están en orden ascendente y False en caso contrario.

Tipos de datos de parámetros

INT|FLOAT, INT|FLOAT, INT|FLOAT

Tipo de datos que se muestra

BOOL

Muestras de código

Ejemplo 1

En este ejemplo, se incluyen valores similares a marcas de tiempo en segundos.

math.is_increasing(1716769112, 1716769113, 1716769114) = true

Ejemplo 2

En este ejemplo, se incluyen un valor negativo de tipo double, un valor cero de tipo INT64 y un valor positivo de tipo INT64.

math.is_increasing(-1.200000, 0, 3) = true

Ejemplo 3

En este ejemplo, se incluyen un valor de doble negativo, un valor de INT64 cero y un valor de INT64 negativo.

math.is_increasing(0-1.200000, 0, 0-3) = false

Ejemplo 4

En este ejemplo, se incluyen dos números de punto flotante negativos de doble precisión y un valor INT64 de cero.

math.is_increasing(0-1.200000, 0-1.50000, 0) = false

Ejemplo 5

Este ejemplo incluye un número doble negativo y dos valores iguales.

math.is_increasing(0-1.200000, 0, 0) = false

math.log

math.log(numericExpression)

Descripción

Devuelve el valor del logaritmo natural de una expresión de número entero o de punto flotante.

Tipos de datos de parámetros

NUMBER

Tipo de datos que se muestra

NUMBER

Muestras de código

Ejemplo 1

math.log($e1.network.sent_bytes) > 20

math.pow

math.pow(base, exponent)

Descripción

Devuelve el valor del primer argumento elevado a la potencia del segundo argumento. Devuelve 0 en caso de desbordamiento.

Tipos de datos de parámetros

Base: INT|FLOAT Exponente: INT|FLOAT

Tipo de datos que se muestra

FLOAT

Muestras de código

Ejemplo 1

En este ejemplo, se muestra un caso de números enteros.

math.pow(2, 2) // 4.00

Ejemplo 2

En este ejemplo, se muestra un caso base de fracción.

math.pow(2.200000, 3) // 10.648

Ejemplo 3

En este ejemplo, se muestra un caso de base y potencia de fracciones.

math.pow(2.200000, 1.200000) // 2.575771

Ejemplo 4

En este ejemplo, se muestra un caso de potencia negativa.

math.pow(3, 0-3) // 0.037037

Ejemplo 5

En este ejemplo, se muestra un caso de potencia fraccionaria.

math.pow(3, 0-1.200000) // 0.267581

Ejemplo 6

En este ejemplo, se muestra un caso base negativo.

math.pow(0-3, 0-3) // -0.037037

Ejemplo 7

En este ejemplo, se muestra un caso de base cero.

math.pow(0, 3) // 0

Ejemplo 8

En este ejemplo, se muestra un caso de potencia cero.

math.pow(9223372036854775807, 0) // 1

Ejemplo 9

En este ejemplo, se muestra un caso base grande.

math.pow(9223372036854775807, 1.200000) // 57262152889751593549824

math.random

math.random()

Descripción

Genera un valor seudoaleatorio de tipo DOUBLE en el rango de [0, 1), el cual incluye 0 pero no 1.

Tipo de datos que se muestra

FLOAT

Muestras de código

En el siguiente ejemplo, se verifica si el valor aleatorio se encuentra en el rango [0, 1). none if(math.random() >= 0 and math.random() < 1) = true

math.round

math.round(numericExpression, decimalPlaces)

Descripción

Devuelve un valor redondeado al número entero más cercano o a la cantidad de posiciones decimales especificada.

Tipos de datos de parámetros

NUMBER

Tipo de datos que se muestra

NUMBER

Muestras de código

math.round(10.7) // returns 11
math.round(1.2567, 2) // returns 1.25
math.round(0-10.7) // returns -11
math.round(0-1.2) // returns -1
math.round(4) // returns 4, math.round(integer) returns the integer

math.sqrt

math.sqrt(number)

Descripción

Devuelve la raíz cuadrada del número especificado. Devuelve 0 en caso de números negativos.

Tipos de datos de parámetros

INT|FLOAT

Tipo de datos que se muestra

FLOAT

Muestras de código

Ejemplo 1

En este ejemplo, se muestra la raíz cuadrada de un argumento int.

math.sqrt(3) = 1.732051

Ejemplo 2

En este ejemplo, se muestra la raíz cuadrada de un argumento int negativo.

math.sqrt(-3) = 0.000000

Ejemplo 3

En este ejemplo, se muestra la raíz cuadrada del argumento cero.

math.sqrt(0) = 0.000000

Ejemplo 4

En este ejemplo, se muestra la raíz cuadrada de un argumento de número de punto flotante.

math.sqrt(9.223372) = 3.037000

Ejemplo 5

En este ejemplo, se muestra la raíz cuadrada de un argumento de número de punto flotante negativo.

math.sqrt(0-1.200000) = 0.000000

métricas

Las funciones de métricas pueden agregar grandes cantidades de datos históricos. Puedes usarlo en tu regla con metrics.functionName() en la sección de resultados.

Para obtener más información, consulta Métricas de YARA-L.

net.ip_in_range_cidr

net.ip_in_range_cidr(ipAddress, subnetworkRange)

Descripción

Devuelve true cuando la dirección IP proporcionada está dentro de la subred especificada.

Puedes usar YARA-L para buscar eventos de UDM en todas las direcciones IP de una subred con la instrucción net.ip_in_range_cidr(). Se admiten IPv4 e IPv6.

Para buscar en un rango de direcciones IP, especifica un campo de UDM de IP y un rango de CIDR. YARA-L puede controlar campos de direcciones IP únicos y repetidos.

Para buscar en un rango de direcciones IP, especifica un campo de ip UDM y un rango de enrutamiento entre dominios sin clases (CIDR). YARA-L puede controlar campos de direcciones IP únicos y repetidos.

Tipos de datos de parámetros

STRING, STRING

Tipo de datos que se muestra

BOOL

Muestras de código

Ejemplo 1

Ejemplo de IPv4:

net.ip_in_range_cidr($e.principal.ip, "192.0.2.0/24")

Ejemplo 2

Ejemplo de IPv6:

net.ip_in_range_cidr($e.network.dhcp.yiaddr, "2001:db8::/32")

Para ver un ejemplo de regla que usa la instrucción net.ip_in_range_cidr(), consulta la regla de ejemplo en Evento único dentro de un rango de direcciones IP.

re.regex

Puedes definir la coincidencia de expresiones regulares en YARA-L 2.0 con cualquiera de las siguientes sintaxis:

• Uso de la sintaxis de YARA-L: Se relaciona con los eventos. A continuación, se muestra una representación genérica de esta sintaxis:

  $e.field = /regex/
  

• Usa la sintaxis de YARA-L como una función que toma los siguientes parámetros:

  • Campo al que se aplica la expresión regular.
  • Expresión regular especificada como una cadena.

  A continuación, se muestra una representación genérica de esta sintaxis:

  re.regex($e.field, `regex`)
  

Descripción

Esta función devuelve true si la cadena contiene una subcadena que coincide con la expresión regular proporcionada. No es necesario agregar .* al principio ni al final de la expresión regular.

Notas

• Para que coincida la cadena exacta o solo un prefijo o sufijo, incluye los caracteres de anclaje ^ (inicial) y $ (final) en la expresión regular. Por ejemplo, /^full$/ coincide exactamente con "full", mientras que /full/ podría coincidir con "fullest", "lawfull" y "joyfully".
• Si el campo de UDM incluye caracteres de salto de línea, regexp solo coincide con la primera línea del campo de UDM. Para aplicar la coincidencia completa de los campos de UDM, agrega un (?s) a la expresión regular. Por ejemplo, reemplaza /.*allUDM.*/ por /(?s).*allUDM.*/.
• Puedes usar el modificador nocase después de las cadenas para indicar que la búsqueda debe ignorar el uso de mayúsculas.

Tipos de datos de parámetros

STRING, STRING

Tipos de expresiones de parámetros

ANY, ANY

Tipo de datos que se muestra

BOOL

Muestras de código

Ejemplo 1

// Equivalent to $e.principal.hostname = /google/
re.regex($e.principal.hostname, "google")

re.capture

re.capture(stringText, regex)

Descripción

Captura (extrae) datos de una cadena con el patrón de expresión regular proporcionado en el argumento.

Esta función toma dos argumentos:

• stringText: Es la cadena original en la que se realizará la búsqueda.
• regex: Es la expresión regular que indica el patrón que se debe buscar.

La expresión regular puede contener 0 o 1 grupos de captura entre paréntesis. Si la expresión regular contiene 0 grupos de captura, la función devuelve la primera substring coincidente completa. Si la expresión regular contiene 1 grupo de captura, devuelve la primera substring coincidente para el grupo de captura. Si se definen dos o más grupos de captura, se muestra un error del compilador.

Tipos de datos de parámetros

STRING, STRING

Tipo de datos que se muestra

STRING

Muestras de código

Ejemplo 1

En este ejemplo, si $e.principal.hostname contiene "aaa1bbaa2", lo siguiente sería verdadero, ya que la función devuelve la primera instancia. Este ejemplo no tiene grupos de captura.

"aaa1" = re.capture($e.principal.hostname, "a+[1-9]")

Ejemplo 2

En este ejemplo, se captura todo lo que se encuentra después del símbolo @ en un correo electrónico. Si el campo $e.network.email.from es test@google.com, el ejemplo devuelve google.com. El siguiente ejemplo contiene un grupo de captura.

"google.com" = re.capture($e.network.email.from , "@(.*)")

Ejemplo 3

Si la expresión regular no coincide con ninguna substring del texto, la función devuelve una cadena vacía. Puedes omitir los eventos en los que no se produce ninguna coincidencia excluyendo la cadena vacía, lo que es especialmente importante cuando usas re.capture() con una desigualdad:

// Exclude the empty string to omit events where no match occurs.
"" != re.capture($e.network.email.from , "@(.*)")

// Exclude a specific string with an inequality.
"google.com" != re.capture($e.network.email.from , "@(.*)")

re.replace

re.replace(stringText, replaceRegex, replacementText)

Descripción

Realiza un reemplazo de expresión regular.

Esta función toma tres argumentos:

• stringText: Es la cadena original.
• replaceRegex: Es la expresión regular que indica el patrón que se debe buscar.
• replacementText: Es el texto que se insertará en cada coincidencia.

Devuelve una nueva cadena derivada de la stringText original, en la que todas las subcadenas que coinciden con el patrón en replaceRegex se reemplazan por el valor en replacementText. Puedes usar dígitos con escape de barras invertidas (\1 a \9) dentro de replacementText para insertar texto que coincida con el grupo entre paréntesis correspondiente en el patrón replaceRegex. Usa \0 para hacer referencia a todo el texto coincidente.

La función reemplaza las coincidencias no superpuestas y priorizará el reemplazo de la primera ocurrencia que se encuentre. Por ejemplo, re.replace("banana", "ana", "111") devuelve la cadena "b111na".

Tipos de datos de parámetros

STRING, STRING, STRING

Tipo de datos que se muestra

STRING

Muestras de código

Ejemplo 1

En este ejemplo, se captura todo lo que se encuentra después del símbolo @ en un correo electrónico, se reemplaza com por org y, luego, se muestra el resultado. Observa el uso de funciones anidadas.

"email@google.org" = re.replace($e.network.email.from, "com", "org")

Ejemplo 2

En este ejemplo, se usan dígitos con escape de barra invertida en el argumento replacementText para hacer referencia a coincidencias con el patrón replaceRegex.

"test1.com.google" = re.replace(
                       $e.principal.hostname, // holds "test1.test2.google.com"
                       "test2\.([a-z]*)\.([a-z]*)",
                       "\\2.\\1"  // \\1 holds "google", \\2 holds "com"
                     )

Ejemplo 3

Ten en cuenta los siguientes casos cuando trabajes con cadenas vacías y re.replace():

Usa una cadena vacía como replaceRegex:

// In the function call below, if $e.principal.hostname contains "name",
// the result is: 1n1a1m1e1, because an empty string is found next to
// every character in `stringText`.
re.replace($e.principal.hostname, "", "1")

Para reemplazar una cadena vacía, puedes usar "^$" como replaceRegex:

// In the function call below, if $e.principal.hostname contains the empty
// string, "", the result is: "none".
re.replace($e.principal.hostname, "^$", "none")

sample_rate

optimization.sample_rate(byteOrString, rateNumerator, rateDenominator)

Descripción

Esta función determina si se debe incluir un evento según una estrategia de muestreo determinística. Esta función devuelve lo siguiente:

• true para una fracción de los valores de entrada, equivalente a (rateNumerator / rateDenominator), lo que indica que el evento se debe incluir en la muestra.
• false, que indica que el evento no se debe incluir en la muestra.

Esta función es útil para situaciones de optimización en las que solo deseas procesar un subconjunto de eventos. Equivale a:

hash.fingerprint2011(byteOrString) % rateDenominator < rateNumerator

Tipos de datos de parámetros

• byteOrString: Expresión que se evalúa como BYTE o STRING.
• rateNumerator: "INT"
• rateDenominator: "INT"

Tipo de datos que se muestra

BOOL

Muestra de código

events:
    $e.metadata.event_type = "NETWORK_CONNECTION"
    $asset_id = $e.principal.asset.asset_id
    optimization.sample_rate($e.metadata.id, 1, 5) // Only 1 out of every 5 events

  match:
    $asset_id over 1h

  outcome:
    $event_count = count_distinct($e.metadata.id)
  // estimate the usage by multiplying by the inverse of the sample rate
    $usage_past_hour = sum(5.0 * $e.network.sent_bytes)

 condition:
  // Requiring a certain number of events after sampling avoids bias (e.g. a
  // device with just 1 connection will still show up 20% of the time and
  // if we multiply that traffic by 5, we'll get an incorrect estimate)
  $e and ($usage_past_hour > 1000000000) and $event_count >= 100

strings.base64_decode

strings.base64_decode(encodedString)

Descripción

Devuelve una cadena que contiene la versión decodificada en base64 de la cadena codificada.

Esta función toma una cadena codificada en base64 como argumento. Si encodedString no es una cadena codificada en base64 válida, la función devuelve encodedString sin cambios.

Tipos de datos de parámetros

STRING

Tipo de datos que se muestra

STRING

Muestras de código

Ejemplo 1

"test" = strings.base64_decode($e.principal.domain.name)

strings.coalesce

strings.coalesce(a, b, c, ...)

Descripción

Esta función toma una cantidad ilimitada de argumentos y devuelve el valor de la primera expresión que no se evalúa como una cadena vacía (por ejemplo, "valor distinto de cero"). Si todos los argumentos se evalúan como una cadena vacía, la llamada a la función devuelve una cadena vacía.

Los argumentos pueden ser literales, campos de eventos o llamadas a funciones. Todos los argumentos deben ser del tipo STRING. Si algún argumento es un campo de evento, los atributos deben ser del mismo evento.

Tipos de datos de parámetros

STRING

Tipo de datos que se muestra

STRING

Muestras de código

Ejemplo 1

En el siguiente ejemplo, se incluyen variables de cadena como argumentos. La condición se evalúa como verdadera cuando (1) $e.network.email.from es suspicious@gmail.com o (2) $e.network.email.from está vacío y $e.network.email.to es suspicious@gmail.com.

"suspicious@gmail.com" = strings.coalesce($e.network.email.from, $e.network.email.to)

Ejemplo 2

En el siguiente ejemplo, se llama a la función coalesce con más de dos argumentos. Esta condición compara la primera dirección IP no nula del evento $e con los valores de la lista de referencia ip_watchlist. El orden en que se unen los argumentos en esta llamada es el mismo en que se enumeran en la condición de la regla:

1. $e.principal.ip se evalúa primero.
2. A continuación, se evalúa $e.src.ip.
3. A continuación, se evalúa $e.target.ip.
4. Por último, la cadena "No IP" se devuelve como un valor predeterminado si los campos ip anteriores no están configurados.

strings.coalesce($e.principal.ip, $e.src.ip, $e.target.ip, "No IP") in %ip_watchlist

Ejemplo 3

En el siguiente ejemplo, se intenta fusionar principal.hostname del evento $e1 y el evento $e2. Devolverá un error del compilador porque los argumentos son variables de eventos diferentes.

// returns a compiler error
"test" = strings.coalesce($e1.principal.hostname, $e2.principal.hostname)

strings.concat

strings.concat(a, b, c, ...)

Descripción

Devuelve la concatenación de una cantidad ilimitada de elementos, cada uno de los cuales puede ser una cadena, un número entero o un número de punto flotante.

Si algún argumento es un campo de evento, los atributos deben ser del mismo evento.

Tipos de datos de parámetros

STRING, FLOAT, INT

Tipo de datos que se muestra

STRING

Muestras de código

Ejemplo 1

En el siguiente ejemplo, se incluyen una variable de cadena y una variable de número entero como argumentos. Tanto principal.hostname como principal.port provienen del mismo evento, $e, y se concatenan para devolver una cadena.

"google:80" = strings.concat($e.principal.hostname, ":", $e.principal.port)

Ejemplo 2

En el siguiente ejemplo, se incluyen una variable de cadena y un literal de cadena como argumentos.

"google-test" = strings.concat($e.principal.hostname, "-test") // Matches the event when $e.principal.hostname = "google"

Ejemplo 3

En el siguiente ejemplo, se incluyen una variable de cadena y un literal de número de punto flotante como argumentos. Cuando se representan como cadenas, los números de punto flotante que son números enteros se formatean sin el punto decimal (por ejemplo, 1.0 se representa como "1"). Además, los números de punto flotante que superan los dieciséis dígitos decimales se truncan en el decimosexto lugar decimal.

"google2.5" = strings.concat($e.principal.hostname, 2.5)

Ejemplo 4

En el siguiente ejemplo, se incluyen una variable de cadena, un literal de cadena, una variable de número entero y un literal de número de punto flotante como argumentos. Todas las variables provienen del mismo evento, $e, y se concatenan con los literales para devolver una cadena.

"google-test802.5" = strings.concat($e.principal.hostname, "-test", $e.principal.port, 2.5)

Ejemplo 5

En el siguiente ejemplo, se intenta concatenar principal.port del evento $e1 con principal.hostname del evento $e2. Devolverá un error del compilador porque los argumentos son variables de eventos diferentes.

// Will not compile
"test" = strings.concat($e1.principal.port, $e2.principal.hostname)

strings.contains

strings.contains( str, substr )

Descripción

Devuelve verdadero si una cadena determinada contiene la subcadena especificada. De lo contrario, devuelve falso.

Tipos de datos de parámetros

STRING, STRING

Tipo de datos que se muestra

BOOL

Muestras de código

Ejemplo 1

Este ejemplo devuelve verdadero porque la cadena tiene una subcadena "is".

strings.contains("thisisastring", "is") = true

Ejemplo 2

Este ejemplo devuelve "false" porque la cadena no tiene la subcadena "that".

strings.contains("thisisastring", "that") = false

strings.count_substrings

strings.count_substrings(string_to_search_in, substring_to_count)

Descripción

Cuando se le proporciona una cadena y una subcadena, devuelve un valor int64 del recuento de ocurrencias no superpuestas de la subcadena dentro de la cadena.

Tipos de datos de parámetros

STRING, STRING

Tipo de datos que se muestra

INT

Muestras de código

En esta sección, se incluyen ejemplos que calculan la cantidad de veces que aparece una subcadena en una cadena determinada.

Ejemplo 1

En este ejemplo, se usa una cadena no nula y un carácter de subcadena único no nulo.

strings.count_substrings("this`string`has`four`backticks", "`") = 4

Ejemplo 2

En este ejemplo, se usa una cadena no nula y una subcadena no nula de más de un carácter.

strings.count_substrings("str", "str") = 1

Ejemplo 3

En este ejemplo, se usa una cadena no nula y una subcadena vacía.

strings.count_substrings("str", "") = 0

Ejemplo 4

En este ejemplo, se usa una cadena vacía y una subcadena no nula de más de un carácter.

strings.count_substrings("", "str") = 0

Ejemplo 5

En este ejemplo, se usa una cadena vacía y una subcadena vacía.

strings.count_substrings("", "") = 0

Ejemplo 6

En este ejemplo, se usa una cadena no nula y una subcadena no nula que tiene más de un carácter y más de una ocurrencia.

strings.count_substrings("fooABAbarABAbazABA", "AB") = 3

Ejemplo 7

En este ejemplo, se usa una cadena no nula y una subcadena no nula que tiene más de un carácter y más de una ocurrencia. Destaca la limitación con las ocurrencias de subcadenas superpuestas

strings.count_substrings("ABABABA", "ABA") = 2

strings.extract_domain

strings.extract_domain(url_string)

Descripción

Extrae el dominio de una cadena.

Tipos de datos de parámetros

STRING

Tipo de datos que se muestra

STRING

Muestras de código

Ejemplo 1

En este ejemplo, se muestra una cadena vacía.

strings.extract_domain("") = ""

Ejemplo 2

Cadena aleatoria, no es una URL

strings.extract_domain("1234") = ""

Ejemplo 3

Varias barras inversas

strings.extract_domain("\\\\") = ""

Ejemplo 4

Los caracteres que no son alfabéticos se controlan correctamente.

strings.extract_domain("http://例子.卷筒纸.中国") = "卷筒纸.中国"

Ejemplo 5

Cómo controlar los URIs

strings.extract_domain("mailto:?to=&subject=&body=") = ""

Ejemplo 6

Varios caracteres antes de la URL real

strings.extract_domain("     \t   !$5*^)&dahgsdfs;http://www.google.com") = "google.com"

Ejemplo 7

caracteres especiales en el URI #

strings.extract_domain("test#@google.com") = ""

Ejemplo 8

Caracteres especiales en la URL #

strings.extract_domain("https://test#@google.com") = ""

Ejemplo 9

caso de prueba positivo

strings.extract_domain("https://google.co.in") = "google.co.in"

strings.extract_hostname

strings.extract_hostname(string)

Descripción

Extrae el nombre de host de una cadena. Esta función distingue mayúsculas de minúsculas.

Tipos de datos de parámetros

STRING

Tipo de datos que se muestra

STRING

Muestras de código

Ejemplo 1

En este ejemplo, se devuelve una cadena vacía.

strings.extract_hostname("") = ""

Ejemplo 2

Cadena aleatoria, no es una URL

strings.extract_hostname("1234") = "1234"

Ejemplo 3

Varias barras inversas

strings.extract_hostname("\\\\") = ""

Ejemplo 4

Los caracteres que no son en inglés se controlan con facilidad.

strings.extract_hostname("http://例子.卷筒纸.中国") = "例子.卷筒纸.中国"

Ejemplo 5

Cómo controlar los URIs

strings.extract_hostname("mailto:?to=&subject=&body=") = "mailto"

Ejemplo 6

Varios caracteres antes de la URL real

strings.extract_hostname("     \t   !$5*^)&dahgsdfs;http://www.google.com") = "www.google.com"

Ejemplo 7

caracteres especiales en el URI #

strings.extract_hostname("test#@google.com") = "test"

Ejemplo 8

Caracteres especiales en la URL #

strings.extract_hostname("https://test#@google.com") = "test"

strings.from_base64

strings.from_base64(base64_encoded_string)

Descripción

La función convierte un valor STRING codificado en base64 en un valor BYTES binario sin procesar. Las llamadas a funciones con valores que no se pueden convertir devuelven un BYTES vacío de forma predeterminada.

Tipos de datos de parámetros

STRING

Tipo de datos que se muestra

BYTES

Muestras de código

Conversión de cadenas codificadas en Base64 a bytes

La función convierte una cadena codificada en base64 en su representación de bytes binarios sin procesar.

strings.from_base64("AAAAAG+OxVhtAm+d2sVuny/hW4oAAAAAAQAAAM0AAAA=") = b'000000006f8ec5586d026f9ddac56e9f2fe15b8a0000000001000000cd000000

Conversión fallida (el valor predeterminado son bytes vacíos)

Si el valor proporcionado no es válido, la función se establece de forma predeterminada en bytes vacíos.

strings.from_base64("invalid-value") = b'

strings.from_hex

strings.from_hex(hex_string)

Descripción

Devuelve los bytes asociados con la cadena hexadecimal determinada.

Tipos de datos de parámetros

STRING

Tipo de datos que se muestra

BYTES

Muestras de código

Obtén los bytes asociados con una cadena hexadecimal determinada.

Ejemplo 1

En este ejemplo, se muestran las conversiones de caracteres no hexadecimales.

strings.from_hex("str") // returns empty bytes

Ejemplo 2

En este ejemplo, se muestra una entrada con una cadena vacía.

strings.from_hex("") // returns empty bytes

Ejemplo 3

En este ejemplo, se muestra la conversión de cadenas hexadecimales.

strings.from_hex("1234") // returns 1234 bytes

Ejemplo 4

En este ejemplo, se muestra la conversión de caracteres no ASCII.

strings.from_hex("筒纸.中国") // returns empty bytes

strings.length

strings.length(string_value)

Descripción

Devuelve la cantidad de caracteres de la cadena de entrada.

Tipos de datos de parámetros

STRING

Tipo de datos que se muestra

INT

Muestras de código

Ejemplo 1

A continuación, se muestra un ejemplo con una prueba de cadena.

strings.length("str") = 3

Ejemplo 2

A continuación, se muestra un ejemplo con una cadena vacía como entrada.

strings.length("") = 0

Ejemplo 3

A continuación, se muestra un ejemplo con una cadena de caracteres especiales.

strings.length("!@#$%^&*()-_") = 12

Ejemplo 4

A continuación, se muestra un ejemplo con una cadena que incluye espacios.

strings.length("This is a test string") = 21

strings.ltrim

strings.ltrim(string_to_trim, cutset)

Descripción

Quita los espacios en blanco iniciales de una cadena determinada. Esta función quita los caracteres iniciales presentes en ese conjunto de caracteres.

Tipos de datos de parámetros

STRING, STRING

Tipo de datos que se muestra

STRING

Muestras de código

A continuación, se muestran ejemplos de casos de uso.

Ejemplo 1

En este ejemplo, se usan el mismo primer y segundo argumento.

strings.ltrim("str", "str") = ""

Ejemplo 2

En este ejemplo, se usa una cadena vacía como segundo argumento.

strings.ltrim("str", "") = "str"

Ejemplo 3

En este ejemplo, se usa una cadena vacía como primer argumento y una cadena como segundo argumento.

strings.ltrim("", "str") = ""

Ejemplo 4

En este ejemplo, se usan cadenas que contienen espacios en blanco y una cadena como segundo argumento.

strings.ltrim("a aastraa aa ", " a") = "straa aa "

strings.reverse

strings.reverse(STRING)

Descripción

Devuelve una cadena que es la inversa de la cadena de entrada.

Tipos de datos de parámetros

STRING

Tipo de datos que se muestra

STRING

Muestras de código

Ejemplo 1

En el siguiente ejemplo, se pasa una cadena corta.

strings.reverse("str") = "rts"  // The function returns 'rts'.

Ejemplo 2

En el siguiente ejemplo, se pasa una cadena vacía.

strings.reverse("") = ""

Ejemplo 3

En el siguiente ejemplo, se pasa un palíndromo.

strings.reverse("tacocat") = "tacocat"

strings.rtrim

strings.rtrim(string_to_trim, cutset)

Descripción

Quita los espacios en blanco finales de una cadena determinada. Quita los caracteres finales que están presentes en ese conjunto de corte.

Tipos de datos de parámetros

STRING, STRING

Tipo de datos que se muestra

STRING

Muestras de código

A continuación, se muestran ejemplos de casos de uso.

Ejemplo 1

En el siguiente ejemplo, se pasa la misma cadena como el primer y el segundo argumento.

strings.rtrim("str", "str") = ""

Ejemplo 2

En el siguiente ejemplo, se pasa una cadena vacía como segundo argumento.

strings.rtrim("str", "") = "str"

Ejemplo 3

En el siguiente ejemplo, se pasa una cadena vacía como primer argumento y una cadena no vacía como segundo argumento.

strings.rtrim("", "str") = ""

Ejemplo 4

En el siguiente ejemplo, se pasa una cadena que contiene espacios en blanco como el primer argumento y una cadena no vacía como el segundo argumento.

strings.rtrim("a aastraa aa ", " a") = "a aasstr"

strings.to_lower

strings.to_lower(stringText)

Descripción

Esta función toma una cadena de entrada y devuelve una cadena después de cambiar todos los caracteres a minúsculas.

Tipos de datos de parámetros

STRING

Tipo de datos que se muestra

STRING

Muestras de código

Ejemplo 1

En el siguiente ejemplo, se devuelve true.

"test@google.com" = strings.to_lower($e.network.email.to)

strings.to_upper

strings.to_upper(string_val)

Descripción

Devuelve la cadena original con todos los caracteres alfabéticos en mayúsculas.

Tipos de datos de parámetros

STRING

Tipo de datos que se muestra

STRING

Muestras de código

Ejemplo 1

En el siguiente ejemplo, se devuelve el argumento proporcionado en mayúsculas.

strings.to_upper("example") = "EXAMPLE"

strings.trim

strings.trim(string_to_trim, cutset)

Descripción

Quita los espacios en blanco iniciales y finales de una cadena determinada. También quita los caracteres no deseados (especificados por el argumento cutset) de la cadena de entrada.

Tipos de datos de parámetros

STRING, STRING

Tipo de datos que se muestra

STRING

Muestras de código

A continuación, se muestran ejemplos de casos de uso.

Ejemplo 1

En el siguiente ejemplo, se pasa la misma cadena como la cadena de entrada y el conjunto de corte, lo que genera una cadena vacía.

strings.trim("str", "str") // ""

Ejemplo 2

En el siguiente ejemplo, se pasa una cadena vacía como el conjunto de corte, lo que genera la cadena original str porque no se especifican caracteres en el conjunto de corte para quitar.

strings.trim("str", "") = "str"

Ejemplo 3

En el siguiente ejemplo, la función genera una cadena vacía porque la cadena de entrada ya está vacía y no hay caracteres para quitar.

strings.trim("", "str") = ""

Ejemplo 4

En el siguiente ejemplo, la función genera str porque la función trim quita lo siguiente:

• Espacio en blanco final en "a aastraa aa "
• Los caracteres especificados en el conjunto de corte (espacio, a)

strings.trim("a aastraa aa ", " a") = "str"

strings.url_decode

strings.url_decode(url_string)

Descripción

Dada una cadena de URL, decodifica los caracteres de escape y controla los caracteres UTF-8 que se codificaron. Devuelve una cadena vacía si falla la decodificación.

Tipos de datos de parámetros

STRING

Tipo de datos que se muestra

STRING

Muestras de código

Ejemplo 1

En este ejemplo, se muestra un caso de prueba positivo.

strings.url_decode("three%20nine%20four") = "three nine four"

Ejemplo 2

En este ejemplo, se muestra un caso de cadena vacía.

strings.url_decode("") // ""

Ejemplo 3

En este ejemplo, se muestra el control de caracteres no alfabéticos.

strings.url_decode("%E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B") // "上海+中國"

Ejemplo 4

En este ejemplo, se muestra una muestra de decodificación de URL.

strings.url_decode("http://www.google.com%3Fparam1%3D%22+1+%3E+2+%22%26param2%3D2%3B") // 'http://www.google.com?param1="+1+>+2+"&param2=2;'

timestamp.as_unix_seconds

timestamp.as_unix_seconds(timestamp [, time_zone])

Descripción

Esta función devuelve un número entero que representa la cantidad de segundos transcurridos desde un ciclo de entrenamiento de Unix para la cadena de marca de tiempo determinada.

• timestamp es una cadena que representa una marca de tiempo de época válida. El formato debe ser %F %T.
• time_zone es opcional y es una cadena que representa una zona horaria. Si se omite, el valor predeterminado es GMT. Puedes especificar zonas horarias con literales de cadena. Las opciones son las siguientes:
  • Nombre de la base de datos de TZ, por ejemplo, America/Los_Angeles. Para obtener más información, consulta la lista de zonas horarias de la base de datos tz en Wikipedia.
  • Es el desplazamiento de zona horaria desde UTC, en el formato(+|-)H[H][:M[M]], por ejemplo, "-08:00".

Estos son ejemplos de especificadores de time_zone válidos que puedes pasar como segundo argumento a las funciones de extracción de tiempo:

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

Tipos de datos de parámetros

STRING, STRING

Tipo de datos que se muestra

INT

Muestras de código

Ejemplo 1

Marca de tiempo de época válida

timestamp.as_unix_seconds("2024-02-22 10:43:00") = 1708598580

Ejemplo 2

Marca de tiempo de época válida con la zona horaria America/New_York

timestamp.as_unix_seconds("2024-02-22 10:43:00", "America/New_York") = 1708616580

timestamp.current_seconds

timestamp.current_seconds()

Descripción

Devuelve un número entero que representa la hora actual en segundos de Unix. Es aproximadamente igual a la marca de tiempo de detección y se basa en el momento en que se ejecuta la regla. Esta función es sinónimo de la función timestamp.now().

Tipos de datos de parámetros

NONE

Tipo de datos que se muestra

INT

Muestras de código

Ejemplo 1

En el siguiente ejemplo, se muestra true si el certificado venció hace más de 24 horas. Calcula la diferencia de tiempo restando los segundos Unix actuales y, luego, realiza la comparación con un operador mayor que.

86400 < timestamp.current_seconds() - $e.network.tls.certificate.not_after

timestamp.get_date

timestamp.get_date(unix_seconds [, time_zone])

Descripción

Esta función devuelve una cadena con el formato YYYY-MM-DD, que representa el día en el que se encuentra una marca de tiempo.

• unix_seconds es un número entero que representa la cantidad de segundos transcurridos desde la época de Unix, como $e.metadata.event_timestamp.seconds, o un marcador de posición que contiene ese valor.
• time_zone es opcional y es una cadena que representa una zona horaria. Si se omite, el valor predeterminado es "GMT". Puedes especificar zonas horarias con literales de cadena. Las opciones son las siguientes:
  • Nombre de la base de datos de la zona horaria, por ejemplo, "America/Los_Angeles". Para obtener más información, consulta la columna "TZ Database Name" de esta página.
  • Es el desplazamiento de zona horaria desde UTC, en el formato(+|-)H[H][:M[M]], por ejemplo, "-08:00".

A continuación, se muestran ejemplos de especificadores de time_zone válidos que puedes pasar como segundo argumento a las funciones de extracción de tiempo:

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

Tipos de datos de parámetros

INT, STRING

Tipo de datos que se muestra

STRING

Muestras de código

Ejemplo 1

En este ejemplo, se omite el argumento time_zone, por lo que se establece de forma predeterminada en "GMT".

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_date($ts) = "2024-02-19"

Ejemplo 2

En este ejemplo, se usa un literal de cadena para definir el time_zone.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_date($ts, "America/Los_Angeles") = "2024-02-20"

timestamp.get_minute

timestamp.get_minute(unix_seconds [, time_zone])

Descripción

Esta función devuelve un número entero en el rango [0, 59] que representa el minuto.

• unix_seconds es un número entero que representa la cantidad de segundos transcurridos desde la época de Unix, como $e.metadata.event_timestamp.seconds, o un marcador de posición que contiene ese valor.
• time_zone es opcional y es una cadena que representa una zona horaria. Si se omite, el valor predeterminado es "GMT". Puedes especificar zonas horarias con literales de cadena. Las opciones son las siguientes:
  • Nombre de la base de datos de la zona horaria, por ejemplo, "America/Los_Angeles". Para obtener más información, consulta la columna "TZ Database Name" de esta página.
  • Es el desplazamiento de zona horaria desde UTC, en el formato(+|-)H[H][:M[M]], por ejemplo, "-08:00".

Estos son ejemplos de especificadores de time_zone válidos que puedes pasar como segundo argumento a las funciones de extracción de tiempo:

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

Tipos de datos de parámetros

INT, STRING

Tipo de datos que se muestra

INT

Muestras de código

Ejemplo 1

En este ejemplo, se omite el argumento time_zone, por lo que se establece de forma predeterminada en "GMT".

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_hour($ts) = 15

Ejemplo 2

En este ejemplo, se usa un literal de cadena para definir el time_zone.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_hour($ts, "America/Los_Angeles") = 15

timestamp.get_hour

timestamp.get_hour(unix_seconds [, time_zone])

Descripción

Esta función devuelve un número entero en el rango [0, 23] que representa la hora.

• unix_seconds es un número entero que representa la cantidad de segundos transcurridos desde la época de Unix, como $e.metadata.event_timestamp.seconds, o un marcador de posición que contiene ese valor.
• time_zone es opcional y es una cadena que representa una zona horaria. Si se omite, el valor predeterminado es "GMT". Puedes especificar zonas horarias con literales de cadena. Las opciones son las siguientes:
  • Nombre de la base de datos de la zona horaria, por ejemplo, "America/Los_Angeles". Para obtener más información, consulta la columna "TZ Database Name" de esta página.
  • Es el desplazamiento de zona horaria desde UTC, en el formato(+|-)H[H][:M[M]], por ejemplo, "-08:00".

Estos son ejemplos de especificadores de time_zone válidos que puedes pasar como segundo argumento a las funciones de extracción de tiempo:

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

Tipos de datos de parámetros

INT, STRING

Tipo de datos que se muestra

INT

Muestras de código

Ejemplo 1

En este ejemplo, se omite el argumento time_zone, por lo que se establece de forma predeterminada en "GMT".

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_hour($ts) = 15

Ejemplo 2

En este ejemplo, se usa un literal de cadena para definir el time_zone.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_hour($ts, "America/Los_Angeles") = 15

timestamp.get_day_of_week

timestamp.get_day_of_week(unix_seconds [, time_zone])

Descripción

Esta función devuelve un número entero en el rango [1, 7] que representa el día de la semana, comenzando por el domingo. Por ejemplo, 1 = domingo y 2 = lunes.

• unix_seconds es un número entero que representa la cantidad de segundos transcurridos desde la época de Unix, como $e.metadata.event_timestamp.seconds, o un marcador de posición que contiene ese valor.
• time_zone es opcional y es una cadena que representa una zona horaria. Si se omite, el valor predeterminado es "GMT". Puedes especificar zonas horarias con literales de cadena. Las opciones son las siguientes:
  • Nombre de la base de datos de la zona horaria, por ejemplo, "America/Los_Angeles". Para obtener más información, consulta la columna "TZ Database Name" de esta página.
  • Es el desplazamiento de zona horaria desde UTC, en el formato(+|-)H[H][:M[M]], por ejemplo, "-08:00".

A continuación, se muestran ejemplos de especificadores de time_zone válidos que puedes pasar como segundo argumento a las funciones de extracción de tiempo:

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

Tipos de datos de parámetros

INT, STRING

Tipo de datos que se muestra

INT

Muestras de código

Ejemplo 1

En este ejemplo, se omite el argumento time_zone, por lo que se establece de forma predeterminada en "GMT".

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_day_of_week($ts) = 6

Ejemplo 2

En este ejemplo, se usa un literal de cadena para definir el time_zone.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_day_of_week($ts, "America/Los_Angeles") = 6

timestamp.get_timestamp

timestamp.get_timestamp(unix_seconds, optional timestamp_format/time_granularity, optional timezone)

Descripción

Esta función devuelve una cadena con el formato YYYY-MM-DD, que representa el día en el que se encuentra una marca de tiempo.

• unix_seconds es un número entero que representa la cantidad de segundos transcurridos desde la época de Unix, como $e.metadata.event_timestamp.seconds, o un marcador de posición que contiene ese valor.
• timestamp_format es opcional y es una cadena que representa el formato de la marca de tiempo. Si se omite, el valor predeterminado es %F %T. Puedes especificar el formato con una cadena de formato de fecha y hora o con una de las siguientes granularidades de tiempo: SECOND, MINUTE, HOUR, DATE, WEEK, MONTH o YEAR. Para ver más opciones de formato, consulta Elementos de formato para partes de fecha y hora
• time_zone es opcional y es una cadena que representa una zona horaria. Si se omite, el valor predeterminado es GMT. Puedes especificar zonas horarias con literales de cadena. Las opciones son las siguientes:
  • Nombre de la base de datos de zona horaria (TZ) de IANA, por ejemplo, America/Los_Angeles. Para obtener más información, consulta la lista de zonas horarias de la base de datos tz en Wikipedia.
  • Es el desplazamiento de zona horaria desde UTC, en el formato (+|-)H[H][:M[M]], por ejemplo, "-08:00".

Estos son ejemplos de especificadores de time_zone válidos que puedes pasar como segundo argumento a las funciones de extracción de tiempo:

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

Tipos de datos de parámetros

INT, STRING, STRING

Tipo de datos que se muestra

STRING

Muestras de código

Ejemplo 1

En este ejemplo, se omite el argumento time_zone, por lo que se establece de forma predeterminada en GMT.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_timestamp($ts) = "2024-02-22 10:43:51"

Ejemplo 2

En este ejemplo, se usa un literal de cadena para definir el time_zone.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_timestamp($ts, "%F %T", "America/Los_Angeles") = "2024-02-22 10:43:51"

Ejemplo 3

En este ejemplo, se usa un literal de cadena para definir el timestamp_format.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_timestamp($ts, "%Y-%m", "GMT") = "2024-02"

Ejemplo 4

En este ejemplo, se da formato a una marca de tiempo de Unix como una cadena con una granularidad de segundos.

timestamp.get_timestamp(1708598631, "SECOND", "GMT") = "2024-02-22 10:43:51"

Ejemplo 5

En este ejemplo, se da formato a una marca de tiempo de Unix como una cadena con un nivel de detalle por minuto.

timestamp.get_timestamp(1708598631, "MINUTE", "GMT") = "2024-02-22 10:43"

Ejemplo 6

En este ejemplo, se da formato a una marca de tiempo de Unix como una cadena con una granularidad de horas.

timestamp.get_timestamp(1708598631, "HOUR", "GMT") = "2024-02-22 10"

Ejemplo 7

En este ejemplo, se le da formato a una marca de tiempo Unix como una cadena con granularidad diaria.

timestamp.get_timestamp(1708598631, "DATE", "GMT") = "2024-02-22"

Ejemplo 8

En este ejemplo, se da formato a una marca de tiempo de Unix como una cadena con una granularidad semanal.

timestamp.get_timestamp(1708598631, "WEEK", "GMT") = "2024-02-18"

Ejemplo 9

En este ejemplo, se da formato a una marca de tiempo de Unix como una cadena con una granularidad mensual.

timestamp.get_timestamp(1708598631, "MONTH", "GMT") = "2024-02"

Ejemplo 10

En este ejemplo, se da formato a una marca de tiempo de Unix como una cadena con una granularidad anual.

timestamp.get_timestamp(1708598631, "YEAR", "GMT") = "2024"

timestamp.get_week

timestamp.get_week(unix_seconds [, time_zone])

Descripción

Esta función devuelve un número entero en el rango [0, 53] que representa la semana del año. Las semanas comienzan los domingos. Las fechas anteriores al primer domingo del año están en la semana 0.

• unix_seconds es un número entero que representa la cantidad de segundos transcurridos desde la época de Unix, como $e.metadata.event_timestamp.seconds, o un marcador de posición que contiene ese valor.
• time_zone es opcional y es una cadena que representa una zona horaria. Si se omite, el valor predeterminado es "GMT". Puedes especificar zonas horarias con literales de cadena. Las opciones son las siguientes:
  • Nombre de la base de datos de la zona horaria, por ejemplo, "America/Los_Angeles". Para obtener más información, consulta la columna "TZ Database Name" de esta página.
  • Es el desplazamiento de zona horaria desde UTC, en el formato(+|-)H[H][:M[M]], por ejemplo, "-08:00".

Estos son ejemplos de especificadores de time_zone válidos que puedes pasar como segundo argumento a las funciones de extracción de tiempo:

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

Tipos de datos de parámetros

INT, STRING

Tipo de datos que se muestra

INT

Muestras de código

Ejemplo 1

En este ejemplo, se omite el argumento time_zone, por lo que se establece de forma predeterminada en "GMT".

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_week($ts) = 0

Ejemplo 2

En este ejemplo, se usa un literal de cadena para definir el time_zone.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_week($ts, "America/Los_Angeles") = 0

timestamp.now

timestamp.now()

Descripción

Devuelve la cantidad de segundos desde 1970-01-01 00:00:00 UTC. También se conoce como tiempo de ciclo de Unix.

Tipo de datos que se muestra

INT

Muestras de código

Ejemplo 1

En el siguiente ejemplo, se devuelve una marca de tiempo para el código ejecutado el 22 de mayo de 2024 a las 18:16:59.

timestamp.now() = 1716401819 // Unix epoch time in seconds for May 22, 2024 at 18:16:59

window.avg

window.avg(numeric_values [, should_ignore_zero_values])

Descripción

Devuelve el promedio de los valores de entrada (que pueden ser números enteros o números de punto flotante). Si configuras el segundo argumento opcional como verdadero, se ignoran los valores cero.

Tipos de datos de parámetros

INT|FLOAT

Tipo de datos que se muestra

FLOAT

Muestras de código

Ejemplo 1

En este ejemplo, se muestra el promedio de números enteros.

// This rule sets the outcome $size_mode to the average
// file size in the 5 minute match window.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.avg($e.file.size) // yields 2.5 if the event file size values in the match window are 1, 2, 3 and 4

Ejemplo 2

En este ejemplo, se muestra el promedio de flotación.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.avg($e.file.size) // yields 1.75 if the event file size values in the match window are 1.1 and 2.4

Ejemplo 3

Promedio de entrada negativo

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.avg($e.file.size) // yields 0.6 if the event file size values in the match window are -1.1, 1.1, 0.0 and 2.4

Ejemplo 4

0 devoluciones 0

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.avg($e.file.size) // yields 0 if the event file size values in the match window is 0

Ejemplo 5

Se ignoran los valores 0

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.avg($e.file.size, true) // yields 394 if the event file size values in the match window are 0, 0, 0 and 394

window.first

window.first(values_to_sort_by, values_to_return)

Descripción

Esta función de agregación devuelve un valor de cadena derivado de un evento con el valor int correlacionado más bajo en la ventana de coincidencia. Un ejemplo de caso de uso es obtener el ID de usuario del evento con la marca de tiempo más baja en el período de coincidencia (el evento más antiguo).

Tipos de datos de parámetros

INT, STRING

Tipo de datos que se muestra

STRING

Muestras de código

Obtén un valor de cadena derivado de un evento con el valor int correlacionado más bajo en la ventana de coincidencia.

// This rule sets the outcome $first_event to the lowest correlated int value
// in the 5 minute match window.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $first_event = window.first($e.metadata.timestamp.seconds, $e.metadata.event_type) // yields v1 if the events in the match window are 1, 2 and 3 and corresponding values v1, v2, and v3.

window.last

window.last(values_to_sort_by, values_to_return)

Descripción

Esta función de agregación devuelve un valor de cadena derivado de un evento con el valor int correlacionado más alto en la ventana de coincidencia. Un ejemplo de caso de uso es obtener el ID de usuario del evento con la marca de tiempo más baja en la ventana de coincidencia (marca de tiempo más alta).

Tipos de datos de parámetros

INT, STRING

Tipo de datos que se muestra

STRING

Muestras de código

Obtén un valor de cadena derivado de un evento con el valor int correlacionado más alto en la ventana de coincidencia.

// This rule sets the outcome $last_event to the highest correlated int value
// in the 5 minute match window.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $last_event = window.first($e.metadata.timestamp.seconds, $e.metadata.event_type) // yields v3 if the events in the match window are 1, 2 and 3 and corresponding values v1, v2, and v3.

window.median

window.median(numeric_values, should_ignore_zero_values)

Descripción

Devuelve la mediana de los valores de entrada. Si hay 2 valores de mediana, solo se elegirá 1 de forma no determinística como valor de devolución.

Tipos de datos de parámetros

INT|FLOAT, BOOL

Tipo de datos que se muestra

FLOAT

Muestras de código

Ejemplo 1

En este ejemplo, se devuelve la mediana cuando los valores de entrada no son cero.

rule median_file_size {
    meta:
    events:
      $e.metadata.event_type = "FILE_COPY"
        $userid = $e.principal.user.userid
    match:
      $userid over 1h
    outcome:
      $median_file_size = window.median($e.principal.file.size) // returns 2 if the file sizes in the match window are [1, 2, 3]
  condition:
      $e
}

Ejemplo 2

En este ejemplo, se devuelve la mediana cuando la entrada incluye algunos valores cero que no se deben ignorar.

rule median_file_size {
    meta:
    events:
      $e.metadata.event_type = "FILE_COPY"
        $userid = $e.principal.user.userid
    match:
      $userid over 1h
    outcome:
      $median_file_size = window.median($e.principal.file.size) // returns 1 if the file sizes in the match window are [0,0, 1, 2, 3]
  condition:
      $e
}

Ejemplo 3

En este ejemplo, se devuelve la mediana cuando la entrada incluye algunos valores cero que se deben ignorar.

rule median_file_size {
    meta:
    events:
      $e.metadata.event_type = "FILE_COPY"
        $userid = $e.principal.user.userid
    match:
      $userid over 1h
    outcome:
      $median_file_size = window.median($e.principal.file.size, true) // returns 2 if the file sizes in the match window are [0,0, 1, 2, 3]
  condition:
      $e
}

Ejemplo 4

En este ejemplo, se devuelve la mediana cuando la entrada incluye todos los valores cero que se deben ignorar.

rule median_file_size {
    meta:
    events:
      $e.metadata.event_type = "FILE_COPY"
        $userid = $e.principal.user.userid
    match:
      $userid over 1h
    outcome:
      $median_file_size = window.median($e.principal.file.size) // returns 0 if the file sizes in the match window are [0,0]
  condition:
      $e
}

Ejemplo 5

En este ejemplo, se muestra que, cuando hay varias medianas, solo se devuelve una.

rule median_file_size {
    meta:
    events:
      $e.metadata.event_type = "FILE_COPY"
        $userid = $e.principal.user.userid
    match:
      $userid over 1h
    outcome:
      $median_file_size = window.median($e.principal.file.size) // returns 1 if the file sizes in the match window are [1, 2, 3, 4]
  condition:
      $e
}

window.mode

window.mode(values)

Descripción

Devuelve la moda de los valores de entrada. En caso de que haya varios valores de modo posibles, solo se elegirá uno de esos valores de forma no determinística como valor de devolución.

Tipos de datos de parámetros

INT|FLOAT|STRING

Tipo de datos que se muestra

STRING

Muestras de código

Ejemplo 1

Obtiene la moda de los valores en la ventana de coincidencia.

// This rule sets the outcome $size_mode to the most frequently occurring
// file size in the 5 minute match window.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.mode($e.file.size) // yields 1.6 if the event file size values in the match window are 1.6, 2, and 1.6

window.stddev

window.stddev(numeric_values)

Descripción

Devuelve la desviación estándar de los valores de entrada en una ventana de coincidencia.

Tipos de datos de parámetros

INT|FLOAT

Tipo de datos que se muestra

FLOAT

Muestras de código

Ejemplo 1

En este ejemplo, se devuelve la desviación estándar de los números enteros en una ventana de coincidencia.

// This rule creates a detection when the file size stddev in 5 minutes for a user is over a threshold.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.stddev($e.file.size) // yields 4.0 if the event file size values in the match window are [10, 14, 18].
condition:
  $e and #p1 > 2

Ejemplo 2

En este ejemplo, se devuelve la desviación estándar de los números de punto flotante en una ventana de coincidencia.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.stddev($e.file.size) // yields 4.488686 if the event file size values in the match window are [10.00, 14.80, 18.97].
condition:
  $e and #p1 > 2

Ejemplo 3

En este ejemplo, se muestra la desviación estándar en una ventana de coincidencia que contiene números negativos.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.stddev($e.file.size) // yields 48.644972 if the event file size values in the match window are [-1, -56, -98].
condition:
  $e and #p1 > 2

Ejemplo 4

Este ejemplo devuelve una desviación estándar de cero cuando todos los valores de la ventana de coincidencia son iguales.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.stddev($e.file.size) // yields 0.000000 if the event file size values in the match window are [1, 1, 1].
condition:
  $e and #p1 > 2

Ejemplo 5

En este ejemplo, se devuelve la desviación estándar de una ventana de coincidencia que contiene números positivos y negativos.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.stddev($e.file.size) // yields 1.000000 if the event file size values in the match window are [1, 0, -1].
condition:
  $e and #p1 > 10

window.variance

window.variance(values)

Descripción

Esta función devuelve la varianza especificada de los valores de entrada.

Tipos de datos de parámetros

INT|FLOAT

Tipo de datos que se muestra

FLOAT

Muestras de código

Ejemplo 1

En este ejemplo, se devuelve la varianza de todos los números enteros.

// This rule creates a detection when the file size variance in 5 minutes for a user is over a threshold.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 16 if the event file size values in the match window are [10, 14, 18].
condition:
  $e and #p1 > 10

Ejemplo 2

En este ejemplo, se devuelve la varianza de todos los números de punto flotante.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 20.148300 if the event file size values in the match window are [10.00, 14.80, 18.97].
condition:
  $e and #p1 > 10

Ejemplo 3

En este ejemplo, se devuelve la varianza de los números negativos.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 2366.333333 if the event file size values in the match window are [-1, -56, -98].
condition:
  $e and #p1 > 10

Ejemplo 4

En este ejemplo, se devuelve un valor de varianza pequeño.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 0.000000 if the event file size values in the match window are [0.000000, 0.000000, 0.000100].
condition:
  $e and #p1 > 10

Ejemplo 5

En este ejemplo, se devuelve una varianza de cero.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 0.000000 if the event file size values in the match window are [1, 1, 1].
condition:
  $e and #p1 > 10

Ejemplo 6

En este ejemplo, se devuelve la varianza de los números positivos y negativos.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 1.000000 if the event file size values in the match window are [1, 0, -1].
condition:
  $e and #p1 > 10

bytes.to_base64

bytes.to_base64(bytes, optional_default_string)

Descripción

La función convierte un valor bytes en un valor base64 encoded string. Las llamadas a funciones con valores que no se pueden convertir devuelven una cadena vacía de forma predeterminada.

Tipos de datos de parámetros

BYTES, STRING

Tipo de datos que se muestra

STRING

Muestras de código

Bytes binarios sin procesar a cadena codificada en Base64

La función convierte los bytes binarios sin procesar en una cadena codificada en base64.

bytes.to_base64(b'000000006f8ec5586d026f9ddac56e9f2fe15b8a0000000001000000cd000000) = "AAAAAG+OxVhtAm+d2sVuny/hW4oAAAAAAQAAAM0AAAA="

Conversión fallida (se establece de forma predeterminada en la cadena proporcionada de forma opcional)

La función usa el valor predeterminado "invalid bytes" cuando el valor de bytes proporcionado no es válido.

bytes.to_base64(b'000000006f8ec5586d", "invalid bytes") = "invalid bytes"

Asignación de la función al marcador de posición

Puedes asignar el resultado de una llamada a una función a un marcador de posición en la sección events. Por ejemplo:

$placeholder = strings.concat($e.principal.hostname, "my-string").

Luego, puedes usar las variables de marcador de posición en las secciones match, condition y outcome. Sin embargo, existen dos limitaciones con la asignación de funciones a marcadores de posición:

1. Cada marcador de posición en la asignación de función a marcador de posición debe asignarse a una expresión que contenga un campo de evento. Por ejemplo, los siguientes ejemplos son válidos:

   $ph1 = $e.principal.hostname
   $ph2 = $e.src.hostname
   
   // Both $ph1 and $ph2 have been assigned to an expression containing an event field.
   $ph1 = strings.concat($ph2, ".com")
   

   $ph1 = $e.network.email.from
   $ph2 = strings.concat($e.principal.hostname, "@gmail.com")
   
   // Both $ph1 and $ph2 have been assigned to an expression containing an event field.
   $ph1 = strings.to_lower($ph2)
   

   Sin embargo, el siguiente ejemplo no es válido:

   $ph1 = strings.concat($e.principal.hostname, "foo")
   $ph2 = strings.concat($ph1, "bar") // $ph2 has NOT been assigned to an expression containing an event field.
   

2. La llamada a la función debe depender de un evento y solo uno. Sin embargo, se puede usar más de un campo del mismo evento en los argumentos de la llamada a la función. Por ejemplo, lo siguiente es válido:

   $ph = strings.concat($event.principal.hostname, "string2")

   $ph = strings.concat($event.principal.hostname, $event.src.hostname)

   Sin embargo, lo siguiente no es válido:

   $ph = strings.concat("string1", "string2")

   $ph = strings.concat($event.principal.hostname, $anotherEvent.src.hostname)

Sintaxis de las listas de referencia

Consulta nuestra página sobre listas de referencia para obtener más información sobre el comportamiento y la sintaxis de las listas de referencia.

Puedes usar listas de referencia en las secciones events o outcome. A continuación, se muestra la sintaxis para usar varios tipos de listas de referencia en una regla:

// STRING reference list
$e.principal.hostname in %string_reference_list

// REGEX reference list
$e.principal.hostname in regex %regex_reference_list

// CIDR reference list
$e.principal.ip in cidr %cidr_reference_list

También puedes usar el operador not y el operador nocase con listas de referencia, como se muestra en el siguiente ejemplo:

// Exclude events whose hostnames match substrings in my_regex_list.
not $e.principal.hostname in regex %my_regex_list

// Event hostnames must match at least 1 string in my_string_list (case insensitive).
$e.principal.hostname in %my_string_list nocase

El operador nocase es compatible con las listas STRING y REGEX.

Por motivos de rendimiento, Detection Engine restringe el uso de listas de referencia.

• Cantidad máxima de instrucciones in en una regla, con o sin operadores especiales: 7
• Cantidad máxima de sentencias in con el operador regex: 4
• Cantidad máxima de sentencias in con el operador cidr: 2

Verificación de tipos

Google SecOps realiza una verificación de tipos en tu sintaxis de YARA-L a medida que creas reglas en la interfaz. Los errores de verificación de tipos que se muestran te ayudan a revisar la regla de manera tal que se verifique que funcionará según lo previsto.

Los siguientes son ejemplos de predicados no válidos:

// $e.target.port is of type integer which cannot be compared to a string.
$e.target.port = "80"

// "LOGIN" is not a valid event_type enum value.
$e.metadata.event_type = "LOGIN"

Muestreo de eventos de detección

Las detecciones de reglas de varios eventos contienen muestras de eventos para proporcionar contexto sobre los eventos que causaron la detección. Hay un límite de hasta 10 muestras de eventos para cada variable de evento definida en la regla. Por ejemplo, si una regla define 2 variables de evento, cada detección puede tener hasta 20 muestras de eventos. El límite se aplica a cada variable del evento por separado. Si una variable de evento tiene 2 eventos aplicables en esta detección y la otra variable de evento tiene 15 eventos aplicables, la detección resultante contiene 12 muestras de eventos (2 + 10).

Las muestras de eventos que superen el límite se omitirán de la detección.

Si deseas obtener más información sobre los eventos que causaron la detección, puedes usar agregaciones en la sección de resultados para generar información adicional en la detección.

Si ves las detecciones en la IU, puedes descargar todas las muestras de eventos para una detección. Para obtener más información, consulta Eventos de descarga.

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