Usar o Logstash para transmitir logs com transformações de pipeline por meio da API baseada em DCR
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
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.
- 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 plug-in, siga estas etapas:
- Analisar os pré-requisitos
- Instalar o plug-in
- Criar um arquivo de exemplo
- Criar os recursos relacionados necessários a DCR
- Configurar o arquivo de configuração do Logstash
- Reiniciar o Logstash
- Exibir logs de entrada no Microsoft Sentinel
- 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 - 8.13
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.
- Siga as instruções no documento do Logstash Trabalhar com plug-ins para instalar o plug-in microsoft-sentinel-log-analytics-logstash-output-plugin.
- Se o sistema Logstash não tiver acesso à Internet, siga as instruções no documento Gerenciamento de plug-ins offline do Logstash para preparar e usar um pacote de plugin offline. (Isso exigirá que a criação de outro sistema Logstash com acesso à Internet.)
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
- Criar um arquivo de exemplo para ingerir logs na tabela Syslog
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
}
}
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. } }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>.jsonno 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 entradals_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.
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 } }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. } }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>.jsonno 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 entradals_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
- Criar recursos de DCR para ingestão em uma tabela padrão
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)):
Analise os pré-requisitos.
Analisar e filtrar dados de exemplo usando o arquivo de exemplo criado na seção anterior.
-
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.
Analise os pré-requisitos.
-
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.
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
outputStreamcom 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 deCustom-. Em nosso exemplo, o valor da propriedadeoutputStreaméMicrosoft-Syslog.
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
streamDeclarationsdevem ser iguais aos campos de arquivo de exemplo, mas você não precisa especificar todos eles. Por exemplo, na DCR abaixo, os camposPRI,typeels_versionsão omitidos na colunastreamDeclarations. - A propriedade
dataflowstransforma a entrada no formato de tabela Syslog e define ooutputStreamcomoMicrosoft-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:
- Substitua a seção de saída do arquivo de configuração do Logstash que você criou na etapa anterior pelo exemplo abaixo.
- Substitua as cadeias de caracteres de espaço reservado no exemplo abaixo pelos valores recuperados.
- Verifique se você alterou o atributo
create_sample_fileparafalse.
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
Verifique se as mensagens estão sendo enviadas para o plug-in de saída.
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.
Para ver os registros na tabela, consulte a tabela usando o nome da tabela como o esquema.
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
streamDeclarationsdevem 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:
- Saiba como obter visibilidade dos seus dados e de possíveis ameaças.
- Introdução à detecção de ameaças com o Microsoft Sentinel.