Sintaxe da linguagem YARA-L 2.0

Compatível com:

Google SecOps SIEM

Esta seção descreve os principais elementos da sintaxe YARA-L. Consulte também Informações gerais da linguagem YARA-L 2.0.

Estrutura da regra

Para o YARA-L 2.0, é necessário especificar declarações, definições e usos de variáveis na seguinte ordem:

1. meta
2. eventos
3. correspondência (opcional)
4. resultado (opcional)
5. transição
6. opções (opcional)

Observação: se você não incluir a seção opcional match, a regra poderá corresponder a um único evento.

Confira a seguir 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 meta

A seção "meta" é composta por várias linhas, em que cada linha 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 abaixo um exemplo de linha de seção meta válida:

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

Sintaxe da seção de eventos

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

• Declarações de variáveis
• Filtros de variáveis de eventos
• 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>

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

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

Essa declaração indica que essa 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 uniã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 eventos

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 combinadas com todas as outras variáveis de evento de uma das seguintes maneiras:

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

• Indiretamente, por uma união transitiva que envolve apenas um campo de evento. Consulte a declaração de variável para ver a definição de "uniã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

Observação: se a única condição de mesclagem for uma cadeia or, uma função para comparação de eventos ou uma combinação de ambos, a regra pode ter um desempenho ruim.

No entanto, confira abaixo 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 em 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 o período a ser usado para correlacionar eventos após a palavra-chave over. Os eventos fora do período 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 5 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 intervalo não são correlacionados. A regra não considera isso como 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 considera isso como 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 valor zero na seção de correspondência

O Rules Engine filtra implicitamente os valores zero de 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 nulos.

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 nulos dos marcadores de posição usados na seção de correspondência. O exemplo a seguir ilustra regras que filtram os valores nulos:

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 nulos, use a opção allow_zero_values na seção de opções.

Janela de salto

Por padrão, as regras do 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. Os eventos são correlacionados dentro de cada janela de salto.

Por exemplo, para uma regra executada no período [1:00, 2:00], com uma seção match sobre 30m, um conjunto possível 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é dois minutos após 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. As janelas deslizantes com a duração especificada na seção match são geradas ao começar ou terminar com uma variável de evento de pivote especificada. Os eventos são correlacionados em cada janela deslizante. Isso permite pesquisar eventos que acontecem em uma ordem específica (por exemplo, e1 ocorre 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 principal é a variável de evento na qual 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 a partir de cada ocorrência do evento principal.

Confira abaixo exemplos de usos válidos de janelas deslizantes:

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

Consulte um exemplo de regra de janela deslizante.

Observação: o uso de janelas deslizantes em vez de janelas de salto resulta em performance mais lenta. O Google recomenda usar janelas deslizantes apenas para casos específicos, como quando a ordem de eventos é absolutamente necessária ou quando procura a não existência de eventos.

O Google recomenda não usar janelas deslizantes para regras de eventos únicos, porque elas são projetadas para detectar vários eventos. Se uma das suas regras se enquadrar nessa categoria, o Google recomenda 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.
  • Opcionalmente, considere adicionar 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 resultados

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, e, se fizer isso, ele precisa ser do tipo inteiro ou float. Se preenchido, o risk_score vai aparecer na visualização de insights da empresa para alertas provenientes 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 valores padrão a seguir 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 UDM security_result.risk_score.

Tipos de dados de variáveis de resultado

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

• integer
• flutua
• string
• listas de números inteiros
• listas de flutuações
• listas de strings

Lógica condicional

Você pode 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 avaliado como um valor booleano. Uma expressão BOOL_CLAUSE tem um formato semelhante às expressões na seção events. Por exemplo, ele pode conter:

• Nomes de campo do 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)

• procure 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 ter o mesmo tipo de dados. Oferecemos suporte a números inteiros, de ponto flutuante e strings.

Você pode omitir a cláusula ELSE_CLAUSE se o tipo de dados for inteiro ou decimal. Se omitido, a ELSE_CLAUSE é avaliada como 0. Exemplo:

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

Você precisa fornecer a cláusula ELSE_CLAUSE se o tipo de dados for string ou se a cláusula 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 o tipo de dados inteiro ou flutuante nas seções outcome e events de uma regra. O Google Security Operations oferece suporte a adição, subtração, multiplicação, divisão e módulo como operadores de nível superior em uma computação.

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 eventos numéricos
• Variáveis de marcador de posição numéricas definidas na seção events
• Variáveis numéricas de resultado 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 flutuantes.

Variáveis de marcador de posição nos resultados

Ao calcular variáveis de resultado, você pode usar variáveis de marcador de posição que foram 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, de forma semelhante à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 abaixo, a variável de resultado $risk_score deriva o valor 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

Os campos de evento repetidos são valores não 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. Ele é um valor não escalar. Já a variável de campo do 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 eventos não repetidos e os campos de eventos repetidos usados na seção de resultados 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 muitos eventos. A seção de resultado opera em todos os eventos em uma janela de correspondência. Qualquer variável de campo de evento mencionada na seção de resultados pode apontar para zero, um ou vários valores do campo em cada evento na janela de correspondência. Na regra anterior, se uma janela de cinco minutos tiver cinco 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 é, portanto, um valor não escalar na seção de resultados desta regra.

Como as variáveis de resultado sempre precisam gerar um único valor escalar, qualquer valor não escalar em que uma atribuição de resultado depende 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
• Marcadores de posição de evento (repetidos ou não) quando a regra usa uma seção de correspondência
• Campos de evento repetidos quando a regra não usa uma seção de correspondência
• Marcadores de posição de evento repetidos quando a regra não usa uma seção de correspondência

Os campos de evento escalar, os marcadores de posição de evento escalar e as constantes podem ser agrupados em uma agregação em uma regra que não usa uma seção de correspondência. No entanto, a maioria das agregações vai gerar o valor encapsulado e, portanto, é desnecessária. A exceção é a agregação array(), que pode ser usada para converter um valor escalar em uma matriz.

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

Você pode usar as seguintes funções de agregação:

• max(): gera o valor máximo de todos os valores possíveis. Só funciona com números inteiros e de ponto flutuante.
• min(): gera o mínimo de 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 de valores possíveis.
• 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 desses valores. Ele trunca a lista de valores distintos para 25 elementos aleatórios. A eliminação de duplicação para conseguir uma lista distinta é aplicada primeiro, depois o truncamento.
• array(): se comporta como array_distinct(), mas retorna uma lista não distinta de valores. Ele também trunca a lista de valores para 25 elementos aleatórios.
• period_start_for_max(): início do período em que o valor máximo do item ocorreu.
• period_start_for_min(): início do período em que o valor mínimo da lista ocorreu.

A função de agregação é importante quando uma regra inclui uma seção condition que especifica que vários eventos precisam existir, porque a função de agregação vai operar 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 agregadas vão operar em vários eventos. Suponha que os eventos a seguir tenham gerado 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"

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 de resultados:

Outras observações e restrições:

• A seção outcome não pode referenciar uma nova variável de marcador de posição que ainda não foi definida na seção events ou na seção 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, já que a variável de evento à qual o campo de evento pertence já foi definida na seção events.
• A seção outcome só pode correlacionar variáveis de eventos que já foram correlacionadas na seção events. As correlações ocorrem quando dois campos de eventos de variáveis de eventos 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 com base no contexto para saber mais sobre a eliminaçã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 Eventos e condicionais de 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 Condições de resultado para mais detalhes.

Caractere de contagem

O caractere # é um caractere especial na seção condition. Se for usado antes de qualquer evento ou nome de variável de marcador de posição, ele vai 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 $ é um caractere especial na seção condition. Se for usado antes de qualquer nome de variável de resultado, ele vai representar o valor desse resultado.

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

Condicionais de evento e marcador de posição

Liste os predicados de condição para eventos e variáveis de marcador de posição aqui, unidos à palavra-chave and ou or. A palavra-chave and pode ser usada entre qualquer condição, mas a palavra-chave or só pode ser usada quando a regra tem apenas uma variável de evento.

Exemplo válido de uso de or entre dois marcadores 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.
}

Observação: não use a palavra-chave not em eventos e condicionais de marcador de posição.

Condições limitadas e ilimitadas

As condições a seguir são condições limitadas. Elas forçam a variável de evento associada a existir, 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 condições 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 que qualquer referência a campos na variável de evento gere um valor zero. Condições ilimitadas podem ser usadas para detectar a ausência de um evento em 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

Observação: para regras de inexistência, o mecanismo de detecção adiciona um atraso de uma hora à latência esperada (com base na frequência de execução da regra) para permitir dados que chegam com atraso.

Requisitos para não existência

Para que uma regra com inexistência seja compilada, ela precisa atender aos seguintes requisitos:

1. Pelo menos um evento do UDM precisa ter uma condição delimitada, ou seja, pelo menos um evento do UDM precisa existir.
2. Se um marcador de posição tiver uma condição ilimitada, ele precisará ser associado a pelo menos um evento UDM limitado.
3. Se uma entidade tiver uma condição ilimitada, ela precisará ser associada a pelo menos um evento UDM limitado.

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 abaixo exemplos válidos de <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
  • $e2 é ilimitado, o que é permitido porque está associado a $u1, que é limitado. Se $e2 não for associado a $u1, isso será inválido.
• #port > 50 and #ip = 0
  • Não há eventos e entidades do UDM na seção de condição. No entanto, os marcadores de posição presentes abrangem todos os eventos e entidades do UDM.
  • $ip é atribuído a $u1 e $u2, e #ip = 0 é uma condição ilimitada. 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 delimitada, $u1 ainda está limitado.

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

• $u1 and $e1
  • Todos os eventos e entidades da UDM que aparecem na seção "Eventos" precisam aparecer na seção "Condição" ou ter um marcador de posição atribuído que apareça na seção "Condição".
• $u1, $u2, $e1, $u2, #port > 50
  • Não é permitido usar vírgulas como separadores de condições.
• !$u1 and !$u2 and $e1 and $e2
  • Viola o primeiro requisito de que pelo menos um evento do UDM seja limitado.
• ($u1 or #port < 50) and $u2 and $e1 and $e2
  • A palavra-chave or não é compatível com condições ilimitadas.
• ($u1 or $u2) and $e1 and $e2
  • A palavra-chave or não é compatível com 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 abrangem todos os eventos e entidades do UDM. No entanto, todas as condições são ilimitadas. Isso significa que nenhum dos eventos da UDM é limitado, fazendo com que a regra não seja compilada.

Observação: não use uma variável match na seção condition. É um erro semântico, já que os eventos são agrupados pelo valor da variável match.

Observação: não especifique apenas condições ilimitadas em todas as variáveis event a que uma variável match é atribuída. É um erro semântico. Para que um valor de variável match seja retornado, é necessário que pelo menos um evento contenha o valor.

Observação: no caso de uso de uma janela deslizante, a variável de evento principal precisa estar envolvida em pelo menos uma condição delimitada.

Condicionais de resultado

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

Especifique as condições de resultado de maneira diferente, dependendo do tipo da variável de resultado:

• integer: compare com um literal inteiro com 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 com = 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")

Observação: se você usar a palavra-chave or dentro da subseção <event/placeholder conditionals>, é necessário colocar toda a subseção entre parênteses. Por exemplo, o seguinte é válido: ($e1 or $e2) and $outcome > 0.

Classificação da regra

Especificar uma condição de resultado em uma regra que tenha uma seção de correspondência significa que a regra será classificada como multievento para a cota de regras. Consulte regra de evento único e regra de eventos múltiplos 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 essa opção está ativada ou não. O valor padrão é false. Essa opção é 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 impede que a regra filtre implicitamente os valores nulos dos marcadores de posição usados na seção de correspondência, conforme descrito em Processamento de valores nulos na seção de correspondência.

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")
• "[e-mail]" = re.replace($e.network.email.from, "com", "org")

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

remotas

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

Você pode 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 ao mais baixo é not, and e or.

Por exemplo, "a ou b e c" é avaliado como "a ou (b e 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 explicitamente definido.

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 é 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 em torno de or são agrupados e avaliados primeiro. O último predicado, $e2.field = "bar", é combinado implicitamente usando and. O resultado é que a ordem de avaliação muda.

Observação: há um limite para o número de valores and e or que podem ser especificados para uma única regra. Esse limite varia de acordo com a complexidade da regra e dos dados na sua conta do Google Security Operations. Entre em contato com seu representante do Google Security Operations para saber mais sobre alternativas a esse tipo de regra.

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 abaixo, "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 anexar nocase ao final da expressão para ignorar a diferenciação entre 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 é possível usar esse recurso 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, na sigla em inglês), 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 um

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

• event_original atende a 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 atenderá à condição.

• event_original atende a 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".

Observação: para usar any ou all com uma função, o modificador precisa preceder o campo repetido, e não a função. Por exemplo, re.regex(any $e.about.hostname, `server-[0-9]+`) é válido, mas any re.regex($e.about.hostname, `server-[0-9]+`) não é.

Ao escrever uma condição com any ou all, lembre-se de 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, ou seja, a regra está verificando 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, o que significa que a regra está verificando 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 com campos escalares.
• any e all não podem ser usados para mesclar 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 em 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:

texto 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 regras 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 expressões não modificadas em campos repetidos 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:

texto do evento	principal.ip	qualquer $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 seria igual.

Outra maneira de pensar sobre esses tipos de expressão é:

• 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 em 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. 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 evento de correspondência 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 event_copy_n. O agrupamento é feito em $ip, porque ele está na seção de correspondência. Portanto, você recebe três correspondências, em que cada uma tem 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
}

Observação: any e all não podem ser usados ao atribuir um campo repetido a uma variável de marcador de posição ou ao unir com um campo de outro evento. Por exemplo, any $e.principal.ip = $ip não é válido.

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 a lista inteira. Assim, quando eles são usados na seção de resultados, o resultado é calculado usando apenas os elementos que atenderam às 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 etapas de execução para essa regra. A primeira etapa é a cópia de eventos:

texto 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:

texto 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 atende a $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 realizar 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 $ip da etapa anterior, e não da etapa de cópia de eventos.

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

$o não contém todos os elementos de $e.principal.ip porque nem todos os elementos atenderam a todas as condições na seção de 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 a indexação de matriz em campos repetidos. Para acessar o enésimo elemento de campo repetido, use a sintaxe de lista padrão (os elementos são indexados a partir de 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, o resultado será true.

Restrições:

• Um índice precisa ser um literal inteiro não negativo. Por exemplo, $e.principal.ip[-1] não é válido.
• Valores com um tipo int (por exemplo, um marcador de posição definido como int) não são contabilizados.
• O índice de matrizes não pode ser combinado com any ou all. Por exemplo, any $e.intermediary.ip[0] não é válido.
• O índice de matrizes não pode ser combinado com a sintaxe de mapa. Por exemplo, $e.additional.fields[0]["key"] não é válido.
• Se o caminho do campo tiver 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"
  }
}

