Extensões de analisadores

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 do Google Security Operations.

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

Criar extensões de analisador

As extensões de analisador oferecem uma maneira flexível de ampliar as funcionalidades 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) sem substituí-los. Com as extensões, é possível personalizar o pipeline do analisador adicionando uma nova lógica de análise, extraindo e transformando campos e atualizando ou removendo mapeamentos de campos da UDM.

Uma extensão de analisador não é o mesmo que um analisador personalizado. Você pode criar um analisador personalizado para um tipo de registro que não tenha 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 UDM estruturados nos registros do UDM. Isso representa apenas um subconjunto dos dados de registro brutos originais. É possível definir extensões de analisador para extrair valores de registros não processados por analisadores padrão. Depois de ativadas, as extensões de 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 do analisador

Os analisadores padrão contêm conjuntos predefinidos de instruções de mapeamento que especificam como extrair, transformar e normalizar 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 registros brutos e mapear os campos de destino correspondentes do UDM.

    Por exemplo, para extrair dados de registros 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 da UDM. Os snippets de código usam a mesma sintaxe semelhante ao Logstash do analisador padrão (ou personalizado).

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

    • Extrações de dados ou lógica complexas.
    • Dados não estruturados que exigem analisadores baseados no 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 usada no analisador padrão (ou personalizado).

Mesclar valores extraídos recentemente em campos da UDM

Depois de ativadas, as extensões do analisador mesclam os valores recém-extraídos em campos da UDM designados 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 destino do UDM.

    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 event.metadata.description do UDM e a extensão de analisador mapear um campo de registro bruto diferente para o mesmo campo do UDM, a extensão de analisador vai substituir o valor definido pelo analisador padrão.

Limitações

  • Uma extensão de analisador por tipo de registro: é possível criar apenas 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 registros para validação: são necessários exemplos de registros dos últimos 30 dias para validar uma extensão de analisador 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.
  • Campos repetidos em snippets de código: tenha cuidado ao substituir objetos repetidos inteiros em snippets de código para evitar a perda não intencional de dados. Para mais detalhes, consulte Mais sobre o seletor de campos repetidos.
  • Eventos desambiguados: as extensões do 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: o modo sem código não é compatível com XML. Em vez disso, use o método de snippet de código.

  • Sem dados retroativos: não é possível analisar dados de registros brutos de forma retroativa.

  • Palavras-chave reservadas com a abordagem sem código: se os registros contiverem alguma das palavras-chave reservadas a seguir, use o snippet de código em vez da abordagem sem código:

    • collectionTimestamp
    • createTimestamp
    • enableCbnForLoop
    • event
    • filename
    • message
    • namespace
    • output
    • onErrorCount
    • timestamp
    • timezone

  • Remover mapeamentos atuais: é possível remover mapeamentos de campos da UDM usando apenas a abordagem de snippet de código.

  • Remover mapeamentos para campos de IP repetidos: não é possível remover mapeamentos de campos da UDM para campos de IP repetidos.

Conceitos do analisador

Os documentos a seguir explicam conceitos importantes do analisador:

Pré-requisitos

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

  • É necessário ter um analisador padrão (ou personalizado) ativo para o tipo de registro.
  • O Google SecOps precisa ingerir e normalizar os registros brutos usando um analisador padrão (ou personalizado).
  • Verifique se o analisador ativo padrão (ou personalizado) 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 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 analisador, 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 de UDM adequados:

    Selecione os campos correspondentes do UDM 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:

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 seu 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 > Analizadores.

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

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 > Analizadores.

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

    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 que 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 de UDM adequados

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

Escolher o campo correto da UDM

Os recursos a seguir podem ajudar a simplificar o processo:

Conheça os principais conceitos da UDM

  • Objetos lógicos: evento e entidade

    O esquema da UDM descreve todos os atributos disponíveis que armazenam dados. Cada registro da 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 evento da UDM armazena dados sobre a ação que ocorreu no ambiente. O registro de eventos original descreve a ação conforme ela foi gravada pelo dispositivo, como firewall ou proxy da Web.
    • Os objetos entidade UDM armazenam dados sobre os participantes ou entidades envolvidos no evento UDM, como recursos, usuários ou recursos no seu ambiente.

  • Estrutura de um evento da UDM

  • Estrutura de uma entidade da UDM

  • Substantivos da UDM: um substantivo representa um participante ou uma entidade em um evento da UDM. Um substantivo pode ser, por exemplo, o dispositivo ou o usuário que realiza a atividade descrita no evento. Um substantivo também pode ser o dispositivo ou usuário que é o destino 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 seria o destino.
    src Uma entidade de origem em que o principal agiu. 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 o 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 gera relatórios sobre o evento, mas não interage diretamente com o tráfego. Por exemplo, 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 a inicialização de um processo.

    Na prática, os objetos substantivo 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.

Entenda o mapeamento de dados usado pelo analisador atual

Recomendamos entender o mapeamento de dados usado pelo analisador padrão (ou personalizado) entre os campos de origem de registros brutos e os campos de destino da UDM.

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

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

  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 do registro bruto e os campos de destino da UDM usados no analisador padrão (ou personalizado) atual.

Usar a ferramenta de pesquisa da UDM

Use a ferramenta de pesquisa de UDM para identificar os campos de UDM que correspondem aos campos de origem de registros brutos.

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 da UDM, acesse Investigação > Pesquisa do SIEM.

Consulte estes tópicos para saber como usar a ferramenta de pesquisa da 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 da UDM para encontrar possíveis campos de destino da UDM com "packets" no nome:

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

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

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

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

  3. Na caixa de diálogo Pesquisa de UDM, selecione Campos de UDM.

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

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

Considerações importantes sobre a UDM para evitar erros

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

Abra a página "Extensões do analisador".

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

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

Abra 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 > Analizadores.

    A tabela Analistas mostra uma lista de analistas padrão por tipo de registro.

  2. Encontre o tipo de registro que você quer estender, 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 registros brutos:

  1. Acesse Investigação > Pesquisa do SIEM.
  2. No campo de pesquisa, adicione o prefixo raw = ao argumento de pesquisa e coloque o termo 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 evento é exibido.
  5. Clique na guia Registro 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 legada Pesquisa de registros brutos:

  1. Use a pesquisa de registros brutos legada para procurar registros semelhantes aos que serão analisados.
  2. Selecione um evento no painel Eventos > Linha do tempo.
  3. Expanda o painel Dados de eventos.

  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 de 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 registros brutos, os dados de amostra são o resultado da sua pesquisa. É possível formatar a amostra usando o menu Ver como (RAW, JSON, CSV, XML etc.) 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 para conferir a saída do UDM dos dados de registro brutos de exemplo.

  • Painel Definição de 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 registros de origem para extrair dos registros brutos recebidos e mapeá-los para os campos correspondentes da UDM ou escrever um snippet de código para realizar essas tarefas e muito mais.

Selecione a abordagem de extensão

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

  • Abordagem de mapeamento de campos de dados (sem código):

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

    Essa abordagem funciona com os seguintes formatos de registros brutos:

    • JSON nativo, XML nativo ou CSV.
    • Cabeçalho 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.

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

  • Abordagem Escrever snippet de código:

    Essa abordagem permite usar uma sintaxe semelhante ao Logstash para especificar instruções de extração e transformação de valores do registro bruto e atribuí-los a campos da UDM no registro da UDM.

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

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

    Confira as próximas etapas em Criar instruções de snippet de código.

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

A abordagem sem código (também chamada de método Mapear campos de dados) permite especificar os caminhos dos campos de registros 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 o seletor de campos repetidos

No painel Definição de 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 armazenado no campo de matriz do UDM.
  • Substituir valores: o valor recém-extraído substitui o conjunto de valores atual no campo de matriz da 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 sobre o seletor de campos repetidos.

Defina 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 destino do UDM.

  1. Se o exemplo de registro bruto exibido 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.

    A Google SecOps precisa 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 registro bruta. Para mais detalhes, consulte Definir os campos do extrator 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 um padrão de extração e um nome de variável para os campos Syslog e Target, respectivamente.

      Campos do extrator 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 retorna um dos seguintes:

      • 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. Também é possível definir 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 recebido 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 dos dados de registro for JSON ou XML, ou a posição da coluna se o formato for CSV.
    • Operador de condição prévia: selecione EQUALS ou NOT EQUALS.
    • 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 pré-condição, consulte Sem código: extrair campos com valor de pré-condição.

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

    • Campo de dados brutos: insira o caminho completo para o campo se o formato dos 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 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 das instruções de mapeamento para o próximo campo.

Para 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ê quer 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 registros recebidos.

  • Se o processo de validação falhar, o estado vai mudar para Falha, e um erro será exibido 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 de analisador recém-criada que ainda não foi enviada.

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

  • LIVE: a extensão do analisador foi aprovada na validação e agora está em produção. Ele extrai e transforma dados de registros brutos recebidos em registros da 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. Com o seletor Campos repetidos, você controla como a extensão do analisador vai armazenar os dados extraídos recentemente 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 ele está no nível mais baixo da hierarquia. Exemplo:

  • O mapeamento de valores para udm.principal.ip é compatível porque o campo repetido ip 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 da 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":"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"} } }
Adicionar valores ao final {"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 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

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 sintático 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 da UDM gerados pelo analisador sintático 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 da UDM após aplicar a extensão timestamp:{} idm:{read_only_udm:{metadata:{event_timestamp:{} ....} principal:{ip:"2.2.2.2"}}}

Mais informações sobre os campos do extrator 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 Syslog

Os valores nos campos Syslog e Target trabalham 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 sintaxe Grok e de expressão regular. A expressão inclui um nome de variável que identifica a parte estruturada do registro bruto. No campo Meta, especifique o nome da variável.

O exemplo a seguir ilustra como esses campos funcionam juntos.

Este é um exemplo de um 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 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 Meta, insira o nome da variável msg. O valor armazenado na variável msg é inserido nas instruções de mapeamento de campos de dados que você cria na extensão do analisador.

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

Confira abaixo os campos Syslog e Destino preenchidos:

Campos do extrator Syslog

A tabela a seguir mostra mais exemplos com registros de amostra, o padrão de extração 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 como atribuir campos metadata.event_type da UDM

Ao atribuir um campo metadata.event_type da UDM a um registro da UDM, ele é validado para garantir que os campos relacionados obrigatórios estejam presentes no registro da 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 faltando, a validação da 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 da UDM que você quer atribuir, use os seguintes 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 da 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 obrigatórios mínimos da UDM necessários para preencher um determinado metadata.event_type da UDM.

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

    Você vai encontrar os seguintes campos mínimos da UDM, apresentados como um objeto da 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 ao Logstash para definir como extrair e transformar valores do registro bruto e atribuí-los a campos da UDM no registro da 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 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 de snippet de código usam a mesma sintaxe e seções do 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 da UDM.
  • Seção 4. Vincule os campos de evento da 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ões de analisadores, painel Snippet da CBN, insira um snippet de código para criar a extensão de analisador.
  2. Clique em Validar para validar as instruções de mapeamento.

Exemplos de instruções de snippets 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 network.sent_bytes do UDM:

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 registros recebidos.
    • Se o processo de validação falhar, o estado vai mudar para Falha, e um erro será exibido no campo "Registro bruto".

Gerenciar extensões de analisador atuais

Você pode ver, editar, excluir e controlar o acesso às extensões de analisador atuais.

Ver uma extensão do analisador existente

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

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

    A guia Extensão em Ver analisador sintático personalizado/pré-criado aparece com detalhes sobre a extensão do analisador sintático. O painel de resumo mostra a extensão do analisador LIVE por padrão.

Editar uma extensão do analisador

  1. Abra Ver analisador sintático personalizado/pré-criado > Guia "Extensão", conforme descrito em Ver uma extensão de analisador sintático atual.

  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 com 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 Ver analisador personalizado/pré-criado > Guia "Extensão", conforme descrito em Ver uma extensão de analisador existente.

  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 Administrador podem acessar as extensões do analisador. Você pode controlar quem pode ver e gerenciar extensões de 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 no Google SecOps estão resumidas na tabela a seguir.

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

Remover mapeamentos de campos da UDM usando extensões de analisador

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

  1. Clique em Configurações do SIEM > Analizadores.
  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 o analisador > Ver extensão.
    • Para novas extensões do analisador, clique em Menu > Estender analisador > Criar extensão.

  3. Selecione Escrever 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 da UDM.

    Para uma extensão atual, no painel Extensão do analisador, clique em Editar e adicione o snippet de código.

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

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

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