Começar a usar a YARA-L

Compatível com:

A YARA-L 2.0 é a linguagem de consulta exclusiva e altamente estruturada que alimenta o Google Security Operations para todas as pesquisas, painéis e detecção de ameaças baseada em regras. Este documento ajuda a entender a estrutura principal do YARA-L e fornece etapas práticas para usá-lo, seja você um analista de segurança em busca de ameaças ou um engenheiro de detecção criando uma nova lógica robusta.

Este documento explica o YARA-L e a sintaxe dele, mostrando como você pode usar a linguagem para expressar tudo, desde uma consulta de filtro básica até uma regra que procura padrões complexos. Use as seções em uma consulta YARA-L para oferecer suporte a funções agregadas, lógica de condição e adicionar contexto por meio de mesclagens, correspondência de padrões e muito mais.

Antes de começar

Entender a estrutura do YARA-L

Cada consulta 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.

Pedido Seção Regras Pesquisa/Painéis Descrição
1 meta Obrigatório Opcional Define metadados descritivos para a regra, como autor, descrição e gravidade. Por exemplo, autor (security team), descrição (Detects multiple failed user logins within 10-minute windows) e gravidade (High).Consulte sintaxe da seção meta.
2 events Obrigatório Obrigatório Define e filtra os eventos que precisam ser rastreados: logins de usuários, falhas de login de usuários (variáveis de evento) e links para a variável de correspondência de usuário (variáveis de marcador de posição). Declara todas as fontes de dados (principalmente eventos) a serem consideradas e as filtra usando campos da UDM. Consulte a sintaxe da seção events.
3 match Obrigatório Opcional Agrupa por eventos e permite especificar o período aceito (por exemplo, by 5m). Obrigatório em alguns casos para pesquisas estatísticas em que ocorre agregação. Obrigatório para consultas de correlação de vários eventos. A especificação de tempo é obrigatória no match para regras e opcional para pesquisa e painéis. Consulte a sintaxe da seção match.

Observação: se você excluir uma seção match, a regra poderá corresponder a um único evento.
4 outcome Opcional Opcional Calcula métricas essenciais e gera insights (por exemplo, count(), avg()). Consulte sintaxe da seção outcome.
5 condition Obrigatório Opcional 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). Consulte a sintaxe da seção condition.
6 options Opcional Opcional Permite ativar ou desativar o comportamento de uma regra específica. Consulte a sintaxe da seção options.
7 dedup N/A Opcional Remove eventos duplicados agrupando-os com base em variáveis-chave ou caminhos de eventos (por exemplo, target.user.userid, target.ip, principal.hostname ou variáveis, como $host, $user). Saiba mais sobre as variáveis de evento e como usar a eliminação de duplicação na Pesquisa e nos Painéis.
8 order N/A Opcional Classifica os resultados definidos por campos específicos (por exemplo, asc). Saiba mais sobre as variáveis de evento. Opcional (aplicável somente quando match é usado).
9 limit N/A Opcional Restringe o número máximo de eventos retornados da consulta.
10 select N/A Opcional Especifica a lista de campos da UDM a serem incluídos nos resultados da consulta.
11 unselect N/A Opcional Especifica a lista de campos da UDM a serem excluídos dos resultados da consulta.

Disponibilidade de fontes de dados da YARA-L

A YARA-L tem acesso a diferentes fontes de dados, dependendo de onde você está na plataforma. Eventos, entidades (ECG) e tabelas de dados estão totalmente disponíveis em pesquisas, painéis e regras. Para mais detalhes sobre consultas de amostra, consulte Fontes de dados compatíveis.

A tabela a seguir lista os recursos disponíveis na YARA-L:

Recurso Disponível em
Casos e histórico de casos Painéis
Tabela de dados Pesquisa, painéis, regras
Entidades (ECG) Pesquisa, painéis, regras
Métricas de ingestão Painéis
Correspondências de IoC Painéis
Detecções de regras Painéis, regras
Conjuntos de regras Painéis
Eventos Pesquisa, painéis, regras
Métricas de UEBA Pesquisa, painéis

Todos os dados no Google SecOps são pesquisados usando dois métodos principais com base nas suas metas: pesquisa por filtro e pesquisa estatística (agregações).

O método de pesquisa de filtro permite isolar eventos específicos do fluxo de telemetria mais amplo sem a sobrecarga da agregação estatística. Esse método usa critérios para reduzir grandes volumes de dados de segurança, como registros ou tráfego de rede, a um conjunto de resultados direcionado. A lógica exige apenas que você especifique eventos na seção events.

Para criar sua primeira pesquisa de filtro YARA-L, siga estas etapas para pesquisar usuários com falha no login:

  1. No Google SecOps, acesse a página de pesquisa.
  2. Filtre os eventos de login:
    metadata.event_type = "USER_LOGIN"

    Dica: você pode omitir o cabeçalho da seção events: nas suas pesquisas. Por padrão, a sintaxe de pesquisa implica essa seção.

  3. Adicione ações event para logins com falha de usuários que não têm um userid vazio. 
    metadata.event_type = "USER_LOGIN"
security_result.action = "FAIL"
principal.user.userid != ""
  4. Execute esta pesquisa para conferir os resultados.

Usar variáveis de marcador de posição

Use variáveis de marcador de posição para extrair valores específicos dos seus eventos, como um nome de usuário ou um endereço IP. Essas variáveis funcionam como âncoras temporárias que permitem comparar dados de diferentes eventos ou mostrar esses valores na saída final.

Você aplica variáveis de marcador de posição para fazer o seguinte:

  • Dados de ponte: use marcadores de posição, como $userid ou $ip, para encontrar correspondências entre diferentes variáveis de evento. Por exemplo, use $userid para vincular o identificador de usuário nos eventos de login e logout.
  • Agrupar resultados: na seção match, use variáveis de marcador de posição para definir a janela da saída da consulta, como match: $userid over 1h.
  • Criar resultados: use marcadores de posição para capturar e exibir pontos de dados específicos na saída da consulta.

Por exemplo, se você atribuir $user = principal.user.userid, a variável $user vai conter o valor específico extraído do evento. Em seguida, use $user na seção match para agrupar toda a atividade relacionada a esse usuário específico.

O método de pesquisa estatística ajuda você a receber insights, tendências ou anomalias realizando cálculos em conjuntos de eventos. Em vez de retornar uma lista de registros individuais, ele fornece resumos agregados dos seus dados. A lógica usa a seção match (para agrupamento) e a seção outcome (para cálculos). A seção outcome oferece suporte a funções de agregação, como count(), sum(), avg(), max(), min() e stddev().

O exemplo a seguir usa esta lógica de consulta:

  • events: filtra os dados brutos de tentativas de login sem sucesso.
  • match: define os eventos de agrupamento (por userid).
  • outcome: realiza a agregação estatística (contagem de eventos por usuário).

Exemplo: agregar a atividade de login com falha usando funções outcome

O exemplo a seguir usa as funções de agregação da seção outcome (como count() ou sum()) para resumir a atividade de login com falha.

  1. Use a seção match para agrupar os eventos de login com falha por userid:

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

match:
  principal.user.userid

  2. Use o count de logins com falha para cada usuário ($failed_login_count), definido pela variável outcome:

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

match:
  principal.user.userid

outcome:
  $failed_login_count = count(metadata.id)

  3. Execute essa pesquisa para ver os resultados.

  4. Opcional: adicione um elemento de tempo à seção match (neste caso, day). Em seguida, atualize a variável outcome para ser mais explícita ($daily_failed_login_count):

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

match:
  $user by day

outcome:
  $daily_failed_login_count = count(metadata.id)

Criar um widget de painel com base na sua pesquisa

É possível criar um widget de painel com base em pesquisas agregadas, como mostrado no exemplo de como criar sua primeira pesquisa.

Depois que a pesquisa for validada, você poderá salvá-la como um widget e adicioná-la ao painel, da seguinte maneira:

  1. Quando os resultados aparecerem, clique na guia Visualizar > Adicionar ao painel.
  2. Configure o widget:
    1. Nomeie o widget (por exemplo, "Daily Failed Login").
    2. Selecione um período.
    3. Escolha se você quer adicionar a um painel novo ou existente.
    4. Clique em Adicionar.
  3. Opcional: crie consultas diretamente nos seus painéis. Como alternativa, você pode copiar painéis selecionados e modificar as edições nas consultas deles como ponto de partida.
  4. Opcional: você pode criar um painel personalizado e adicionar widgets a ele usando YARA-L. Para mais detalhes, consulte Criar um painel personalizado.

Configure um painel

Ao criar um painel, a seção events é um ponto de partida obrigatório. Lá, você tem a flexibilidade de usar match (para agrupar resultados) ou outcome (para calcular saídas e agregações).

Por exemplo, é possível ter um painel com as seções events e match, em que o painel mostra a gravidade ($severity) das detecções agrupadas em buckets by hour.

Exemplo: agregar séries temporais por gravidade

  • É possível criar um painel usando as seções events e match para mostrar a gravidade ($severity) das detecções agrupadas em intervalos hour:

    detection.detection.severity != "UNKNOWN_SEVERITY"
$severity = detection.detection.severity

match:
  $severity by hour

Exemplo: agregar o impacto total crítico

  • Da mesma forma, é possível criar um painel usando as seções events e outcome para acompanhar detecções de alta gravidade:

    detection.detection.severity = "CRITICAL"
$severity = detection.detection.severity

outcome:
  $detection_count = count_distinct($severity)

Exemplo: visualizar o volume de detecção por gravidade ao longo do tempo

  • No exemplo a seguir, você pode contar detecções críticas e especificar o período no console. Em muitos casos, você vai usar as seções match e outcome ao criar uma visualização em um dashboard:

    detection.detection.severity != "UNKNOWN_SEVERITY"
$severity = detection.detection.severity

match:
  $severity by hour

outcome:
  $detection_count = count_distinct(detection.id)

Exemplo: calcular a frequência de login do usuário

  • O exemplo a seguir se concentra no cálculo do login_count para usuários específicos usando as seções match e outcome:

    events:
  metadata.event_type = "USER_LOGIN"

match:
  target.user.userid

outcome:
  $login_count = count(metadata.id)

Criar uma regra

Uma regra requer as seguintes seções:

  • meta: contém o nome da regra e detalhes descritivos.
  • events: define suas fontes de dados e filtros usando variáveis de evento.
  • condition: especifica quais variáveis de evento precisam existir para que a regra seja acionada.

Definir e usar variáveis de evento

As variáveis de evento funcionam como um contêiner lógico, agrupando seus filtros para que você possa fazer referência a essa atividade específica em toda a pesquisa, regra ou painel.

Ao definir a lógica na seção events, você pode usar variáveis de evento (como $e) para representar um evento específico (ou um grupo de eventos) que corresponda aos seus critérios.

Exemplo: definir e filtrar variáveis de evento

  • Para definir uma variável de evento (por exemplo, $e), use um prefixo na seção events da consulta. Isso declara que esses eventos serão representados pela variável. Por exemplo, a expressão $e.principal.hostname = "dev" avalia cada evento para determinar se o nome do host é uma correspondência exata.

    $e.principal.hostname = "dev"
$e.metadata.event_type = "USER_LOGIN"

Em seguida, use essa variável em outras seções da consulta para fazer referência a esse grupo específico de eventos (nas seções match, outcome e condition) e aos campos de dados deles.

Organizar a estrutura e a sintaxe das regras

Use a estrutura e a sintaxe de regra a seguir para definir variáveis, lógica de agrupamento e limites de ativação:

Elemento Descrição Exemplo
Estrutura da regra Encapsula sua consulta em um bloco rule e atribui um nome exclusivo para identificar a detecção. rule DailyFailedLoginAttempts { }
Seção meta Obrigatório. Inclui metadados descritivos (como "author", "description", "severity") para melhorar o gerenciamento de regras e fornecer contexto à sua equipe. Recomendado como prática recomendada para gerenciamento de regras. author = "Alex"
severity = "Medium"
Variável de evento Em uma consulta de regras, cada campo na seção events tem um prefixo com uma variável de evento (como $e) para representar um evento específico (ou um grupo de eventos) que corresponda aos seus critérios. Eles funcionam como grupos lógicos de filtros.

No exemplo Converter sua pesquisa em uma regra YARA-L, $e representa todos os logins de usuários com falha.		 $e.metadata.event_type = "USER_LOGIN"
Variável de marcador de posição Atribui um evento a um nome comum que pode ser referenciado posteriormente na consulta. Para mais detalhes, consulte Usar variáveis de marcador de posição. $userid = $e.principal.user.userid
Seção match Define seus agrupamentos e especifica um período aceito. No exemplo Converter sua pesquisa em uma regra YARA-L, o agrupamento match: $userid over day agrupa corretamente os eventos pelo ID do usuário em cada período de 24 horas (1d).

Ao escrever uma regra, especifique um período de tempo compatível para definir o período de retorno. É possível implementar uma janela de salto, deslizante ou de rotação, dependendo dos requisitos da sua lógica. Usar o operador over cria explicitamente uma janela de salto. 		$userid over 1d
Seção outcome Realiza agregações estatísticas ou captura variáveis específicas para tornar os alertas resultantes mais informativos.

Use a função count() em $e.metadata.id para agregar eventos em cada grupo match. Você também pode atribuir variáveis, como $userid, para capturar campos específicos da UDM e fornecer mais contexto na saída de detecção resultante.		 $failed_count = count($e.metadata.id)
Seção condition Obrigatório para que uma regra gere uma detecção.

Define o limite de detecção na seção condition. Por exemplo, o uso de #e > 5 exige que a contagem de eventos exceda cinco (5) para acionar um alerta. Se você não estiver realizando cálculos, ainda precisará de uma seção condition e declarar a existência da variável de evento (por exemplo, #e).

Analise o valor de referência do seu ambiente para definir limites que detectem atividades suspeitas e minimizem os falsos positivos. Se você não estiver fazendo cálculos, ainda precisará de uma seção condition e declarar a existência da variável de evento, como #e.		 #e > 5 ou $e

Para entender como essa estrutura funciona, confira o exemplo a seguir.

Exemplo: detectar força bruta (vários logins com falha)

  • O exemplo a seguir detecta várias tentativas de login malsucedidas de um único usuário em um período de 24 horas:

    rule DailyFailedLoginAttempts {
  meta:
    author = "Alex"
    description = "Detects multiple failed login attempts for a single user within a day."
    severity = "Medium"

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

  match:
    $userid over 1d

  outcome:
    $daily_failed_login_count = count($e.metadata.id)

  condition:
    $daily_failed_login_count > 5
}

Para converter uma consulta de pesquisa finalizada em uma regra confiável para gerar detecções, siga estas etapas:

  1. No Google SecOps, acesse o Editor de regras.
  2. Inicie uma nova regra.
  3. Cole a consulta de pesquisa e modifique-a para se adequar à estrutura da regra, incluindo:
    • Seção meta: define a regra de metadados, incluindo o nome, o autor e o nível de gravidade.
    • Seção event: obrigatória. Ao contrário da pesquisa, você precisa ter um cabeçalho de seção event` nomeado.
    • Variáveis de evento: declaram e referenciam eventos específicos (ou grupos de eventos) na sua lógica.
    • Seção match com janelas de tempo compatíveis: especifica as chaves de agrupamento e define os parâmetros de tempo (por exemplo, 5m ou 1d). Observação: se você usar uma seção match nas regras, adicione uma janela de tempo.
    • Seção condition: define a lógica ou o limite final que precisa ser atendido para acionar uma regra.

Avançado: criar uma regra de vários eventos

Você usa uma regra de vários eventos para correlacionar diferentes tipos de atividade que ocorrem em um período específico. Em vez de analisar um único evento, você conecta vários eventos, como um usuário que faz login e, em seguida, faz o download de um arquivo incomum, para identificar ameaças complexas.

Uma regra de vários eventos exige as seguintes seções:

  • meta: contém o nome da regra e detalhes descritivos.
  • events: define suas fontes de dados e filtros usando variáveis de evento.
  • match: define o período e a variável de marcador de posição usada para vincular seus eventos.
  • outcomeCaptura mais contexto para o alerta. As regras com múltiplos eventos exigem uma função de agregação.
  • condition: especifica quais variáveis de evento precisam existir para que a regra seja acionada.

Para criar uma regra de vários eventos, faça o seguinte:

  1. Defina as variáveis de evento: na seção de eventos, defina $e1 para capturar eventos "PROCESS_LAUNCH" e $e2 para capturar hashes de arquivos maliciosos específicos.
  2. Correlacionar com marcadores de posição: use a variável de marcador de posição $user para conectar esses dois fluxos de eventos distintos por um ID de usuário principal compartilhado (por exemplo, $user = $e1.principal.user.userid and $user = $e2.principal.user.userid).
  3. Agrupe a correspondência: na seção match, especifique que esses eventos precisam acontecer para o mesmo $user em um período definido, como 5 minutos (5m).

Exemplo: criar uma regra de vários eventos

  • No exemplo a seguir, $e1 representa um evento PROCESS_LAUNCH, e $e2 representa um evento com um hash malicioso específico. A variável de marcador de posição $user correlaciona esses eventos pelo mesmo ID principal do usuário.

    rule MultiEventExample {
  meta:
    author = "Alex"
    description = "Detects a bad hash execution or a process launch from a specific IP for the same user."

  events:
    $e1.principal.ip = "1.1.1.1"
    $e1.metadata.event_type = "PROCESS_LAUNCH"
    $e2.target.file.sha256 = "badhash..."
    $user = $e1.principal.user.userid
    $user = $e2.principal.user.userid

  match:
    $user over 5m

  condition:
    $e1 or $e2
}

Os componentes de regra a seguir descrevem a lógica usada no exemplo:

  • Variáveis de evento: definimos duas variáveis de evento, $e1 e $e2. Usamos a variável de marcador de posição $user para unir esses eventos no campo comum userid.
  • Seção match: incluímos uma seção match para que essa regra de vários eventos agrupe por usuário e especifique uma janela de tempo de salto de cinco minutos (5m) para correlacionar os eventos.
  • Seção condition: define a lógica para acionar o alerta. Este exemplo aciona um alerta se o primeiro ou o segundo evento existir.

Usar outras ferramentas para criar sua consulta

Essas ferramentas são companheiras essenciais para escrever, validar e acelerar a adoção do YARA-L:

  • Ferramenta de pesquisa do UDM: pesquise e consulte rapidamente nomes de campos, definições e tipos de dados do UDM diretamente na UI. Se o ID do campo for desconhecido, priorize a verificação dessa referência.
  • Pesquisa de linguagem natural para YARA-L: na barra de pesquisa, insira descrições para elaborar sua consulta inicial ou receber ou traduzir sugestões correspondentes do YARA-L.
  • Tradutor de SPL para YARA-L (ferramenta do Labs): se você estiver migrando de plataformas concorrentes, use essa ferramenta (disponível na seção Labs) para converter consultas SPL legadas do Splunk em YARA-L. Isso gera um ponto de partida estruturado, o que acelera a migração e refina a lógica de detecção. Para usar a ferramenta do Labs, no Google SecOps, acesse yourinstancename.chronicle.security/labs.

A seguir

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