Desenvolver analisadores do Modelo de Informação de Segurança Avançada (ASIM)

Os utilizadores do Modelo de Informação de Segurança Avançada (ASIM) utilizam analisadores unificadores em vez de nomes de tabelas nas suas consultas, para ver dados num formato normalizado e para incluir todos os dados relevantes para o esquema na consulta. Analisadores unificadores, por sua vez, empregam analisadores específicos da fonte para tratar dos detalhes específicos de cada fonte.

Microsoft Sentinel fornece analisadores internos e específicos da origem para muitas fontes de dados. Talvez você queira modificar, ou desenvolver, esses analisadores específicos da fonte nas seguintes situações:

  • Quando o dispositivo fornece eventos que se ajustam a um esquema do ASIM, mas um analisador específico da fonte para seu dispositivo e o esquema relevante não estão disponíveis no Microsoft Sentinel.

  • Quando os analisadores específicos da fonte do ASIM estão disponíveis para seu dispositivo, mas seu dispositivo envia eventos em um método ou formato diferente do esperado pelos analisadores do ASIM. Por exemplo:

    • Seu dispositivo de origem pode ser configurado para enviar eventos de maneira não padrão.

    • O seu dispositivo pode ter uma versão diferente da suportada pelo analisador ASIM.

    • Os eventos podem ser coletados, modificados e encaminhados por um sistema intermediário.

Para compreender como os analisadores se encaixam na arquitetura ASIM, veja o diagrama de arquitetura ASIM.

Processo de desenvolvimento do analisador ASIM personalizado

O fluxo de trabalho a seguir descreve as etapas gerais para desenvolver um analisador ASIM personalizado e específico da fonte:

  1. Coletar logs de exemplo.

  2. Identifique o esquema ou esquemas que os eventos enviados da fonte representam. Para obter mais informações, veja Descrição geral do esquema.

  3. Mapeie os campos de evento de origem para o esquema ou esquemas identificados.

  4. Desenvolva um ou mais analisadores do ASIM para sua fonte. Você precisará desenvolver um analisador de filtragem e um analisador sem parâmetros para cada esquema relevante para a fonte.

  5. Teste seu analisador.

  6. Implante os analisadores nos workspaces do Microsoft Sentinel.

  7. Atualize o analisador de unificação relevante do ASIM para que ele referencie o novo analisador personalizado. Para obter mais informações, consulte Gerenciar analisadores do ASIM.

  8. Talvez você também queira contribuir com seus analisadores para a distribuição primária do ASIM. Os analisadores contribuídos também podem ser disponibilizados em todos os espaços de trabalho como analisadores integrados.

Este artigo orienta você pelas etapas de desenvolvimento, teste e implantação do processo.

Coletar logs de exemplo

Para criar analisadores ASIM eficazes, você precisa de um conjunto representativo de logs, o que, na maioria das vezes, exigirá configurar o sistema de origem e conectá-lo ao Microsoft Sentinel. Se não tiver o dispositivo de origem disponível, os serviços pay as you go na cloud permitem-lhe implementar muitos dispositivos para desenvolvimento e teste.

Além disso, encontrar a documentação e os exemplos do fornecedor para os registos pode ajudar a acelerar o desenvolvimento e reduzir os erros ao garantir uma ampla cobertura do formato de registo.

Um conjunto representativo de registos deve incluir:

  • Eventos com resultados diferentes.
  • Eventos com diferentes ações de resposta.
  • Formatos diferentes para nome de utilizador, nome de anfitrião e IDs e outros campos que requerem normalização de valor.

Tip

Inicie um novo analisador personalizado usando um analisador existente para o mesmo esquema. Usar um analisador existente é especialmente importante para filtrar analisadores para garantir que eles aceitem todos os parâmetros exigidos pelo esquema.

Planejamento de mapeamento

