Compartilhar via

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

  • Artigo

Importante

No momento, a ingestão de dados usando o plug-in de saída do Logstash com DCRs (Regras de Coleta de Dados) está em visualização pública. O recurso é fornecido sem um Contrato de Nível de Serviço. Para obter mais informações, consulte Termos de Uso Complementares de Versões Prévias do Microsoft Azure.

O novo plug-in de saída do Logstash do Microsoft Sentinel dá suporte a transformações de pipeline e configuração avançada por meio de DCRs (Regras de Coleta de Dados). O plug-in encaminha qualquer tipo de log 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 do 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.

Observação

Uma versão anterior do plug-in do Logstash permite que você conecte fontes de dados por meio do Logstash usando a API de Coleta de Dados.

Com o novo plug-in, você pode:

  • Controlar a configuração dos nomes e tipos de coluna.
  • Executar transformações de tempo de 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 é limitada apenas a tabelas padrão com suporte para ingestão de logs personalizados.

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

Visão geral

Arquitetura e plano de fundo

Diagrama da arquitetura de Logstash.

O mecanismo Logstash é composto por três componentes:

  • Plug-ins de entrada: coleção personalizada de dados de várias fontes.
  • Plug-ins de filtro: manipular e normalizar dados de acordo com os critérios especificados.
  • Plug-ins de saída: envio personalizado de dados coletados e processados para vários destinos.

Observação

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

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

  • Confira os pré-requisitos para o suporte à versão do Logstash do plug-in.

O plug-in de saída do Microsoft Sentinel para o Logstash envia dados formatados em JSON para o workspace do Log Analytics, usando a API de Ingestão de Logs do Log Analytics. Os dados são ingeridos em logs personalizados ou tabela padrão.

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

Para configurar o plug-in, siga estas etapas:

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

Pré-requisitos

  • Instale uma versão com suporte do Logstash. O plug-in dá suporte às seguintes versões do Logstash:

    • 7.0 - 7.17.13
    • 8.0 - 8.9
    • 8.11

    Observação

    Se você usar o Logstash 8, recomendamos desabilitar o ECS no pipeline.

  • Verifique se você tem um workspace do Log Analytics com pelo menos os direitos de colaborador.

  • Verifique se você tem permissões para criar objetos de DCR no workspace.

Instalar o plug-in

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

Criar um arquivo de exemplo

Nesta seção, você criará 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 do Logstash para enviar eventos ao Microsoft Sentinel. Para este exemplo, usamos o plug-in de entrada do gerador para simular eventos. Você pode usar qualquer outro plug-in de entrada.

Neste exemplo, o arquivo de configuração do Logstash é da seguinte forma:

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 garantir que o caminho do arquivo referenciado exista, antes de criar o arquivo de exemplo, inicie o Logstash.

    O plug-in grava dez registros em um arquivo de exemplo chamado sampleFile<epoch seconds>.json no caminho configurado. Por exemplo: c:\temp\sampleFile1648453501.json. Veja abaixo uma parte de um arquivo 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 essas propriedades a cada registro:

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

    Você pode remover esses campos ao criar a DCR.

Criar um arquivo de exemplo para ingerir logs na tabela Syslog

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

  1. Se você ainda não tiver mensagens de syslog encaminhadas para o computador Logstash, poderá usar o comando do agente 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 garantir que o caminho do arquivo exista, antes de criar o arquivo de exemplo, inicie o Logstash.

    O plug-in grava dez registros em um arquivo de exemplo chamado sampleFile<epoch seconds>.json no caminho configurado. Por exemplo: c:\temp\sampleFile1648453501.json. Veja abaixo uma parte de um arquivo 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 essas propriedades a cada registro:

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

    Você pode remover esses campos ao criar a DCR.

Criar os recursos necessários a DCR

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

Nesta seção, você criará recursos a serem usados para a DCR em um destes cenários:

