Desenvolver extensões de analisador

Compatível com:

Este documento explica como criar extensões de analisador para extrair campos de dados de registro brutos e mapeá-los para campos de destino do modelo de dados unificado (UDM, na sigla em inglês) na plataforma do Google Security Operations.

O documento descreve o processo de criação da extensão do analisador:

Criar extensões do analisador

As extensões de analisador oferecem uma maneira flexível de ampliar os recursos dos analisadores padrão (e personalizados) atuais. As extensões de analisador oferecem uma maneira flexível de ampliar os recursos dos analisadores padrão (ou personalizados) atuais sem substituí-los. As extensões permitem personalizar o pipeline do analisador adicionando uma nova lógica de análise, extraindo e transformando campos e atualizando ou removendo mapeamentos de campos do UDM.

Uma extensão de analisador não é o mesmo que um analisador personalizado. É possível criar um analisador personalizado para um tipo de registro que não tem um analisador padrão ou desativar as atualizações do analisador.

Processo de extração e normalização do analisador

O Google SecOps recebe dados de registro originais como registros brutos. Os analisadores padrão (e personalizados) extraem e normalizam os campos de registro principais em campos de UDM estruturados em registros de UDM. Isso representa apenas um subconjunto dos dados de registro brutos originais. É possível definir extensões de analisador para extrair valores de registro não processados por analisadores padrão. Depois de ativadas, as extensões de analisador se tornam parte do processo de extração e normalização de dados do Google SecOps.

Fluxo de trabalho de ingestão e normalização

Definir novas extensões do analisador

Os analisadores padrão contêm conjuntos predefinidos de instruções de mapeamento que especificam como extrair, transformar e normalizar os valores de segurança principais. É possível criar novas extensões de analisador definindo instruções de mapeamento usando a abordagem sem código (Mapear campos de dados) ou a abordagem de snippet de código:

  • Abordagem sem código

    A abordagem sem código é mais adequada para extrações simples de registros brutos no formato JSON, XML ou CSV nativo. Ele permite especificar campos de origem de registro brutos e mapear os campos de UDM de destino correspondentes.

    Por exemplo, para extrair dados de registro JSON com até 10 campos, usando comparações de igualdade simples.

  • Abordagem de snippet de código

    A abordagem de snippet de código permite definir instruções para extrair e transformar valores do registro bruto e atribuí-los a campos do UDM. Os snippets de código usam a mesma sintaxe do Logstash que o analisador padrão (ou personalizado).

    Essa abordagem é aplicável a todos os formatos de registro compatíveis. Ele é melhor para estes cenários:

    • Extrações de dados ou lógica complexas.
    • Dados não estruturados que exigem analisadores baseados em Grok.
    • Formatos não JSON, como CSV e XML.

    Os snippets de código usam funções para extrair dados específicos dos dados de registro brutos. Por exemplo, Grok, JSON, KV e XML.

    Na maioria dos casos, é melhor usar a abordagem de mapeamento de dados que foi usada no analisador padrão (ou personalizado).

Mesclar valores recém-extraídos em campos do UDM

Depois de ativadas, as extensões do analisador mesclam os valores recém-extraídos em campos designados da UDM no registro correspondente de acordo com princípios de mesclagem predefinidos. Exemplo:

  • Substituir valores atuais: os valores extraídos substituem os valores atuais nos campos de UDM de destino.

    A única exceção são os campos repetidos, em que é possível configurar a extensão do analisador para anexar novos valores ao gravar dados em um campo repetido no registro do UDM.

  • A extensão do analisador tem precedência: as instruções de mapeamento de dados em uma extensão do analisador têm precedência sobre as do analisador padrão (ou personalizado) para esse tipo de registro. Se houver um conflito nas instruções de mapeamento, a extensão do analisador vai substituir o valor definido pelo padrão.

    Por exemplo, se o analisador padrão mapear um campo de registro bruto para o campo UDM event.metadata.description e a extensão do analisador mapear um campo de registro bruto diferente para esse mesmo campo UDM, a extensão do analisador vai substituir o valor definido pelo analisador padrão.

Seletor de campos repetidos

Nas abordagens de mapeamento de campos de dados (sem código) e de gravação de snippet de código, é possível controlar como a extensão do analisador salva valores em campos repetidos (campos que aceitam uma matriz de valores, por exemplo, principal.ip). No painel Extensão (definição da extensão), use o campo Campos repetidos, que oferece as opções Adicionar valores ao final e Substituir valores.

Comportamento de anexar x substituir

Alguns campos do UDM armazenam uma matriz de valores, como o campo principal.ip. O seletor de Campos repetidos permite controlar como a extensão do analisador armazena dados recém-extraídos em um campo repetido:

  • Adicionar valores ao final:

    A extensão do analisador vai anexar o valor recém-extraído à matriz de valores atuais no campo do UDM.

  • Substituir valores:

    A extensão do analisador vai substituir a matriz de valores atuais no campo do UDM pelo valor recém-extraído.

Uma extensão de analisador pode mapear dados para um campo repetido somente quando o campo repetido está no nível mais baixo da hierarquia. Exemplo:

  • O mapeamento de valores para udm.principal.ip é compatível porque o campo ip repetido está no nível mais baixo da hierarquia, e principal não é um campo repetido.
  • Não é possível mapear valores para udm.intermediary.hostname porque intermediary é um campo repetido e não está no nível mais baixo da hierarquia.

A tabela a seguir mostra exemplos de como a configuração do seletor de campos repetidos afeta o registro de UDM gerado.

Seleção de campos repetidos Exemplo de registro Configuração da extensão do analisador Resultado gerado
Adicionar valores ao final {"protoPayload":{"@type":"type.AuditLog","authenticationInfo":{"principalEmail":""},"requestMetadata":{"callerIp":"1.1.1.1, 2.2.2.2"}}} Campo de condição prévia: protoPayload.requestMetadata.callerIp
Valor da condição prévia: " "
Operador de condição prévia: NOT_EQUALS
Campo de dados brutos: protoPayload.requestMetadata.callerIp
Campo de destino: event.idm.read_only_udm.principal.ip 		metadata:{event_timestamp:{}.....}principal:{Ip:"1.1.1.1, 2.2.2.2"} } }
Adicionar valores ao final {"protoPayload":{"@type":"type.AuditLog","authenticationInfo":{"principalEmail":""},"requestMetadata":{"callerIp":"2.2.2.2, 3.3.3.3", "name":"Akamai Ltd"}}} Condição prévia 1:
Campo da condição prévia:protoPayload.requestMetadata.callerIp
Valor da condição prévia: " "
Operador da condição prévia: NOT_EQUALS
Campo de dados brutos: protoPayload.requestMetadata.callerIp
Campo de destino: event.idm.read_only_udm.principal.ip