Antes de desenvolver um analisador, mapeie as informações disponíveis no evento de origem ou eventos para o esquema que você identificou:

  • Mapeie todos os campos obrigatórios e, preferencialmente, também os campos recomendados.
  • Tente mapear todas as informações disponíveis da origem para campos normalizados. Se não estiver disponível como parte do esquema selecionado, considere o mapeamento para campos disponíveis em outros esquemas.
  • Mapeie os valores dos campos de origem para os valores normalizados permitidos pelo ASIM. O valor original é armazenado num campo separado, como EventOriginalResultDetails.

Desenvolvendo analisadores

Desenvolva uma filtragem e um analisador sem parâmetros para cada esquema relevante.

Um analisador personalizado é uma consulta KQL desenvolvida na página Microsoft Sentinel Logs. A consulta do analisador tem três partes:

Filtrar>Analisar>Preparar campos

Filtragem

Filtrar os registos relevantes

Em muitos casos, uma tabela no Microsoft Sentinel inclui vários tipos de eventos. Por exemplo:

  • A tabela Syslog tem dados de várias fontes.
  • As tabelas personalizadas podem incluir informações de uma única fonte que fornece mais de um tipo de evento e podem se ajustar a vários esquemas.

Portanto, um analisador deve primeiro filtrar somente os registros relevantes para o esquema de destino.

A filtragem no KQL é feita usando o operador where. Por exemplo, o evento Sysmon 1 relata a criação do processo e, portanto, deve ser normalizado para o esquema ProcessEvent. O evento Sysmon 1 faz parte da tabela Event, logo o seguinte filtro deve ser usado:

Event | where Source == "Microsoft-Windows-Sysmon" and EventID == 1

Importante

Um analisador de sintaxe não deve filtrar por tempo. A consulta que utiliza o analisador aplicará um intervalo de tempo.

Filtragem por tipo de origem usando uma Watchlist

Em alguns casos, o próprio evento não contém informações que permitiriam a filtragem por tipos de origem específicos.

Por exemplo, os eventos DNS do Infoblox são enviados como mensagens do Syslog e são difíceis de distinguir das mensagens do Syslog enviadas de outras fontes. Nestes casos, o analisador baseia-se numa lista de origens que define os eventos relevantes. Essa lista é mantida na lista de monitoramento Sources_by_SourceType.

Para empregar a lista de observação ASimSourceType em seus analisadores, use a função _ASIM_GetSourceBySourceType na seção de filtragem dos analisadores. Por exemplo, o analisador DNS do Infoblox inclui o seguinte na secção de filtragem:

  | where Computer in (_ASIM_GetSourceBySourceType('InfobloxNIOS'))

Para utilizar este exemplo no seu analisador:

  • Substitua Computer pelo nome do campo que contém as informações de origem da sua fonte. Você pode mantê-lo como Computer para qualquer analisador baseado no Syslog.

  • Substitua o token InfobloxNIOS por um valor de sua escolha para o analisador. Informe os usuários do analisador que eles devem atualizar a watchlist ASimSourceType usando o valor selecionado, bem como a lista de origens que enviam eventos desse tipo.

Filtragem com base em parâmetros de analisador

Ao desenvolver analisadores de filtragem, certifique-se de que o analisador aceita os parâmetros de filtragem para o esquema relevante, conforme documentado no artigo de referência para esse esquema. O uso de um analisador existente como ponto de partida garante que seu analisador inclua a assinatura correta de função. Na maioria dos casos, o código de filtragem em si também é semelhante entre analisadores de filtragem para o mesmo esquema.

Ao filtrar, certifique-se de que:

  • Filtrar antes de analisar usando campos físicos. Se os resultados filtrados não forem precisos o suficiente, repita o teste após a análise para ajustar os resultados. Para obter mais informações, confira otimização de filtragem.
  • Não filtre se o parâmetro não estiver definido e ainda tiver o valor predefinido.

Os exemplos a seguir mostram como implementar a filtragem em um parâmetro de cadeia de caracteres, em que o valor padrão é geralmente '*', e em um parâmetro de lista, em que o valor padrão é geralmente uma lista vazia.

srcipaddr=='*' or ClientIP==srcipaddr
array_length(domain_has_any) == 0 or Name has_any (domain_has_any)

Veja mais informações sobre os seguintes itens na documentação do Kusto:

Otimização da filtragem

Para garantir o desempenho do analisador, observe as seguintes recomendações de filtragem:

  • Sempre filtre por campos integrados em vez de analisados. Embora às vezes seja mais fácil filtrar usando campos analisados, isso afeta drasticamente o desempenho.
  • Utilize operadores que proporcionam um desempenho otimizado. Especialmente ==, has e startswith. A utilização de operadores como contains ou matches regex também afeta significativamente o desempenho.

Nem sempre é fácil seguir as recomendações de filtragem para melhorar o desempenho. Por exemplo, utilizar has é menos preciso do que contains. Noutros casos, a correspondência do campo incorporado, como SyslogMessage, é menos precisa do que comparar um campo extraído, como DvcAction. Nesses casos, recomendamos fazer uma filtragem prévia usando um operador de otimização de desempenho em um campo integrado e repetir o filtro usando condições mais precisas após a análise.

Para obter um exemplo, confira o snippet de analisador DNS Infoblox a seguir. O analisador primeiro verifica se o campo SyslogMessage has (tem) a palavra client. No entanto, o termo pode ser usado em um local diferente na mensagem, portanto, depois de analisar o campo Log_Type, o analisador verifica novamente se a palavra client era realmente o valor do campo.

Syslog | where ProcessName == "named" and SyslogMessage has "client"
…
      | extend Log_Type = tostring(Parser[1]),
      | where Log_Type == "client"

Note

Os analisadores não devem filtrar por tempo, uma vez que a consulta que utiliza o analisador já filtra o tempo.

Análise

Depois que a consulta seleciona os registros relevantes, talvez seja necessário analisá-los. Normalmente, a análise é necessária se vários campos de evento forem transmitidos num único campo de texto.

Os operadores KQL que executam a análise são listados abaixo, ordenados por otimização de desempenho. O primeiro fornece o desempenho mais otimizado, enquanto o último proporciona o desempenho menos otimizado.

Operador/função() Description
Função split() Analise uma cadeia de valores delimitados.
Função parse_csv() Analise uma cadeia de valores formatada como uma linha CSV (valores separados por vírgulas).
operador parse-kv Extrai informações estruturadas de uma expressão de cadeia e representa as informações num formulário chave/valor.
operador de análise Analise múltiplos valores de uma cadeia arbitrária com um padrão, que pode ser um padrão simplificado com melhor desempenho ou uma expressão regular.
Função extract_all() Analisar valores individuais de uma cadeia de caracteres arbitrária usando uma expressão regular. extract_all terá um desempenho semelhante a parse se o último usar uma expressão regular.
função extract() Extrair um único valor de uma cadeia de caracteres arbitrária usando uma expressão regular.

Usar extract fornece melhor desempenho do que parse ou extract_all se um único valor for necessário. No entanto, usar várias ativações de extract sobre a mesma cadeia de caracteres de fonte é menos eficiente do que uma única parse ou extract_all. O ideal é evitar essa prática.
Função parse_json() Analise os valores numa cadeia formatada como JSON. Quando apenas alguns valores de JSON são necessários, usar parse, extract ou extract_all melhora o desempenho.
Função parse_xml() Analise os valores numa cadeia formatada como XML. Quando apenas alguns valores do XML são necessários, usar parse, extract ou extract_all melhora o desempenho.

Normalização

Mapeamento de nomes de campo

A forma mais simples de normalização é mudar o nome de um campo original para o nome normalizado. Use o operador project-rename para fazer isso. O uso do recurso 'project-rename' assegura que o campo continue a ser gerenciado como um campo físico e que o gerenciamento do campo ocorra de forma mais eficiente. Por exemplo:

 | project-rename
    ActorUserId = InitiatingProcessAccountSid,
    ActorUserAadId = InitiatingProcessAccountObjectId,
    ActorUserUpn = InitiatingProcessAccountUpn,

Normalizar o formato e o tipo dos campos

Em muitos casos, o valor original extraído precisa ser normalizado. Por exemplo, no ASIM, um endereço MAC usa dois-pontos como separador, enquanto a origem pode enviar um endereço MAC delimitado por hífen. O operador principal para transformar valores é extend, juntamente com um conjunto amplo de funções de cadeia KQL, numéricas e de data.

Além disso, garantir que os campos de saída do analisador correspondam ao tipo definido no esquema é fundamental para que os analisadores funcionem. Por exemplo, talvez seja necessário converter uma cadeia de caracteres que representa a data e a hora em um campo datetime. Funções como todatetime e tohex são úteis nestes casos.

Por exemplo, o ID de evento exclusivo original pode ser enviado como um número inteiro, mas o ASIM requer que o valor seja uma cadeia, para garantir uma ampla compatibilidade entre as origens de dados. Portanto, ao atribuir o campo de origem, use extend e tostring em vez de project-rename:

  | extend EventOriginalUid = tostring(ReportId),

Campos e valores derivados

O valor do campo de origem, depois de extraído, pode precisar ser associado ao conjunto de valores especificado para o campo de esquema de destino. As funções iff, case e lookup podem ser úteis a fim de mapear dados disponíveis para valores de destino.

Por exemplo, o analisador DNS da Microsoft atribui o campo EventResult com base na ID do evento e no Código de resposta usando uma instrução iff da seguinte forma:

   extend EventResult = iff(EventId==257 and ResponseCode==0 ,'Success','Failure')

Para mapear vários valores, defina o mapeamento usando o operador datatable e empregue lookup para efetuar o mapeamento. Por exemplo, algumas fontes relatam códigos de resposta DNS numéricos e o protocolo de rede, enquanto o esquema exige a representação de rótulos de texto mais comuns para ambos. O seguinte exemplo demonstra como derivar os valores necessários usando datatable e lookup:

   let NetworkProtocolLookup = datatable(Proto:real, NetworkProtocol:string)[
        6, 'TCP',
        17, 'UDP'
   ];
    let DnsResponseCodeLookup=datatable(DnsResponseCode:int,DnsResponseCodeName:string)[
      0,'NOERROR',
      1,'FORMERR',
      2,'SERVFAIL',
      3,'NXDOMAIN',
      ...
   ];
   ...
   | lookup DnsResponseCodeLookup on DnsResponseCode
   | lookup NetworkProtocolLookup on Proto

Observe que a pesquisa é útil e eficiente também quando o mapeamento tem apenas dois valores possíveis.

Quando as condições de mapeamento são mais complexas, combine iff, case e lookup. O exemplo abaixo mostra como combinar lookup e case. O lookup exemplo acima devolve um valor vazio no campo DnsResponseCodeName se o valor de pesquisa não for encontrado. O exemplo case abaixo o complementa, usando o resultado da operação lookup, se disponível, e especificando condições adicionais caso contrário.

   | extend DnsResponseCodeName = 
      case (
        DnsResponseCodeName != "", DnsResponseCodeName,
        DnsResponseCode between (3841 .. 4095), 'Reserved for Private Use',
        'Unassigned'
      )

Microsoft Sentinel fornece funções úteis para valores de pesquisa comuns. Por exemplo, a pesquisa DnsResponseCodeName acima pode ser implementada usando uma das seguintes funções:


| extend DnsResponseCodeName = _ASIM_LookupDnsResponseCode(DnsResponseCode)

| invoke _ASIM_ResolveDnsResponseCode('DnsResponseCode')

A primeira opção aceita como parâmetro o valor a ser pesquisado e permite que você escolha o campo de saída e, portanto, útil como uma função de pesquisa geral. A segunda opção é mais voltada para analisadores, usa como entrada o nome do campo de origem e atualiza o campo ASIM necessário, nesse caso DnsResponseCodeName.

Para obter uma lista completa das funções de ajuda do ASIM, veja Funções ASIM

Campos de enriquecimento

Além dos campos disponíveis na origem, um evento ASIM resultante inclui campos de enriquecimento que o analisador deve gerar. Em muitos casos, os analisadores podem atribuir um valor constante aos campos, por exemplo:

  | extend                  
     EventCount = int(1),
     EventProduct = 'M365 Defender for Endpoint',
     EventVendor = 'Microsoft',
     EventSchemaVersion = '0.1.0',
     EventSchema = 'ProcessEvent'

Outro tipo de campos de enriquecimento que seus analisadores devem definir são os campos de tipo, que designam o tipo do valor armazenado em um campo relacionado. Por exemplo, o campo SrcUsernameType designa o tipo de valor armazenado no campo SrcUsername. Você pode encontrar mais informações sobre campos de tipo na descrição de entidades.

Na maioria dos casos, os tipos também recebem um valor constante. No entanto, em alguns casos, o tipo precisa ser determinado com base no valor real, por exemplo:

   DomainType = iif (array_length(SplitHostname) > 1, 'FQDN', '')

Microsoft Sentinel fornece funções úteis para lidar com o enriquecimento. Por exemplo, use a função a seguir para atribuir automaticamente os campos SrcHostname, SrcDomain, SrcDomainType e SrcFQDN com base no valor do campoComputer.

  | invoke _ASIM_ResolveSrcFQDN('Computer')

Essa função definirá os campos da seguinte maneira:

Área de computação Campos de saída
server1 SrcHostname: server1
SrcDomain, SrcDomainType e SrcFQDN estão todos vazios
server1.microsoft.com SrcHostname: server1
SrcDomain: microsoft.com
SrcDomainType: FQDN
SrcFQDN:server1.microsoft.com

As funções _ASIM_ResolveDstFQDN e _ASIM_ResolveDvcFQDN desempenham uma tarefa semelhante, preenchendo os campos relacionados Dst e Dvc. Para obter uma lista completa das funções de ajuda do ASIM, veja Funções ASIM

Selecionar campos no conjunto de resultados

Opcionalmente, o analisador pode selecionar campos no conjunto de resultados. Remover campos desnecessários pode melhorar o desempenho e aumentar a clareza ao evitar confusão entre campos normalizados e campos de origem restantes.

Os seguintes operadores KQL são usados para selecionar campos em seu conjunto de resultados:

Operador Description Quando utilizar num analisador
project-away Remova campos. Use project-away para campos específicos que você deseja remover do conjunto de resultados. É recomendável não remover os campos originais que não são normalizados do conjunto de resultados, a menos que eles criem confusão ou sejam muito grandes e possam ter implicações de desempenho.
projeto Seleciona os campos que existiam antes ou que foram criados como parte da instrução e remove todos os outros campos. Não recomendado para utilização num analisador, uma vez que o analisador não deve remover outros campos que não estejam normalizados.

Se precisar de remover campos específicos, como valores temporários utilizados durante a análise, utilize project-away para os remover dos resultados.

Por exemplo, ao analisar uma tabela de log personalizada, use o seguinte para remover os campos originais restantes que ainda têm um descritor de tipo:

    | project-away
        *_d, *_s, *_b, *_g

Processar variantes de análise

Importante

As diferentes variantes representam diferentes tipos de eventos, geralmente mapeados para esquemas diferentes, desenvolvendo analisadores separados

Em muitos casos, os eventos em um fluxo de eventos incluem variantes que exigem uma lógica de análise diferente. Para analisar diferentes variantes em um único analisador, use instruções condicionais como iff e caseou use uma estrutura de união.

Para utilizar union para processar múltiplas variantes, crie uma função separada para cada variante e utilize a instrução união para combinar os resultados:

let AzureFirewallNetworkRuleLogs = AzureDiagnostics
    | where Category == "AzureFirewallNetworkRule"
    | where isnotempty(msg_s);
let parseLogs = AzureFirewallNetworkRuleLogs
    | where msg_s has_any("TCP", "UDP")
    | parse-where
        msg_s with           networkProtocol:string 
        " request from "     srcIpAddr:string
        ":"                  srcPortNumber:int
    …
    | project-away msg_s;
let parseLogsWithUrls = AzureFirewallNetworkRuleLogs
    | where msg_s has_all ("Url:","ThreatIntel:")
    | parse-where
        msg_s with           networkProtocol:string 
        " request from "     srcIpAddr:string
        " to "               dstIpAddr:string
    ...
union parseLogs,  parseLogsWithUrls…

Para evitar eventos duplicados e processamento excessivo, certifique-se de que cada função começa por filtrar, utilizando campos nativos, apenas os eventos que pretende analisar. Além disso, se necessário, use o project-away em cada filial, antes da união.

Implantar analisadores

Implante os analisadores manualmente copiando-os para a página de log do Azure Monitor e salvando a consulta como uma função. Este método é útil para testes. Para obter mais informações, confira Criar uma função.

Para implantar um grande número de parsers, recomendamos usar modelos ARM de parser, da seguinte forma:

  1. Crie um arquivo YAML com base no modelo relevante para cada esquema e inclua sua consulta nele. Comece com o modelo YAML relevante para o seu esquema e tipo de analisador, filtragem ou sem parâmetros.

  2. Utilize o conversor de modelos ASIM YAML para ARM para converter o seu ficheiro YAML num modelo do ARM.

  3. Se estiver implantando uma atualização, exclua as versões mais antigas das funções usando o portal ou a ferramenta de exclusão de função do PowerShell.

  4. Implemente o modelo com o portal do Azure ou o PowerShell.

Você também pode combinar vários modelos em um único processo de implantação usando modelos vinculados

Tip

Os modelos do ARM podem combinar recursos diferentes, para que os analisadores possam ser implementados juntamente com conectores, regras analíticas ou listas de observação, para citar algumas opções úteis. Por exemplo, o seu analisador pode referenciar uma lista de observação implementada juntamente com a mesma.

Analisadores de teste

Esta seção descreve as ferramentas de teste que o ASIM fornece e que permitem testar seus analisadores. Dito isto, os analisadores são código, às vezes complexos, e é recomendado complementar práticas padrão de garantia de qualidade, como revisões de código, com testes automatizados.

Instalar ferramentas de teste do ASIM

Para testar o ASIM, implemente a ferramenta de teste ASIM numa área de trabalho Microsoft Sentinel onde:

  • O analisador está implantado.
  • A tabela de origem usada pelo analisador está disponível.
  • A tabela de origem usada pelo analisador é preenchida com uma coleção variada de eventos relevantes.

Validar o esquema de saída

Para se certificar de que o seu analisador produz um esquema válido, utilize o verificador de esquemas ASIM ao executar a seguinte consulta na página Registos do Microsoft Sentinel:

<parser name> | getschema | invoke ASimSchemaTester('<schema>')

Trate os resultados da seguinte forma:

Erro Action
Falta o campo obrigatório [<Campo>] Adicione o campo ao seu analisador. Em muitos casos, esse seria um valor derivado ou um valor constante e não um campo já disponível na fonte.
O campo ausente [<Campo>] é obrigatório quando a coluna obrigatória [<Campo>] existe Adicione o campo ao seu analisador. Em muitos casos, esse campo denota os tipos da coluna existente a que se refere.
O campo ausente [<Campo>] é obrigatório quando a coluna [<Campo>] existe Adicione o campo ao seu analisador. Em muitos casos, esse campo denota os tipos da coluna existente a que se refere.
Alias obrigatório ausente [<Campo>] alias da coluna existente [<Campo>] Adicione o alias ao analisador
Alias recomendado ausente [<Campo>] alias da coluna existente [<Campo>] Adicione o alias ao analisador
Alias opcional ausente [<Campo>] alias da coluna existente [<Campo>] Adicione o alias ao analisador
Alias obrigatório ausente [<Campo>] alias da coluna ausente [<Campo>] Este erro acompanha um erro semelhante para o campo com apelido. Corrija o erro de campo aliasado e adicione esse alias ao analisador.
Tipo incompatível para o campo [<Campo>]. Atualmente, ele é [<Tipo>] e deveria ser [<Tipo>] Certifique-se de que o tipo de campo normalizado esteja correto, normalmente usando uma função de conversão, como tostring.
Informações Action
Campo recomendado ausente [<Campo>] Considere adicionar este campo ao seu analisador.
Informações Action
Alias recomendado ausente [<Campo>] alias da coluna não existente [<Campo>] Se você adicionar o campo com alias ao parser, certifique-se de adicionar esse alias também.
Alias opcional ausente [<Campo>] referenciando a coluna inexistente [<Campo>] Se você adicionar o campo com alias ao parser, certifique-se de adicionar esse alias também.
Campo opcional ausente [<Campo>] Embora os campos opcionais estejam muitas vezes em falta, vale a pena rever a lista para determinar se algum dos campos opcionais pode ser mapeado a partir da origem.
Campo extra não normalizado [<Campo>] Embora os campos não normalizados sejam válidos, vale a pena revisar a lista para determinar se qualquer um dos valores não normalizados pode ser mapeado para um campo opcional.

Note

Os erros impedirão que o conteúdo que utiliza o analisador funcione corretamente. Os avisos não impedirão o funcionamento do conteúdo, mas poderão reduzir a qualidade dos resultados.

Validar os valores de saída

Para garantir que o analisador produza valores válidos, use o testador de dados ASIM executando a seguinte consulta na página Microsoft Sentinel Logs:

<parser name> | limit <X> | invoke ASimDataTester ('<schema>')

A especificação de um esquema é opcional. Se um esquema não for especificado, o campo EventSchema será usado para identificar o esquema ao qual o evento deve aderir. Se um evento não incluir um EventSchema campo, somente campos comuns serão verificados. Se um esquema for especificado como um parâmetro, esse esquema será usado para testar todos os registros. Isso é útil para analisadores mais antigos que não definem o campo EventSchema.

Note

Mesmo quando um esquema não é especificado, parênteses vazios são necessários após o nome da função.

Este teste consome muitos recursos e pode não funcionar em todo o conjunto de dados. Defina X como o maior número para o qual a consulta não expire ou defina o intervalo de tempo da consulta usando o seletor de intervalo de tempo.

Trate os resultados da seguinte forma:

Message Action
(0) Erro: incompatibilidade de tipo para a coluna [<Campo>]. Atualmente, ele é [<Tipo>] e deveria ser [<Tipo>] Certifique-se de que o tipo de campo normalizado esteja correto, normalmente usando uma função de conversão, como tostring.
(0) Erro: valores inválidos (até 10 listados) para o campo [<Campo>] do tipo [<Tipo Lógico>] Certifique-se de que o analisador mapeie o campo de origem correto para o campo de saída. Se mapeado corretamente, atualize o analisador para transformar o valor de origem no tipo, valor ou formato corretos. Consulte a lista de tipos lógicos para obter mais informações sobre os valores e formatos corretos para cada tipo lógico.

Observe que a ferramenta de teste lista apenas uma amostra de 10 valores inválidos.
(1) Aviso: valor vazio no campo obrigatório [<Campo>] Os campos obrigatórios devem ser preenchidos, não apenas definidos. Verifique se o campo pode ser populado de outras fontes para registros para os quais a fonte atual está vazia.
(2) Informações: valor vazio no campo recomendado [<Campo>] Os campos recomendados geralmente devem ser preenchidos. Verifique se o campo pode ser populado de outras fontes para registros para os quais a fonte atual está vazia.
(2) Informações: Valor vazio no campo opcional [<Campo>] Verifique se o campo com alias é obrigatório ou recomendado e, em caso afirmativo, se ele pode ser preenchido de outras fontes.

Muitas das mensagens também comunicam o número de registos que geraram a mensagem e a respetiva percentagem da amostra total. Esse percentual é um bom indicador da importância do problema. Por exemplo, para um campo recomendado:

  • Os valores vazios de 90% podem indicar um problema geral de análise.
  • Os valores vazios de 25% podem indicar uma variante de evento que não foi analisada corretamente.
  • Um punhado de valores vazios pode ser um problema insignificante.

Note

