Condividi tramite

Usare Logstash per trasmettere i log con trasformazioni della pipeline tramite l'API basata su DCR

  • Articolo

Importante

L'inserimento dati tramite il plug-in di output Logstash con le regole di raccolta dati (DCR) è attualmente in anteprima pubblica. Questa funzionalità viene fornita senza un contratto di servizio. Per altre informazioni, vedere le Condizioni supplementari per l'uso delle anteprime di Microsoft Azure.

Il nuovo plug-in di output Logstash di Microsoft Sentinel supporta le trasformazioni della pipeline e la configurazione avanzata tramite regole di raccolta dati (DCR). Il plug-in inoltra qualsiasi tipo di log da origini dati esterne in tabelle personalizzate o standard in Log Analytics o Microsoft Sentinel.

In questo articolo si apprenderà come configurare il nuovo plug-in Logstash per trasmettere i dati in Log Analytics o Microsoft Sentinel usando controller di dominio, con controllo completo sullo schema di output. Informazioni su come distribuire il plug-in.

Nota

Una versione precedente del plug-in Logstash consente di connettere le origini dati tramite Logstash tramite l'API raccolta dati.

Con il nuovo plug-in, è possibile:

  • Controllare la configurazione dei nomi e dei tipi di colonna.
  • Eseguire trasformazioni in fase di inserimento, ad esempio filtri o arricchimenti.
  • Inserire log personalizzati in una tabella personalizzata o inserire un flusso di input Syslog nella tabella Syslog di Log Analytics.

L'inserimento in tabelle standard è limitato solo alle tabelle standard supportate per l'inserimento di log personalizzati.

Per altre informazioni sull'uso del motore di raccolta dati Logstash, vedere Introduzione a Logstash.

Panoramica

Architettura e sfondo

Diagramma dell'architettura Logstash.

Il motore Logstash è composto da tre componenti:

  • Plug-in di input: raccolta personalizzata di dati da varie origini.
  • Plug-in di filtro: manipolazione e normalizzazione dei dati in base ai criteri specificati.
  • Plug-in di output: invio personalizzato di dati raccolti ed elaborati in varie destinazioni.

Nota

  • Microsoft supporta solo il plug-in di output Logstash fornito da Microsoft Sentinel descritto qui. Il plug-in corrente è denominato microsoft-sentinel-log-analytics-logstash-output-plugin, v1.1.0. È possibile aprire un ticket di supporto per eventuali problemi relativi al plug-in di output.

  • Microsoft non supporta plug-in di output Logstash di terze parti per Microsoft Sentinel o altri plug-in o componenti Logstash di qualsiasi tipo.

  • Vedere i prerequisiti per il supporto della versione logstash del plug-in.

Il plug-in di output di Microsoft Sentinel per Logstash invia dati in formato JSON all'area di lavoro Log Analytics usando l'API di inserimento log di Log Analytics. I dati vengono inseriti in log personalizzati o in una tabella standard.

  • Altre informazioni sull'API di inserimento dei log.

Distribuire il plug-in di output di Microsoft Sentinel in Logstash

Per configurare il plug-in, seguire questa procedura:

  1. Esaminare i prerequisiti
  2. Installare il plug-in
  3. Creare un file di esempio
  4. Creare le risorse correlate a DCR necessarie
  5. Configurare il file di configurazione Logstash
  6. Riavviare Logstash
  7. Visualizzare i log in ingresso in Microsoft Sentinel
  8. Monitorare i log di controllo del plug-in di output

Prerequisiti

  • Installare una versione supportata di Logstash. Il plug-in supporta le versioni di Logstash seguenti:

    • 7.0 - 7.17.13
    • 8.0 - 8.9
    • 8.11

    Nota

    Se si usa Logstash 8, è consigliabile disabilitare ECS nella pipeline.

  • Verificare di disporre di un'area di lavoro Log Analytics con almeno diritti di collaboratore.

  • Verificare di avere le autorizzazioni necessarie per creare oggetti DCR nell'area di lavoro.

Installare il plug-in

Il plug-in di output di Microsoft Sentinel è disponibile nella raccolta Logstash.

Creare un file di esempio

In questa sezione viene creato un file di esempio in uno di questi scenari:

Creare un file di esempio per i log personalizzati

