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 UDM (modelo de dados unificado) na plataforma Google Security Operations.

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

Criar extensões de analisador

As extensões de analisador oferecem uma maneira flexível de ampliar os recursos de analisadores padrão (e personalizados) existentes. Eles não substituem os analisadores padrão (e personalizados), mas permitem a personalização perfeita do pipeline do analisador, permitindo uma nova lógica de análise e a extração, manipulação e mapeamento de campos.

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

Extração do analisador e processo de normalização

O Google SecOps recebe dados de registro originais como registros brutos. Os analisadores padrão (e personalizados) extraem e normalizam campos de registro principais em campos estruturados do UDM em registros do UDM. Isso representa apenas um subconjunto dos dados brutos originais do registro. É 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 do analisador passam a fazer 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 de analisador

Os parsers 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 o snippet de código:

  • Abordagem sem código

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

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

  • 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 com suporte. Ela é melhor para estes cenários:

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

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

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

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

Depois de ativadas, as extensões de analisador mesclam os valores recém-extraídos em campos UDM designados no registro UDM correspondente de acordo com os 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 de analisador têm precedência sobre as instruções no 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 mapeia um campo de registro bruto para o campo UDM event.metadata.description e a extensão do analisador mapeia um campo de registro bruto diferente para o mesmo campo UDM, a extensão do analisador substitui o valor definido pelo analisador padrão.

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 juntas.
  • Exemplos de registro para validação: são necessários exemplos de registro dos últimos 30 dias para validar uma extensão do analisador de UDM. Para saber mais, consulte Conferir se há um parser ativo para o tipo de registro.
  • Erros de analisador básico: os erros de analisador básico não podem ser identificados ou corrigidos nas extensões do analisador.
  • Campos repetidos em snippets de código: tenha cuidado ao substituir objetos repetidos inteiros em snippets de código para evitar a perda acidental de dados. Para mais detalhes, consulte Mais informações sobre o seletor de campos repetidos.
  • Eventos sem ambiguidade: as extensões de analisador não podem processar registros com vários eventos únicos em um único registro, por exemplo, matriz do Google Drive.
  • XML e sem código: a abordagem sem código não é recomendada para XML devido a possíveis problemas de codificação. Use a abordagem de snippet de código para XML.
  • Nenhum dado retroativo: não é possível analisar dados de registro brutos de forma retroativa.

Conceitos do analisador

Os documentos a seguir explicam conceitos importantes do analisador:

Pré-requisitos

Pré-requisitos para a criação de uma extensão de analisador:

  • É necessário ter um analisador padrão (ou personalizado) ativo para o tipo de registro.
  • O Google SecOps precisa ser capaz de processar 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 brutos nos últimos 30 dias. Esses dados precisam conter uma amostra dos campos que você pretende extrair ou usar para filtrar os registros de log. Ele será usado para validar suas 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 parser, crie um 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 UDM adequados:

    Selecione os campos UDM correspondentes apropriados para mapear os campos de registro bruto 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ê pretende estender, conforme descrito nas seções a seguir:

Verifique 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ê quer estender.

Pesquise o tipo de registro nestas listas:

Verifique 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 > Parcializadores.

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

Verifique 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 > Parcializadores.

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

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

Identifique os campos a serem 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 correspondentes do UDM.

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

Para detalhes sobre como pesquisar nos registros brutos, consulte:

Selecionar os campos UDM adequados

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

Escolha o campo UDM correto

Os recursos a seguir podem ajudar a simplificar o processo:

Conheça os principais conceitos da UDM

Entender o mapeamento de dados usado pelo analisador

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

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

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

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

    A guia Código do analisador mostra o mapeamento de dados entre os campos de origem de registro bruto e os campos de UDM de destino usados no analisador padrão (ou personalizado) atual.

Usar a ferramenta de pesquisa de UDM

Use a ferramenta de pesquisa do UDM para identificar campos do UDM que correspondem aos campos de origem de 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 SIEM.

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

