O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Transição da SPL para a YARA-L 2.0

Compatível com:

Google SecOps SIEM

Este guia é destinado a usuários que já conhecem a linguagem de processamento de busca (SPL) do Splunk. Ele oferece uma introdução rápida à YARA-L 2.0, a linguagem principal para criar pesquisas, painéis e regras de detecção no Google Security Operations.

Entender a estrutura do YARA-L 2.0

A YARA-L 2.0 é a linguagem de consulta unificada usada no Google SecOps para pesquisar ameaças, criar painéis em tempo real e criar regras de detecção de alta fidelidade em todos os dados de registro da empresa conforme eles são ingeridos.

A linguagem funciona em conjunto com o mecanismo de detecção do Google SecOps e permite pesquisar ameaças e outros eventos em grandes volumes de dados.

Diferenças básicas de estrutura entre SPL e YARA-L

A SPL usa uma série de comandos encadeados com caracteres de barra vertical (|), enquanto a YARA-L é baseada em seções. Você define uma consulta usando seções distintas, como events, outcome e condition, para descrever um padrão que quer pesquisar, detectar ou visualizar.

A tabela a seguir compara a estrutura básica entre SPL e YARA-L:

Função	SPL (procedural)	YARA-L (declarativa)
Conceito principal	Transformar um fluxo de dados etapa por etapa usando um pipeline de comandos.	Analisa e aplica uma estrutura multipartes de condições e transformações a um fluxo de dados operacionais e de segurança, identificando ameaças e extraindo insights valiosos.
Fluxo de dados	Procedural. Os resultados de um comando são transmitidos como entrada para o próximo.	Estrutura declarativa para processar e correlacionar padrões de maneira ideal em grande escala. Não é mais preciso se preocupar com a eficiência.
Correlação de eventos	Depende de comandos explícitos, como `join`, `transaction` e `stats`.	Integrado ao definir vários eventos e correlacioná-los com base em um campo comum na lógica da consulta.
Janelamento de tempo	Processada como uma janela de pesquisa estática (por exemplo, `last 60m`). Cada nova pesquisa é uma solicitação nova.	Processado como uma janela de tempo contínua e deslizante definida na consulta (por exemplo, `over 5m`).
Sintaxe	Orientado por comandos (por exemplo, `index=web`).	Conciso e orientado pela lógica (por exemplo, `metadata.event_type= "USER_LOGIN"`).

Estrutura específica das consultas

O YARA-L impõe uma estrutura específica para consultas, que é diferente dos comandos sequenciais e com pipe (|) da SPL. Enquanto a SPL cria resultados encadeando comandos, o YARA-L define diferentes aspectos da consulta em seções distintas.

Cada consulta ou regra YARA-L é segmentada em seções distintas e nomeadas, que determinam o comportamento da consulta. Essa estrutura permite a análise e a correlação em várias etapas.