In questo scenario si configura il plug-in di input Logstash per inviare eventi a Microsoft Sentinel. Per questo esempio viene usato il plug-in di input del generatore per simulare gli eventi. È possibile usare qualsiasi altro plug-in di input.

In questo esempio il file di configurazione Logstash è simile al seguente:

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

  1. Copiare la configurazione del plug-in di output seguente nel file di configurazione 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. Per assicurarsi che il percorso del file di riferimento esista prima di creare il file di esempio, avviare Logstash.

    Il plug-in scrive dieci record in un file di esempio denominato sampleFile<epoch seconds>.json nel percorso configurato. Ad esempio: c:\temp\sampleFile1648453501.json. Ecco una parte di un file di esempio creato dal plug-in:

    [
        {
            "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
    ...

    ]

    Il plug-in aggiunge automaticamente queste proprietà a ogni record:

    • ls_timestamp: ora in cui il record viene ricevuto dal plug-in di input
    • ls_version: versione della pipeline Logstash.

    È possibile rimuovere questi campi quando si crea il record di controllo di dominio.

Creare un file di esempio per inserire i log nella tabella Syslog

In questo scenario si configura il plug-in di input Logstash per inviare eventi syslog a Microsoft Sentinel.

  1. Se nel computer Logstash non sono già stati inoltrati messaggi syslog, è possibile usare il comando logger per generare messaggi. Ad esempio (per 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. Copiare la configurazione del plug-in di output seguente nel file di configurazione 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. Per assicurarsi che il percorso del file esista prima di creare il file di esempio, avviare Logstash.

    Il plug-in scrive dieci record in un file di esempio denominato sampleFile<epoch seconds>.json nel percorso configurato. Ad esempio: c:\temp\sampleFile1648453501.json. Ecco una parte di un file di esempio creato dal plug-in:

    [
    	{
    		"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"
    	}
]

    Il plug-in aggiunge automaticamente queste proprietà a ogni record:

    • ls_timestamp: ora in cui il record viene ricevuto dal plug-in di input
    • ls_version: versione della pipeline Logstash.

    È possibile rimuovere questi campi quando si crea il record di controllo di dominio.

Creare le risorse DCR necessarie

Per configurare il plug-in Logstash basato su DCR di Microsoft Sentinel, è prima necessario creare le risorse correlate a DCR.

In questa sezione vengono create risorse da usare per il Registro Azure Container, in uno di questi scenari:

Creare risorse DCR per l'inserimento in una tabella personalizzata

Per inserire i dati in una tabella personalizzata, seguire questa procedura (in base all'esercitazione Inviare dati ai log di Monitoraggio di Azure usando l'API REST (portale di Azure):

  1. Esaminare i prerequisiti.

  2. Configurazione dell'applicazione.

  3. Aggiungere una tabella di log personalizzata.

  4. Analizzare e filtrare i dati di esempio usando il file di esempio creato nella sezione precedente.

  5. Raccogliere informazioni dal Registro Azure Container.

  6. Assegnare le autorizzazioni al Registro Azure Container.

    Ignorare il passaggio Invia dati di esempio.

Se si verificano problemi, vedere i passaggi per la risoluzione dei problemi.

Creare risorse DCR per l'inserimento in una tabella standard

Per inserire i dati in una tabella standard come Syslog o CommonSecurityLog, usare un processo basato sull'esercitazione Inviare dati ai log di Monitoraggio di Azure usando l'API REST (modelli di Resource Manager). Mentre l'esercitazione illustra come inserire dati in una tabella personalizzata, è possibile modificare facilmente il processo per inserire i dati in una tabella standard. I passaggi seguenti indicano le modifiche rilevanti nei passaggi.

  1. Esaminare i prerequisiti.

  2. Raccogliere i dettagli dell'area di lavoro.

  3. Configurare un'applicazione.

    Ignorare il passaggio Crea nuova tabella nell'area di lavoro Log Analytics. Questo passaggio non è rilevante quando si inseriscono dati in una tabella standard, perché la tabella è già definita in Log Analytics.

  4. Creare il record di controllo di dominio. In questo passaggio:

    • Specificare il file di esempio creato nella sezione precedente.
    • Usare il file di esempio creato per definire la streamDeclarations proprietà . Ognuno dei campi nel file di esempio deve avere una colonna corrispondente con lo stesso nome e il tipo appropriato (vedere l'esempio seguente).
    • Configurare il valore della outputStream proprietà con il nome della tabella standard anziché la tabella personalizzata. A differenza delle tabelle personalizzate, i nomi delle tabelle standard non hanno il _CL suffisso .
    • Il prefisso del nome della tabella deve essere Microsoft- invece di Custom-. Nell'esempio il valore della outputStream proprietà è Microsoft-Syslog.

  5. Assegnare le autorizzazioni a un record di controllo di dominio.

    Ignorare il passaggio Invia dati di esempio.

Se si verificano problemi, vedere i passaggi per la risoluzione dei problemi.

Esempio: DCR che inserisce i dati nella tabella Syslog

Tenere presente quanto segue:

  • I streamDeclarations nomi e i tipi di colonna devono corrispondere ai campi del file di esempio, ma non è necessario specificarli tutti. Ad esempio, nel DCR seguente i PRIcampi e typels_version vengono omessi dalla streamDeclarations colonna .
  • La dataflows proprietà trasforma l'input nel formato di tabella Syslog e imposta su outputStreamMicrosoft-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'))]"
		}
	}
}

