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

O plug-in de saída do Logstash do Microsoft Sentinel suporta transformações de pipeline e configuração avançada através das 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:

• Controlar a configuração dos nomes e tipos de coluna.
• Efetue transformações de tempo de ingestão, como filtragem ou melhoramento.
• Ingerir registos personalizados numa 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.
• Plug-ins 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:

• Rever os pré-requisitos
• Instalar o plug-in
• Criar um ficheiro de exemplo
• Criar os recursos relacionados com DCR necessários
• Configurar o ficheiro de configuração do Logstash
• Reiniciar Logstash
• Ver registos recebidos no Microsoft Sentinel
• Monitorizar 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
  • 8.11 - 8.15
  • 8.19.2
  • 9.0.8
  • 9.1.10
  • 9.2.4 - 9.2.5

  Observação

  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, contribuidor direitos.

• 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 Trabalhar com plug-ins do Logstash 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 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 Microsoft Sentinel plug-in logstash baseado em DCR, crie primeiro os recursos relacionados com 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. Reveja 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 problemas, veja os passos de resolução de problemas.

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

Para ingerir os dados numa tabela padrão, como o Syslog ou o CommonSecurityLog, utilize um processo baseado no tutorial Enviar dados para Azure Monitorizar Registos com a API REST (Resource Manager modelos). 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. Reveja 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:

   • Indique o ficheiro de exemplo que criou na secção anterior.
   • 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 problemas, veja os passos de resolução de problemas.

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 PRIcampos e ls_versiontype são omitidos da streamDeclarations coluna.
• 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 do Logstash para ingerir os registos numa tabela personalizada com a autenticação do principal de serviço, obtenha estes valores:

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 marcador de posição no exemplo abaixo pelos valores obtidos.
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_app_Id => "<enter your client_app_id value here>"
      client_app_secret => "<enter your client_app_secret value here>"
      tenant_id => "<enter your tenant id here>"
      data_collection_endpoint => "<enter your logsIngestion URI here>"
      dcr_immutable_id => "<enter your DCR immutableId here>"
      dcr_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 managed_identity está definido como true, o plug-in é autenticado sem um segredo do cliente. O plug-in deteta automaticamente o mecanismo de identidade adequado no runtime pela seguinte ordem:

1. Identidade da Carga de Trabalho do AKS – se as variáveis AZURE_CLIENT_IDde ambiente , AZURE_TENANT_IDe AZURE_FEDERATED_TOKEN_FILE estiverem presentes (definidas automaticamente pelo AKS), o plug-in efetua uma troca de tokens OIDC.
2. Azure Arc – se o Azure Connected Machine Agent () forazcmagent detetado no anfitrião, o plug-in utiliza o Azure ponto final de identidade gerida do Arc para servidores híbridos e no local.
3. IMDS – caso contrário, o plug-in reverterá para o Azure Instance Metadata Service (IMDS) para Azure VMs e VMSS.

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

Exemplo: Identidade gerida atribuída pelo sistema

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

Exemplo: Identidade gerida atribuída pelo utilizador

output {
    microsoft-sentinel-log-analytics-logstash-output-plugin {
      managed_identity => true
      managed_identity_object_id => "<enter the object ID of your user-assigned identity>"
      data_collection_endpoint => "<enter your DCE logsIngestion URI here>"
      dcr_immutable_id => "<enter your DCR immutableId here>"
      dcr_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.

   

Monitorizar 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

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

Azure Rede Virtual etiquetas de serviço podem ser utilizadas para definir controlos de acesso de rede em grupos de segurança de rede, Firewall do Azure 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 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.1.0

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

2.0.0

• Refatorizar o plug-in de Ruby para Java.
• Adição da autenticação ManagedIdentity.
• Moveu a base de código do GitHub para Azure DevOps.
• Base de código fechada.

1.2.0

• Adiciona suporte de autenticação de identidade gerida para Azure VMs/VMSS (atribuídas pelo sistema e atribuídas pelo utilizador através do IMDS).
• Adiciona suporte de identidade de carga de trabalho do AKS através da troca de tokens OIDC.
• Adiciona Azure suporte de identidade gerida do Arc para servidores híbridos e no local.
• Deteta automaticamente o método de autenticação no runtime com base no ambiente (vars env de identidade da carga de trabalho, agente do Arc ou contingência do IMDS).
• Migra o cliente HTTP de excon para para melhorar rest-client a compatibilidade do ecossistema de plug-ins JRuby e Logstash.
• Muda o nome Azure referências do 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 resolve 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 plugin_flush_interval para 60 ou mais. Pode monitorizar o payload de ingestão com métricas DCR. Para obter mais informações sobre plugin_flush_interval, 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 problemas adicionais possíveis, veja a secção resolução de problemas no tutorial.