Sintaxe da linguagem YARA-L 2.0
Esta seção descreve os principais elementos da sintaxe YARA-L. Consulte também Visão geral da linguagem YARA-L 2.0.
Estrutura das regras
Para a YARA-L 2.0, especifique as declarações, as definições e os usos variáveis na seguinte ordem:
- Meta
- eventos
- correspondência (opcional)
- resultado (opcional)
- transição
- opções (opcional)
Veja a seguir a estrutura genérica de uma regra:
rule <rule Name>
{
meta:
// Stores arbitrary key-value pairs of rule details, such as who wrote
// it, what it detects on, version control, etc.
events:
// Conditions to filter events and the relationship between events.
match:
// Values to return when matches are found.
outcome:
// Additional information extracted from each detection.
condition:
// Condition to check events and the variables used to find matches.
options:
// Options to turn on or off while executing this rule.
}
Sintaxe de metases
A metaseção é composta por várias linhas, em que cada linha define um par de chave-valor. A parte da chave precisa ser uma string sem aspas, e a parte do valor precisa ser uma string entre aspas:
<key> = "<value>"
Este é um exemplo de uma linha de seção meta
válida:
meta:
author = "Google"
severity = "HIGH"
Sintaxe da seção de eventos
Na seção events
, liste os predicados para especificar o seguinte:
- Declarações de variáveis
- Filtros de variáveis de evento
- Mesclagens de variáveis de evento
Declarações de variáveis
Para declarações de variáveis, use a seguinte sintaxe:
<EVENT_FIELD> = <VAR>
<VAR> = <EVENT_FIELD>
Ambos são equivalentes, como mostrado nos exemplos a seguir:
$e.source.hostname = $hostname
$userid = $e.principal.user.userid
Essa declaração indica que a variável representa o campo especificado para a variável de evento. Quando o campo do evento é repetido, a variável de correspondência pode representar qualquer valor na matriz. Também é possível atribuir vários campos de evento a uma única variável de correspondência ou de marcador de posição. Essa é uma condição de mesclagem transitiva.
Por exemplo, os seguintes URLs:
$e1.source.ip = $ip
$e2.target.ip = $ip
São equivalentes a:
$e1.source.ip = $ip
$e1.source.ip = $e2.target.ip
Quando uma variável é usada, ela precisa ser declarada por meio da declaração da variável. Se uma variável for usada sem nenhuma declaração, ela será considerada um erro de compilação.
Filtros de variáveis de evento
Uma expressão booleana que atua sobre uma única variável de evento é considerada um filtro.
Mesclagens de variáveis de evento
Todas as variáveis de evento usadas na regra precisam ser mescladas com todas as outras variáveis de evento de uma das seguintes maneiras:
Diretamente, usando uma comparação de igualdade entre os campos de evento das duas variáveis de evento mescladas, por exemplo:
$e1.field = $e2.field
. A expressão não pode incluir aritmética.Indiretamente, por uma junção transitiva envolvendo apenas um campo de evento. Consulte a declaração de variável para ver a definição de "transitive join". A expressão não pode incluir aritmética.
Por exemplo, supondo que $e1, $e2 e $e3 sejam usados na regra, as seções events
a seguir são válidas.
events:
$e1.principal.hostname = $e2.src.hostname // $e1 joins with $e2
$e2.principal.ip = $e3.src.ip // $e2 joins with $e3
events:
// $e1 joins with $e2 via function to event comparison
re.capture($e1.src.hostname, ".*") = $e2.target.hostname
events:
// $e1 joins with $e2 via an `or` expression
$e1.principal.hostname = $e2.src.hostname
or $e1.principal.hostname = $e2.target.hostname
or $e1.principal.hostname = $e2.principal.hostname
events:
// all of $e1, $e2 and $e3 are transitively joined via the placeholder variable $ip
$e1.src.ip = $ip
$e2.target.ip = $ip
$e3.about.ip = $ip
events:
// $e1 and $e2 are transitively joined via function to event comparison
re.capture($e2.principal.application, ".*") = $app
$e1.principal.hostname = $app
No entanto, aqui estão alguns exemplos de seções events
inválidas.
events:
// Event to arithmetic comparison is an invalid join condition for $e1 and $e2.
$e1.principal.port = $e2.src.port + 1
events:
$e1.src.ip = $ip
$e2.target.ip = $ip
$e3.about.ip = "192.1.2.0" //$e3 is not joined with $e1 or $e2.
events:
$e1.src.port = $port
// Arithmetic to placeholder comparison is an invalid transitive join condition.
$e2.principal.port + 800 = $port
Sintaxe da seção de correspondência
Na seção match
, liste as variáveis de correspondência para eventos de grupo antes de verificar as condições de correspondência. Esses campos são retornados com cada correspondência.
- Especifique o que cada variável de correspondência representa na seção
events
. - Especifique a duração a ser usada para correlacionar eventos após a palavra-chave
over
. Os eventos fora desse período são ignorados. Use a seguinte sintaxe para especificar a duração:
<number><m/h/d>
Em que
m/h/d
significa minutos, horas e dias, respectivamente.O tempo mínimo que você pode especificar é de 1 minuto.
O tempo máximo que você pode especificar é de 48 horas.
Confira a seguir um exemplo de match
válido:
$var1, $var2 over 5m
Essa instrução retorna $var1
e $var2
(definidos na seção events
) quando a regra encontra uma correspondência. O tempo especificado é de 5 minutos. Os eventos com mais de cinco minutos de diferença não são correlacionados e, portanto, são ignorados pela regra.
Confira outro exemplo de uma seção match
válida:
$user over 1h
Essa instrução retorna $user
quando a regra encontra uma correspondência. O período especificado é de 1 hora. Eventos com mais de uma hora de diferença não são correlacionados. A regra não as considera como uma detecção.
Confira outro exemplo de uma seção match
válida:
$source_ip, $target_ip, $hostname over 2m
Essa instrução retorna $source_ip
, $target_ip
e $hostname
quando a regra encontra uma correspondência. A janela de tempo especificada é de 2 minutos. Eventos com mais de dois minutos de diferença não são correlacionados. A regra não as considera como uma detecção.
Os exemplos a seguir ilustram seções match
inválidas:
var1, var2 over 5m // invalid variable name
$user 1h // missing keyword
Processamento de valores zero na seção de correspondência
O Mecanismo de regras filtra implicitamente os valores zero para todos os marcadores de posição usados na seção de correspondência (""
para string, 0
para números, false
para booleanos, o valor na posição 0 para tipos enumerados).
O exemplo a seguir ilustra regras que filtram os valores zero.
rule ZeroValuePlaceholderExample {
meta:
events:
// Because $host is used in the match section, the rule behaves
// as if the following predicate was added to the events section:
// $host != ""
$host = $e.principal.hostname
// Because $otherPlaceholder was not used in the match section,
// there is no implicit filtering of zero values for $otherPlaceholder.
$otherPlaceholder = $e.principal.ip
match:
$host over 5m
condition:
$e
}
No entanto, se um marcador for atribuído a uma função, as regras não filtram implicitamente os valores zero dos marcadores usados na seção de correspondência. O exemplo a seguir ilustra regras que filtram os valores zero:
rule ZeroValueFunctionPlaceholder {
meta:
events:
// Even though $ph is used in the match section, there is no
// implicit filtering of zero values for $ph, because $ph is assigned to a function.
$ph = re.capture($e.principal.hostname, "some-regex")
match:
$ph over 5m
condition:
$e
}
Para desativar a filtragem implícita de valores zero,
use a opção allow_zero_values
na seção de opções.
Janela de salto
Por padrão, as regras da YARA-L 2.0 com uma seção de correspondência são avaliadas usando janelas de salto.
O intervalo de tempo da execução da regra é dividido em um conjunto de janelas de salto sobrepostas, cada uma com a duração especificada na seção match
. Os eventos são então correlacionados
dentro de cada janela de salto.
Por exemplo, para uma regra executada no intervalo de tempo [1:00, 2:00], com uma seção match
em 30m
, um possível conjunto de janelas de salto sobrepostas que poderia ser gerado é [1:00, 1:30], [1:03, 1:33] e [1:06, 1:36].
Essas janelas são usadas para correlacionar vários eventos.
Janela deslizante
Usar janelas de salto não é uma maneira eficaz de pesquisar eventos que acontecem em uma ordem específica (por exemplo, e1
acontece até dois minutos após e2
). Uma ocorrência do evento e1
e uma ocorrência do evento e2
são correlacionadas somente se se enquadrarem na mesma janela de salto gerada.
Uma maneira mais eficaz de pesquisar essas sequências de eventos é usar janelas deslizantes.
Janelas deslizantes com a duração especificada na seção match
são geradas ao
começar ou terminar com uma variável de evento dinâmica especificada. Os eventos são correlacionados dentro de cada janela deslizante. Isso permite pesquisar eventos que ocorrem em uma ordem específica (por exemplo, e1
acontece dentro de dois minutos de e2
). Uma ocorrência do evento e1
e uma ocorrência do evento e2
são correlacionadas se o evento e1
ocorrer na duração da janela deslizante após o evento e2
.
Especifique janelas deslizantes na seção match
de uma regra da seguinte maneira:
<match-var-1>, <match-var-2>, ... over <duration> before|after <pivot-event-var>
A variável de evento dinâmico é a variável de evento em que as janelas deslizantes se baseiam. Se você usar a palavra-chave before
, as janelas deslizantes serão geradas, terminando com cada ocorrência do evento dinâmico. Se a palavra-chave after
for usada, as janelas deslizantes serão geradas começando com cada ocorrência do evento dinâmico.
Confira abaixo exemplos de usos válidos de janelas deslizantes:
$var1, $var2 over 5m after $e1
$user over 1h before $e2
Veja um exemplo de regra de janela deslizante.
O Google recomenda não usar janelas deslizantes para regras de evento único, porque elas são projetadas para detectar vários eventos. Se uma das suas regras se enquadrar nessa categoria, o Google recomenda uma das seguintes soluções alternativas:
- Converta a regra para usar diversas variáveis de evento e atualize a seção de condição
se ela exigir mais de uma ocorrência do evento.
- Outra opção é adicionar filtros de carimbo de data/hora em vez de usar uma janela deslizante.
Por exemplo,
$permission_change.metadata.event_timestamp.seconds < $file_creation.metadata.event_timestamp.seconds
.
- Outra opção é adicionar filtros de carimbo de data/hora em vez de usar uma janela deslizante.
Por exemplo,
- Remover a janela deslizante.
Sintaxe da seção de resultados
Na seção outcome
, você pode definir até 20 variáveis de resultados, com
nomes arbitrários. Esses resultados serão armazenados nas detecções geradas
pela regra. Cada detecção pode ter valores diferentes para os resultados.
O nome do resultado, $risk_score
, é especial. Também é possível definir um
resultado com esse nome e, se você fizer isso, ele precisa ser um número inteiro ou um tipo flutuante. Se preenchido, o risk_score
será exibido na visualização do Enterprise Insights para alertas provenientes de detecções de regras.
Se você não incluir uma variável $risk_score
na seção de resultados de uma regra,
um dos valores padrão a seguir será definido:
- Se a regra estiver configurada para gerar um alerta,
$risk_score
será definido como 40. - Se a regra não estiver configurada para gerar um alerta,
$risk_score
será definido como 15.
O valor de $risk_score
é armazenado no campo de UDM security_result.risk_score
.
Tipos de dados variáveis de resultado
Cada variável de resultado pode ter um tipo de dados diferente, que é determinado pela expressão usada para calculá-lo. Oferecemos suporte aos seguintes tipos de dados de resultados:
- integer
- flutuadores
- string
- listas de números inteiros
- listas de pontos flutuantes
- listas de strings
Lógica condicional
Você pode usar a lógica condicional para calcular o valor de um resultado. Os condicionais são especificados usando o seguinte padrão de sintaxe:
if(BOOL_CLAUSE, THEN_CLAUSE)
if(BOOL_CLAUSE, THEN_CLAUSE, ELSE_CLAUSE)
Você pode ler uma expressão condicional como "se BOOL_CLAUSE for verdadeiro, então retornar THEN_CLAUSE, ou retornar ELSE_CLAUSE".
BOOL_CLAUSE precisa ser avaliado como um valor booleano. Uma expressão BOOL_CLAUSE tem uma forma semelhante às expressões na seção events
. Por exemplo, ela pode
conter:
Nomes de campos do UDM com operador de comparação, por exemplo:
if($context.graph.entity.user.title = "Vendor", 100, 0)
variável de marcador de posição que foi definida na seção
events
, por exemplo:if($severity = "HIGH", 100, 0)
outra variável de resultado definida na seção
outcome
, por exemplo:if($risk_score > 20, "HIGH", "LOW")
funções que retornam um booleano, por exemplo:
if(re.regex($e.network.email.from, `.*altostrat.com`), 100, 0)
procurar em uma lista de referências, por exemplo:
if($u.principal.hostname in %my_reference_list_name, 100, 0)
comparação de agregação, por exemplo:
if(count($login.metadata.event_timestamp.seconds) > 5, 100, 0)
THEN_CLAUSE e ELSE_CLAUSE precisam ter o mesmo tipo de dados. Aceitamos números inteiros, flutuantes e strings.
É possível omitir ELSE_CLAUSE se o tipo de dados for inteiro ou flutuante. Se omitido, ELSE_CLAUSE será avaliado como 0. Exemplo:
`if($e.field = "a", 5)` is equivalent to `if($e.field = "a", 5, 0)`
Forneça a ELSE_CLAUSE se o tipo de dados for string ou se THEN_CLAUSE for uma variável de marcador de posição ou de resultado.
Operações matemáticas
É possível usar operações matemáticas para calcular dados do tipo inteiro ou flutuante nas seções outcome
e events
de uma regra. As Operações de segurança do Google oferecem suporte a adição, subtração, multiplicação, divisão e módulo como operadores de nível superior em uma computação.
O snippet a seguir é um exemplo de computação na seção outcome
:
outcome:
$risk_score = max(100 + if($severity = "HIGH", 10, 5) - if($severity = "LOW", 20, 0))
Operações matemáticas são permitidas nos seguintes tipos de operandos, desde que cada operando e toda a expressão aritmética sejam devidamente agregados (consulte Agregações):
- Campos de eventos numéricos
- Variáveis de marcador numérico definidas na seção
events
- Variáveis de resultado numérico definidas na seção
outcome
- Funções que retornam ints ou flutuações
- Agregações que retornam ints ou flutuações
O módulo não é permitido em pontos flutuantes.
Variáveis de marcador nos resultados
Ao calcular variáveis de resultado, é possível usar variáveis de marcador de posição que foram definidas na seção de eventos da sua regra. Neste exemplo, suponha que $email_sent_bytes
tenha sido definido na seção de eventos da regra:
Exemplo de evento único:
// No match section, so this is a single-event rule.
outcome:
// Use placeholder directly as an outcome value.
$my_outcome = $email_sent_bytes
// Use placeholder in a conditional.
$other_outcome = if($file_size > 1024, "SEVERE", "MODERATE")
condition:
$e
Exemplo de vários eventos:
match:
// This is a multi event rule with a match section.
$hostname over 5m
outcome:
// Use placeholder directly in an aggregation function.
$max_email_size = max($email_sent_bytes)
// Use placeholder in a mathematical computation.
$total_bytes_exfiltrated = sum(
1024
+ $email_sent_bytes
+ $file_event.principal.file.size
)
condition:
$email_event and $file_event
Variáveis de resultado em expressões de atribuição de resultado
As variáveis de resultado podem ser usadas para derivar outras variáveis de resultado, semelhantes às variáveis de marcador de posição definidas na seção events
. É possível referenciar uma variável de resultado na atribuição de outra com um token $
seguido pelo nome dela. As variáveis de resultado precisam ser definidas antes de serem referenciadas no texto da regra. Quando usadas em uma expressão de atribuição, as variáveis de resultado não podem ser agregadas (consulte Agregações).
No exemplo a seguir, a variável de resultado $risk_score
deriva seu
valor da variável de resultado $event_count
:
Exemplo de vários eventos:
match:
// This is a multi event rule with a match section.
$hostname over 5m
outcome:
// Aggregates all timestamp on login events in the 5 minute match window.
$event_count = count($login.metadata.event_timestamp.seconds)
// $event_count cannot be aggregated again.
$risk_score = if($event_count > 5, "SEVERE", "MODERATE")
// This is the equivalent of the 2 outcomes above combined.
$risk_score2 = if(count($login.metadata.event_timestamp.seconds) > 5, "SEVERE", "MODERATE")
condition:
$e
As variáveis de resultado podem ser usadas em qualquer tipo de expressão no lado direito de uma atribuição de resultado, exceto nas seguintes expressões:
- Agregações
Arrays.length()
chamadas de funções- Com modificadores
any
ouall
Agregações
Campos de eventos repetidos não são valores escalares. Ou seja, uma única variável aponta
para vários valores. Por exemplo, a variável de campo de evento $e.target.ip
é um campo repetido e pode ter zero, um ou muitos valores de IP. É um valor não escalar. Já a variável $e.principal.hostname
do campo de evento não é um campo repetido e tem apenas um valor, ou seja, um valor escalar.
Da mesma forma, campos de eventos não repetidos e campos de eventos repetidos usados na seção de resultados de uma regra com uma janela de correspondência são valores não escalares. Por exemplo, a regra a seguir agrupa eventos usando uma seção de correspondência e se refere a um campo de evento não repetido na seção de resultados:
rule OutcomeAndMatchWindow{
...
match:
$userid over 5m
outcome:
$hostnames = array($e.principal.hostname)
...
}
Qualquer janela de cinco minutos em que a regra for executada poderá conter nenhum, um ou vários eventos. A seção de resultados
opera em todos os eventos em uma janela de correspondência. Qualquer variável de campo de evento citada na seção de resultados pode apontar para zero, um ou muitos valores do campo em cada evento na janela de correspondência.
Na regra anterior, se uma janela de cinco minutos contiver cinco eventos $e
, o $e.principal.hostname
na seção de resultados vai apontar para cinco nomes de host diferentes. Portanto, a variável do campo de evento $e.principal.hostname
é um valor não escalar na seção de resultado desta regra.
Como as variáveis de resultado precisam sempre produzir um único valor escalar, qualquer valor não escalar de que uma atribuição de resultado depende precisa ser agregado para gerar um único valor escalar. Em uma seção de resultado, estes são valores não escalares e precisam ser agregados:
- Campos de evento (repetidos ou não) quando a regra usa uma seção de correspondência
- Marcadores de evento (repetidos ou não repetidos) quando a regra usa uma seção de correspondência
- Campos de eventos repetidos quando a regra não usa uma seção de correspondência
- Marcadores de eventos repetidos quando a regra não usa uma seção de correspondência
Campos de eventos escalares, marcadores de eventos escalares e constantes podem ser unidos em uma agregação em uma regra que não usa uma seção de correspondência. No entanto, a maioria das agregações produz o valor unido e, portanto, são desnecessárias. A exceção é a agregação array()
, que pode ser usada para converter um valor escalar em uma matriz.
As variáveis de resultado são tratadas como agregações: não podem ser agregadas novamente quando mencionadas em outra atribuição de resultado.
Você pode usar as seguintes funções de agregação:
max()
: gera o máximo de todos os valores possíveis. Funciona apenas com números inteiros e flutuantes.min()
: gera o mínimo entre todos os valores possíveis. Funciona apenas com números inteiros e flutuantes.sum()
: gera a soma de todos os valores possíveis. Funciona apenas com números inteiros e flutuantes.count_distinct()
: coleta todos os valores possíveis e gera a contagem distinta de valores possíveis.count()
: se comporta comocount_distinct()
, mas retorna uma contagem não distinta de valores possíveis.array_distinct()
: coleta todos os valores distintos possíveis e gera uma lista deles. A lista de valores distintos será truncada para 25 elementos aleatórios. A eliminação de duplicação para conseguir uma lista distinta é aplicado primeiro, depois o truncamento.array()
: se comporta comoarray_distinct()
, mas retorna uma lista não distinta de valores. A lista de valores também é truncada para 25 elementos aleatórios.
A função agregada é importante quando uma regra inclui uma seção condition
que especifica a existência de vários eventos, porque ela
opera em todos os eventos que geraram a detecção.
Por exemplo, se as seções outcome
e condition
contiverem:
outcome:
$asset_id_count = count($event.principal.asset_id)
$asset_id_distinct_count = count_distinct($event.principal.asset_id)
$asset_id_list = array($event.principal.asset_id)
$asset_id_distinct_list = array_distinct($event.principal.asset_id)
condition:
#event > 1
Como a seção de condição exige que haja mais de um event
para cada
detecção, as funções de agregação operam em vários eventos. Suponha que os seguintes eventos tenham gerado uma detecção:
event:
// UDM event 1
asset_id="asset-a"
event:
// UDM event 2
asset_id="asset-b"
event:
// UDM event 3
asset_id="asset-b"
Então, os valores de seus resultados serão:
- $asset_id_count =
3
- $asset_id_distinct_count =
2
- $asset_id_list =
["asset-a", "asset-b", "asset-b"]
- $asset_id_distinct_list =
["asset-a", "asset-b"]
Informações importantes ao usar a seção de resultados:
Outras observações e restrições:
- A seção
outcome
não pode referenciar uma nova variável de marcador que ainda não tenha sido definida na seçãoevents
ou na seçãooutcome
. - A seção
outcome
não pode usar variáveis de eventos que não foram definidas na seçãoevents
. - A seção
outcome
pode usar um campo de evento que não foi usado na seçãoevents
, já que a variável de evento a que o campo de evento pertence já foi definida na seçãoevents
. - A seção
outcome
só pode correlacionar variáveis de eventos que já foram correlacionadas na seçãoevents
. As correlações ocorrem quando dois campos de eventos de diferentes variáveis de evento são iguais.
Você pode encontrar um exemplo usando a seção de resultados na Visão geral da YARA-L 2.0. Consulte Criar análises baseadas no contexto para detalhes sobre a dedução de detecção com a seção de resultados.
Sintaxe da seção de condição
- especifique uma condição de correspondência para eventos e marcadores de posição definidos na seção
events
. Consulte a seção a seguir, Condicionais de marcador de posição e evento, para mais detalhes. - (opcional) use a palavra-chave
and
para especificar uma condição de correspondência com variáveis de resultado definidas na seçãooutcome
. Consulte a seção a seguir, Condicionais de resultado, para mais detalhes.
Contar caractere
#
é um caractere especial na seção condition
. Se usado antes de qualquer nome de variável de marcador de posição ou evento, ele representa o número de eventos ou valores distintos que atendem a todas as condições da seção events
.
Por exemplo, #c > 1
significa que a variável c
precisa ocorrer mais de uma vez.
Caractere do valor
$
é um caractere especial na seção condition
. Se for
usado antes de qualquer nome de variável de resultado, ele representará o valor desse resultado.
Se usado antes de qualquer nome de variável de evento ou marcador de posição (por exemplo,
$event
), ele representa #event > 0
.
Condições de evento e marcador de posição
Liste predicados de condição para eventos e variáveis de marcador de posição aqui, combinados com a palavra-chave and
ou or
. A palavra-chave and
pode ser usada entre qualquer condição, mas a palavra-chave or
só pode ser usada quando a regra tem apenas uma única variável de evento.
Um exemplo válido do uso de or
entre dois marcadores de posição no mesmo evento:
rule ValidConditionOr {
meta:
events:
$e.metadata.event_type = "NETWORK_CONNECTION"
// Note that all placeholders use the same event variable.
$ph = $e.principal.user.userid // Define a placeholder variable to put in match section.
$ph2 = $e.principal.ip // Define a second placeholder variable to put in condition section.
$ph3 = $e.principal.hostname // Define a third placeholder variable to put in condition section.
match:
$ph over 5m
condition:
$ph2 or $ph3
}
Um exemplo inválido do uso de or
entre duas condições em eventos diferentes:
rule InvalidConditionOr {
meta:
events:
$e.metadata.event_type = "NETWORK_CONNECTION"
$e2.graph.metadata.entity_type = "FILE"
$e2.graph.entity.hostname = $e.principal.hostname
$ph = $e.principal.user.userid // Define a placeholder variable to put in match section.
match:
$ph over 5m
condition:
$e or $e2 // This line will cause an error because there is an or between events.
}
Condições limitadas e ilimitadas
As condições a seguir são condições limitadas. Elas forçam a existência da variável de evento associada, o que significa que pelo menos uma ocorrência do evento precisa aparecer em qualquer detecção.
$var // equivalent to #var > 0
#var > n // where n >= 0
#var >= m // where m > 0
As condições a seguir são ilimitadas. Eles permitem que a variável de evento associada não exista, o que significa que é possível que nenhuma ocorrência do evento apareça em uma detecção e qualquer referência a campos na variável de evento produza um valor zero. Condições ilimitadas podem ser usadas para detectar a ausência de um evento durante um período. Por exemplo, um evento de ameaça sem um evento de mitigação em uma janela de 10 minutos. As regras que usam condições ilimitadas são chamadas de regras de não existência.
!$var // equivalent to #var = 0
#var >= 0
#var < n // where n > 0
#var <= m // where m >= 0
Requisitos para inexistência
Para que uma regra com não existência seja compilada, ela precisa atender aos seguintes requisitos:
- Pelo menos um evento de UDM precisa ter uma condição limitada, ou seja, ter pelo menos um evento de UDM.
- Se um marcador tiver uma condição ilimitada, ele precisará estar associado a pelo menos um evento de UDM limitado.
- Se uma entidade tiver uma condição ilimitada, ela precisará ser associada a pelo menos um evento de UDM limitado.
Considere a seguinte regra com a seção de condição omitida:
rule NonexistenceExample {
meta:
events:
$u1.metadata.event_type = "NETWORK_CONNECTION" // $u1 is a UDM event.
$u2.metadata.event_type = "NETWORK_CONNECTION" // $u2 is a UDM event.
$e1.graph.metadata.entity_type = "FILE" // $e1 is an Entity.
$e2.graph.metadata.entity_type = "FILE" // $e2 is an Entity.
$user = $u1.principal.user.userid // Match variable is required for Multi-Event Rule.
// Placeholder Associations:
// u1 u2
// | \ /
// port ip
// | \
// e1 e2
$u1.target.port = $port
$e1.graph.entity.port = $port
$u1.principal.ip = $ip
$u2.target.ip = $ip
$e2.graph.entity.ip = $ip
// UDM-Entity Associations:
// u1 - u2
// | \ |
// e1 e2
$u1.metadata.event_type = $u2.metadata.event_type
$e1.graph.entity.hostname = $u1.principal.hostname
$e2.graph.entity.hostname = $u1.target.hostname
$e2.graph.entity.hostname = $u2.principal.hostname
match:
$user over 5m
condition:
<condition_section>
}
Confira a seguir exemplos válidos para a <condition_section>
:
$u1 and !$u2 and $e1 and $e2
- Todos os eventos e entidades de UDM estão presentes na seção de condição.
- Pelo menos um evento de UDM é vinculado.
$u1 and !$u2 and $e1 and !$e2
$e2
é ilimitado, o que é permitido porque está associado a$u1
, que é limitado. Se$e2
não estiver associado a$u1
, isso será inválido.
#port > 50 and #ip = 0
- Não há eventos e entidades de UDM na seção de condição. No entanto, os marcadores presentes abrangem todos os eventos e entidades de UDM.
$ip
é atribuído a$u1
e$u2
, e#ip = 0
é uma condição ilimitada. No entanto, as condições limitadas são mais fortes do que as ilimitadas. Como$port
é atribuído a$u1
e#port > 50
é uma condição limitada,$u1
ainda é limitada.
Os seguintes exemplos são inválidos para a <condition_section>
:
$u1 and $e1
- Cada evento e entidade de UDM que aparece na seção "Eventos" precisa aparecer na seção "Condição" (ou ter um marcador de posição atribuído a ele na seção "Condição").
$u1, $u2, $e1, $u2, #port > 50
- Vírgulas não são permitidas como separadores de condição.
!$u1 and !$u2 and $e1 and $e2
- Viola o primeiro requisito de que pelo menos um evento de UDM seja vinculado.
($u1 or #port < 50) and $u2 and $e1 and $e2
- A palavra-chave
or
não é compatível com condições ilimitadas.
- A palavra-chave
($u1 or $u2) and $e1 and $e2
- A palavra-chave
or
não tem suporte entre variáveis de eventos diferentes.
- A palavra-chave
not $u1 and $u2 and $e1 and $e2
- A palavra-chave
not
não é permitida para condições de evento e de marcador.
- A palavra-chave
#port < 50 and #ip = 0
- Os marcadores presentes abrangem todos os eventos e entidades de UDM. No entanto, todas as condições são ilimitadas. Isso significa que nenhum dos eventos de UDM é limitado, fazendo com que a regra não seja compilada.
Condicionais de resultado
Liste os predicados de condição das variáveis de resultado aqui, unidos com a palavra-chave and
ou or
ou precedidos pela palavra-chave not
.
Especifique os condicionais de resultado de maneira diferente, dependendo do tipo da variável de resultado:
integer: compara com um literal de número inteiro com os operadores
=, >, >=, <, <=, !=
, por exemplo:$risk_score > 10
float: compara com um literal flutuante com operadores
=, >, >=, <, <=, !=
, por exemplo:$risk_score <= 5.5
string: compara com um literal de string com
=
ou!=
, por exemplo:$severity = "HIGH"
lista de números inteiros ou matrizes: especifique a condição usando a função
arrays.contains
, por exemplo:arrays.contains($event_ids, "id_1234")
Classificação de regras
Especificar uma condição de resultado em uma regra que tenha uma seção de correspondência significa que a regra será classificada como uma regra de vários eventos para a cota de regras. Consulte a regra de evento único e a regra de vários eventos para mais informações sobre classificações de um ou vários eventos.
Sintaxe da seção de opções
Na seção options
, é possível especificar as opções para a regra. Confira
este exemplo de como especificar a seção de opções:
rule RuleOptionsExample {
// Other rule sections
options:
allow_zero_values = true
}
É possível especificar opções usando a sintaxe key = value
, em que key
precisa ser um nome de opção predefinido e value
precisa ser um valor válido para a opção, conforme especificado para as opções a seguir:
allow_zero_values
Os valores válidos para essa opção são true
e false
, que determinam
se ela está ativada ou não. O valor padrão é false
. Essa opção ficará
desativada se não for especificada na regra.
Para ativar essa configuração, adicione o seguinte à seção de opções da sua regra: allow_zero_values = true
. Isso
vai impedir que a regra filtre implicitamente os
valores zero dos marcadores usados na seção de correspondência, conforme
descrito em Processamento de valores zero na seção de correspondência.
Expressões booleanas
As expressões booleanas são expressões com um tipo booleano.
Comparações
Para que uma expressão binária use como condição, use a seguinte sintaxe:
<EXPR> <OP> <EXPR>
A expressão pode ser um campo de evento, uma variável, um literal ou uma expressão de função.
Exemplo:
$e.source.hostname = "host1234"
$e.source.port < 1024
1024 < $e.source.port
$e1.source.hostname != $e2.target.hostname
$e1.metadata.collected_timestamp.seconds > $e2.metadata.collected_timestamp.seconds
$port >= 25
$host = $e2.target.hostname
"google-test" = strings.concat($e.principal.hostname, "-test")
"email@google.org" = re.replace($e.network.email.from, "com", "org")
Se os dois lados forem literais, isso será considerado um erro de compilação.
Funções
Algumas expressões de função retornam um valor booleano, que pode ser usado como um predicado individual na seção events
. Essas funções são:
re.regex()
net.ip_in_range_cidr()
Exemplo:
re.regex($e.principal.hostname, `.*\.google\.com`)
net.ip_in_range_cidr($e.principal.ip, "192.0.2.0/24")
Expressões da lista de referências
Você pode usar listas de referências na seção de eventos. Consulte a seção sobre Listas de referência para mais detalhes.
Expressões lógicas
Você pode usar os operadores lógicos and
e or
na seção events
, conforme mostrado nos exemplos a seguir:
$e.metadata.event_type = "NETWORK_DNS" or $e.metadata.event_type = "NETWORK_DHCP"
($e.metadata.event_type = "NETWORK_DNS" and $e.principal.ip = "192.0.2.12") or ($e.metadata.event_type = "NETWORK_DHCP" and $e.principal.mac = "AB:CD:01:10:EF:22")
not $e.metadata.event_type = "NETWORK_DNS"
Por padrão, a ordem de precedência da maior para a menor é not
, and
, or
.
Por exemplo, "a ou b e c" é avaliado como "a ou (b e c)" quando os operadores or
e and
são definidos explicitamente na expressão.
Na seção events
, os predicados são combinados usando o operador and
se um operador não for definido explicitamente.
A ordem da avaliação poderá ser diferente se o operador and
estiver implícito na expressão.
Por exemplo, considere as expressões de comparação a seguir, em que or
é definido explicitamente. O operador and
está implícito.
$e1.field = "bat"
or $e1.field = "baz"
$e2.field = "bar"
Este exemplo é interpretado da seguinte maneira:
($e1.field = "bat" or $e1.field = "baz")
and ($e2.field = "bar")
Como or
é definido explicitamente, os predicados em torno de or
são agrupados e avaliados primeiro.
O último predicado, $e2.field = "bar"
, é unido implicitamente usando and
. O resultado é que a ordem de avaliação muda.
Tipos enumerados
Você pode usar os operadores com tipos enumerados. Isso pode ser aplicado a regras para simplificar e otimizar o desempenho (use operadores em vez de listas de referência).
No exemplo a seguir, "USER_UNCATEGORIZED" e "USER_RESOURCE_DELETION" correspondem a 15000 e 15014. Portanto, a regra vai procurar todos os eventos listados:
$e.metadata.event_type >= "USER_CATEGORIZED" and $e.metadata.event_type <= "USER_RESOURCE_DELETION"
Lista de eventos:
- USER_RESOURCE_DELETION
- USER_RESOURCE_UPDATE_CONTENT
- USER_RESOURCE_UPDATE_PERMISSIONS
- USER_STATS
- USER_UNCATEGORIZED
Modificador de ausência de maiúsculas
Quando você tem uma expressão de comparação entre valores de string ou uma expressão regular, é possível acrescentar sem maiúsculas no final da expressão para ignorar a capitalização.
$e.principal.hostname != "http-server" nocase
$e1.principal.hostname = $e2.target.hostname nocase
$e.principal.hostname = /dns-server-[0-9]+/ nocase
re.regex($e.target.hostname, `client-[0-9]+`) nocase
Isso não pode ser usado quando um tipo de campo é um valor enumerado. Os exemplos abaixo são inválidos e vão gerar erros de compilação:
$e.metadata.event_type = "NETWORK_DNS" nocase
$e.network.ip_protocol = "TCP" nocase
Campos repetidos
No Modelo de dados unificado (UDM), alguns campos são rotulados como repetidos, o que indica que são listas de valores ou outros tipos de mensagens.
Campos repetidos e expressões booleanas
Há dois tipos de expressões booleanas que atuam em campos repetidos:
- Modificada
- Não modificado
Considere o seguinte evento:
event_original {
principal {
// ip is a repeated field
ip: [ "192.0.2.1", "192.0.2.2", "192.0.2.3" ]
hostname: "host"
}
}
Expressões modificadas
As seções a seguir descrevem a finalidade e como usar os modificadores any
e all
em expressões.
qualquer um
Se qualquer elemento do campo repetido atender à condição, o evento como um todo satisfaz a condição.
event_original
satisfazany $e.principal.ip = "192.0.2.1"
.event_original
falhaany $e.repeated_field.field_a = "9.9.9.9
.
todas
Se todos os elementos do campo repetido atenderem à condição, o evento como um todo atenderá à condição.
event_original
satisfaznet.ip_in_range_cidr(all $e.principal.ip, "192.0.2.0/8")
.event_original
falhaall $e.principal.ip = "192.0.2.2"
.
Ao escrever uma condição com any
ou all
, esteja ciente de que negar a condição com not
pode não ter o mesmo significado que usar o operador negado.
Exemplo:
not all $e.principal.ip = "192.168.12.16"
verifica se nem todos os endereços IP correspondem a192.168.12.16
, o que significa que a regra está verificando se pelo menos um endereço IP não corresponde a192.168.12.16
.all $e.principal.ip != "192.168.12.16"
verifica se todos os endereços IP não correspondem a192.168.12.16
, o que significa que a regra está verificando se nenhum endereço IP corresponde a192.168.12.16
.
Restrições:
- Os operadores
any
eall
são compatíveis apenas com campos repetidos, e não campos escalares. any
eall
não podem ser usados para unir dois campos repetidos. Por exemplo,any $e1.principal.ip = $e2.principal.ip
não é válido.- Os operadores
any
eall
não são compatíveis com a expressão da lista de referência.
Expressões não modificadas
Com expressões não modificadas, cada elemento no campo repetido é tratado individualmente. Se o campo repetido de um evento tiver n elementos, a regra será aplicada a n cópias do evento, em que cada cópia tiver um dos elementos do campo repetido. Essas cópias são temporárias e não são armazenadas.
A regra é aplicada às seguintes cópias:
cópia do evento | principal.ip | principal.hostname |
---|---|---|
event_copy_1 | “192.0.2.1” | "apresentador" |
event_copy_2 | “192.0.2.2” | "apresentador" |
event_copy_3 | “192.0.2.3” | "apresentador" |
Se qualquer cópia do evento satisfizer a todas as condições não modificadas no campo repetido, o evento como um todo atenderá a todas as condições. Isso significa que, se você tiver várias condições em um campo repetido, a cópia do evento precisará atender a todas elas. Os exemplos de regras a seguir usam o conjunto de dados de exemplo anterior para demonstrar esse comportamento.
A regra a seguir retorna uma correspondência quando executada no conjunto de dados de exemplo event_original
, porque event_copy_1
satisfaz todos os predicados de eventos:
rule repeated_field_1 {
meta:
events:
net.ip_in_range_cidr($e.principal.ip, "192.0.2.0/8") // Checks if IP address matches 192.x.x.x
$e.principal.ip = "192.0.2.1"
condition:
$e
}
A regra a seguir não retorna uma correspondência quando executada no conjunto de dados de exemplo event_original
, porque não há nenhuma cópia de evento em $e.principal.ip
que satisfaça todos os predicados do evento.
rule repeated_field_2 {
meta:
events:
$e.principal.ip = "192.0.2.1"
$e.principal.ip = "192.0.2.2"
condition:
$e
}
As expressões modificadas em campos repetidos são compatíveis com expressões não modificadas em campos repetidos porque a lista de elementos é a mesma para cada cópia do evento. Considere a seguinte regra:
rule repeated_field_3 {
meta:
events:
any $e.principal.ip = "192.0.2.1"
$e.principal.ip = "192.0.2.3"
condition:
$e
}
A regra é aplicada às seguintes cópias:
cópia do evento | principal.ip | qualquer $e.principal.ip |
---|---|---|
event_copy_1 | “192.0.2.1” | ["192.0.2.1", "192.0.2.2", "192.0.2.3"] |
event_copy_2 | “192.0.2.2” | ["192.0.2.1", "192.0.2.2", "192.0.2.3"] |
event_copy_3 | “192.0.2.3” | ["192.0.2.1", "192.0.2.2", "192.0.2.3"] |
Nesse caso, todas as cópias atendem a any $e.principal.ip = "192.0.2.1"
, mas apenas event_copy_3
satisfaz $e.principal.ip = "192.0.2.3". Como resultado, o evento como um todo seria correspondente.
Outra maneira de pensar sobre esses tipos de expressão é:
- As expressões em campos repetidos que usam
any
ouall
operam na lista emevent_original
. - Expressões em campos repetidos que não usam
any
ouall
operam em eventosevent_copy_n
individuais.
Campos repetidos e marcadores de posição
Os campos repetidos funcionam com atribuições de marcadores de posição. Semelhante às expressões não modificadas em campos repetidos, uma cópia do evento é feita para cada elemento. Usando o mesmo exemplo de event_copy
, o marcador de posição usa o valor do valor do campo repetido de event_copy_n
para cada uma das cópias do evento, em que n é o número da cópia do evento. Se o marcador for usado na seção de correspondência, poderá haver várias correspondências.
O exemplo a seguir gera uma correspondência. O marcador $ip
é igual
a 192.0.2.1
para event_copy_1
, que satisfaz os predicados na regra.
Os exemplos de eventos de correspondência contêm um único elemento, event_original
.
// Generates 1 match.
rule repeated_field_placeholder1 {
meta:
events:
$ip = $e.principal.ip
$ip = "192.0.2.1"
$host = $e.principal.hostname
match:
$host over 5m
condition:
$e
}
O exemplo a seguir gera três correspondências. O marcador $ip
é igual
a valores diferentes para cada uma das diferentes cópias de event_copy_n
.
O agrupamento é feito em $ip
, porque ele está na seção de correspondência. Portanto, você obtém três correspondências em que cada correspondência tem um valor diferente para a variável de correspondência $ip
. Cada correspondência tem a mesma amostra de evento: um único elemento, event_original
.
// Generates 3 matches.
rule repeated_field_placeholder2 {
meta:
events:
$ip = $e.principal.ip
net.ip_in_range_cidr($ip, "192.0.2.0/8") // Checks if IP matches 192.x.x.x
match:
$ip over 5m
condition:
$e
}
Resultados que usam marcadores de posição atribuídos a campos repetidos
Marcadores são atribuídos a cada elemento de cada campo repetido, não a toda a lista. Assim, quando usados na seção de resultados, eles são calculados usando apenas os elementos que atenderam às seções anteriores.
Considere a seguinte regra:
rule outcome_repeated_field_placeholder {
meta:
events:
$ip = $e.principal.ip
$ip = "192.0.2.1" or $ip = "192.0.2.2"
$host = $e.principal.hostname
match:
$host over 5m
outcome:
$o = array_distinct($ip)
condition:
$e
}
Existem quatro estágios de execução para essa regra. A primeira etapa é a cópia do evento:
cópia do evento | $ip | $host | $e |
---|---|---|---|
event_copy_1 | “192.0.2.1” | "apresentador" | event_id |
event_copy_2 | “192.0.2.2” | "apresentador" | event_id |
event_copy_3 | “192.0.2.3” | "apresentador" | event_id |
A seção de eventos vai filtrar as linhas que não corresponderem aos filtros:
cópia do evento | $ip | $host | $e |
---|---|---|---|
event_copy_1 | “192.0.2.1” | "apresentador" | event_id |
event_copy_2 | “192.0.2.2” | "apresentador" | event_id |
event_copy_3
foi filtrado porque "192.0.2.3"
não atende a $ip = "192.0.2.1" or $ip = "192.0.2.2"
.
A seção de correspondência é agrupada por variáveis de correspondência, e a seção de resultados faz a agregação em cada grupo:
$host | $o | $e |
---|---|---|
"apresentador" | ["192.0.2.1", "192.0.2.2"] | event_id |
$o = array_distinct($ip)
é calculado usando o $ip
do cenário anterior, e não do cenário de cópia de eventos.
Por fim, a seção de condição vai filtrar cada grupo. Como essa regra apenas verifica a existência de $e, a linha anterior produzirá uma única detecção.
$o
não contém todos os elementos de $e.principal.ip
porque nem todos eles atendem a todas as condições na seção de eventos. No entanto, todos os elementos de e.principal.ip
aparecerão na amostra de evento porque ela usa event_original
.
Indexação de matrizes
Você pode realizar a indexação de matrizes em campos repetidos. Para acessar o enésimo elemento de campo repetido, use a sintaxe de lista padrão (os elementos são indexados em 0). Um elemento fora dos limites retorna o valor padrão.
$e.principal.ip[0] = "192.168.12.16"
$e.principal.ip[999] = ""
Se houver menos de 1.000 elementos, será avaliado comotrue
.
Restrições:
- O índice precisa ser um literal inteiro não negativo. Por exemplo,
$e.principal.ip[-1]
não é válido. - Valores do tipo
int
(por exemplo, um marcador definido comoint
) não contam. - A indexação de matriz não pode ser combinada com
any
ouall
. Por exemplo,any $e.intermediary.ip[0]
não é válido. - A indexação de matriz não pode ser combinada com a sintaxe do mapa. Por exemplo,
$e.additional.fields[0]["key"]
não é válido. - Se o caminho tiver vários campos repetidos, todos eles precisarão usar a indexação de matriz. Por exemplo,
$e.intermediary.ip[0]
não é válido porqueintermediary
eip
são campos repetidos, mas existe apenas um índice paraip
.
Mensagens repetidas
Quando um campo message
é repetido, um efeito não intencional é reduzir a probabilidade de uma correspondência. Isso é ilustrado nos exemplos a seguir.
Considere o seguinte evento:
event_repeated_message {
// about is a repeated message field.
about {
// ip is a repeated string field.
ip: [ "192.0.2.1", "192.0.2.2", "192.0.2.3" ]
hostname: "alice"
}
about {
hostname: "bob"
}
}
Conforme indicado para expressões não modificadas em campos repetidos, uma cópia temporária do evento é feita para cada elemento do campo repetido. Considere a seguinte regra:
rule repeated_message_1 {
meta:
events:
$e.about.ip = "192.0.2.1"
$e.about.hostname = "bob"
condition:
$e
}
A regra é aplicada às seguintes cópias:
cópia do evento | about.ip | about.hostname |
---|---|---|
event_copy_1 | “192.0.2.1” | "alice" |
event_copy_2 | “192.0.2.2” | "alice" |
event_copy_3 | “192.0.2.3” | "alice" |
event_copy_4 | "" | "bob" |
O evento não corresponde à regra porque não existe uma cópia do evento que satisfaça todas as expressões.
Mensagens repetidas e indexação de matrizes
Outro comportamento inesperado pode ocorrer ao usar a indexação de matriz com expressões não modificadas em campos de mensagens repetidos. Considere a seguinte regra de exemplo que usa indexação de matriz:
rule repeated_message_2 {
meta:
events:
$e.about.ip = "192.0.2.1"
$e.about[1].hostname = "bob"
condition:
$e
}
A regra é aplicada às seguintes cópias:
cópia do evento | about.ip | sobre[1].hostname |
---|---|---|
event_copy_1 | “192.0.2.1” | "bob" |
event_copy_2 | “192.0.2.2” | "bob" |
event_copy_3 | “192.0.2.3” | "bob" |
event_copy_4 | "" | "bob" |
Como event_copy_1
satisfaz todas as expressões em repeated_message_2
, o evento corresponde à regra.
Isso pode causar um comportamento inesperado porque a regra repeated_message_1
não tinha indexação de matriz e não produziu correspondências, enquanto a regra repeated_message_2
usava a indexação de matriz e produzia uma correspondência.
Comentários
Designe comentários com duas barras (// comment
) ou comentários de várias linhas separados por barras de asterisco (/* comment */
), como você faria em C.
Literais
Números inteiros e flutuantes não negativos, literais de string, booleanos e de expressão regular são compatíveis.
Literais de strings e expressões regulares
Você pode usar qualquer um dos seguintes caracteres de aspas para colocar strings entre YARA-L 2.0. No entanto, o texto das mensagens anteriores é interpretado de maneira diferente dependendo do que você usa.
Aspas duplas (") — use para strings normais. Precisa incluir caracteres de escape.
Por exemplo: "hello\tworld" —\t é interpretado como uma tabulaçãoAspas (`) — use para interpretar todos os caracteres literalmente.
Por exemplo: "hello\tworld" —\t não é interpretado como uma tabulação.
Há duas opções para expressões regulares.
Se você quiser usar expressões regulares diretamente sem a função re.regex()
, use /regex/
para os literais de expressões regulares.
Também é possível usar literais de string como literais de expressão regular ao usar a função re.regex()
. Para literais de string de aspas duplas, é necessário fazer o escape de caracteres de barra invertida com caracteres de barra invertida, o que pode parecer estranho.
Por exemplo, as seguintes expressões regulares são equivalentes:
re.regex($e.network.email.from, `.*altostrat\.com`)
re.regex($e.network.email.from, ".*altostrat\\.com")
$e.network.email.from = /.*altostrat\.com/
O Google recomenda usar caracteres de aspas para strings em expressões regulares para facilitar a leitura.
Operadores
Você pode usar os seguintes operadores em YARA-L:
Operador | Descrição |
= | igual/declaração |
!= | diferente |
< | menor que |
<= | menor ou igual a |
> | maior que |
>= | maior ou igual a |
Variáveis
Na YARA-L 2.0, todas as variáveis são representadas como $<variable name>
.
Você pode definir os seguintes tipos de variáveis:
Variáveis de evento: representam grupos de eventos no formato normalizado (UDM, na sigla em inglês) ou eventos de entidade. Especifique as condições das variáveis de evento na seção
events
. Para identificar variáveis de evento, use os campos "Nome", "Origem do evento" e "Evento". As origens permitidas sãoudm
(para eventos normalizados) egraph
(para eventos da entidade). Se a origem for omitida,udm
será definido como a origem padrão. Os campos de evento são representados como uma cadeia de .<field name> (por exemplo, $e.field1.field2). As cadeias de campos de eventos sempre começam pela origem de nível superior (UDM ou Entidade).Variáveis de correspondência: declare na seção
match
. As variáveis de correspondência se tornam campos de agrupamento da consulta, já que uma linha é retornada para cada conjunto exclusivo de variáveis de correspondência (e para cada janela de tempo). Quando a regra encontra uma correspondência, os valores das variáveis de correspondência são retornados. Especifique o que cada variável de correspondência representa na seçãoevents
.Variáveis de marcador de posição: declare e defina na seção
events
. As variáveis de marcador de posição são semelhantes às variáveis de correspondência. No entanto, é possível usar variáveis de marcador de posição na seçãocondition
para especificar condições de correspondência.
Use variáveis de correspondência e de marcador para declarar relações entre campos de evento por meio de condições de mesclagem transitivas. Consulte Sintaxe da seção "Eventos" para mais detalhes.
Palavras-chave
As palavras-chave em YARA-L 2.0 não diferenciam maiúsculas de minúsculas. Por exemplo, and
ou AND
são
equivalentes. Os nomes das variáveis não podem entrar em conflito com as palavras-chave. Por exemplo,
$AND
ou $outcome
é inválido.
As seguintes palavras-chave são para as regras de detecção de mecanismo: rule
, meta
, match
, over
, events
, condition
, outcome
, options
, and
, or
, not
, nocase
, in
, regex
, cidr
, before
, after
, all
, any
, if
, max
, min
, sum
, array
, array_distinct
, count
, count_distinct
, is
, e null
.
Mapas
A YARA-L oferece suporte ao acesso a mapas para structs e rótulos.
Estruturas e rótulos
Alguns campos de UDM usam o tipo de dados Struct ou Label.
Para pesquisar um par de chave-valor específico em struct e em rótulo, use a sintaxe de mapa padrão:
// A Struct field.
$e.udm.additional.fields["pod_name"] = "kube-scheduler"
// A Label field.
$e.metadata.ingestion_labels["MetadataKeyDeletion"] = "startup-script"
O acesso ao mapa sempre retorna uma string.
Casos aceitos
Seção Eventos e resultados
// Using a Struct field in the events section
events:
$e.udm.additional.fields["pod_name"] = "kube-scheduler"
// Using a Label field in the outcome section
outcome:
$value = array_distinct($e.metadata.ingestion_labels["MetadataKeyDeletion"])
Atribuir um valor de mapa a um marcador de posição
$placeholder = $u1.metadata.ingestion_labels["MetadataKeyDeletion"]
Usar um campo de mapa em uma condição de mesclagem
// using a Struct field in a join condition between two udm events $u1 and $u2
$u1.metadata.event_type = $u2.udm.additional.fields["pod_name"]
Casos não aceitos
Os mapas não são aceitos nos casos a seguir.
Combinar any
ou all
palavras-chave com um mapa
Por exemplo, não há suporte para o seguinte:
all $e.udm.additional.fields["pod_name"] = "kube-scheduler"
Outros tipos de valores
A sintaxe do mapa só pode retornar um valor de string. No caso dos tipos de dados Struct, a sintaxe do mapa só pode acessar chaves com valores que sejam strings. Não é possível acessar chaves com valores que são outros tipos primitivos, como números inteiros.
Processamento de valores duplicados
Os acessos a mapas sempre retornam um único valor. No caso incomum em que o acesso ao mapa possa se referir a vários valores, ele retornará deterministamente o primeiro valor.
Isso pode acontecer em um dos seguintes casos:
Um rótulo tem uma chave duplicada.
A estrutura de rótulos representa um mapa, mas não impõe a exclusividade da chave. Por convenção, um mapa precisa ter chaves exclusivas. Portanto, as Operações de segurança do Google não recomendam preencher um rótulo com chaves duplicadas.
O texto da regra
$e.metadata.ingestion_labels["dupe-key"]
retornaria o primeiro valor possível,val1
, se executado no seguinte exemplo de dados:// Disrecommended usage of label with a duplicate key: event { metadata{ ingestion_labels{ key: "dupe-key" value: "val1" // This is the first possible value for "dupe-key" } ingestion_labels{ key: "dupe-key" value: "val2" } } }
Um rótulo tem um campo repetido de ancestral.
Um campo repetido pode conter um rótulo como um campo filho. Duas entradas diferentes no campo repetido de nível superior podem conter rótulos com a mesma chave. O texto da regra
$e.security_result.rule_labels["key"]
retornaria o primeiro valor possível,val3
, se executado no seguinte exemplo de dados:event { // security_result is a repeated field. security_result { threat_name: "threat1" rule_labels { key: "key" value: "val3" // This is the first possible value for "key" } } security_result { threat_name: "threat2" rule_labels { key: "key" value: "val4" } } }
Funções
Nesta seção, descrevemos as funções da YARA-L 2.0 que podem ser usadas nas regras do mecanismo de detecção e na pesquisa.
Essas funções podem ser usadas nas seguintes partes de uma regra YARA-L:
- Seção
events
BOOL_CLAUSE
de uma condicional na seção de resultados
arrays.length
arrays.length(repeatedField)
Descrição
Retorna o número de elementos de campo repetidos.
Tipos de dados de parâmetros
LIST
Tipo de retorno
NUMBER
Amostras de código
Exemplo 1
Retorna o número de elementos de campo repetidos.
arrays.length($e.principal.ip) = 2
Exemplo 2
Se houver vários campos repetidos ao longo do caminho, retorna o número total de elementos de campo repetidos.
arrays.length($e.intermediary.ip) = 3
Impressão digital
hash.fingerprint2011(byteOrString)
Descrição
Essa função calcula o hash fingerprint2011
de uma sequência ou string de bytes de entrada. Essa função retorna um valor INT
não assinado no intervalo [2, 0xFFFFFFFFFFFFFFFF]
.
Tipos de dados de parâmetros
BTYE
, STRING
Tipo de retorno
INT
Exemplo de código
id_fingerprint = hash.fingerprint2011("user123")
grupo
group(field1, field2, field3, ...)
Descrição
Agrupar campos de tipo semelhante em uma variável de marcador de posição.
Na pesquisa UDM, os campos agrupados são usados para pesquisar em vários campos de um tipo semelhante. A função de grupo é semelhante aos campos agrupados, mas permite selecionar quais campos você quer agrupar para acionar uma detecção. Você pode usar a função de grupo para coletar informações sobre uma entidade específica (por exemplo, um nome de host, endereço IP ou ID do usuário) em diferentes tipos de substantivo.
Amostras de código
Exemplo 1
Agrupe todos os endereços IP e forneça uma contagem decrescente dos endereços IP mais prevalentes no período verificado.
$ip = group(principal.ip, about.ip, target.ip)
$ip != ""
match:
$ip
outcome:
$count = count_distinct(metadata.id)
order:
$count desc
math.abs
math.abs(numericExpression)
Descrição
Retorna o valor absoluto de um número inteiro ou uma expressão flutuante.
Tipos de dados de parâmetros
NUMBER
Tipo de retorno
NUMBER
Amostras de código
Exemplo 1
Este exemplo retorna "True" se o evento estava mais de cinco minutos do horário especificado (em segundos a partir da época Unix), independentemente de o evento ter ocorrido antes ou depois do horário especificado. Uma chamada para math.abs
não pode depender de várias variáveis ou marcadores de posição. Por exemplo, não é possível substituir o
valor de tempo fixado no código de 1643687343 no exemplo a seguir por
$e2.metadata.event_timestamp.seconds
.
300 < math.abs($e1.metadata.event_timestamp.seconds - 1643687343)
math.log
math.log(numericExpression)
Descrição
Retorna o valor de registro natural de um número inteiro ou uma expressão flutuante.
Tipos de dados de parâmetros
NUMBER
Tipo de retorno
NUMBER
Amostras de código
Exemplo 1
math.log($e1.network.sent_bytes) > 20
math.round
math.round(numericExpression, decimalPlaces)
Descrição
Retorna um valor arredondado para o número inteiro mais próximo ou para o número especificado de casas decimais.
Tipos de dados de parâmetros
NUMBER
Tipo de retorno
NUMBER
Amostras de código
math.round(10.7) // returns 11
math.round(1.2567, 2) // returns 1.25
math.round(-10.7) // returns -11
math.round(-1.2) // returns -1
math.round(4) // returns 4, math.round(integer) returns the integer
metrics
As funções de métricas podem agregar grandes quantidades de dados históricos. Use
isso na sua regra com metrics.functionName()
na seção de
resultados.
Para mais informações, consulte Métricas de YARA-L.
net.ip_in_range_cidr
net.ip_in_range_cidr(ipAddress, subnetworkRange)
Descrição
Retorna true
quando o endereço IP fornecido está dentro da sub-rede especificada.
É possível usar a YARA-L para pesquisar eventos de UDM em todos os endereços IP
de uma sub-rede usando a instrução net.ip_in_range_cidr()
.
Há suporte para IPv4 e IPv6.
Para pesquisar em um intervalo de endereços IP, especifique um campo IP UDM e um intervalo CIDR. A YARA-L pode lidar com campos de endereços IP singulares e repetidos.
Para pesquisar em um intervalo de endereços IP, especifique um campo de UDM ip
e um intervalo de roteamento entre domínios sem classe (CIDR). A YARA-L pode lidar com campos de endereços IP singulares e repetidos.
Tipos de dados de parâmetros
STRING
, STRING
Tipo de retorno
BOOL
Amostras de código
Exemplo 1
Exemplo de IPv4:
net.ip_in_range_cidr($e.principal.ip, "192.0.2.0/24")
Exemplo 2
Exemplo de IPv6:
net.ip_in_range_cidr($e.network.dhcp.yiaddr, "2001:db8::/32")
Para conferir um exemplo de regra que usa a instrução net.ip_in_range_cidr()
, consulte a regra de exemplo em Evento único dentro do intervalo de endereços IP.
re.regex
Você pode definir a correspondência de expressões regulares na YARA-L 2.0 usando uma das seguintes sintaxes:
Como usar a sintaxe YARA-L — Relacionada a eventos. Esta é uma representação genérica dessa sintaxe:
$e.field = /regex/
Usando a sintaxe YARA-L — como uma função que aceita os seguintes parâmetros:
- Campo ao qual a expressão regular é aplicada.
- Expressão regular especificada como uma string.
Esta é uma representação genérica dessa sintaxe:
re.regex($e.field, `regex`)
Descrição
Essa função retornará true
se a string contiver uma substring que corresponda à expressão regular fornecida. Não é necessário adicionar .*
no início ou no fim da expressão regular.
Observações
- Para corresponder à string exata ou apenas um prefixo ou sufixo, inclua os caracteres âncora
^
(início) e$
(final) na expressão regular. Por exemplo,/^full$/
corresponde exatamente a"full"
, enquanto/full/
pode corresponder a"fullest"
,"lawfull"
e"joyfully"
. - Se o campo de UDM incluir caracteres de nova linha, o
regexp
corresponderá apenas à primeira linha do campo de UDM. Para aplicar a correspondência completa do campo do UDM, adicione um(?s)
à expressão regular. Por exemplo, substitua/.*allUDM.*/
por/(?s).*allUDM.*/
. - Você pode usar o modificador
nocase
após as strings para indicar que a pesquisa precisa ignorar letras maiúsculas.
Tipos de dados de parâmetros
STRING
, STRING
Tipos de expressão de parâmetro
ANY
, ANY
Tipo de retorno
BOOL
Amostras de código
Exemplo 1
// Equivalent to $e.principal.hostname = /google/
re.regex($e.principal.hostname, "google")
re.capture
re.capture(stringText, regex)
Descrição
Captura (extrai) dados de uma string usando o padrão de expressão regular fornecido no argumento.
Essa função usa dois argumentos:
stringText
: a string original a ser pesquisada.regex
: a expressão regular que indica o padrão a ser pesquisado.
A expressão regular pode conter 0 ou 1 grupo de captura entre parênteses. Se a expressão regular contiver 0 grupos de captura, a função retornará a primeira substring inteira correspondente. Se a expressão regular contiver um grupo de captura, ela retornará a primeira substring correspondente ao grupo. Definir dois ou mais grupos de captura retorna um erro do compilador.
Tipos de dados de parâmetros
STRING
, STRING
Tipo de retorno
STRING
Amostras de código
Exemplo 1
Neste exemplo, se $e.principal.hostname
contiver "aaa1bbaa2", o seguinte será verdadeiro, porque a função
retorna a primeira instância. Este exemplo não tem grupos de captura.
"aaa1" = re.capture($e.principal.hostname, "a+[1-9]")
Exemplo 2
Esse exemplo captura tudo que vem após o símbolo @ em um e-mail. Se o campo $e.network.email.from
for test@google.com
, o exemplo retornará google.com
. O exemplo a seguir contém um grupo de captura.
"google.com" = re.capture($e.network.email.from , "@(.*)")
Exemplo 3
Se a expressão regular não corresponder a nenhuma substring no texto, a função retornará uma string vazia. É possível omitir eventos em que nenhuma correspondência ocorre
excluindo a string vazia, o que é especialmente importante quando você está
usando re.capture()
com uma desigualdade:
// Exclude the empty string to omit events where no match occurs.
"" != re.capture($e.network.email.from , "@(.*)")
// Exclude a specific string with an inequality.
"google.com" != re.capture($e.network.email.from , "@(.*)")
re.replace
re.replace(stringText, replaceRegex, replacementText)
Descrição
Executa uma substituição de expressão regular.
Essa função usa três argumentos:
stringText
: a string original.replaceRegex
: a expressão regular que indica o padrão a ser pesquisado.replacementText
: o texto a ser inserido em cada correspondência.
Retorna uma nova string derivada do stringText
original, em que todas as
substrings que correspondem ao padrão em replaceRegex
são substituídas pelo valor em
replacementText
. É possível usar dígitos com escape de barra invertida (\1
a \9
) em
replacementText
para inserir texto correspondente ao grupo entre parênteses
no padrão replaceRegex
. Use \0
para se referir a todo o texto correspondente.
A função substitui as correspondências não sobrepostas e priorizará a substituição da primeira ocorrência encontrada. Por exemplo, re.replace("banana", "ana", "111")
retorna a string "b111na".
Tipos de dados de parâmetros
STRING
, STRING
e STRING
Tipo de retorno
STRING
Amostras de código
Exemplo 1
Este exemplo captura tudo após o símbolo @
em um e-mail, substitui com
por org
e retorna o resultado. Observe o uso de funções aninhadas.
"email@google.org" = re.replace($e.network.email.from, "com", "org")
Exemplo 2
Este exemplo usa dígitos de escape de barra invertida no argumento replacementText
para
fazer referência a correspondências ao padrão replaceRegex
.
"test1.com.google" = re.replace(
$e.principal.hostname, // holds "test1.test2.google.com"
"test2\.([a-z]*)\.([a-z]*)",
"\\2.\\1" // \\1 holds "google", \\2 holds "com"
)
Exemplo 3
Observe os seguintes casos ao lidar com strings vazias e re.replace()
:
Usando uma string vazia como replaceRegex
:
// In the function call below, if $e.principal.hostname contains "name",
// the result is: 1n1a1m1e1, because an empty string is found next to
// every character in `stringText`.
re.replace($e.principal.hostname, "", "1")
Para substituir uma string vazia, use "^$"
como replaceRegex
:
// In the function call below, if $e.principal.hostname contains the empty
// string, "", the result is: "none".
re.replace($e.principal.hostname, "^$", "none")
sample_rate
optimization.sample_rate(byteOrString, rateNumerator, rateDenominator)
Descrição
Essa função determina se um evento deve ser incluído com base em uma estratégia de amostragem determinística. Essa função retorna:
true
para uma fração de valores de entrada, equivalente a (rateNumerator
/rateDenominator
), indicando que o evento precisa ser incluído na amostra.false
: indica que o evento não deve ser incluído na amostra.
Essa função é útil em cenários de otimização em que você quer processar apenas um subconjunto de eventos. Equivalente a:
hash.fingerprint2011(byteOrString) % rateDenominator < rateNumerator
Tipos de dados de parâmetros
- byteOrString: expressão avaliada como
BYTE
ouSTRING
. - rateNumerator: 'INT'
- rateDenominator: 'INT'
Tipo de retorno
BOOL
Exemplo de código
events:
$e.metadata.event_type = "NETWORK_CONNECTION"
$asset_id = $e.principal.asset.asset_id
optimization.sample_rate($e.metadata.id, 1, 5) // Only 1 out of every 5 events
match:
$asset_id over 1h
outcome:
$event_count = count_distinct($e.metadata.id)
// estimate the usage by multiplying by the inverse of the sample rate
$usage_past_hour = sum(5.0 * $e.network.sent_bytes)
condition:
// Requiring a certain number of events after sampling avoids bias (e.g. a
// device with just 1 connection will still show up 20% of the time and
// if we multiply that traffic by 5, we'll get an incorrect estimate)
$e and ($usage_past_hour > 1000000000) and $event_count >= 100
strings.base64_decode
strings.base64_decode(encodedString)
Descrição
Retorna uma string que contém a versão decodificada em base64 da string codificada.
Essa função usa uma string codificada em base64 como argumento. Se encodedString
não for uma string codificada em base64 válida, a função retornará encodedString
inalterado.
Tipos de dados de parâmetros
STRING
Tipo de retorno
STRING
Amostras de código
Exemplo 1
"test" = strings.base64_decode($e.principal.domain.name)
strings.coalesce
strings.coalesce(a, b, c, ...)
Descrição
Essa função usa um número ilimitado de argumentos e retorna o valor da primeira expressão que não é avaliada como uma string vazia (por exemplo, "valor diferente de zero"). Se todos os argumentos forem avaliados como uma string vazia, a chamada da função retornará uma string vazia.
Os argumentos podem ser literais, campos de evento ou chamadas de função. Todos os argumentos precisam ser do tipo STRING
. Se algum argumento for de evento, os atributos precisarão ser do mesmo evento.
Tipos de dados de parâmetros
STRING
Tipo de retorno
STRING
Amostras de código
Exemplo 1
O exemplo a seguir inclui variáveis de string como argumentos. A condição é avaliada como verdadeira quando (1) $e.network.email.from
é suspicious@gmail.com
ou (2) $e.network.email.from
está vazio e $e.network.email.to
é suspicious@gmail.com
.
"suspicious@gmail.com" = strings.coalesce($e.network.email.from, $e.network.email.to)
Exemplo 2
O exemplo a seguir chama a função coalesce
com mais de dois
argumentos. Essa condição compara o primeiro endereço IP não nulo do evento $e
com valores na lista de referências ip_watchlist
. A ordem em que os argumentos são unidos nessa chamada é a mesma em que são enumerados na condição de regra:
$e.principal.ip
é avaliado primeiro.$e.src.ip
é avaliado em seguida.$e.target.ip
é avaliado em seguida.- Por fim, a string "Sem IP" vai ser retornada como um valor padrão se os campos
ip
anteriores não estiverem definidos.
strings.coalesce($e.principal.ip, $e.src.ip, $e.target.ip, "No IP") in %ip_watchlist
Exemplo 3
O exemplo a seguir tenta unir principal.hostname
dos eventos $e1
e $e2
. Ela retornará um erro do compilador porque os argumentos são variáveis de evento diferentes.
// returns a compiler error
"test" = strings.coalesce($e1.principal.hostname, $e2.principal.hostname)
strings.concat
strings.concat(a, b, c, ...)
Descrição
Retorna a concatenação de um número ilimitado de itens, sendo que cada um pode ser uma string, um número inteiro ou um valor flutuante.
Se algum argumento for de evento, os atributos precisarão ser do mesmo evento.
Tipos de dados de parâmetros
STRING
, FLOAT
, INT
Tipo de retorno
STRING
Amostras de código
Exemplo 1
O exemplo a seguir inclui uma variável de string e uma variável de número inteiro como
argumentos. Tanto principal.hostname
quanto principal.port
são do mesmo
evento, $e
, e são concatenados para retornar uma string.
"google:80" = strings.concat($e.principal.hostname, ":", $e.principal.port)
Exemplo 2
O exemplo a seguir inclui uma variável de string e um literal de string como argumentos.
"google-test" = strings.concat($e.principal.hostname, "-test") // Matches the event when $e.principal.hostname = "google"
Exemplo 3
O exemplo a seguir inclui uma variável de string e um literal flutuante como argumentos. Quando representados como strings, os pontos flutuantes que são números inteiros são formatados sem o ponto decimal.Por exemplo, 1,0 é representado como "1". Além disso, os pontos flutuantes que excedem a dezesseis dígitos decimais são truncados para a décima sexta casa decimal.
"google2.5" = strings.concat($e.principal.hostname, 2.5)
Exemplo 4
O exemplo a seguir inclui uma variável de string, um literal de string, uma variável de número inteiro e um literal flutuante como argumentos. Todas as variáveis são do mesmo evento, $e
, e são concatenadas com os literais para retornar uma string.
"google-test802.5" = strings.concat($e.principal.hostname, "-test", $e.principal.port, 2.5)
Example 5
O exemplo a seguir tenta concatenar principal.port do evento $e1
,
com principal.hostname
do evento $e2
. Ele retornará um erro do compilador porque os argumentos são variáveis de evento diferentes.
// Will not compile
"test" = strings.concat($e1.principal.port, $e2.principal.hostname)
strings.to_lower
strings.to_lower(stringText)
Descrição
Essa função usa uma string de entrada e retorna uma string depois de alterar todos os caracteres para minúsculas.
Tipos de dados de parâmetros
STRING
Tipo de retorno
STRING
Amostras de código
Exemplo 1
O exemplo a seguir retorna true
.
"test@google.com" = strings.to_lower($e.network.email.to)
strings.to_upper
strings.to_upper(stringText)
Descrição
Essa função usa uma string de entrada e retorna uma string depois de alterar todos os caracteres para letras maiúsculas
Tipos de dados de parâmetros
STRING
Tipo de retorno
STRING
Amostras de código
Exemplo 1
O exemplo a seguir retorna true
.
"TEST@GOOGLE.COM" = strings.to_upper($e.network.email.to)
timestamp.current_seconds
timestamp.current_seconds()
Descrição
Retorna um número inteiro que representa o horário atual em segundos do Unix. Esse valor é aproximadamente igual ao carimbo de data/hora de detecção e se baseia em quando a regra é executada.
Tipos de dados de parâmetros
NONE
Tipo de retorno
INT
Amostras de código
Exemplo 1
O exemplo a seguir retornará true
se o certificado tiver expirado há mais de 24 horas. Ela calcula a diferença de horário subtraindo os segundos atuais do Unix e, em seguida, comparando usando um operador maior que.
86400 < timestamp.current_seconds() - $e.network.tls.certificate.not_after
timestamp.get_date
timestamp.get_date(unix_seconds [, time_zone])
Descrição
Essa função retorna uma string no formato YYYY-MM-DD
, representando o dia em que o carimbo de data/hora está.
unix_seconds
é um número inteiro que representa o número de segundos após a época Unix, como$e.metadata.event_timestamp.seconds
, ou um marcador contendo esse valor.time_zone
é opcional e é uma string que representa um time_zone. Se omitido, o padrão será "GMT". Especifique fusos horários usando literais de string. As opções são:- O nome do banco de dados TZ, por exemplo, "America/Los_Angeles". Para mais informações, consulte a coluna"Nome do banco de dados TZ" nesta página.
- A diferença do fuso horário em relação ao UTC, no formato
(+|-)H[H][:M[M]]
, por exemplo: "-08:00".
Veja alguns exemplos de especificadores de time_zone válidos, que podem ser transmitidos como o segundo argumento para as funções de extração de tempo:
"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"
Tipos de dados de parâmetros
INT
, STRING
Tipo de retorno
STRING
Amostras de código
Exemplo 1
Neste exemplo, o argumento time_zone
é omitido, então o padrão é "GMT".
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_date($ts) = "2024-02-19"
Exemplo 2
Neste exemplo, usamos um literal de string para definir a time_zone
.
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_date($ts, "America/Los_Angeles") = "2024-02-20"
timestamp.get_minute
timestamp.get_minute(unix_seconds [, time_zone])
Descrição
Essa função retorna um número inteiro no intervalo [0, 59]
, que representa o minuto.
unix_seconds
é um número inteiro que representa o número de segundos após a época Unix, como$e.metadata.event_timestamp.seconds
, ou um marcador contendo esse valor.time_zone
é opcional e é uma string que representa um fuso horário. Se omitido, o padrão será "GMT". Especifique fusos horários usando literais de string. As opções são:- O nome do banco de dados TZ, por exemplo, "America/Los_Angeles". Para mais informações, consulte a coluna"Nome do banco de dados TZ" nesta página.
- A diferença do fuso horário em relação ao UTC, no formato
(+|-)H[H][:M[M]]
, por exemplo: "-08:00".
Confira alguns exemplos de especificadores time_zone
válidos, que podem ser transmitidos como o segundo argumento para as funções de extração de tempo:
"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"
Tipos de dados de parâmetros
INT
, STRING
Tipo de retorno
INT
Amostras de código
Exemplo 1
Neste exemplo, o argumento time_zone
é omitido, então o padrão é "GMT".
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_hour($ts) = 15
Exemplo 2
Neste exemplo, usamos um literal de string para definir a time_zone
.
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_hour($ts, "America/Los_Angeles") = 15
timestamp.get_hour
timestamp.get_hour(unix_seconds [, time_zone])
Descrição
Essa função retorna um número inteiro no intervalo [0, 23]
que representa a hora.
unix_seconds
é um número inteiro que representa o número de segundos após a época Unix, como$e.metadata.event_timestamp.seconds
, ou um marcador contendo esse valor.time_zone
é opcional e é uma string que representa um fuso horário. Se omitido, o padrão será "GMT". Especifique fusos horários usando literais de string. As opções são:- O nome do banco de dados TZ, por exemplo, "America/Los_Angeles". Para mais informações, consulte a coluna"Nome do banco de dados TZ" nesta página.
- A diferença do fuso horário em relação ao UTC, no formato
(+|-)H[H][:M[M]]
, por exemplo: "-08:00".
Confira alguns exemplos de especificadores time_zone
válidos, que podem ser transmitidos como o segundo argumento para as funções de extração de tempo:
"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"
Tipos de dados de parâmetros
INT
, STRING
Tipo de retorno
INT
Amostras de código
Exemplo 1
Neste exemplo, o argumento time_zone
é omitido, então o padrão é "GMT".
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_hour($ts) = 15
Exemplo 2
Neste exemplo, usamos um literal de string para definir a time_zone
.
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_hour($ts, "America/Los_Angeles") = 15
timestamp.get_day_of_week
timestamp.get_day_of_week(unix_seconds [, time_zone])
Descrição
Essa função retorna um número inteiro no intervalo [1, 7]
, que representa o dia da semana começando com domingo. Por exemplo, 1 = domingo e 2 = segunda-feira.
unix_seconds
é um número inteiro que representa o número de segundos após a época Unix, como$e.metadata.event_timestamp.seconds
, ou um marcador contendo esse valor.time_zone
é opcional e é uma string que representa um time_zone. Se omitido, o padrão será "GMT". Especifique fusos horários usando literais de string. As opções são:- O nome do banco de dados TZ, por exemplo, "America/Los_Angeles". Para mais informações, consulte a coluna"Nome do banco de dados TZ" nesta página.
- A diferença do fuso horário em relação ao UTC, no formato
(+|-)H[H][:M[M]]
, por exemplo: "-08:00".
Veja alguns exemplos de especificadores de time_zone válidos, que podem ser transmitidos como o segundo argumento para as funções de extração de tempo:
"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"
Tipos de dados de parâmetros
INT
, STRING
Tipo de retorno
INT
Amostras de código
Exemplo 1
Neste exemplo, o argumento time_zone
é omitido, então o padrão é "GMT".
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_day_of_week($ts) = 6
Exemplo 2
Neste exemplo, usamos um literal de string para definir a time_zone
.
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_day_of_week($ts, "America/Los_Angeles") = 6
timestamp.get_timestamp
timestamp.get_timestamp(unix_seconds, optional timestamp_format, optional timezone)
Descrição
Essa função retorna uma string no formato YYYY-MM-DD
, representando o dia em que o carimbo de data/hora está.
unix_seconds
é um número inteiro que representa o número de segundos após a época Unix, como$e.metadata.event_timestamp.seconds
, ou um marcador contendo esse valor.timestamp_format
é opcional e é uma string que representa o formato do carimbo de data/hora. Se omitido, o padrão é%F %T
. É possível especificar o formato usando literais de string. Veja as opções em Formatar elementos para partes de data e hora.time_zone
é opcional e é uma string que representa um fuso horário. Se omitido, o padrão éGMT
. Especifique fusos horários usando literais de string. As opções são as seguintes:- O nome do banco de dados da IANA, por exemplo,
America/Los_Angeles
. Para mais informações, consulte a lista de fusos horários do banco de dados tz na Wikipédia. - A diferença do fuso horário em relação ao UTC, no formato
(+|-)H[H][:M[M]]
, por exemplo: "-08:00".
- O nome do banco de dados da IANA, por exemplo,
Confira alguns exemplos de especificadores time_zone
válidos, que podem ser transmitidos como o segundo argumento para as funções de extração de tempo:
"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"
Tipos de dados de parâmetros
INT
, STRING
e STRING
Tipo de retorno
STRING
Amostras de código
Exemplo 1
Neste exemplo, o argumento time_zone
é omitido, então o padrão é GMT
.
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_timestamp($ts) = "2024-02-22 10:43:51"
Exemplo 2
Neste exemplo, usamos um literal de string para definir a time_zone
.
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_timestamp($ts, "%F %T", "America/Los_Angeles") = "2024-02-22 10:43:51"
Exemplo 3
Neste exemplo, usamos um literal de string para definir a timestamp_format
.
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_timestamp($ts, "%Y-%m", "GMT") = "2024-02"
timestamp.get_week
timestamp.get_week(unix_seconds [, time_zone])
Descrição
Essa função retorna um número inteiro no intervalo [0, 53]
, que representa a semana do ano. As semanas começam no domingo. As datas anteriores ao primeiro domingo do ano
estão na semana 0.
unix_seconds
é um número inteiro que representa o número de segundos após a época Unix, como$e.metadata.event_timestamp.seconds
, ou um marcador contendo esse valor.time_zone
é opcional e é uma string que representa um fuso horário. Se omitido, o padrão será "GMT". Especifique fusos horários usando literais de string. As opções são:- O nome do banco de dados TZ, por exemplo, "America/Los_Angeles". Para mais informações, consulte a coluna"Nome do banco de dados TZ" nesta página.
- A diferença do fuso horário em relação ao UTC, no formato
(+|-)H[H][:M[M]]
, por exemplo: "-08:00".
Confira alguns exemplos de especificadores time_zone
válidos, que podem ser transmitidos como o segundo argumento para as funções de extração de tempo:
"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"
Tipos de dados de parâmetros
INT
, STRING
Tipo de retorno
INT
Amostras de código
Exemplo 1
Neste exemplo, o argumento time_zone
é omitido, então o padrão é "GMT".
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_week($ts) = 0
Exemplo 2
Neste exemplo, usamos um literal de string para definir a time_zone
.
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_week($ts, "America/Los_Angeles") = 0
Função para atribuição do marcador de posição
Você pode atribuir o resultado de uma chamada de função a um marcador na seção events
. Exemplo:
$placeholder = strings.concat($e.principal.hostname, "my-string").
É possível usar as variáveis de marcador nas seções match
, condition
e outcome
.
No entanto, há duas limitações com relação à atribuição de funções para marcadores:
Cada marcador de posição na função à atribuição do marcador precisa ser atribuído a uma expressão que contenha um campo de evento. Por exemplo, os seguintes exemplos são válidos:
$ph1 = $e.principal.hostname $ph2 = $e.src.hostname // Both $ph1 and $ph2 have been assigned to an expression containing an event field. $ph1 = strings.concat($ph2, ".com")
$ph1 = $e.network.email.from $ph2 = strings.concat($e.principal.hostname, "@gmail.com") // Both $ph1 and $ph2 have been assigned to an expression containing an event field. $ph1 = strings.to_lower($ph2)
No entanto, o exemplo a seguir é inválido:
$ph1 = strings.concat($e.principal.hostname, "foo") $ph2 = strings.concat($ph1, "bar") // $ph2 has NOT been assigned to an expression containing an event field.
A chamada de função precisa depender de um e exatamente um evento. No entanto, mais de um campo do mesmo evento pode ser usado em argumentos de chamada de função. Por exemplo, o seguinte é válido:
$ph = strings.concat($event.principal.hostname, "string2")
$ph = strings.concat($event.principal.hostname, $event.src.hostname)
No entanto, o seguinte é inválido:
$ph = strings.concat("string1", "string2")
$ph = strings.concat($event.principal.hostname, $anotherEvent.src.hostname)
Sintaxe de listas de referência
Consulte nossa página sobre listas de referências para mais informações sobre o comportamento e a sintaxe da lista de referências.
Você pode usar listas de referência nas seções events
ou outcome
. Esta é a
sintaxe para usar vários tipos de listas de referência em uma regra:
// STRING reference list
$e.principal.hostname in %string_reference_list
// REGEX reference list
$e.principal.hostname in regex %regex_reference_list
// CIDR reference list
$e.principal.ip in cidr %cidr_reference_list
Também é possível usar os operadores not
e nocase
com listas de referência, conforme mostrado no exemplo a seguir:
// Exclude events whose hostnames match substrings in my_regex_list.
not $e.principal.hostname in regex %my_regex_list
// Event hostnames must match at least 1 string in my_string_list (case insensitive).
$e.principal.hostname in %my_string_list nocase
O operador nocase
é compatível com as listas STRING
e REGEX
.
Por motivos de desempenho, o mecanismo de detecção restringe o uso da lista de referências.
- Máximo de
in
instruções em uma regra, com ou sem operadores especiais: 7 - Máximo de instruções
in
com o operadorregex
: 4 - Máximo de instruções
in
com o operadorcidr
: 2
Verificação de tipo
As Operações de segurança do Google realizam a verificação de tipo em relação à sintaxe da YARA-L à medida que você cria regras na interface. Os erros de verificação de tipo exibidos ajudam você a revisar a regra para garantir que ela funcionará conforme o esperado.
Veja a seguir exemplos de predicados inválidos:
// $e.target.port is of type integer which cannot be compared to a string.
$e.target.port = "80"
// "LOGIN" is not a valid event_type enum value.
$e.metadata.event_type = "LOGIN"
Amostragem de eventos de detecção
As detecções de regras de vários eventos contêm amostras de eventos para fornecer contexto sobre os eventos que causaram a detecção. Há um limite de até 10 amostras de evento para cada variável de evento definida na regra. Por exemplo, se uma regra definir duas variáveis de evento, cada detecção poderá ter até 20 amostras de eventos. O limite é aplicado a cada variável de evento separadamente. Se uma variável de evento tiver dois eventos aplicáveis nessa detecção e a outra variável de evento tiver 15 eventos aplicáveis, a detecção resultante conterá 12 amostras de eventos (2 + 10).
Todas as amostras de eventos acima do limite são omitidas da detecção.
Se você quiser mais informações sobre os eventos que causaram a detecção, use as agregações na seção de resultados para gerar mais informações.
Se você estiver visualizando as detecções na UI, poderá fazer o download de todas as amostras de eventos para uma detecção. Para mais informações, consulte Fazer o download de eventos.