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

Compatível com:

Google SecOps SIEM

Este guia ajuda os engenheiros de segurança a escolher o tipo de janela correto para consultas e evitar erros de compilador "variável não vinculada". A transição de janelas deslizantes para janelas em cascata permite criar uma lógica que depende da ausência de eventos, como um heartbeat ausente ou uma origem do 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 Detection Engine (roles/chronicle.detectionEngineAdmin)
• Editor de SecOps (roles/chronicle.editor)

Tipos de janela compatíveis

O 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 detectar eventos próximos a limites.	Correlação geral de vários eventos, independente dos horários de início exatos.
Acrobacias	$key by <duration>	Segmenta dados em blocos contínuos, não sobrepostos e de tamanho fixo. Avalia de forma independente 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	Ancora a janela a um evento "pivot" específico. Requer que o pivô exista para acionar uma análise retroativa ou prospectiva.	Sequência estrita 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 são resolvidas diretamente em carimbos de data/hora do GoogleSQL para uso em consultas. Com elas, você acessa os limites dos seus intervalos de tempo:

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

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 termos como nomes de 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/não existência (por exemplo, batimentos cardíacos ausentes)	Janela fixa (by)	window_start, window_end	Avalia blocos de tempo fixos mesmo que nenhum evento ocorra, evitando erros de Variável não limitada.
Relatórios cronológicos	Deslizar ou rolar	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 período	Deslizar ou rolar	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 carimbos 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 fazer 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 da UDM.

Use filtros de carimbo de data/hora para melhorar a performance. Se você só precisar confirmar que um evento aconteceu depois de outro, uma comparação de carimbos 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 acontecem perto dos limites de uma janela não sejam perdidos.

• Caso de uso:ideal para detecções em que é necessário 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. Em seguida, os eventos são correlacionados em cada uma dessas janelas predeterminadas.

Observação: use a janela de salto, a menos que você precise de uma sequência específica de eventos (pedido A e depois pedido B). Use apenas janelas deslizantes quando a sequência de eventos for essencial ou quando você procurar eventos ausentes.

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 é coberto pelos Termos de produtos pré-GA dos Termos específicos de serviço do Google Security Operations. Os recursos pré-GA podem ter suporte limitado, e as mudanças realizadas podem não ser compatíveis com outras versões pré-GA. Para mais informações, consulte as diretrizes do serviço de suporte técnico do Google SecOps e os Termos específicos de serviço do Google SecOps.
Se esse recurso não estiver visível no seu ambiente, consulte Gerenciar recursos de visualização ou entre em contato com o administrador do sistema.

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 rotativa, 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 fixas quando precisar:

• Analise eventos em blocos de tempo distintos e não sobrepostos.
• Produzir apenas uma detecção para uma determinada entidade (conforme definido pelas variáveis de correspondência) em cada intervalo de tempo fixo, independente 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 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.
• Eliminação de duplicação:eventos subsequentes que corresponderem aos critérios na mesma instância de janela não vão gerar detecções adicionais.

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 por 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 da janela de [00:00:00-00:59:59]. Como já existe uma detecção para Alex, esse evento é eliminado por duplicação. 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]. 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 cruza o limite da janela fixa.

Configurar janelas rotativas para detecções de ausência

Para gerar um alerta 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 do período de referência. Use as palavras-chave window_start e window_end para fazer referência a limites específicos do agrupamento por período.

Contexto:use outcome: $ext_window_end = window_end para incluir o horário exato de término de uma pulsação perdida nos metadados do alerta.

Exemplo: detectar um heartbeat ausente com metadados

As janelas rotativas permitem alertar sobre uma contagem de zero, o que ajuda a evitar falhas do compilador ao procurar 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 em um evento de pivô específico e olha para frente (after) ou para trás (before).

Observação: disponível apenas para regras, não compatível com pesquisa ou painéis.

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 ocorra em um período específico de um gatilho (por exemplo, um Network Connection em até 30 segundos de um Process Start).
• 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.

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 principal.	5m, 1h, 30s
Direção	Se a janela se estende para frente ou para trás.	after, before
Evento de pivô	A variável de evento que ancora a janela.	$proc, $alert

Confira exemplos válidos de janela deslizante:

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

Requisitos e limitações

• Performance: as janelas deslizantes exigem mais poder 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

O 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 "before" para investigar a atividade que antecede um alerta específico. Isso é usado com frequência na análise da 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

O 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 na 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 uma vez após o término completo da janela de 24 horas.

• Latência do alerta:as regras que usam by (tumbling) só são acionadas após o término do bloco de tempo fixo. Uma regra 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 aparece como TIME_BUCKET na interface.Essa é uma limitação conhecida da exibição da UI, mas sua lógica continua 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 um evento para ancorar a janela, enquanto as janelas em cascata não.
Divergência no 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 de janela são calculados somente depois que os eventos são agrupados 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.