Configurare il file di configurazione Logstash

Per configurare il file di configurazione Logstash per inserire i log in una tabella personalizzata, recuperare questi valori:

Campo Come recuperare
client_app_Id Valore Application (client) ID creato nel passaggio 3 quando si creano le risorse DCR, in base all'esercitazione usata in questa sezione.
client_app_secret Valore Application (client) ID creato nel passaggio 5 quando si creano le risorse DCR, in base all'esercitazione usata in questa sezione.
tenant_id ID tenant della sottoscrizione. È possibile trovare l'ID tenant in Home > Microsoft Entra ID > Overview Basic Information (Informazioni >di base).
data_collection_endpoint Valore dell'URI logsIngestion nel passaggio 3 quando si creano le risorse DCR, in base all'esercitazione usata in questa sezione.
dcr_immutable_id Il valore di DCR nel passaggio 6 quando si creano le risorse DCRimmutableId, in base all'esercitazione usata in questa sezione.
dcr_stream_name Per le tabelle personalizzate, come illustrato nel passaggio 6 quando si creano le risorse DCR, passare alla visualizzazione JSON di DCR e copiare la dataFlows>streams proprietà . Vedere l'esempio dcr_stream_name seguente.

Per le tabelle standard, il valore è Custom-SyslogStream.

Dopo aver recuperato i valori necessari:

  1. Sostituire la sezione di output del file di configurazione Logstash creato nel passaggio precedente con l'esempio seguente.
  2. Sostituire le stringhe segnaposto nell'esempio seguente con i valori recuperati.
  3. Assicurarsi di modificare l'attributo create_sample_file in false.

Configurazione facoltativa

Campo Descrizione Default value
azure_cloud Usato per specificare il nome del cloud di Azure usato, i valori disponibili sono: AzureCloud, AzureChinaCloude AzureUSGovernment. AzureCloud
key_names Matrice di stringhe. Specificare questo campo se si vuole inviare un subset delle colonne a Log Analytics. Nessuno (il campo è vuoto)
plugin_flush_interval Definisce la differenza massima di tempo (in secondi) tra l'invio di due messaggi a Log Analytics. 5
retransmission_time Imposta la quantità di tempo in secondi per la ritrasmissione dei messaggi dopo l'invio non riuscito. 10
compress_data Quando questo campo è True, i dati dell'evento vengono compressi prima di usare l'API. Consigliato per le pipeline con velocità effettiva elevata. False
proxy Specificare l'URL proxy da usare per tutte le chiamate API. Nessuno (il campo è vuoto)
proxy_aad Specificare l'URL proxy da usare per le chiamate API all'ID Microsoft Entra. Stesso valore di "proxy" (campo vuoto)
proxy_endpoint Specificare l'URL proxy da usare per le chiamate API all'endpoint di raccolta dati. Stesso valore di "proxy" (campo vuoto)

Esempio: sezione di configurazione del plug-in di output

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"
    }
}

Per impostare altri parametri per il plug-in di output Logstash di Microsoft Sentinel, vedere il file leggimi del plug-in di output.

Nota

