Enviar logs para o Microsoft Sentinel com Logstash e API baseada em DCR

O plugin de saída do Logstash do Microsoft Sentinel oferece suporte a transformações de pipeline e configurações avançadas por meio das Regras de Coleta 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:

• Controle a configuração dos nomes e tipos das colunas.
• Realize transformações no momento da ingestão, como filtragem ou enriquecimento.
• Ingerir logs personalizados em uma tabela personalizada ou ingerir um fluxo de entrada do Syslog na 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.

Visã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.
• Plugins de saída: envio personalizado de dados coletados 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 a DCR
• Configurar o ficheiro de configuração do Logstash
• Reiniciar Logstash
• Exibir logs recebidos no Microsoft Sentinel
• Monitorar logs 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 (essas versões exigem uma atualização de segurança, segundo o Logstash)

  • 8.11 - 8.15 (essas versões exigem 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 (essas versões exigem atualização de segurança, segundo o Logstash)

  • 9.3.3

  • 9.4.0

    Observação

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

• Verifique se você tem uma área de trabalho do Log Analytics com pelo menos permissões de Colaborador.

• 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 Trabalhando 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 plugin grava dez registros em um arquivo de amostra chamado sampleFile<epoch seconds>.json no caminho configurado assim que houver 10 eventos para amostragem ou quando o processo do Logstash for encerrado de forma ordenada. 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: o horário em que o registro é recebido do plugin 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
   

   Aqui está um exemplo do plug-in de input 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 plugin grava dez registros em um arquivo de amostra chamado sampleFile<epoch seconds>.json no caminho configurado assim que houver 10 eventos para amostragem ou quando o processo do Logstash for encerrado de forma ordenada. 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: o horário em que o registro é recebido do plugin 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, primeiro crie os recursos relacionados ao 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. Analise 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 você encontrar algum problema, consulte os passos de solução de problemas da API de Ingestão de Logs.

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

Para ingerir os dados para uma tabela padrão, como Syslog ou CommonSecurityLog, use um processo baseado no tutorial Enviar dados para os Logs do Azure Monitor usando 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. Analise 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:

   • Forneça o arquivo de exemplo que você criou em Criar um arquivo 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 você encontrar algum problema, consulte os passos de soluçã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 na 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 definir os parâmetros do arquivo de configuração Logstash para ingerir os logs em uma tabela personalizada usando autenticação de entidade 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 espaço reservado no exemplo abaixo pelos valores recuperados.
3. Certifique-se de que altera o create_sample_file atributo para false.

Exemplo: configuração do plug-in de saída da entidade 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 você não fornece credenciais da entidade de serviço (client_id, tenant_id e DefaultAzureCredential), o plugin se autentica usando client_secret do SDK do Azure. DefaultAzureCredential tenta uma sequência de métodos de autenticação e usa o primeiro que tem sucesso. Em um 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 roda em um host Azure com identidade de 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 gerenciada: Se o host tiver uma identidade gerenciada ativada, o plugin autentica usando essa identidade. Esse método abrange VMs Azure, Conjuntos de Dimensionamento de Máquinas Virtuais e servidores habilitados para 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 gerenciada

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.

Exibir logs 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.

   

Monitorar logs 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 você não estiver vendo nenhum dado neste arquivo de log, gere e envie alguns eventos localmente usando os plugins de entrada e de filtro para garantir que o plugin de saída esteja recebendo 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 oferece suporte a marcas de serviço da rede virtual do Azure. São necessárias etiquetas AzureMonitor e AzureActiveDirectory .

As tags de serviço da Rede Virtual do Azure podem ser usadas para definir controles de acesso à rede em grupos de segurança de rede, Firewall do Azure e rotas definidas pelo usuário. 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 de 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 para cada plug-in para tráfego de autenticação e ingestão usando proxy, proxy_aad e proxy_endpoint.
• Atualizados o handler do Netty, o HTTP, o HTTP/2 e os componentes de DNS da versão 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

• Threads de trabalho agora são executadas como execuções limitadas, agendadas pelo executor: exceções recuperáveis são registradas em log, e a thread retoma a execução no próximo ciclo; erros fatais da JVM são registrados em log e relançados.
• Corrigido o encerramento normal para que os lotes em processamento sejam drenados (batchers, depois unificadores e, em seguida, remetentes) antes de os trabalhadores pararem, com limite de max_graceful_shutdown_time_seconds.
• Foram adicionados tempos limite de upload configuráveis connect_timeout_seconds (padrão 15) e write_timeout_seconds (padrão 60); as tentativas com timeout de conexão e de gravação são refeitas.
• Adicionados ID de thread, tipo de exceção, tamanho de lote e fluxo DCR aos logs de falha de lote.

2.3.3

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

2.3.2

• Corrigida a morte do thread de trabalhador silencioso causada por exceções não detectadas no ciclo de processamento do trabalhador.
• Corrigido o NullPointerException no SenderWorker quando o Azure retorna um LogsUploadException com uma resposta HTTP nula.
• Adicionou o manejo resiliente de erros com rastreamento consecutivo de erros para reduzir falhas permanentes dos trabalhadores.
• Adicionei valor opcional id de configuração para telemetria.
• Adicionado fluxo DCR ao log 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 registro em nível de informação quando lotes são enviados com sucesso.

2.2.0

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

2.1.2

• Atualizações de documentação.

2.1.0

• Corrigida a normalização de eventos.

2.0.0

• O plugin foi refatorado de Ruby para Java.
• Adicionada a autenticação ManagedIdentity.
• Moveu a base de código do GitHub para Azure DevOps.
• Base de código fechada.

1.2.0

• Adiciona suporte à autenticação com identidade gerenciada para VMs/VMSS do Azure (atribuídas pelo sistema e atribuídas pelo usuário via IMDS).
• Adiciona suporte à identidade de carga de trabalho do AKS via troca de token OIDC.
• Adiciona suporte à identidade gerenciada do Azure Arc para servidores híbridos e locais.
• Detecta 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 fallback do IMDS).
• Migra o cliente HTTP de excon para rest-client para maior compatibilidade com o ecossistema de plug-ins do JRuby e do Logstash.
• Renomeia as referências ao 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 versão inicial do plug-in de saída do Logstash para 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 do max_waiting_time_for_batch_seconds e max_waiting_for_unifier_time_seconds para 60 ou mais. Você pode monitorar o payload de ingestão usando métricas DCR. Para mais informações sobre as variáveis de tempo de espera, veja 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. Você deve incluir este campo na transformação KQL.

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