Exemplo de ferramenta de pesquisa do UDM

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

  1. Acesse Investigação > Pesquisa SIEM.

  2. Na página Pesquisa do SIEM, digite "pacotes" no campo Pesquisar campos do UDM por valor e clique em Lookup do UDM.

    A caixa de diálogo UDM Lookup é aberta. A ferramenta de pesquisa corresponde aos campos do UDM por nome de campo ou valor de campo:

    • Consulta por nome de campo: corresponde a string de texto inserida a nomes de campos que contêm esse texto.
    • Pesquisa por valor de campo: corresponde ao valor inserido em campos que contêm esse valor nos dados de registro armazenados.

  3. Na caixa de diálogo UDM Lookup, selecione UDM Fields.

    A função de pesquisa vai mostrar uma lista de campos UDM em potencial que contêm o texto "pacotes" nos nomes dos campos UDM.

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

Considerações importantes sobre a 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 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 do UDM. Para mais detalhes, consulte Mapeamento de campo arbitrário para UDM.
  • Campos repetidos: tenha cuidado ao trabalhar com campos repetidos em trechos de código. A substituição de um objeto inteiro pode substituir os dados originais. Usar a abordagem sem código oferece mais controle sobre os campos repetidos. Para mais detalhes, consulte Mais informações sobre o seletor de campos repetidos.
  • Campos obrigatórios do UDM para tipos de evento do UDM: ao atribuir um campo metadata.event_type do UDM a um registro do UDM, cada event_type exige que um conjunto diferente de campos relacionados esteja presente no registro do UDM. Para mais detalhes, consulte Mais informações sobre a atribuição de campos metadata.event_type do UDM.
  • Problemas do analisador básico: as extensões do analisador não podem corrigir erros do analisador básico. O analisador de base é o analisador padrão (ou personalizado) que criou o registro UDM. Considere opções como aprimorar a extensão do analisador, modificar o analisador de base ou pré-filtrar registros.
Mapeamento de campo arbitrário 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 que você armazene informações valiosas no registro do UDM, mesmo que ele não tenha um campo UDM 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 com estas seções:

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

Abrir a página "Extensões do analisador"

Na página Extensões do analisador, você pode definir a nova extensão do analisador.

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

Abrir no menu "Configurações"

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

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

    A tabela Parsers mostra uma lista de parsers padrão por tipo de registro.

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

    A página Extensões do analisador é aberta.

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

  1. Acesse Investigação > Pesquisa SIEM.
  2. No campo de pesquisa, adicione o prefixo raw = ao argumento de pesquisa e inclua 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 Visualização de eventos é mostrado.
  5. Clique na guia Log bruto no painel Visualização de eventos. O registro bruto é exibido.

  6. Clique em Gerenciar analisador > Criar extensão > Próxima.

    A página Extensões do analisador é aberta.

Para abrir a página Extensões do analisador em uma herança Pesquisa de registro bruto:

  1. Use a Pesquisa de registros brutos legada para procurar registros semelhantes aos que serão analisados.
  2. Selecione um evento no painel Eventos > Cronograma.
  3. Abra o painel Dados do evento.

  4. Clique em Gerenciar analisador > Criar extensão > Próxima.

    A página Extensões do analisador é aberta.

Página de extensões do analisador

A página mostra os painéis Registro bruto e Definição da extensão:

  • Painel Registro bruto:

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

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

    2. Clique em Visualizar saída do UDM para conferir a saída do UDM para os dados de registro brutos de exemplo.

  • Painel 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 snippet de código. Não é possível usar as duas abordagens na mesma extensão do analisador.

    Dependendo da abordagem escolhida, você pode especificar os campos de dados de registro de origem para extrair 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ões do analisador, painel "Definição da extensão", no campo Método da extensão, selecione uma das seguintes abordagens para criar a extensão do analisador:

  • Abordagem 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 e JSON, XML ou CSV nativo. É 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.

    Confira as próximas etapas, Instruções para criar campos de dados de mapa sem código.

  • Abordagem Escrever snippet de código:

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

    • Os trechos de código usam a mesma sintaxe e 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 com suporte para esse tipo de registro.

    Confira as próximas etapas, Instruções para criar um 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 Map data fields) permite especificar os caminhos dos campos de registro bruto e mapeá-los para os campos de destino UDM correspondentes.

Antes de criar uma extensão de analisador usando a abordagem sem código, você precisa ter trabalhado com estas 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 o seletor de campos repetidos

No painel Definição da extensão, no campo Campos repetidos, defina como a extensão do analisador precisa salvar um valor em campos repetidos (campos que aceitam uma matriz de valores, por exemplo, principal.ip):

  • Anexar valores: o valor recém-extraído é anexado ao conjunto de valores armazenados no campo de matriz do UDM.
  • Substituir valores: o valor extraído recentemente substitui o conjunto de valores existente no campo de matriz do UDM, armazenado anteriormente pelo analisador padrão.

As configurações no seletor Campos repetidos não afetam os campos não repetidos.

Para mais detalhes, consulte Mais informações sobre o seletor de campos repetidos.

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 de UDM de destino.

  1. Se a amostra de registro bruto exibida no painel Registro bruto contiver um cabeçalho Syslog, os campos Syslog e Destino serão mostrados. 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 identificam o cabeçalho do Syslog e a mensagem de log bruta. Para mais detalhes, consulte Definir os campos do extrator do Syslog.

      • Destino: nome da variável no campo 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 um nome de variável para os campos Syslog e Target, respectivamente.

      Campos do extrator de Syslog

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

      O processo de validação verifica 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 aparece. Corrija a condição de erro antes de continuar.

  2. Opcionalmente, defina uma instrução de pré-condição.

    Uma instrução de pré-condição 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 de entrada atender aos critérios de pré-condição, a extensão do analisador vai aplicar a instrução de mapeamento. Se os valores não corresponderem, a extensão do analisador não vai aplicar a instrução de mapeamento.

    Preencha os seguintes campos:

    • Campo de pré-condição: 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 do registro for JSON ou XML ou a posição da coluna se o formato de dados for CSV.
    • Operador de pré-condição: selecione EQUALS ou NOT EQUALS.
    • Valor da condição prévia: o valor estático que será comparado com o campo de condição prévia no registro bruto.

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

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

    • Campo de dados brutos: insira o caminho completo para o campo se o formato de dados do 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 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 conferir 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 será mostrado 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 de analisador

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

  • DRAFT: extensão do 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 existentes para garantir que os campos sejam analisados sem erros.

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

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

Mais informações sobre o seletor de campos repetidos

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 vai armazenar os dados recém-extraídos em um campo repetido:

  • Anexar valores:

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

  • Substituir valores:

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

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

  • O mapeamento de valores para udm.principal.ip é aceito 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 Campos repetidos afeta o registro gerado da UDM.

Seleção de Campos repetidos Exemplo de registro Configuração da extensão do analisador Resultado gerado
Acrescentar valores {"protoPayload":{"@type":"type.AuditLog","authenticationInfo":{"principalEmail":"admin@cmmar.co"},"requestMetadata":{"callerIp":"1.1.1.1, 2.2.2.2"}}} Campo de pré-condição: protoPayload.requestMetadata.callerIp
Valor da pré-condição: " "
Operador de pré-condição: 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"} } }
Acrescentar valores {"protoPayload":{"@type":"type.AuditLog","authenticationInfo":{"principalEmail":"admin@cmmar.co"},"requestMetadata":{"callerIp":"2.2.2.2, 3.3.3.3", "name":"Akamai Ltd"}}} Pré-condição 1:
Campo de pré-condição:protoPayload.requestMetadata.callerIp
Valor de pré-condição: " "
Operador de pré-condição: NOT_EQUALS
Campo de dados brutos: protoPayload.requestMetadata.callerIp
Campo de destino: event.idm.read_only_udm.principal.ip

Pré-condição 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 da aplicação da 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":"admin@cmmar.co"},"requestMetadata":{"callerIp":"2.2.2.2"}}} Campo de pré-condição: protoPayload.authenticationInfo.principalEmail
Valor da pré-condição: " "
Operador de pré-condição: NOT_EQUALS
Campo de dados brutos: protoPayload.authenticationInfo.principalEmail
Campo de destino: event.idm.read_only_udm.principal.ip 		Eventos do UDM gerados pelo analisador pré-criado antes da aplicação da extensão.
timestamp:{} idm:{read_only_udm:{metadata:{event_timestamp:{} ... principal:{ip:"1.1.1.1"}}}

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

Mais informações sobre os campos do extrator de Syslog

Os campos do extrator de 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 de Syslog

Os valores nos campos Syslog e Target trabalham juntos para definir como a extensão do analisador separa o cabeçalho Syslog da parte estruturada de um registro bruto. No campo Syslog, você define uma expressão usando uma combinação de sintaxe de expressão regular e Grok. A expressão inclui um nome de variável que identifica a parte estruturada do registro bruto. No campo Target, 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 o seguinte exemplo de expressão no campo Syslog: %{TIMESTAMP_ISO8601} %{WORD} %{WORD} ([- ]+)?%{GREEDYDATA:msg}

  • Esta parte da expressão identifica o cabeçalho 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 Meta, digite o nome da variável msg. O valor armazenado na variável msg é inserido nas instruções de mapeamento de campo de dados criadas na extensão do analisador.

Usando o exemplo de registro bruto, o seguinte segmento é 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"}

A seguir, são mostrados os campos Syslog e Target preenchidos:

Campos do extrator de 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 Target e o resultado.

Exemplo de registro bruto Campo 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 a atribuição de campos metadata.event_type do UDM

Ao atribuir um campo metadata.event_type do UDM a um registro do UDM, ele é validado para garantir que os campos relacionados necessários estejam presentes no registro do UDM. Cada metadata.event_type da UDM exige 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 uma event_type do UDM que você quer atribuir, use estes recursos:

  • Documentação do Google SecOps: Guia de uso do UDM: campos obrigatórios e opcionais do UDM para cada tipo de evento

  • Recursos não oficiais de terceiros: Validação de eventos do UDM

    Nos casos em que o guia de uso da UDM não tem detalhes, este documento complementa a documentação oficial fornecendo os campos mínimos obrigatórios da UDM necessários para preencher um determinado metadata.event_type da UDM.

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

    Os seguintes campos mínimos do UDM, apresentados como um objeto do UDM, vão aparecer:

    {
    "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 a sintaxe semelhante ao 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 ao 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 ao escrever instruções de snippet de código

As instruções do snippet de código podem falhar devido a problemas como padrões incorretos do Grok, operações de renomeação ou substituição com falha 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 seções que o analisador padrão (ou personalizado):

  • Seção 1. Extrair dados do registro bruto.
  • Seção 2. Transforme 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 da UDM à chave @output.

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

  1. Na página Extensões do analisador, no painel Snippet 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:

  {
      "insertId": "00000000",
      "jsonPayload": {
          ...section omitted for brevity...
          "packets_sent": "4",
          ...section omitted for brevity...
      },
      "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:

mutate {
 replace => {
    "jsonPayload.packets_sent" => ""
 }
}
filter {
    # 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"
                }
            }
            # Section 3. assign the value to a UDM field
            mutate {
                copy => {
                    "udm.network.sent_bytes" => "jsonPayload.packets_sent"
                }
                on_error => "_exception"
            }
            if ![_exception] {
                # 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 será mostrado no campo "Registro bruto".

Gerenciar extensões de analisador

Você pode conferir, editar, excluir e controlar o acesso a extensões de analisador.

Conferir uma extensão de analisador

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

  3. Acesse essa linha e clique no Menu > Mostrar extensão.

    A guia View Custom/Prebuilt Parser > Extension 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 View Custom/Prebuilt Parser > Extension, conforme descrito em Visualizar uma extensão de analisador existente.

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

    A página Extensões do analisador é exibida.

  3. Edite a extensão do analisador.

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

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

    • 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 View Custom/Prebuilt Parser > Extension, conforme descrito em Visualizar uma extensão de analisador existente.

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

Controlar o acesso a extensões do analisador

Por padrão, os usuários com a função de Administrador podem acessar extensões do analisador. Você pode controlar quem pode acessar e gerenciar 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.

As novas funções do Google SecOps estão resumidas na tabela a seguir.

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

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