Condição prévia 2:
Campo de dados brutos: protoPayload.requestMetadata.name
Campo de destino: event.idm.read_only_udm.metadata.product_name

 Eventos gerados pelo analisador pré-criado antes de aplicar a extensão.
metadata:{event_timestamp:{} ... principal:{ip:"1.1.1.1"}}}

Saída após a aplicação da extensão.
timestamp:{} idm:{read_only_udm:{metadata:{event_timestamp:{} .... product_name: "Akamai Ltd"}principal:{ip:"1.1.1.1, 2.2.2.2, 3.3.3.3"}}}

Substituir valores {"protoPayload":{"@type":"type..AuditLog","authenticationInfo":{"principalEmail":""},"requestMetadata":{"callerIp":"2.2.2.2"}}} Campo de condição prévia: protoPayload.authenticationInfo.principalEmail
Valor da condição prévia: " "
Operador de condição prévia: NOT_EQUALS
Campo de dados brutos: protoPayload.authenticationInfo.principalEmail
Campo de destino: event.idm.read_only_udm.principal.ip 		Eventos de UDM gerados pelo analisador predefinido antes de aplicar a extensão.
timestamp:{} idm:{read_only_udm:{metadata:{event_timestamp:{} ... principal:{ip:"1.1.1.1"}}}

Saída do UDM após aplicar a extensão timestamp:{} idm:{read_only_udm:{metadata:{event_timestamp:{} ....} principal:{ip:"2.2.2.2"}}}

Limitações

  • Uma extensão de analisador por tipo de registro: só é possível criar uma extensão de analisador por tipo de registro.
  • Apenas uma abordagem de instrução de mapeamento de dados: é possível criar uma extensão de analisador usando a abordagem sem código ou de snippet de código, mas não as duas abordagens juntas.
  • Amostras de registro para validação: as amostras de registro dos últimos 30 dias são necessárias para validar uma extensão do analisador de UDM. Para mais detalhes, consulte Verificar se há um analisador ativo para o tipo de registro.
  • Erros do analisador de base: não é possível identificar ou corrigir erros do analisador de base nas extensões do analisador.
  • Processamento de campos repetidos: só é possível usar um único método (Anexar ou Substituir) em uma extensão específica. Tenha cuidado ao substituir objetos repetidos inteiros para evitar a perda não intencional de dados.
  • Additional.fields é interpretado como um conjunto de pares de chave-valor, não como um campo repetido: consequentemente, é possível combinar os mapeamentos de UDM do analisador e as saídas de UDM da extensão adicionando as respectivas chaves-valor ao conjunto.
  • Eventos sem ambiguidade: as extensões do analisador não podem processar registros com vários eventos exclusivos em um único registro, por exemplo, matriz do Google Drive.
  • XML e sem código: o modo sem código não é compatível com XML. Use o método de snippet de código.
  • Sintaxe do analisador versus regras de detecção do YARA-L: os analisadores de ingestão e as extensões de analisador usam o Logstash Grok e a sintaxe de configuração com filtros (por exemplo, grok, mutate, json, date e base64) no momento da ingestão para analisar registros brutos no modelo de dados unificado (UDM). Os analisadores não podem usar a sintaxe YARA-L, blocos de resultados ou funções geradoras (como yield). O YARA-L 2.0 é estritamente uma linguagem de consulta de mecanismo de detecção avaliada em downstream em eventos UDM normalizados para alertas de ameaças e não pode analisar registros brutos, alterar campos UDM ou descartar o tráfego de registros recebidos.
  • Aplicação somente para frente por padrão: por padrão, as extensões de analisador se aplicam a registros recém-ingeridos somente a partir do momento da ativação. Se houver uma necessidade comercial crítica de analisar novamente os registros históricos com mapeamentos atualizados, solicite uma tarefa de repetição de registro de back-end ao suporte do Google Cloud . Para mais informações, consulte Analisar novamente os dados históricos (reprodução de registros).
  • Rótulos de ingestão inacessíveis na lógica do analisador: as extensões do analisador não podem ler rótulos de ingestão (metadata.ingestion_labels) para mapear valores em campos do UDM porque os analisadores são executados em um ambiente de execução de sandbox com visibilidade apenas do corpo do registro bruto.
  • Palavras-chave reservadas com a abordagem sem código: se os registros contiverem alguma das palavras-chave reservadas a seguir, use a abordagem de snippet de código em vez da abordagem sem código:
    • collectionTimestamp
    • createTimestamp
    • enableCbnForLoop
    • event
    • filename
    • message
    • namespace
    • output
    • onErrorCount
    • timestamp
    • timezone
  • Remover mapeamentos: é possível remover mapeamentos de campo do UDM usando apenas a abordagem de snippet de código.
  • Não é possível remover o mapeamento de um campo UDM de nome do host usando uma extensão: não é possível remover o mapeamento de um campo UDM de nome do host (por exemplo, principal.hostname) usando uma extensão.

Conceitos do analisador

Os documentos a seguir explicam conceitos importantes do analisador:

Pré-requisitos

Pré-requisitos para criar extensões de analisador:

  • É necessário que haja um analisador padrão (ou personalizado) ativo para o tipo de registro.
  • O Google SecOps precisa ser capaz de ingerir e normalizar os registros brutos usando um analisador padrão (ou personalizado).
  • Verifique se o analisador padrão (ou personalizado) ativo para o tipo de registro de destino ingeriu dados de registro brutos nos últimos 30 dias. Esses dados precisam conter uma amostra dos campos que você pretende extrair ou usar para filtrar os registros. Ele será usado para validar as novas instruções de mapeamento de dados.

Primeiros passos

Antes de criar uma extensão de analisador, faça o seguinte:

  1. Verifique os pré-requisitos:

    Verifique se há um analisador ativo para o tipo de registro. Se ele ainda não tiver um analisador, crie um analisador personalizado.

  2. Identifique os campos a serem extraídos dos registros brutos:

    Identifique os campos que você quer extrair dos registros brutos.

  3. Selecione os campos de UDM apropriados:

    Selecione os campos do UDM correspondentes para mapear os campos de registro brutos extraídos.

  4. Escolha uma abordagem de definição de extensão do analisador:

    Escolha uma das duas abordagens de extensão (abordagens de mapeamento de dados) para criar a extensão do analisador.

Verificar os pré-requisitos

Verifique se há um analisador ativo para o tipo de registro que você quer estender, conforme descrito nas seções a seguir:

Verificar se há um analisador ativo para o tipo de registro

Verifique se há um analisador padrão (ou personalizado) ativo para o tipo de registro que você pretende estender.

Pesquise seu tipo de registro nestas listas:

Verificar se há um analisador personalizado para o tipo de registro

Para garantir que haja um analisador personalizado para um tipo de registro:

  1. Na barra de navegação, selecione Configurações do SIEM > Analisadores.

  2. Pesquise na tabela Analisadores o tipo de registro que você quer estender.

Verificar se o analisador está ativo para o tipo de registro

Para verificar se um analisador está ativo para um tipo de registro, siga estas etapas:

  1. Na barra de navegação, selecione Configurações do SIEM > Analisadores.

  2. Pesquise na tabela Analisadores o tipo de registro que você quer estender.

    Se o analisador do tipo de registro não estiver ativo, ative-o:

Identificar os campos que serão extraídos dos registros brutos

Analise o registro bruto de onde você quer extrair dados para identificar os campos não extraídos pelo analisador padrão (ou personalizado). Preste atenção em como o analisador padrão (ou personalizado) extrai campos de registro brutos e os mapeia para os campos de UDM correspondentes.

Para identificar os campos específicos que você quer extrair dos registros brutos, use as ferramentas de pesquisa para identificar os campos:

Para detalhes sobre como pesquisar nos registros brutos, consulte:

Selecione os campos de UDM apropriados

Agora que você identificou os campos de destino específicos a serem extraídos, é possível associá-los aos campos de UDM de destino correspondentes. Estabeleça um mapeamento claro entre os campos de origem do registro bruto e os campos de destino do UDM. É possível mapear dados para qualquer campo do UDM que seja compatível com os tipos de dados padrão ou campos repetidos.

Escolher o campo correto do UDM

Os recursos a seguir podem ajudar a simplificar o processo:

Conheça os principais conceitos do UDM

  • Objetos lógicos: evento e entidade

    O esquema do UDM descreve todos os atributos disponíveis que armazenam dados. Cada registro de UDM descreve um evento ou uma entidade. Os dados são armazenados em campos diferentes, dependendo se o registro descreve um evento ou uma entidade.

    • Um objeto de evento de UDM armazena dados sobre a ação que ocorreu no ambiente. O log de eventos original descreve a ação conforme ela foi registrada pelo dispositivo, como firewall ou proxy da Web.
    • Os repositórios de objetos de entidade do UDM armazenam dados sobre os participantes ou as entidades envolvidas no evento do UDM, como ativos, usuários ou recursos no seu ambiente.

  • Estrutura de um evento de UDM

  • Estrutura de uma entidade do UDM

  • Substantivos do UDM: um substantivo representa um participante ou uma entidade em um evento do UDM. Um substantivo pode ser, por exemplo, o dispositivo ou usuário que realiza a atividade descrita no evento. Um substantivo também pode ser o dispositivo ou usuário que é o alvo da atividade descrita no evento.

    Substantivo do UDM Descrição
    principal A entidade responsável por iniciar a ação descrita no evento.
    target A entidade que é o destinatário ou objeto da ação. Em uma conexão de firewall, a máquina que recebe a conexão é o destino.
    src Uma entidade de origem que sofreu uma ação do principal. Por exemplo, se um usuário copiar um arquivo de uma máquina para outra, o arquivo e a máquina de origem serão representados como src.
    intermediary Qualquer entidade que atue como intermediária no evento, como um servidor proxy. Eles podem influenciar a ação, como bloquear ou alterar uma solicitação.
    observer Uma entidade que monitora e relata o evento, mas não interage diretamente com o tráfego. Exemplos incluem sistemas de detecção de intrusões de rede ou sistemas de gerenciamento de eventos e informações de segurança.
    about Qualquer outra entidade envolvida no evento que não se encaixe nas categorias anteriores. Por exemplo, anexos de e-mail ou DLLs carregadas durante o início de um processo.

    Na prática, os objetos Noun principal e de destino são os mais usados. Também é importante observar que as descrições anteriores constituem o uso recomendado de substantivos. O uso real pode variar de acordo com a implementação de um analisador de base padrão ou personalizado.

Entender o mapeamento de dados usado pelo analisador atual

É recomendável entender o mapeamento de dados atual usado pelo analisador padrão (ou personalizado), entre os campos de origem do registro bruto e os campos de destino do UDM.

Para ver o mapeamento de dados entre os campos de origem do registro bruto e os campos de destino do UDM usados no analisador padrão (ou personalizado) atual:

  1. Na barra de navegação, selecione Configurações do SIEM > Analisadores.
  2. Pesquise na tabela Analisadores o tipo de registro que você quer estender.

  3. Navegue até essa linha e clique em Menu > Visualizar.

    Na guia Predefinido (ou Personalizado), a seção Código do analisador exibe o mapeamento de dados entre os campos de origem de registro brutos e os campos de UDM de destino usados no analisador padrão (ou personalizado) atual.

Usar a ferramenta de pesquisa do UDM

Use a ferramenta de pesquisa de UDM para identificar os campos de UDM que correspondem aos campos de origem do registro bruto.

O Google SecOps oferece a ferramenta de pesquisa de UDM para ajudar você a encontrar rapidamente os campos de UDM de destino. Para acessar a ferramenta de pesquisa de UDM, acesse Investigação > Pesquisa do SIEM.

Consulte estes tópicos para saber como usar a ferramenta de pesquisa de UDM:

Exemplo da ferramenta de pesquisa do UDM

Por exemplo, se você tiver um campo de origem no registro bruto chamado "packets", use a ferramenta de pesquisa de UDM para encontrar possíveis campos de UDM de destino com "packets" no nome:

  1. Acesse Investigação > Pesquisa do SIEM.

  2. Na página Pesquisa do SIEM, clique em Pesquisa de UDM.

    A caixa de diálogo Pesquisa de UDM é aberta. A ferramenta de pesquisa faz a correspondência dos campos do UDM por nome ou valor:

    • Pesquisa por nome do campo: faz a correspondência da string de texto inserida com os nomes de campo que contêm esse texto.
    • Pesquisa por valor do campo: corresponde o valor inserido aos campos que contêm esse valor nos dados de registro armazenados.

  3. Na caixa de diálogo Pesquisa de UDM, digite "pacotes" no campo Pesquisar campos/valores de UDM e selecione Campos de UDM.

    A função de pesquisa vai mostrar uma lista de possíveis campos de UDM que contêm o texto "packets" nos nomes dos campos de UDM.

  4. Clique em cada linha para ver a descrição de cada campo do UDM.

Considerações importantes sobre o UDM para evitar erros

  • Campos com aparência semelhante: a estrutura hierárquica do UDM pode levar a campos com nomes semelhantes. Consulte os analisadores padrão para receber orientações. Para mais detalhes, consulte Entender o mapeamento de dados usado pelo analisador atual.
  • Mapeamento de campo arbitrário: use o objeto additional para dados que não são mapeados diretamente para um campo de UDM. Para mais detalhes, consulte Mapeamento de campo arbitrário para UDM.
  • Campos repetidos: tenha cuidado ao trabalhar com campos repetidos em snippets de código. Substituir um objeto inteiro pode substituir os dados originais. A abordagem sem código oferece mais controle sobre os campos repetidos. Para mais detalhes, consulte Seletor de campos repetidos.
  • Campos de UDM obrigatórios para tipos de evento de UDM: ao atribuir um campo de UDM metadata.event_type a um registro de UDM, cada event_type exige que um conjunto diferente de campos relacionados esteja presente no registro de UDM. Para mais detalhes, consulte Mais informações sobre como atribuir campos UDM metadata.event_type.
  • Problemas com o analisador de base: as extensões do analisador não podem corrigir erros do analisador de base. O analisador de base é o analisador padrão (ou personalizado) que criou o registro UDM. Considere opções como melhorar a extensão do analisador, modificar o analisador de base ou pré-filtrar os registros.
Mapeamento de campos arbitrários no UDM

Quando não for possível encontrar um campo UDM padrão adequado para armazenar seus dados, use o objeto additional para armazenar os dados como um par de chave-valor personalizado. Isso permite armazenar informações valiosas no registro do UDM, mesmo que ele não tenha um campo correspondente.

Escolher uma abordagem de definição de extensão do analisador

Antes de escolher uma abordagem de definição de extensão do analisador, você precisa ter trabalhado nestas seções:

As próximas etapas são abrir a página Extensão do analisador e selecionar a abordagem de extensão a ser usada para definir a extensão do analisador:

Abra a página "Extensão do analisador"

A página Extensão do analisador permite definir a nova extensão do analisador.

É possível abrir a página Extensão do analisador das seguintes maneiras: no menu Configurações, em uma Pesquisa de registro bruto ou em uma Pesquisa de registro bruto legada:

Abrir no menu de configurações

Para abrir a página Extensão do analisador no menu Configurações:

  1. Na barra de navegação, selecione Configurações do SIEM > Analisadores.

    A tabela Analisadores mostra uma lista de analisadores padrão por tipo de registro.

  2. Encontre o tipo de registro que você quer estender, clique no Menu > Estender analisador > Criar extensão.

    A página Extensão do analisador é aberta.

Para abrir a página Extensão do analisador em uma Pesquisa de registro bruto:

  1. Acesse Investigação > Pesquisa do SIEM.
  2. No campo de pesquisa, adicione o prefixo raw = ao argumento de pesquisa e coloque o termo de pesquisa entre aspas. Por exemplo, raw = "example.com".
  3. Clique em Executar pesquisa. Os resultados são exibidos no painel Registros brutos.
  4. Clique em um registro (linha) no painel Registros brutos. O painel Visualizador de eventos é exibido.
  5. Clique na guia Registro bruto no painel Visualizador de eventos. O registro bruto é exibido.

  6. Clique em Gerenciar analisador > Estender analisador > Criar extensão (ou selecione Criar extensão > Próxima).

    A página Extensão do analisador é aberta.

Para abrir a página Extensão do analisador em uma Pesquisa de registro bruto legada:

  1. Use a Pesquisa de registros brutos legada para procurar registros semelhantes aos que serão analisados.
  2. Selecione um evento (ou clique no ícone de registro bruto) no painel Linha do tempo para abrir o registro bruto.

  3. Clique em Gerenciar analisador > Estender analisador > Criar extensão (ou selecione Criar extensão > Próxima).

    A página Extensão do analisador é aberta.

Página "Extensão do analisador"

A página mostra os painéis Registro bruto e Extensão (definição da extensão):

  • Painel Registro bruto:

    Isso mostra dados de amostra de registros brutos para o tipo de registro selecionado. Se você abriu a página na Pesquisa de registros brutos, os dados de amostra são o resultado da sua pesquisa. É possível formatar a amostra usando o menu Visualizar como (Bruto, JSON, CSV, XML ou Hex/ASCII) e a caixa de seleção Ajustar texto.

    1. Verifique se a amostra de dados de registro brutos exibida é representativa dos registros que a extensão do analisador vai processar.

    2. Clique em Visualizar saída do UDM (ou Mostrar saída do UDM) para conferir a saída do UDM para os dados de registro brutos de amostra.

  • Painel Extensão (definição da extensão):

    Isso permite definir uma extensão de analisador usando uma das duas abordagens de instrução de mapeamento: Mapear campos de dados (sem código) ou Escrever snippets de código (ou Escrever snippet de código). Não é possível usar as duas abordagens na mesma extensão de analisador.

    Dependendo da abordagem escolhida, é possível especificar os campos de dados de registro de origem a serem extraídos dos registros brutos recebidos e mapeá-los para os campos UDM correspondentes ou escrever um snippet de código para realizar essas tarefas e muito mais.

Selecionar a abordagem de extensão

Na página Extensão do analisador, no painel Extensão, no campo Método de extensão, selecione uma das seguintes abordagens para criar a extensão do analisador:

  • Mapear campos de dados (sem código):

    Essa abordagem permite especificar os campos no registro bruto e mapeá-los para os campos de destino do UDM.

    Essa abordagem funciona com os seguintes formatos de registro bruto:

    • JSON nativo, XML nativo ou CSV.
    • Cabeçalho do syslog mais JSON nativo, XML nativo ou CSV. É possível criar instruções de mapeamento de tipo de campo de dados para registros brutos nestes formatos: JSON, XML, CSV, SYSLOG + JSON, SYSLOG + XML e SYSLOG + CSV.

    Consulte as próximas etapas, Criar instruções sem código (mapear campos de dados).

  • Abordagem Escrever snippets de código (ou Escrever snippet de código):

    Essa abordagem permite usar uma sintaxe semelhante à do Logstash para especificar instruções para extrair e transformar valores do registro bruto e atribuí-los a campos de UDM no registro de UDM.

    • Os snippets de código usam a mesma sintaxe e as mesmas seções que os analisadores padrão (ou personalizados). Para mais informações, consulte Sintaxe do analisador.

    • Essa abordagem funciona com todos os formatos de dados compatíveis com esse tipo de registro.

    Consulte as próximas etapas, Criar instruções de snippet de código.

Criar instruções sem código (campos de dados do mapa)

A abordagem sem código (também chamada de método Mapear campos de dados) permite especificar os caminhos dos campos de registro brutos e mapeá-los para os campos de destino correspondentes do UDM.

Antes de criar uma extensão de analisador usando a abordagem sem código, você precisa ter trabalhado nestas seções:

As próximas etapas para definir a extensão do analisador são:

  1. Definir o seletor de campos repetidos
  2. Definir uma instrução de mapeamento de dados para cada campo
  3. Enviar e ativar a extensão do analisador

Definir uma instrução de mapeamento de dados para cada campo

Defina uma instrução de mapeamento de dados para cada campo que você quer extrair do registro bruto. A instrução precisa especificar o caminho do campo de origem no registro bruto e mapeá-lo para o campo UDM de destino.

  1. Se a amostra de registro bruto exibida no painel Registro bruto tiver um cabeçalho do Syslog, os campos Syslog e Destino serão exibidos. Alguns formatos de registro não contêm um cabeçalho Syslog, por exemplo, JSON nativo, XML nativo ou CSV.

    O Google SecOps vai precisar dos campos Syslog e Target para pré-processar o cabeçalho do Syslog e extrair a parte estruturada do registro.

    1. Defina estes campos:

      • Syslog: é um padrão definido pelo usuário que pré-processa e separa um cabeçalho Syslog da parte estruturada de um registro bruto.

        Especifique o padrão de extração, usando Grok e expressões regulares, que identifica o cabeçalho do Syslog e a mensagem de registro bruta. Para mais detalhes, consulte Definir os campos do extrator do Syslog.

      • Destino: nome da variável no campo do Syslog que armazena a parte estruturada do registro.

        Especifique o nome da variável no padrão de extração que armazena a parte estruturada do registro.

      Este é um exemplo de padrão de extração e nome de variável para os campos Syslog e Target, respectivamente.

      Campos do extrator do Syslog

    2. Depois de inserir valores nos campos Syslog e Destino, clique no botão Validar.

      O processo de validação verifica se há erros de sintaxe e de análise e, em seguida, retorna uma das seguintes opções:

      • Sucesso: os campos de mapeamento de dados aparecem. Defina o restante da extensão do analisador.
      • Falha: uma mensagem de erro é exibida. Corrija a condição de erro antes de continuar.

  2. Se quiser, defina uma instrução de condição prévia.

    Uma instrução de condição prévia identifica um subconjunto dos registros brutos que a extensão do analisador processa ao corresponder um valor estático a um campo no registro bruto. Se um registro bruto recebido atender aos critérios da condição prévia, a extensão do analisador aplicará a instrução de mapeamento. Se os valores não corresponderem, a extensão do analisador não aplicará a instrução de mapeamento.

    Preencha os seguintes campos:

    • Campo de condição prévia (ou Coluna de condição prévia para CSV): identificador de campo no registro bruto que contém o valor a ser comparado. Insira o caminho completo para o campo se o formato de dados de registro for JSON ou XML, ou a posição da coluna se o formato de dados for CSV.
    • Operador de condição prévia: selecione Igual a ou Diferente de.
    • Valor da condição prévia: o valor estático que será comparado com o Campo da condição prévia no registro bruto.

    Para outro exemplo de instrução de condição prévia, consulte Sem código: extrair campos com valor de condição prévia.

  3. Mapeie o campo de dados de registro bruto para o campo UDM de destino:

    • Campo de dados brutos (ou Coluna de dados brutos para CSV): insira o caminho completo para o campo se o formato de dados de registro for JSON (por exemplo: jsonPayload.connection.dest_ip) ou XML (por exemplo: /Event/Reason-Code) ou a posição da coluna se o formato de dados for CSV (observação: as posições do índice começam em 1).

    • Campo de destino: insira o nome do campo de UDM totalmente qualificado em que o valor será armazenado, por exemplo, udm.metadata.collected_timestamp.seconds.

  4. Para continuar adicionando mais campos, clique em Adicionar e insira todos os detalhes da instrução de mapeamento para o próximo campo.

Para ver outro exemplo de mapeamento dos campos, consulte Sem código: extrair campos.

Enviar e ativar a extensão do analisador

Depois de definir as instruções de mapeamento de dados para todos os campos que você pretende extrair do registro bruto, envie e ative a extensão do analisador.

Clique em Enviar para salvar e validar a instrução de mapeamento.

O Google SecOps valida as instruções de mapeamento:

  • Se o processo de validação for bem-sucedido, o estado vai mudar para Ativo, e as instruções de mapeamento vão começar a processar os dados de registro recebidos.

  • Se o processo de validação falhar, o estado vai mudar para Falha, e um erro vai aparecer no campo "Registro bruto".

    Este é um exemplo de erro de validação:

      ERROR: generic::unknown: pipeline.ParseLogEntry failed: LOG_PARSING_CBN_ERROR:
  "generic::invalid_argument: pipeline failed: filter mutate (7) failed: copy failure:
  copy source field \"jsonPayload.dest_instance.region\" must not be empty
  (try using replace to provide the value before calling copy)

  "LOG: {"insertId":"14suym9fw9f63r","jsonPayload":{"bytes_sent":"492",
  "connection":{"dest_ip":"10.12.12.33","dest_port":32768,"protocol":6,
  "src_ip":"10.142.0.238","src_port":22},"end_time":"2023-02-13T22:38:30.490546349Z",
  "packets_sent":"15","reporter":"SRC","src_instance":{"project_id":"example-labs",
  "region":"us-east1","vm_name":"example-us-east1","zone":"us-east1-b"},
  "src_vpc":{"project_id":"example-labs","subnetwork_name":"default",
  "vpc_name":"default"},"start_time":"2023-02-13T22:38:29.024032655Z"},
  "logName":"projects/example-labs/logs/compute.googleapis.com%2Fvpc_flows",
  "receiveTimestamp":"2023-02-13T22:38:37.443315735Z","resource":{"labels":
  {"location":"us-east1-b","project_id":"example-labs",
    "subnetwork_id":"00000000000000000000","subnetwork_name":"default"},
    "type":"gce_subnetwork"},"timestamp":"2023-02-13T22:38:37.443315735Z"}

    Estados do ciclo de vida de uma extensão do analisador

    As extensões de analisador têm os seguintes estados de ciclo de vida:

  • DRAFT: extensão de analisador recém-criada que ainda não foi enviada.

  • VALIDATING: o Google SecOps está validando as instruções de mapeamento em relação aos registros brutos atuais para garantir que os campos sejam analisados sem erros.

  • LIVE: a extensão do analisador foi validada e agora está em produção. Ele extrai e transforma dados de registros brutos recebidos em registros UDM.

  • FAILED: a validação da extensão do analisador falhou.

