Sintaxe da seção de correspondência

Compatível com:

Google SecOps SIEM

Na YARA-L 2.0, a seção match fornece o mecanismo para correlação de vários eventos. Ela define a lógica para agrupar eventos em uma única detecção vinculando atributos comuns, como usuários, endereços IP ou hashes de arquivo, em um limite temporal específico.

Use a seção match para os seguintes casos de uso:

Vincule dois ou mais eventos distintos em uma regra.
Agregue dados na Pesquisa e nos painéis, como a contagem de tentativas de login com falha em um período específico.

Definir critérios de correlação

Use-o para definir os critérios dessa correlação especificando o seguinte:

Campos de agrupamento (chaves): variáveis (como $user ou $ip) que precisam ter valores idênticos em todos os eventos (definidos na seção events) para acionar uma correspondência.
Restrição de tempo: o período em que os eventos agrupados precisam ocorrer para atender à regra ou agregação. Em "Regras", isso define a janela de detecção. Em "Pesquisa e painéis", isso define a janela de agregação ou correlação.

Comparar os requisitos de recursos

A tabela a seguir detalha as comparações para regras de pesquisa e painéis.

Recurso	Requisito de regras	Suporte para pesquisa e painéis
Tipos de variáveis	É necessário usar os marcadores de posição definidos na seção `events`.	Aceita marcadores de posição e campos diretos da UDM.
Janela de tempo	Define o limite de detecção.	Define o bucket de agregação ou correlação.
Sintaxe	`over <number><m/h/d>` (por exemplo, `10m`, `2h`, `1d`)	`over <number><m/h/d>`
Limites	Mín.: `1m` / Máx.: `48h`	Mín.: `1m` / Máx.: `48h`

Tipos de janela compatíveis

A YARA-L 2.0 usa diferentes comportamentos de janela para determinar como o tempo é dividido e como os eventos são agrupados. É possível agrupar campos de evento e marcadores de posição na seção match por uma granularidade de tempo especificada usando uma das seguintes janelas compatíveis.

Tipo de janela compatível	Sintaxe	Descrição	Caso de uso comum
Hop	`$key over <duration>`	Intervalos de tempo sobrepostos (comportamento padrão).	Correlação geral de vários eventos.
Tumbling	`$key by <duration>`	Intervalos de tempo de tamanho fixo, contínuos e sem sobreposição.	Quantificar a atividade em blocos de até uma hora (por exemplo, `$user by 30m`).
Deslizamento	`$key over <duration> [before\|after] $pivot`	Intervalos de tempo ancorados em um evento "pivô" específico.	Sequência estrita (por exemplo, `File Download after Login`).

Exemplo de sintaxe:

match:
  $user, $source_ip over 5m  // Groups events by user and IP within a 5-minute window

Janela de salto

Uma janela de salto é o comportamento padrão para regras de vários eventos. Ele cria intervalos de tempo sobrepostos para garantir que os eventos que acontecem perto dos limites de uma janela não sejam perdidos.

Sintaxe: $key over <duration> (por exemplo, $user over 30m)
Caso de uso: ideal para detecção quando você precisa garantir que um cenário específico seja capturado, não importa exatamente quando o intervalo da janela começa ou termina.
Suporte: compatível com agregação em pesquisas e painéis (por exemplo, count).

Por padrão, as consultas da YARA-L com uma seção match usam janelas de salto para correlacionar vários eventos ao longo do tempo. O período de execução da consulta é dividido em um conjunto de janelas de salto fixas e sobrepostas. Embora a duração desses períodos seja especificada na seção match, o intervalo de sobreposição e o alinhamento de período são definidos pelo sistema e não podem ser configurados pelo usuário. Em seguida, os eventos são correlacionados em cada uma dessas janelas predeterminadas.

Exemplo: janelas de salto sobrepostas para correlação contínua

O exemplo a seguir mostra uma consulta executada no intervalo de tempo [1:00, 2:00], com uma seção match $user over 30m, em que um possível conjunto de janelas de salto sobrepostas que podem ser geradas é [1:00, 1:30], [1:03, 1:33] e [1:06, 1:36].

rule hop_window_brute_force_example {
meta:
  description = "Detects multiple failed logins within a shifting 30-minute window."
  severity = "Medium"

events:
  $login.metadata.event_type = "USER_LOGIN"
  $login.extensions.auth.auth_status = "FAILURE"
  $login.principal.user.userid = $user

match:
  // This creates the overlapping windows (e.g., 1:00-1:30, 1:03-1:33)
  $user over 30m

condition:
  // This will trigger if 10 or more failures fall into any single 30m hop
  #login >= 10
}

Exemplo: correlação de vários eventos usando uma janela de salto

O exemplo a seguir representa o padrão para a maioria das regras de vários eventos. Ele captura eventos que ocorrem no mesmo período geral.

rule hop_window_example {
meta:
  description = "Detect a user with a failed login followed by a success within 30m"

events:
  $e1.metadata.event_type = "USER_LOGIN"
  $e1.extensions.auth.auth_status = "FAILURE"
  $e1.principal.user.userid = $user

  $e2.metadata.event_type = "USER_LOGIN"
  $e2.extensions.auth.auth_status = "SUCCESS"
  $e2.principal.user.userid = $user

match:
  $user over 30m  // This is a hop window

condition:
  $e1 and $e2
}

Exemplo: comparação de janelas de salto

Para identificar uma tentativa de força bruta, uma janela de 10m agrupa todas as falhas de USER_LOGIN. Em seguida, o condition avalia se a contagem (#e) nesse bucket específico de 10 minutos excede seu limite.

rule failed_logins
{
meta:
  author = "Security Team"
  description = "Detects multiple failed user logins within 10-minute windows."
  severity = "HIGH"

events:
  $e.metadata.event_type = "USER_LOGIN"
  $e.security_result.action = "FAIL"
  $user = $e.target.user.userid

match:
  $user over 10m

condition:
  #e >= 5
}

A seção match encontra usuários com falha no login em um novo local em um intervalo de 10 minutos (10m):

match:
  $user over 10m

Janelas em cascata

Uma janela em cascata segmenta um fluxo de dados em intervalos de tempo de tamanho fixo, contínuos e sem sobreposição. O carimbo de data/hora de cada evento se enquadra em exatamente uma janela. Não há sobreposição entre as janelas em cascata. Isso é diferente de uma janela deslizante ou de salto, que pode ter intervalos de tempo sobrepostos.

Para implementar uma janela rotativa, use o operador by na seção match.

As janelas em cascata dividem o tempo em blocos contínuos e consecutivos. Exemplo:

by 1h: cria janelas para cada hora (por exemplo, [00:00:00-00:59:59], [01:00:00-01:59:59] etc.).
by 10m: cria janelas para cada intervalo de 10 minutos (por exemplo, [00:00:00-00:09:59], [00:10:00-00:19:59] etc.).

Casos de uso

Use janelas rotativas quando precisar:

Analise eventos em blocos de tempo distintos e não sobrepostos.
Verifique se apenas uma detecção é produzida para uma determinada entidade (conforme definido pelas variáveis de correspondência) em cada intervalo de tempo fixo, independentemente de quantas vezes o evento ocorre.
Contar entidades únicas em períodos fixos.

Comportamento de eliminação de duplicação

Uma característica principal das janelas de rolagem é como as detecções são processadas em cada janela para o mesmo conjunto de variáveis de correspondência:

Uma detecção por janela:para um determinado conjunto de valores das variáveis de correspondência (por exemplo, um $userid específico), no máximo uma detecção é gerada para qualquer janela rotativa única.
O primeiro a chegar vence:os primeiros eventos ingeridos que atendem às condições da regra para esse conjunto de variáveis de correspondência em uma janela específica acionam a detecção.
Deduplicação:eventos subsequentes que corresponderem aos critérios na mesma instância de janela não vão gerar outras detecções.

Sintaxe

A sintaxe na seção match é:

match:
  $variable by <duration>

em que:

$variable é a variável de marcador de posição que você está usando para correspondência.
<duration> é um número seguido por uma unidade de tempo:
- m: minuto
- h: hora
- d: dia
Especifique um mínimo de um minuto e um máximo de 72 horas ou três dias.

Exemplo

A regra a seguir agrupa os logins por $userid em janelas de uma hora não sobrepostas (por exemplo, [00:00:00-00:59:59], [01:00:00-01:59:59] etc.):

rule TumblingWindowExample {
  meta:
    description = "Example using a 1-hour tumbling window"
  events:
    $e.metadata.event_type = "USER_LOGIN"
    $e.principal.user.userid = $userid
  match:
    $userid by 1h
  condition:
    $e
}

Confira abaixo um exemplo de comportamento de detecção para user = "alex":

Evento 1: Alex faz login às 00h30. Isso se enquadra na janela [00:00:00-00:59:59]. Uma detecção é gerada para Alex nessa janela.
Evento 2: outro usuário, "taylor", faz login às 00h45. Isso também se enquadra em [00:00:00-00:59:59], mas como o $userid é diferente, uma detecção separada é gerada para Taylor nessa janela.
Evento 3: Alex faz login novamente às 00h40. Isso ainda está dentro da janela [00:00:00-00:59:59]. Como já existe uma detecção para Alex nessa janela, o evento é duplicado. Nenhuma nova detecção é gerada.
Evento 4: Alex faz login às 01h20. Isso se enquadra na próxima janela, [01:00:00-01:59:59]. Uma nova detecção é gerada para Alex nessa nova janela.

Embora o Evento 1 e o Evento 4 de Alice tenham ocorrido com menos de uma hora de diferença, eles se enquadram em detecções separadas porque o Evento 4 cruza o limite da janela fixa.

Janela deslizante

Use uma janela deslizante quando precisar pesquisar eventos que ocorrem em uma ordem estrita e relativa (por exemplo, e1 ocorre até dois minutos depois de e2). Ao contrário das janelas fixas, uma janela deslizante é acionada por cada ocorrência do $pivot_event designado usando esta sintaxe:

after: a janela começa no carimbo de data/hora do evento de pivô e se estende para frente.
before: a janela termina no carimbo de data/hora do evento de pivô e se estende para trás.

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

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

Sintaxe: $key over <duration> before|after $<pivot_event>
Chaves de agrupamento: campos comuns (por exemplo, $user, $ip) usados para vincular eventos.
Duração: o deslocamento de tempo do evento de tabela dinâmica (por exemplo, 5m, 1h).
Casos de uso:
- Sequência estrita: detecta uma cadeia de ataques em que a ordem é necessária (por exemplo, uma criação de usuário seguida de uma elevação de privilégios).
- Tempo relativo: encontre um evento que ocorra em um período específico de um "gatilho" (por exemplo, um evento Process Start seguido por um Network Connection em 30 segundos).
- Detecção de ausência: identifica quando um evento obrigatório de "limpeza" ou "heartbeat" não ocorre após um evento de início (por exemplo, um Database Backup Start sem um evento End correspondente).

Exemplos válidos de janela deslizante

Confira a seguir exemplos de janelas deslizantes válidas:

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

Exemplo: correlação prospectiva com janelas deslizantes (`after`)

O exemplo a seguir demonstra como detectar uma sequência de eventos em que o segundo precisa ocorrer dentro de um período específico após um evento principal de "acionamento" ou pivô. Isso é útil para detectar movimentos laterais rápidos ou ações de acompanhamento automatizadas.

rule sliding_window_after_example {
meta:
  description = "Detect a network connection occurring within 1 minute after a suspicious process launch."
  severity = "High"

events:
  $proc.metadata.event_type = "PROCESS_LAUNCH"
  $proc.principal.hostname = $host

  $net.metadata.event_type = "NETWORK_HTTP"
  $net.principal.hostname = $host

match:
  // $proc is the pivot; the 1-minute window starts at the $proc timestamp
  $host over 1m after $proc

condition:
  $proc and $net
}

Exemplo: correlação retrospectiva com janelas deslizantes (`before`)

Use uma janela deslizante "before" para investigar a atividade que antecedeu um alerta específico. Isso é usado com frequência na análise da causa principal para identificar o que aconteceu imediatamente antes de uma detecção crítica.

rule sliding_window_before_example {
meta:
  description = "Identify file modifications occurring in the 5 minutes before a ransomware alert."
  severity = "Critical"

events:
  $file.metadata.event_type = "FILE_MODIFICATION"
  $file.principal.hostname = $host

  $alert.metadata.event_type = "ANTIVIRUS_DETECTION"
  $alert.metadata.product_name = "Premium_AV"
  $alert.principal.hostname = $host

match:
  // $alert is the pivot; the 5-minute window ends at the $alert timestamp
  $host over 5m before $alert

condition:
  $file and $alert
}

Desempenho e práticas recomendadas

As janelas deslizantes exigem mais capacidade de processamento do que as janelas padrão (de salto) porque são calculadas para cada ocorrência do evento de pivô e podem resultar em um desempenho mais lento.

Siga estas diretrizes para ter uma performance ideal em regras, pesquisas e painéis:

Priorize janelas de salto: use a janela de salto padrão, a menos que a sequência específica de eventos (pedido A e depois pedido B) seja necessária para a lógica de detecção. Use janelas deslizantes apenas quando a sequência de eventos for essencial ou quando você estiver procurando eventos ausentes.
Use filtros de carimbo de data/hora para melhorar a performance: se você só precisa garantir que um evento aconteceu depois de outro, uma comparação de carimbo de data/hora na seção events ou condition geralmente é mais eficiente do que uma janela deslizante. Por exemplo:

$e1.metadata.event_timestamp.seconds < $e2.metadata.event_timestamp.seconds

Design de vários eventos: evite usar janelas deslizantes para consultas de evento único. As janelas deslizantes são projetadas para correlação de vários eventos. Para a lógica de evento único, as seguintes diretrizes se aplicam:
- Use várias variáveis de evento e atualize a seção condition.
- Remova toda a seção match se a correlação não for necessária.
- Se quiser, adicione filtros de carimbo de data e hora em vez de usar uma janela deslizante. Por exemplo:
  $permission_change.metadata.event_timestamp.seconds < $file_creation.metadata.event_timestamp.seconds

Entender o limite temporal

A seção match divide os eventos em grupos com base nas chaves de agrupamento. A duração especificada define o limite temporal para cada grupo:

Inclusão: apenas os eventos dentro da janela são transmitidos para a avaliação de condition dessa correspondência específica.
Exclusão: eventos fora da janela são ignorados para esse grupo de correspondência específico, evitando que eventos não relacionados acionem um falso positivo.

Valores zero na seção `match`

O Google SecOps filtra implicitamente os valores zero para todos os marcadores de posição usados na seção match ("" para string, 0 para números, false para booleanos, o valor na posição 0 para tipos enumerados).

Exemplo: filtrar valores zero

O exemplo a seguir ilustra consultas que filtram os valores zero.

rule ZeroValuePlaceholderExample {

events:
  // Because $host is used in the match section, the query 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,
  // 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 consultas não vão filtrar implicitamente os valores zero dos marcadores usados na seção match.

Para desativar a filtragem implícita de valores zero, use a opção allow_zero_values na seção de opções. A opção allow_zero_values está disponível apenas em "Regras".

Exemplo: permitir valores zero

O exemplo a seguir ilustra consultas que não filtram implicitamente os valores zero de marcadores usados na seção match:

rule AllowZeroValuesExample {

events:
  // Because allow_zero_values is set to true, there is no implicit filtering
  // of zero values for $host.
  $host = $e.principal.hostname

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

match:
  $host over 5m

condition:
  $e

options:
  allow_zero_values = true
}

A seguir

Confira os recursos a seguir para continuar sua lógica YARA-L ou se aprofundar em funções de consulta avançadas:

Sintaxe e lógica

Referências e exemplos

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