Partilhar via

Use o Logstash para transmitir logs com transformações de pipeline por meio de API baseada em DCR

  • Artigo

Importante

A ingestão de dados usando o plug-in de saída Logstash com Regras de Coleta de Dados (DCRs) está atualmente em visualização pública. Este recurso é fornecido sem um contrato de nível de serviço. Para obter mais informações, veja Termos Suplementares de Utilização para Pré-visualizações do Microsoft Azure.

O novo plug-in de saída Logstash do Microsoft Sentinel suporta transformações de pipeline e configuração avançada por meio de DCRs (Data Collection Rules). O plug-in encaminha qualquer tipo de logs de fontes de dados externas para tabelas personalizadas ou padrão no Log Analytics ou no Microsoft Sentinel.

Neste artigo, você aprenderá a configurar o novo plug-in Logstash para transmitir os dados para o Log Analytics ou o Microsoft Sentinel usando DCRs, com controle total sobre o esquema de saída. Saiba como implantar o plug-in.

Nota

Uma versão anterior do plug-in Logstash permite que você conecte fontes de dados através do Logstash por meio da API de coleta de dados.

Com o novo plugin, você pode:

  • Controle a configuração dos nomes e tipos de coluna.
  • Execute transformações no tempo de ingestão, como filtragem ou enriquecimento.
  • Ingerir logs personalizados em uma tabela personalizada ou ingerir um fluxo de entrada Syslog na tabela Syslog do Log Analytics.

A ingestão em tabelas padrão é limitada apenas a tabelas padrão suportadas para ingestão de logs personalizados.

Para saber mais sobre como trabalhar com o mecanismo de coleta de dados Logstash, consulte Introdução ao Logstash.

Descrição geral

Arquitetura e antecedentes

Diagrama da arquitetura Logstash.

O motor Logstash é composto por três componentes:

  • Plugins de entrada: Coleção personalizada de dados de várias fontes.
  • Plugins de filtro: Manipulação e normalização de dados de acordo com critérios especificados.
  • Plugins de saída: Envio personalizado de dados recolhidos e processados para vários destinos.

Nota

  • A Microsoft suporta apenas o plug-in de saída Logstash fornecido pelo Microsoft Sentinel discutido aqui. O plug-in atual é chamado microsoft-sentinel-log-analytics-logstash-output-plugin, v1.1.0. Você pode abrir um ticket de suporte para quaisquer problemas relacionados ao plug-in de saída.

  • A Microsoft não oferece suporte a plug-ins de saída Logstash de terceiros para o Microsoft Sentinel ou qualquer outro plug-in ou componente Logstash de qualquer tipo.

  • Consulte os pré-requisitos para o suporte à versão Logstash do plugin.

O plug-in de saída do Microsoft Sentinel para Logstash envia dados formatados em JSON para seu espaço de trabalho do Log Analytics, usando a API de ingestão de log do Log Analytics. Os dados são ingeridos em logs personalizados ou tabela padrão.

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

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

Para configurar o plugin, siga estes passos:

  1. Rever os pré-requisitos
  2. Instale o plugin
  3. Criar um arquivo de exemplo
  4. Crie os recursos relacionados ao DCR necessários
  5. Configurar o arquivo de configuração do Logstash
  6. Reiniciar o Logstash
  7. Exibir logs de entrada no Microsoft Sentinel
  8. Monitore os logs de auditoria do plug-in de saída

Pré-requisitos

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

    • 7.0 - 7.17.13
    • 8.0 - 8.9
    • 8.11 - 8.13

    Nota

    Se você usa o Logstash 8, recomendamos que desative o ECS no pipeline.

  • Verifique se você tem um espaço de trabalho do Log Analytics com pelo menos direitos de colaborador.

  • Verifique se você tem permissões para criar objetos DCR no espaço de trabalho.

Instale o plugin

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

Criar um arquivo de exemplo

Nesta seção, você cria um arquivo de exemplo em um destes cenários:

Criar um arquivo de exemplo para logs personalizados

Nesse cenário, você configura o plug-in de entrada Logstash para enviar eventos para o Microsoft Sentinel. Para este exemplo, usamos o plugin de entrada do gerador para simular eventos. Você pode usar qualquer outro plug-in de entrada.

Neste exemplo, o arquivo de configuração Logstash tem esta aparência:

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

  1. Copie a configuração do plug-in de saída abaixo para o arquivo 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. Para certificar-se de que o caminho do arquivo referenciado existe antes de criar o arquivo de exemplo, inicie o Logstash.

    O plug-in grava dez registros em um arquivo de exemplo nomeado sampleFile<epoch seconds>.json no caminho configurado. Por exemplo: c:\temp\sampleFile1648453501.json. Aqui está parte de um arquivo de exemplo que o plugin 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 plugin adiciona automaticamente estas propriedades a cada registo:

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

    Você pode remover esses campos ao criar o DCR.

Criar um arquivo de exemplo para ingerir logs na tabela Syslog

Nesse cenário, você configura o plug-in de entrada Logstash para enviar eventos syslog para o Microsoft Sentinel.

  1. Se você ainda não tiver mensagens syslog encaminhadas para sua máquina Logstash, poderá usar 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
Here is an example for the Logstash input plugin:
input {
     syslog {
         port => 514
    }
}

  2. Copie a configuração do plug-in de saída abaixo para o arquivo 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. Para certificar-se de que o caminho do arquivo existe antes de criar o arquivo de exemplo, inicie o Logstash.

    O plug-in grava dez registros em um arquivo de exemplo nomeado sampleFile<epoch seconds>.json no caminho configurado. Por exemplo: c:\temp\sampleFile1648453501.json. Aqui está parte de um arquivo de exemplo que o plugin 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 plugin adiciona automaticamente estas propriedades a cada registo:

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

    Você pode remover esses campos ao criar o DCR.

Crie os recursos DCR necessários

Para configurar o plug-in Logstash baseado em DCR do Microsoft Sentinel, primeiro você precisa criar os recursos relacionados ao DCR.

Nesta seção, você cria recursos para usar em seu DCR, em um destes cenários:

Criar recursos DCR para ingestão em uma tabela personalizada

Para ingerir os dados em uma tabela personalizada, siga estas etapas (com base no tutorial Enviar dados para Logs do Azure Monitor usando a API REST (portal do Azure):

  1. Veja os pré-requisitos.

  2. Configure o aplicativo.

  3. Adicione uma tabela de log personalizada.

  4. Analise e filtre dados de exemplo usando o arquivo de exemplo criado na seção anterior.

  5. Colete informações do DCR.

  6. Atribua permissões ao DCR.

    Ignore a etapa Enviar dados de exemplo.

Se você encontrar algum problema, consulte as etapas de solução de problemas.

Criar recursos DCR para ingestão em uma tabela padrão

Para ingerir os dados em uma tabela padrão como Syslog ou CommonSecurityLog, use um processo baseado no tutorial Enviar dados para Logs do Azure Monitor usando a API REST (modelos do Gerenciador de Recursos). Embora o tutorial explique como ingerir dados em uma tabela personalizada, você pode facilmente ajustar o processo para ingerir dados em uma tabela padrão. As etapas abaixo indicam alterações relevantes nas etapas.

  1. Veja os pré-requisitos.

  2. Coletar detalhes do espaço de trabalho.

  3. Configure um aplicativo.

    Ignore a etapa Criar nova tabela no espaço de trabalho do Log Analytics. Esta etapa não é relevante ao ingerir dados em uma tabela padrão, porque a tabela já está definida no Log Analytics.

  4. Crie o DCR. Nesta etapa:

    • Forneça o arquivo de exemplo criado na seção anterior.
    • Use o arquivo de exemplo que você criou para definir a streamDeclarations propriedade. Cada um dos campos no arquivo de exemplo deve ter uma coluna correspondente com o mesmo nome e o tipo apropriado (veja o exemplo abaixo).
    • Configure o outputStream valor da 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 sufixo _CL .
    • O prefixo do nome da tabela deve ser Microsoft- em vez de Custom-. No nosso exemplo, o valor da outputStream propriedade é Microsoft-Syslog.

  5. Atribua permissões a um DCR.

    Ignore a etapa Enviar dados de exemplo.

Se você encontrar algum problema, consulte as etapas de solução de problemas.

Exemplo: DCR que ingere dados na tabela Syslog

Tenha em atenção que:

  • Os streamDeclarations nomes e tipos de coluna devem ser os mesmos que os campos de arquivo de exemplo, mas não é necessário especificar todos eles. Por exemplo, no DCR abaixo, os PRIcampos , type e ls_version são omitidos da streamDeclarations coluna.
  • A dataflows propriedade transforma a entrada para o formato de tabela Syslog e define como outputStream 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": "westus2",
			"allowedValues": [
				"westus2",
				"eastus2",
				"eastus2euap"
			],
			"type": "String",
			"metadata": {
				"description": "Specifies the location in which to create the Data Collection Rule."
			}
		},
        "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 arquivo de configuração do Logstash

Para configurar o arquivo de configuração Logstash para ingerir os logs em uma tabela personalizada, recupere estes valores:

Campo Como recuperar
client_app_Id O Application (client) ID valor que você cria na etapa 3 ao criar os recursos DCR, de acordo com o tutorial usado nesta seção.
client_app_secret O Application (client) ID valor que você cria na etapa 5 ao criar os recursos DCR, de acordo com o tutorial usado nesta seção.
tenant_id ID de inquilino da sua subscrição. Você pode encontrar a ID do locatário em Home > Microsoft Entra ID > Overview > Basic Information.
data_collection_endpoint O valor do logsIngestion URI na etapa 3 quando você cria os recursos DCR, de acordo com o tutorial usado nesta seção.
dcr_immutable_id O valor do DCR immutableId na etapa 6 quando você cria os recursos DCR, de acordo com o tutorial usado nesta seção.
dcr_stream_name Para tabelas personalizadas, conforme explicado na etapa 6 ao criar os recursos DCR, vá para a visualização JSON do DCR e copie a dataFlows>streams propriedade. Veja o dcr_stream_name exemplo abaixo.

Para tabelas padrão, o valor é Custom-SyslogStream.

Depois de recuperar os valores necessários:

  1. Substitua a seção de saída do arquivo de configuração Logstash criado na etapa anterior pelo exemplo abaixo.
  2. Substitua as cadeias de caracteres de espaço reservado no exemplo abaixo pelos valores recuperados.
  3. Certifique-se de alterar o create_sample_file atributo para false.

Configuração opcional

Campo Description Default value
azure_cloud Usados para especificar o nome da nuvem do Azure que está sendo usada, os valores disponíveis são: AzureCloud, AzureChinaCloude AzureUSGovernment. AzureCloud
key_names Uma matriz de cadeias de caracteres. Forneça este campo se quiser enviar um subconjunto das colunas para o Log Analytics. Nenhum (campo está vazio)
plugin_flush_interval Define a diferença de tempo máxima (em segundos) entre o envio de duas mensagens para o Log Analytics. 5
retransmission_time Define a quantidade de tempo, em segundos, para retransmitir mensagens quando o envio falhar. 10
compress_data Quando esse campo é True, os dados do evento são compactados antes de usar a API. Recomendado para pipelines de alto rendimento. False
proxy Especifique qual URL de proxy usar para todas as chamadas de API. Nenhum (campo está vazio)
proxy_aad Especifique qual URL de proxy usar para chamadas de API para o Microsoft Entra ID. Mesmo valor que 'proxy' (o campo está vazio)
proxy_endpoint Especifique qual URL de proxy usar para chamadas de API para o Ponto de Extremidade de Coleta de Dados. Mesmo valor que 'proxy' (o campo está vazio)

Exemplo: Seção de configuração do plug-in de saída

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"
      proxy => "http://proxy.example.com"
    }
}

Para definir outros parâmetros para o plug-in de saída do Microsoft Sentinel Logstash, consulte o arquivo readme do plug-in de saída.

Nota

Por motivos de segurança, recomendamos que você não indique implicitamente os client_app_Idatributos , client_app_secret, tenant_id, data_collection_endpointe dcr_immutable_id no arquivo de configuração do Logstash. Recomendamos que você armazene essas informações confidenciais em um Logstash KeyStore.

Reiniciar o Logstash

Reinicie o Logstash com a configuração atualizada do plug-in de saída e veja que os dados são ingeridos na tabela certa de acordo com sua configuração DCR.

Exibir logs de entrada no Microsoft Sentinel

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

  2. No menu de navegação do Microsoft Sentinel, clique em Logs. Sob o título Tabelas , expanda a categoria Logs personalizados . Localize e clique no nome da tabela que você especificou (com um _CL sufixo) na configuração.

    Captura de ecrã de registos personalizados de armazenamento de registos.

  3. Para ver os registros na tabela, consulte a tabela usando o nome da tabela como o esquema.

    Captura de tela de uma consulta de logs personalizados de log stash.

Monitore os logs de auditoria do plug-in de saída

Para monitorar a conectividade e a atividade do plug-in de saída do Microsoft Sentinel, habilite o arquivo de log Logstash apropriado. Consulte o documento Logstash Directory Layout para obter o local do arquivo de log.

Se você não estiver vendo nenhum dado neste arquivo de log, gere e envie alguns eventos localmente (através dos plug-ins de entrada e filtro) para garantir que o plug-in de saída esteja recebendo dados. O Microsoft Sentinel suportará apenas problemas relacionados ao plug-in de saída.

Segurança da rede

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

Etiquetas de serviço da rede virtual

O plug-in de saída do Microsoft Sentinel dá suporte a tags de serviço de rede virtual do Azure. As tags AzureMonitor e AzureActiveDirectory são necessárias.

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. Use tags de serviço no lugar de endereços IP específicos ao criar regras de segurança e rotas. Para cenários em que as tags de serviço da Rede Virtual do Azure não podem ser usadas, os requisitos de firewall são fornecidos abaixo.

Requisitos de firewall

A tabela a seguir lista os requisitos de firewall para cenários em que as tags de serviço de rede virtual do Azure não podem ser usadas.

Cloud Ponto final Propósito Porta Direção Inspeção de HTTPS direto
Azure Commercial https://login.microsoftonline.com Servidor de autorização (a plataforma de identidade da Microsoft) Porta 443 De Saída Sim
Azure Commercial https://<data collection endpoint name>.<Azure cloud region>.ingest.monitor.azure.com Ponto final de recolha de dados Porta 443 De Saída Sim
Azure Government https://login.microsoftonline.us Servidor de autorização (a plataforma de identidade da Microsoft) Porta 443 De Saída Sim
Azure Government Substitua '.com' acima por '.us' Ponto final de recolha de dados Porta 443 De Saída Sim
Microsoft Azure operado pela 21Vianet https://login.chinacloudapi.cn Servidor de autorização (a plataforma de identidade da Microsoft) Porta 443 De Saída Sim
Microsoft Azure operado pela 21Vianet Substitua '.com' acima por '.cn' Ponto final de recolha de dados Porta 443 De Saída Sim

Limitações

  • A ingestão em tabelas padrão é limitada apenas a tabelas padrão suportadas para ingestão de logs personalizados.
  • As colunas do fluxo de entrada na streamDeclarations propriedade devem começar com uma letra. Se você iniciar uma coluna com outros caracteres (por exemplo @ , ou _), a operação falhará.
  • O TimeGenerated campo datetime é obrigatório. Você deve incluir esse campo na transformação KQL.
  • Para possíveis problemas adicionais, consulte a seção de solução de problemas no tutorial.

Próximos passos

Neste artigo, você aprendeu como usar o Logstash para conectar fontes de dados externas ao Microsoft Sentinel. Para saber mais sobre o Microsoft Sentinel, consulte os seguintes artigos: