Funções de métricas para regras de análise de risco

Este documento descreve os principais elementos dos novos recursos de sintaxe do YARA-L para a análise de risco. Para mais informações sobre a YARA-L, consulte Sintaxe da linguagem YARA-L 2.0.

Funções de métrica da YARA-L

O Google Security Operations é compatível com várias funções de métricas, que podem agregar grandes quantidades de dados históricos.

A função de métrica só pode ser usada na seção de resultado. Todas as chamadas de função de exemplo pressupõem o uso em uma regra de vários eventos.

Todas as regras que usam a função de métrica são categorizadas automaticamente como regras de vários eventos, mesmo que não tenham uma seção de correspondência e usem apenas uma variável de evento. Isso significa que eles serão contabilizados na cota de regras de vários eventos.

Parâmetros de função de métrica

As funções de métrica podem ser usadas para regras que realizam análises comportamentais de entidades.

Por exemplo, a regra a seguir informa o número máximo de bytes diários que um endereço IP específico enviou no mês passado. O endereço IP específico é representado por uma variável de marcador de posição, $ip neste exemplo. Para mais informações sobre variáveis de marcador de posição, consulte Declarações de variáveis.

$max_bytes_per_day = max(metrics.network_bytes_outbound(
    period:1d, window:30d,
    metric:value_sum,
    agg:max,
    principal.asset.ip:$ip
))

Devido ao grande número de argumentos usados nessas funções, elas usam parâmetros nomeados, que podem ser especificados em qualquer ordem. Os parâmetros são os seguintes:

Período

O período durante o qual os eventos de registro individuais são combinados em uma única observação. Os únicos valores permitidos são 1h e 1d.

Janela

O período de tempo durante o qual as observações individuais são agregadas em um único valor, como a média e o máximo. Os valores permitidos para window são baseados no período da métrica. O mapeamento válido é o seguinte:

period:1h : window:today

period:1d : window:30d

Por exemplo, a regra a seguir informa o maior número de tentativas de autenticação falhas de um usuário específico (Alice) em um determinado dia, nos últimos 30 dias:

$user = "alice"
$max_fail = max(metrics.auth_attempts_fail(
    period:1d, window:30d,
        metric:event_count_sum,
        agg:max,
        target.user.userid:$user
))

Uma combinação de métricas horárias e diárias pode ser usada para tipos de detecção first-seen. Por exemplo, a regra a seguir informa se é a primeira vez que um usuário fez login no aplicativo:

events:
    $e.metadata.event_type = "USER_LOGIN"
    $e.security_result.action = "ALLOW"
    $userid = $e.target.user.userid
    $app = $e.target.application
match:
    // find events from now - 4h ago, which is the recommended look-back period
    $userid, $app over 4h
outcome:
    // check hourly analytics until daily analytics are available
    $first_seen_today = max(metrics.auth_attempts_success(
        period:1h, window:today, metric:first_seen, agg:max,
        target.user.userid:$userid, target.application:$app))
    $first_seen_monthly = max(metrics.auth_attempts_success(
        period:1d, window:30d, metric:first_seen, agg:max,
        target.user.userid:$userid, target.application:$app))
condition:
    $e and ($first_seen_today = 0) and ($first_seen_monthly = 0)

Métrica

Dentro de cada período, cada observação tem uma série de métricas associadas a ela. Uma delas precisa ser selecionada para agregação em toda a janela. Cinco tipos de metric são aceitos:

event_count_sum: número de eventos de registro exclusivos em cada período.

first_seen: carimbo de data/hora da primeira ocorrência de um evento de registro correspondente em cada período.

last_seen: carimbo de data/hora da última visualização de um evento de registro correspondente em cada período.

value_sum: representa a soma do número de bytes em todos os eventos de registro combinados no período. Só é possível usar esse valor para uma função de métrica com bytes no nome.

num_unique_filter_values: métrica que não é pré-calculada pelo Google SecOps, mas pode ser calculada durante a execução da regra. Consulte Contar métricas exclusivas para mais detalhes e requisitos.

Agg

Qual agregação é aplicada à métrica. As agregações são aplicadas em toda a janela (por exemplo, o maior valor diário nos últimos 30 dias). Os valores permitidos são:

avg: valor médio por período. Essa é uma média estatística que não inclui valores iguais a zero.

max: maior valor por período.

min: menor valor por período.

num_metric_periods: número de períodos na janela de tempo que tiveram um valor de métrica diferente de zero.

stddev: desvio padrão do valor por período. É um desvio padrão estatístico que não inclui valores zero.

sum: soma de cada valor por período em toda a janela.

Por exemplo, a regra a seguir informa o número médio de tentativas de autenticação falhas de um usuário específico (Alice) em qualquer dia nos últimos 30 dias:

$user = "alice"
$avg_fail = max(metrics.auth_attempts_fail(
        period:1d, window:30d,
        metric:event_count_sum,
        agg:avg,
        target.user.userid:$user
))

A regra a seguir informa quantas autenticações bem-sucedidas um usuário específico teve nos últimos 30 dias:

$total_success = max(metrics.auth_attempts_success(
        period:1d, window:30d,
        metric:event_count_sum,
        agg:sum,
        target.user.userid:$user
))

A regra a seguir informa se um usuário específico fez login pelo menos uma vez nos últimos 30 dias:

$days_success = max(metrics.auth_attempts_success(
        period:1d, window:30d,
        metric:event_count_sum,
        agg:num_metric_periods,
        target.user.userid:$user
))

A regra a seguir informa a primeira ou a última vez que um usuário específico fez login com sucesso:

$first_seen = max(metrics.auth_attempts_success(
        period:1d, window:30d,
        metric:first_seen,
        agg:min,
        target.user.userid:$user
))
$last_seen = max(metrics.auth_attempts_success(
        period:1d, window:30d,
        metric:last_seen,
        agg:max,
        target.user.userid:$user
))

A regra a seguir informa o número máximo de bytes enviados por um usuário em qualquer dia nos últimos 30 dias:

$max_daily_bytes = max(metrics.network_bytes_outbound(
        period:1d, window:30d,
        metric:value_sum,
        agg:max,
        target.user.userid:$user
))

Filtro

Os filtros permitem filtrar uma métrica antes da agregação usando um valor na métrica pré-calculada (consulte os valores em Métrica). Os filtros podem ser qualquer expressão de eventos válida (uma única linha na seção de eventos) que não contenha campos ou marcadores de posição de eventos. As únicas variáveis que podem ser incluídas nessa condição são tipos de métricas.

A regra a seguir inclui apenas métricas em que value_sum > 10 AND event_count_sum > 2:

$max_bytes_per_day = max(metrics.network_bytes_outbound(
    period:1d, window:30d,
    metric:value_sum,
    agg:max,
    principal.asset.ip:$ip
    filter:value_sum > 10 AND event_count_sum > 2
))

Exemplos válidos de filtros

filter:value_sum > 10 AND event_count_sum != 5
filter:event_count_sum = 100 OR event_count_sum > 1000
filter:timestamp.get_day_of_week(first_seen) = 3

Exemplos de filtros inválidos

// No placeholders in filter expressions.
filter:value_sum > $ph

// No event fields in filter expressions.
filter:event_count_sum + $e.field > 10

// No event fields in filter expressions.
filter:timestamp.subtract(first_seen, $e.metadata.timestamp)

Campos do UDM

Uma métrica é filtrada por 1, 2 ou 3 campos do UDM, dependendo da função. Para mais informações, consulte Funções.

Os seguintes tipos de campos do UDM são usados para funções de métrica:

• Dimensões: (obrigatório) diferentes combinações estão listadas nesta documentação. Não é possível fazer uma junção com uma métrica que tenha um valor padrão ("" para string e 0 para int).
• Namespaces (opcional): só é possível usar namespaces para entidades especificadas em dimensões. Por exemplo, se você usa principal.asset.hostname filter, também pode usar um principal.namespace filter. Se você não incluir um filtro de namespace, os dados de todos os namespaces serão agregados. É possível usar um valor padrão como filtro de namespace.

Cálculos de janela

O Google Security Operations calcula métricas usando uma janela de métricas diária ou por hora.

Janelas diárias

Todas as janelas diárias, como 30d, são determinadas da mesma forma. O Google Security Operations usa os dados de métricas mais recentes disponíveis que foram gerados e não se sobrepõem ao período da regra. O cálculo das métricas diárias pode levar até 6 horas para ser concluído e só começa no fim do dia em UTC. Os dados de métricas do dia anterior ficam disponíveis às 6h UTC ou antes todos os dias.

Por exemplo, para uma regra que está sendo executada em dados de eventos de 31/10/2023, 4h UTC a 31/10/2023, 7h UTC, as métricas diárias de 31/10/2023 provavelmente já foram geradas. Portanto, o cálculo da métrica usará os dados de 01/10/2023 a 30/10/2023 (inclusive). Já para uma regra que é executada em dados de eventos de 31/10/2023 1h UTC a 31/10/2023 3h UTC, as métricas diárias de 30/10/2023 provavelmente não foram geradas. Portanto, o cálculo da métrica usará os dados de 30/09/2023 a 29/10/2023 (inclusive).

Intervalo de today horas

A janela de métricas por hora é calculada de maneira diferente da janela para métricas diárias. A janela de métricas por hora de today não tem um tamanho estático como a janela 30d para métricas diárias. A janela de métricas por hora today preenche o máximo de dados possível entre o fim da janela diária e o início da janela de tempo da regra.

Por exemplo, para uma regra que está sendo executada com dados de eventos de 31/10/2023 4:00:00 UTC a 31/10/2023 7:00:00 UTC, o cálculo da métrica diária usa os dados de 01/10/2023 a 30/10/2023 (inclusive), e a janela da métrica por hora usa os dados de 31/10/2023 00:00:00 UTC a 31/10/2023 4:00:00 UTC.

Contar métricas únicas

Há um tipo especial de métrica num_unique_filter_values que não é pré-calculada pelo Google SecOps, mas sim durante a execução de uma regra. Isso é feito agregando uma dimensão em uma métrica pré-calculada. Por exemplo, a métrica daily total count of distinct countries that a user attempted to authenticate pode ser derivada da métrica pré-calculada auth_attempts_total nas dimensões target.user.userid e principal.ip_geo_artifact.location.country_or_region ao realizar uma agregação de contagem exclusiva na última dimensão.

A regra de exemplo a seguir conta métricas exclusivas:

$outcome_variable = max(metrics.auth_attempts_total(
    period: 1d,
    window: 30d,
    // This metric type indicates any filter with a wildcard value should be
    // aggregated over each day to produce a new metric on-the-fly.
    metric: num_unique_filter_values,
    agg: max,
    target.user.userid: $userid,
    // Filter whose value should be counted over each day to produce the
    // num_unique_filter_values metric.
    principal.ip_geo_artifact.location.country_or_region: *
))

Este recurso tem a seguinte limitação:

• O cálculo da contagem de métricas exclusivas só pode ser agregado em uma dimensão de filtro. Para indicar isso, use o token curinga * como valor do filtro.

Funções

Esta seção inclui documentação sobre as funções de métricas específicas compatíveis com o Google Security Operations.

Eventos de alerta

O metrics.alert_event_name_count pré-calcula valores históricos para eventos da UDM que geraram alertas do Carbon Black, do CrowdStrike Falcon, da API Microsoft Graph Alerts ou do Microsoft Sentinel.