Comando	Ação	Opcional \| Obrigatório
`meta`	Define metadados descritivos para a regra, como autor, descrição e gravidade.	Opcional para pesquisa e painéis. Obrigatório apenas para regras.
`events`	Define e filtra eventos. Declara todas as fontes de dados (principalmente eventos da UDM) a serem consideradas e as filtra usando campos da UDM. Saiba mais sobre a [`events` sintaxe da seção](/chronicle/docs/yara-l/events-syntax).	Obrigatório (lógica principal da consulta) para pesquisa, dashboards e regras.
`match`	Agrupa por eventos e permite especificar o período compatível (por exemplo, `by 5m`). Saiba mais sobre a [sintaxe da seção "match"](https://docs.cloud.google.com/chronicle/docs/yara-l/match-syntax).	Opcional para pesquisas estatísticas em que a agregação ocorre. Obrigatório apenas para consultas de correlação de vários eventos. A especificação de horário é obrigatória para regras e opcional para Pesquisa e Painéis.
`outcome`	Calcula métricas essenciais e recebe insights (por exemplo, `count()`, `avg()`). Saiba mais sobre a [sintaxe da seção "outcome"](/chronicle/docs/yara-l/outcome-syntax).	Opcional.
`condition`	Define a lógica que precisa ser atendida para retornar resultados (na pesquisa) ou acionar um alerta (em uma regra). Avalia os critérios da variável de consulta para determinar se um resultado se aplica (por exemplo, `event > 5`). Saiba mais sobre a [sintaxe da seção "condition"](/chronicle/docs/yara-l/condition-syntax).	Opcional em Pesquisa e Painéis. Obrigatório apenas para regras.
`dedup`	Remove eventos duplicados agrupando-os com base em variáveis essenciais (por exemplo, `target.user.userid`, `target.ip`, `principal.hostname`). Saiba mais sobre como [usar a eliminação de duplicação na pesquisa e nos painéis](/chronicle/docs/investigation/deduplication-yaral).	Opcional. Não disponível em "Regras".
`order`	Classifica os resultados dos eventos coletados definidos por campos específicos (por exemplo, `asc`).	Opcional (aplicável somente quando `match` é usado). Não disponível em "Regras".
`limit`	Restringe o número máximo de eventos retornados da consulta.	Opcional (aplicável apenas quando a correspondência é usada). Não disponível em "Regras".
`select`	Especifica a lista de campos da UDM a serem incluídos nos resultados da consulta.	Opcional. Não disponível em "Regras".
`unselect`	Especifica a lista de campos de UDM a serem excluídos dos resultados da consulta.	Opcional. Não disponível em Regras.

Comandos comuns em SPL e YARA-L

A estrutura da seção YARA-L permite usar os mesmos comandos comuns encontrados na SPL. Nesta seção, descrevemos as semelhanças e diferenças.

Comando SPL `search` = seção YARA-L `events`

O comando search na SPL é equivalente à seção events na YARA-L. A seção events define os eventos e como eles são filtrados inicialmente. Embora outras seções (como match ou outcome) sejam opcionais, a seção events é fundamental para todas as regras.

Exemplo:

metadata.event_type = "USER_LOGIN"

principal.hostname != "" AND metadata.event_type = "NETWORK_CONNECTION"

Na seção events das regras (e consultas avançadas), use variáveis de evento para simplificar sua lógica.

Uma variável de evento funciona como um agrupamento lógico de filtros, representando um evento específico ou um grupo de eventos que correspondem a determinados critérios.

Por exemplo, para definir uma variável de evento, como $e, use-a como um prefixo para todos os eventos e filtros relacionados na seção events da consulta. Em seguida, use essa variável em outras seções da consulta (como match ou outcome) para fazer referência a esse grupo específico de eventos e aos campos de dados deles.

A aplicação mais comum para variáveis de evento é em regras de detecção. O exemplo a seguir demonstra como usar a variável de evento ($e) em uma regra para agrupar eventos e encontrar o número de falhas de login de um usuário em um dia. A regra é acionada se exceder um limite definido.

No exemplo de regra, cada evento é definido com a variável de evento ($e). A variável $e também é referenciada em metadata.id para vincular os metadados da regra aos eventos definidos.

rule DailyFailedLoginAttempts {
 meta:
   author = "Alex"
   description = "Detects a high number of failed login attempts for a single user within a day."

events:
   // Alias for each event
   $e.metadata.event_type = "USER_LOGIN"
   $e.security_result.action = "FAIL"
   $e.principal.user.userid != ""
   $userid = $e.principal.user.userid

match:
   // Group events by principal.user.userid within a 24-hour window
   $userid over 1d

outcome:
   // Count the number of unique event IDs for each user per day
   $daily_failed_login_count = count($e.metadata.id)

condition:
   // Trigger a detection if the daily failed login count exceeds a threshold
   // You should adjust this threshold based on your environment's baseline.
   #e > 0
}

Para garantir que a regra seja acionada, geralmente é necessário verificar a contagem dos eventos agrupados. É possível especificar uma contagem mínima na seção condition usando a variável de evento. Por exemplo, a condição (#e > 0) verifica se existe pelo menos um evento que atende aos critérios.

Comando SPL `eval` = seção YARA-L `outcome`

O comando eval é uma função SPL fundamental usada para manipular e definir valores de campo nos resultados da pesquisa.

Finalidade: calcula e define novos valores de campo.
Funcionalidade: avalia expressões matemáticas, de string ou booleanas.
Resultado: o resultado da avaliação cria um novo campo ou substitui o valor de um campo existente.
Encadeamento: várias expressões podem ser encadeadas usando uma vírgula (por exemplo, | eval A=1, B=A+1).
Processamento sequencial: as expressões em uma cadeia são processadas sequencialmente, permitindo que cálculos posteriores referenciem e se baseiem em campos criados ou modificados por expressões anteriores.

Os exemplos na tabela a seguir (e depois) explicam essa estrutura de comando:

Função	Descrição	Exemplo de YARA-L
Operadores booleanos	Usado em `events` e `condition`. Consulte Usar "ou" na seção de condição.	`metadata.log_type != "" or metadata.event_type = "NETWORK_DNS"`
Campos calculados	Usado na seção `outcome`.	`metadata.event_type = "SCAN_NETWORK" principal.hostname != "" outcome: $id = metadata.id $host = principal.hostname $bytes = cast.as_int(network.sent_bytes)`
Criação dinâmica de nomes de campos	Usado na seção `outcome`.	Confira exemplos em Comparar SPL e YARA-L.

Exemplo: criar um campo que contenha o resultado de um cálculo

Usando a YARA-L, crie um novo campo, bytes, em cada evento. Calcule os bytes somando os valores nos campos bytes enviados e recebidos bytes.

metadata.event_type = "SCAN_NETWORK"
principal.hostname != ""
$host = principal.hostname

match:
  $host

outcome:
  $bytes = cast.as_int(sum(network.sent_bytes))

Exemplo: concatenar valores de dois campos

Use o caractere ponto (.) para concatenar os valores nos campos first_name e last_name. Use aspas ("") para inserir um caractere de espaço entre os dois campos. Ao concatenar, os valores são lidos como strings, independentemente do valor real.

Em SPL, a consulta seria parecida com esta:

| eval full_name = first_name+" "+last_name

No YARA-L, a consulta de pesquisa seria semelhante a esta:

principal.user.first_name = $first_name
principal.user.last_name = $last_name

outcome:
   $full_name = strings.concat($first_name, " ", $last_name)

Usando o exemplo de consulta de login com falha, o exemplo a seguir permite encontrar usuários que tiveram cinco (5) ou mais logins com falha em um período de 10 minutos (10m) entre eles (usando variáveis de evento e de marcador de posição):

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

match:
  $userid by 10m

outcome:
   $login_count= count(metadata.id)

condition:
   $login_count > 5

Comando SPL `where` = seção YARA-L `condition`

O comando SPL where é equivalente a uma combinação das seções events, outcome ou condition na YARA-L. Usando a seção events, você pode declarar eventos e especificar atributos específicos para eles (por exemplo, principal.hostname = "xyz"). Depois de declarar os eventos, use operadores booleanos, de comparação e resultados de funções de agregação (da seção outcome) para definir os parâmetros que os eventos precisam atender para que a consulta retorne um resultado.

O exemplo a seguir demonstra como definir uma condição de limite em uma contagem agregada. A consulta é estruturada para contar o número total de eventos de login com falha por User-ID e usa a seção condition para gerar resultados apenas para usuários que registraram cinco ou mais logins com falha.

metadata.event_type = "USER_LOGIN"
security_result.action = "FAIL"

match:
  target.user.userid

outcome:
  // metadata.id counts all unique events associated with failed logins.
  $count = count(metadata.id)
  //metadata.id counts all unique events associated with blocked logins.

condition:
  $count > 5

Comando SPL `dedup` = seção YARA-L `dedup`

O comando dedup da SPL é equivalente à seção dedup na YARA-L. Use a seção dedup para remover resultados duplicados especificados por um evento na seção events.

Exemplo:

principal.hostname = "foo"

dedup:
   target.ip

Saiba como usar a eliminação de duplicação na Pesquisa e nos painéis, principalmente sobre as diretrizes de performance.

Comando SPL `stats` = seção YARA-L `match` ou `outcome` (ou ambas)

Em SPL, a agregação geralmente é processada pela família de comandos stats, que especifica o tipo de agregação (como count, distinct count, max, min) e o campo "group by".

No YARA-L, as seções match e outcome fornecem esse recurso em conjunto:

Lógica de agregação: a seção match cria agregações definindo o grupo de eventos a ser considerado (match: $grouping_field by time). Em seguida, a seção outcome define as funções agregadas específicas para calcular nesse grupo (por exemplo, count(), min(), max()).
Janelamento de tempo: a seção match permite especificar uma janela de tempo para agrupar eventos. Use a palavra-chave over (para regras) ou by (para pesquisa e painéis) (por exemplo, match: $userid by 1h). Essa funcionalidade é semelhante à SPL, como "timechart", "streamstats" e "eventstats". Para mais informações, consulte Janelas de tempo.

Exemplo: calcular a soma de bytes agrupados por nome do host principal e IP de destino

O exemplo a seguir usa a seção match para definir um grupo de agregação com base no nome do host principal e no endereço IP de destino em um período de um dia. A soma resultante dos bytes enviados é calculada na seção outcome.

metadata.event_type = "NETWORK_CONNECTION"
network.sent_bytes > 0
principal.hostname != ""
target.ip != ""

// Define placeholder variables for grouping
$principal_hostname = principal.hostname
$target_ip = target.ip

// Group events by principal hostname, target IP, and day
match:
  $principal_hostname, $target_ip by day

// Calculate the sum of sent bytes for each group
outcome:
  $daily_bytes_sent = sum(network.sent_bytes)

Mapear SPL para YARA-L

A SPL processa dados etapa por etapa usando comandos encadeados, enquanto a YARA-L usa uma estrutura declarativa baseada em seções para definir padrões e ações. Apesar dessas diferenças fundamentais na abordagem, o poder expressivo da YARA-L permite realizar muitas das mesmas tarefas que você está acostumado a fazer na SPL, desde filtragem básica até agregações e correlações complexas.

Nesta seção, explicamos as diferenças mapeando as funcionalidades conhecidas da SPL para as equivalentes no framework YARA-L.

Comparar SPL e YARA-L

Esta tabela compara funções e conceitos comuns na linguagem SPL com os equivalentes em YARA-L 2.0 ou como o conceito é processado em uma estrutura de consulta YARA-L.

Comando ou conceito da SPL	Finalidade	Equivalente em YARA-L	Descrição e mapeamento da YARA-L	Exemplo de implementação do YARA-L
`search`	Filtragem inicial de dados	Seção `events`	Defina campos e condições de evento. Sem `events`: prefixo necessário para pesquisa ou painéis. Confira um exemplo.	`events: metadata.event_type = "USER_LOGIN" security_result.action = "FAIL"`
`where`	Filtragem adicional nos resultados	Seções `events` e `condition`	Aplicar lógica booleana, geralmente em resultados agregados. Conferir exemplo.	`events: metadata.event_type = "USER_LOGIN" security_result.action = "FAIL" outcome: $failed_count = count(metadata.id) condition: $failed_count > 5`
`eval`	Calcula novos valores com base em campos, agregações e pesquisas de dados atuais	Seção `outcome` ou `events`	Confira um exemplo.	`metadata.event_type = "USER_LOGIN" outcome: $login_count = count(metadata.id)`
`stats`	Agregações (`count`, `sum`, média)	`match` ou `outcome`	Agrupar por campos em `match`. Calcular agregações em `outcome`. Confira exemplos de agregação e exemplos de comandos SPL.	`metadata.event_type = "USER_LOGIN" outcome: $login_count = count(metadata.id)`
`dedup`	Remove eventos duplicados com base em um ou mais campos.	Seção `dedup`	Especifique os campos para eliminar duplicações.	`metadata.event_type = "USER_LOGIN" security_result.action = "FAIL" $user = target.user.userid dedup: $user`
`table`	Define a saída da coluna da tabela	`select` ou `unselect`	Usado em painéis. Na pesquisa, mostra variáveis `outcome`.	`metadata.event_type = "USER_LOGIN" select: principal.hostname`
`sort`	Lista os resultados em ordem crescente ou decrescente	Seção `order`	Veja o exemplo na célula ao lado.	`metadata.event_type = "SCAN_NETWORK" principal.hostname != "" outcome: $id = metadata.id $host = principal.hostname $bytes = uint64(network.sent_bytes) order: $bytes desc`
`limit`	Restringe o número de resultados retornados.	Seção `limit`	Confira o exemplo na célula ao lado.	`metadata.event_type = "SCAN_NETWORK" principal.hostname != "" outcome: $id = metadata.id $host = principal.hostname $bytes = cast.as_int(network.sent_bytes) order: $bytes desc limit: 3`
Funções de múltiplos valores	Processado com funções `mv*` (`mvexpand`, `mvfilter`)	Compatibilidade integrada	O YARA-L desaninha automaticamente matrizes na seção de eventos. As funções de matriz estão disponíveis em `outcome`, se necessário.	Confira exemplos de função multivalorada.
Janelamento de tempo	`earliest=-5m, latest=now`	Seção `match`, `over`, `by`	Para detecções contínuas, use `match: $field over 5m or by 5m`. Para painéis na interface de pesquisa, use `match: $field by 5m`.	Confira exemplos em Janelas de tempo.

Consultas de agregação e estatísticas

Em YARA-L, as funções de agregação e estatística geralmente são colocadas na seção outcome, e a agregação é baseada na seção match.

O comando stats é o principal mecanismo para implementar a agregação de dados nas consultas YARA-L. Ele transforma dados de eventos brutos em métricas de segurança resumidas. Enquanto o comando eval processa transformações no nível do campo, linha por linha (semelhante a uma expressão SELECT), o stats realiza agregação no nível do conjunto (semelhante a GROUP BY em SQL).

A tabela a seguir mostra a sintaxe e o uso principais, demonstrando como usar as estatísticas de maneira eficaz para implementar uma lógica de segurança sofisticada com base em padrões de dados e outliers estatísticos.

Função SPL	Descrição	Equivalente em YARA-L	Exemplo de implementação do YARA-L
`count`	Conta o número de eventos.	`count()`	`metadata.event_type= "USER_LOGIN" security_result.action= "FAIL" outcome: $event_count = count(metadata.id) condition: $event_count > 2`
`dc (count_distinct)`	Conta o número de valores exclusivos de um campo.	`count_distinct()`	`metadata.event_type = "USER_LOGIN" outcome: $unique_users=count_distinct(principal.user.userid)`
`sum`	Calcula a soma dos valores de um campo.	`sum()`	`metadata.event_type = "SCAN_NETWORK" principal.hostname != "" $host = principal.hostname match: $host outcome: $bytes = sum(network.sent_bytes)`
`avg`	Calcula o valor médio de um campo.	`avg()`	`$host = principal.hostname match: $host by day outcome: $avg_bytes_sent = avg(network.sent_bytes)`
`min/max`	Encontra o valor mínimo ou máximo de um campo.	`min()` ou `max()`	`metadata.event_type = "SCAN_NETWORK" principal.hostname != "" $host = principal.hostname match: $host outcome: $bytes = max(network.sent_bytes)- min(network.sent_bytes)`
`median()`	Encontra o valor mediano.	`window.median`	`target.file.mime_type = "PDF" outcome: $median_file_size = window.median(target.file.size, false)`
`first() and last()`	Retorna valores com base na ordem dos eventos nos resultados da pesquisa.	`window.first/window.last`	`metadata.event_type = "NETWORK_CONNECTION" principal.ip != "" match: principal.ip outcome: $event_count = count(metadata.id) $first_seen = window.first(metadata.event_timestamp.seconds, timestamp.get_timestamp(metadata.event_timestamp.seconds)) $last_seen = window.last(metadata.event_timestamp.seconds, timestamp.get_timestamp(metadata.event_timestamp.seconds))`
`STDDEV()`	Calcula o desvio padrão, que mede a dispersão de um conjunto de dados.	`window.stddev`	`principal.hostname= $host match: $host over 5m outcome: $stddev = window.stddev(network.sent_bytes)`

Para mais detalhes, consulte funções adicionais.

Por exemplo, uma consulta de várias etapas pode rastrear vários logins com falha em agregações em camadas. Para mais detalhes, consulte o exemplo de agregação em várias etapas e Criar consultas em várias etapas na YARA-L.

Agregação em várias etapas (média horária para semanal)

Este exemplo de vários estágios agrega inicialmente os dados para encontrar os bytes transferidos por host a cada hora. Em seguida, ela usa essa agregação para calcular a média geral nesses intervalos por hora nos últimos sete dias.

stage bytes_per_host {
metadata.event_type = "SCAN_NETWORK"
principal.hostname != ""
$host = principal.hostname

match:
  $host by hour

outcome:
  $bytes = cast.as_int(sum(network.sent_bytes))
}

$host = $bytes_per_host.host

match:
  $host

outcome:
  $hour_buckets = array_distinct(timestamp.get_timestamp($bytes_per_host.window_start))
  $num_hour_buckets = count_distinct($bytes_per_host.window_start)
  $avg_hourly_bytes = avg($bytes_per_host.bytes)

Funções multivaloradas (ler uma matriz)

A sintaxe da YARA-L foi criada para entender que um campo pode ter vários valores. Quando você escreve uma consulta que inclui um evento com um campo multivalorado na seção events, a linguagem verifica automaticamente todos os valores na matriz. Não é necessário usar uma função especial para filtrar a matriz. Basta indicar a condição que você quer que seja atendida. Por exemplo, se o campo principal.ip do evento de registro contiver o seguinte, o mecanismo YARA-L vai verificar automaticamente cada valor na matriz principal.ip. Se algum dos valores for "10.1.1.5", a condição será atendida.

["10.1.1.5", "10.2.2.6", "10.3.3.7"]

A tabela a seguir mostra uma comparação entre YARA-L e SPL sobre como gerenciar campos de vários valores em dados de registro. Campos de vários valores, como uma matriz de endereços IP ou uma lista de grupos de usuários, são um recurso comum em registros estruturados.

Função SPL	Purpose	Equivalente em YARA-L	Exemplo de implementação do YARA-L
`mvfilter()`	Filtra um campo multivalorado para manter apenas os valores correspondentes.	Quando usado na seção `events` de uma consulta YARA-L, liste o campo a ser correspondido. O YARA-L verifica automaticamente se algum valor na matriz de grupos corresponde a"admin".	`principal.user.group_identifiers = "admin"`
`mvcount()`	Conta o número de valores em um campo de vários valores.	`count()` aplicado a um campo na seção de consulta `outcome`. Não é necessário remover o aninhamento de nenhum valor primeiro.	Consulte o exemplo Contar o número de usuários que pertencem ao grupo de funcionários de TI.
`mvexpand`	Cria um novo evento para cada valor em um campo multivalorado.	Processa campos multivalorados de forma nativa e implícita. A remoção do aninhamento acontece automaticamente.	Consulte o exemplo Contar o número de usuários que pertencem ao grupo de funcionários de TI.
`mvjoin`	Une todos os valores de um campo de vários valores em uma única string para fins de formatação de dados.	Os valores são armazenados automaticamente como uma matriz nos resultados. A saída do YARA-L é estruturada, não uma string simples. Ele exibe o campo como uma matriz se for necessário fazer mais manipulações. Para mais detalhes, use as funções de matriz.

Exemplo: contar o número de logins do `admin`

No exemplo a seguir, a condição $metadata.event_type = "USER_LOGIN" filtra eventos em que event_type é "USER_LOGIN":

events:
 metadata.event_type = "USER_LOGIN"
 // Changed to a more appropriate event type for login
 principal.user.group_identifiers = "admin"

outcome:
 // This counts each unique event ID where the principal user is in the `"admin"` group.
 $admin_login_count = count(metadata.id)

O campo $principal.user.group_identifiers= "admin" é um campo repetido (uma matriz).

Desaninhamento implícito: o YARA-L desaninha automaticamente esse campo internamente durante a avaliação da consulta.
Verificação de condição: um evento vai atender à condição se algum dos valores na matriz $principal.user.group_identifiers for igual a "admin".
Não é necessário um comando explícito: ao contrário da SPL, não é preciso um comando específico de remoção de aninhamento, como mvexpand.

A seção sobre o impacto na agregação (outcome) significa que a remoção implícita do aninhamento é crucial na seção outcome (por exemplo, outcome: $admin_login_count = count(metadata.id)). Observe o seguinte impacto:

Um único evento da UDM que contém vários valores correspondentes em um campo repetido pode gerar várias linhas internas para fins de avaliação de consulta.
Como a seção events já desaninhar os eventos com base em cada valor correspondente em $principal.user.group_identifiers, a agregação count(metadata.id) conta cada uma dessas instâncias desaninhadas.

Exemplo: contar o número de usuários que pertencem ao grupo de equipe de TI

SPL:

index=<your_index_name> user_id="jsmith"
| where match(memberOf, "Domain Admins|IT Staff|HR")
| mvexpand memberOf
| stats count by memberOf
| mvexpand actions
| table memberOf, count, actions

YARA-L (pesquisa):

 principal.user.userid = "jsmith"
 additional.fields["memberOf"] = $group
   $group = /Domain Admins|IT Staff|HR/ nocase

 match:
   $group by 1h

 outcome:
   $group_count = count_distinct(metadata.id)
   $memberOf = array_distinct($group)
   $risk_score = max(50)

Exemplo: criar uma regra para alertar quando um hash de arquivo específico estiver presente

SPL:

| eval file_hashes="hash12345,hash67890,hashABCDE"
| makemv delim="," file_hashes
| mvexpand file_hashes
| search file_hashes="hash67890"
| table _time, file_hashes

YARA-L (regra):

    rule specific_file_hash_detected {

    meta:
      rule_name = "Specific File Hash Detected"
      description = "Detects events where a specific file hash is present."
      severity = "Medium"

    events:
      $e.target.file.sha256 = "hash67890"

    outcome:
      $time = array_distinct($e.metadata.event_timestamp.seconds)
      $file_hashes = array_distinct($e.target.file.sha256)

    condition:
      $e
    }

Janelamento de tempo

Na YARA-L, a janela de tempo é um método para correlacionar eventos em um período específico e contínuo. Quando usada em regras, essa janela se move continuamente com os dados recebidos, o que fornece a detecção contínua e em tempo real de padrões que se desenvolvem ao longo do tempo.

Esse processo é uma parte fundamental do design para detecção automatizada e um dos benefícios de usar a YARA-L. Ao especificar a janela de tempo, suas detecções e painéis trabalham continuamente com dados em tempo real.

Recurso	SPL	YARA-L
Meta principal	Pesquisa estática, análise ad hoc	Detecção contínua, correlação automatizada
Funções principais	`earliest, latest, span, transaction`	`over`, `by`
Exemplo de 5 minutos	`earliest=-5m` (pesquisa estática) ou `transaction maxspan=5m`	`match`: `[event] over 5m` (detecção contínua em regras) ou `[event] by 5m` (pesquisa e painéis)

Os exemplos nesta seção ilustram a diferença entre uma janela de tempo rotativa (usando by) e uma janela de tempo deslizante (usando over) na YARA-L.

Janela de tempo em cascata (`by <time_unit>`)

Conceito: usadas na pesquisa YARA-L, as janelas em cascata criam intervalos de tempo fixos e não sobrepostos. O sistema processa cada evento atribuindo-o a exatamente um bucket de tempo específico com base no carimbo de data/hora. Esses intervalos fixos são absolutos e se alinham estritamente com marcadores de tempo padrão, como dias, horas ou minutos.
Uso: usado com frequência em consultas de pesquisa e painéis do Google SecOps para agregar dados em segmentos de tempo discretos.

Exemplo: contagem diária de logins bem-sucedidos por usuário

Essa consulta de pesquisa agrupa os eventos de login bem-sucedidos por cada usuário único em cada dia do calendário. O exemplo a seguir demonstra uma janela em cascata de pesquisa YARA-L (by day):

events:
  //Filter for successful login events
  metadata.event_type = "USER_LOGIN"
  principal.user.userid != ""

match:
  //Group by each unique user ID, aggregated over a calendar day.
  principal.user.userid by day

outcome:
  //Count how many successful logins occurred for this user on this specific day.
  $daily_success_count = count(metadata.id)

  //Get the timestamp of the FIRST event within this daily group.
  $first_event_time = window.first(metadata.event_timestamp.seconds, timestamp.get_timestamp(metadata.event_timestamp.seconds))

  //Get the timestamp of the LAST event within this daily group.
  $last_event_time = window.last(metadata.event_timestamp.seconds, timestamp.get_timestamp(metadata.event_timestamp.seconds))

Como funciona: se o usuário jdoe tiver 10 logins bem-sucedidos em Nov 17 e 15 em Nov 18, essa consulta vai gerar duas linhas separadas para jdoe, uma para cada dia, com as respectivas contagens. O bucket Nov 17 inclui eventos de 2025-11-17 00:00:00 to 23:59:59 UTC.

Janela de tempo variável (`over <duration>`)

Conceito: usadas em regras YARA-L, as janelas deslizantes são janelas de tempo móveis, potencialmente sobrepostas, de uma duração especificada. Elas são ideais para correlacionar eventos que acontecem em uma determinada proximidade.
Uso: usado principalmente em regras YARA-L para detectar padrões ou sequências de eventos em um período contínuo.

Exemplo: detectar vários logins com falha em 5 minutos

Este exemplo de regra YARA-L gera uma detecção se um único usuário tiver mais de 5 failed logins tentativas em qualquer período contínuo de 5-minute:

rule TooManyFailedLogins_SlidingWindow {
 meta:
   author = "Alex"
   description = "Detects when a user has more than 5 failed logins within a 5-minute sliding window."
   severity = "Medium"

events:
   // Define an event variable $e for failed login attempts
   $e.metadata.event_type = "USER_LOGIN"
   $e.security_result.action = "FAIL"
   $e.principal.user.userid != ""
   $userid = $e.principal.user.userid

match:
   // Group events by userid over a continuous 5-minute sliding window.
   // Any events for the same $userid within 5 minutes of each other are grouped.
   $userid over 5m

outcome:
   // Count the number of failed login events within each 5-minute window for the grouped userid.
   $failed_count = count($e.metadata.id)

condition:
   // Trigger a detection if the count of failed logins in ANY 5-minute window is greater than 5.
   #e > 5
}

Como funciona: o sistema monitora continuamente as tentativas de login com falha. A qualquer momento, ele considera os últimos 5 minutos de eventos para cada usuário. Por exemplo, se entre 10:02:30 e 10:07:30, o usuário jdoe acumular seis tentativas de login sem sucesso, uma detecção será acionada. Essa janela avança constantemente, permitindo a detecção de padrões em tempo real, independentemente dos limites do calendário.

A seguir

Saiba mais na Visão geral do YARA-L 2.0
Confira a sintaxe completa da linguagem YARA-L 2.0.
Saiba como escrever regras do Detection Engine
Novidade nos blogs do Google SecOps

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