Sintaxe da linguagem YARA-L 2.0

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

Estrutura das regras

Para o YARA-L 2.0, tem de especificar declarações, definições e utilizações de variáveis pela seguinte ordem:

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

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

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

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

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

  outcome:
    // Additional information extracted from each detection.

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

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

Sintaxe da secção meta

A secção meta é composta por várias linhas, em que cada linha define um par de chave-valor. Uma parte da chave tem de ser uma string sem aspas e uma parte do valor tem de ser uma string com aspas:

<key> = "<value>"

Segue-se um exemplo de uma linha de secção meta válida:

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

Sintaxe da secção de eventos

Na secçã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 eventos

Declarações de variáveis

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

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

Ambos são equivalentes, como mostrado nos exemplos seguintes:

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

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

Por exemplo, o seguinte:

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

São equivalentes a:

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

Quando é usada uma variável, esta tem de ser declarada através da declaração de variáveis. Se for usada uma variável sem qualquer declaração, é considerada um erro de compilação.

Filtros de variáveis de eventos

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

Junções de variáveis de eventos

Todas as variáveis de eventos usadas na regra têm de ser unidas a todas as outras variáveis de eventos de uma das seguintes formas:

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

• Indiretamente, através de uma junção transitiva que envolva apenas um campo de evento (consulte a declaração de variáveis para uma definição de "junção transitiva"). A expressão não pode incluir aritmética.

Por exemplo, se assumirmos que $e1, $e2 e $e3 são usados na regra, as seguintes secções events são válidas.

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

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

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

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

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

No entanto, seguem-se exemplos de secçõ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 secção de correspondência

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

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

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

  Onde m/h/d significa minutos, horas e dias, respetivamente.

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

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

Segue-se um exemplo de um match válido:

$var1, $var2 over 5m

Esta declaração devolve $var1 e $var2 (definidos na secção events) quando a regra encontra uma correspondência. O tempo especificado é de 5 minutos. Os eventos com uma diferença superior a 5 minutos não são correlacionados e, por isso, são ignorados pela regra.

Segue-se outro exemplo de uma secção match válida:

$user over 1h

Esta declaração devolve $user quando a regra encontra uma correspondência. O período especificado é de 1 hora. Os eventos com mais de uma hora de diferença não são correlacionados. A regra não os considera uma deteção.

Segue-se outro exemplo de uma secção match válida:

$source_ip, $target_ip, $hostname over 2m

Esta declaração devolve $source_ip, $target_ip e $hostname quando a regra encontra uma correspondência. O período especificado é de 2 minutos. Os eventos com mais de 2 minutos de diferença não são correlacionados. A regra não os considera uma deteção.

Os exemplos seguintes ilustram secções inválidas match:

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

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

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

rule ZeroValuePlaceholderExample {
  meta:
  events:
    // Because $host is used in the match section, the rule behaves
    // as if the following predicate was added to the events section:
    // $host != ""
    $host = $e.principal.hostname

    // Because $otherPlaceholder was not used in the match section,
    // there is no implicit filtering of zero values for $otherPlaceholder.
    $otherPlaceholder = $e.principal.ip

  match:
    $host over 5m

  condition:
    $e
}

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

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

  match:
    $ph over 5m

  condition:
    $e
}

Para desativar a filtragem implícita de valores zero, pode usar a opção allow_zero_values na secção de opções.

Janela de salto

Por predefinição, as regras YARA-L 2.0 com uma secção de correspondência são avaliadas através de janelas de saltos. O intervalo de tempo da execução da regra é dividido num conjunto de intervalos de tempo sobrepostos, cada um com a duração especificada na secção match. Em seguida, os eventos são correlacionados em cada intervalo de salto.

Por exemplo, para uma regra executada no intervalo de tempo [1:00, 2:00], com uma secção match sobre 30m, um possível conjunto de intervalos de salto sobrepostos que podem ser gerados é [1:00, 1:30], [1:03, 1:33] e [1:06, 1:36]. Estes períodos são usados para correlacionar vários eventos.

Janela deslizante

A utilização de intervalos de saltos não é uma forma eficaz de pesquisar eventos que ocorrem numa ordem específica (por exemplo, e1 ocorre até 2 minutos após e2). Uma ocorrência do evento e1 e uma ocorrência do evento e2 são correlacionadas apenas se se enquadrarem no mesmo intervalo de saltos gerado.

Uma forma mais eficaz de pesquisar essas sequências de eventos é usar janelas deslizantes. As janelas deslizantes com a duração especificada na secção match são geradas quando começam ou terminam com uma variável de evento de referência especificada. Em seguida, os eventos são correlacionados em cada período de tempo móvel. Isto permite pesquisar eventos que ocorrem numa ordem específica (por exemplo, e1 ocorre no prazo de 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 no período de tempo de análise após o evento e2.

Especifique intervalos móveis na secção match de uma regra da seguinte forma:

<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 se baseiam os períodos de análise dinâmicos. Se usar a palavra-chave before, são geradas janelas deslizantes que terminam com cada ocorrência do evento principal. Se for usada a palavra-chave after, são geradas janelas deslizantes a partir de cada ocorrência do evento de referência.

Seguem-se exemplos de utilizações válidas de janelas deslizantes:

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

Veja um exemplo de uma regra de janela deslizante.

Recomendamos que não use intervalos deslizantes para regras de evento único, porque os intervalos deslizantes foram concebidos para detetar vários eventos. Se uma das suas regras se enquadrar nesta categoria, recomendamos uma das seguintes soluções alternativas:

• Converta a regra para usar várias variáveis de eventos e atualize a secção de condições se a regra exigir mais do que uma ocorrência do evento.
  • Opcionalmente, considere adicionar filtros de data/hora em vez de usar um período dinâmico. Por exemplo, $permission_change.metadata.event_timestamp.seconds < $file_creation.metadata.event_timestamp.seconds
• Remova a janela deslizante.

Sintaxe da secção de resultado

Na secção outcome, pode definir até 20 variáveis de resultados com nomes arbitrários. Estes resultados são armazenados nas deteções geradas pela regra. Cada deteção pode ter valores diferentes para os resultados.

O nome do resultado, $risk_score, é especial. Opcionalmente, pode definir um resultado com este nome e, se o fizer, tem de ser um tipo inteiro ou flutuante. Se estiver preenchido, o ícone risk_score é apresentado na vista Estatísticas empresariais para alertas provenientes de deteções de regras.

Se não incluir uma variável $risk_score na secção de resultados de uma regra, é definido um dos seguintes valores predefinidos:

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

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

Tipos de dados de variáveis de resultados

Cada variável de resultado pode ter um tipo de dados diferente, que é determinado pela expressão usada para a calcular. Suportamos os seguintes tipos de dados de resultados:

• número inteiro
• flutuadores
• de string
• listas de números inteiros
• listas de flutuantes
• listas de strings

Lógica condicional

Pode usar a lógica condicional para calcular o valor de um resultado. As condições são especificadas através do seguinte padrão de sintaxe:

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

Pode ler uma expressão condicional como "se BOOL_CLAUSE for verdadeiro, devolve THEN_CLAUSE, caso contrário, devolve ELSE_CLAUSE".

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

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

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

• variável do marcador de posição que foi definida na secção events, por exemplo:

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

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

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

• Funções que devolvem um valor booleano, por exemplo:

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

• consultar numa 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)

THEN_CLAUSE e ELSE_CLAUSE têm de ser do mesmo tipo de dados. Suportamos números inteiros, números de vírgula flutuante e strings.

Pode omitir a ELSE_CLAUSE se o tipo de dados for um número inteiro ou um número de vírgula flutuante. Se for omitido, a CLÁUSULA_ELSE é avaliada como 0. Por exemplo:

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

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

Operações matemáticas

Pode usar operações matemáticas para calcular o tipo de dados inteiro ou flutuante nas secções outcomee events de uma regra. As operações de segurança da Google suportam adição, subtração, multiplicação, divisão e módulo como operadores de nível superior num cálculo.

O fragmento seguinte é um exemplo de cálculo na secçã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 a expressão aritmética completa estejam devidamente agregados (consulte Agregações):

• Campos de eventos numéricos
• Variáveis de marcadores de posição numéricos definidas na secção events
• Variáveis de resultados numéricos definidas na secção outcome
• Funções que devolvem números inteiros ou de vírgula flutuante
• Agregações que devolvem números inteiros ou de vírgula flutuante

O módulo não é permitido em números de vírgula flutuante.

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

Ao calcular as variáveis de resultados, pode usar variáveis de marcadores de posição que foram definidas na secção de eventos da sua regra. Neste exemplo, vamos assumir que $email_sent_bytes foi definido na secçã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 resultados em expressões de atribuição de resultados

As variáveis de resultado podem ser usadas para derivar outras variáveis de resultado, semelhantes às variáveis de marcadores de posição definidas na secção events. Pode fazer referência a uma variável de resultado na atribuição de outra variável de resultado com um token $ seguido do nome da variável. As variáveis de resultado têm de ser definidas antes de poderem ser referenciadas no texto da regra. Quando usadas numa expressão de atribuição, as variáveis de resultado não podem ser agregadas (consulte Agregações).

No exemplo seguinte, a variável de resultado $risk_score deriva o respetivo 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 eventos 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. É um valor não escalar. Por outro lado, a variável do campo de evento $e.principal.hostname não é um campo repetido e só tem 1 valor (ou seja, um valor escalar).

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

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

Qualquer período de 5 minutos durante o qual a regra é executada pode conter zero, um ou vários eventos. A secção de resultados funciona em todos os eventos num período de correspondência. Qualquer variável de campo de evento referida na secção de resultados pode apontar para zero, um ou vários valores do campo em cada evento no período de correspondência. Por exemplo, se um período de 5 minutos contiver 5 eventos $e, $e.principal.hostname na secção de resultados aponta para cinco nomes de anfitrião diferentes. A variável do campo de evento $e.principal.hostname é tratada como um valor não escalar na secção outcome desta regra.

Uma vez que as variáveis de resultado têm sempre de gerar um único valor escalar, qualquer valor não escalar do qual uma atribuição de resultado dependa tem de ser agregado para gerar um único valor escalar. Numa secção de resultados, os seguintes são valores não escalares e têm de ser agregados:

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

Os campos de eventos escalares, os marcadores de posição de eventos escalares e as constantes podem ser incluídos em funções de agregação em regras que não incluem uma secção de correspondência. No entanto, na maioria dos casos, estas agregações devolvem o valor envolvido, o que as torna desnecessárias. Uma exceção é a agregação array(), que pode usar para converter explicitamente um valor escalar num conjunto.

As variáveis de resultados são tratadas como agregações: não podem ser reagregadas quando são referidas noutra atribuição de resultados.

Pode usar as seguintes funções de agregação:

• max(): apresenta o máximo de todos os valores possíveis. Funciona apenas com números inteiros e de vírgula flutuante.
• min(): apresenta o mínimo de todos os valores possíveis. Funciona apenas com números inteiros e de vírgula flutuante.
• sum(): apresenta a soma de todos os valores possíveis. Funciona apenas com números inteiros e de vírgula flutuante.
• count_distinct(): recolhe todos os valores possíveis e, em seguida, apresenta a contagem distinta dos valores possíveis.
• count(): comporta-se como count_distinct(), mas devolve uma contagem não distinta de valores possíveis.
• array_distinct(): recolhe todos os valores distintos possíveis e, em seguida, apresenta uma lista destes valores. Trunca a lista de valores distintos para 1000 elementos aleatórios. A anulação da duplicação para obter uma lista distinta é aplicada primeiro e, em seguida, é aplicada a truncagem.
• array(): comporta-se como array_distinct(), mas devolve uma lista não distinta de valores. Também trunca a lista de valores para 1000 elementos aleatórios.
• period_start_for_max(): início do período em que ocorreu o máximo do valor indicado.
• period_start_for_min(): início do período em que ocorreu o mínimo do valor indicado.

A função de agregação é importante quando uma regra inclui uma secção condition que especifica que têm de existir vários eventos, porque a função de agregação opera em todos os eventos que geraram a deteção.

Por exemplo, se as secçõ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

Uma vez que a secção de condições requer mais de um event para cada deteção, as funções de agregação operam em vários eventos. Suponhamos que os seguintes eventos geraram uma deteçã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"

Em seguida, os valores dos seus 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"]

Aspetos a ter em conta ao usar a secção de resultados:

Outras notas e restrições:

• A secção outcome não pode fazer referência a uma nova variável de marcador de posição que não tenha sido definida na secção events ou na secção outcome.
• A secção outcome não pode usar variáveis de eventos que não tenham sido definidas na secção events.
• A secção outcome pode usar um campo de evento que não foi usado na secção events, desde que a variável de evento à qual o campo de evento pertence já tenha sido definida na secção events.
• A secção outcome só pode correlacionar variáveis de eventos que já tenham sido correlacionadas na secção events. As correlações ocorrem quando dois campos de eventos de variáveis de eventos diferentes são equiparados.

Pode encontrar um exemplo com a secção de resultados na vista geral do YARA-L 2.0. Consulte o artigo Crie estatísticas de contexto para ver detalhes sobre a eliminação de duplicados de deteção com a secção de resultados.

Sintaxe da secção de condições

• especificar uma condição de correspondência sobre eventos e marcadores de posição definidos na secção events. Consulte a secção seguinte, Condicionais de eventos e marcadores de posição, para ver mais detalhes.
• (Opcional) Use a palavra-chave and para especificar uma condição de correspondência usando variáveis de resultados definidas na secção outcome. Consulte a secção seguinte, Condicionais de resultados, para ver mais detalhes.

Contar carateres

O caráter # é um caráter especial na secção condition. Se for usado antes de qualquer evento ou nome de variável de marcador de posição, representa o número de eventos ou valores distintos que satisfazem todas as condições da secção events.

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

Caráter de valor

O caráter $ é um caráter especial na secção condition. Se for usado antes do nome de qualquer variável de resultado, representa o valor desse resultado.

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

Condicionais de eventos e marcadores de posição

Indique aqui os predicados de condições para eventos e variáveis de marcadores de posição.

Pode juntar estes predicados usando a palavra-chave and ou or.

• Use a palavra-chave and entre quaisquer condições.

• Use a palavra-chave or apenas quando a regra contiver uma única variável de evento.

Um exemplo válido de utilização de or entre dois marcadores de posição 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 utilização de or entre duas condições em eventos diferentes:

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

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

  match:
    $ph over 5m

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

Condições delimitadas e não delimitadas

As seguintes condições são condições delimitadas. Forçam a existência da variável de evento associada, o que significa que, pelo menos, uma ocorrência do evento tem de aparecer em qualquer deteção.

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

As seguintes condições são condições ilimitadas. Permitem que a variável de evento associada não exista, o que significa que é possível que não apareça nenhuma ocorrência do evento numa deteção e qualquer referência a campos na variável de evento produzirá um valor zero. As condições ilimitadas podem ser usadas para detetar a ausência de um evento durante um período. Por exemplo, um evento de ameaça sem um evento de mitigação num período de 10 minutos. As regras que usam condições ilimitadas são denominadas regras de não existência.

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

Requisitos de não existência

Para que uma regra com não existência seja compilada, tem de cumprir os seguintes requisitos:

1. Pelo menos, um evento de UDM tem de ter uma condição delimitada (ou seja, tem de existir, pelo menos, um evento de UDM).
2. Se um marcador de posição tiver uma condição ilimitada, tem de estar associado a, pelo menos, um evento de UDM limitado.
3. Se uma entidade tiver uma condição ilimitada, tem de estar associada a, pelo menos, um evento de UDM limitado.

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

Seguem-se exemplos válidos para o <condition_section>:

• $u1 and !$u2 and $e1 and $e2
  • Todos os eventos e entidades da UDM estão presentes na secção de condições.
  • Pelo menos, um evento da UDM está limitado.
• $u1 and !$u2 and $e1 and !$e2
  • $e2 não tem limites, o que é permitido porque está associado a $u1, que tem limites. Se $e2 não estivesse associado a $u1, este campo seria inválido.
• #port > 50 and #ip = 0
  • Não estão presentes eventos nem entidades do UDM na secção de condições. No entanto, os marcadores de posição presentes abrangem todos os eventos e entidades do UDM.
  • $ip está atribuído a $u1 e $u2, e #ip = 0 é uma condição ilimitada. No entanto, as condições delimitadas são mais fortes do que as condições não delimitadas. Uma vez que $port está atribuído a $u1 e #port > 50 é uma condição limitada, $u1 continua limitado.

Seguem-se exemplos inválidos para o elemento <condition_section>:

• $u1 and $e1
  • Todos os eventos e entidades da UDM apresentados na secção de eventos têm de ser apresentados na secção de condições (ou ter um marcador de posição atribuído que seja apresentado na secção de condições).
• $u1, $u2, $e1, $u2, #port > 50
  • Não são permitidas vírgulas como separadores de condições.
• !$u1 and !$u2 and $e1 and $e2
  • Viola o primeiro requisito de que, pelo menos, um evento de UDM está limitado.