Tentativas de autenticação

metrics.auth_attempts_total pré-calcula valores históricos para eventos da UDM com um USER_LOGIN event type.

metrics.auth_attempts_success também exige que o evento tenha pelo menos um SecurityResult.Action de ALLOW.

Em vez disso, metrics.auth_attempts_fail exige que nenhum dos SecurityResult.Actions seja ALLOW.

Bytes de DNS de saída

metrics.dns_bytes_outbound pré-calcula valores históricos para eventos da UDM em que network.sent_bytes é maior que 0, e a porta de destino é 53/udp, 53/tcp ou 3000/tcp. network.sent_bytes está disponível como value_sum.

Consultas DNS

metrics.dns_queries_total pré-calcula valores históricos para eventos da UDM que têm um valor em network.dns.id.

metrics.dns_queries_success também exige que o network.dns.response_code era 0 (NoError).

metrics.dns_queries_fail considera apenas eventos com um network.dns.response_code maior que 0.

Execuções de arquivos

metrics.file_executions_total pré-calcula valores históricos para eventos da UDM com um PROCESS_LAUNCH event type.

Além disso, metrics.file_executions_success exige que o evento tenha pelo menos um SecurityResult.Action de ALLOW.

metrics.file_executions_fail exige que nenhum dos SecurityResult.Actions seja ALLOW.

Consultas HTTP

metrics.http_queries_total pré-calcula valores históricos para eventos da UDM que têm um valor em network.http.method.

metrics.http_queries_success também exige que network.http.response_code é menor que 400.

metrics.http_queries_fail considera apenas eventos com um network.http.response_code é maior ou igual a 400.

Bytes da rede

metrics.network_bytes_inbound pré-calcula valores históricos para eventos da UDM que têm um valor diferente de zero para network.received_bytes, e disponibiliza esse campo como value_sum.

metrics.network_bytes_outbound exige um valor diferente de zero para network.sent_bytes e disponibiliza esse campo como value_sum.

metrics.network_bytes_total considera eventos que têm um valor diferente de zero para network.received_bytes ou network.sent_bytes (ou ambos) e disponibiliza a soma desses dois campos como value_sum.

Criação de recursos

metrics.resource_creation_total pré-calcula valores históricos para eventos da UDM com um RESOURCE_CREATION event type ou um USER_RESOURCE_CREATION event type.

Para conferir uma lista de tipos de eventos equivalentes, consulte Tipos de eventos de metadados.

Além disso, metrics.resource_creation_success exige que o evento tenha pelo menos um SecurityResult.Action de ALLOW.

Exclusão de recursos

metrics.resource_deletion_success pré-calcula valores históricos para eventos da UDM com um RESOURCE_DELETION event type e exige que o evento tenha pelo menos um SecurityResult.Actions de ALLOW.

Leitura de recursos

metrics.resource_read_success pré-calcula valores históricos para eventos da UDM com um RESOURCE_READ event type e exige que o evento tenha pelo menos um SecurityResult.Action de ALLOW.

metrics.resource_read_fail exige que nenhum dos SecurityResult.Actions seja ALLOW.

Limitações

Ao criar regras de YARA-L com métricas, esteja ciente das seguintes limitações:

• Não é possível fazer uma junção com uma métrica que tenha um valor padrão ("" para string e 0 para int).
• Valores padrão:
  • Se não houver dados de métricas correspondentes a um evento, o valor retornado da função de métricas será 0.
  • Se houver um evento na detecção sem dados de métrica, usar min para agregar a função poderá retornar 0.
  • Para verificar se há dados de um evento, use a agregação de métricas num_metric_periods no mesmo evento com os mesmos filtros.
• As funções de métrica só podem ser usadas na seção de resultado.
• Como as funções de métrica são usadas apenas na seção de resultado, elas precisam ser agregadas como qualquer outro valor em regras com uma seção de correspondência.

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