Aplicar a lógica de janelas do YARA-L 2.0
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 (
byouover) na seçãomatchpara usar essas palavras-chave. - Restrição de seção: use essas palavras-chave em
condition,orderououtcome. Eles são inválidos na seçãoevents. - 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
}
Pesquisar
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
$useridespecí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:
- Identifique a meta de detecção. Determine se você está procurando alta frequência ou falta de atividade.
- Selecione a palavra-chave
window. Useoverpara frequência ebypara ausência. - Limites da janela de referência. Use as palavras-chave
window_startewindow_endpara 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,
e1ocorre até dois minutos apóse2). - Tempo relativo: encontre um evento que ocorre em um deslocamento específico de um acionador (por exemplo, um
Network Connectionem até 30 segundos de umProcess 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 commatch: $user by 24hsó é 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 deby 24hnão vai alertar no meio da janela.Incompatibilidade de interface: na Pesquisa e nos Painéis, a palavra-chave
window_startse refere diretamente ao campoTIME_BUCKET. Quando você filtra ou agrupa porwindow_start, o cabeçalho da coluna é exibido comoTIME_BUCKETna 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
- Biblioteca de referência de consultas do YARA-L 2.0
- Sintaxe da seção
match - Sintaxe da seção
condition
Precisa de mais ajuda? Receba respostas de membros da comunidade e profissionais do Google SecOps.