Conforme declarado 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:

texto 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 de evento que satisfaça todas as expressões.

Mensagens repetidas e indexação de matrizes

Outro comportamento inesperado pode ocorrer ao usar a indexação de matriz com expressões não modificadas em campos de mensagens repetidas. Considere o exemplo de regra a seguir, 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:

texto 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 atende a 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 a indexação de matriz e produziu uma correspondência.

Comentários

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

Literais

Números inteiros e flutuantes não negativos, strings, booleanos e literais de expressão regular são aceitos.

Literais de string e expressão regular

É possível usar qualquer um dos seguintes caracteres de aspas para encerrar strings no YARA-L 2.0. No entanto, o texto citado é interpretado de maneira diferente dependendo do que você usa.

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

2. Aspas simples retas (`) — use 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 com 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 o uso de caracteres de aspas simples para strings em expressões regulares para facilitar a leitura.

Operadores

É possível usar os seguintes operadores no 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 em forma normalizada (UDM) ou eventos de entidade. Especifique condições para variáveis de evento na seção events. Identifique as variáveis usando um nome, a origem e os campos do 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 período). Quando a regra encontra uma correspondência, os valores da variável 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.

Observação: todas as variáveis de marcador de posição precisam ser mapeadas para um campo de evento. Por exemplo, se você apenas referenciar o marcador de posição a seguir nesta única linha em uma regra, a compilação vai falhar, porque $var não está vinculado a uma variável de evento: $e.field != $var

Use variáveis de correspondência e de marcador de posição para declarar relações entre campos de eventos por meio de condições de mesclagem transitiva. Consulte a Sintaxe da seção de eventos para mais detalhes.

Palavras-chave

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

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

O YARA-L oferece suporte ao acesso de mapas para structs e rótulos.

Estruturas e rótulos

Alguns campos do 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 com suporte

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 de posição

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

Como usar um campo de mapa em uma condição de mesclagem

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

Não há suporte para mapas 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 do map só pode retornar um valor de string. No caso de tipos de dados Struct, a sintaxe do mapa só pode acessar chaves cujos valores são strings. Não é possível acessar chaves com valores de outros tipos primitivos, como números inteiros.

Processamento de valores duplicados

As acessos ao mapa sempre retornam um único valor. No caso raro em que o acesso ao mapa pode se referir a vários valores, o acesso ao mapa vai retornar de forma determinística o primeiro valor.

Isso pode acontecer nos seguintes casos:

• Um rótulo tem uma chave duplicada.

  A estrutura de rótulos representa um mapa, mas não impõe a exclusividade da chave. Por convenção, um mapa precisa ter chaves exclusivas. Por isso, o Google Security Operations 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 fosse executado no seguinte exemplo de dados:

  // 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"] retorna o primeiro valor possível, val3, se for executado no seguinte exemplo de dados:

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

remotas

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

Observação: o uso da variável de evento $e é opcional quando o YARA-L é usado na pesquisa. principal.hostname e $e.principal.hostname são aceitos na pesquisa.

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

• Seção events
• BOOL_CLAUSE de uma condicional na seção de resultados

arrays.concat

Compatível com:

Regras Pesquisa

arrays.concat(string_array, string_array)

Descrição

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

Tipos de dados de parâmetro

ARRAY_STRINGS, ARRAY_STRINGS

Tipo de retorno

ARRAY_STRINGS

Amostras de código

Exemplo 1

O exemplo a seguir concatena duas matrizes de string diferentes.

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

Exemplo 2

O exemplo a seguir concatena matrizes com string vazia.

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

Exemplo 3

O exemplo a seguir concatena matrizes vazias.

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

arrays.join_string

Compatível com:

Regras Pesquisa

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âmetro

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:

Regras Pesquisa

arrays.length(repeatedField)

Descrição

Retorna o número de elementos de campo repetidos.

Tipos de dados de parâmetro

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 no caminho, o número total de elementos de campo repetidos será retornado.

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

arrays.max

Compatível com:

Regras Pesquisa

arrays.max(array_of_ints_or_floats)

Descrição

Retorna o maior elemento de uma matriz ou zero se ela estiver vazia.

Tipos de dados de parâmetro

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 maior elemento em uma matriz de números inteiros.

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

Exemplo 2

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

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

arrays.min

Compatível com:

Regras Pesquisa

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

Descrição

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

Tipos de dados de parâmetro

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

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

Exemplo 3

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

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

arrays.size

Compatível com:

Regras Pesquisa

arrays.size( array )

Descrição

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

Tipos de dados de parâmetro

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 int 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 1 elemento

arrays.size([1.200000]) = 1

Exemplo 4

Este exemplo usa uma matriz vazia.

arrays.size([]) = 0

arrays.index_to_float

Compatível com:

Regras Pesquisa

arrays.index_to_float(array, index)

Descrição

Retorna o elemento no índice especificado de uma matriz. O elemento nesse índice é retornado como um número 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 da matriz.

Tipos de dados de parâmetro

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

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

arrays.index_to_float([1.2, 2.1, 3.5, 4.6], -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:

Regras Pesquisa

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 da matriz.

Tipos de dados de parâmetro

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"], -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 int no índice 0.

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

arrays.index_to_str

Compatível com:

Regras Pesquisa

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. A indexação negativa permite acessar elementos da matriz do final da matriz. Por exemplo, um índice de -1 se refere ao último elemento da matriz, e um índice de -2 se refere ao penúltimo elemento da matriz.

Tipos de dados de parâmetro

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"], -1) // "test4"

Exemplo 3

O exemplo a seguir busca um elemento para um índice maior que o tamanho da matriz, 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 flutuantes. 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á na forma de uma string.

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

cast.as_bool

Compatível com:

Regras Pesquisa

cast.as_bool(string_or_int)

Descrição

A função converte um valor de int ou string em um valor booleano. As chamadas de função com valores que não podem ser convertidos retornam FALSO. Retorna TRUE apenas para o número inteiro 1 e a string 'true', que não diferencia maiúsculas de minúsculas.

Tipos de dados de parâmetro

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 de verdade com letra maiúscula

cast.as_bool("TRUE") = true

Example 5

Número inteiro negativo

cast.as_bool(-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:

Regras Pesquisa

cast.as_float(string_to_cast)

Descrição

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

Tipos de dados de parâmetro

STRING

Tipo de retorno

FLOAT

Amostras de código

Exemplo 1

O casting de uma string não numérica retorna 0.

cast.as_float("str") = 0.0000000

Exemplo 2

O casting 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

Impressão digital

Compatível com:

Regras

hash.fingerprint2011(byteOrString)

Descrição

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

Observação: essa função não deve ser usada como um hash criptograficamente seguro.

Tipos de dados de parâmetro

BTYE, STRING

Tipo de retorno

INT

Exemplo de código

id_fingerprint = hash.fingerprint2011("user123")

grupo

Compatível com:

Pesquisar

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 de grupo é semelhante aos campos agrupados, exceto pelo fato de permitir que você selecione quais campos quer agrupar para acionar uma detecção. É possível usar 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 do usuário) em diferentes tipos de substantivos.

Observação: para a pesquisa, é possível usar campos agrupados na seção de eventos, mas não nas seções de correspondência e resultado.

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 de tempo 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:

Regras

hash.sha256(string)

Descrição

Retorna um hash SHA-256 da string de entrada.

Tipos de dados de parâmetro

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:

Regras Pesquisa

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âmetro

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 a hora especificada (em segundos desde a época Unix), independentemente de o evento 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 fixado em 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:

Regras Pesquisa

math.ceil(number)

Descrição

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

Tipos de dados de parâmetro

FLOAT

Tipo de retorno

INT

Amostras de código

Esta seção contém exemplos de como usar 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(-1.200000) = -1

Exemplo 3

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

math.ceil(184467440737095516160.0) = 0

math.floor

Compatível com:

Regras Pesquisa

math.floor(float_val)

Descrição

Retorna o maior valor inteiro que não seja 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âmetro

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(-1.234568) = -2

Exemplo 3

Este exemplo mostra um caso de zero.

math.floor(0.000000) = 0

math.geo_distance

Compatível com:

Regras

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

Descrição

Retorna a distância entre dois geolocalizadores (coordenadas). Retorna -1 se a geocoordenadas for inválida.

Tipos de dados de parâmetro

FLOAT, FLOAT, FLOAT, FLOAT

Tipo de retorno

FLOAT

Amostras de código

Exemplo 1

Este exemplo 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

Este exemplo 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

Este exemplo retorna -1 quando um dos parâmetros é uma coordenada inválida.

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

Exemplo 4

Este exemplo 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:

Regras Pesquisa

math.is_increasing(num1, num2, num3)

Descrição

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

Tipos de dados de parâmetro

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 duplo negativo, um INT64 zero e um INT64 positivo.

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

Exemplo 3

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

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

Exemplo 4

Este exemplo inclui dois números duplos negativos e um valor INT64 zero.

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

Example 5

Este exemplo inclui um número duplo negativo e dois valores iguais.

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

math.log

Compatível com:

Regras Pesquisa

math.log(numericExpression)

Descrição

Retorna o valor do logaritmo natural de uma expressão inteira ou flutuante.

Tipos de dados de parâmetro

NUMBER

Tipo de retorno

NUMBER

Amostras de código

Exemplo 1

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

math.pow

Compatível com:

Regras Pesquisa

math.pow(base, exponent)

Descrição

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

Tipos de dados de parâmetro

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 de fração de base.

math.pow(2.200000, 3) // 10.648

Exemplo 3

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

math.pow(2.200000, 1.200000) // 2.575771

Exemplo 4

Este exemplo mostra um caso de energia negativa.

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

Example 5

Este exemplo mostra um caso de potência fracionada.

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

Exemplo 6

Este exemplo mostra um caso de base negativo.

math.pow(-3, -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 zero energia.

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:

Regras Pesquisa

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:

Pesquisar

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âmetro

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(-10.7) // returns -11
math.round(-1.2) // returns -1
math.round(4) // returns 4, math.round(integer) returns the integer

math.sqrt

Compatível com:

Regras Pesquisa

math.sqrt(number)

Descrição

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

Tipos de dados de parâmetro

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

Esse exemplo retorna a raiz quadrada de um argumento do tipo float.

math.sqrt(9.223372) = 3.037000

Example 5

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

math.sqrt(-1.200000) = 0.000000

métricas

Compatível com:

Regras

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

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

net.ip_in_range_cidr

Compatível com:

Regras Pesquisa

net.ip_in_range_cidr(ipAddress, subnetworkRange)

Descrição

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

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

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

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

Tipos de dados de parâmetro

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 conferir um exemplo de regra que usa a instrução net.ip_in_range_cidr(), consulte o exemplo de regra em Um evento no intervalo de endereços IP.

re.regex

Compatível com:

Regras Pesquisa

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

• Usar a sintaxe YARA-L: relacionado 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 corresponde à expressão regular fornecida. Não é necessário adicionar .* no início ou no final da expressão regular.

Observações

• Para corresponder à string exata ou apenas a um prefixo ou sufixo, inclua os caracteres de âncora ^ (início) e $ (fim) 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 da UDM. Para aplicar a correspondência completa de campos do UDM, adicione um (?s) à expressão regular. Por exemplo, substitua /.*allUDM.*/ por /(?s).*allUDM.*/.
• É possível usar o modificador nocase após strings para indicar que a pesquisa precisa ignorar a diferenciação entre maiúsculas e minúsculas.

Tipos de dados de parâmetro

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:

Regras Pesquisa

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 grupos de captura entre parênteses. Se a expressão regular contiver 0 grupos de captura, a função vai retornar a primeira substring correspondente. Se a expressão regular contiver um grupo de captura, ela vai retornar a primeira substring correspondente para o grupo de captura. A definição de dois ou mais grupos de captura retorna um erro do compilador.

Tipos de dados de parâmetro

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 [e-mail], 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. É possível omitir eventos em que não há correspondência excluindo a string vazia, o que é especialmente importante quando você está usando 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:

Regras Pesquisa

re.replace(stringText, replaceRegex, replacementText)

Descrição

Realiza 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 do 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) no 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 as 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âmetro

STRING, STRING, STRING

Tipo de retorno

STRING

Amostras de código

Exemplo 1

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

"[e-mail]" = re.replace($e.network.email.from, "com", "org")

Exemplo 2

Este exemplo usa dígitos 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:

Regras

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 precisa 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âmetro

• 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:

Regras Pesquisa

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âmetro

STRING

Tipo de retorno

STRING

Amostras de código

Exemplo 1

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

strings.coalesce

Compatível com:

Regras Pesquisa

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

Descrição

Essa função recebe um número ilimitado de argumentos e retorna o valor da primeira expressão que não é avaliado 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âmetro

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 é [e-mail] ou (2) $e.network.email.from está vazio e $e.network.email.to é [e-mail].

"[e-mail]" = 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 nesta chamada é a mesma em que eles são enumerados na condição da regra:

1. $e.principal.ip é avaliado primeiro.
2. $e.src.ip é avaliado em seguida.
3. $e.target.ip é avaliado em seguida.
4. Por fim, a string "No IP" é 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 mesclar 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:

Regras Pesquisa

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

Descrição

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

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

Tipos de dados de parâmetro

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 flutuantes que são números inteiros são formatados sem o ponto decimal (por exemplo, 1,0 é representado como "1"). Além disso, os números flutuantes que excedem 16 dígitos decimais são truncados para a décima sexta 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:

Regras Pesquisa

strings.contains( str, substr )

Descrição

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

Tipos de dados de parâmetro

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:

Regras Pesquisa

strings.count_substrings(string_to_search_in, substring_to_count)

Descrição

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

Tipos de dados de parâmetro

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 caractere de substring única não nula.

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 maior que 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 maior que um caractere.

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

Example 5

Este exemplo usa uma string vazia e uma substring vazia.

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 substring sobrepostas.

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

strings.extract_domain

Compatível com:

Regras Pesquisa

strings.extract_domain(url_string)

Descrição

Extrai o domínio de uma string.

Observação: a função não realiza a normalização Unicode.

Observação: os dados de sufixo público em publicsuffix.org também contêm domínios privados. Essa função não trata um domínio privado como um sufixo público. Por exemplo, se "us.com" for um domínio particular nos dados do sufixo público, "foo.us.com" vai retornar "us.com" (o sufixo público "com" mais o rótulo anterior "us") em vez de "foo.us.com" (o domínio particular "us.com" mais o rótulo anterior "foo").

Observação: os dados do sufixo público podem mudar com o tempo. Por conseguinte, a entrada que produz um valor vazio padrão agora pode produzir um valor não vazio no futuro.

Tipos de dados de parâmetro

STRING

Tipo de retorno

STRING

Amostras de código

Exemplo 1

Este exemplo mostra uma string vazia

strings.extract_domain("") = ""

Exemplo 2

string aleatório, não um URL

strings.extract_domain("1234") = ""

Exemplo 3

várias voltas para trás

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

Exemplo 4

caracteres não alfabéticos são processados corretamente

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:

Regras Pesquisa

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âmetro

STRING

Tipo de retorno

STRING

Amostras de código

Exemplo 1

Este exemplo retorna uma string vazia.

strings.extract_hostname("") = ""

Exemplo 2

string aleatório, não um URL

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

Exemplo 3

várias barras invertidas

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

Exemplo 4

caracteres não ingleses são processados corretamente

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_hex

Compatível com:

Regras Pesquisa

strings.from_hex(hex_string)

Descrição

Retorna os bytes associados à string hexadecimal especificada.

Tipos de dados de parâmetro

STRING

Tipo de retorno

BYTES

Amostras de código

Recebe bytes associados a uma string hexadecimal específica.

Exemplo 1

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

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

Exemplo 2

Este exemplo mostra a entrada com uma string vazia.

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

Exemplo 3

Este exemplo mostra a conversão de string hexadecimal.

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

Compatível com:

Regras Pesquisa

strings.ltrim(string_to_trim, cutset)

Descrição

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

Tipos de dados de parâmetro

STRING, STRING

Tipo de retorno

STRING

Amostras de código

Confira abaixo 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 o 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:

Regras Pesquisa

strings.reverse(STRING)

Descrição

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

Tipos de dados de parâmetro

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 passa um palíndromo.

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

strings.rtrim

Compatível com:

Regras Pesquisa

strings.rtrim(string_to_trim, cutset)

Descrição

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

Tipos de dados de parâmetro

STRING, STRING

Tipo de retorno

STRING

Amostras de código

Confira abaixo 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.

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

Exemplo 4

O exemplo a seguir transmite uma string com 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:

Regras Pesquisa

strings.to_lower(stringText)

Descrição

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

Tipos de dados de parâmetro

STRING

Tipo de retorno

STRING

Amostras de código

Exemplo 1

O exemplo a seguir retorna true.

"[e-mail]" = strings.to_lower($e.network.email.to)

strings.to_upper

Compatível com:

Regras Pesquisa

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âmetro

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:

Regras Pesquisa

strings.trim(string_to_trim, cutset)

Descrição

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

Tipos de dados de parâmetro

STRING, STRING

Tipo de retorno

STRING

Amostras de código

Confira abaixo alguns exemplos de casos de uso.

Exemplo 1

No exemplo abaixo, a mesma string é transmitida como a string de entrada e o conjunto de corte, resultando em uma string vazia.

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

Exemplo 2

No exemplo abaixo, 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 abaixo, 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 abaixo, a função gera str porque a função trim remove o seguinte:

• Espaço em branco final 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:

Regras Pesquisa

strings.url_decode(url_string)

Descrição

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

Tipos de dados de parâmetro

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 decodificação de URL de amostra.

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:

Regras Pesquisa

timestamp.as_unix_seconds(timestamp [, time_zone])

Descrição

Essa função retorna um número inteiro que representa o número de segundos passados de 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 é GMT. É possível especificar fusos horários usando literais de string. As opções são as seguintes:
  • O nome do banco de dados TZ, por exemplo, America/Los_Angeles. Para mais informações, consulte a lista de fusos horários do banco de dados tz na Wikipédia.
  • O deslocamento de 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 as 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âmetro

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:

Regras Pesquisa

timestamp.current_seconds()

Descrição

Retorna um número inteiro que representa o horário atual em segundos Unix. Esse valor é aproximadamente igual ao carimbo de data/hora da detecção e é baseado no momento em que a regra é executada. Essa função é um sinônimo da função timestamp.now().

Tipos de dados de parâmetro

NONE

Tipo de retorno

INT

Amostras de código

Exemplo 1

O exemplo a seguir retorna true se o certificado estiver expirado há mais de 24 horas. Ele calcula a diferença de tempo subtraindo os segundos Unix atual e, em seguida, compara usando um operador maior que.

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

timestamp.get_date

Compatível com:

Regras Pesquisa

timestamp.get_date(unix_seconds [, time_zone])

Descrição

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

• unix_seconds é um número inteiro que representa o número de segundos após a época 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 é "GMT". É possível especificar fusos horários usando literais de string. As opções são:
  • O nome do banco de dados TZ, por exemplo, "America/Los_Angeles". Para mais informações, consulte a coluna "Nome do banco de dados TZ" desta página.
  • O deslocamento de 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âmetro

INT, STRING

Tipo de retorno

STRING

Amostras de código

Exemplo 1

Neste exemplo, o argumento time_zone é omitido, portanto, 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:

Regras Pesquisa

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 após a época 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 é "GMT". É possível especificar fusos horários usando literais de string. As opções são:
  • O nome do banco de dados TZ, por exemplo, "America/Los_Angeles". Para mais informações, consulte a coluna "Nome do banco de dados TZ" desta página.
  • O deslocamento de 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 as 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âmetro

INT, STRING

Tipo de retorno

INT

Amostras de código

Exemplo 1

Neste exemplo, o argumento time_zone é omitido, portanto, 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:

Regras Pesquisa

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 após a época 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 é "GMT". É possível especificar fusos horários usando literais de string. As opções são:
  • O nome do banco de dados TZ, por exemplo, "America/Los_Angeles". Para mais informações, consulte a coluna "Nome do banco de dados TZ" desta página.
  • O deslocamento de 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 as 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âmetro

INT, STRING

Tipo de retorno

INT

Amostras de código

Exemplo 1

Neste exemplo, o argumento time_zone é omitido, portanto, 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:

Regras Pesquisa

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 após a época 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 é "GMT". É possível especificar fusos horários usando literais de string. As opções são:
  • O nome do banco de dados TZ, por exemplo, "America/Los_Angeles". Para mais informações, consulte a coluna "Nome do banco de dados TZ" desta página.
  • O deslocamento de 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âmetro

INT, STRING

Tipo de retorno

INT

Amostras de código

Exemplo 1

Neste exemplo, o argumento time_zone é omitido, portanto, 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:

Regras Pesquisa

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

Descrição

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

• unix_seconds é um número inteiro que representa o número de segundos após a época 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 literais de string. Para opções, 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 é GMT. É possível especificar fusos horários usando literais de string. As opções são as seguintes:
  • O nome do banco de dados do fuso horário (TZ) da IANA, por exemplo, America/Los_Angeles. Para mais informações, consulte a lista de fusos horários do banco de dados tz na Wikipédia.
  • O deslocamento de 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 as 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âmetro

INT, STRING, STRING

Tipo de retorno

STRING

Amostras de código

Exemplo 1

Neste exemplo, o argumento time_zone é omitido, portanto, ele é definido como GMT por padrão.

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

timestamp.get_week

Compatível com:

Regras Pesquisa

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 antes do primeiro domingo do ano estão na semana 0.

• unix_seconds é um número inteiro que representa o número de segundos após a época 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 é "GMT". É possível especificar fusos horários usando literais de string. As opções são:
  • O nome do banco de dados TZ, por exemplo, "America/Los_Angeles". Para mais informações, consulte a coluna "Nome do banco de dados TZ" desta página.
  • O deslocamento de 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 as 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âmetro

INT, STRING

Tipo de retorno

INT

Amostras de código

Exemplo 1

Neste exemplo, o argumento time_zone é omitido, portanto, 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:

Regras Pesquisa

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 de é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 18h16min59s.

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

window.avg

Compatível com:

Regras

window.avg(numeric_values [, should_ignore_zero_values])

Descrição

Retorna a média dos valores de entrada, que podem ser inteiros ou números com ponto flutuante. Definir o segundo argumento opcional como verdadeiro ignora valores nulos.

Tipos de dados de parâmetro

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

Ignorar valores 0

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

window.first

Compatível com:

Regras

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 valor de int correlacionado mais baixo 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 (evento mais antigo).

Tipos de dados de parâmetro

INT, STRING

Tipo de retorno

STRING

Amostras de código

Receba um valor de string derivado de um evento com o valor de int correlacionado mais baixo 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:

Regras

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 valor int mais alto na janela de correspondência. Um exemplo de caso de uso é receber o ID do usuário 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âmetro

INT, STRING

Tipo de retorno

STRING

Amostras de código

Recebe um valor de string derivado de um evento com o valor int mais alto 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:

Regras

window.median(numeric_values, should_ignore_zero_values)

Descrição

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

Tipos de dados de parâmetro

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 nulos que precisam 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 nulos que precisam 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 mediana é 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:

Regras

window.mode(values)

Descrição

Retorna o modo dos valores de entrada. No caso de 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âmetro

INT|FLOAT|STRING

Tipo de retorno

STRING

Amostras de código

Exemplo 1

Receber 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:

Regras

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âmetro

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 flutuantes 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:

Regras

window.variance(values)

Descrição

Essa função retorna a variação especificada dos valores de entrada.

Tipos de dados de parâmetro

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 variação de todos os números flutuantes.

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 variação 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 variação 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 variação 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

Atribuição de função a marcador de posição

É possível 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").

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

1. Todos os marcadores de posição na atribuição de função a marcador de posição precisam ser atribuídos a uma expressão que contenha um campo de evento. Por exemplo, os exemplos a seguir 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 apenas 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 de listas de referências

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

É possível usar listas de referência nas seções events ou outcome. Confira 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 o operador not e o operador 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 mecanismo de detecção restringe o uso da lista de referência.

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

Verificação de tipo

O Google Security Operations realiza a verificação de tipo com base na sintaxe YARA-L ao criar regras na interface. Os erros de verificação de tipo exibidos ajudam você a revisar a regra de forma que ela funcione 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 eventos para cada variável de evento definida na regra. Por exemplo, se uma regra define duas variáveis de evento, cada detecção pode 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 variável tiver 15 eventos aplicáveis, 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 você quiser mais informações sobre os eventos que causaram a detecção, use agregações na seção de resultados para gerar mais informações na detecção.

Se você estiver visualizando as detecções na UI, poderá fazer o download de todos os exemplos de eventos de uma detecção. Para mais informações, consulte Eventos de download.