Sintaxe da linguagem YARA-L 2.0

Compatível com:

Esta seção descreve os principais elementos da sintaxe YARA-L. Consulte também Visão geral da linguagem YARA-L 2.0.

Estrutura da regra

Para a YARA-L 2.0, especifique declarações, definições e usos de variáveis na seguinte ordem:

  1. meta
  2. eventos
  3. match (opcional)
  4. resultado (opcional)
  5. transição
  6. options (opcional)

O exemplo a seguir ilustra a estrutura genérica de uma regra:

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.
}

Sintaxe da seção de metadados

A seção "Meta" é composta por várias linhas, em que cada uma define um par de chave-valor. Uma parte da chave precisa ser uma string sem aspas, e uma parte do valor precisa ser uma string entre aspas:

<key> = "<value>"

Confira um exemplo de linha de seção meta válida:

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

Sintaxe da seção "Eventos"

Na seção events, liste os predicados para especificar o seguinte:

  • Declarações de variáveis
  • Filtros de variáveis de evento
  • Junções de variáveis de evento

Declarações de variáveis

Para declarações de variáveis, use a seguinte sintaxe:

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

Ambos são equivalentes, conforme mostrado nos exemplos a seguir:

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

Essa declaração indica que a variável representa o campo especificado para a variável de evento. Quando o campo de evento é repetido, a variável de correspondência pode representar qualquer valor na matriz. Também é possível atribuir vários campos de evento a uma única variável de correspondência ou marcador de posição. Essa é uma condição de junção transitiva.

Por exemplo, os seguintes URLs:

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

São equivalentes a:

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

Quando uma variável é usada, ela precisa ser declarada. Se uma variável for usada sem declaração, ela será considerada um erro de compilação.

Filtros de variáveis de evento

Uma expressão booleana que atua em uma única variável de evento é considerada um filtro.

Junções de variáveis de evento

Todas as variáveis de evento usadas na regra precisam ser unidas a todas as outras variáveis de evento de uma das seguintes maneiras:

  • Diretamente por uma comparação de igualdade entre campos de evento das duas variáveis de evento unidas, por exemplo: $e1.field = $e2.field. A expressão não pode incluir aritmética.

  • Indiretamente, por uma junção transitiva que envolve apenas um campo de evento. Consulte a declaração de variável para uma definição de "junção transitiva". A expressão não pode incluir aritmética.

Por exemplo, supondo que $e1, $e2 e $e3 sejam usados na regra, as seguintes seções events são 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

No entanto, confira exemplos de seções events invá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

Sintaxe da seção de correspondência

Na seção match, liste as variáveis de correspondência para eventos de grupo antes de verificar as condições de correspondência. Esses campos são retornados com cada correspondência.

  • Especifique o que cada variável de correspondência representa na seção events.
  • Especifique a duração a ser usada para correlacionar eventos após a palavra-chave over. Os eventos fora da duração são ignorados.

  • Use a seguinte sintaxe para especificar a duração: <number><m/h/d>

    Em que m/h/d significa minutos, horas e dias, respectivamente.

  • O tempo mínimo que você pode especificar é de 1 minuto.

  • O tempo máximo que você pode especificar é de 48 horas.

Confira abaixo um exemplo de match válido:

$var1, $var2 over 5m

Essa instrução retorna $var1 e $var2 (definidos na seção events) quando a regra encontra uma correspondência. O tempo especificado é de 5 minutos. Eventos com mais de cinco minutos de diferença não são correlacionados e, portanto, são ignorados pela regra.

Confira outro exemplo de uma seção match válida:

$user over 1h

Essa instrução retorna $user quando a regra encontra uma correspondência. O período especificado é de uma hora. Eventos com mais de uma hora de diferença não são correlacionados. A regra não os considera uma detecção.

Confira outro exemplo de uma seção match válida:

$source_ip, $target_ip, $hostname over 2m

Essa instrução retorna $source_ip, $target_ip e $hostname quando a regra encontra uma correspondência. O período especificado é de 2 minutos. Eventos com mais de dois minutos de diferença não são correlacionados. A regra não os considera uma detecção.

Os exemplos a seguir ilustram seções match inválidas:

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

Processamento de valores zero na seção de correspondência

O mecanismo de regras filtra implicitamente os valores zero para todos os marcadores de posição usados na seção de correspondência ("" para string, 0 para números, false para booleanos, o valor na posição 0 para tipos enumerados). O exemplo a seguir ilustra regras que filtram os valores zero.

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
}

No entanto, se um marcador de posição for atribuído a uma função, as regras não filtrarão implicitamente os valores zero dos marcadores de posição usados na seção de correspondência. O exemplo a seguir ilustra regras que filtram os valores zero:

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 desativar a filtragem implícita de valores zero, use a opção allow_zero_values na seção de opções.

Janela de salto

Por padrão, as regras YARA-L 2.0 com uma seção de correspondência são avaliadas usando janelas de salto. O período de execução da regra é dividido em um conjunto de janelas de salto sobrepostas, cada uma com a duração especificada na seção match. Em seguida, os eventos são correlacionados em cada janela de transmissão.

Por exemplo, para uma regra executada no intervalo de tempo [1:00, 2:00], com uma seção match em 30m, um possível conjunto de janelas de salto sobrepostas que podem ser geradas é [1:00, 1:30], [1:03, 1:33] e [1:06, 1:36]. Essas janelas são usadas para correlacionar vários eventos.

Janela deslizante

Usar janelas de salto não é uma maneira eficaz de pesquisar eventos que acontecem em uma ordem específica (por exemplo, e1 acontece até 2 minutos depois de e2). Uma ocorrência do evento e1 e uma ocorrência do evento e2 são correlacionadas apenas se estiverem na mesma janela de salto gerada.

Uma maneira mais eficaz de pesquisar essas sequências de eventos é usar janelas deslizantes. Janelas deslizantes com a duração especificada na seção match são geradas quando começam ou terminam com uma variável de evento de pivô especificada. Em seguida, os eventos são correlacionados em cada janela deslizante. Isso permite pesquisar eventos que acontecem em uma ordem específica (por exemplo, e1 acontece em até 2 minutos após e2). Uma ocorrência do evento e1 e uma ocorrência do evento e2 são correlacionadas se o evento e1 ocorrer dentro da duração da janela deslizante após o evento e2.

Especifique janelas deslizantes na seção match de uma regra da seguinte maneira:

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

A variável de evento de pivô é aquela em que as janelas deslizantes são baseadas. Se você usar a palavra-chave before, janelas deslizantes serão geradas, terminando com cada ocorrência do evento de pivô. Se a palavra-chave after for usada, janelas deslizantes serão geradas começando com cada ocorrência do evento de pivô.

Confira alguns exemplos de usos válidos da janela deslizante:

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

Confira um exemplo de regra de janela deslizante.

Não recomendamos o uso de janelas deslizantes para regras de evento único, porque elas são projetadas para detectar vários eventos. Se uma das suas regras se enquadrar nessa categoria, recomendamos uma das seguintes soluções alternativas:

  • Converta a regra para usar várias variáveis de evento e atualize a seção de condição se a regra exigir mais de uma ocorrência do evento.
    • Se quiser, adicione filtros de carimbo de data/hora em vez de usar uma janela deslizante. Por exemplo, $permission_change.metadata.event_timestamp.seconds < $file_creation.metadata.event_timestamp.seconds.
  • Remova a janela deslizante.

Sintaxe da seção de resultado

Na seção outcome, é possível definir até 20 variáveis de resultado com nomes arbitrários. Esses resultados serão armazenados nas detecções geradas pela regra. Cada detecção pode ter valores diferentes para os resultados.

O nome do resultado, $risk_score, é especial. Você pode definir um resultado com esse nome, que precisa ser um número inteiro ou um tipo de ponto flutuante. Se preenchido, o risk_score vai aparecer na visualização de insights empresariais para alertas de detecções de regras.

Se você não incluir uma variável $risk_score na seção de resultado de uma regra, um dos seguintes valores padrão será definido:

  • Se a regra estiver configurada para gerar um alerta, $risk_score será definido como 40.
  • Se a regra não estiver configurada para gerar um alerta, $risk_score será definido como 15.

O valor de $risk_score é armazenado no campo security_result.risk_score do UDM.

Tipos de dados da variável de resultado

Cada variável de resultado pode ter um tipo de dado diferente, que é determinado pela expressão usada para calcular. Oferecemos suporte aos seguintes tipos de dados de resultado:

  • integer
  • ponto flutuante
  • string
  • listas de números inteiros
  • listas de números de ponto flutuante
  • listas de strings

Lógica condicional

É possível usar a lógica condicional para calcular o valor de um resultado. As condições são especificadas usando o seguinte padrão de sintaxe:

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

Você pode ler uma expressão condicional como "se BOOL_CLAUSE for verdadeiro, retorne THEN_CLAUSE, caso contrário, retorne ELSE_CLAUSE".

BOOL_CLAUSE precisa ser avaliada como um valor booleano. Uma expressão BOOL_CLAUSE tem uma forma semelhante às expressões na seção events. Por exemplo, ele pode conter:

  • Nomes de campos da UDM com operador de comparação, por exemplo:

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

  • variável de marcador de posição definida na seção events, por exemplo:

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

  • outra variável de resultado definida na seção outcome, por exemplo:

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

  • funções que retornam um booleano, por exemplo:

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

  • pesquisar em uma lista de referência, por exemplo:

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

  • comparação de agregação, por exemplo:

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

As cláusulas THEN_CLAUSE e ELSE_CLAUSE precisam ser do mesmo tipo de dados. Aceitamos números inteiros, números de ponto flutuante e strings.

É possível omitir a ELSE_CLAUSE se o tipo de dados for um número inteiro ou um ponto flutuante. Se for omitida, a ELSE_CLAUSE será avaliada como 0. Exemplo:

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

Você precisa fornecer a ELSE_CLAUSE se o tipo de dados for string ou se a THEN_CLAUSE for uma variável de marcador de posição ou de resultado.

Operações matemáticas

É possível usar operações matemáticas para calcular tipos de dados inteiros ou de ponto flutuante nas seções outcome e events de uma regra. O Google Security Operations aceita adição, subtração, multiplicação, divisão e módulo como operadores de nível superior em um cálculo.

O snippet a seguir é um exemplo de cálculo na seção outcome:

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

As operações matemáticas são permitidas nos seguintes tipos de operandos, desde que cada operando e toda a expressão aritmética sejam agregados corretamente (consulte Agregações):

  • Campos de evento numéricos
  • Variáveis de marcador de posição numéricas definidas na seção events
  • Variáveis de resultado numéricas definidas na seção outcome
  • Funções que retornam números inteiros ou de ponto flutuante
  • Agregações que retornam números inteiros ou de ponto flutuante

O módulo não é permitido em números de ponto flutuante.

Variáveis de marcador em resultados

Ao calcular variáveis de resultado, você pode usar variáveis de marcador de posição definidas na seção de eventos da regra. Neste exemplo, suponha que $email_sent_bytes foi definido na seção de eventos da regra:

Exemplo de evento único:

// 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

Exemplo de vários 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

Variáveis de resultado em expressões de atribuição de resultado

As variáveis de resultado podem ser usadas para derivar outras variáveis de resultado, semelhantes às variáveis de marcador de posição definidas na seção events. É possível se referir a uma variável de resultado na atribuição de outra variável de resultado com um token $ seguido pelo nome da variável. As variáveis de resultado precisam ser definidas antes de serem referenciadas no texto da regra. Quando usadas em uma expressão de atribuição, as variáveis de resultado não podem ser agregadas (consulte Agregações).

No exemplo a seguir, a variável de resultado $risk_score deriva o valor dela da variável de resultado $event_count:

Exemplo de vários 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

As variáveis de resultado podem ser usadas em qualquer tipo de expressão no lado direito de uma atribuição de resultado, exceto nas seguintes expressões:

  • Agregações
  • Arrays.length() chamadas de funções
  • Com modificadores any ou all

Agregações

Campos de evento repetidos não são valores escalares. Ou seja, uma única variável aponta para vários valores. Por exemplo, a variável de campo de evento $e.target.ip é um campo repetido e pode ter zero, um ou vários valores de IP. É um valor não escalar. Já a variável de campo de evento $e.principal.hostname não é um campo repetido e tem apenas um valor (ou seja, um valor escalar).

Da mesma forma, os campos de evento não repetidos e repetidos usados na seção de resultado de uma regra com uma janela de correspondência são valores não escalares. Por exemplo, a regra a seguir agrupa eventos usando uma seção de correspondência e se refere a um campo de evento não repetido na seção de resultado:

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

Qualquer janela de cinco minutos em que a regra é executada pode conter zero, um ou vários eventos. A seção de resultado opera em todos os eventos de uma janela de correspondência. Qualquer variável de campo de evento referida na seção de resultado pode apontar para zero, um ou vários valores do campo em cada evento na janela de correspondência. Por exemplo, se uma janela de 5 minutos contiver 5 eventos $e, $e.principal.hostname na seção de resultados vai apontar para cinco nomes de host diferentes. A variável de campo de evento $e.principal.hostname é tratada como um valor não escalar na seção outcome desta regra.

Como as variáveis de resultado sempre precisam gerar um único valor escalar, qualquer valor não escalar de que uma atribuição de resultado dependa precisa ser agregado para gerar um único valor escalar. Em uma seção de resultado, os seguintes são valores não escalares e precisam ser agregados:

  • Campos de evento (repetidos ou não repetidos) quando a regra usa uma seção de correspondência
  • Substitutos de eventos (repetidos ou não repetidos) quando a regra usa uma seção de correspondência
  • Campos de eventos repetidos quando a regra não usa uma seção de correspondência
  • Marcadores de posição de eventos repetidos quando a regra não usa uma seção de correspondência

Campos de eventos escalares, marcadores de posição de eventos escalares e constantes podem ser envolvidos em funções de agregação em regras que não incluem uma seção de correspondência. No entanto, na maioria dos casos, essas agregações retornam o valor encapsulado, o que as torna desnecessárias. Uma exceção é a agregação array(), que pode ser usada para converter explicitamente um valor escalar em uma matriz.

As variáveis de resultado são tratadas como agregações: elas não podem ser reagregadas quando são mencionadas em outra atribuição de resultado.

É possível usar as seguintes funções de agregação:

  • max(): gera o máximo em todos os valores possíveis. Só funciona com números inteiros e de ponto flutuante.
  • min(): gera o mínimo em todos os valores possíveis. Só funciona com números inteiros e de ponto flutuante.
  • sum(): gera a soma de todos os valores possíveis. Só funciona com números inteiros e de ponto flutuante.
  • count_distinct(): coleta todos os valores possíveis e gera a contagem distinta deles.
  • count(): se comporta como count_distinct(), mas retorna uma contagem não distinta de valores possíveis.
  • array_distinct(): coleta todos os valores distintos possíveis e gera uma lista deles. Ela vai truncar a lista de valores distintos para 1.000 elementos aleatórios. Primeiro, a deduplicação é aplicada para gerar uma lista distinta e, depois, o truncamento.
  • array(): se comporta como array_distinct(), mas retorna uma lista não distinta de valores. Ela também trunca a lista de valores para 1.000 elementos aleatórios.
  • period_start_for_max(): início do período em que ocorreu o máximo do valor listado.
  • period_start_for_min(): início do período em que ocorreu o mínimo do valor listado.

A função de agregação é importante quando uma regra inclui uma seção condition que especifica que vários eventos precisam existir, porque ela opera em todos os eventos que geraram a detecção.

Por exemplo, se as seções outcome e condition contiverem:

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

Como a seção de condição exige mais de um event para cada detecção, as funções de agregação operam em vários eventos. Suponha que os eventos a seguir geraram uma detecção:

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

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

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

Então, os valores dos resultados serão:

  • $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"]

O que você precisa saber ao usar a seção "Resultado":

Outras observações e restrições:

  • A seção outcome não pode referenciar uma nova variável de marcador de posição que não tenha sido definida na seção events ou outcome.
  • A seção outcome não pode usar variáveis de evento que não foram definidas na seção events.
  • A seção outcome pode usar um campo de evento que não foi usado na seção events, desde que a variável de evento a que o campo pertence já tenha sido definida na seção events.
  • A seção outcome só pode correlacionar variáveis de evento que já foram correlacionadas na seção events. As correlações acontecem quando dois campos de evento de variáveis de evento diferentes são equiparados.

Confira um exemplo usando a seção de resultados em Visão geral da YARA-L 2.0. Consulte Criar análises contextuais para mais detalhes sobre a remoção de duplicação de detecção com a seção de resultados.

Sintaxe da seção de condição

  • especifique uma condição de correspondência em eventos e marcadores de posição definidos na seção events. Consulte a seção a seguir, Condicionais de evento e marcador de posição, para mais detalhes.
  • (opcional) Use a palavra-chave and para especificar uma condição de correspondência usando variáveis de resultado definidas na seção outcome. Consulte a seção Condicionais de resultado para mais detalhes.

Contar caractere

O caractere # é especial na seção condition. Se ele for usado antes de qualquer evento ou nome de variável de marcador de posição, representará o número de eventos ou valores distintos que atendem a todas as condições da seção events.

Por exemplo, #c > 1 significa que a variável c precisa ocorrer mais de uma vez.

Caractere de valor

O caractere $ é especial na seção condition. Se ele for usado antes de qualquer nome de variável de resultado, representará o valor desse resultado.

Se for usado antes de qualquer evento ou nome de variável de marcador (por exemplo, $event), ele representará #event > 0.

Condicionais de eventos e marcadores de posição

Liste predicados de condição para eventos e variáveis de marcador de posição usando as palavras-chave and ou or. É possível usar and para combinar qualquer condição. No entanto, só é possível usar or quando todas as condições fazem referência à mesma variável de evento.

Um exemplo válido de uso de or entre dois espaços reservados no mesmo 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
}

Um exemplo inválido de uso de or entre duas condições em eventos diferentes:

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.
}

Condições limitadas e ilimitadas

As condições a seguir são limitadas. Elas forçam a existência da variável de evento associada, o que significa que pelo menos uma ocorrência do evento precisa aparecer em qualquer detecção.

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

As condições a seguir são ilimitadas. Elas permitem que a variável de evento associada não exista, o que significa que é possível que nenhuma ocorrência do evento apareça em uma detecção, e qualquer referência a campos na variável de evento vai gerar um valor zero. Condições sem limites podem ser usadas para detectar a ausência de um evento durante um período. Por exemplo, um evento de ameaça sem um evento de mitigação em uma janela de 10 minutos. As regras que usam condições ilimitadas são chamadas de regras de não existência.

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

Requisitos de não existência

Para que uma regra com não existência seja compilada, ela precisa atender aos seguintes requisitos:

  1. Pelo menos um evento da UDM precisa ter uma condição limitada (ou seja, pelo menos um evento da UDM precisa existir).
  2. Se um marcador de posição tiver uma condição sem restrições, ele precisará ser associado a pelo menos um evento UDM com restrições.
  3. Se uma entidade tiver uma condição sem restrições, ela precisará estar associada a pelo menos um evento de UDM com restrições.

Considere a seguinte regra com a seção de condição 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>
}

Confira a seguir exemplos válidos para <condition_section>:

  • $u1 and !$u2 and $e1 and $e2
    • Todos os eventos e entidades da UDM estão presentes na seção de condição.
    • Pelo menos um evento da UDM está limitado.
  • $u1 and !$u2 and $e1 and !$e2
    • $e2não tem limites, o que é permitido porque está associado a $u1, que tem limites. Se $e2 não estivesse associado a $u1, isso seria inválido.
  • #port > 50 and #ip = 0
    • Nenhum evento e entidade da UDM está presente na seção de condição. No entanto, os marcadores de posição presentes abrangem todos os eventos e entidades da UDM.
    • $ip é atribuído a $u1 e $u2, e #ip = 0 é uma condição sem restrições. No entanto, as condições limitadas são mais fortes do que as ilimitadas. Como $port é atribuído a $u1 e #port > 50 é uma condição limitada, $u1 ainda é limitado.

Confira a seguir exemplos inválidos para <condition_section>:

  • $u1 and $e1
    • Todos os eventos e entidades da UDM que aparecem na seção "Eventos" também precisam aparecer na seção "Condição" ou ter um marcador de posição atribuído a eles que apareça nessa seção.
  • $u1, $u2, $e1, $u2, #port > 50
    • Não é permitido usar vírgulas como separadores de condição.
  • !$u1 and !$u2 and $e1 and $e2
    • Viola o primeiro requisito de que pelo menos um evento da UDM seja limitado.
  • ($u1 or #port < 50) and $u2 and $e1 and $e2
    • A palavra-chave or não é compatível com condições sem restrições.
  • ($u1 or $u2) and $e1 and $e2
    • A palavra-chave or não é compatível entre diferentes variáveis de evento.
  • not $u1 and $u2 and $e1 and $e2
    • A palavra-chave not não é permitida para condições de evento e marcador de posição.
  • #port < 50 and #ip = 0
    • Os marcadores de posição presentes cobrem todos os eventos e entidades da UDM. No entanto, todas as condições são ilimitadas. Isso significa que nenhum dos eventos de UDM está vinculado, fazendo com que a regra não seja compilada.

Condicionais de resultado

Liste aqui os predicados de condição para variáveis de resultado, unidos com a palavra-chave and ou or ou precedidos pela palavra-chave not.

Especifique condicionais de resultado de maneira diferente, dependendo do tipo de variável de resultado:

  • integer: compare com um literal inteiro usando operadores =, >, >=, <, <=, !=. Por exemplo:

    $risk_score > 10

  • float: compare com um literal de ponto flutuante com operadores =, >, >=, <, <=, !=. Por exemplo:

    $risk_score <= 5.5

  • string: compare com um literal de string usando = ou !=. Por exemplo:

    $severity = "HIGH"

  • Lista de números inteiros ou matrizes: especifique a condição usando a função arrays.contains. Por exemplo:

    arrays.contains($event_ids, "id_1234")

Classificação de regras

Especificar uma condição de resultado em uma regra que tem uma seção de correspondência significa que ela será classificada como uma regra de vários eventos para a cota de regras. Consulte regra de evento único e regra de vários eventos para mais informações sobre classificações de eventos únicos e múltiplos.

Sintaxe da seção de opções

Na seção options, é possível especificar as opções da regra. Confira um exemplo de como especificar a seção de opções:

rule RuleOptionsExample {
  // Other rule sections

  options:
    allow_zero_values = true
}

É possível especificar opções usando a sintaxe key = value, em que key precisa ser um nome de opção predefinido e value precisa ser um valor válido para a opção, conforme especificado para as seguintes opções:

allow_zero_values

Os valores válidos para essa opção são true e false, que determinam se ela está ativada ou não. O valor padrão é false. Essa opção fica desativada se não for especificada na regra.

Para ativar essa configuração, adicione o seguinte à seção de opções da regra: allow_zero_values = true. Isso evita que a regra filtre implicitamente os valores zero dos marcadores de posição usados na seção de correspondência, conforme descrito em processamento de valores zero na seção de correspondência.

suppression_window

A opção suppression_window permite controlar a frequência com que uma regra aciona uma detecção. Isso impede que a mesma regra gere várias detecções em um período especificado, mesmo que as condições da regra sejam atendidas várias vezes. A gestão de janelas de supressão usa uma abordagem de janela em cascata, que suprime duplicatas em uma janela de tamanho fixo e sem sobreposição.

Você pode fornecer um suppression_key opcional para refinar ainda mais quais instâncias da regra são suprimidas na janela de supressão. Se não for especificado, todas as instâncias da regra serão suprimidas. Essa chave é definida como uma variável de resultado.

No exemplo a seguir, suppression_window está definido como 5m e suppression_key está definido como a variável $hostname. Depois que a regra aciona uma detecção para $hostname, outras detecções para $hostname são suprimidas pelos próximos cinco minutos. No entanto, se a regra for acionada em um evento com um nome de host diferente, uma detecção será criada.

O valor padrão de suppression_window é 0. Ou seja, a janela de supressão fica desativada por padrão. Essa opção só funciona para regras de evento único que não têm uma seção match.

Exemplo:

rule SuppressionWindowExample {
  // Other rule sections

  outcome:
    $suppression_key = $hostname

  options:
    suppression_window = 5m
}

Regras de detecção compostas

A detecção combinada no Google SecOps envolve a conexão de várias regras YARA-L. Nesta seção, explicamos como criar uma regra combinada. Para uma visão geral das detecções compostas, consulte Visão geral das detecções compostas.

Estrutura da regra

As regras de detecção combinadas são sempre regras de vários eventos e seguem a mesma estrutura e sintaxe. Os seguintes requisitos se aplicam às regras de detecção compostas:

  • As regras compostas precisam usar uma seção match para definir condições de acionamento da detecção.
  • As regras que usam campos de detecção e eventos da UDM precisam unir explicitamente essas fontes de dados.

Para informações sobre limitações de regras, consulte Limitações.

Usar detecções como entrada para regras

As regras compostas podem referenciar detecções geradas por qualquer regra personalizada ou selecionada. O Google SecOps oferece dois métodos para fazer isso.

Faça referência ao conteúdo de detecção usando variáveis de resultado, variáveis de correspondência ou metarrótulos

Para acessar dados de uma detecção sem fazer referência aos eventos originais da UDM, use variáveis outcome, match ou rótulos meta. Recomendamos essa abordagem porque ela oferece mais flexibilidade e melhor compatibilidade entre diferentes tipos de regras.

Por exemplo, várias regras podem armazenar uma string (como um URL, nome de arquivo ou chave de registro) em uma variável outcome comum se você estiver procurando essa string em contextos diferentes. Para acessar essa string em uma regra combinada, comece com detection e localize as informações relevantes usando elementos do recurso de coleta.

Exemplo:suponha que uma regra de detecção produza as seguintes informações:

  • Variável de resultado: dest_domain = "cymbal.com"
  • Campo de UDM: target.hostname = "cymbal.com"

Na regra combinada, é possível acessar esses dados usando os seguintes caminhos:

  • detection.detection.outcomes["dest_domain"] para acessar a variável de resultado dest_domain.
  • detection.collection_elements.references.event.target.hostname para acessar o campo target.hostname da UDM.
  • detection.time_window.start_time.seconds para acessar o carimbo de data/hora da detecção.

A API Collection e a API SecurityResult oferecem acesso aos dois:

  • Metadados de detecção e valores de resultado (detection.detection)
  • Eventos de UDM subjacentes de regras referenciadas (collection_elements)

Referenciar conteúdo de detecção usando o ID ou o nome da regra

É possível fazer referência a uma regra pelo nome ou ID. Recomendamos essa abordagem quando a lógica de detecção depende de regras específicas. Referenciar regras relevantes por nome ou ID melhora o desempenho e evita tempos limite ao reduzir os dados analisados. Por exemplo, é possível consultar diretamente campos como target.url ou principal.ip de uma detecção anterior conhecida.

  • Referenciar uma regra pelo ID (recomendado): use o campo detection.detection.rule_id para referenciar uma regra por ID. Você pode encontrar o ID da regra no URL dela no Google SecOps. As regras geradas pelo usuário têm IDs no formato ru_UUID, enquanto as detecções selecionadas têm IDs no formato ur_UUID. Exemplo:

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

  • Referenciar uma regra por nome:use o campo detection.detection.rule_name para referenciar uma regra por nome. É possível especificar o nome exato da regra ou usar uma expressão regular para corresponder a ela. Exemplo:

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

Observação:recomendamos usar IDs de regra para referências porque eles são exclusivos e não mudam. Os nomes das regras podem ser modificados, o que pode prejudicar sua detecção composta.

Combinar eventos e detecções

As regras compostas podem combinar diferentes fontes de dados, incluindo eventos do UDM, dados do gráfico de entidades e campos de detecção. As seguintes diretrizes se aplicam:

  • Usar variáveis distintas por origem: atribua variáveis de evento exclusivas a cada fonte de dados (por exemplo, $e para eventos, $d para detecções), em que a fonte de dados inclui eventos, entidades e detecções.
  • Unir fontes no contexto compartilhado: conecte fontes de dados usando valores comuns, como IDs de usuário, endereços IP ou nomes de domínio nas condições da regra.
  • Defina uma janela de correspondência: sempre inclua uma cláusula match com uma janela de tempo de no máximo 48 horas.

Exemplo:

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
}