Per motivi di sicurezza, è consigliabile non specificare in modo implicito gli client_app_Idattributi , client_app_secret, tenant_iddata_collection_endpoint, e dcr_immutable_id nel file di configurazione Logstash. È consigliabile archiviare queste informazioni riservate in un archivio chiavi Logstash.

Riavviare Logstash

Riavviare Logstash con la configurazione aggiornata del plug-in di output e verificare che i dati vengano inseriti nella tabella corretta in base alla configurazione di DCR.

Visualizzare i log in ingresso in Microsoft Sentinel

  1. Verificare che i messaggi vengano inviati al plug-in di output.

  2. Scegliere Log dal menu di spostamento di Microsoft Sentinel. Nell'intestazione Tabelle espandere la categoria Log personalizzati. Trovare e fare clic sul nome della tabella specificata (con un _CL suffisso) nella configurazione.

    Screenshot dei log di accantonamento dei log personalizzati.

  3. Per visualizzare i record nella tabella, eseguire una query sulla tabella usando il nome della tabella come schema.

    Screenshot di una query log di stash personalizzata.

Monitorare i log di controllo del plug-in di output

Per monitorare la connettività e l'attività del plug-in di output di Microsoft Sentinel, abilitare il file di log Logstash appropriato. Vedere il documento Logstash Directory Layout (Layout directory Logstash) per il percorso del file di log.

Se non vengono visualizzati dati in questo file di log, generare e inviare alcuni eventi in locale (tramite i plug-in di input e filtro) per assicurarsi che il plug-in di output riceva i dati. Microsoft Sentinel supporterà solo i problemi relativi al plug-in di output.

Sicurezza della rete

Definire le impostazioni di rete e abilitare l'isolamento di rete per il plug-in di output Logstash di Microsoft Sentinel.

Tag del servizio di rete virtuale

Il plug-in di output di Microsoft Sentinel supporta i tag del servizio di rete virtuale di Azure. Sono necessari sia i tag AzureMonitor che AzureActiveDirectory .

I tag del servizio Rete virtuale di Azure possono essere usati per definire i controlli di accesso di rete nei gruppi di sicurezza di rete, nei Firewall di Azure e nelle route definite dall'utente. Usare i tag del servizio al posto di indirizzi IP specifici quando si creano regole e route di sicurezza. Per gli scenari in cui non è possibile usare i tag del servizio Rete virtuale di Azure, i requisiti del firewall sono indicati di seguito.

Requisiti del firewall

La tabella seguente elenca i requisiti del firewall per gli scenari in cui non è possibile usare i tag del servizio di rete virtuale di Azure.

Cloud Endpoint Scopo Porta Direzione Ignorare il controllo HTTPS
Azure Commercial https://login.microsoftonline.com Server di autorizzazione (Microsoft Identity Platform) Porta 443 In uscita Sì
Azure Commercial https://<data collection endpoint name>.<Azure cloud region>.ingest.monitor.azure.com Endpoint raccolta dati Porta 443 In uscita Sì
Azure Government https://login.microsoftonline.us Server di autorizzazione (Microsoft Identity Platform) Porta 443 In uscita Sì
Azure Government Sostituire '.com' sopra con '.us' Endpoint raccolta dati Porta 443 In uscita Sì
Microsoft Azure gestito da 21Vianet https://login.chinacloudapi.cn Server di autorizzazione (Microsoft Identity Platform) Porta 443 In uscita Sì
Microsoft Azure gestito da 21Vianet Sostituire '.com' sopra con '.cn' Endpoint raccolta dati Porta 443 In uscita Sì

Limiti

  • L'inserimento in tabelle standard è limitato solo alle tabelle standard supportate per l'inserimento di log personalizzati.
  • Le colonne del flusso di input nella streamDeclarations proprietà devono iniziare con una lettera. Se si avvia una colonna con altri caratteri ( ad esempio @ o _), l'operazione ha esito negativo.
  • Il TimeGenerated campo datetime è obbligatorio. È necessario includere questo campo nella trasformazione KQL.
  • Per altri problemi, vedere la sezione relativa alla risoluzione dei problemi nell'esercitazione.

Passaggi successivi

In questo articolo si è appreso come usare Logstash per connettere origini dati esterne a Microsoft Sentinel. Per altre informazioni su Microsoft Sentinel, vedere gli articoli seguenti: