Transmitir registos para o Microsoft Sentinel com Logstash e a API baseada em DCR

O plug-in de saída do Logstash para o Microsoft Sentinel suporta transformações de pipeline e configuração avançada através de Regras de Recolha de Dados (DCRs). O plug-in reencaminha registos de origens de dados externas para tabelas padrão ou personalizadas no Log Analytics ou Microsoft Sentinel.

Neste artigo, saiba como configurar o plug-in do Logstash para transmitir dados para o Log Analytics ou Microsoft Sentinel com DCRs, com controlo total sobre o esquema de saída.

Com o plug-in, pode:

• Configurar os nomes e tipos das colunas.
• Execute transformações no momento da ingestão, como filtragem ou enriquecimento.
• Importe registos personalizados para uma tabela personalizada ou importe um fluxo de entrada Syslog para a tabela Syslog do Log Analytics.

A ingestão em tabelas padrão está limitada apenas a tabelas padrão suportadas para ingestão de registos personalizados.

Para saber mais sobre como trabalhar com o motor de recolha de dados do Logstash, veja Introdução ao Logstash.

Descrição geral da arquitetura

O motor logstash é composto por três componentes:

• Plug-ins de entrada: recolha personalizada de dados de várias origens.
• Filtrar plug-ins: manipulação e normalização de dados de acordo com critérios especificados.
• Extensões de saída: envio personalizado de dados recolhidos e processados para vários destinos.

O plug-in envia dados formatados em JSON para a área de trabalho do Log Analytics com a API de Ingestão de Registos. Os dados são ingeridos em registos personalizados ou numa tabela padrão.

• Saiba mais sobre a API de ingestão de registos.

Implementar o plug-in de saída do Microsoft Sentinel no Logstash

Para configurar o plug-in, siga estes passos:

• Revise os pré-requisitos do plugin Logstash
• Instalar o plug-in
• Criar um ficheiro de exemplo
• Criar os recursos necessários relacionados com DCR
• Configurar o ficheiro de configuração do Logstash
• Reiniciar Logstash
• Ver registos recebidos no Microsoft Sentinel
• Monitorize os registos de auditoria do plug-in de saída

Pré-requisitos do plug-in logstash

• Instale uma versão suportada do Logstash. O plug-in suporta as seguintes versões do Logstash:

  • 7.0 - 7.17.13

  • 8.0 - 8.9 (estas versões requerem uma atualização de segurança, segundo o Logstash)

  • 8.11 - 8.15 (estas versões requerem uma atualização de segurança, segundo o Logstash)

  • 8.19.2 (esta versão requer uma atualização de segurança, segundo o Logstash)

  • 9.0.8 (esta versão requer uma atualização de segurança, segundo o Logstash)

  • 9.1.10 (esta versão requer uma atualização de segurança, segundo o Logstash)

  • 9.2.4 - 9.2.5 (estas versões requerem uma atualização de segurança, segundo o Logstash)

  • 9.3.3

  • 9.4.0

    Nota

    Se utilizar o Logstash 8, recomendamos que desative o ECS no pipeline.

• Verifique se tem uma área de trabalho do Log Analytics com, pelo menos, direitos de contribuidor.

• Verifique se tem permissões para criar objetos DCR na área de trabalho.

Instalar o plug-in

O plug-in de saída Microsoft Sentinel está disponível na coleção Logstash em RubyGems.

• Siga as instruções no documento do Logstash Trabalhar com plug-ins para instalar o plug-in microsoft-sentinel-log-analytics-logstash-output-plugin. Para instalar numa instalação do Logstash existente, execute o seguinte comando:

  logstash-plugin install microsoft-sentinel-log-analytics-logstash-output-plugin
  

• Se o sistema Logstash não tiver acesso à Internet, siga as instruções no documento Gestão de Plug-ins Offline do Logstash para preparar e utilizar um plug-in offline. (Isto requer a criação de outro sistema Logstash com acesso à Internet.)

Criar um ficheiro de exemplo

Nesta secção, vai criar um ficheiro de exemplo num destes cenários:

• Criar um ficheiro de exemplo para registos personalizados
• Criar um ficheiro de exemplo para ingerir registos na tabela Syslog

Criar um ficheiro de exemplo para registos personalizados

Neste cenário, vai configurar o plug-in de entrada do Logstash para enviar eventos para Microsoft Sentinel. Este exemplo utiliza o plug-in de entrada do gerador para simular eventos. Pode utilizar qualquer outro plug-in de entrada.

Neste exemplo, o ficheiro de configuração do Logstash tem o seguinte aspeto:

input {
      generator {
            lines => [
                 "This is a test log message"
            ]
           count => 10
      }
}

Para criar o ficheiro de exemplo, siga estes passos:

1. Copie a configuração do plug-in de saída abaixo para o ficheiro de configuração do Logstash.

   output {
       microsoft-sentinel-log-analytics-logstash-output-plugin {
         create_sample_file => true
         sample_file_path => "<enter the path to the file in which the sample data will be written>" #for example: "c:\\temp" (for windows) or "/tmp" for Linux. 
       }
   }
   

2. Certifique-se de que o caminho do ficheiro referenciado já existe e, em seguida, inicie o Logstash.

   O plug-in escreve dez registos num ficheiro de exemplo com o nome sampleFile<epoch seconds>.json no caminho configurado assim que existirem 10 eventos para amostrar ou quando o processo do Logstash sair corretamente. Por exemplo: c:\temp\sampleFile1648453501.json. Eis uma parte de um ficheiro de exemplo que o plug-in cria:

   [
           {
               "host": "logstashMachine",
               "sequence": 0,
               "message": "This is a test log message",
               "ls_timestamp": "2022-03-28T17:45:01.690Z",
               "ls_version": "1"
           },
           {
               "host": "logstashMachine",
               "sequence": 1
       ...
   
       ]    
   

   O plug-in adiciona automaticamente estas propriedades a todos os registos:

   • ls_timestamp: a hora em que o registo é recebido do plug-in de entrada
   • ls_version: a versão do pipeline do Logstash.

   Pode remover estes campos quando criar o DCR.

Criar um ficheiro de exemplo para ingerir registos na tabela Syslog

Neste cenário, vai configurar o plug-in de entrada do Logstash para enviar eventos do syslog para Microsoft Sentinel.

1. Se ainda não tiver mensagens syslog reencaminhadas para o seu computador Logstash, pode utilizar o comando logger para gerar mensagens. Por exemplo (para Linux):

   logger -p local4.warn --rfc3164 --tcp -t CEF "0|Microsoft|Device|cef-test|example|data|1|here is some more data for the example" -P 514 -d -n 127.0.0.1
   

   Eis um exemplo do plug-in de entrada do Logstash:

   input {
        syslog {
            port => 514
       }
   }
   

2. Copie a configuração do plug-in de saída abaixo para o ficheiro de configuração do Logstash.

   output {
       microsoft-sentinel-log-analytics-logstash-output-plugin {
         create_sample_file => true
         sample_file_path => "<enter the path to the file in which the sample data will be written>" #for example: "c:\\temp" (for windows) or "/tmp" for Linux. 
       }
   }
   

3. Certifique-se de que o caminho do ficheiro já existe e, em seguida, inicie o Logstash.

   O plug-in escreve dez registos num ficheiro de exemplo com o nome sampleFile<epoch seconds>.json no caminho configurado assim que existirem 10 eventos para amostrar ou quando o processo do Logstash sair corretamente. Por exemplo: c:\temp\sampleFile1648453501.json. Eis uma parte de um ficheiro de exemplo que o plug-in cria:

   [
           {
               "logsource": "logstashMachine",
               "facility": 20,
               "severity_label": "Warning",
               "severity": 4,
               "timestamp": "Apr  7 08:26:04",
               "program": "CEF:",
               "host": "127.0.0.1",
               "facility_label": "local4",
               "priority": 164,
               "message": "0|Microsoft|Device|cef-test|example|data|1|here is some more data for the example",
               "ls_timestamp": "2022-04-07T08:26:04.000Z",
               "ls_version": "1"
           }
   ]    
   
   

   O plug-in adiciona automaticamente estas propriedades a todos os registos:

   • ls_timestamp: a hora em que o registo é recebido do plug-in de entrada
   • ls_version: a versão do pipeline do Logstash.

   Pode remover estes campos quando criar o DCR.

Criar os recursos DCR necessários

Para configurar o plug-in do Logstash baseado em DCR do Microsoft Sentinel, crie primeiro os recursos relacionados com a DCR.

Nesta secção, vai criar recursos para utilizar para o DCR, num destes cenários:

• Criar recursos DCR para ingestão numa tabela personalizada
• Criar recursos DCR para ingestão numa tabela padrão

Criar recursos DCR para ingestão numa tabela personalizada

Para ingerir os dados numa tabela personalizada, siga estes passos (com base no tutorial Enviar dados para Azure Monitorizar Registos com a API REST (portal do Azure):

1. Veja os pré-requisitos.

2. Configure a aplicação.

3. Adicionar uma tabela de registo personalizada.

4. Analise e filtre dados de exemplo com o ficheiro de exemplo que criou na secção anterior.

5. Recolha informações do DCR.

6. Atribua permissões ao DCR.

   Ignore o passo Enviar dados de exemplo.

Se encontrar algum problema, consulte os passos de resolução de problemas da API de Ingestão de Logs.

Criar recursos DCR para ingestão numa tabela padrão

Para ingerir os dados numa tabela padrão, como Syslog ou CommonSecurityLog, utiliza um processo baseado no tutorial Enviar dados para os Registos do Azure Monitor com a API REST (modelos do Resource Manager). Embora o tutorial explique como ingerir dados numa tabela personalizada, pode ajustar facilmente o processo para ingerir dados numa tabela padrão. Os passos abaixo indicam alterações relevantes nos passos.

1. Veja os pré-requisitos.

2. Recolha os detalhes da área de trabalho.

3. Configurar uma aplicação.

   Ignore o passo Criar nova tabela na área de trabalho do Log Analytics. Este passo não é relevante ao ingerir dados numa tabela padrão, porque a tabela já está definida no Log Analytics.

4. Crie o DCR. Neste passo:

   • Fornece o ficheiro de exemplo que criaste em Criar um ficheiro de exemplo.
   • Utilize o ficheiro de exemplo que criou para definir a streamDeclarations propriedade . Cada um dos campos no ficheiro de exemplo deve ter uma coluna correspondente com o mesmo nome e o tipo adequado (veja o exemplo abaixo).
   • Configure o valor da outputStream propriedade com o nome da tabela padrão em vez da tabela personalizada. Ao contrário das tabelas personalizadas, os nomes de tabelas padrão não têm o _CL sufixo.
   • O prefixo do nome da tabela deve ser Microsoft- em vez de Custom-. Neste exemplo, o valor da outputStream propriedade é Microsoft-Syslog.

5. Atribua permissões a um DCR.

   Ignore o passo Enviar dados de exemplo.

Se encontrar algum problema, consulte os passos de resolução de problemas da API de Ingestão de Logs.

Exemplo: DCR que ingere dados na tabela Syslog

Tenha estes pontos em mente:

• Os streamDeclarations nomes e tipos de coluna devem ser os mesmos que os campos de ficheiro de exemplo, mas não tem de especificar todos. Por exemplo, no DCR abaixo, os campos PRI, type e ls_version são omitidos da coluna streamDeclarations.
• A dataflows propriedade transforma a entrada no formato de tabela do Syslog e define o outputStream para Microsoft-Syslog.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "dataCollectionRuleName": {
      "type": "String",
      "metadata": {
        "description": "Specifies the name of the Data Collection Rule to create."
      }
    },
    "location": {
      "defaultValue": "[resourceGroup().location]",
      "type": "String",
      "metadata": {
        "description": "Specifies the location in which to create the Data Collection Rule."
      }
    },
    "workspaceResourceId": {
      "type": "String",
      "metadata": {
        "description": "Specifies the Azure resource ID of the Log Analytics workspace to use."
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.Insights/dataCollectionRules",
      "apiVersion": "2021-09-01-preview",
      "name": "[parameters('dataCollectionRuleName')]",
      "location": "[parameters('location')]",
      "properties": {
        "streamDeclarations": {
          "Custom-SyslogStream": {
            "columns": [
              { "name": "ls_timestamp", "type": "datetime" },
              { "name": "timestamp", "type": "datetime" },
              { "name": "message", "type": "string" },
              { "name": "facility_label", "type": "string" },
              { "name": "severity_label", "type": "string" },
              { "name": "host", "type": "string" },
              { "name": "logsource", "type": "string" }
            ]
          }
        },
        "destinations": {
          "logAnalytics": [
            {
              "workspaceResourceId": "[parameters('workspaceResourceId')]",
              "name": "clv2ws1"
            }
          ]
        },
        "dataFlows": [
          {
            "streams": ["Custom-SyslogStream"],
            "destinations": ["clv2ws1"],
            "transformKql": "source | project TimeGenerated = ls_timestamp, EventTime = todatetime(timestamp), Computer = logsource, HostName = logsource, HostIP = host, SyslogMessage = message, Facility = facility_label, SeverityLevel = severity_label",
            "outputStream": "Microsoft-Syslog"
          }
        ]
      }
    }
  ],
  "outputs": {
    "dataCollectionRuleId": {
      "type": "String",
      "value": "[resourceId('Microsoft.Insights/dataCollectionRules', parameters('dataCollectionRuleName'))]"
    }
  }
}

Configurar o ficheiro de configuração do Logstash

O plug-in suporta dois métodos de autenticação: principal de serviço (credenciais de cliente) e identidade gerida (sem palavra-passe). Escolha o método que se adequa ao seu ambiente.

Autenticação do principal de serviço

Para configurar o ficheiro de configuração Logstash para ingerir os registos numa tabela personalizada usando autenticação de principal de serviço, recupere os seguintes valores: client_id, client_secret, tenant_id, data_collection_endpoint, dcr_id, e stream_name.

Depois de obter os valores necessários:

1. Substitua a secção de saída do ficheiro de configuração logstash que criou no passo anterior pelo exemplo abaixo.
2. Substitua as cadeias de caracteres de marcador de posição no exemplo abaixo pelos valores que recuperou.
3. Certifique-se de que altera o create_sample_file atributo para false.

Exemplo: Configuração do plug-in de saída do principal de serviço

output {
    microsoft-sentinel-log-analytics-logstash-output-plugin {
      client_id => "<enter your client_id value here>"
      client_secret => "<enter your client_secret value here>"
      tenant_id => "<enter your tenant id here>"
      data_collection_endpoint => "<enter your logsIngestion URI here>"
      dcr_id => "<enter your DCR immutableId here>"
      stream_name => "<enter your stream name here>"
      create_sample_file=> false
      sample_file_path => "c:\\temp"
    }
}

Autenticação de identidade gerida (sem palavra-passe)

Quando não fornece credenciais de principal de serviço (client_id, , e tenant_id), o plugin autentica-se usando DefaultAzureCredential a partir do client_secretSDK do Azure. DefaultAzureCredential Tenta uma sequência de métodos de autenticação e usa o primeiro que tem sucesso. Num ambiente de servidor, os métodos relevantes são tentados nesta ordem:

1. Variáveis de ambiente: Lê credenciais de variáveis de ambiente como AZURE_CLIENT_ID, AZURE_TENANT_ID, e AZURE_CLIENT_SECRET para autenticar como um principal de serviço.
2. Identidade da carga de trabalho: Se o plugin correr num host Azure com a identidade da carga de trabalho ativada (por exemplo, AKS com a AZURE_FEDERATED_TOKEN_FILE variável de ambiente definida), o plugin realiza uma troca de tokens OIDC.
3. Identidade gerida: Se o anfitrião tiver uma identidade gerida ativada, o plugin autentica-se usando essa identidade. Este método abrange VMs do Azure, Conjuntos de Dimensionamento de Máquinas Virtuais e servidores habilitados pelo Azure Arc.

Para a sequência completa de credenciais que DefaultAzureCredential tenta, veja Cadeias de credenciais na biblioteca Azure Identity for Java.

Configuração necessária para a identidade gerida:

Exemplo: Identidade gerida

output {
    microsoft-sentinel-log-analytics-logstash-output-plugin {
      data_collection_endpoint => "<enter your DCE logsIngestion URI here>"
      dcr_id => "<enter your DCR immutableId here>"
      stream_name => "<enter your stream name here>"
    }
}

Configuração opcional

Reiniciar Logstash

Reinicie o Logstash com a configuração atualizada do plug-in de saída. Verifique se os dados são ingeridos na tabela correta de acordo com a configuração do DCR.

Ver registos recebidos no Microsoft Sentinel

Para verificar se os dados de registo chegam à área de trabalho, siga estes passos:

1. Verifique se as mensagens estão a ser enviadas para o plug-in de saída.

2. No menu de navegação Microsoft Sentinel, selecione Registos. No cabeçalho Tabelas , expanda a categoria Registos Personalizados . Localize e selecione o nome da tabela que especificou (com um _CL sufixo) na configuração.

   

3. Para ver registos na tabela, consulte a tabela com o nome da tabela como esquema.

   

Monitorize os registos de auditoria do plug-in de saída

Para monitorizar a conectividade e a atividade do plug-in de saída do Microsoft Sentinel, ative o ficheiro de registo do Logstash adequado. Veja o documento Esquema de Diretório do Logstash para a localização do ficheiro de registo.

Se não vir dados neste ficheiro de registo, gere e envie alguns eventos localmente através dos plug-ins de entrada e filtro para se certificar de que o plug-in de saída está a receber dados. Microsoft Sentinel suporta apenas problemas relacionados com o plug-in de saída.

Segurança de rede

Defina as definições de rede e ative o isolamento de rede para o plug-in de saída do Microsoft Sentinel Logstash.

Etiquetas de serviço de rede virtual

O plug-in de saída do Microsoft Sentinel suporta etiquetas de serviço de rede virtual do Azure. São necessárias etiquetas AzureMonitor e AzureActiveDirectory .

As etiquetas de serviço da Rede Virtual do Azure podem ser utilizadas para definir controlos de acesso de rede em grupos de segurança de rede, Azure Firewall e rotas definidas pelo utilizador. Utilize etiquetas de serviço em vez de endereços IP específicos quando criar regras e rotas de segurança. Para cenários em que não é possível utilizar Azure Rede Virtual etiquetas de serviço, os requisitos da firewall são indicados abaixo.

Requisitos da firewall

A tabela seguinte lista os requisitos de firewall para cenários em que não é possível utilizar Azure etiquetas de serviço de rede virtual.

Histórico de versões do plug-in

2.5.0

• Adicionada configuração opcional de proxy por plugin para tráfego de autenticação e ingestão usando proxy, proxy_aad, e proxy_endpoint.
• Atualizados os componentes do handler Netty, HTTP, HTTP/2 e DNS de 4.1.133.Final para 4.1.136.Final.
• Atualizado o Jackson Databind e o Jackson Core de 2.18.6 para 2.18.8.

2.4.0

• As threads de trabalho passam agora a executar iterações limitadas, programadas pelo executor: as exceções recuperáveis são registadas e a thread retoma a execução no ciclo seguinte; os erros fatais da JVM são registados e relançados.
• Corrigido o encerramento ordeiro para que os lotes em curso sejam escoados (agrupadores, depois unificadores e depois remetentes) antes de os trabalhadores pararem, dentro do limite de max_graceful_shutdown_time_seconds.
• Adicionados tempos limite de carregamento configuráveis connect_timeout_seconds (predefinição: 15) e write_timeout_seconds (predefinição: 60); as tentativas com tempos limite de ligação e de escrita são repetidas.
• Adicionei ID de thread, tipo de exceção, tamanho de lote e fluxo DCR aos registos de falhas de lote.

2.3.3

• Corrigida a perda de fidelidade dos tipos numéricos e booleanos: os campos associados aos tipos internos JRuby do Logstash (por exemplo, portas e contagens de bytes) são agora preservados como números e booleanos JSON nativos, em vez de serem convertidos em cadeias de caracteres, garantindo uma ingestão fiável nos DCRs com colunas tipadas.

2.3.2

• Corrigida a morte silenciosa da thread de trabalho causada por exceções não capturadas no ciclo de processamento da thread de trabalho.
• Corrigido o NullPointerException no SenderWorker quando o Azure devolve um LogsUploadException com uma resposta HTTP nula.
• Adicionou um tratamento resiliente de erros com rastreamento consecutivo de erros para reduzir a falha permanente dos trabalhadores.
• Valor de configuração opcional id adicionado para telemetria.
• Adicionei fluxo DCR ao registo de lotes enviados.

2.3.0

• Funcionalidade ativada com o Logstash 9.4.
• Versões de dependência removidas para bibliotecas externas (azure-sdk-bom, logback, slf4j, Netty).

2.2.1

• Adiciona uma linha de registo ao nível da informação quando os lotes são enviados com sucesso.

2.2.0

• Adiciona a possibilidade de usar valores de configuração novos ou antigos.

2.1.2

• Atualizações da documentação.

2.1.0

• Correção da normalização de eventos.

2.0.0

• Refatorizar o plug-in de Ruby para Java.
• Adicionada a autenticação com identidade gerida.
• Moveu a base de código do GitHub para Azure DevOps.
• Base de código fechada.

1.2.0

• Adiciona suporte para autenticação com identidade gerida para VMs/VMSS do Azure (identidade atribuída pelo sistema e identidade atribuída pelo utilizador através do IMDS).
• Adiciona suporte de identidade de carga de trabalho do AKS através da troca de tokens OIDC.
• Adiciona suporte para identidade gerida do Azure Arc em servidores híbridos e no local.
• Deteta automaticamente o método de autenticação em tempo de execução com base no ambiente (variáveis de ambiente de identidade da carga de trabalho, agente Arc ou recurso ao IMDS).
• Migra o cliente HTTP de excon para rest-client para melhorar a compatibilidade com o ecossistema de plug-ins do JRuby e do Logstash.
• Altera as referências a Azure Active Directory para Microsoft Entra ID.

1.1.4

• Limita excon a versão da biblioteca a uma versão inferior a 1.0.0 para garantir que a porta é sempre utilizada ao utilizar um proxy.

1.1.3

• Substitui a rest-client biblioteca utilizada para ligar a Azure pela excon biblioteca.

1.1.1

• Adiciona suporte para Azure cloud do Governo dos EUA e microsoft Azure operado pela 21Vianet na China.

1.1.0

• Permite definir diferentes valores de proxy para ligações de API.
• Atualiza a versão da API de ingestão de registos para 2023-01-01.
• Muda o nome do plug-in para microsoft-sentinel-log-analytics-logstash-output-plugin.

1.0.0

• A primeira versão do plug-in de saída do Logstash para o Microsoft Sentinel. Este plug-in utiliza Regras de Recolha de Dados (DCRs) com a API de Ingestão de Registos do Azure Monitor.

Problemas conhecidos

Ao utilizar o Logstash instalado numa imagem do Docker do Lite Ubuntu, poderá ser apresentado o seguinte aviso:

java.lang.RuntimeException: getprotobyname_r failed

Para resolver este erro, instale o pacote netbase no dockerfile:

USER root
RUN apt install netbase -y

Para obter mais informações, veja Regressão JNR no Logstash 7.17.0 (Docker).

Se a taxa de eventos do seu ambiente for baixa, aumente o valor de max_waiting_time_for_batch_seconds e max_waiting_for_unifier_time_seconds para 60 ou mais. Pode monitorizar a carga útil de ingestão utilizando métricas DCR. Para mais informações sobre as variáveis de tempo de espera, consulte a tabela de configuração Opcional .

Limitações

• A ingestão em tabelas padrão está limitada apenas a tabelas padrão suportadas para ingestão de registos personalizados.

• As colunas do fluxo de entrada na streamDeclarations propriedade têm de começar com uma letra. Se iniciar uma coluna com outros carateres (por exemplo @ , ou _), a operação falhará.

• O TimeGenerated campo datetime é obrigatório. Tem de incluir este campo na transformação KQL.

• Para possíveis problemas adicionais, consulte os passos de resolução de problemas da API de Ingestão de Logs.