Os erros impedirão que o conteúdo que utiliza o analisador funcione corretamente. Os avisos não impedirão o funcionamento do conteúdo, mas poderão reduzir a qualidade dos resultados.

Contribuir com analisadores

Talvez você queira contribuir com o parser para a distribuição principal do ASIM. Se forem aceites, os analisadores estarão disponíveis para todos os clientes como analisadores incorporados do ASIM.

Para contribuir com seus analisadores:

Documentando avisos aceitos

Se os avisos listados pelas ferramentas de teste do ASIM forem considerados válidos para um analisador, documente os avisos aceitos no arquivo YAML do analisador usando a seção Exceções, conforme mostrado no exemplo abaixo.

Exceptions:
- Field: DnsQuery 
  Warning: Invalid value
  Exception: May have values such as "1164-ms-7.1440-9fdc2aab.3b2bd806-978e-11ec-8bb3-aad815b5cd42" which are not valid domains names. Those are related to TKEY RR requests.
- Field: DnsQuery
  Warning: Empty value in mandatory field
  Exception: May be empty for requests for root servers and for requests for RR type DNSKEY

O aviso especificado no arquivo YAML deve ser uma forma curta da mensagem de aviso que identifica exclusivamente. O valor é usado para corresponder às mensagens de aviso ao executar testes automatizados e ignorá-las.

Diretrizes de envio de amostras

Os dados de amostra são necessários para solucionar problemas do analisador e para garantir que futuras atualizações do analisador estejam em conformidade com amostras mais antigas. Os exemplos que submeter devem incluir qualquer variante de evento suportada pelo analisador. Certifique-se de que os eventos de exemplo incluem todos os tipos de eventos possíveis, formatos de eventos e variações, como eventos que representam atividades com êxito e com falhas. Certifique-se também se as variações nos formatos de valor estão representadas. Por exemplo, se um nome de anfitrião puder ser representado como um FQDN ou um nome de anfitrião simples, os eventos de exemplo devem incluir ambos os formatos.

Para submeter os exemplos de eventos, utilize os seguintes passos:

  • Na tela Logs, execute uma consulta que extrairá da tabela de origem apenas os eventos selecionados pelo analisador. Por exemplo, para o analisador DNS do Infoblox, utilize a seguinte consulta:
    Syslog
    | where ProcessName == "named"

  • Exporte os resultados usando a opção Exportar para CSV para um arquivo chamado <EventVendor>_<EventProduct>_<EventSchema>_IngestedLogs.csv, Onde EventProduct, EventProduct e EventSchema são os valores atribuídos pelo analisador a esses campos.

  • Na tela Logs, execute uma consulta que retorne o esquema ou a tabela de entrada do analisador. Por exemplo, para o mesmo analisador DNS do Infoblox, a consulta é:

    Syslog
    | getschema

  • Exporte os resultados usando a opção Exportar para CSV para um arquivo chamado <TableName>_schema.csv, onde TableName é o nome da tabela de origem que o analisador usa.

  • Inclua ambos os arquivos no seu PR na pasta /Sample Data/ASIM. Se o arquivo já existir, adicione seu identificador de GitHub ao nome, por exemplo: <EventVendor>_<EventProduct>_<EventSchema>_SchemaTest_<GitHubHandle>.csv

Diretrizes de envio de resultados do teste

Os resultados dos testes são importantes para verificar a correção do analisador e compreender qualquer exceção reportada.

Para submeter os resultados do teste, utilize os seguintes passos:

  • Execute os testes do analisador e descreva-os na secção de testes .

  • e exporte os resultados dos testes usando a opção Exportar para CSV para arquivos nomeados <EventVendor>_<EventProduct>_<EventSchema>_SchemaTest.csv e <EventVendor>_<EventProduct>_<EventSchema>_DataTest.csv respectivamente.

  • Inclua ambos os arquivos no seu PR na pasta /Parsers/ASim<schema>/Tests.

Conteúdo relacionado

Saiba mais sobre os analisadores do ASIM:

Saiba mais sobre o ASIM em geral:

  • Last updated on