Mais sobre os campos do extrator do Syslog

Os campos do extrator do Syslog permitem separar o cabeçalho do Syslog de um registro estruturado definindo o Grok, a expressão regular e um token nomeado no padrão de expressão regular para armazenar a saída.

Definir os campos do extrator do Syslog

Os valores nos campos Syslog e Destino funcionam juntos para definir como a extensão do analisador separa o cabeçalho do Syslog da parte estruturada de um registro bruto. No campo Syslog, defina uma expressão usando uma combinação de Grok e sintaxe de expressão regular. A expressão inclui um nome de variável que identifica a parte estruturada do registro bruto. No campo Destino, especifique o nome da variável.

O exemplo a seguir ilustra como esses campos funcionam juntos.

Este é um exemplo de registro bruto:

<13>1 2022-09-14T15:03:04+00:00 fieldname fieldname - - - {"timestamp": "2021-03-14T14:54:40.842152+0000","flow_id": 1885148860701096, "src_ip": "10.11.22.1","src_port": 51972,"dest_ip": "1.2.3.4","dest_port": 55291,"proto": "TCP"}

O registro bruto contém as seguintes seções:

  • Cabeçalho do Syslog: <13> 2022-09-14T15:03:04+00:00 fieldname fieldname - - -

  • Evento formatado em JSON: {"timestamp": "2021-03-14T14:54:40.842152+0000","flow_id": 1885148860701096, "src_ip": "10.11.22.1","src_port": 51972,"dest_ip": "1.2.3.4","dest_port": 55291,"proto": "TCP"}