• ($u1 or #port < 50) and $u2 and $e1 and $e2
  • A palavra-chave or não é suportada com condições ilimitadas.
• ($u1 or $u2) and $e1 and $e2
  • A palavra-chave or não é suportada entre diferentes variáveis de eventos.
• not $u1 and $u2 and $e1 and $e2
  • A palavra-chave not não é permitida para condições de eventos e marcadores de posição.
• #port < 50 and #ip = 0
  • Os marcadores de posição presentes abrangem todos os eventos e entidades da UDM. No entanto, todas as condições são ilimitadas. Isto significa que nenhum dos eventos da UDM está limitado, o que faz com que a regra não seja compilada.

Condições de resultados

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

Especifique as condições dos resultados de forma diferente consoante o tipo de variável de resultado:

• integer: compare com um literal inteiro com os operadores =, >, >=, <, <=, !=, por exemplo:

  $risk_score > 10

• float: compare com um literal float 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 através da função arrays.contains, por exemplo:

  arrays.contains($event_ids, "id_1234")

Classificação de regras

Especificar um resultado condicional numa regra que tenha uma secção de correspondência significa que a regra é classificada como uma regra de vários eventos para a quota de regras. Consulte a regra de evento único e a regra de vários eventos para mais informações sobre as classificações de eventos únicos e múltiplos.

Sintaxe da secção de opções

Na secção options, pode especificar as opções da regra. Segue-se um exemplo de como especificar a secção de opções:

rule RuleOptionsExample {
  // Other rule sections

  options:
    allow_zero_values = true
}

Pode especificar opções através da sintaxe key = value, em que key tem de ser um nome de opção predefinido e value tem de ser um valor válido para a opção, conforme especificado para as seguintes opções:

allow_zero_values

Os valores válidos para esta opção são true e false, que determinam se esta opção está ativada ou não. O valor predefinido é false. Esta opção está desativada se não estiver especificada na regra.

Para ativar esta definição, adicione o seguinte à secção de opções da sua regra: allow_zero_values = true. Ao fazê-lo, evita que a regra filtre implicitamente os valores zero dos marcadores de posição usados na secção de correspondência, conforme descrito no artigo Processamento de valores zero na secção de correspondência.

suppression_window

A opção suppression_window permite-lhe controlar a frequência com que uma regra aciona uma deteção. Impede que a mesma regra gere várias deteções num período especificado, mesmo que as condições da regra sejam cumpridas várias vezes. A aplicação de janelas de supressão usa uma abordagem de janelas rotativas, que suprime duplicados numa janela de tamanho fixo e sem sobreposição.

Opcionalmente, pode fornecer um suppression_key para refinar ainda mais as instâncias da regra que são suprimidas no período de supressão. Se não for especificado, todas as instâncias da regra são suprimidas. Esta chave está definida como uma variável de resultado.

No exemplo seguinte, suppression_window está definido como 5m e suppression_key está definido como a variável $hostname. Depois de a regra acionar uma deteção para $hostname, as deteções adicionais para $hostname são suprimidas durante os cinco minutos seguintes. No entanto, se a regra for acionada num evento com um nome de anfitrião diferente, é criada uma deteção.

O valor predefinido de suppression_window é 0, ou seja, a janela de supressão está desativada por predefinição. Esta opção só funciona para regras de evento único que não tenham uma secção match.

Exemplo:

rule SuppressionWindowExample {
  // Other rule sections

  outcome:
    $suppression_key = $hostname

  options:
    suppression_window = 5m
}

Regras de deteção compostas

A deteção composta no Google SecOps envolve a ligação de várias regras YARA-L. Esta secção explica como criar uma regra composta. Para ver uma vista geral das deteções compostas, consulte o artigo Vista geral das deteções compostas.

Compreenda a estrutura das regras

As regras de deteção compostas são sempre regras de vários eventos e seguem a mesma estrutura e sintaxe.

Uma regra composta tem os seguintes componentes essenciais:

1. events bloco: define as suas entradas; as deteções ou os eventos específicos que a regra analisa.

2. match bloco: especifica como as entradas devem ser ligadas durante um período definido.

3. condition bloco: contém a lógica final que determina se os eventos unidos cumprem os critérios para acionar um alerta.

Defina as entradas no bloco events

O primeiro passo é definir as entradas da regra no bloco events. As entradas para regras compostas provêm de coleções, que armazenam as deteções geradas por outras regras. O Google SecOps oferece os dois métodos seguintes para aceder aos dados das recolhas.

Referencie conteúdo de deteção através de variáveis de resultados, variáveis de correspondência ou metacaraterísticas

Para aceder a dados de uma deteção sem fazer referência aos eventos UDM originais, use variáveis outcome, variáveis match ou etiquetas meta. Recomendamos esta abordagem porque oferece maior flexibilidade e melhor compatibilidade em diferentes tipos de regras.

Por exemplo, várias regras podem armazenar uma string (como um URL, um nome de ficheiro ou uma chave de registo) numa variável outcome comum se estiver à procura dessa string em diferentes contextos. Para aceder a esta string a partir de uma regra composta, comece com detection e localize as informações relevantes através de elementos do recurso de recolha.

Exemplo: por exemplo, suponhamos que uma regra de deteção produz as seguintes informações:

• Variável de resultado: dest_domain = "cymbal.com"

• Campo UDM: target.hostname = "cymbal.com"

Na regra composta, pode aceder a estes dados através dos seguintes caminhos:

• detection.detection.outcomes["dest_domain"] para aceder à variável de resultado dest_domain.

• detection.collection_elements.references.event.target.hostname para aceder ao campo target.hostname UDM.

• detection.time_window.start_time.seconds para aceder à data/hora de deteção.

A API Collection e a API SecurityResult oferecem acesso a ambas:

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

Consulte o conteúdo de deteção através do ID ou do nome da regra

Pode fazer referência a uma regra pelo nome ou ID. Recomendamos esta abordagem quando a lógica de deteção depende de regras específicas. Fazer referência a regras relevantes por nome ou ID melhora o desempenho e evita os limites de tempo, reduzindo os dados analisados. Por exemplo, pode consultar diretamente campos como target.url ou principal.ip a partir de uma deteção anterior conhecida.

• Referencie uma regra pelo ID da regra (recomendado): use o campo detection.detection.rule_id para referenciar uma regra por ID. Pode encontrar o ID da regra no URL da regra no Google SecOps. As regras geradas pelo utilizador têm IDs no formato ru_UUID, enquanto as deteções organizadas têm IDs no formato ur_UUID. Por exemplo:

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

• Fazer referência a uma regra pelo nome da regra: use o campo detection.detection.rule_name para fazer referência a uma regra pelo nome. Pode especificar o nome exato da regra ou usar uma expressão regular para a fazer corresponder. Por exemplo:

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

Junte as suas entradas na secção match

Para associar deteções, eventos ou entidades relacionados numa regra composta, defina a secção match com variáveis definidas na secção events. Estas variáveis podem incluir etiquetas de regras, variáveis de resultados, variáveis de correspondência, campos de deteção ou elementos de recolha.

Para obter informações sobre a sintaxe, consulte o artigo Sintaxe da secção de correspondência.

Defina a secção condition

Defina a secção condition para avaliar os resultados da secção match. Se a condição for true, é gerado um alerta. Para informações sobre a sintaxe, consulte o artigo Sintaxe da secção de condições.

Use técnicas avançadas

Esta secção explica como aplicar técnicas avançadas ao criar regras compostas.

Combine eventos e deteções

As regras compostas podem combinar várias origens de dados, incluindo eventos da UDM, dados do gráfico de entidades e campos de deteção. Aplicam-se as seguintes diretrizes:

• Use variáveis distintas por origem: atribua variáveis de eventos únicas a cada origem de dados (por exemplo, $e para eventos, $d para deteções), em que a origem de dados inclui eventos, entidades e deteções.

• Junte origens no contexto partilhado: associe origens de dados através de valores comuns, como IDs de utilizadores, endereços IP ou nomes de domínios nas condições da sua regra.

• Defina um período de correspondência: inclua sempre uma cláusula match com um período não superior a 48 horas.

Por exemplo:

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

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

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

  match:
    $hostname over 1h

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

  condition:
    $e and $d and $prevalence
}

Crie deteções compostas sequenciais

As deteções compostas sequenciais identificam padrões de eventos relacionados em que a sequência de deteções é importante, como uma deteção de tentativa de início de sessão por força bruta, seguida de um início de sessão bem-sucedido. Estes padrões podem combinar várias deteções base, eventos UDM não processados ou ambos.

Para criar uma deteção composta sequencial, tem de aplicar essa ordem na sua regra. Para aplicar a sequência esperada, use um dos seguintes métodos:

• Janelas deslizantes: defina a sequência de deteções através de janelas deslizantes nas suas condições match.

• Comparações de datas/horas: compare as datas/horas das deteções na lógica da regra para verificar se ocorrem na ordem selecionada.

Por exemplo:

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

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

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

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

  match:
    $userid over 24h after $d1

Classificações de risco

O risk_score é um número inteiro de 0 a 100 que representa a potencial gravidade ou impacto de uma deteção. Uma pontuação mais elevada indica uma descoberta mais crítica, partindo do princípio de que a deteção é true.

Para garantir a consistência na plataforma, recomendamos que use os seguintes intervalos de pontuação ao atribuir uma risk_score às suas deteções personalizadas. Este alinhamento ajuda a padronizar a priorização de alertas e os fluxos de trabalho de resposta.

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.

Por exemplo:

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

Se ambos os lados forem literais, é considerado um erro de compilação.

Funções

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

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

Por exemplo:

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

Expressões de listas de referências

Pode usar listas de referência na secção de eventos. Consulte a secção sobre Listas de referência para ver mais detalhes.

Expressões lógicas

Pode usar os operadores lógicos and e lógicos or na secção events, como mostrado nos seguintes exemplos:

• $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 predefinição, a ordem de precedência do mais alto para o 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 secção events, os predicados são unidos através do operador and se um operador não estiver 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 está definido explicitamente. O operador and está implícito.

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

Este exemplo é interpretado da seguinte forma:

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

Uma vez que or está definido explicitamente, os predicados que envolvem or são agrupados e avaliados primeiro. O último predicado, $e2.field = "bar", é unido implicitamente através de and. O resultado é que a ordem de avaliação é alterada.

Tipos enumerados

Pode usar os operadores com tipos enumerados. Pode ser aplicado a regras para simplificar e otimizar o desempenho (use o operador em vez de listas de referência).

No exemplo seguinte, "USER_UNCATEGORIZED" e "USER_RESOURCE_DELETION" correspondem a 15000 e 15014, pelo que 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 tem uma expressão de comparação entre valores de string ou uma expressão regular, pode acrescentar nocase no final da expressão para ignorar as letras maiú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 esta opção quando um tipo de campo é um valor enumerado. Os seguintes exemplos são inválidos e geram erros de compilação:

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

Campos repetidos

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

Campos repetidos e expressões booleanas

Existem 2 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 secções seguintes descrevem a finalidade e como usar os modificadores any e all em expressões.

qualquer

Se qualquer elemento do campo repetido satisfizer a condição, o evento como um todo satisfaz a condição.

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

todos

Se todos os elementos do campo repetido satisfizerem a condição, o evento como um todo satisfaz a condição.

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

Quando escreve uma condição com any ou all, tenha em atenção que negar a condição com not pode não ter o mesmo significado que usar o operador negado.

Por exemplo:

• not all $e.principal.ip = "192.168.12.16" verifica se nem todos os endereços IP correspondem a 192.168.12.16, o que significa que a regra está a verificar 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 nenhum endereço IP corresponde a 192.168.12.16, o que significa que a regra está a verificar se nenhum endereço IP corresponde a 192.168.12.16.

Restrições:

• Os operadores any e all só são compatíveis com campos repetidos (não campos escalares).
• Não é possível usar any e all para juntar 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 suportados 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 contiver n elementos, a regra é aplicada em n cópias do evento, em que cada cópia tem um dos elementos do campo repetido. Estas cópias são temporárias e não são armazenadas.

A regra é aplicada nas seguintes cópias:

Se qualquer cópia do evento satisfizer todas as condições não modificadas no campo repetido, o evento como um todo satisfaz todas as condições. Isto significa que, se tiver várias condições num campo repetido, a cópia do evento tem de satisfazer todas elas. Os exemplos de regras seguintes usam o conjunto de dados de exemplo anterior para demonstrar este comportamento.

A regra seguinte devolve 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 seguinte não devolve uma correspondência quando executada no conjunto de dados de exemplo, porque não existe nenhuma cópia do evento em $e.principal.ip que satisfaça todos os predicados de eventos.event_original

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

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

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

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

Campos e marcadores de posição repetidos

Os campos repetidos funcionam com atribuições de marcadores de posição. Semelhante às expressões não modificadas em campos repetidos, é feita uma cópia do evento para cada elemento. Usando o mesmo exemplo de event_copy, o marcador de posição assume o valor do campo repetido de event_copy_n para cada uma das cópias do evento em que n é o número da cópia do evento. Se o marcador de posição for usado na secção de correspondência, podem ocorrer várias correspondências.

O exemplo seguinte 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. Os exemplos de eventos da 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 seguinte gera três correspondências. O marcador de posição $ip é igual a valores diferentes para cada uma das diferentes cópias event_copy_n. O agrupamento é feito em $ip, uma vez que está na secção de correspondências. Por conseguinte, 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 o mesmo exemplo de evento: um único elemento, event_original.

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

  match:
    $ip over 5m

  condition:
    $e
}

Resultados com 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 e não à lista completa. Assim, quando são usados na secção de resultados, o resultado é calculado usando apenas os elementos que satisfizeram as secçõ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
}

Existem 4 fases de execução para esta regra. A primeira fase é a cópia de eventos:

A secção de eventos filtra e exclui as linhas que não correspondem aos filtros:

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

A secção de correspondência é, então, agrupada por variáveis de correspondência, e a secção de resultado agrega cada grupo:

$o = array_distinct($ip) é calculado com base em $ip da fase anterior e não da fase de cópia de eventos.

Por último, a secção de condições filtra cada grupo. Uma vez que esta regra apenas verifica a existência de $e, a linha anterior produz uma única deteção.

$o não contém todos os elementos de $e.principal.ip porque nem todos os elementos satisfizeram todas as condições na secção de eventos. No entanto, todos os elementos de e.principal.ip são apresentados no exemplo de evento porque o exemplo de evento usa event_original.

Indexação de matrizes

Pode realizar a indexação de matrizes em campos repetidos. Para aceder ao elemento do campo repetido n, use a sintaxe de lista padrão (os elementos têm índice 0). Um elemento fora dos limites devolve o valor predefinido.

• $e.principal.ip[0] = "192.168.12.16"
• $e.principal.ip[999] = "" Se existirem menos de 1000 elementos, esta condição é avaliada como true.

Restrições:

• Um índice tem de ser um literal de número inteiro não negativo. Por exemplo, $e.principal.ip[-1] não é válido.
• Os valores que têm um tipo int (por exemplo, um marcador de posição definido como int) não são contabilizados.
• A indexação de matrizes não pode ser combinada com any nem all. Por exemplo, any $e.intermediary.ip[0] não é válido.
• Não é possível combinar a indexação de matrizes com a sintaxe de mapas. Por exemplo, $e.additional.fields[0]["key"] não é válido.
• Se o caminho do campo contiver vários campos repetidos, todos os campos repetidos têm de usar a indexação de matrizes. Por exemplo, $e.intermediary.ip[0] não é válido porque intermediary e ip são campos repetidos, mas só existe um índice para ip.

Mensagens repetidas

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

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 indicado para expressões não modificadas em campos repetidos, é criada uma cópia temporária do evento 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:

O evento não corresponde à regra porque não existe nenhuma cópia do evento que satisfaça todas as expressões.

Mensagens repetidas e indexação de matrizes

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

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:

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

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

Comentários

Designar comentários com dois carateres de barra (// comment) ou comentários de várias linhas separados por carateres de barra e asterisco (/* comment */), como faria em C.

Literals

São suportados números inteiros e de vírgula flutuante não negativos, strings, booleanos e literais de expressões regulares.

Literais de string e de expressão regular

Pode usar qualquer um dos seguintes carateres de aspas para incluir strings no YARA-L 2.0. No entanto, o texto entre aspas é interpretado de forma diferente consoante o que usar.

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

2. Acentos graves (`) – Use para interpretar todos os carateres literalmente.
   Por exemplo: `hello\tworld` —\t não é interpretado como uma tabulação

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

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

Também pode usar strings literais como literais de expressões regulares quando usa a função re.regex(). Tenha em atenção que, para literais de string com aspas duplas, tem de usar carateres de barra invertida para que os carateres de barra invertida sejam interpretados de forma literal, 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/

A Google recomenda a utilização de carateres de acento grave para strings em expressões regulares para facilitar a leitura.

Operadores

Pode usar os seguintes operadores em YARA-L:

Variáveis

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

Pode definir os seguintes tipos de variáveis:

• Variáveis de eventos: representam grupos de eventos de forma normalizada (UDM) ou eventos de entidades. Especifique condições para variáveis de eventos na secção events. Identifica as variáveis de evento através de um nome, uma origem do evento e campos de eventos. As origens permitidas são udm (para eventos normalizados) e graph (para eventos de entidades). Se a origem for omitida, udm é definida como a origem predefinida. Os campos de eventos são representados como uma cadeia de .<field name> (por exemplo, $e.field1.field2). As cadeias de campos de eventos começam sempre na origem de nível superior (UDM ou entidade).

• Variáveis de correspondência: declare-as na secção match. As variáveis de correspondência tornam-se campos de agrupamento para a consulta, uma vez que é devolvida uma linha para cada conjunto único de variáveis de correspondência (e para cada intervalo de tempo). Quando a regra encontra uma correspondência, são devolvidos os valores das variáveis de correspondência. Especifique o que cada variável de correspondência representa na secção events.

• Variáveis dos marcadores de posição: declare e defina na secção events. As variáveis dos marcadores de posição são semelhantes às variáveis de correspondência. No entanto, pode usar variáveis de marcadores de posição na secção condition para especificar condições de correspondência.

Use variáveis de correspondência e variáveis de marcadores de posição para declarar relações entre campos de eventos através de condições de junção transitivas (consulte a sintaxe da secção de eventos para obter mais detalhes).

Keywords

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

Seguem-se as palavras-chave para regras do motor de deteção: 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 suporta o acesso a mapas para Structs e Labels.

Estruturas e etiquetas

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 devolve sempre uma string.

Registos suportados

Secção de 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"]

Usar um campo de mapa numa condição de junção

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

Registos não suportados

Os mapas não são suportados nos seguintes casos.

Combinar palavras-chave any ou all com um mapa

Por exemplo, o seguinte não é suportado:

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

Outros tipos de valores

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

Processamento de valores duplicados

Os acessos de mapa devolvem sempre um único valor. No caso limite invulgar em que o acesso ao mapa possa referir-se a vários valores, o acesso ao mapa devolve deterministicamente o primeiro valor.

Isto pode acontecer em qualquer um dos seguintes casos:

• Uma etiqueta tem uma chave duplicada.

  A estrutura de etiquetas representa um mapa, mas não aplica a unicidade das chaves. Por convenção, um mapa deve ter chaves únicas, pelo que o Google SecOps não recomenda preencher uma etiqueta com chaves duplicadas.

  O texto da regra $e.metadata.ingestion_labels["dupe-key"] devolveria 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"
      }
    }
  }
  

• Uma etiqueta tem um campo repetido de elemento principal.

  Um campo repetido pode conter uma etiqueta como um campo secundário. Duas entradas diferentes no campo repetido de nível superior podem conter etiquetas com a mesma chave. O texto da regra $e.security_result.rule_labels["key"] devolveria o primeiro valor possível, val3, se fosse 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"
      }
    }
  }
  

Aceda às variáveis de resultados nos mapas

Esta secção explica como aceder às variáveis de resultados nos mapas como os respetivos tipos de dados originais (por exemplo, números inteiros, booleanos ou listas destes tipos) em vez de apenas strings. Pode usar esta funcionalidade para ter mais flexibilidade e precisão na lógica das regras.

Os dados de resultados estão disponíveis nos dois campos seguintes:

• Os valores de resultados mantêm os respetivos tipos originais no campo variables.

• O campo outcomes armazena as versões string para retrocompatibilidade.

Pode aceder a estes valores de resultados através do mapa variables para obter o tipo específico ou aceder a elementos numa sequência através da indexação de matrizes. Pode aceder a um item específico na sequência pelo respetivo índice ou selecionar a sequência completa para avaliar cada valor individualmente.

Sintaxe:

$d.detection.detection.variables[OUTCOME_NAME].TYPE_SUFFIX

Sintaxe para sequências:

$d.detection.detection.variables[OUTCOME_NAME].SEQUENCE_TYPE_SUFFIX.TYPE_VALS_SUFFIX

Exemplos:

• Aceda ao resultado de uma string:

  $my_string_outcome = $d.detection.detection.variables["outcome_ip"].string_val
  

  Este exemplo obtém o valor da string diretamente (por exemplo, "1.1.1.1" if outcome_ip era uma única string).

• Aceder a um resultado de número inteiro:

  $my_int_outcome = $d.detection.detection.variables["outcome_port"].int64_value
  

  Este exemplo obtém o valor inteiro (por exemplo, 30).

• Aceda a uma lista de números inteiros (Int64Sequence):

  $my_int_list = $d.detection.detection.variables["outcome_ports"].int64_seq.int64_vals
  

  Este exemplo obtém a lista completa de números inteiros e anula a aninhagem dos mesmos, como campos repetidos (por exemplo, [2, 3, 4]).

• Aceder a um elemento específico de uma lista de números inteiros:

  $first_int = $d.detection.detection.variables["outcome_ports"].int64_seq.int64_vals[0]
  

  Este exemplo obtém o primeiro número inteiro da lista (por exemplo, 2).

• Aceda a uma lista de strings (StringSequence):

  $my_string_list = $d.detection.detection.variables["outcome_ips"].string_seq.string_vals
  

  Este exemplo obtém a lista completa de strings e anula a aninhagem das mesmas, como campos repetidos (por exemplo, ["1.1.1.1", "2.2.2.2"]).

• Aceda a um elemento específico a partir de uma lista de strings:

  $first_ip = $d.detection.detection.variables["outcome_ips"].string_seq.string_vals[0]
  

  Este exemplo obtém o primeiro endereço IP da lista (por exemplo, "1.1.1.1").

Sufixos de tipo disponíveis para variables

Para ver uma lista completa dos sufixos suportados, consulte o artigo FindingVariable.

Funções

Esta secção descreve as funções YARA-L 2.0 que pode usar nas regras do motor de deteção e na pesquisa.

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

• events secção.
• BOOL_CLAUSE de uma condição na secção de resultados.

arrays.concat

arrays.concat(string_array, string_array)

Descrição

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

Tipos de dados de parâmetros

ARRAY_STRINGS, ARRAY_STRINGS

Tipo devolvido

ARRAY_STRINGS

Exemplos de código

Exemplo 1

O exemplo seguinte concatena duas matrizes de strings diferentes.

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

Exemplo 2

O exemplo seguinte concatena matrizes com uma string vazia.

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

Exemplo 3

O exemplo seguinte concatena matrizes vazias.

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

arrays.join_string

arrays.join_string(array_of_strings, optional_delimiter)

Descrição

Converte uma matriz de strings numa única string separada pelo parâmetro opcional. Se não for fornecido nenhum delimitador, é usada a string vazia.

Tipos de dados de parâmetros

ARRAY_STRINGS, STRING

Tipo devolvido

STRING

Exemplos de código

Seguem-se alguns exemplos de como usar a função:

Exemplo 1

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

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

Exemplo 2

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

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

Exemplo 3

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

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

arrays.length

arrays.length(repeatedField)

Descrição

Devolve o número de elementos de campo repetidos.

Tipos de dados de parâmetros

LIST

Tipo devolvido

NUMBER

Exemplos de código

Exemplo 1

Devolve o número de elementos de campo repetidos.

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

Exemplo 2

Se existirem vários campos repetidos ao longo do caminho, devolve o número total de elementos de campos repetidos.

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

arrays.max

arrays.max(array_of_ints_or_floats)

Descrição

Devolve o maior elemento numa matriz ou zero se a matriz estiver vazia.

Tipos de dados de parâmetros

ARRAY_INTS|ARRAY_FLOATS

Tipo devolvido

FLOAT

Exemplos de código

Seguem-se alguns exemplos de como usar a função:

Exemplo 1

Este exemplo devolve o elemento maior numa matriz de números inteiros.

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

Exemplo 2

Este exemplo devolve o elemento maior numa matriz de números de vírgula flutuante.

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

arrays.min

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

Descrição

Devolve o elemento mais pequeno numa matriz ou zero se a matriz estiver vazia. Se o segundo argumento opcional for definido como verdadeiro, os elementos iguais a zero são ignorados.

Tipos de dados de parâmetros

ARRAY_INTS|ARRAY_FLOATS, BOOL

Tipo devolvido

FLOAT

Exemplos de código

Seguem-se alguns exemplos de como usar a função:

Exemplo 1

Este exemplo devolve o elemento mais pequeno numa matriz de números inteiros.

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

Exemplo 2

Este exemplo devolve o elemento mais pequeno numa matriz de números de vírgula flutuante.

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

Exemplo 3

Este exemplo devolve o elemento mais pequeno numa matriz de números de vírgula flutuante, ignorando os zeros.

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

arrays.size

arrays.size( array )

Descrição

Devolve a dimensão da matriz. Devolve 0 para uma matriz vazia.

Tipos de dados de parâmetros

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS

Tipo devolvido

INT

Exemplos 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 3 elementos.

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

Exemplo 3

Este exemplo usa uma matriz de números de vírgula 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

arrays.index_to_float(array, index)

Descrição

Devolve o elemento no índice especificado de uma matriz. O elemento nesse índice é devolvido como um número de vírgula flutuante.

O índice é um valor inteiro que representa a posição de um elemento na matriz. Por predefiniçã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 é a dimensão da matriz. A indexação negativa permite aceder a elementos da matriz relativamente ao fim da matriz. Por exemplo, um índice de -1 refere-se ao último elemento na matriz e um índice de -2 refere-se ao penúltimo elemento na matriz.

Tipos de dados de parâmetros

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS, INT

Tipo devolvido

FLOAT

Exemplos de código

Exemplo 1

O exemplo seguinte obtém um elemento no índice 1 de uma matriz de números de vírgula flutuante.

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

Exemplo 2

O exemplo seguinte obtém um elemento no índice -1 de uma matriz de números de vírgula flutuante.

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

Exemplo 3

O exemplo seguinte obtém um elemento para um índice superior ao tamanho da matriz.

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

Exemplo 4

O exemplo seguinte obtém um elemento de uma matriz vazia.

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

Exemplo 5

O exemplo seguinte obtém 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 seguinte obtém 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

arrays.index_to_int(array_of_inputs, index)

Descrição

Devolve o valor num determinado índice numa matriz como um número inteiro.

O índice é um valor inteiro que representa a posição de um elemento na matriz. Por predefiniçã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 é a dimensão da matriz. A indexação negativa permite aceder a elementos da matriz relativamente ao fim da matriz. Por exemplo, um índice de -1 refere-se ao último elemento na matriz e um índice de -2 refere-se ao penúltimo elemento na matriz.

Tipos de dados de parâmetros

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS, INT

Tipo devolvido

INT

Exemplos de código

Exemplo 1

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

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

Exemplo 2

Esta função devolve o elemento no índice -1.

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

Exemplo 3

Devolve 0 para o elemento fora dos limites.

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

Exemplo 4

Esta função obtém o elemento da matriz de números de vírgula flutuante no índice 1.

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

Exemplo 5

Esta função obtém o elemento da matriz int no índice 0.

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

arrays.index_to_str

arrays.index_to_str(array, index)

Descrição

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

Tipos de dados de parâmetros

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS, INT

Tipo devolvido

STRING

Exemplos de código

Exemplo 1

O exemplo seguinte obtém um elemento no índice 1 de uma matriz de strings.

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

Exemplo 2

O exemplo seguinte obtém um elemento no índice -1 (último elemento da matriz) de uma matriz de strings.

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

Exemplo 3

O exemplo seguinte obtém um elemento para um índice superior ao tamanho da matriz, o que devolve uma string vazia.

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

Exemplo 4

O exemplo seguinte obtém um elemento de uma matriz vazia.

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

Exemplo 5

O exemplo seguinte obtém um elemento no índice 0 de uma matriz de números de vírgula flutuante. O resultado é devolvido como uma string.

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

Exemplo 6

O exemplo seguinte obtém um elemento no índice 2 de uma matriz de números inteiros. O resultado está no formato de uma string.

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

cast.as_bool

cast.as_bool(string_or_int)

Descrição

A função converte um valor int ou string num valor bool. As chamadas de funções com valores que não podem ser convertidos devolvem FALSE. Devolve VERDADEIRO apenas para o número inteiro 1 e a string "true" sem distinção entre maiúsculas e minúsculas.

Tipos de dados de parâmetros

INT|STRING

Tipo devolvido

BOOL

Exemplos 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

Truthy string

cast.as_bool("true") = true

Exemplo 4

String verdadeira com maiúsculas

cast.as_bool("TRUE") = true

Exemplo 5

Número inteiro negativo

cast.as_bool(0-1) = false

Exemplo 6

Número inteiro falso (0)

cast.as_bool(0) = false

Exemplo 7

string vazia

cast.as_bool("") = false

cast.as_float

cast.as_float(string_to_cast)

Descrição

Converte uma string numérica num número de vírgula flutuante. Todas as chamadas de funções com valores que não podem ser convertidos devolvem 0. Os números de vírgula flutuante mantêm a precisão até 7 dígitos decimais.

Tipos de dados de parâmetros

STRING

Tipo devolvido

FLOAT

Exemplos de código

Exemplo 1

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

cast.as_float("str") = 0.0000000

Exemplo 2

A conversão de uma string vazia devolve 0.

cast.as_float("") = 0.0000000

Exemplo 3

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

cast.as_float("1.012345678") = 1.0123456

cast.as_string

cast.as_string(int_or_bytes_or_bool, optional_default_string)

Descrição

A função cast.as_string transforma um valor INT, BYTES ou BOOL na respetiva representação de string. Pode fornecer um argumento default_string opcional para processar casos em que a conversão falha. Se omitir o argumento default_string ou se a entrada for uma sequência de bytes UTF-8 ou BASE64 inválida, a função devolve uma string vazia.

Tipos de dados de parâmetros

INT|BYTES|BOOL, STRING

Tipo devolvido

STRING

Exemplos de código

Conversão de número inteiro para string

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

cast.as_string(123) = "123"

Conversão de número de ponto flutuante em string

A função converte o número de vírgula flutuante 2.25 na string "2.25".

cast.as_string(2.25) = "2.25"

Conversão de bytes em string

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

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

Conversão de Booleano para string

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

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

Conversão falhada (predefinição para a string fornecida opcionalmente)

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

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

impressão digital

hash.fingerprint2011(byteOrString)

Descrição

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

Tipos de dados de parâmetros

BTYE, STRING

Tipo devolvido

INT

Exemplo de código

id_fingerprint = hash.fingerprint2011("user123")

grupo

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

Descrição

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

Na pesquisa UDM, os campos agrupados são usados para pesquisar em vários campos de um tipo semelhante. A função group é semelhante aos campos agrupados, exceto que permite selecionar os campos que quer agrupar para acionar uma deteção. Pode usar a função de grupo para recolher informações sobre uma entidade específica (por exemplo, um nome de anfitrião, um endereço IP ou um ID de utilizador) em diferentes tipos de substantivos.

Exemplos de código

Exemplo 1

Agrupe todos os endereços IP e forneça uma contagem descendente do endereço IP mais prevalente no intervalo de tempo analisado.

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

hash.sha256

hash.sha256(string)

Descrição

Devolve um hash SHA-256 da string de entrada.

Tipos de dados de parâmetros

STRING

Tipo devolvido

STRING

Exemplos 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

math.abs(numericExpression)

Descrição

Devolve o valor absoluto de uma expressão de número inteiro ou de vírgula flutuante.

Tipos de dados de parâmetros

NUMBER

Tipo devolvido

NUMBER

Exemplos de código

Exemplo 1

Este exemplo devolve True se o evento tiver ocorrido mais de 5 minutos após a hora especificada (em segundos desde a época Unix), independentemente de o evento ter ocorrido antes ou depois da hora especificada. Uma chamada para math.abs não pode depender de várias variáveis nem marcadores de posição. Por exemplo, não pode substituir o valor de tempo codificado de 1643687343 no exemplo seguinte por $e2.metadata.event_timestamp.seconds.

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

math.ceil

math.ceil(number)

Descrição

Devolve o menor número inteiro que não é inferior ao número indicado (arredondamento para cima). Devolve 0 se a entrada for nula ou demasiado grande para caber num int64.

Tipos de dados de parâmetros

FLOAT

Tipo devolvido

INT

Exemplos de código

Esta secção contém exemplos de utilização de math.ceil.

Exemplo 1

Este exemplo devolve o limite superior de um número inteiro.

math.ceil(2.000000) = 2

Exemplo 2

Este exemplo devolve o limite superior de um número negativo.

math.ceil(0-1.200000) = -1

Exemplo 3

Este exemplo devolve 0 como o limite superior de um número demasiado grande para um inteiro de 64 bits.

math.ceil(184467440737095516160.0) = 0

math.floor

math.floor(float_val)

Descrição

Devolve o maior valor inteiro que não é superior ao valor fornecido (arredondamento para baixo). Devolve 0 se a entrada for nula ou demasiado grande para caber num int64.

Tipos de dados de parâmetros

FLOAT

Tipo devolvido

INT

Exemplos de código

Exemplo 1

Este exemplo mostra um caso de número positivo.

math.floor(1.234568) = 1

Exemplo 2

Este exemplo mostra um caso de número negativo.

math.floor(0-1.234568) = -2

Exemplo 3

Este exemplo mostra um caso zero.

math.floor(0.000000) = 0

math.geo_distance

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

Descrição

Devolve a distância entre duas localizações geográficas (coordenadas) em metros. Devolve -1 se as coordenadas forem inválidas.

Tipos de dados de parâmetros

FLOAT, FLOAT, FLOAT, FLOAT

Tipo devolvido

FLOAT

Exemplos de código

Exemplo 1

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

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

Exemplo 2

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

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

Exemplo 3

O exemplo seguinte devolve -1 quando um dos parâmetros é uma coordenada inválida:

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

Exemplo 4

O exemplo seguinte devolve 0 quando as coordenadas são iguais:

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

math.is_increasing

math.is_increasing(num1, num2, num3)

Descrição

Aceita uma lista de valores numéricos (inteiros ou duplos) e devolve True se os valores estiverem por ordem ascendente e False caso contrário.

Tipos de dados de parâmetros

INT|FLOAT, INT|FLOAT, INT|FLOAT

Tipo devolvido

BOOL

Exemplos de código

Exemplo 1

Este exemplo inclui valores semelhantes a datas/horas em segundos.

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

Exemplo 2

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

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

Exemplo 3

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

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

Exemplo 4

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

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

Exemplo 5

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

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

math.log

math.log(numericExpression)

Descrição

Devolve o valor do logaritmo natural de uma expressão de número inteiro ou de vírgula flutuante.

Tipos de dados de parâmetros

NUMBER

Tipo devolvido

NUMBER

Exemplos de código

Exemplo 1

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

math.pow

math.pow(base, exponent)

Descrição

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

Tipos de dados de parâmetros

base: INT|FLOAT expoente: INT|FLOAT

Tipo devolvido

FLOAT

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

math.pow(2.200000, 3) // 10.648

Exemplo 3

Este exemplo mostra uma base de fração e uma potência.

math.pow(2.200000, 1.200000) // 2.575771

Exemplo 4

Este exemplo mostra um caso de potência negativa.

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

Exemplo 5

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

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

Exemplo 6

Este exemplo mostra um caso base negativo.

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

Exemplo 7

Este exemplo mostra um caso base zero.

math.pow(0, 3) // 0

Exemplo 8

Este exemplo mostra um caso de potência zero.

math.pow(9223372036854775807, 0) // 1

Exemplo 9

Este exemplo mostra um registo de base grande.

math.pow(9223372036854775807, 1.200000) // 57262152889751593549824

math.random

math.random()

Descrição

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

Tipo devolvido

FLOAT

Exemplos de código

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

math.round

math.round(numericExpression, decimalPlaces)

Descrição

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

Tipos de dados de parâmetros

NUMBER

Tipo devolvido

NUMBER

Exemplos de código

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

math.sqrt

math.sqrt(number)

Descrição

Devolve a raiz quadrada do número fornecido. Devolve 0 no caso de números negativos.

Tipos de dados de parâmetros

INT|FLOAT

Tipo devolvido

FLOAT

Exemplos de código

Exemplo 1

Este exemplo devolve a raiz quadrada de um argumento int.

math.sqrt(3) = 1.732051

Exemplo 2

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

math.sqrt(-3) = 0.000000

Exemplo 3

Este exemplo devolve a raiz quadrada do argumento zero.

math.sqrt(0) = 0.000000

Exemplo 4

Este exemplo devolve a raiz quadrada de um argumento flutuante.

math.sqrt(9.223372) = 3.037000

Exemplo 5

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

math.sqrt(0-1.200000) = 0.000000

métricas

As funções de métricas podem agregar grandes quantidades de dados do histórico. Pode usar esta opção na sua regra através de metrics.functionName() na secção de resultado.

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

net.ip_in_range_cidr

net.ip_in_range_cidr(ipAddress, subnetworkRange)

Descrição

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

Pode usar o YARA-L para pesquisar eventos UDM em todos os endereços IP numa sub-rede através da declaração net.ip_in_range_cidr(). O IPv4 e o IPv6 são suportados.

Para pesquisar num 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 singulares e repetidos.

Para pesquisar num intervalo de endereços IP, especifique um ipcampo de UDM e um intervalo de Classless Inter-Domain Routing (CIDR). O YARA-L pode processar campos de endereços IP singulares e repetidos.

Tipos de dados de parâmetros

STRING, STRING

Tipo devolvido

BOOL

Exemplos de código

Exemplo 1

Exemplo de IPv4:

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

Exemplo 2

Exemplo de IPv6:

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

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

re.regex

Pode definir a correspondência de expressões regulares no YARA-L 2.0 com qualquer uma das seguintes sintaxes:

• Usar a sintaxe YARA-L: relacionada com eventos. Segue-se uma representação genérica desta sintaxe:

  $e.field = /regex/
  

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

  • Campo ao qual a expressão regular é aplicada.
  • Expressão regular especificada como uma string.

  Segue-se uma representação genérica desta sintaxe:

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

Descrição

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

Notas

• Para corresponder à string exata ou apenas a um prefixo ou um sufixo, inclua os carateres de âncora ^(starting) e $ (ending) na expressão regular. Por exemplo, /^full$/ corresponde exatamente a "full", enquanto /full/ pode corresponder a "fullest", "lawfull" e "joyfully".
• Se o campo UDM incluir carateres de nova linha, o regexp só corresponde à primeira linha do campo UDM. Para aplicar a correspondência total de campos da UDM, adicione um (?s) à expressão regular. Por exemplo, substitua /.*allUDM.*/ por /(?s).*allUDM.*/.
• Pode usar o modificador nocase após as strings para indicar que a pesquisa deve ignorar as letras maiúsculas.

Tipos de dados de parâmetros

STRING, STRING

Tipos de expressões de parâmetros

ANY, ANY

Tipo devolvido

BOOL

Exemplos de código

Exemplo 1

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

re.capture

re.capture(stringText, regex)

Descrição

Captura (extrai) dados de uma string através do padrão de expressão regular fornecido no argumento.

Esta função recebe dois argumentos:

• stringText: a string original a pesquisar.
• regex: a expressão regular que indica o padrão a pesquisar.

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 devolve a primeira substring correspondente completa. Se a expressão regular contiver 1 grupo de captura, devolve a primeira substring correspondente para o grupo de captura. A definição de dois ou mais grupos de captura devolve um erro do compilador.

Tipos de dados de parâmetros

STRING, STRING

Tipo devolvido

STRING

Exemplos de código

Exemplo 1

Neste exemplo, se $e.principal.hostname contiver "aaa1bbaa2", o seguinte seria verdadeiro, porque a função devolve 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 o que está após o símbolo @ num email. Se o campo $e.network.email.from for test@google.com, o exemplo devolve google.com. O exemplo seguinte 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 devolve uma string vazia. Pode omitir eventos em que não ocorra nenhuma correspondência excluindo a string vazia, o que é especialmente importante quando está a usar 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

re.replace(stringText, replaceRegex, replacementText)

Descrição

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

Esta função recebe três argumentos:

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

Devolve uma nova string derivada da string stringText original, onde todas as substrings que correspondem ao padrão em replaceRegex são substituídas pelo valor em replacementText. Pode usar dígitos com barra invertida (\1 a \9) em replacementText para inserir texto correspondente ao grupo entre parênteses correspondente no padrão replaceRegex. Use \0 para se referir a todo o texto correspondente.

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

Tipos de dados de parâmetros

STRING, STRING, STRING

Tipo devolvido

STRING

Exemplos de código

Exemplo 1

Este exemplo captura tudo após o símbolo @ num email, substitui com por org e, em seguida, devolve o resultado. Repare na utilização de funções aninhadas.

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

Exemplo 2

Este exemplo usa dígitos com carateres de escape de barra invertida no argumento replacementText para fazer referência a correspondências com o 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

Tenha em atenção os seguintes casos quando trabalhar com strings vazias e re.replace():

Usar 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, pode usar "^$" como replaceRegex:

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

sample_rate

optimization.sample_rate(byteOrString, rateNumerator, rateDenominator)

Descrição

Esta função determina se deve incluir um evento com base numa estratégia de amostragem determinística. Esta função devolve:

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

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

hash.fingerprint2011(byteOrString) % rateDenominator < rateNumerator

Tipos de dados de parâmetros

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

Tipo devolvido

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

strings.base64_decode(encodedString)

Descrição

Devolve uma string que contém a versão descodificada em base64 da string codificada.

Esta função seleciona uma string codificada em base64 como um argumento. Se encodedString não for uma string codificada em base64 válida, a função devolve encodedString inalterado.

Tipos de dados de parâmetros

STRING

Tipo devolvido

STRING

Exemplos de código

Exemplo 1

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

strings.coalesce

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

Descrição

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

Os argumentos podem ser literais, campos de eventos ou chamadas de funções. Todos os argumentos têm de ser do tipo STRING. Se algum argumento for um campo de evento, os atributos têm de ser do mesmo evento.

Tipos de dados de parâmetros

STRING

Tipo devolvido

STRING

Exemplos de código

Exemplo 1

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

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

Exemplo 2

O exemplo seguinte chama a função coalesce com mais de dois argumentos. Esta 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 unidos nesta chamada é a mesma ordem em que são enumerados na condição da regra:

1. $e.principal.ip é avaliado primeiro.
2. Em seguida, é avaliado o elemento $e.src.ip.
3. Em seguida, é avaliado o elemento $e.target.ip.
4. Por último, a string "No IP" é devolvida como um valor predefinido se os campos anteriores não estiverem definidos.ip

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

Exemplo 3

O exemplo seguinte tenta unir principal.hostname do evento $e1 e do evento $e2. Devolve 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

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

Descrição

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

Se algum argumento for um campo de evento, os atributos têm de ser do mesmo evento.

Tipos de dados de parâmetros

STRING, FLOAT, INT

Tipo devolvido

STRING

Exemplos de código

Exemplo 1

O exemplo seguinte inclui uma variável de string e uma variável inteira como argumentos. Ambas as funções principal.hostname e principal.port são do mesmo evento, $e, e são concatenadas para devolver uma string.

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

Exemplo 2

O exemplo seguinte 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 seguinte inclui uma variável de string e um literal flutuante como argumentos. Quando representados como strings, os números de vírgula flutuante 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 de vírgula flutuante que excedam dezasseis 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 seguinte inclui uma variável de string, um literal de string, uma variável inteira e um literal flutuante como argumentos. Todas as variáveis são do mesmo evento, $e, e são concatenadas com os literais para devolver uma string.

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

Exemplo 5

O exemplo seguinte tenta concatenar principal.port do evento $e1 com principal.hostname do evento $e2. Devolve 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

strings.contains( str, substr )

Descrição

Devolve true se uma determinada string contiver a substring especificada. Caso contrário, devolve false.

Tipos de dados de parâmetros

STRING, STRING

Tipo devolvido

BOOL

Exemplos de código

Exemplo 1

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

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

Exemplo 2

Este exemplo devolve o valor falso porque a string não tem a substring "that".

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

strings.count_substrings

strings.count_substrings(string_to_search_in, substring_to_count)

Descrição

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

Tipos de dados de parâmetros

STRING, STRING

Tipo devolvido

INT

Exemplos de código

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

Exemplo 1

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

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

Exemplo 2

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

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

Exemplo 3

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

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

Exemplo 4

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

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

Exemplo 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 caráter 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 caráter e mais de uma ocorrência. Realça a limitação com ocorrências de subcadeias sobrepostas

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

strings.extract_domain

strings.extract_domain(url_string)

Descrição

Extrai o domínio de uma string.

Tipos de dados de parâmetros

STRING

Tipo devolvido

STRING

Exemplos de código

Exemplo 1

Este exemplo mostra uma string vazia

strings.extract_domain("") = ""

Exemplo 2

string aleatória, não um URL

strings.extract_domain("1234") = ""

Exemplo 3

várias barras invertidas

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

Exemplo 4

Carateres não alfabéticos processados corretamente

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

Exemplo 5

Tratamento de URIs

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

Exemplo 6

Vários carateres antes do URL real

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

Exemplo 7

carateres especiais no URI #

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

Exemplo 8

carateres 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

strings.extract_hostname(string)

Descrição

Extrai o nome do anfitrião de uma string. Esta função é sensível a maiúsculas e minúsculas.

Tipos de dados de parâmetros

STRING

Tipo devolvido

STRING

Exemplos de código

Exemplo 1

Este exemplo devolve uma string vazia.

strings.extract_hostname("") = ""

Exemplo 2

string aleatória, não um URL

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

Exemplo 3

várias barras invertidas

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

Exemplo 4

Carateres não ingleses processados corretamente

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

Exemplo 5

Tratamento de URIs

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

Exemplo 6

Vários carateres antes do URL real

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

Exemplo 7

carateres especiais no URI #

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

Exemplo 8

carateres especiais no URL #

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

strings.from_base64

strings.from_base64(base64_encoded_string)

Descrição

A função converte um valor STRING codificado em base64 num valor BYTES binário não processado. As chamadas de funções com valores que não podem ser convertidos devolvem um valor BYTES vazio por predefinição.

Tipos de dados de parâmetros

STRING

Tipo devolvido

BYTES

Exemplos de código

Conversão de string codificada em Base64 para bytes

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

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

Conversão falhada (predefinição para bytes vazios)

A função reverte para bytes vazios se o valor fornecido for inválido.

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

strings.from_hex

strings.from_hex(hex_string)

Descrição

Devolve os bytes associados à string hexadecimal fornecida.

Tipos de dados de parâmetros

STRING

Tipo devolvido

BYTES

Exemplos de código

Obtém bytes associados a uma determinada string hexadecimal.

Exemplo 1

Este exemplo mostra conversões de carateres 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 strings hexadecimais.

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

Exemplo 4

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

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

strings.ltrim

strings.ltrim(string_to_trim, cutset)

Descrição

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

Tipos de dados de parâmetros

STRING, STRING

Tipo devolvido

STRING

Exemplos de código

Seguem-se exemplos de utilização.

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

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

Exemplo 4

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

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

strings.reverse

strings.reverse(STRING)

Descrição

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

Tipos de dados de parâmetros

STRING

Tipo devolvido

STRING

Exemplos de código

Exemplo 1

O exemplo seguinte transmite uma string curta.

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

Exemplo 2

O exemplo seguinte transmite uma string vazia.

strings.reverse("") = ""

Exemplo 3

O exemplo seguinte passa um palíndromo.

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

strings.rtrim

strings.rtrim(string_to_trim, cutset)

Descrição

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

Tipos de dados de parâmetros

STRING, STRING

Tipo devolvido

STRING

Exemplos de código

Seguem-se exemplos de utilização.

Exemplo 1

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

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

Exemplo 2

O exemplo seguinte passa uma string vazia como o segundo argumento.

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

Exemplo 3

O exemplo seguinte passa uma string vazia como o primeiro argumento e uma string não vazia como o segundo argumento.

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

Exemplo 4

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

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

strings.to_lower

strings.to_lower(stringText)

Descrição

Esta função recebe uma string de entrada e devolve uma string depois de alterar todos os carateres para minúsculas

Tipos de dados de parâmetros

STRING

Tipo devolvido

STRING

Exemplos de código

Exemplo 1

O exemplo seguinte devolve true.

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

strings.to_upper

strings.to_upper(string_val)

Descrição

Devolve a string original com todos os carateres alfabéticos em maiúsculas.

Tipos de dados de parâmetros

STRING

Tipo devolvido

STRING

Exemplos de código

Exemplo 1

O exemplo seguinte devolve o argumento fornecido em maiúsculas.

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

strings.trim

strings.trim(string_to_trim, cutset)

Descrição

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

Tipos de dados de parâmetros

STRING, STRING

Tipo devolvido

STRING

Exemplos de código

Seguem-se exemplos de utilização.

Exemplo 1

No exemplo seguinte, a mesma string é transmitida como a string de entrada e o conjunto de caracteres a remover, o que resulta numa string vazia.

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

Exemplo 2

No exemplo seguinte, é transmitida uma string vazia como o conjunto de corte, o que resulta na string original str porque não existem carateres especificados no conjunto de corte a remover.

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

Exemplo 3

No exemplo seguinte, a função produz uma string vazia porque a string de entrada já está vazia e não existem carateres para remover.

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

Exemplo 4

No exemplo seguinte, a função produz str porque a função trim remove o seguinte:

• espaços em branco finais em "a aastraa aa "
• Os carateres especificados no cutset (espaço, a)

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

strings.url_decode

strings.url_decode(url_string)

Descrição

Dada uma string de URL, descodifique os carateres de escape e processe os carateres UTF-8 que foram codificados. Devolve uma string vazia se a descodificação falhar.

Tipos de dados de parâmetros

STRING

Tipo devolvido

STRING

Exemplos de código

Exemplo 1

Este exemplo mostra um 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 carateres 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 descodificação de URL de exemplo.

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

timestamp.as_unix_seconds

timestamp.as_unix_seconds(timestamp [, time_zone])

Descrição

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

• timestamp é uma string que representa uma data/hora de época válida. O formato tem de ser %F %T.
• time_zone é opcional e é uma string que representa um fuso horário. Se for omitido, o valor predefinido é GMT. Pode especificar fusos horários através de literais de string. As opções são as seguintes:
  • O nome da base de dados TZ, por exemplo, America/Los_Angeles. Para mais informações, consulte a lista de fusos horários da base de dados TZ na Wikipédia.
  • A diferença do fuso horário em relação ao UTC, no formato(+|-)H[H][:M[M]], por exemplo: "-08:00".

Seguem-se exemplos de especificadores time_zone válidos, que pode transmitir como o segundo argumento para funções de extração de tempo:

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

Tipos de dados de parâmetros

STRING, STRING

Tipo devolvido

INT

Exemplos de código

Exemplo 1

Indicação de tempo de época válida

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

Exemplo 2

Indicação de tempo da época válida 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

timestamp.current_seconds()

Descrição

Devolve um número inteiro que representa a hora atual em segundos Unix. Isto é aproximadamente igual à data/hora de deteção e baseia-se no momento em que a regra é executada. Esta função é um sinónimo da função timestamp.now().

Tipos de dados de parâmetros

NONE

Tipo devolvido

INT

Exemplos de código

Exemplo 1

O exemplo seguinte devolve true se o certificado tiver expirado há mais de 24 horas. Calcula a diferença de tempo subtraindo os segundos Unix atuais e, em seguida, comparando-os com um operador de superior a.

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

timestamp.get_date

timestamp.get_date(unix_seconds [, time_zone])

Descrição

Esta função devolve uma string no formato YYYY-MM-DD, que representa o dia em que uma indicação de tempo se encontra.

• 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 for omitido, a predefinição é "GMT". Pode especificar fusos horários através de literais de string. As opções são:
  • O nome da base de dados TZ, por exemplo, "America/Los_Angeles". Para mais informações, consulte a coluna "Nome da base de dados de fusos horários" desta página
  • A diferença do fuso horário em relação ao UTC, no formato(+|-)H[H][:M[M]], por exemplo: "-08:00".

Seguem-se exemplos de especificadores de time_zone válidos, que pode transmitir como o segundo argumento para funções de extração de tempo:

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

Tipos de dados de parâmetros

INT, STRING

Tipo devolvido

STRING

Exemplos de código

Exemplo 1

Neste exemplo, o argumento time_zone é omitido, pelo que é usado o valor predefinido "GMT".

$ts = $e.metadata.collected_timestamp.seconds

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

Exemplo 2

Este exemplo usa um literal de string para definir o time_zone.

$ts = $e.metadata.collected_timestamp.seconds

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

timestamp.get_minute

timestamp.get_minute(unix_seconds [, time_zone])

Descrição

Esta função devolve 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 for omitido, a predefinição é "GMT". Pode especificar fusos horários através de literais de string. As opções são:
  • O nome da base de dados TZ, por exemplo, "America/Los_Angeles". Para mais informações, consulte a coluna "Nome da base de dados de fusos horários" desta página
  • A diferença do fuso horário em relação ao UTC, no formato(+|-)H[H][:M[M]], por exemplo: "-08:00".

Seguem-se exemplos de especificadores time_zone válidos, que pode transmitir como o segundo argumento para funções de extração de tempo:

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

Tipos de dados de parâmetros

INT, STRING

Tipo devolvido

INT

Exemplos de código

Exemplo 1

Neste exemplo, o argumento time_zone é omitido, pelo que é usado o valor predefinido "GMT".

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_hour($ts) = 15

Exemplo 2

Este exemplo usa um literal de string para definir o time_zone.

$ts = $e.metadata.collected_timestamp.seconds

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

timestamp.get_hour

timestamp.get_hour(unix_seconds [, time_zone])

Descrição

Esta função devolve 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 for omitido, a predefinição é "GMT". Pode especificar fusos horários através de literais de string. As opções são:
  • O nome da base de dados TZ, por exemplo, "America/Los_Angeles". Para mais informações, consulte a coluna "Nome da base de dados de fusos horários" desta página
  • A diferença do fuso horário em relação ao UTC, no formato(+|-)H[H][:M[M]], por exemplo: "-08:00".

Seguem-se exemplos de especificadores time_zone válidos, que pode transmitir como o segundo argumento para funções de extração de tempo:

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

Tipos de dados de parâmetros

INT, STRING

Tipo devolvido

INT

Exemplos de código

Exemplo 1

Neste exemplo, o argumento time_zone é omitido, pelo que é usado o valor predefinido "GMT".

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_hour($ts) = 15

Exemplo 2

Este exemplo usa um literal de string para definir o time_zone.

$ts = $e.metadata.collected_timestamp.seconds

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

timestamp.get_day_of_week

timestamp.get_day_of_week(unix_seconds [, time_zone])

Descrição

Esta função devolve 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 fuso horário. Se for omitido, a predefinição é "GMT". Pode especificar fusos horários através de literais de string. As opções são:
  • O nome da base de dados TZ, por exemplo, "America/Los_Angeles". Para mais informações, consulte a coluna "Nome da base de dados de fusos horários" desta página
  • A diferença do fuso horário em relação ao UTC, no formato(+|-)H[H][:M[M]], por exemplo: "-08:00".

Seguem-se exemplos de especificadores de time_zone válidos, que pode transmitir como o segundo argumento para funções de extração de tempo:

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

Tipos de dados de parâmetros

INT, STRING

Tipo devolvido

INT

Exemplos de código

Exemplo 1

Neste exemplo, o argumento time_zone é omitido, pelo que é usado o valor predefinido "GMT".

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_day_of_week($ts) = 6

Exemplo 2

Este exemplo usa um literal de string para definir o time_zone.

$ts = $e.metadata.collected_timestamp.seconds

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

timestamp.get_timestamp

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

Descrição

Esta função devolve uma string no formato YYYY-MM-DD, que representa o dia em que uma indicação de tempo se encontra.

• 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 da data/hora. Se for omitido, o valor predefinido é %F %T. Pode especificar o formato através de uma string de formato de data/hora ou de uma das seguintes granularidades de tempo: SECOND, MINUTE, HOUR, DATE, WEEK, MONTH ou YEAR. Para mais opções de formatação, consulte o artigo Formate elementos para partes de data e hora
• time_zone é opcional e é uma string que representa um fuso horário. Se for omitido, o valor predefinido é GMT. Pode especificar fusos horários através de literais de string. As opções são as seguintes:
  • O nome da base de dados de fusos horários (TZ) da IANA, por exemplo, America/Los_Angeles. Para mais informações, consulte a lista de fusos horários da base de dados TZ na Wikipédia.
  • A diferença do fuso horário em relação ao UTC, no formato (+|-)H[H][:M[M]], por exemplo: "-08:00".

Seguem-se exemplos de especificadores time_zone válidos, que pode transmitir como o segundo argumento para funções de extração de tempo:

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

Tipos de dados de parâmetros

INT, STRING, STRING

Tipo devolvido

STRING

Exemplos de código

Exemplo 1

Neste exemplo, o argumento time_zone é omitido, pelo que é usado o valor predefinido GMT.

$ts = $e.metadata.collected_timestamp.seconds

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

Exemplo 2

Este exemplo usa um literal de string 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 um literal de string para definir o timestamp_format.

$ts = $e.metadata.collected_timestamp.seconds

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

Exemplo 4

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

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

Exemplo 5

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

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

Exemplo 6

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

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

Exemplo 7

Este exemplo formata uma indicação de tempo Unix como uma string com granularidade de dias.

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

Exemplo 8

Este exemplo formata uma data/hora Unix como uma string com granularidade semanal.

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

Exemplo 9

Este exemplo formata uma data/hora Unix como uma string com uma granularidade mensal.

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

Exemplo 10

Este exemplo formata uma data/hora Unix como uma string com granularidade anual.

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

timestamp.get_week

timestamp.get_week(unix_seconds [, time_zone])

Descrição

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

• unix_seconds é um número inteiro que representa o número de segundos 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 for omitido, a predefinição é "GMT". Pode especificar fusos horários através de literais de string. As opções são:
  • O nome da base de dados TZ, por exemplo, "America/Los_Angeles". Para mais informações, consulte a coluna "Nome da base de dados de fusos horários" desta página
  • A diferença do fuso horário em relação ao UTC, no formato(+|-)H[H][:M[M]], por exemplo: "-08:00".

Seguem-se exemplos de especificadores time_zone válidos, que pode transmitir como o segundo argumento para funções de extração de tempo:

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

Tipos de dados de parâmetros

INT, STRING

Tipo devolvido

INT

Exemplos de código

Exemplo 1

Neste exemplo, o argumento time_zone é omitido, pelo que é usado o valor predefinido "GMT".

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_week($ts) = 0

Exemplo 2

Este exemplo usa um literal de string para definir o time_zone.

$ts = $e.metadata.collected_timestamp.seconds

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

timestamp.now

timestamp.now()

Descrição

Devolve o número de segundos desde 01/01/1970 às 00:00:00 UTC. Isto também é conhecido como tempo de época Unix.

Tipo devolvido

INT

Exemplos de código

Exemplo 1

O exemplo seguinte devolve uma data/hora para o código executado a 22 de maio de 2024 às 18:16:59.

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

window.avg

window.avg(numeric_values [, should_ignore_zero_values])

Descrição

Devolve a média dos valores de entrada (que podem ser números inteiros ou números de vírgula flutuante). Definir o segundo argumento opcional como verdadeiro ignora os valores zero.

Tipos de dados de parâmetros

INT|FLOAT

Tipo devolvido

FLOAT

Exemplos de código

Exemplo 1

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

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

Exemplo 2

Este exemplo mostra a média de flutuação.

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 entradas negativas

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 devoluções 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

Exemplo 5

A 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

window.first(values_to_sort_by, values_to_return)

Descrição

Esta função de agregação devolve um valor de string derivado de um evento com o valor int correlacionado mais baixo no período de correspondência. Um exemplo de utilização é obter o userid do evento com a data/hora mais baixa na janela de correspondência (evento mais antigo).

Tipos de dados de parâmetros

INT, STRING

Tipo devolvido

STRING

Exemplos de código

Obtenha 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

window.last(values_to_sort_by, values_to_return)

Descrição

Esta função de agregação devolve um valor de string derivado de um evento com o valor int correlacionado mais elevado na janela de correspondência. Um exemplo de utilização é obter o userid do evento com a data/hora mais baixa na janela de correspondência (data/hora mais alta).

Tipos de dados de parâmetros

INT, STRING

Tipo devolvido

STRING

Exemplos de código

Obtenha um valor de string derivado de um evento com o valor int mais correlacionado na janela de correspondência.

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

window.median

window.median(numeric_values, should_ignore_zero_values)

Descrição

Devolve a mediana dos valores de entrada. Se existirem 2 valores medianos, apenas 1 é escolhido de forma não determinística como o valor de retorno.

Tipos de dados de parâmetros

INT|FLOAT, BOOL

Tipo devolvido

FLOAT

Exemplos de código

Exemplo 1

Este exemplo devolve 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 devolve 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 devolve a mediana quando a entrada inclui alguns valores zero que devem ser ignorados.

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

Exemplo 4

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

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

Exemplo 5

Este exemplo mostra que, quando existem várias medianas, apenas é devolvida uma mediana.

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

window.mode

window.mode(values)

Descrição

Devolve a moda dos valores de entrada. No caso de existirem vários valores de modo possíveis, apenas um desses valores é escolhido de forma não determinística como o valor de retorno.

Tipos de dados de parâmetros

INT|FLOAT|STRING

Tipo devolvido

STRING

Exemplos de código

Exemplo 1

Obtenha 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

window.stddev(numeric_values)

Descrição

Devolve o desvio padrão dos valores de entrada numa janela de correspondência.

Tipos de dados de parâmetros

INT|FLOAT

Tipo devolvido

FLOAT

Exemplos de código

Exemplo 1

Este exemplo devolve o desvio padrão de números inteiros numa 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 devolve o desvio padrão de números de vírgula flutuante numa 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 devolve o desvio padrão numa 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 devolve um 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

Exemplo 5

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

window.variance(values)

Descrição

Esta função devolve a variância especificada dos valores de entrada.

Tipos de dados de parâmetros

INT|FLOAT

Tipo devolvido

FLOAT

Exemplos de código

Exemplo 1

Este exemplo devolve 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 devolve a variância de todos os números de vírgula flutuante.

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

Exemplo 3

Este exemplo devolve a variância de números negativos.

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

Exemplo 4

Este exemplo devolve um valor de variância pequeno.

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

Exemplo 5

Este exemplo devolve uma variância zero.

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

Exemplo 6

Este exemplo devolve a variância de números positivos e negativos.

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

bytes.to_base64

bytes.to_base64(bytes, optional_default_string)

Descrição

A função converte um valor bytes num valor base64 encoded string. As chamadas de funções com valores que não podem ser convertidos devolvem uma string vazia por predefinição.

Tipos de dados de parâmetros

BYTES, STRING

Tipo devolvido

STRING

Exemplos de código

Bytes binários não processados para string codificada em Base64

A função converte os bytes binários não processados numa string codificada em base64.

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

Conversão falhada (predefinição para a string fornecida opcionalmente)

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

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

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

Pode atribuir o resultado de uma chamada de função a um marcador de posição na secção events. Por exemplo:

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

Em seguida, pode usar as variáveis de marcadores de posição nas secções match, condition e outcome. No entanto, existem duas limitações com a atribuição de funções a marcadores de posição:

1. Todos os marcadores de posição na função para a atribuição de marcadores de posição têm de ser atribuídos a uma expressão que contenha um campo de evento. Por exemplo, os seguintes exemplos são válidos:

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

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

   No entanto, o seguinte exemplo é 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 deve depender de um e exatamente um evento. No entanto, é possível usar mais de um campo do mesmo evento nos argumentos de chamadas de funções. Por exemplo, o seguinte é válido:

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

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

   No entanto, o seguinte é inválido:

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

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

Sintaxe das listas de referências

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

Pode usar listas de referências nas secções events ou outcome. Segue-se a sintaxe para usar vários tipos de listas de referência numa 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 pode usar o operador not e o operador nocase com listas de referência, como mostrado no exemplo seguinte:

// 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 listas REGEX.

Por motivos de desempenho, o motor de deteção restringe a utilização da lista de referências.

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

Verificação de tipos

O Google SecOps realiza a verificação de tipos em relação à sua sintaxe YARA-L à medida que cria regras na interface. Os erros de verificação de tipos apresentados ajudam a rever a regra de forma a confirmar que funciona corretamente.

Seguem-se 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 deteção

As deteções de regras de vários eventos contêm exemplos de eventos para fornecer contexto acerca dos eventos que causaram a deteção. Existe um limite de até 10 exemplos de eventos para cada variável de evento definida na regra. Por exemplo, se uma regra definir 2 variáveis de evento, cada deteção pode ter até 20 exemplos de eventos. O limite aplica-se a cada variável de evento separadamente. Se uma variável de evento tiver 2 eventos aplicáveis nesta deteção e a outra variável de evento tiver 15 eventos aplicáveis, a deteção resultante contém 12 exemplos de eventos (2 + 10).

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

Se quiser mais informações sobre os eventos que causaram a deteção, pode usar agregações na secção de resultados para gerar informações adicionais na deteção.

Se estiver a ver deteções na IU, pode transferir todas as amostras de eventos para uma deteção. Para mais informações, consulte o artigo Transfira eventos.

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