Compartilhar via

Desenvolva analisadores do ASIM (Modelo de Informações de Segurança Avançado) (Visualização pública)

  • Artigo

Os usuários do ASIM (Modelo de Informações de Segurança Avançado) usam analisadores unificados em vez de nomes de tabela em suas consultas, para exibir dados em um formato normalizado e incluir todos os dados relevantes para o esquema na consulta. A unificação de analisadores, por sua vez, usa analisadores específicos da fonte para lidar com os detalhes específicos de cada fonte.

O Microsoft Sentinel fornece analisadores integrados e específicos 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.

    • Seu dispositivo pode ter uma versão diferente da que é compatível com o analisador ASIM.

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

Para entender como os analisadores se encaixam na arquitetura do ASIM, consulte o diagrama de arquitetura do ASIM.

Importante

O ASIM está atualmente em VERSÃO PRÉVIA. Os termos suplementares de versão prévia do Azure incluem termos legais adicionais que se aplicam aos recursos do Azure que estão em versão beta, versão prévia ou que, de outra forma, ainda não foram lançados em disponibilidade geral.

Processo de desenvolvimento do analisador ASIM personalizado

O fluxo de trabalho a seguir descreve as etapas de alto nível no desenvolvimento de um analisador personalizado do ASIM, 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, consulte Visã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 do ASIM relevante para referenciar o novo analisador personalizado. Para obter mais informações, confira como gerenciar analisadores do ASIM.

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

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

Dica

Assista também ao webinar de aprofundamento no Microsoft Sentinel: Normalizando analisadores e conteúdo normalizado ou veja os slides relacionados. Para saber mais, confira as Próximas etapas.

Coletar logs de exemplo

Para criar analisadores do ASIM eficazes, você precisa de um conjunto representativo de logs, o que, na maioria das vezes, exigirá a configuração do sistema de origem e a conexão com o Microsoft Sentinel. Se você não tiver o dispositivo de origem disponível, os serviços de pagamento em nuvem conforme o uso permitirão implantar muitos dispositivos para o desenvolvimento e teste.

Além disso, encontrar a documentação e os exemplos do fornecedor para os logs pode ajudar a acelerar o desenvolvimento e reduzir erros, garantindo ampla cobertura de formato de log.

Um conjunto representativo de logs deve incluir:

  • Eventos com resultados de eventos diferentes.
  • Eventos com diferentes ações de resposta.
  • Formatos diferentes para nome de usuário, nome de host e IDs e outros campos que exigem normalização de valor.

Dica

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 valores para campos na origem para os valores normalizados permitidos pelo o ASIM. O valor original é armazenado em um 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 Logs do Microsoft Sentinel. A consulta do analisador tem três partes:

Filtrar>Analisar>Preparar campos

Filtragem

Filtragem de registros 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 não deve filtrar por tempo. A consulta que usa 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. Nesses casos, o analisador depende de uma lista de origens que definem os eventos relevantes. Essa lista é mantida na watchlist Sources_by_SourceType.

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

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

Para usar este exemplo no analisador:

  • Substitua Computer pelo nome do campo que inclui as informações de origem para sua origem. 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 do analisador

Ao desenvolver analisadores de filtragem, o analisador deve aceitar os parâmetros de filtragem para o esquema relevante, conforme documentado no artigo de referência desse esquema. O uso de um analisador existente como ponto de partida garante que o analisador inclua a assinatura de função correta. Na maioria dos casos, o código de filtragem real também é semelhante para filtrar analisadores para o mesmo esquema.

Ao filtrar, lembre-se de:

  • 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 padrão.

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)

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.
  • Use operadores que forneçam desempenho otimizado. Especialmente ==, has e startswith. O uso de operadores como contains ou matches regex também afeta bastante o desempenho.

Nem sempre é fácil seguir as recomendações de filtragem para melhorar o desempenho. Por exemplo, usar has é menos preciso do que contains. Em outros casos, corresponder o campo integrado, como SyslogMessage, é menos preciso 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"

Observação

Os analisadores não devem filtrar por tempo, pois a consulta que está usando o analisador já filtra por 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 são transmitidos em um ú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, e o último fornece o desempenho menos otimizado.

Operador Descrição
split Analisar uma cadeia de caracteres de valores delimitados.
parse_csv Analisar uma cadeia de caracteres de valores formatados como uma linha CSV (valores separados por vírgula).
parse-kv Extrai informações estruturadas de uma expressão de cadeia de caracteres e representa as informações em um formulário chave/valor.
parse Analisar vários valores de uma cadeia de caracteres arbitrária usando um padrão, que pode ser um padrão simplificado com melhor desempenho ou uma expressão regular.
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.
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.
parse_json Analisar os valores de uma cadeia de caracteres formatada como JSON. Quando apenas alguns valores de JSON são necessários, usar parse, extract ou extract_all melhora o desempenho.
parse_xml Analisar os valores em uma cadeia de caracteres formatada como XML. Quando apenas alguns valores do XML são necessários, usar parse, extract ou extract_all melhora o desempenho.

Normalização

Nomes de campo de mapeamento

A maneira mais simples de normalização é renomear o campo original com o respectivo nome normalizado. Use o operador project-rename para fazer isso. O uso da renomeação de projeto permite que o campo ainda seja gerenciado como um campo físico e melhor o desempenho ao gerenciar o campo. Por exemplo:

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

Normalizando 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 amplo conjunto de funções de data, numéricas e de cadeia de caracteres da KQL.

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 nesses casos.

Por exemplo, a ID de evento exclusiva original pode ser enviada como um inteiro, mas o ASIM requer que o valor seja uma cadeia de caracteres, para garantir uma ampla compatibilidade entre as fontes 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 o lookup e case. O lookup exemplo acima retornará um valor vazio no campo DnsResponseCodeName se o valor da pesquisa não for encontrada. O case exemplo a seguir aumenta-o usando o resultado da operação lookup, se disponível, e especificando outras condições caso contrário.

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

O Microsoft Sentinel fornece funções úteis para valores comuns de pesquisa. 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. 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 de funções de ajuda do ASIM, confira as funções do 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', '')

O Microsoft Sentinel fornece funções úteis para gerenciar 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:

Campo do computador Campos de saída
Server1 SrcHostname: server1
SrcDomain, SrcDomainType, SrcFQDN todos vazios
server1.microsoft.com SrcHostname: server1
SrcDomain: microsoft.com
SrcDomainType: FQDN
SrcFQDN:server1.microsoft.com

As funções _ASIM_ResolveDstFQDN e _ASIM_ResolveDvcFQDN executam uma tarefa semelhante preenchendo os campos Dst e Dvc relacionados. Para obter uma lista completa de funções de ajuda do ASIM, confira as funções do 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 adicionar clareza evitando 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 Descrição Quando usar em um analisador
project-away Remove 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.
project 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 uso em um analisador, porque ele não removerá os outros campo que não estiverem normalizados.

Se você precisar remover campos específicos, como valores temporários usados durante a análise, use project-away para removê-los 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

Tratar variantes de análise

Importante

As variantes diferentes representam tipos de evento diferentes, normalmente mapeados para diferentes esquemas, desenvolver analisadores separados

Em muitos casos, os eventos de um fluxo de eventos incluem variantes que exigem 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.

Ao usar union para lidar com várias variantes, crie uma função separada para cada variante e use 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, verifique se cada função começa pela filtragem, usando campos nativos, apenas os eventos que se destina a analisar. Além disso, se necessário, use o project-away em cada filial, antes da união.

Implantar analisadores

Implante analisadores manualmente copiando-os na página de Log do Azure Monitor. Depois, salve 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 analisadores, é recomendável usar modelos ARM do analisador, 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 tipo de esquema e analisador, filtragem ou sem parâmetro.

  2. Use o conversor de ASIM YAML para modelo ARM para converter o arquivo YAML em um modelo 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. Implante seu modelo usando 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

Dica

Os modelos ARM podem incluir recursos diferentes, para que seus analisadores sejam implantados com conectores, regras de análise ou watchlists, entre outras opções úteis. Por exemplo, o analisador pode referenciar uma watchlist implantada com ele.

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ódigos, às vezes complexos e práticas padrão de garantia de qualidade, como revisões de código, são recomendados, além de testes automatizados.

Instalar ferramentas de teste do ASIM

Para testar o ASIM, implante a ferramenta de teste do ASIM em um workspace do Microsoft Sentinel em que:

  • 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 garantir que o analisador produza um esquema válido, use o testador de esquema ASIM executando a seguinte consulta na página Logs do Microsoft Sentinel:

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

Manipule os resultados da seguinte forma:

Erro Ação
Campo obrigatório ausente [<Campo>] Adicione o campo ao 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 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 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>] Esse erro acompanha um erro semelhante para o campo com alias. Corrija o erro de campo com alias 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.
Info Ação
Campo recomendado ausente [<Campo>] Considere adicionar esse campo ao analisador.
Info Ação
Alias recomendado ausente [<Campo>] alias da coluna não existente [<Campo>] Se você adicionar o campo com alias ao analisador, adicione esse alias também.
Alias opcional ausente [<Campo>] alias da coluna não existente [<Campo>] Se você adicionar o campo com alias ao analisador, adicione esse alias também.
Campo opcional ausente [<Campo>] Embora os campos opcionais geralmente estejam ausentes, vale a pena revisar a lista para determinar se qualquer um dos campos opcionais pode ser mapeado da fonte.
Campo não normalizado extra [<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.

Observação

Os erros impedirão que o conteúdo que usa 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 Logs do Microsoft Sentinel:

<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. Por exemplo, um evento não inclui um campo EventSchema; 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.

Observação

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

Esse teste faz uso intensivo de recursos e pode não funcionar em todo o conjunto de dados. Defina X para o maior número para o qual a consulta não atinja o tempo limite ou defina o intervalo de tempo para a consulta usando o selador de intervalo de tempo.

Manipule os resultados da seguinte forma:

Mensagem Ação
(0) Erro: tipo incompatível 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 correto. 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 relatam o número de registros que geraram a mensagem e sua porcentagem do exemplo total. Esse percentual é um bom indicador da importância do problema. Por exemplo, para um campo recomendado:

  • Valores 90% vazios 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.

Observação

Os erros impedirão que o conteúdo que usa 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 analisador para a distribuição primária do ASIM. Se aceito, os analisadores estarão disponíveis para todos os clientes como analisadores internos 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. As amostras enviadas devem incluir qualquer variante de evento que tenha suporte do analisador. Certifique-se de que os eventos de amostra incluam todos os tipos de eventos possíveis, formatos de eventos e variações, como eventos que representam atividades bem-sucedidas e com falha. Certifique-se também se as variações nos formatos de valor estão representadas. Por exemplo, se um nome do host puder ser representado como um FQDN ou um nome do host simples, os eventos de amostra deverão incluir ambos os formatos.

Para enviar as amostras de eventos, use as seguintes etapas:

  • 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, use 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 produzirá 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 em sua PR na pasta /Sample Data/ASIM. Se o arquivo já existir, adicione seu identificador do GitHub ao nome, por exemplo: <EventVendor>_<EventProduct>_<EventSchema>_SchemaTest_<GitHubHanlde>.csv

Diretrizes de envio de resultados do teste

Os resultados do teste são importantes para verificar a exatidão do analisador e entender qualquer exceção relatada.

Para enviar os resultados do teste, use as seguintes etapas:

  • Execute os testes do analisador descritos na seçã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 em sua PR na pasta /Parsers/ASim<schema>/Tests.

Próximas etapas

Este artigo aborda o desenvolvimento de analisadores do ASIM.

Saiba mais sobre analisadores do ASIM:

Saiba mais sobre o ASIM em geral: