Criar analisadores personalizados e extensões de analisador com o Gemini

Compatível com:

Google SecOps SIEM

Observação: esse recurso é coberto pelos Termos de produtos e recursos em pré-GA dos Termos específicos de serviço do Google Security Operations. Os recursos pré-GA podem ter suporte limitado, e as mudanças realizadas podem não ser compatíveis com outras versões pré-GA. Para mais informações, consulte as diretrizes do serviço de suporte técnico do Google SecOps e os Termos específicos de serviço do Google SecOps.
Se esse recurso não estiver visível no seu ambiente, consulte Gerenciar recursos em fase de pré-lançamento ou entre em contato com o administrador do sistema.

Observação:esse recurso está em pré-lançamento particular e não está disponível para todos os clientes em todas as regiões. Os recursos em fase de pré-lançamento particular não são gerenciáveis na página do Gerenciador de Pré-lançamento Público na plataforma do Google SecOps.

Este guia ajuda analistas de segurança e engenheiros de detecção a usar a análise de IA no Google Security Operations para criar analisadores personalizados do zero ou criar extensões de analisador que aumentam os analisadores atuais. Usando comandos de linguagem natural e a documentação do fornecedor, é possível mapear registros brutos para o Modelo de Dados Unificado (UDM) sem escrever sintaxes de analisador complexas ou expressões regulares.

Escolher entre analisadores personalizados de IA e extensões de analisador de IA

A tabela a seguir compara os recursos "Criar analisador com IA" e "Escrever extensão com IA" na análise de IA:

Aspecto do recurso	Criar analisador com IA	Escrever extensão com IA
Saída	Um analisador personalizado completo e independente	Uma extensão em camadas em um analisador atual
Caso de uso principal	Fontes de registro novas ou não compatíveis ou uma reescrita completa do analisador	Adicionar ou corrigir campos específicos em um analisador em funcionamento
Entrada	Tipo de registro, registros brutos ingeridos e links de documentação opcionais	Tipo de registro, registro bruto de amostra e um comando que descreve os campos a serem mapeados

Terminologia importante

• Análise de IA:o conjunto de recursos de análise assistida por IA no Google SecOps, incluindo a geração de analisadores personalizados de IA (Criar analisador com IA) e extensões de analisador de IA (Escrever extensão com IA).
• Modelo de dados unificado (UDM): a estrutura de dados padrão usada no Google SecOps para armazenar e analisar dados de registro.

Antes de começar

Antes de usar a análise de IA, confirme se os seguintes pré-requisitos foram atendidos:

• Confirme se os recursos de análise de IA estão ativados na sua instância do Google SecOps. Se as opções Criar analisador com IA ou Criar extensão com IA não aparecerem, entre em contato com seu representante do Google SecOps.
• Para extensões de analisador de IA, verifique se o tipo de registro de destino já tem um analisador predefinido ou personalizado ativo e prepare um registro bruto de amostra para testar a extração.
• Para a geração de analisadores personalizados de IA, faça a ingestão de uma amostra representativa da origem de registro antes de começar. O Agente de Analisador aprende com os registros que você já ingeriu para o tipo de registro selecionado. Se nenhum registro for encontrado para o tipo, a geração não poderá ser iniciada. As tentativas de início com falha não são contabilizadas na cota.
• Para a geração de analisadores personalizados de IA, prepare de um a cinco links acessíveis ao público para a referência de formato de registro do fornecedor, como um dicionário de campos, um esquema de eventos ou uma página de amostras de registro (recomendado). A documentação abrangente é o fator mais importante na qualidade do analisador.

Criar um analisador personalizado com IA

O recurso Criar Analisador com IA cria um analisador personalizado completo para uma fonte de registro do zero. Selecione um tipo de registro e, se quiser, forneça links para a documentação de registro do fornecedor. O Agente de Analisador coleta amostras dos registros ingeridos, pesquisa o esquema de registro, planeja o mapeamento de campo bruto para UDM e escreve o código do analisador em JavaScript. Em seguida, você analisa o resultado e o refina usando instruções em inglês simples que fazem referência a nomes de campos brutos e campos de UDM. Quando a saída estiver pronta, envie o analisador como qualquer outro analisador personalizado.

Com a geração de analisadores personalizados de IA, é possível:

• Integre uma fonte de registro que não tenha um analisador pré-criado ou que não se ajuste ao formato do registro.
• Gere um analisador completo que cubra todos os formatos de registro distintos encontrados nos dados ingeridos, em vez de apenas uma única amostra.
• Refine o analisador gerado com comandos de acompanhamento sem escrever o código do analisador.

Iniciar um analisador personalizado gerado com IA

1. No Google SecOps, acesse Configurações do SIEM > Analisadores.
2. Clique em Adicionar novo analisador.
3. Na caixa de diálogo Criar novo analisador personalizado, selecione a Origem de registro que você quer analisar (por exemplo, GCP DNS).
4. Em Como você vai criar o analisador?, selecione Criar analisador com IA.
5. Clique em Criar.

Adicionar documentação do produto e iniciar a geração

Observação: os links de documentação são opcionais. Se você não adicionar links, a etapa de pesquisa vai buscar na Web a documentação do fornecedor e inferir o esquema diretamente dos seus registros brutos. Essa abordagem funciona bem para produtos comuns e bem documentados. Para fontes de registro de nicho ou internas, adicionar links oferece uma cobertura de campo melhor.

1. Opcional: no painel Agente do analisador, no campo Adicionar link do produto, cole um link para a documentação de registro do fornecedor e clique em Adicionar. É possível adicionar até cinco links. O contador Documentação mostra quantos links você adicionou.
2. Clique em Gerar analisador.

Diretrizes para links de documentação

Para melhorar a cobertura de campos no analisador gerado, siga estas diretrizes ao selecionar links de documentação:

• Forneça apenas links públicos para a documentação do fornecedor. Se um link for privado ou inacessível, o Agente de Análise vai ignorar o link e pesquisar na Web sem falhar na geração.
• Link para páginas que descrevem campos de registro e tipos de evento, como um esquema de registro, dicionário de campos ou referência de evento. Evite páginas de marketing ou visões gerais de produtos.
• Selecione as páginas que correspondem ao formato de registro que você ingere. Por exemplo, se você ingerir registros de auditoria JSON, vincule à referência de registro de auditoria JSON em vez da referência de syslog.
• Adicione um link para cada categoria de evento se o fornecedor documentar diferentes categorias de eventos em páginas separadas (por exemplo, consultas DNS, eventos de firewall e atividade do administrador).

Acompanhar o progresso da geração

Quando a geração do analisador personalizado começa, o status muda para GERAÇÃO EM ANDAMENTO. O processo de geração consiste nas seguintes etapas:

Fase	Ação do agente	Saída transmitida para a próxima fase
Como buscar registros brutos	O agente faz uma amostragem dos registros ingeridos para o tipo de registro. Ele agrupa os registros para selecionar um conjunto de exemplos que abrange todos os formatos de registro e formas de evento.	Exemplos de registros representativos
Análise de Conteúdo	O agente lê os links do documento que você forneceu ou pesquisa na Web se você não tiver fornecido links. Ele combina essas informações com os registros de exemplo para criar um esquema de registro e um dicionário de campos.	Esquema de registro e dicionário de campos
Criar um plano de mapeamento	O agente identifica cada tipo de evento nos registros e planeja como cada campo de registro bruto é mapeado para o campo do UDM correspondente.	Plano de mapeamento do campo bruto para o campo do UDM para cada tipo de evento
Gerar código do analisador	O agente converte o plano de mapeamento em código de analisador JavaScript. Ele testa o código com os registros de exemplo e resolve erros até que o analisador seja executado sem problemas.	Analisador pronto para revisão

Observação: o processo de geração geralmente leva de 30 a 90 minutos, dependendo do número de formatos de registro distintos, da complexidade da fonte de registro e do tamanho do esquema de registro. Você não precisa deixar a página aberta. Clique em Fechar e volte para Configurações do SIEM > Analisadores mais tarde. Quando a geração for concluída, o analisador vai aparecer na lista com um selo GERADO COM IA.

Se a geração do analisador falhar porque nenhum registro foi encontrado para o tipo selecionado, faça a ingestão de registros brutos desse tipo antes de iniciar a geração novamente. Para qualquer outra falha de geração, não há opções de triagem manual disponíveis. Acione uma nova sessão de geração. Se a falha persistir, entre em contato com o suporte para abrir um caso.

Revisar e refinar o analisador personalizado

Quando a geração do analisador personalizado é concluída, o status muda para GERADO COM IA, e a página mostra os seguintes painéis:

• Agente do analisador:exibe o campo de comando Refinar analisador com IA, em que é possível inserir instruções de acompanhamento.
• Código do analisador:mostra o código do analisador JavaScript gerado para revisão. O código gerado é somente leitura antes do envio. Para modificar a lógica, insira um comando no campo Refinar analisador com IA.
• Registro bruto:mostra exemplos de registros brutos para o tipo de registro. Clique em Editar para colar sua própria linha de registro ou em Atualizar para carregar outras amostras.
• Mostrar saída do UDM:executa o código do analisador atual no registro bruto e exibe o evento do UDM resultante para que você possa verificar cada mapeamento.

Analisar a saída gerada

Antes de ativar o analisador, revise os mapeamentos gerados nos registros de amostra:

1. Carregue vários registros brutos, incluindo cada tipo de evento que você quer analisar, e clique em Mostrar saída do UDM para cada registro.
2. Verifique se o analisador mapeia os campos de registro brutos para os campos de UDM apropriados e preenche os valores com precisão (por exemplo, metadados de eventos, campos de entidade como principal e target e campos de resultado de segurança).
3. Verifique se há campos brutos importantes que ainda não foram mapeados.

Refinar o analisador personalizado com IA

Se um mapeamento estiver incorreto ou ausente, insira uma instrução no campo Refinar analisador com IA e clique em Confirmar. O Agente de Analisador atualiza o analisador atual em vez de começar do zero e preserva todos os mapeamentos que você não mencionou. Cada refinamento cria uma nova versão do código do analisador que você pode revisar.

Siga estas diretrizes para criar comandos de refinamento eficazes:

1. Indique o campo de origem bruto (ou um valor de amostra do registro) e o caminho exato do campo de UDM de destino.
2. Agrupe as mudanças relacionadas e evite misturar correções não relacionadas em um único comando longo.
3. Coloque strings exatas do registro bruto entre aspas simples, como 'NXDOMAIN' ou 'allow'.
4. Indique os mapeamentos condicionais explicitamente usando uma estrutura if ... then ... otherwise ... quando um mapeamento depender de um valor de campo.
5. Instrua o agente a mapear atributos específicos do fornecedor que não têm um campo de UDM correspondente para additional.fields com um nome de chave claro.

A tabela a seguir mostra exemplos de comandos de refinamento para registros de GCP DNS:

Meta	Exemplo de comando
Corrigir um mapeamento incorreto	"Map jsonPayload.sourceIP to principal.ip instead of target.ip."
Adicionar um campo ausente	"Map jsonPayload.vmInstanceName to principal.hostname."
Mapear um valor aninhado ou repetido	"Map jsonPayload.queryName to network.dns.questions.name and jsonPayload.queryType to network.dns.questions.type."
Aplique lógica condicional	"If jsonPayload.responseCode is 'NXDOMAIN', set security_result.summary to 'Domain does not exist'. Otherwise, leave it empty."
Definir o tipo de evento	"Set metadata.event_type to NETWORK_DNS for all DNS query logs."
Mapear um campo específico do fornecedor	"Map jsonPayload.alias_query_response_code to additional.fields with key 'alias_query_response_code'."
Remover um mapeamento	"Stop mapping jsonPayload.protocol to network.application_protocol."

Observação: não é possível editar o código gerado diretamente no painel Código do analisador antes do envio. Depois de enviar e ativar o analisador, você pode editar o código manualmente como qualquer outro analisador personalizado.

Enviar e ativar o analisador personalizado

Quando a saída do UDM estiver correta, clique em Enviar para salvar e ativar o analisador personalizado gerado.

Para abandonar o rascunho do analisador, clique em Descartar. Para remover um analisador personalizado gerado com IA salvo, abra o analisador e clique em Excluir em Excluir analisador personalizado.

Atenção: a geração de analisadores personalizados com IA é um recurso experimental. A qualidade do analisador gerado pode variar. Sempre revise a saída do UDM para cada tipo de evento e valide o analisador antes de ativá-lo na produção.

Resolver problemas na geração de analisadores personalizados de IA

A tabela a seguir lista problemas comuns que podem ocorrer ao gerar um analisador personalizado com IA e como resolvê-los:

Problema ou sintoma	Resolução
A opção Criar analisador com IA não aparece.	O recurso não está ativado para sua instância. Entre em contato com seu representante do Google SecOps.
A geração falha porque nenhum registro é encontrado para o tipo de registro.	O agente analisador requer registros brutos ingeridos para o tipo de registro selecionado. Faça a ingestão de registros brutos para o tipo de registro antes de iniciar a geração novamente.
A geração falha por outro motivo.	Não há opções de triagem manual disponíveis para uma geração com falha. Acione a geração novamente. Se a falha persistir, entre em contato com o suporte para abrir um caso.
A geração leva muito tempo para ser concluída.	A geração geralmente leva de 30 a 90 minutos. Fontes de registro complexas com muitos formatos distintos ou esquemas grandes levam mais tempo. Você pode fechar a página e voltar para Configurações do SIEM > Analisadores mais tarde.
Muitos campos permanecem sem mapeamento.	Adicione links de documentação que descrevam os campos de registro e inicie uma nova sessão ou use comandos de refinamento para mapear os campos ausentes.
Um comando de refinamento mudou um mapeamento não relacionado.	Descreva a correção em um comando de acompanhamento (por exemplo, "Revert the change to principal.ip and map jsonPayload.sourceIP to it again."). Como alternativa, envie e ative o analisador para editar o código manualmente.
Alguns registros não são analisados em Mostrar saída do UDM.	Cole o registro com falha no painel Registro bruto e envie um comando de refinamento que cite a parte não analisada do registro.

Criar uma extensão de analisador com IA

Quando um analisador de registros padrão no Google SecOps analisa sua fonte de registros, ele pode omitir atributos personalizados específicos do cliente, campos opcionais ou telemetria especializada. Com as extensões de analisador de IA (Escrever extensão com IA), é possível:

• Extraia campos adicionais de registros brutos e mapeie-os para campos padrão do UDM ou additional.fields personalizados.
• Aplicar lógica condicional e transformações de valor, como mapear ações de string para tipos enumerados de UDM.
• Refine as extensões geradas de forma interativa em conversas multiturno sem precisar começar do zero.

Práticas recomendadas para criar comandos

Para receber extensões de analisador precisas, siga estas diretrizes de comando:

1. Indique claramente qual parte do registro bruto deve ser extraída e qual caminho de campo do UDM ela preenche (por exemplo, principal.ip, target.user.email_addresses ou security_result.action).
2. Coloque strings literais, delimitadores ou valores de amostra em registros não estruturados entre aspas simples, como '198.51.100.0' ou 'allow'.
3. Instrua a IA a mapear atributos proprietários ou específicos do fornecedor que não têm um campo UDM dedicado em additional.fields com um nome de chave claro (por exemplo, additional.fields["application"]).

Gerar uma extensão de analisador

É possível iniciar o fluxo de trabalho de extensão do analisador em um dos seguintes locais no Google SecOps:

• Acesse Configurações do SIEM > Analisadores para selecionar e estender qualquer analisador de registros.
• Abra o fluxo de criação de extensões diretamente de um evento com campos não analisados ao investigar registros na página Pesquisa.

Para gerar uma extensão de analisador na página Analisadores, siga estas etapas:

1. No Google SecOps, acesse Configurações do SIEM > Analisadores.
2. Pesquise na tabela Analisadores o tipo de registro que você quer estender.
3. Na linha do analisador, clique em Menu e selecione Estender analisador > Criar extensão.
4. No painel Registro bruto, verifique o registro bruto de amostra ou clique em Editar para colar uma amostra do registro que você quer analisar.
5. No painel Extensão, em Método de extensão, selecione Escrever extensão com IA.
6. No campo de comando, insira uma descrição em inglês simples dos campos que você quer extrair.

7. Clique em Confirmar.

   O sistema gera o código da extensão e atualiza o painel Saída do UDM.

Refinar a extensão do analisador

É possível criar e refinar sua extensão de analisador de forma iterativa em sessões de conversa multiturno. Quando você envia um comando de acompanhamento, a IA aplica as novas instruções à extensão gerada anteriormente. Os mapeamentos e a lógica condicional de turnos anteriores são preservados automaticamente, a menos que você peça explicitamente para substituí-los ou removê-los.

Observação: as sessões não são mantidas depois que você sai da página. Para não perder seu trabalho, conclua ou salve a extensão antes de sair.

1. No campo de comando, insira uma instrução complementar para ajustar o código gerado.
2. Clique em Confirmar.
3. Após cada comando, visualize o código de extensão gerado, inspecione as saídas de UDM de amostra e confirme ou ajuste a lógica.

Observação: se você precisar corrigir um erro de uma rodada anterior, diga o que mudar em português simples, por exemplo, "Change the target field for callerIp from target.ip to principal.ip".

O exemplo de fluxo de trabalho a seguir mostra como o refinamento iterativo cria uma extensão de analisador em várias interações:

1. Turno 1 (extração inicial):
   • Comando do usuário:"Extract source IP '198.51.100.0' to principal.ip and destination IP '198.51.100.1' to target.ip."
   • Resultado:a IA gera um mapeamento de extensão principal.ip e target.ip.
2. Turno 2 (mapeamento aditivo):
   • Comando do usuário:"Also map virtual system string 'vsys1' to observer.administrative_domain."
   • Resultado:a IA atualiza a extensão para mapear observer.administrative_domain, mantendo os mapeamentos de IP da rodada 1.
3. Turno 3 (refinamento condicional):
   • Comando do usuário:"In addition, map action string 'allow' to security_result[0].action as ALLOW."
   • Resultado:a IA incorpora o mapeamento de enumeração da ação condicional sobre todas as extrações anteriores.

Validar a extensão do analisador

1. Clique em Validate (Validar).
2. Analise as métricas de validação após a conclusão do processo.

Acessar informações de referência

Use os exemplos a seguir para criar comandos precisos para extensões de analisador.

Comandos de registros estruturados

Para registros estruturados em que os dados são organizados em chaves, atributos ou tags XML nomeados, especifique os nomes ou caminhos dos campos no comando.

Exemplo de registro estruturado: formato JSON

{
  "insertId": "u0mlpdesys",
  "logName": "projects/sample-project-id/logs/cloudaudit.googleapis.com%2Fdata_access",
  "protoPayload": {
    "authenticationInfo": {
      "principalEmail": "[e-mail]"
    },
    "methodName": "GenerateAccessToken",
    "requestMetadata": {
      "callerIp": "203.0.113.195",
      "callerSuppliedUserAgent": "google-cloud-sdk gcloud/392.0.0"
    },
    "resourceName": "projects/-/serviceAccounts/110649196922301550006",
    "serviceName": "iamcredentials.googleapis.com"
  }
}

Exemplos de comandos para registros estruturados

Instrução de comando	Campo ou chave de origem	Campo de UDM de destino
"Map principalEmail to principal.user.email_addresses."	principalEmail	principal.user.email_addresses
"Extract callerIp to principal.ip and methodName to metadata.product_event_type."	callerIp, methodName	principal.ip, metadata.product_event_type
"Map resourceName to target.resource.name and serviceName to target.application."	resourceName, serviceName	target.resource.name, target.application
"From XML tags, map /Event/System/Hostname to principal.hostname."	/Event/System/Hostname	principal.hostname

Comandos de registros não estruturados

Para registros não estruturados, especifique valores literais diretamente do registro de amostra, referências posicionais ou rótulos descritivos.

Exemplo de mensagem syslog não estruturada

<14>Nov  9 18:52:45 198.51.100.1 1,2021/11/09 18:52:45,007051000184334,TRAFFIC,start,2561,2021/11/09 18:52:45,198.51.100.0,198.51.100.1,0.0.0.0,0.0.0.0,any allow,,,ping,vsys1,LAN,LAN,ethernet1/2,ethernet1/2,LFPpan,2021/11/09 18:52:45,9729,6,0,0,2048,0,0x100000,icmp,allow,444,444,0,6

Exemplos de comandos para registros não estruturados

Instrução de comando	Exemplo de valor literal ou descrição	Campo de UDM de destino
"Extract source IP '198.51.100.0' to principal.ip and destination IP '198.51.100.1' to target.ip."	'198.51.100.0', '198.51.100.1'	principal.ip, target.ip
"Extract the application string 'ping' from the log and map it to additional.fields['application']."	'ping'	additional.fields["application"]
"Map rule name 'any allow' to security_result.rule_id."	'any allow'	security_result[0].rule_id
"Extract sent bytes and received bytes into network.sent_bytes and network.received_bytes."	Contadores de bytes numéricos no registro	network.sent_bytes, network.received_bytes

Comandos de lógica condicional

Descrever a lógica condicional para normalizar valores de registro brutos em enumerações específicas do UDM.

• Normalização de enumeração: "If the firewall action in the log is 'allow', set security_result.action to ALLOW; otherwise set security_result.action to BLOCK."
• Mapeamento de campo condicional:"If the protocol is 'icmp', map the ICMP type and code into network.icmp.type and network.icmp.code."
• Mapeamento de status: "When the log status contains 'success' or '0', set security_result.severity to INFO; if it contains 'error', set it to ERROR."

Limites de uso

Para manter o desempenho ideal e a disponibilidade de recursos, os recursos de análise de IA aplicam as seguintes cotas de uso padrão:

• É possível iniciar até 10 sessões de geração de analisador personalizado de IA ou de extensão de analisador de IA por instância em um período de 24 horas. Para analisadores personalizados, cada clique em Gerar analisador para um novo analisador inicia uma sessão.
• Cada sessão aplica os seguintes limites de interação:
  • Para a geração de analisadores personalizados de IA, cada sessão aceita até seis turnos no total, o que inclui a geração inicial e até cinco comandos de refinamento.
  • Para extensões de analisador de IA, cada sessão aceita até 5 mensagens no total, incluindo o comando inicial e as interações de refinamento subsequentes.

Se você atingir o limite de turnos ou mensagens de uma sessão, poderá enviar ou salvar seu trabalho atual ou iniciar uma nova sessão (sujeito à cota de sessão diária). Para analisadores personalizados, depois de enviar e ativar o analisador, é possível editar o código manualmente como qualquer outro analisador personalizado.

A seguir

• Para mais informações sobre como criar e gerenciar analisadores personalizados, consulte Configurar analisadores personalizados.
• Para mais detalhes sobre outros métodos de extensão do analisador, consulte Desenvolver extensões do analisador.
• Para ver snippets e cenários de extensão de amostra, consulte Exemplos de extensão de analisador.
• Para uma visão geral de como os registros brutos são analisados para o UDM, consulte Visão geral da análise de registros.

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