Para separar o cabeçalho do Syslog da parte JSON do registro bruto, use a seguinte expressão de exemplo no campo Syslog: %{TIMESTAMP_ISO8601} %{WORD} %{WORD} ([- ]+)?%{GREEDYDATA:msg}

  • Esta parte da expressão identifica o cabeçalho do Syslog: %{TIMESTAMP\_ISO8601} %{WORD} %{WORD} ([- ]+)?
  • Esta parte da expressão captura o segmento JSON do registro bruto: %{GREEDYDATA:msg}

Este exemplo inclui o nome da variável msg. Você escolhe o nome da variável. A extensão do analisador extrai o segmento JSON do registro bruto e o atribui à variável msg.

No campo Destino, insira o nome da variável msg. O valor armazenado na variável msg é inserido nas instruções de mapeamento de campo de dados que você cria na extensão do analisador.

Usando o registro bruto de exemplo, o segmento a seguir é inserido na instrução de mapeamento de dados:

{"timestamp": "2021-03-14T14:54:40.842152+0000","flow_id": 1885148860701096, "src_ip": "10.11.22.1","src_port": 51972,"dest_ip": "1.2.3.4","dest_port": 55291,"proto": "TCP"}

Veja a seguir os campos Syslog e Destino preenchidos:

Campos do extrator do Syslog

A tabela a seguir mostra mais exemplos com registros de amostra, o padrão de extração do Syslog, o nome da variável de destino e o resultado.

Exemplo de registro bruto Campo do Syslog Campo de destino Result
<13>1 2022-07-14T15:03:04+00:00 suricata suricata - - - {\"timestamp\": \"2021-03-14T14:54:40.842152+0000\",\"flow_id\": 1885148860701096,\"in_iface\": \"enp94s0\",\"event_type\": \"alert\",\"vlan\": 522,\"src_ip\": \"1.1.2.1\",\"src_port\": 51972,\"dest_ip\": \"1.2.3.4\",\"dest_port\": 55291,\"proto\": \"TCP\"}" %{TIMESTAMP_ISO8601} %{WORD} %{WORD} ([- ]+)?%{GREEDYDATA:msg} msg field_mappings { field: "msg" value: "{\"timestamp\": \"2021-03-14T14:54:40.842152+0000\",\"flow_id\": 1885148860701096,\"in_iface\": \"enp94s0\",\"event_type\": \"alert\",\"vlan\": 522,\"src_ip\": \"1.1.2.1\",\"src_port\": 51972,\"dest_ip\": \"1.2.3.4\",\"dest_port\": 55291,\"proto\": \"TCP\"}" }
<13>1 2022-07-14T15:03:04+00:00 suricata suricata - - - {\"timestamp\": \"2021-03-14T14:54:40.842152+0000\"} - - - {\"timestamp\": \"2021-03-14T14:54:40.842152+0000\",\"flow_id\": 1885148860701096,\"in_iface\": \"enp94s0\",\"event_type\": \"alert\",\"vlan\": 522,\"src_ip\": \"1.1.2.1\",\"src_port\": 51972,\"dest_ip\": \"1.2.3.4\",\"dest_port\": 55291,\"proto\": \"TCP\"} %{TIMESTAMP_ISO8601} %{WORD} %{WORD} ([- ]+)?%{GREEDYDATA:msg1} ([- ]+)?%{GREEDYDATA:msg2} msg2 field_mappings { field: "msg2" value: "{\"timestamp\": \"2021-03-14T14:54:40.842152+0000\",\"flow_id\": 1885148860701096,\"in_iface\": \"enp94s0\",\"event_type\": \"alert\",\"vlan\": 522,\"src_ip\": \"1.1.2.1\",\"src_port\": 51972,\"dest_ip\": \"1.2.3.4\",\"dest_port\": 55291,\"proto\": \"TCP\"}" }
"<13>1 2022-07-14T15:03:04+00:00 suricata suricata - - - {\"timestamp\": \"2021-03-14T14:54:40.842152+0000\"} - - - {\"timestamp\": \"2021-03-14T14:54:40.842152+0000\",\"flow_id\": 1885148860701096,\"in_iface\": \"enp94s0\",\"event_type\": \"alert\",\"vlan\": 522,\"src_ip\": \"1.1.2.1\",\"src_port\": 51972,\"dest_ip\": \"1.2.3.4\",\"dest_port\": 55291,\"proto\": \"TCP\"}" %{TIMESTAMP_ISO8601} %{WORD} %{WORD} ([- ]+)?%{GREEDYDATA:message} ([- ]+)?%{GREEDYDATA:msg2} msg2 Error - message already exists in state and not overwritable.

Mais informações sobre como atribuir campos metadata.event_type do UDM

Ao atribuir um campo metadata.event_type de UDM a um registro de UDM, ele é validado para garantir que os campos relacionados obrigatórios estejam presentes no registro de UDM. Cada metadata.event_type de UDM requer um conjunto diferente de campos relacionados. Por exemplo, um evento USER_LOGIN sem um user não é útil.

Se um campo relacionado obrigatório estiver ausente, a validação do UDM vai retornar um erro:

  "error": {
    "code": 400,
    "message": "Request contains an invalid argument.",
    "status": "INVALID_ARGUMENT"
  }

Um analisador grok retorna um erro mais detalhado:

  generic::unknown:
  invalid event 0: LOG_PARSING_GENERATED_INVALID_EVENT:
  "generic::invalid_argument: udm validation failed: target field is not set"

Para encontrar os campos obrigatórios de um event_type de UDM a ser atribuído, use os recursos a seguir, em que os guias de adoção complementam o Guia de Uso do UDM, fornecendo os campos obrigatórios mínimos do UDM necessários para preencher um determinado metadata.event_type de UDM.

Por exemplo, abra o documento e pesquise o tipo de evento GROUP_CREATION.

Você verá os seguintes campos mínimos de UDM, apresentados como um objeto UDM:

  {
      "metadata": {
          "event_timestamp": "2023-07-03T13:01:10.957803Z",
          "event_type": "GROUP_CREATION"
      },
      "principal": {
          "user": {
              "userid": "pinguino"
          }
      },
      "target": {
          "group": {
              "group_display_name": "foobar_users"
          }
      }
  }

Criar instruções de snippet de código

A abordagem de snippet de código permite usar uma sintaxe semelhante à do Logstash para definir como extrair e transformar valores do registro bruto e atribuí-los a campos do UDM no registro do UDM.

Antes de criar uma extensão de analisador usando a abordagem de snippet de código, você precisa ter trabalhado nestas seções:

As próximas etapas para definir a extensão do analisador são:

  1. Para dicas e práticas recomendadas, consulte Dicas e práticas recomendadas para escrever instruções de snippet de código.
  2. Criar uma instrução de snippet de código
  3. Enviar uma instrução de snippet de código

Dicas e práticas recomendadas para escrever instruções de snippet de código

As instruções de snippet de código podem falhar devido a problemas como padrões Grok incorretos, falha nas operações de renomeação ou substituição ou erros de sintaxe. Confira as dicas e práticas recomendadas a seguir:

Criar uma instrução de snippet de código

As instruções do snippet de código usam a mesma sintaxe e as mesmas seções do analisador padrão (ou personalizado):

  • Seção 1. Extraia dados do registro bruto.
  • Seção 2. Transformar os dados extraídos.
  • Seção 3. Atribua um ou mais valores a um campo do UDM.
  • Seção 4. Vincule os campos de evento do UDM à chave @output.

Para criar uma extensão de analisador usando a abordagem de snippet de código, faça o seguinte:

  1. Na página Extensão do analisador, no painel Snippet da CBN, insira um snippet de código para criar a extensão do analisador.
  2. Clique em Validar para validar as instruções de mapeamento.

Exemplos de instruções de snippet de código

O exemplo a seguir ilustra um snippet de código.

Este é um exemplo do registro bruto (com outros campos jsonPayload omitidos para fins de brevidade):

  {
      "insertId": "00000000",
      "jsonPayload": {
          "packets_sent": "4"
      },
      "timestamp": "2022-05-03T01:45:00.150614953Z"
  }

Este é um exemplo de snippet de código que mapeia o valor em jsonPayload.packets_sent para o campo UDM network.sent_bytes:

filter {
  mutate {
    replace => {
      "jsonPayload.packets_sent" => ""
    }
  }
  # Section 1. extract data from the raw JSON log
  json {
    source => "message"
    array_function => "split_columns"
    on_error => "_not_json"
  }
  if [_not_json] {
    drop {
      tag => "TAG_UNSUPPORTED"
    }
  } else {
    # Section 2. transform the extracted data
    if [jsonPayload][packets_sent] not in ["", 0] {
      mutate {
        convert => {
          "jsonPayload.packets_sent" => "uinteger"
        }
        on_error => "_exception1"
      }
      # Section 3. assign the value to a UDM field
      mutate {
        Replace => {
          "event.idm.read_only_udm.network.sent_bytes" => "jsonPayload.packets_sent"
        }
        on_error => "_exception2"
      }
      if ![_exception1] and![_exception2] {
        # Section 4. Bind the UDM fields to the @output key
        mutate {
          merge => {
            "@output" => "event"
          }
        }
      }
    }
  }
}

Enviar uma instrução de snippet de código

  1. Clique em Enviar para salvar as instruções de mapeamento.

  2. O Google SecOps valida as instruções de mapeamento.

    • Se o processo de validação for bem-sucedido, o estado vai mudar para Ativo, e as instruções de mapeamento vão começar a processar os dados de registro recebidos.
    • Se o processo de validação falhar, o estado vai mudar para Falha, e um erro vai aparecer no campo "Registro bruto".

Gerenciar extensões de analisador

É possível visualizar, editar, excluir e controlar o acesso às extensões de analisador atuais.

Ver uma extensão de analisador

  1. Na barra de navegação, selecione Configurações do SIEM > Analisadores.
  2. Na lista de analisadores, encontre o analisador (tipo de registro) que você quer visualizar. Os analisadores com uma extensão são indicados pelo texto EXTENSION (ou EXTN) ao lado do nome.

  3. Acesse essa linha e clique em Menu > Estender analisador > Ver extensão.

    A guia Visualizar analisador personalizado/pré-criado > Extensão (ou Extensões) aparece mostrando detalhes sobre a extensão do analisador. O painel de resumo mostra a extensão do analisador LIVE por padrão.

Editar uma extensão de analisador

  1. Abra a guia Ver analisador personalizado/pré-criado > Extensão (ou Extensões), conforme descrito em Ver uma extensão de analisador atual.

  2. Clique no botão Editar extensão (ou Editar).

    A página Extensão do analisador é exibida.

  3. Edite a extensão do analisador.

    • Para cancelar a edição e descartar as mudanças, clique em Descartar rascunho (ou Descartar extensão).

    • Para excluir a extensão do analisador a qualquer momento, clique em Excluir extensão com falha (ou Excluir extensão).

    • Quando terminar de editar a extensão do analisador, clique em Enviar.

      O processo de validação é executado para validar a nova configuração.

Excluir uma extensão do analisador

  1. Abra a guia Ver analisador personalizado/pré-criado > Extensão (ou Extensões), conforme descrito em Ver uma extensão de analisador atual.

  2. Clique no botão Excluir extensão.

Controlar o acesso às extensões do analisador

Por padrão, os usuários com a função de Administrador podem acessar as extensões do analisador. É possível controlar quem pode ver e gerenciar as extensões do analisador. Para mais informações sobre como gerenciar usuários e grupos ou atribuir papéis, consulte Controle de acesso baseado em papéis.

Os novos papéis no Google SecOps estão resumidos na tabela a seguir.

Recurso Ação Descrição
Analisador Excluir Excluir extensões do analisador.
Analisador Editar Criar e editar extensões de analisador.
Analisador Ver Ver extensões do analisador.

Remover mapeamentos de campos do UDM usando extensões do analisador sintático

É possível usar extensões de analisador para remover um mapeamento de campo do UDM.

  1. Clique em Configurações do SIEM > Analisadores.
  2. Use um dos seguintes métodos para acessar a página Extensão do analisador:
    • Para uma extensão atual, clique em Menu > Estender analisador > Ver extensão.
    • Para novas extensões de analisador, clique em Menu > Estender analisador > Criar extensão.

  3. Selecione Gravar snippets de código (ou Gravar snippet de código) como o método de extensão para adicionar um snippet de código personalizado que remove valores de campos específicos do UDM.

    Para uma extensão atual, na guia Extensão (ou Extensões), clique em Editar extensão (ou Editar) e adicione o snippet de código.

    Consulte Snippet de código: remover mapeamentos atuais para ver exemplos de snippets.

  4. Siga as etapas em Enviar uma instrução de snippet de código para enviar a extensão.

Processamento de fuso horário e formatação de carimbo de data/hora

O Google SecOps padroniza e serializa carimbos de data/hora no formato RFC 3339 UTC com precisão de microssegundos (YYYY-MM-DDTHH:MM:SS.ffffffZ). Se os registros de origem fornecerem apenas precisão de segundo nível, a plataforma preencherá automaticamente os dígitos fracionários ausentes com zeros à direita (.000000Z) para manter a uniformidade do esquema.

Se um carimbo de data/hora de evento aparecer antes do horário de ingestão (ingested_timestamp < event_timestamp), a discrepância geralmente ocorre quando uma origem emite carimbos de data/hora de relógio local sem deslocamentos de fuso horário ISO (que usam UTC como padrão) ou sofre desvio de relógio. É possível resolver discrepâncias de fuso horário usando um dos seguintes métodos:

  • Ajustar carimbos de data/hora em uma extensão de analisador: use o filtro date em uma extensão de analisador de snippet de código para especificar o fuso horário de origem:

    if [raw_log] =~ /EST/ {
  date {
    match => [ "timestamp_str", "MMM dd HH:mm:ss" ]
    timezone => "America/New_York"
    target => "event.metadata.event_timestamp"
  }
}

  • Configurar uma substituição de fuso horário do coletor do encaminhador: acesse Configurações do SIEM > Encaminhadores, edite o coletor de destino, ative Substituir fuso horário e selecione o fuso horário de origem da IANA no menu Fuso horário (por exemplo, Europe/Paris) para ajustar os carimbos de data/hora automaticamente durante a ingestão.

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