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 regole di raccolta dati (DCR) è attualmente disponibile 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 i DCR, con un 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 attraverso l'API di 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 è formato 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 dei 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 dei log di Log Analytics. I dati vengono inseriti in log personalizzati o in una tabella standard.

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

Per configurare il plug-in, seguire questi passaggi:

  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 di 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 seguenti versioni di Logstash:

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

    Nota

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

  • Verificare di disporre di un'area di lavoro di 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 di 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 di 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 di 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 DCR.

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

In questo scenario si configura il plug-in di input di 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 di 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 DCR.

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 DCR, 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 DCR.

  6. Assegnare le autorizzazioni al DCR.

    Ignorare il passaggio di invio dei 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 di creazione di una 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 DCR. In questo passaggio:

    • Specificare il file di esempio creato nella sezione precedente.
    • Usare il file di esempio creato per definire la proprietà streamDeclarations. 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 proprietà outputStream con il nome della tabella standard invece della tabella personalizzata. A differenza delle tabelle personalizzate, i nomi delle tabelle standard non hanno il suffisso _CL.
    • Il prefisso del nome della tabella deve essere Microsoft- invece di Custom-. Nell'esempio, il valore della proprietà outputStream è Microsoft-Syslog.

  5. Assegnare le autorizzazioni a un DCR.

    Ignorare il passaggio di invio dei 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 nomi e i tipi di colonne streamDeclarations devono corrispondere ai campi del file di esempio, ma non è necessario specificarli tutti. Ad esempio, nel DCR seguente i campi PRI, type e ls_version vengono omessi dalla colonna streamDeclarations.
  • La proprietà dataflows trasforma l'input nel formato di tabella Syslog e imposta outputStream su 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'))]"
		}
	}
}

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 i dati
client_app_Id Il 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 Il 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 > Panoramica > Informazioni di base.
data_collection_endpoint Il 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 immutableId nel passaggio 6 quando si creano le risorse DCR, 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 del DCR e copiare la proprietà dataFlows>streams. Vedere dcr_stream_name nell'esempio di seguito.

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, AzureChinaCloud e 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 un 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 a Microsoft Entra ID. 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 di 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 attributi client_app_Id, client_app_secret, tenant_id, data_collection_endpoint edcr_immutable_id nel file di configurazione Logstash. È consigliabile archiviare queste informazioni riservate in un archivio chiavi di 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 DCR.

Visualizzare i log in ingresso in Microsoft Sentinel

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

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

    Screenshot dei log personalizzati dei log di accantonamento.

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

    Screenshot di una query sui log personalizzati dei log di accantonamento.

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 Layout della 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 di 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 di rete virtuale di Azure possono essere usati per definire i controlli di accesso alla rete in gruppi di sicurezza di rete, Firewall di Azure e route definite dall'utente. Quando si creano regole di sicurezza e percorsi, usare i tag del servizio anziché gli indirizzi IP specifici. Per scenari in cui non fosse possibile usare tag del servizio di rete virtuale di Azure, i requisiti del firewall sono indicati di seguito.

Requisiti del firewall

Per scenari in cui non fosse possibile usare tag del servizio di rete virtuale di Azure, i requisiti del firewall sono indicati di seguito.

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 di 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 di 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 di 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 proprietà streamDeclarations devono iniziare con una lettera. Se si avvia una colonna con altri caratteri ( ad esempio @ o _), l'operazione ha esito negativo.
  • Il campo datetime TimeGenerated è obbligatorio. È necessario includere questo campo nella trasformazione KQL.
  • Per altri problemi, vedere la sezione relativa allarisoluzione 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: