Aplicar a lógica de janelas do YARA-L 2.0

Compatível com:

Este guia ajuda os engenheiros de segurança a escolher o tipo de janela correto para consultas, evitando erros de compilador "variável não limitada". A transição de janelas deslizantes para janelas de tumbling permite criar uma lógica que depende da ausência de eventos, como uma pulsação ausente ou uma fonte de registro com falha.

Antes de começar

Confirme se sua conta tem um dos seguintes papéis para criar e modificar consultas YARA-L:

  • Administrador do mecanismo de detecção (roles/chronicle.detectionEngineAdmin)
  • Editor de SecOps (roles/chronicle.editor)

Tipos de janela compatíveis

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

Tipo de janela compatível Sintaxe Descrição Caso de uso comum
Hop $key over <duration> Cria intervalos de tempo fixos e sobrepostos. O sistema define a sobreposição e o alinhamento para capturar eventos próximos aos limites. Correlação geral de vários eventos, independentemente dos horários de início exatos.
Acrobacias $key by <duration> Segmenta dados em blocos de tamanho fixo, contínuos e não sobrepostos. Avalia independentemente da chegada do evento. Quantificar a atividade em intervalos fixos (por exemplo, $user by 30m) ou detectar a ausência de eventos.
Deslizamento $key over <duration> [before|after] $pivot Fixa a janela a um evento "pivot" específico. Requer que o pivô exista para acionar uma análise retroativa ou prospectiva. Sequenciamento estrito em que a ordem dos eventos é essencial (por exemplo, File Download after Login).

Entender a lógica de window_start e window_end

O Google Security Operations oferece duas palavras-chave universais e reservadas que se resolvem diretamente em carimbos de data/hora do GoogleSQL para uso em consultas. Essas palavras-chave permitem acessar os limites dos buckets de tempo:

  • window_start: o limite inicial do bucket de tempo.
  • window_end: o limite de fechamento do período.

Restrições de uso

  • Requisito de correspondência: é necessário definir uma janela (by ou over) na seção match para usar essas palavras-chave.
  • Restrição de seção: use essas palavras-chave em condition, order ou outcome. Eles são inválidos na seção events.
  • Namespace: não use esses nomes como variáveis personalizadas (por exemplo, $window_start).

Determinar o tipo e a sintaxe da janela

Use esta tabela como uma referência rápida ao determinar qual tipo de janela e sintaxe usar nas regras de detecção.

Cenário Janela recomendada Palavras-chave recomendadas Principal vantagem
Detecções de alta frequência (por exemplo, ataques de força bruta) Janela deslizante (over) window_start, window_end É acionado imediatamente quando o limite é atingido em um período contínuo.
Ausência/inexistência (por exemplo, ausência de heartbeats) Janela fixa (by) window_start, window_end Avalia blocos de tempo fixos mesmo que não ocorram eventos, evitando erros de variável não limitada.
Relatórios cronológicos Deslizamento ou queda order: window_start asc Padroniza a saída de alertas para facilitar a análise da linha do tempo na interface do Chronicle.
Filtragem por tempo Deslizamento ou queda condition: window_start > "2026-01-01 00:00:00Z" Limita a avaliação de regras a datas específicas usando a coerção de carimbo de data/hora do GoogleSQL.

Comparar tipos de carimbo de data/hora e fusos horários

O YARA-L permite comparar window_start e window_end diretamente com strings no formato de carimbo de data/hora do GoogleSQL. Isso permite realizar uma filtragem precisa sem conversão de tipo manual.

Observação: sempre especifique o UTC usando o sufixo Z (por exemplo, "2026-03-17T17:35:00Z") para alinhar com os carimbos de data/hora de eventos do UDM.

Use filtros de carimbo de data/hora para melhorar o desempenho. Se você só precisa confirmar que um evento aconteceu depois de outro, uma comparação de carimbo de data/hora na seção condition geralmente é mais eficiente: $e1.metadata.event_timestamp.seconds < $e2.metadata.event_timestamp.seconds.

Saiba mais sobre a sintaxe da seção match e a sintaxe da seção condition.

Exemplos: window_end e window_start

  • window_end < "2026-01-01T12:30:00Z" (data, hora e sufixo UTC)
  • window_start != "2026-01-01 15:00:00+00" (com ajuste de tempo UTC)

Se a comparação falhar, verifique se a string segue o formato de carimbo de data/hora canônico do GoogleSQL.

Janelas de salto

Uma janela de salto cria intervalos de tempo sobrepostos para que os eventos que ocorrem perto dos limites de uma janela não sejam perdidos.

  • Caso de uso: ideal para detecções em que você precisa capturar um cenário específico, independentemente de quando o intervalo da janela começa ou termina.
  • Suporte: compatível com agregação em pesquisas e painéis.

As consultas YARA-L com uma seção match usam janelas de salto para correlacionar vários eventos ao longo do tempo. O sistema divide o período de execução da consulta em um conjunto de janelas de salto fixas e sobrepostas. Embora você especifique a duração dessas janelas na seção match, o sistema define o intervalo de sobreposição e o alinhamento da janela. Os eventos são correlacionados dentro de cada uma dessas janelas predeterminadas.

Saiba mais sobre a sintaxe da seção match.

As janelas de salto têm implicações específicas para detecções de regras compostas. Para mais informações, consulte Regras compostas: intervalos de tempo e janelas de salto.

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

O exemplo a seguir mostra uma consulta executada no período [1:00, 2:00], com uma seção match $user over 30m. Um possível conjunto de janelas de salto sobrepostas que o sistema gera é [1:00, 1:30], [1:03, 1:33] e [1:06, 1:36].

Regra

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
}
metadata.event_type = "USER_LOGIN"
security_result.action = "FAIL"
principal.user.userid = $user

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

Painel

metadata.event_type = "USER_LOGIN"
security_result.action = "FAIL"
principal.user.userid = $user

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

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

O exemplo a seguir captura eventos que ocorrem no mesmo período geral:

Regra

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

events:
  // Event 1: Capture failed login attempts
  $fail.metadata.event_type = "USER_LOGIN"
  $fail.security_result.action = "FAIL"
  $fail.principal.user.userid = $user

  // Event 2: Capture successful login attempts
  $success.metadata.event_type = "USER_LOGIN"
  $success.security_result.action = "ALLOW"
  $success.principal.user.userid = $user

match:
  // Correlate events for the SAME $user within a rolling 30-minute window.
  $user over 30m

condition:
  // Ensure both a failed ($fail) and a successful ($success) login event occurred for the same user within the 30m window.
  $fail and $success
}

Pesquisar

// Event 1: Capture failed login attempts
metadata.event_type = "USER_LOGIN"
security_result.action = "FAIL"
principal.user.userid = $user // Assign user ID to a placeholder

// Event 2: Capture successful login attempts
metadata.event_type = "USER_LOGIN"
security_result.action = "ALLOW"
principal.user.userid = $user // Link to the same user placeholder

match:
  // Correlate events for the SAME $user within a rolling 30-minute window.
  $user over 30m

Painel

// Event 1: Capture failed login attempts
metadata.event_type = "USER_LOGIN"
security_result.action = "FAIL"
principal.user.userid = $user // Assign user ID to a placeholder

// Event 2: Capture successful login attempts
metadata.event_type = "USER_LOGIN"
security_result.action = "ALLOW"
principal.user.userid = $user // Link to the same user placeholder

match:
  // Correlate events for the SAME $user within a rolling 30-minute window.
  $user over 30m

Exemplo: comparação de janelas de salto

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

Regra

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
}

Pesquisar

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

match:
  $user over 10m

Painel

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

match:
  $user over 10m

Janelas em cascata

Observação: esse recurso não está disponível para todos os clientes em todas as regiões.

Uma janela em cascata segmenta dados em intervalos de tempo contínuos, de tamanho fixo e que não se sobrepõem. 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 de salto ou uma janela deslizante, que podem ter intervalos de tempo sobrepostos.

Para implementar uma janela em cascata, use o operador by na seção match. As janelas em cascata dividem o tempo em blocos contínuos e consecutivos, por exemplo:

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

Casos de uso comuns

Use janelas em cascata quando precisar:

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

Comportamento de eliminação de duplicação

Uma característica importante das janelas em cascata é como o mecanismo lida com as detecções 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), o mecanismo gera no máximo uma detecção para qualquer janela em cascata.
  • A primeira chegada 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.
  • Eliminação de duplicação: os 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>

  • $variable é a variável de marcador de posição que você está correspondendo.
  • 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: agrupamento de intervalo fixo

A regra a seguir agrupa os logins por $userid em janelas de uma hora que não se sobrepõem.

Regra

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
}

Pesquisar

metadata.event_type = "USER_LOGIN"
principal.user.userid = $userid

match:
  $userid by 1h

Painel

metadata.event_type = "USER_LOGIN"
principal.user.userid = $userid

match:
  $userid by 1h

Exemplo: comportamento de detecção (usuário = "Alex")

  • Evento 1: Alex faz login às 00h30. Isso se enquadra na janela [00:00:00-00:59:59]. O mecanismo gera uma detecção 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, o mecanismo gera uma detecção separada para Taylor.
  • Evento 3: Alex faz login novamente às 00h40. Isso ainda está dentro do período de [00:00:00-00:59:59]. Como já existe uma detecção para Alex, esse evento é desduplicado. Nenhuma nova detecção é gerada.
  • Evento 4: Alex faz login à 1h20. Isso se enquadra na próxima janela, [01:00:00-01:59:59]. O mecanismo gera uma nova detecção para Alex.

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

Configurar janelas em cascata para detecções de ausência

Para alertar sobre uma contagem de zero e evitar falhas do compilador, siga estas etapas:

  1. Identifique a meta de detecção. Determine se você está procurando alta frequência ou falta de atividade.
  2. Selecione a palavra-chave window. Use over para frequência e by para ausência.
  3. Limites da janela de referência. Use as palavras-chave window_start e window_end para referenciar limites específicos do período.

Contexto: use outcome: $ext_window_end = window_end para incluir o horário exato de término de um heartbeat perdido nos metadados do alerta.

Exemplo: detectar um heartbeat ausente com metadados

As janelas em cascata permitem que você receba alertas sobre uma contagem de zero, o que ajuda a evitar falhas do compilador ao pesquisar uma falta de atividade.

Regra

rule missing_heartbeat_detection {
meta:
  description = "Alert when a system fails to check in within a 24h block"

events:
  $e.metadata.event_type = "STATUS_UPDATE"
  $host = $e.principal.hostname

match:
  $host by 24h  // Tumbling window lets you detect zero counts

outcome:
  $event_count = count($e.metadata.id)
  $missing_window_start = window_start
  $missing_window_end = window_end

condition:
  $event_count = 0 and window_start > "2026-01-01T12:30:00Z"
}

Pesquisar

metadata.event_type = "STATUS_UPDATE"
$host = principal.hostname

match:
  $host by 24h  // Tumbling window lets you detect zero counts

outcome:
  $event_count = count(metadata.id)
  $missing_window_start = window_start
  $missing_window_end = window_end

Painel

metadata.event_type = "STATUS_UPDATE"
$host = principal.hostname

match:
  $host by 24h  // Tumbling window lets you detect zero counts

outcome:
  $event_count = count(metadata.id)
  $missing_window_start = window_start
  $missing_window_end = window_end

Janelas deslizantes

Uma janela deslizante é ancorada a um evento de pivô específico e olha para frente (after) ou para trás (before).

Casos de uso comuns

Use janelas deslizantes quando a sequência de eventos for essencial:

  • Sequenciamento estrito: detecta uma cadeia de ataques (por exemplo, e1 ocorre até dois minutos após e2).
  • Tempo relativo: encontre um evento que ocorre em um deslocamento específico de um acionador (por exemplo, um Network Connection em até 30 segundos de um Process Start).
  • Detecção de ausência: identifique quando um evento de "limpeza" ou "heartbeat" obrigatório não ocorre após um evento de início.

Sintaxe

match: <grouping_keys> over <duration> [before|after] <$pivot_event>

Componente Descrição Exemplo
Chaves de agrupamento Campos comuns usados para vincular eventos. $host, $user
Duração O ajuste de tempo do evento de referência. 5m, 1h, 30s
Direção Se a janela se estende para frente ou para trás. after, before
Evento dinâmico A variável de evento que ancora a janela. $proc, $alert

Confira a seguir exemplos válidos de janelas deslizantes:

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

Requisitos e limitações

  • Desempenho: as janelas deslizantes exigem mais capacidade de processamento do que as janelas de salto. Use-os apenas quando a ordem dos eventos for estritamente necessária (por exemplo, quando um evento precisa acontecer até cinco minutos após outro).
  • Consultas de evento único: não use janelas deslizantes para a lógica de evento único. Em vez disso, use várias variáveis de evento na seção condition.

Exemplo: correlação prospectiva (after)

Regra

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
}

Pesquisar

after não é compatível com a Pesquisa.

Painel

after não é compatível com os painéis.

Exemplo: correlação retrospectiva (before)

Use uma janela deslizante de "before" para investigar a atividade que levou a um alerta específico. Isso costuma ser usado na análise de causa raiz para identificar o que aconteceu imediatamente antes de uma detecção crítica.

Regra

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
}

Pesquisar

before não é compatível com a Pesquisa.

Painel

before não é compatível com os painéis.

Solução de problemas

Use esta seção para entender a latência, os limites e as correções de problemas comuns de janelas no YARA-L.

Latência e limites

  • As regras que usam janelas em cascata (by) só são acionadas no final do bloco de tempo fixo. Por exemplo, uma regra com match: $user by 24h só é avaliada depois que a janela de 24 horas termina.

  • Latência de alerta: as regras que usam by (tumbling) só são acionadas após o término do bloco de tempo fixo. Uma regra de by 24h não vai alertar no meio da janela.

  • Incompatibilidade de interface: na Pesquisa e nos Painéis, a palavra-chave window_start se refere diretamente ao campo TIME_BUCKET. Quando você filtra ou agrupa por window_start, o cabeçalho da coluna é exibido como TIME_BUCKET na interface.Essa é uma limitação conhecida da interface, mas sua lógica permanece válida.

Correção de erros

Código do erro Descrição Corrigir
Variável não limitada A regra usa over (janela deslizante) com uma condição $count = 0. Mude a palavra-chave de janelamento para by (janela em cascata). As janelas deslizantes exigem que um evento exista para ancorar a janela, enquanto as janelas em cascata não.
Incompatibilidade de cabeçalho da interface O usuário vê TIME_BUCKET na UI em vez de window_start. Nenhuma correção é necessária. A lógica de filtragem e ordenação ainda funciona corretamente usando as palavras-chave.
Identificador desconhecido: window_start A palavra-chave é usada, mas nenhuma janela é definida em match. Adicione uma instrução de janela à seção match (por exemplo, $hostname by 1h).
Uso inválido de window_start em eventos A palavra-chave é referenciada na seção events. Mova a lógica para a seção condition ou outcome. Os limites da janela são calculados somente após o agrupamento de eventos na fase de correspondência.

A seguir

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