Criar recursos de 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 os logs do Azure Monitor usando a API REST (portal do Azure)):

  1. Analise os pré-requisitos.

  2. Configuram o aplicativo.

  3. Adicione uma tabela personalizada de logs.

  4. Analisar e filtrar dados de exemplo usando o arquivo de exemplo criado na seção anterior.

  5. Colete informações da DCR.

  6. Atribua permissões à DCR.

    Ignore a etapa Enviar dados de exemplo.

Se você encontrar problemas, confira as etapas de solução de problemas.

Criar recursos de 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 com base no tutorial Enviar dados para os logs do Azure Monitor usando a API REST (modelos do ARM). Embora o tutorial explique como ingerir dados em uma tabela personalizada, você pode ajustar facilmente o processo para ingerir dados em uma tabela padrão. As etapas abaixo indicam alterações relevantes nas etapas.

  1. Analise os pré-requisitos.

  2. Coletar detalhes do workspace.

  3. Configurar um aplicativo.

    Ignore a etapa Criar nova tabela no workspace do Log Analytics. Essa etapa não é relevante ao ingerir dados em uma tabela padrão, pois a tabela já está definida no Log Analytics.

  4. Criar a 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 propriedade streamDeclarations. 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 valor da propriedade outputStream com o nome da tabela padrão, em vez da tabela personalizada. Ao contrário das tabelas personalizadas, os nomes de tabela padrão não têm o sufixo _CL.
    • O prefixo do nome da tabela deve ser Microsoft-, em vez de Custom-. Em nosso exemplo, o valor da propriedade outputStream é Microsoft-Syslog.

  5. Atribuir permissões a uma DCR.

    Ignore a etapa Enviar dados de exemplo.

Se você encontrar problemas, confira as etapas de solução de problemas.

Exemplo: DCR que ingere dados na tabela Syslog

Observe que:

  • Os nomes e tipos de coluna streamDeclarations devem ser iguais aos campos de arquivo de exemplo, mas você não precisa especificar todos eles. Por exemplo, na DCR abaixo, os campos PRI, type e ls_version são omitidos na coluna streamDeclarations.
  • A propriedade dataflows transforma a entrada no formato de tabela Syslog e define o outputStream como 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 do Logstash para ingerir os logs em uma tabela personalizada, recupere estes valores:

Campo Como recuperar
client_app_Id O valor Application (client) ID criado na etapa 3 ao criar os recursos da DCR, de acordo com o tutorial que você usou nesta seção.
client_app_secret O valor Application (client) ID criado na etapa 5 ao criar os recursos da DCR, de acordo com o tutorial que você usou nesta seção.
tenant_id ID do locatário da sua assinatura. Você pode encontrar a ID do locatário na Página Inicial > do Microsoft Entra ID > Visão geral > Informações básicas.
data_collection_endpoint O valor do URI logsIngestion na etapa 3 ao criar os recursos da DCR, de acordo com o tutorial que você usou nesta seção.
dcr_immutable_id O valor da DCR immutableId na etapa 6 ao criar os recursos da DCR, de acordo com o tutorial que você usou nesta seção.
dcr_stream_name Para tabelas personalizadas, conforme explicado na etapa 6 ao criar os recursos da DCR, vá para a exibição JSON da DCR e copie a propriedade dataFlows>streams. Veja o dcr_stream_name no 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 do Logstash que você criou na etapa anterior pelo exemplo abaixo.
  2. Substitua as cadeias de caracteres de espaço reservado no exemplo abaixo pelos valores recuperados.
  3. Verifique se você alterou o atributo create_sample_file para false.

Configuração opcional

Campo Descrição Valor padrão
azure_cloud Usado para especificar o nome da nuvem do Azure que está sendo usada. Os valores disponíveis são: AzureCloud, AzureChinaCloud e AzureUSGovernment. AzureCloud
key_names Uma matriz de cadeias de caracteres. Forneça esse campo se você quiser enviar um subconjunto das colunas para o Log Analytics. Nenhum (o campo está vazio)
plugin_flush_interval Define a diferença máxima de tempo (em segundos) entre o envio de duas mensagens para o Log Analytics. 5
retransmission_time Define o tempo em segundos para retransmitir mensagens depois que o envio falhou. 10
compress_data Quando esse campo é True, os dados do evento são compactados antes de usar a API. Recomendado para pipelines de alta taxa de transferência. False
proxy Especifique qual URL de proxy usar para todas as chamadas à API. Nenhum (o campo está vazio)
proxy_aad Especifique qual URL de proxy usar para chamadas à API para a ID do Microsoft Entra. Mesmo valor que "proxy" (o campo está vazio)
proxy_endpoint Especifique qual URL de proxy usar para chamadas à 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 Logstash do Microsoft Sentinel, confira o arquivo leiame do plug-in de saída.

Observação

Por motivos de segurança, recomendamos que você não declare implicitamente os atributos client_app_Id, client_app_secret, tenant_id, data_collection_endpoint e dcr_immutable_id no arquivo de configuração do Logstash. Recomendamos que você armazene essas informações confidenciais em um Repositório de Chaves do Logstash.

Reiniciar o Logstash

Reinicie o Logstash com a configuração atualizada do plug-in de saída e veja se os dados são ingeridos na tabela certa de acordo com a configuração da 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 Azure Sentinel, clique em Logs. No título Tabelas, expanda a categoria Logs personalizados. Localize e clique no nome da tabela especificada (com um sufixo _CL) na configuração.

    Captura de tela dos logs personalizados do stash de log.

  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 do stash de log.

Monitorar 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 Layout do diretório Logstash para o local do arquivo de log.

Se não for exibido nenhum dado nesse arquivo de log, gere e envie alguns eventos localmente (por meio dos plug-ins de entrada e de filtro) para verificar se o plug-in de saída está recebendo dados. O Microsoft Sentinel dará suporte apenas a problemas relacionados ao plug-in de saída.

Segurança de rede

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

Marcas de serviço de rede virtual

O plug-in de saída do Microsoft Sentinel dá suporte às marcas de serviço da Rede Virtual do Azure. As marcas AzureMonitor e AzureActiveDirectory são necessárias.

É possível usar as marcas de serviço da Rede Virtual do Azure para definir os controles de acesso à rede em grupos de segurança de rede, no Firewall do Azure e em rotas definidas pelo usuário. Use marcas de serviço em vez de endereços IP específicos ao criar regras e rotas de segurança. Confira abaixo os requisitos de firewall para os cenários em que não é possível usar as marcas de serviço da Rede Virtual do Azure.

Requisitos de firewall

A lista a seguir contém os requisitos de firewall para os cenários em que não é possível usar as marcas de serviço da Rede Virtual do Azure.

Nuvem Ponto de extremidade Finalidade Porta Direção Ignorar a inspeção de HTTPS
Azure Commercial https://login.microsoftonline.com Servidor de autorização (a plataforma de identidade da Microsoft) Porta 443 Saída Sim
Azure Commercial https://<data collection endpoint name>.<Azure cloud region>.ingest.monitor.azure.com Ponto de extremidade de coleta de dados Porta 443 Saída Sim
Azure Government https://login.microsoftonline.us Servidor de autorização (a plataforma de identidade da Microsoft) Porta 443 Saída Sim
Azure Government Substitua '.com' acima por '.us' Ponto de extremidade de coleta de dados Porta 443 Saída Sim
Microsoft Azure operado pela 21Vianet https://login.chinacloudapi.cn Servidor de autorização (a plataforma de identidade da Microsoft) Porta 443 Saída Sim
Microsoft Azure operado pela 21Vianet Substitua '.com' acima por '.cn' Ponto de extremidade de coleta de dados Porta 443 Saída Sim

Limitações

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

Próximas etapas

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