Criar detecções compostas sequenciais

As detecções compostas sequenciais identificam padrões de eventos relacionados em que a sequência de detecções é importante, como uma tentativa de login por força bruta seguida de um login bem-sucedido. Esses padrões podem combinar várias detecções básicas, eventos UDM brutos ou ambos.

Para criar uma detecção composta sequencial, é necessário impor essa ordem na regra. Para aplicar a sequência esperada, use um dos seguintes métodos:

  • Janelas deslizantes:defina a sequência de detecções usando janelas deslizantes nas condições match.
  • Comparações de carimbos de data/hora:compare os carimbos de data/hora das detecções na lógica da regra para verificar se elas ocorrem na ordem selecionada.

Exemplo:

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

Expressões booleanas

As expressões booleanas são expressões com um tipo booleano.

Comparações

Para usar uma expressão binária como condição, use a seguinte sintaxe:

  • <EXPR> <OP> <EXPR>

A expressão pode ser um campo de evento, uma variável, um literal ou uma expressão de função.

Exemplo:

  • $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")

Se os dois lados forem literais, isso será considerado um erro de compilação.

Funções

Algumas expressões de função retornam um valor booleano, que pode ser usado como um predicado individual na seção events. Essas funções são:

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

Exemplo:

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

Expressões de lista de referência

É possível usar listas de referência na seção de eventos. Consulte a seção sobre Listas de referência para mais detalhes.

Expressões lógicas

É possível usar os operadores lógicos and e or na seção events, conforme mostrado nos exemplos a seguir:

  • $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"

Por padrão, a ordem de precedência do mais alto para o mais baixo é not, and, or.

Por exemplo, "a or b and c" é avaliado como "a or (b and c)" quando os operadores or e and são definidos explicitamente na expressão.

Na seção events, os predicados são unidos usando o operador and se um operador não for definido explicitamente.

A ordem de avaliação pode ser diferente se o operador and estiver implícito na expressão.

Por exemplo, considere as seguintes expressões de comparação em que or é definido explicitamente. O operador and está implícito.

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

Este exemplo é interpretado da seguinte maneira:

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

Como or é definido explicitamente, os predicados ao redor de or são agrupados e avaliados primeiro. O último predicado, $e2.field = "bar", é unido implicitamente usando and. O resultado é que a ordem de avaliação muda.

Tipos enumerados

É possível usar os operadores com tipos enumerados. Ele pode ser aplicado a regras para simplificar e otimizar a performance (use o operador em vez de listas de referência).

No exemplo a seguir, "USER_UNCATEGORIZED" e "USER_RESOURCE_DELETION" correspondem a 15000 e 15014. Portanto, a regra vai procurar todos os eventos listados:

$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

Quando você tem uma expressão de comparação entre valores de string ou uma expressão regular, é possível adicionar "nocase" ao final da expressão para ignorar o uso de maiúsculas e minú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

Não pode ser usado quando um tipo de campo é um valor enumerado. Os exemplos a seguir são inválidos e vão gerar erros de compilação:

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

Campos repetidos

No modelo de dados unificado (UDM), alguns campos são rotulados como repetidos, o que indica que são listas de valores ou outros tipos de mensagens.

Campos repetidos e expressões booleanas

Há dois tipos de expressões booleanas que atuam em campos repetidos:

  1. Modificado
  2. Não modificado

Considere o seguinte evento:

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

    hostname: "host"
  }
}

Expressões modificadas

As seções a seguir descrevem a finalidade e como usar os modificadores any e all em expressões.

qualquer

Se qualquer elemento do campo repetido atender à condição, o evento como um todo vai atender.

  • event_original satisfaz any $e.principal.ip = "192.0.2.1".
  • event_original falha any $e.repeated_field.field_a = "9.9.9.9.
todas

Se todos os elementos do campo repetido atenderem à condição, o evento como um todo vai atender à condição.

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

Ao escrever uma condição com any ou all, saiba que negar a condição com not pode não ter o mesmo significado que usar o operador negado.

Exemplo:

  • not all $e.principal.ip = "192.168.12.16" verifica se nem todos os endereços IP correspondem a 192.168.12.16. Isso significa que a regra verifica se pelo menos um endereço IP não corresponde a 192.168.12.16.
  • all $e.principal.ip != "192.168.12.16" verifica se todos os endereços IP não correspondem a 192.168.12.16, ou seja, a regra verifica se nenhum endereço IP corresponde a 192.168.12.16.

Restrições:

  • Os operadores any e all são compatíveis apenas com campos repetidos (não escalares).
  • any e all não podem ser usados para unir dois campos repetidos. Por exemplo, any $e1.principal.ip = $e2.principal.ip não é válido.
  • Os operadores any e all não são compatíveis com a expressão da lista de referência.

Expressões não modificadas

Com expressões não modificadas, cada elemento no campo repetido é tratado individualmente. Se o campo repetido de um evento tiver n elementos, a regra será aplicada a n cópias do evento, em que cada cópia tem um dos elementos do campo repetido. Essas cópias são temporárias e não são armazenadas.

A regra é aplicada nas seguintes cópias:

cópia do evento principal.ip principal.hostname
event_copy_1 "192.0.2.1" "host"
event_copy_2 "192.0.2.2" "host"
event_copy_3 "192.0.2.3" "host"

Se qualquer cópia de evento atender a todas as condições não modificadas no campo repetido, o evento como um todo atenderá a todas as condições. Isso significa que, se você tiver várias condições em um campo repetido, a cópia do evento precisará atender a todas elas. Os exemplos de regra a seguir usam o conjunto de dados de exemplo anterior para demonstrar esse comportamento.

A regra a seguir retorna uma correspondência quando executada no conjunto de dados de exemplo event_original, porque event_copy_1 satisfaz todos os 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
}

A regra a seguir não retorna uma correspondência quando executada no conjunto de dados de exemplo event_original, porque não há uma cópia de evento em $e.principal.ip que satisfaça todos os predicados de evento.

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

As expressões modificadas em campos repetidos são compatíveis com as não modificadas porque a lista de elementos é a mesma para cada cópia de evento. Considere a seguinte regra:

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

A regra é aplicada nas seguintes cópias:

cópia do evento principal.ip any $e.principal.ip
event_copy_1 "192.0.2.1" ["192.0.2.1", "192.0.2.2", "192.0.2.3"]
event_copy_2 "192.0.2.2" ["192.0.2.1", "192.0.2.2", "192.0.2.3"]
event_copy_3 "192.0.2.3" ["192.0.2.1", "192.0.2.2", "192.0.2.3"]

Nesse caso, todas as cópias atendem a any $e.principal.ip = "192.0.2.1", mas apenas event_copy_3 atende a $e.principal.ip = "192.0.2.3". Como resultado, o evento como um todo corresponderia.

Outra forma de pensar nesses tipos de expressões é:

  • As expressões em campos repetidos que usam any ou all operam na lista em event_original.
  • As expressões em campos repetidos que não usam any ou all operam em eventos event_copy_n individuais.

Campos repetidos e marcadores de posição

Os campos repetidos funcionam com atribuições de marcador de posição. Assim como nas expressões não modificadas em campos repetidos, uma cópia do evento é feita para cada elemento. Usando o mesmo exemplo de event_copy, o marcador de posição recebe o valor do campo repetido de event_copy_n para cada uma das cópias de evento em que n é o número da cópia do evento. Se o marcador de posição for usado na seção de correspondência, isso poderá resultar em várias correspondências.

O exemplo a seguir gera uma correspondência. O marcador de posição $ip é igual a 192.0.2.1 para event_copy_1, o que satisfaz os predicados na regra. As amostras de eventos da partida contêm um único 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
}

O exemplo a seguir gera três correspondências. O marcador de posição $ip é igual a valores diferentes para cada uma das cópias de event_copy_n. O agrupamento é feito em $ip porque está na seção de correspondência. Portanto, você recebe três correspondências, cada uma com um valor diferente para a variável de correspondência $ip. Cada correspondência tem a mesma amostra de evento: um único 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 usando marcadores de posição atribuídos a campos repetidos

Os marcadores de posição são atribuídos a cada elemento de cada campo repetido, não à lista inteira. Assim, quando eles são usados na seção de resultado, o resultado é calculado usando apenas os elementos que satisfizeram as seções anteriores.

Considere a seguinte regra:

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
}

Há quatro estágios de execução para essa regra. A primeira etapa é a cópia de eventos:

cópia do evento $ip $host $e
event_copy_1 "192.0.2.1" "host" event_id
event_copy_2 "192.0.2.2" "host" event_id
event_copy_3 "192.0.2.3" "host" event_id

A seção de eventos vai filtrar as linhas que não correspondem aos filtros:

cópia do evento $ip $host $e
event_copy_1 "192.0.2.1" "host" event_id
event_copy_2 "192.0.2.2" "host" event_id

event_copy_3 é filtrado porque "192.0.2.3" não satisfaz $ip = "192.0.2.1" or $ip = "192.0.2.2".

A seção de correspondência vai agrupar por variáveis de correspondência, e a seção de resultado vai fazer a agregação em cada grupo:

$host $o $e
"host" ["192.0.2.1", "192.0.2.2"] event_id

O $o = array_distinct($ip) é calculado usando o $ip da etapa anterior, não da etapa de cópia de eventos.

Por fim, a seção de condição vai filtrar cada grupo. Como essa regra verifica apenas a existência de $e, a linha anterior vai gerar uma única detecção.

$o não contém todos os elementos de $e.principal.ip porque nem todos os elementos atendem a todas as condições na seção "Eventos". No entanto, todos os elementos de e.principal.ip vão aparecer na amostra de evento porque ela usa event_original.

Indexação de matrizes

É possível realizar indexação de matrizes em campos repetidos. Para acessar o n-ésimo elemento de campo repetido, use a sintaxe de lista padrão (os elementos são indexados em 0). Um elemento fora dos limites retorna o valor padrão.

  • $e.principal.ip[0] = "192.168.12.16"
  • $e.principal.ip[999] = "" Se houver menos de 1.000 elementos, isso será avaliado como true.

Restrições:

  • Um índice precisa ser um literal inteiro não negativo. Por exemplo, $e.principal.ip[-1] não é válido.
  • Valores que têm um tipo int (por exemplo, um marcador de posição definido como int) não são contabilizados.
  • Não é possível combinar a indexação de matrizes com any ou all. Por exemplo, any $e.intermediary.ip[0] não é válido.
  • Não é possível combinar a indexação de matrizes com a sintaxe de mapa. Por exemplo, $e.additional.fields[0]["key"] não é válido.
  • Se o caminho do campo contiver vários campos repetidos, todos eles precisarão usar indexação de matriz. Por exemplo, $e.intermediary.ip[0] não é válido porque intermediary e ip são campos repetidos, mas há apenas um índice para ip.

Mensagens repetidas

Quando um campo message é repetido, um efeito não intencional é reduzir a probabilidade de uma correspondência. Isso é ilustrado nos exemplos a seguir.

Considere o seguinte 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 afirmado para expressões não modificadas em campos repetidos, uma cópia temporária do evento é feita para cada elemento do campo repetido. Considere a seguinte regra:

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

A regra é aplicada nas seguintes cópias:

cópia do evento about.ip about.hostname
event_copy_1 "192.0.2.1" "alice"
event_copy_2 "192.0.2.2" "alice"
event_copy_3 "192.0.2.3" "alice"
event_copy_4 "" "bob"

O evento não corresponde à regra porque não há uma cópia que satisfaça todas as expressões.

Mensagens repetidas e indexação de matrizes

Outro comportamento inesperado pode ocorrer ao usar indexação de matriz com expressões não modificadas em campos de mensagens repetidas. Considere a seguinte regra de exemplo que usa indexação de matriz:

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

A regra é aplicada às seguintes cópias:

cópia do evento about.ip about[1].hostname
event_copy_1 "192.0.2.1" "bob"
event_copy_2 "192.0.2.2" "bob"
event_copy_3 "192.0.2.3" "bob"
event_copy_4 "" "bob"

Como event_copy_1 satisfaz todas as expressões em repeated_message_2, o evento corresponde à regra.

Isso pode levar a um comportamento inesperado porque a regra repeated_message_1 não tinha indexação de matriz e não produziu correspondências, enquanto a regra repeated_message_2 usou indexação de matriz e produziu uma correspondência.

Comentários

Designar comentários com dois caracteres de barra (// comment) ou comentários de várias linhas definidos usando caracteres de barra asterisco (/* comment */), como em C.

Literais

Há suporte para números inteiros e de ponto flutuante não negativos, strings, booleanos e literais de expressões regulares.

Literais de string e expressão regular

Você pode usar qualquer um dos seguintes caracteres de aspas para incluir strings no YARA-L 2.0. No entanto, o texto entre aspas é interpretado de maneira diferente dependendo de qual deles você usa.

  1. Aspas duplas ("): use para strings normais. Precisa incluir caracteres de escape.
    Por exemplo: "hello\tworld" —\t é interpretado como uma tabulação

  2. Aspas invertidas (`) — usadas para interpretar todos os caracteres literalmente.
    Por exemplo: `hello\tworld` —\t não é interpretado como uma tabulação

Para expressões regulares, você tem duas opções.

Se você quiser usar expressões regulares diretamente sem a função re.regex(), use /regex/ para os literais de expressão regular.

Também é possível usar literais de string como literais de expressão regular ao usar a função re.regex(). Para literais de string entre aspas duplas, é necessário fazer o escape de caracteres de barra invertida com caracteres de barra invertida, o que pode parecer estranho.

Por exemplo, as seguintes expressões regulares são equivalentes:

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

O Google recomenda usar crases para strings em expressões regulares para facilitar a leitura.

Operadores

É possível usar os seguintes operadores em YARA-L:

Operador Descrição
= equal/declaration
!= diferente
< menor que
<= menor ou igual a
> maior que
>= maior ou igual a

Variáveis

No YARA-L 2.0, todas as variáveis são representadas como $<variable name>.

É possível definir os seguintes tipos de variáveis:

  • Variáveis de evento: representam grupos de eventos de forma normalizada (UDM) ou eventos de entidade. Especifique condições para variáveis de evento na seção events. Você identifica variáveis de evento usando um nome, uma origem e campos de evento. As fontes permitidas são udm (para eventos normalizados) e graph (para eventos de entidade). Se a origem for omitida, udm será definida como a origem padrão. Os campos de evento são representados como uma cadeia de .<nome do campo> (por exemplo, $e.field1.field2). As cadeias de campos de eventos sempre começam na origem de nível superior (UDM ou entidade).

  • Variáveis de correspondência: declare na seção match. As variáveis de correspondência se tornam campos de agrupamento para a consulta, já que uma linha é retornada para cada conjunto exclusivo de variáveis de correspondência (e para cada janela de tempo). Quando a regra encontra uma correspondência, os valores das variáveis de correspondência são retornados. Especifique o que cada variável de correspondência representa na seção events.

  • Variáveis de marcador de posição: declare e defina na seção events. As variáveis de marcador de posição são semelhantes às variáveis de correspondência. No entanto, é possível usar variáveis de marcador de posição na seção condition para especificar condições de correspondência.

Use variáveis de correspondência e variáveis de substituição para declarar relações entre campos de evento usando condições de junção transitivas. Consulte Sintaxe da seção de eventos para mais detalhes.

Palavras-chave

As palavras-chave em YARA-L 2.0 não diferenciam maiúsculas de minúsculas. Por exemplo, and e AND são equivalentes. Os nomes das variáveis não podem entrar em conflito com palavras-chave. Por exemplo, $AND ou $outcome é inválido.

As seguintes palavras-chave são para as regras de detecção de mecanismo: 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, e null.

Maps

A YARA-L oferece suporte ao acesso a mapas para structs e rótulos.

Estruturas e rótulos

Alguns campos da UDM usam o tipo de dados Struct ou Label.

Para pesquisar um par de chave-valor específico em Struct e Label, use a sintaxe de mapa padrão:

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

O acesso ao mapa sempre retorna uma string.

Casos compatíveis

Confira a seguir alguns casos de uso de palavras-chave compatíveis.

Seção "Eventos e 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"])
Atribuir um valor de mapa a um marcador
$placeholder = $u1.metadata.ingestion_labels["MetadataKeyDeletion"]
Como usar um campo de mapa em uma condição de junção
// 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 não aceitos

Os mapas não são compatíveis nos seguintes casos:

Como combinar palavras-chave any ou all com um mapa

Por exemplo, não é possível usar o seguinte:

all $e.udm.additional.fields["pod_name"] = "kube-scheduler"
Outros tipos de valores

A sintaxe de mapa só pode retornar um valor de string. No caso de tipos de dados Struct, a sintaxe de mapa só pode acessar chaves cujos valores são strings. Não é possível acessar chaves cujos valores são outros tipos primitivos, como números inteiros.

Processamento de valores duplicados

Os acessos ao mapa sempre retornam um único valor. No caso raro em que o acesso ao mapa pode se referir a vários valores, ele vai retornar deterministicamente o primeiro valor.

Isso pode acontecer em um dos seguintes casos:

  • Um rótulo tem uma chave duplicada.

    A estrutura do rótulo representa um mapa, mas não exige exclusividade da chave. Por convenção, um mapa precisa ter chaves exclusivas. Por isso, o Google SecOps não recomenda preencher um rótulo com chaves duplicadas.

    O texto da regra $e.metadata.ingestion_labels["dupe-key"] retornaria o primeiro valor possível, val1, se executado no exemplo de dados a seguir:

    // 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"
    }
  }
}

  • Um rótulo tem um campo repetido de ancestral.

    Um campo repetido pode conter um rótulo como um campo filho. Duas entradas diferentes no campo repetido de nível superior podem conter rótulos com a mesma chave. O texto da regra $e.security_result.rule_labels["key"] retornaria o primeiro valor possível, val3, se executado no exemplo de dados a seguir:

    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"
    }
  }
}

Funções

Esta seção descreve as funções da YARA-L 2.0 que podem ser usadas em regras e pesquisas do mecanismo de detecção.

Essas funções podem ser usadas nas seguintes partes de uma regra da YARA-L:

arrays.concat

Compatível com:
arrays.concat(string_array, string_array)

Descrição

Retorna uma nova matriz de strings copiando elementos das matrizes de strings originais.

Tipos de dados de parâmetros

ARRAY_STRINGS, ARRAY_STRINGS

Tipo de retorno

ARRAY_STRINGS

Amostras de código

Exemplo 1

O exemplo a seguir concatena duas matrizes de strings diferentes.

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

O exemplo a seguir concatena matrizes com uma string vazia.

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

O exemplo a seguir concatena matrizes vazias.

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

arrays.join_string

Compatível com:
arrays.join_string(array_of_strings, optional_delimiter)

Descrição

Converte uma matriz de strings em uma única string separada pelo parâmetro opcional. Se nenhum delimitador for fornecido, a string vazia será usada.

Tipos de dados de parâmetros

ARRAY_STRINGS, STRING

Tipo de retorno

STRING

Amostras de código

Confira alguns exemplos de como usar a função:

Exemplo 1

Este exemplo une uma matriz com elementos não nulos e um delimitador.

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

Este exemplo une uma matriz com um elemento nulo e um delimitador.

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

Este exemplo une uma matriz com elementos não nulos e sem delimitador.

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

arrays.length

Compatível com:
arrays.length(repeatedField)

Descrição

Retorna o número de elementos de campo repetidos.

Tipos de dados de parâmetros

LIST

Tipo de retorno

NUMBER

Amostras de código

Exemplo 1

Retorna o número de elementos de campo repetidos.

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

Se houver vários campos repetidos ao longo do caminho, vai retornar o número total de elementos de campo repetidos.

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

arrays.max

Compatível com:
arrays.max(array_of_ints_or_floats)

Descrição

Retorna o maior elemento em uma matriz ou zero se a matriz estiver vazia.

Tipos de dados de parâmetros

ARRAY_INTS|ARRAY_FLOATS

Tipo de retorno

FLOAT

Amostras de código

Confira alguns exemplos de como usar a função:

Exemplo 1

Este exemplo retorna o elemento maior em uma matriz de números inteiros.

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

Este exemplo retorna o elemento maior em uma matriz de números de ponto flutuante.

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

arrays.min

Compatível com:
arrays.min(array_of_ints_or_floats[, ignore_zeros=false])

Descrição

Retorna o menor elemento em uma matriz ou zero se a matriz estiver vazia. Se o segundo argumento opcional for definido como "true", os elementos iguais a zero serão ignorados.

Tipos de dados de parâmetros

ARRAY_INTS|ARRAY_FLOATS, BOOL

Tipo de retorno

FLOAT

Amostras de código

Confira alguns exemplos de como usar a função:

Exemplo 1

Este exemplo retorna o menor elemento em uma matriz de números inteiros.

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

Este exemplo retorna o menor elemento em uma matriz de números de ponto flutuante.

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

Este exemplo retorna o menor elemento em uma matriz de números de ponto flutuante, ignorando os zeros.

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

arrays.size

Compatível com:
arrays.size( array )

Descrição

Retorna o tamanho da matriz. Retorna 0 para uma matriz vazia.

Tipos de dados de parâmetros

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS

Tipo de retorno

INT

Amostras de código

Exemplo 1

Este exemplo usa uma matriz de strings que contém dois elementos.

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

Este exemplo usa uma matriz de números inteiros que contém três elementos.

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

Este exemplo usa uma matriz de ponto flutuante que contém um elemento.

arrays.size([1.200000]) = 1
Exemplo 4

Este exemplo usa uma matriz vazia.

arrays.size([]) = 0

arrays.index_to_float

Compatível com:
arrays.index_to_float(array, index)

Descrição

Retorna o elemento no índice especificado de uma matriz. O elemento nesse índice é retornado como um ponto flutuante.

O índice é um valor inteiro que representa a posição de um elemento na matriz. Por padrão, o primeiro elemento de uma matriz tem um índice de 0, e o último elemento tem um índice de n-1, em que n é o tamanho da matriz. A indexação negativa permite acessar elementos da matriz em relação ao final dela. Por exemplo, um índice de -1 se refere ao último elemento da matriz, e um índice de -2 se refere ao penúltimo elemento.

Tipos de dados de parâmetros

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS, INT

Tipo de retorno

FLOAT

Amostras de código

Exemplo 1

O exemplo a seguir busca um elemento no índice 1 de uma matriz de números de ponto flutuante.

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

O exemplo a seguir busca um elemento no índice -1 de uma matriz de números de ponto flutuante.

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

O exemplo a seguir busca um elemento para um índice maior que o tamanho da matriz.

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

O exemplo a seguir busca um elemento de uma matriz vazia.

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

O exemplo a seguir busca um elemento no índice 1 de uma matriz de strings.

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

O exemplo a seguir busca um elemento no índice 2 de uma matriz de números inteiros.

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

arrays.index_to_int

Compatível com:
arrays.index_to_int(array_of_inputs, index)

Descrição

Retorna o valor em um determinado índice em uma matriz como um número inteiro.

O índice é um valor inteiro que representa a posição de um elemento na matriz. Por padrão, o primeiro elemento de uma matriz tem um índice de 0, e o último elemento tem um índice de n-1, em que n é o tamanho da matriz. A indexação negativa permite acessar elementos da matriz em relação ao final dela. Por exemplo, um índice de -1 se refere ao último elemento da matriz, e um índice de -2 se refere ao penúltimo elemento.

Tipos de dados de parâmetros

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS, INT

Tipo de retorno

INT

Amostras de código

Exemplo 1

Essa chamada de função retorna 0 quando o valor no índice é uma string não numérica.

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

Essa função retorna o elemento no índice -1.

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

Retorna 0 para o elemento fora dos limites.

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

Essa função busca o elemento da matriz de ponto flutuante no índice 1.

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

Essa função busca o elemento da matriz de números inteiros no índice 0.

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

arrays.index_to_str

Compatível com:
arrays.index_to_str(array, index)

Descrição

Retorna o elemento no índice especificado da matriz como uma string. O índice é um valor inteiro que representa a posição de um elemento na matriz. Por padrão, o primeiro elemento de uma matriz tem um índice de 0, e o último elemento tem um índice de n-1, em que n é o tamanho da matriz. Com a indexação negativa, é possível acessar elementos da matriz do final para o início. Por exemplo, um índice de -1 se refere ao último elemento da matriz, e um índice de -2 se refere ao penúltimo elemento.

Tipos de dados de parâmetros

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS, INT

Tipo de retorno

STRING

Amostras de código

Exemplo 1

O exemplo a seguir busca um elemento no índice 1 de uma matriz de strings.

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

O exemplo a seguir busca um elemento no índice -1 (último elemento da matriz) de uma matriz de strings.

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

O exemplo a seguir busca um elemento para um índice maior que o tamanho da matriz, o que retorna uma string vazia.

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

O exemplo a seguir busca um elemento de uma matriz vazia.

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

O exemplo a seguir busca um elemento no índice 0 de uma matriz de números de ponto flutuante. A saída é retornada como uma string.

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

O exemplo a seguir busca um elemento no índice 2 de uma matriz de números inteiros. A saída está no formato de uma string.

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

cast.as_bool

Compatível com:
cast.as_bool(string_or_int)

Descrição

A função converte um valor int ou string em um valor booleano. As chamadas de função com valores que não podem ser convertidos vão retornar FALSE. Retorna TRUE somente para o número inteiro 1 e a string "true" (sem diferenciar maiúsculas e minúsculas).

Tipos de dados de parâmetros

INT|STRING

Tipo de retorno

BOOL

Amostras de código

Exemplo 1

Este exemplo mostra como converter uma string não booleana

cast.as_bool("123") = false
Exemplo 2

Número inteiro verdadeiro (1)

cast.as_bool(1) = true
Exemplo 3

String verdadeira

cast.as_bool("true") = true
Exemplo 4

String verdadeira em maiúscula

cast.as_bool("TRUE") = true
Example 5

Número inteiro negativo

cast.as_bool(0-1) = false
Exemplo 6

Número inteiro falso (0)

cast.as_bool(0) = false
Exemplo 7

String vazia

cast.as_bool("") = false

cast.as_float

Compatível com:
cast.as_float(string_to_cast)

Descrição

Converte uma string numérica em um ponto flutuante. Todas as chamadas de função com valores que não podem ser convertidos retornam 0. Os números de ponto flutuante mantêm a precisão de até sete casas decimais.

Tipos de dados de parâmetros

STRING

Tipo de retorno

FLOAT

Amostras de código

Exemplo 1

A conversão de uma string não numérica retorna 0.

cast.as_float("str") = 0.0000000
Exemplo 2

A conversão de uma string vazia retorna 0.

cast.as_float("") = 0.0000000
Exemplo 3

A transmissão de uma string numérica válida retorna um valor de ponto flutuante.

cast.as_float("1.012345678") = 1.0123456

cast.as_string

Compatível com:
cast.as_string(int_or_bytes_or_bool, optional_default_string)

Descrição

A função cast.as_string transforma um valor INT, BYTES ou BOOL na representação de string dele. Você pode fornecer um argumento default_string opcional para lidar com casos em que a transmissão falha. Se você omitir o argumento default_string ou se a entrada for uma sequência de bytes UTF-8 ou BASE64 inválida, a função vai retornar uma string vazia.

Tipos de dados de parâmetros

INT|BYTES|BOOL, STRING

Tipo de retorno

STRING

Amostras de código

Conversão de número inteiro para string

A função converte o número inteiro 123 na string "123".

cast.as_string(123) = "123"
Conversão de ponto flutuante para string

A função converte o ponto flutuante 2.25 na string "2.25".

cast.as_string(2.25) = "2.25"
Conversão de bytes para string

A função converte o b'01 binário bruto na string "\x01".

cast.as_string(b'01, "") = "\x01"
Conversão de booleano para string

A função converte o booleano true na string "true".

cast.as_string(true, "") = "true"
Falha na conversão (o padrão é a string fornecida opcionalmente)

A função usa a string "casting error" como padrão quando o valor fornecido é inválido.

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

Impressão digital

Compatível com:
hash.fingerprint2011(byteOrString)

Descrição

Essa função calcula o hash fingerprint2011 de uma sequência de bytes ou string de entrada. Essa função retorna um valor INT sem sinal no intervalo [2, 0xFFFFFFFFFFFFFFFF].

Tipos de dados de parâmetros

BTYE, STRING

Tipo de retorno

INT

Exemplo de código

id_fingerprint = hash.fingerprint2011("user123")

grupo

Compatível com:
group(field1, field2, field3, ...)

Descrição

Agrupe campos de um tipo semelhante em uma variável de marcador de posição.

Na pesquisa da UDM, os campos agrupados são usados para pesquisar em vários campos de um tipo semelhante. A função "grupo" é semelhante aos campos agrupados, mas permite selecionar quais campos você quer agrupar para acionar uma detecção. Use a função de grupo para coletar informações sobre uma entidade específica (por exemplo, um nome de host, endereço IP ou ID de usuário) em diferentes tipos de substantivo.

Amostras de código

Exemplo 1

Agrupe todos os endereços IP e forneça uma contagem decrescente do endereço IP mais prevalente no período verificado. 

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

hash.sha256

Compatível com:
hash.sha256(string)

Descrição

Retorna um hash SHA-256 da string de entrada.

Tipos de dados de parâmetros

STRING

Tipo de retorno

STRING

Amostras de código

Exemplo 1

Este exemplo mostra o hash SHA-256 quando a entrada é uma string válida.

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

Este exemplo mostra o hash SHA-256 quando a entrada é uma string vazia.

hash.sha256("") = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

math.abs

Compatível com:
math.abs(numericExpression)

Descrição

Retorna o valor absoluto de uma expressão de número inteiro ou ponto flutuante.

Tipos de dados de parâmetros

NUMBER

Tipo de retorno

NUMBER

Amostras de código

Exemplo 1

Esse exemplo retorna "True" se o evento ocorreu mais de 5 minutos após o horário especificado (em segundos desde a época Unix), independentemente de ter ocorrido antes ou depois do horário especificado. Uma chamada para math.abs não pode depender de várias variáveis ou marcadores de posição. Por exemplo, não é possível substituir o valor de tempo codificado de 1643687343 no exemplo a seguir por $e2.metadata.event_timestamp.seconds.

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

math.ceil

Compatível com:
math.ceil(number)

Descrição

Retorna o menor número inteiro que não seja menor que o número fornecido (arredondamento para cima). Retornará 0 se a entrada for nula ou muito grande para caber em um int64.

Tipos de dados de parâmetros

FLOAT

Tipo de retorno

INT

Amostras de código

Esta seção contém exemplos de uso do math.ceil.

Exemplo 1

Este exemplo retorna o teto de um número inteiro.

math.ceil(2.000000) = 2
Exemplo 2

Este exemplo retorna o teto de um número negativo.

math.ceil(0-1.200000) = -1
Exemplo 3

Este exemplo retorna 0 como o teto de um número muito grande para um inteiro de 64 bits.

math.ceil(184467440737095516160.0) = 0

math.floor

Compatível com:
math.floor(float_val)

Descrição

Retorna o maior valor inteiro que não é maior que o valor fornecido (arredondamento para baixo). Retorna 0 se a entrada for nula ou muito grande para caber em um int64.

Tipos de dados de parâmetros

FLOAT

Tipo de retorno

INT

Amostras de código

Exemplo 1

Este exemplo mostra um caso de número positivo.

math.floor(1.234568) = 1
Exemplo 2

Este exemplo mostra um caso de número negativo.

math.floor(0-1.234568) = -2
Exemplo 3

Este exemplo mostra um caso de zero.

math.floor(0.000000) = 0

math.geo_distance

Compatível com:
math.geo_distance(longitude1, latitude1, longitude2, latitude2))

Descrição

Retorna a distância entre dois locais geográficos (coordenadas) em metros. Retorna -1 se as coordenadas forem inválidas.

Tipos de dados de parâmetros

FLOAT, FLOAT, FLOAT, FLOAT

Tipo de retorno

FLOAT

Amostras de código

Exemplo 1

O exemplo a seguir retorna a distância quando todos os parâmetros são coordenadas válidas:

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

O exemplo a seguir retorna a distância quando um dos parâmetros é uma coordenada truncada:

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

O exemplo a seguir retorna -1 quando um dos parâmetros é uma coordenada inválida:

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

O exemplo a seguir retorna 0 quando as coordenadas são iguais:

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

math.is_increasing

Compatível com:
math.is_increasing(num1, num2, num3)

Descrição

Usa uma lista de valores numéricos (inteiros ou de ponto flutuante) e retorna True se os valores estiverem em ordem crescente e False caso contrário.

Tipos de dados de parâmetros

INT|FLOAT, INT|FLOAT, INT|FLOAT

Tipo de retorno

BOOL

Amostras de código

Exemplo 1

Este exemplo inclui valores semelhantes a carimbos de data/hora em segundos.

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

Este exemplo inclui um valor double negativo, um INT64 zero e um INT64 positivo.

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

Este exemplo inclui um valor double negativo, um INT64 zero e um INT64 negativo.

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

Este exemplo inclui dois números de ponto flutuante negativos e um valor INT64 zero.

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

Este exemplo inclui um número de ponto flutuante negativo e dois valores iguais.

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

math.log

Compatível com:
math.log(numericExpression)

Descrição

Retorna o valor do logaritmo natural de uma expressão de número inteiro ou ponto flutuante.

Tipos de dados de parâmetros

NUMBER

Tipo de retorno

NUMBER

Amostras de código

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

math.pow

Compatível com:
math.pow(base, exponent)

Descrição

Retorna o valor do primeiro argumento elevado à potência do segundo argumento. Retorna 0 em caso de estouro.

Tipos de dados de parâmetros

base: INT|FLOAT expoente: INT|FLOAT

Tipo de retorno

FLOAT

Amostras de código

Exemplo 1

Este exemplo mostra um caso de número inteiro.

math.pow(2, 2) // 4.00
Exemplo 2

Este exemplo mostra um caso básico de fração.

math.pow(2.200000, 3) // 10.648
Exemplo 3

Este exemplo mostra uma base fracionária e um caso de potência.

math.pow(2.200000, 1.200000) // 2.575771
Exemplo 4

Este exemplo mostra um caso de potência negativa.

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

Este exemplo mostra um caso de potência fracionária.

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

Este exemplo mostra um caso de base negativo.

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

Este exemplo mostra um caso de base zero.

math.pow(0, 3) // 0
Exemplo 8

Este exemplo mostra um caso de potência zero.

math.pow(9223372036854775807, 0) // 1
Exemplo 9

Este exemplo mostra um caso de base grande.

math.pow(9223372036854775807, 1.200000) // 57262152889751593549824

math.random

Compatível com:
math.random()

Descrição

Gera um valor pseudoaleatório do tipo DOUBLE no intervalo de [0, 1), incluindo 0 e excluindo 1.

Tipo de retorno

FLOAT

Amostras de código

O exemplo a seguir verifica se o valor aleatório está no intervalo [0, 1). none if(math.random() >= 0 and math.random() < 1) = true

math.round

Compatível com:
math.round(numericExpression, decimalPlaces)

Descrição

Retorna um valor arredondado para o número inteiro mais próximo ou para o número especificado de casas decimais.

Tipos de dados de parâmetros

NUMBER

Tipo de retorno

NUMBER

Amostras 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

Compatível com:
math.sqrt(number)

Descrição

Retorna a raiz quadrada do número especificado. Retorna 0 em caso de números negativos.

Tipos de dados de parâmetros

INT|FLOAT

Tipo de retorno

FLOAT

Amostras de código

Exemplo 1

Este exemplo retorna a raiz quadrada de um argumento int.

math.sqrt(3) = 1.732051
Exemplo 2

Este exemplo retorna a raiz quadrada de um argumento int negativo.

math.sqrt(-3) = 0.000000
Exemplo 3

Este exemplo retorna a raiz quadrada do argumento zero.

math.sqrt(0) = 0.000000
Exemplo 4

Este exemplo retorna a raiz quadrada de um argumento de ponto flutuante.

math.sqrt(9.223372) = 3.037000
Example 5

Este exemplo retorna a raiz quadrada de um argumento de ponto flutuante negativo.

math.sqrt(0-1.200000) = 0.000000

métricas

Compatível com:

As funções de métricas podem agregar grandes quantidades de dados históricos. Você pode usar isso na sua regra usando metrics.functionName() na seção de resultado.

Para mais informações, consulte Métricas do YARA-L.

net.ip_in_range_cidr

Compatível com:
net.ip_in_range_cidr(ipAddress, subnetworkRange)

Descrição

Retorna true quando o endereço IP fornecido está dentro da sub-rede especificada.

Você pode usar o YARA-L para pesquisar eventos da UDM em todos os endereços IP de uma sub-rede usando a instrução net.ip_in_range_cidr(). Os dois protocolos são compatíveis.

Para pesquisar em um intervalo de endereços IP, especifique um campo UDM de IP e um intervalo CIDR. A YARA-L pode processar campos de endereço IP únicos e repetidos.

Para pesquisar em um intervalo de endereços IP, especifique um campo ip da UDM e um intervalo de roteamento entre domínios sem classe (CIDR). A YARA-L pode processar campos de endereço IP únicos e repetidos.

Tipos de dados de parâmetros

STRING, STRING

Tipo de retorno

BOOL

Amostras de código

Exemplo 1

Exemplo de IPv4:

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

Exemplo de IPv6:

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

Para ver um exemplo de regra usando a instrução net.ip_in_range_cidr(), consulte o exemplo em Evento único em um intervalo de endereços IP.

re.regex

Compatível com:

É possível definir a correspondência de expressões regulares em YARA-L 2.0 usando uma das seguintes sintaxes:

  • Usando a sintaxe YARA-L — relacionada a eventos. Confira a seguir uma representação genérica dessa sintaxe:

    $e.field = /regex/

  • Usando a sintaxe YARA-L como uma função que recebe os seguintes parâmetros:

    • Campo em que a expressão regular é aplicada.
    • Expressão regular especificada como uma string.

    Confira a seguir uma representação genérica dessa sintaxe:

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

Descrição

Essa função retorna true se a string contiver uma substring que corresponda à expressão regular fornecida. Não é necessário adicionar .* no início ou no fim da expressão regular.

Observações
  • Para corresponder à string exata ou apenas a um prefixo ou sufixo, inclua os caracteres âncora ^ (inicial) e $ (final) na expressão regular. Por exemplo, /^full$/ corresponde exatamente a "full", enquanto /full/ pode corresponder a "fullest", "lawfull" e "joyfully".
  • Se o campo da UDM incluir caracteres de nova linha, o regexp só vai corresponder à primeira linha do campo. Para forçar a correspondência completa do campo UDM, adicione um (?s) à expressão regular. Por exemplo, substitua /.*allUDM.*/ por /(?s).*allUDM.*/.
  • Use o modificador nocase depois das strings para indicar que a pesquisa deve ignorar a capitalização.

Tipos de dados de parâmetros

STRING, STRING

Tipos de expressão de parâmetro

ANY, ANY

Tipo de retorno

BOOL

Amostras de código

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

re.capture

Compatível com:
re.capture(stringText, regex)

Descrição

Captura (extrai) dados de uma string usando o padrão de expressão regular fornecido no argumento.

Essa função usa dois argumentos:

  • stringText: a string original a ser pesquisada.
  • regex: a expressão regular que indica o padrão a ser pesquisado.

A expressão regular pode conter 0 ou 1 grupo de captura entre parênteses. Se a expressão regular contiver zero grupos de captura, a função retornará a primeira substring correspondente inteira. Se a expressão regular contiver um grupo de captura, ela vai retornar a primeira substring correspondente a esse grupo. Definir dois ou mais grupos de captura retorna um erro do compilador.

Tipos de dados de parâmetros

STRING, STRING

Tipo de retorno

STRING

Amostras de código

Exemplo 1

Neste exemplo, se $e.principal.hostname contiver "aaa1bbaa2", o seguinte será verdadeiro porque a função retorna a primeira instância. Este exemplo não tem grupos de captura.

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

Este exemplo captura tudo depois do símbolo @ em um e-mail. Se o campo $e.network.email.from for test@google.com, o exemplo vai retornar google.com. O exemplo a seguir contém um grupo de captura.

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

Se a expressão regular não corresponder a nenhuma substring no texto, a função vai retornar uma string vazia. Você pode omitir eventos em que não há correspondência excluindo a string vazia, o que é especialmente importante quando você usa re.capture() com uma desigualdade:

// 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

Compatível com:
re.replace(stringText, replaceRegex, replacementText)

Descrição

Executa uma substituição de expressão regular.

Essa função usa três argumentos:

  • stringText: a string original.
  • replaceRegex: a expressão regular que indica o padrão a ser pesquisado.
  • replacementText: o texto a ser inserido em cada correspondência.

Retorna uma nova string derivada da stringText original, em que todas as substrings que correspondem ao padrão em replaceRegex são substituídas pelo valor em replacementText. Use dígitos de escape com barra invertida (\1 a \9) em replacementText para inserir um texto correspondente ao grupo entre parênteses no padrão replaceRegex. Use \0 para indicar o texto correspondente inteiro.

A função substitui correspondências não sobrepostas e prioriza a substituição da primeira ocorrência encontrada. Por exemplo, re.replace("banana", "ana", "111") retorna a string "b111na".

Tipos de dados de parâmetros

STRING, STRING, STRING

Tipo de retorno

STRING

Amostras de código

Exemplo 1

Este exemplo captura tudo após o símbolo @ em um e-mail, substitui com por org e retorna o resultado. Observe o uso de funções aninhadas.

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

Este exemplo usa dígitos de escape com barra invertida no argumento replacementText para referenciar correspondências ao padrão 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"
                     )
Exemplo 3

Observe os seguintes casos ao lidar com strings vazias e re.replace():

Usar uma string vazia 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 substituir uma string vazia, use "^$" 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

Compatível com:
optimization.sample_rate(byteOrString, rateNumerator, rateDenominator)

Descrição

Essa função determina se um evento será incluído com base em uma estratégia de amostragem determinista. Essa função retorna:

  • true para uma fração de valores de entrada, equivalente a (rateNumerator / rateDenominator), indicando que o evento deve ser incluído na amostra.
  • false indicando que o evento não deve ser incluído na amostra.

Essa função é útil para cenários de otimização em que você quer processar apenas um subconjunto de eventos. Equivalente a:

hash.fingerprint2011(byteOrString) % rateDenominator < rateNumerator

Tipos de dados de parâmetros

  • byteOrString: expressão avaliada como BYTE ou STRING.
  • rateNumerator: 'INT'
  • rateDenominator: 'INT'

Tipo de retorno

BOOL

Exemplo 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

Compatível com:
strings.base64_decode(encodedString)

Descrição

Retorna uma string que contém a versão decodificada em base64 da string codificada.

Essa função usa uma string codificada em base64 como argumento. Se encodedString não for uma string codificada em base64 válida, a função vai retornar encodedString sem alterações.

Tipos de dados de parâmetros

STRING

Tipo de retorno

STRING

Amostras de código

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

strings.coalesce

Compatível com:
strings.coalesce(a, b, c, ...)

Descrição

Essa função usa um número ilimitado de argumentos e retorna o valor da primeira expressão que não é avaliada como uma string vazia (por exemplo, "valor diferente de zero"). Se todos os argumentos forem avaliados como uma string vazia, a chamada de função vai retornar uma string vazia.

Os argumentos podem ser literais, campos de evento ou chamadas de função. Todos os argumentos precisam ser do tipo STRING. Se algum argumento for um campo de evento, os atributos precisarão ser do mesmo evento.

Tipos de dados de parâmetros

STRING

Tipo de retorno

STRING

Amostras de código

Exemplo 1

O exemplo a seguir inclui variáveis de string como argumentos. A condição é avaliada como verdadeira quando (1) $e.network.email.from é suspicious@gmail.com ou (2) $e.network.email.from está vazio e $e.network.email.to é suspicious@gmail.com.

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

O exemplo a seguir chama a função coalesce com mais de dois argumentos. Essa condição compara o primeiro endereço IP não nulo do evento $e com os valores na lista de referência ip_watchlist. A ordem em que os argumentos são agrupados nessa chamada é a mesma em que são enumerados na condição da regra:

  1. $e.principal.ip é avaliado primeiro.
  2. Em seguida, $e.src.ip é avaliado.
  3. Em seguida, $e.target.ip é avaliado.
  4. Por fim, a string "No IP" será retornada como um valor padrão se os campos ip anteriores não estiverem definidos.
strings.coalesce($e.principal.ip, $e.src.ip, $e.target.ip, "No IP") in %ip_watchlist
Exemplo 3

O exemplo a seguir tenta unir principal.hostname do evento $e1 e do evento $e2. Ele vai retornar um erro do compilador porque os argumentos são variáveis de eventos diferentes.

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

strings.concat

Compatível com:
strings.concat(a, b, c, ...)

Descrição

Retorna a concatenação de um número ilimitado de itens, cada um dos quais pode ser uma string, um número inteiro ou um ponto flutuante.

Se algum argumento for um campo de evento, os atributos precisarão ser do mesmo evento.

Tipos de dados de parâmetros

STRING, FLOAT, INT

Tipo de retorno

STRING

Amostras de código

Exemplo 1

O exemplo a seguir inclui uma variável de string e uma variável de número inteiro como argumentos. principal.hostname e principal.port são do mesmo evento, $e, e são concatenados para retornar uma string.

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

O exemplo a seguir inclui uma variável de string e um literal de string como argumentos.

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

O exemplo a seguir inclui uma variável de string e um literal de ponto flutuante como argumentos. Quando representados como strings, os números de ponto flutuante inteiros são formatados sem o ponto decimal (por exemplo, 1,0 é representado como "1"). Além disso, os números de ponto flutuante que excedem 16 casas decimais são truncados na 16ª casa decimal.

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

O exemplo a seguir inclui uma variável de string, um literal de string, uma variável de número inteiro e um literal de ponto flutuante como argumentos. Todas as variáveis são do mesmo evento, $e, e são concatenadas com os literais para retornar uma string.

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

O exemplo a seguir tenta concatenar principal.port do evento $e1 com principal.hostname do evento $e2. Ele vai retornar um erro do compilador porque os argumentos são variáveis de eventos diferentes.

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

strings.contains

Compatível com:
strings.contains( str, substr )

Descrição

Retorna verdadeiro se uma determinada string contiver a substring especificada. Caso contrário, ele retorna "false".

Tipos de dados de parâmetros

STRING, STRING

Tipo de retorno

BOOL

Amostras de código

Exemplo 1

Este exemplo retorna "true" porque a string tem uma substring "is".

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

Este exemplo retorna "false" porque a string não tem a substring "that".

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

strings.count_substrings

Compatível com:
strings.count_substrings(string_to_search_in, substring_to_count)

Descrição

Quando recebe uma string e uma substring, retorna um int64 da contagem de ocorrências não sobrepostas da substring na string.

Tipos de dados de parâmetros

STRING, STRING

Tipo de retorno

INT

Amostras de código

Esta seção contém exemplos que calculam o número de vezes que uma substring aparece em uma determinada string.

Exemplo 1

Este exemplo usa uma string não nula e um único caractere de substring não nulo.

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

Este exemplo usa uma string não nula e uma substring não nula com mais de um caractere.

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

Este exemplo usa uma string não nula e uma substring vazia.

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

Este exemplo usa uma string vazia e uma substring não nula com mais de um caractere.

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

Este exemplo usa uma string e uma substring vazias.

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

Este exemplo usa uma string não nula e uma substring não nula com mais de um caractere e mais de uma ocorrência.

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

Este exemplo usa uma string não nula e uma substring não nula com mais de um caractere e mais de uma ocorrência. Ele destaca a limitação com ocorrências de substrings sobrepostas.

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

strings.extract_domain

Compatível com:
strings.extract_domain(url_string)

Descrição

Extrai o domínio de uma string.

Tipos de dados de parâmetros

STRING

Tipo de retorno

STRING

Amostras de código

Exemplo 1

Este exemplo mostra uma string vazia

strings.extract_domain("") = ""
Exemplo 2

string aleatória, não um URL

strings.extract_domain("1234") = ""
Exemplo 3

várias barras invertidas

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

Caracteres não alfabéticos tratados de maneira prática

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

processamento de URIs

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

vários caracteres antes do URL real

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

caracteres especiais no URI #

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

caracteres especiais no URL #

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

caso de teste positivo

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

strings.extract_hostname

Compatível com:
strings.extract_hostname(string)

Descrição

Extrai o nome do host de uma string. Essa função diferencia maiúsculas de minúsculas.

Tipos de dados de parâmetros

STRING

Tipo de retorno

STRING

Amostras de código

Exemplo 1

Este exemplo retorna uma string vazia.

strings.extract_hostname("") = ""
Exemplo 2

string aleatória, não um URL

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

várias barras invertidas

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

tratamento adequado de caracteres que não são do inglês

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

processamento de URIs

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

vários caracteres antes do URL real

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

caracteres especiais no URI #

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

caracteres especiais no URL #

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

strings.from_base64

Compatível com:
strings.from_base64(base64_encoded_string)

Descrição

A função converte um valor STRING codificado em base64 em um valor BYTES binário bruto. As chamadas de função com valores que não podem ser convertidos retornam um BYTES vazio por padrão.

Tipos de dados de parâmetros

STRING

Tipo de retorno

BYTES

Amostras de código

Conversão de string codificada em base64 para bytes

A função converte uma string codificada em base64 na representação de bytes binários brutos.

strings.from_base64("AAAAAG+OxVhtAm+d2sVuny/hW4oAAAAAAQAAAM0AAAA=") = b'000000006f8ec5586d026f9ddac56e9f2fe15b8a0000000001000000cd000000
Falha na conversão (padrão para bytes vazios)

A função usa bytes vazios como padrão se o valor fornecido for inválido.

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

strings.from_hex

Compatível com:
strings.from_hex(hex_string)

Descrição

Retorna os bytes associados à string hexadecimal especificada.

Tipos de dados de parâmetros

STRING

Tipo de retorno

BYTES

Amostras de código

Recebe bytes associados a uma determinada string hexadecimal.

Exemplo 1

Este exemplo mostra conversões de caracteres não hexadecimais.

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

Este exemplo mostra uma entrada com uma string vazia.

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

Este exemplo mostra a conversão de strings hexadecimais.

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

Este exemplo mostra a conversão de caracteres não ASCII.

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

strings.length

Compatível com:
strings.length(string_value)

Descrição

Retorna o número de caracteres na string de entrada.

Tipos de dados de parâmetros

STRING

Tipo de retorno

INT

Amostras de código

Exemplo 1

Confira a seguir um exemplo com um teste de string.

strings.length("str") = 3
Exemplo 2

Confira um exemplo com uma string vazia como entrada.

strings.length("") = 0
Exemplo 3

Confira um exemplo com uma string de caracteres especiais.

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

Confira a seguir um exemplo com uma string com espaços.

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

strings.ltrim

Compatível com:
strings.ltrim(string_to_trim, cutset)

Descrição

Corta os espaços em branco à esquerda de uma determinada string. Essa função remove os caracteres iniciais presentes nesse conjunto de corte.

Tipos de dados de parâmetros

STRING, STRING

Tipo de retorno

STRING

Amostras de código

Confira alguns exemplos de casos de uso.

Exemplo 1

Este exemplo usa o mesmo primeiro e segundo argumento.

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

Este exemplo usa uma string vazia como segundo argumento.

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

Este exemplo usa uma string vazia como o primeiro argumento e uma string como o segundo.

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

Este exemplo usa strings que contêm espaços em branco e uma string como o segundo argumento.

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

strings.reverse

Compatível com:
strings.reverse(STRING)

Descrição

Retorna uma string que é o inverso da string de entrada.

Tipos de dados de parâmetros

STRING

Tipo de retorno

STRING

Amostras de código

Exemplo 1

O exemplo a seguir transmite uma string curta.

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

O exemplo a seguir transmite uma string vazia.

strings.reverse("") = ""
Exemplo 3

O exemplo a seguir transmite um palíndromo.

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

strings.rtrim

Compatível com:
strings.rtrim(string_to_trim, cutset)

Descrição

Corta os espaços em branco à direita de uma determinada string. Remove os caracteres finais presentes nesse conjunto de corte.

Tipos de dados de parâmetros

STRING, STRING

Tipo de retorno

STRING

Amostras de código

Confira alguns exemplos de casos de uso.

Exemplo 1

O exemplo a seguir transmite a mesma string como o primeiro e o segundo argumento.

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

O exemplo a seguir transmite uma string vazia como o segundo argumento.

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

O exemplo a seguir transmite uma string vazia como o primeiro argumento e uma string não vazia como o segundo argumento.

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

O exemplo a seguir transmite uma string que contém espaços em branco como o primeiro argumento e uma string não vazia como o segundo argumento.

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

strings.to_lower

Compatível com:
strings.to_lower(stringText)

Descrição

Essa função usa uma string de entrada e retorna uma string depois de mudar todos os caracteres para minúsculas.

Tipos de dados de parâmetros

STRING

Tipo de retorno

STRING

Amostras de código

Exemplo 1

O exemplo a seguir retorna true.

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

strings.to_upper

Compatível com:
strings.to_upper(string_val)

Descrição

Retorna a string original com todos os caracteres alfabéticos em maiúsculas.

Tipos de dados de parâmetros

STRING

Tipo de retorno

STRING

Amostras de código

Exemplo 1

O exemplo a seguir retorna o argumento fornecido em letras maiúsculas.

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

strings.trim

Compatível com:
strings.trim(string_to_trim, cutset)

Descrição

Remove os espaços em branco à esquerda e à direita de uma determinada string. Além disso, remova caracteres indesejados (especificados pelo argumento "cutset") da string de entrada.

Tipos de dados de parâmetros

STRING, STRING

Tipo de retorno

STRING

Amostras de código

Confira alguns exemplos de casos de uso.

Exemplo 1

No exemplo a seguir, a mesma string é transmitida como a string de entrada e o conjunto de corte, o que resulta em uma string vazia.

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

No exemplo a seguir, uma string vazia é transmitida como o conjunto de corte, o que resulta na string original "str" porque não há caracteres especificados no conjunto de corte para remover.

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

No exemplo a seguir, a função gera uma string vazia porque a string de entrada já está vazia e não há caracteres para remover.

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

No exemplo a seguir, a função gera "str" porque a função "trim" remove o seguinte:

  • espaço em branco à direita em "a aastraa aa "
  • os caracteres especificados no conjunto de corte (espaço, a)
strings.trim("a aastraa aa ", " a") = "str"

strings.url_decode

Compatível com:
strings.url_decode(url_string)

Descrição

Dada uma string de URL, decodifique os caracteres de escape e processe os caracteres UTF-8 que foram codificados. Retorna uma string vazia se a decodificação falhar.

Tipos de dados de parâmetros

STRING

Tipo de retorno

STRING

Amostras de código

Exemplo 1

Este exemplo mostra um caso de teste positivo.

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

Este exemplo mostra um caso de string vazia.

strings.url_decode("") // ""
Exemplo 3

Este exemplo mostra o processamento de caracteres não alfabéticos.

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

Este exemplo mostra uma amostra de decodificação 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

Compatível com:
timestamp.as_unix_seconds(timestamp [, time_zone])

Descrição

Essa função retorna um número inteiro que representa o número de segundos após uma época Unix para a string de carimbo de data/hora especificada.

  • timestamp é uma string que representa um carimbo de data/hora de época válido. O formato precisa ser %F %T.
  • time_zone é opcional e é uma string que representa um fuso horário. Se omitido, o padrão será GMT. É possível especificar fusos horários usando literais de string. As opções são:

Confira exemplos de especificadores time_zone válidos, que podem ser transmitidos como o segundo argumento para funções de extração de tempo:

"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 dados de parâmetros

STRING, STRING

Tipo de retorno

INT

Amostras de código

Exemplo 1

Carimbo de data/hora de época válido

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

Carimbo de data/hora de época válido com o fuso horário America/New_York

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

timestamp.current_seconds

Compatível com:
timestamp.current_seconds()

Descrição

Retorna um número inteiro que representa a hora atual em segundos Unix. Isso é aproximadamente igual ao carimbo de data/hora da detecção e se baseia em quando a regra é executada. Essa função é um sinônimo da função timestamp.now().

Tipos de dados de parâmetros

NONE

Tipo de retorno

INT

Amostras de código

Exemplo 1

O exemplo a seguir retorna true se o certificado tiver expirado há mais de 24 horas. Ele calcula a diferença de tempo subtraindo os segundos Unix atuais e comparando usando um operador "maior que".

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

timestamp.get_date

Compatível com:
timestamp.get_date(unix_seconds [, time_zone])

Descrição

Essa função retorna uma string no formato YYYY-MM-DD, representando o dia em que um carimbo de data/hora está.

  • unix_seconds é um número inteiro que representa o número de segundos desde a época do Unix, como $e.metadata.event_timestamp.seconds, ou um marcador de posição que contém esse valor.
  • time_zone é opcional e é uma string que representa um time_zone. Se omitido, o padrão será "GMT". É possível especificar fusos horários usando literais de string. As opções são:
    • O nome do banco de dados de fuso horário, por exemplo, "America/Los_Angeles". Para mais informações, consulte a coluna "Nome do banco de dados de fuso horário" desta página.
    • O ajuste do fuso horário em relação ao UTC, no formato(+|-)H[H][:M[M]], por exemplo: "-08:00".

Confira exemplos de especificadores de time_zone válidos, que podem ser transmitidos como o segundo argumento para funções de extração de tempo:

"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 dados de parâmetros

INT, STRING

Tipo de retorno

STRING

Amostras de código

Exemplo 1

Neste exemplo, o argumento time_zone é omitido, então o padrão é "GMT".

$ts = $e.metadata.collected_timestamp.seconds

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

Este exemplo usa uma string literal para definir o time_zone.

$ts = $e.metadata.collected_timestamp.seconds

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

timestamp.get_minute

Compatível com:
timestamp.get_minute(unix_seconds [, time_zone])

Descrição

Essa função retorna um número inteiro no intervalo [0, 59] que representa o minuto.

  • unix_seconds é um número inteiro que representa o número de segundos desde a época do Unix, como $e.metadata.event_timestamp.seconds, ou um marcador de posição que contém esse valor.
  • time_zone é opcional e é uma string que representa um fuso horário. Se omitido, o padrão será "GMT". É possível especificar fusos horários usando literais de string. As opções são:
    • O nome do banco de dados de fuso horário, por exemplo, "America/Los_Angeles". Para mais informações, consulte a coluna "Nome do banco de dados de fuso horário" desta página.
    • O ajuste do fuso horário em relação ao UTC, no formato(+|-)H[H][:M[M]], por exemplo: "-08:00".

Confira exemplos de especificadores time_zone válidos, que podem ser transmitidos como o segundo argumento para funções de extração de tempo:

"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 dados de parâmetros

INT, STRING

Tipo de retorno

INT

Amostras de código

Exemplo 1

Neste exemplo, o argumento time_zone é omitido, então o padrão é "GMT".

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_hour($ts) = 15
Exemplo 2

Este exemplo usa uma string literal para definir o time_zone.

$ts = $e.metadata.collected_timestamp.seconds

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

timestamp.get_hour

Compatível com:
timestamp.get_hour(unix_seconds [, time_zone])

Descrição

Essa função retorna um número inteiro no intervalo [0, 23] que representa a hora.

  • unix_seconds é um número inteiro que representa o número de segundos desde a época do Unix, como $e.metadata.event_timestamp.seconds, ou um marcador de posição que contém esse valor.
  • time_zone é opcional e é uma string que representa um fuso horário. Se omitido, o padrão será "GMT". É possível especificar fusos horários usando literais de string. As opções são:
    • O nome do banco de dados de fuso horário, por exemplo, "America/Los_Angeles". Para mais informações, consulte a coluna "Nome do banco de dados de fuso horário" desta página.
    • O ajuste do fuso horário em relação ao UTC, no formato(+|-)H[H][:M[M]], por exemplo: "-08:00".

Confira exemplos de especificadores time_zone válidos, que podem ser transmitidos como o segundo argumento para funções de extração de tempo:

"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 dados de parâmetros

INT, STRING

Tipo de retorno

INT

Amostras de código

Exemplo 1

Neste exemplo, o argumento time_zone é omitido, então o padrão é "GMT".

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_hour($ts) = 15
Exemplo 2

Este exemplo usa uma string literal para definir o time_zone.

$ts = $e.metadata.collected_timestamp.seconds

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

timestamp.get_day_of_week

Compatível com:
timestamp.get_day_of_week(unix_seconds [, time_zone])

Descrição

Essa função retorna um número inteiro no intervalo [1, 7] que representa o dia da semana, começando no domingo. Por exemplo, 1 = domingo e 2 = segunda-feira.

  • unix_seconds é um número inteiro que representa o número de segundos desde a época do Unix, como $e.metadata.event_timestamp.seconds, ou um marcador de posição que contém esse valor.
  • time_zone é opcional e é uma string que representa um time_zone. Se omitido, o padrão será "GMT". É possível especificar fusos horários usando literais de string. As opções são:
    • O nome do banco de dados de fuso horário, por exemplo, "America/Los_Angeles". Para mais informações, consulte a coluna "Nome do banco de dados de fuso horário" desta página.
    • O ajuste do fuso horário em relação ao UTC, no formato(+|-)H[H][:M[M]], por exemplo: "-08:00".

Confira exemplos de especificadores de time_zone válidos, que podem ser transmitidos como o segundo argumento para funções de extração de tempo:

"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 dados de parâmetros

INT, STRING

Tipo de retorno

INT

Amostras de código

Exemplo 1

Neste exemplo, o argumento time_zone é omitido, então o padrão é "GMT".

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_day_of_week($ts) = 6
Exemplo 2

Este exemplo usa uma string literal para definir o time_zone.

$ts = $e.metadata.collected_timestamp.seconds

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

timestamp.get_timestamp

Compatível com:
timestamp.get_timestamp(unix_seconds, optional timestamp_format/time_granularity, optional timezone)

Descrição

Essa função retorna uma string no formato YYYY-MM-DD, representando o dia em que um carimbo de data/hora está.

  • unix_seconds é um número inteiro que representa o número de segundos desde a época do Unix, como $e.metadata.event_timestamp.seconds, ou um marcador de posição que contém esse valor.
  • timestamp_format é opcional e é uma string que representa o formato do carimbo de data/hora. Se omitido, o padrão é %F %T. É possível especificar o formato usando uma string de formato de data e hora ou uma das seguintes granularidades de tempo: SECOND, MINUTE, HOUR, DATE, WEEK, MONTH ou YEAR. Para mais opções de formatação, consulte Formatar elementos para partes de data e hora.
  • time_zone é opcional e é uma string que representa um fuso horário. Se omitido, o padrão será GMT. É possível especificar fusos horários usando literais de string. As opções são:

Confira exemplos de especificadores time_zone válidos, que podem ser transmitidos como o segundo argumento para funções de extração de tempo:

"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 dados de parâmetros

INT, STRING, STRING

Tipo de retorno

STRING

Amostras de código

Exemplo 1

Neste exemplo, o argumento time_zone é omitido, então o padrão é GMT.

$ts = $e.metadata.collected_timestamp.seconds

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

Este exemplo usa uma string literal para definir o time_zone.

$ts = $e.metadata.collected_timestamp.seconds

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

Este exemplo usa uma string literal para definir o timestamp_format.

$ts = $e.metadata.collected_timestamp.seconds

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

Este exemplo formata um carimbo de data/hora do Unix como uma string com granularidade de segundo.

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

Este exemplo formata um carimbo de data/hora do Unix como uma string com granularidade de minutos.

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

Este exemplo formata um carimbo de data/hora Unix como uma string com granularidade de hora.

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

Este exemplo formata um carimbo de data/hora Unix como uma string com granularidade diária.

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

Este exemplo formata um carimbo de data/hora do Unix como uma string com granularidade semanal.

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

Este exemplo formata um carimbo de data/hora Unix como uma string na granularidade mensal.

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

Este exemplo formata um carimbo de data/hora Unix como uma string na granularidade anual.

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

timestamp.get_week

Compatível com:
timestamp.get_week(unix_seconds [, time_zone])

Descrição

Essa função retorna um número inteiro no intervalo [0, 53] que representa a semana do ano. As semanas começam no domingo. As datas anteriores ao primeiro domingo do ano estão na semana 0.

  • unix_seconds é um número inteiro que representa o número de segundos desde a época do Unix, como $e.metadata.event_timestamp.seconds, ou um marcador de posição que contém esse valor.
  • time_zone é opcional e é uma string que representa um fuso horário. Se omitido, o padrão será "GMT". É possível especificar fusos horários usando literais de string. As opções são:
    • O nome do banco de dados de fuso horário, por exemplo, "America/Los_Angeles". Para mais informações, consulte a coluna "Nome do banco de dados de fuso horário" desta página.
    • O ajuste do fuso horário em relação ao UTC, no formato(+|-)H[H][:M[M]], por exemplo: "-08:00".

Confira exemplos de especificadores time_zone válidos, que podem ser transmitidos como o segundo argumento para funções de extração de tempo:

"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 dados de parâmetros

INT, STRING

Tipo de retorno

INT

Amostras de código

Exemplo 1

Neste exemplo, o argumento time_zone é omitido, então o padrão é "GMT".

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_week($ts) = 0
Exemplo 2

Este exemplo usa uma string literal para definir o time_zone.

$ts = $e.metadata.collected_timestamp.seconds

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

timestamp.now

Compatível com:
timestamp.now()

Descrição

Retorna o número de segundos desde 1970-01-01 00:00:00 UTC. Isso também é conhecido como horário da época Unix.

Tipo de retorno

INT

Amostras de código

Exemplo 1

O exemplo a seguir retorna um carimbo de data/hora para o código executado em 22 de maio de 2024 às 18:16:59.

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

window.avg

Compatível com:
window.avg(numeric_values [, should_ignore_zero_values])

Descrição

Retorna a média dos valores de entrada (que podem ser números inteiros ou de ponto flutuante). Definir o segundo argumento opcional como "true" ignora os valores zero.

Tipos de dados de parâmetros

INT|FLOAT

Tipo de retorno

FLOAT

Amostras de código

Exemplo 1

Este exemplo mostra a média de números inteiros.

// 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
Exemplo 2

Este exemplo mostra a média de ponto flutuante.

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
Exemplo 3

Média de entrada negativa

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
Exemplo 4

0 retorna 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
Example 5

Ignorando 0 valores

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

Compatível com:
window.first(values_to_sort_by, values_to_return)

Descrição

Essa função de agregação retorna um valor de string derivado de um evento com o menor valor inteiro correlacionado na janela de correspondência. Um exemplo de caso de uso é extrair o user_id do evento com o carimbo de data/hora mais antigo na janela de correspondência.

Tipos de dados de parâmetros

INT, STRING

Tipo de retorno

STRING

Amostras de código

Recebe um valor de string derivado de um evento com o menor valor inteiro correlacionado na janela de correspondência.

// 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

Compatível com:
window.last(values_to_sort_by, values_to_return)

Descrição

Essa função de agregação retorna um valor de string derivado de um evento com o maior valor int correlacionado na janela de correspondência. Um exemplo de caso de uso é receber o userid do evento com o carimbo de data/hora mais baixo na janela de correspondência (carimbo de data/hora mais alto).

Tipos de dados de parâmetros

INT, STRING

Tipo de retorno

STRING

Amostras de código

Recebe um valor de string derivado de um evento com o maior valor inteiro correlacionado na janela de correspondência.

// 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

Compatível com:
window.median(numeric_values, should_ignore_zero_values)

Descrição

Retorna a mediana dos valores de entrada. Se houver dois valores medianos, apenas um será escolhido de forma não determinística como o valor de retorno.

Tipos de dados de parâmetros

INT|FLOAT, BOOL

Tipo de retorno

FLOAT

Amostras de código

Exemplo 1

Este exemplo retorna a mediana quando os valores de entrada não são zero.

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
}
Exemplo 2

Este exemplo retorna a mediana quando a entrada inclui alguns valores zero que não devem ser ignorados.

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
}
Exemplo 3

Este exemplo retorna a mediana quando a entrada inclui alguns valores zero que devem ser ignorados.

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
}
Exemplo 4

Este exemplo retorna a mediana quando a entrada inclui todos os valores zero que devem ser ignorados.

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
}
Example 5

Este exemplo mostra que, quando há várias medianas, apenas uma é retornada.

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

Compatível com:
window.mode(values)

Descrição

Retorna a moda dos valores de entrada. Se houver vários valores de modo possíveis, apenas um deles será escolhido de forma não determinística como o valor de retorno.

Tipos de dados de parâmetros

INT|FLOAT|STRING

Tipo de retorno

STRING

Amostras de código

Exemplo 1

Recebe o modo dos valores na janela de correspondência.

// 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

Compatível com:
window.stddev(numeric_values)

Descrição

Retorna o desvio padrão dos valores de entrada em uma janela de correspondência.

Tipos de dados de parâmetros

INT|FLOAT

Tipo de retorno

FLOAT

Amostras de código

Exemplo 1

Este exemplo retorna o desvio padrão de números inteiros em uma janela de correspondência.

// 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
Exemplo 2

Este exemplo retorna o desvio padrão de números de ponto flutuante em uma janela de correspondência.

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
Exemplo 3

Este exemplo retorna o desvio padrão em uma janela de correspondência que contém 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
Exemplo 4

Este exemplo retorna com desvio padrão zero quando todos os valores na janela de correspondência são iguais.

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
Example 5

Este exemplo retorna o desvio padrão de uma janela de correspondência que contém números positivos e 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

Compatível com:
window.variance(values)

Descrição

Essa função retorna a variância especificada dos valores de entrada.

Tipos de dados de parâmetros

INT|FLOAT

Tipo de retorno

FLOAT

Amostras de código

Exemplo 1

Este exemplo retorna a variância de todos os números inteiros.

// 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
Exemplo 2

Este exemplo retorna a variância de todos os números de ponto flutuante.

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
Exemplo 3

Este exemplo retorna a variância de 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
Exemplo 4

Este exemplo retorna um valor de variância pequeno.

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
Example 5

Este exemplo retorna uma variância zero.

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
Exemplo 6

Este exemplo retorna a variância de números positivos e 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

Compatível com:
bytes.to_base64(bytes, optional_default_string)

Descrição

A função converte um valor bytes em um base64 encoded string. As chamadas de função com valores que não podem ser convertidos retornam uma string vazia por padrão.

Tipos de dados de parâmetros

BYTES, STRING

Tipo de retorno

STRING

Amostras de código

Bytes binários brutos para string codificada em base64

A função converte os bytes binários brutos em uma string codificada em base64.

bytes.to_base64(b'000000006f8ec5586d026f9ddac56e9f2fe15b8a0000000001000000cd000000) = "AAAAAG+OxVhtAm+d2sVuny/hW4oAAAAAAQAAAM0AAAA="
Falha na conversão (o padrão é a string fornecida opcionalmente)

A função usa o valor padrão "invalid bytes" quando o valor de bytes fornecido não é válido.

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

Função para atribuição de marcador de posição

Você pode atribuir o resultado de uma chamada de função a um marcador de posição na seção events. Exemplo:

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

Depois, use as variáveis de marcador de posição nas seções match, condition e outcome. No entanto, há duas limitações na atribuição de função a marcador de posição:

  1. Cada marcador de posição na atribuição de função a marcador de posição precisa ser atribuído a uma expressão que contenha um campo de evento. Por exemplo, os seguintes exemplos são 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)

    No entanto, o exemplo a seguir é invá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. A chamada de função precisa depender de um e exatamente um evento. No entanto, mais de um campo do mesmo evento pode ser usado em argumentos de chamada de função. Por exemplo, o seguinte é válido:

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

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

    No entanto, o seguinte é inválido:

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

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

Sintaxe das listas de referências

Consulte nossa página sobre listas de referência para mais informações sobre o comportamento e a sintaxe delas.

É possível usar listas de referência nas seções events ou outcome. Esta é a sintaxe para usar vários tipos de listas de referência em uma regra:

// 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

Também é possível usar os operadores not e nocase com listas de referência, conforme mostrado no exemplo a seguir:

// 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

O operador nocase é compatível com listas STRING e REGEX.

Por motivos de desempenho, o Detection Engine restringe o uso de listas de referência.

  • Número máximo de instruções in em uma regra, com ou sem operadores especiais: 7
  • Número máximo de instruções in com o operador regex: 4
  • Número máximo de instruções in com o operador cidr: 2

Verificação de tipo

O Google SecOps realiza a verificação de tipos na sua sintaxe YARA-L enquanto você cria regras na interface. Os erros de verificação de tipo mostrados ajudam a revisar a regra para verificar se ela vai funcionar conforme o esperado.

Confira a seguir exemplos de predicados invá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"

Amostragem de eventos de detecção

As detecções de regras de vários eventos contêm amostras de eventos para fornecer contexto sobre os eventos que causaram a detecção. Há um limite de até 10 amostras de evento para cada variável definida na regra. Por exemplo, se uma regra definir duas variáveis de evento, cada detecção poderá ter até 20 amostras de evento. O limite se aplica a cada variável de evento separadamente. Se uma variável de evento tiver dois eventos aplicáveis nessa detecção e a outra tiver 15, a detecção resultante vai conter 12 amostras de eventos (2 + 10).

Todas as amostras de eventos acima do limite são omitidas da detecção.

Se quiser mais informações sobre os eventos que causaram a detecção, use agregações na seção de resultado para gerar informações adicionais na detecção.

Se você estiver visualizando detecções na UI, poderá baixar todas as amostras de eventos de uma detecção. Para mais informações, consulte Fazer o download de eventos.

Precisa de mais ajuda? Receba respostas de membros da comunidade e profissionais do Google SecOps.