Delen via

Logstash gebruiken om logboeken te streamen met pijplijntransformaties via DCR-API

  • Artikel

Belangrijk

Gegevensopname met behulp van de invoegtoepassing Logstash-uitvoer met DATA Collection Rules (DCR's) is momenteel beschikbaar als openbare preview. Deze functie wordt geleverd zonder service level agreement. Zie Aanvullende gebruiksvoorwaarden voor Microsoft Azure-previews voor meer informatie.

De nieuwe invoegtoepassing Logstash-uitvoer van Microsoft Sentinel ondersteunt pijplijntransformaties en geavanceerde configuratie via DATA Collection Rules (DCR's). De invoegtoepassing stuurt elk type logboek van externe gegevensbronnen door naar aangepaste of standaardtabellen in Log Analytics of Microsoft Sentinel.

In dit artikel leert u hoe u de nieuwe Logstash-invoegtoepassing instelt om de gegevens te streamen naar Log Analytics of Microsoft Sentinel met DCR's, met volledige controle over het uitvoerschema. Meer informatie over het implementeren van de invoegtoepassing.

Notitie

Met een eerdere versie van de Logstash-invoegtoepassing kunt u via Logstash verbinding maken met gegevensbronnen via de Api voor gegevensverzameling.

Met de nieuwe invoegtoepassing kunt u het volgende doen:

  • De configuratie van de kolomnamen en -typen beheren.
  • Voer opname-tijdtransformaties uit, zoals filteren of verrijken.
  • U kunt aangepaste logboeken opnemen in een aangepaste tabel of een Syslog-invoerstroom opnemen in de Log Analytics Syslog-tabel.

Opname in standaardtabellen is alleen beperkt tot standaardtabellen die worden ondersteund voor opname van aangepaste logboeken.

Zie Aan de slag met Logstash voor logboeken voor meer informatie over het werken met de logstash-engine voor gegevensverzameling.

Overzicht

Architectuur en achtergrond

Diagram van de Logstash-architectuur.

De Logstash-engine bestaat uit drie onderdelen:

  • Invoerinvoegtoepassingen: Aangepaste verzameling van gegevens uit verschillende bronnen.
  • Filterinvoegtoepassingen: Manipulatie en normalisatie van gegevens volgens opgegeven criteria.
  • Uitvoerinvoegtoepassingen: Aangepast verzenden van verzamelde en verwerkte gegevens naar verschillende bestemmingen.

Notitie

  • Microsoft ondersteunt alleen de door Microsoft Sentinel geleverde Logstash-uitvoerinvoegtoepassing die hier wordt besproken. De huidige invoegtoepassing heet microsoft-sentinel-log-analytics-logstash-output-plugin, v1.1.0. U kunt een ondersteuningsticket openen voor problemen met betrekking tot de uitvoerinvoegtoepassing.

  • Microsoft biedt geen ondersteuning voor logstash-uitvoerinvoegtoepassingen van derden voor Microsoft Sentinel of andere Logstash-invoegtoepassingen of onderdelen van elk type.

  • Zie de vereisten voor de ondersteuning van de Logstash-versie van de invoegtoepassing.

De Microsoft Sentinel-uitvoerinvoegtoepassing voor Logstash verzendt JSON-geformatteerde gegevens naar uw Log Analytics-werkruimte met behulp van de Log Analytics Log Ingestion-API. De gegevens worden opgenomen in aangepaste logboeken of standaardtabellen.

  • Meer informatie over de OPNAME-API voor logboeken.

De Microsoft Sentinel-uitvoerinvoegtoepassing implementeren in Logstash

Voer de volgende stappen uit om de invoegtoepassing in te stellen:

  1. Controleer de vereisten
  2. De invoegtoepassing installeren
  3. Een voorbeeldbestand maken
  4. De vereiste DCR-gerelateerde resources maken
  5. Logstash-configuratiebestand configureren
  6. Logstash opnieuw starten
  7. Binnenkomende logboeken weergeven in Microsoft Sentinel
  8. Auditlogboeken van de uitvoerinvoegtoepassing controleren

Vereisten

  • Installeer een ondersteunde versie van Logstash. De invoegtoepassing ondersteunt de volgende Logstash-versies:

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

    Notitie

    Als u Logstash 8 gebruikt, raden we u aan ECS uit te schakelen in de pijplijn.

  • Controleer of u een Log Analytics-werkruimte hebt met ten minste inzenderrechten.

  • Controleer of u gemachtigd bent om DCR-objecten in de werkruimte te maken.

De invoegtoepassing installeren

De Microsoft Sentinel-uitvoerinvoegtoepassing is beschikbaar in de Logstash-verzameling.

Een voorbeeldbestand maken

In deze sectie maakt u een voorbeeldbestand in een van deze scenario's:

Een voorbeeldbestand maken voor aangepaste logboeken

In dit scenario configureert u de Logstash-invoerinvoegtoepassing voor het verzenden van gebeurtenissen naar Microsoft Sentinel. In dit voorbeeld gebruiken we de generatorinvoerinvoegtoepassing om gebeurtenissen te simuleren. U kunt elke andere invoegtoepassing voor invoer gebruiken.

In dit voorbeeld ziet het configuratiebestand Logstash er als volgt uit:

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

  1. Kopieer de configuratie van de uitvoerinvoegtoepassing hieronder naar uw Logstash-configuratiebestand.

    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. Als u ervoor wilt zorgen dat het pad naar het bestand waarnaar wordt verwezen bestaat voordat u het voorbeeldbestand maakt, start u Logstash.

    De invoegtoepassing schrijft tien records naar een voorbeeldbestand met de naam sampleFile<epoch seconds>.json in het geconfigureerde pad. Bijvoorbeeld: c:\temp\sampleFile1648453501.json. Hier maakt u deel uit van een voorbeeldbestand dat door de invoegtoepassing wordt gemaakt:

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

    ]

    De invoegtoepassing voegt deze eigenschappen automatisch toe aan elke record:

    • ls_timestamp: Het tijdstip waarop de record wordt ontvangen van de invoerinvoegtoepassing
    • ls_version: de logstash-pijplijnversie.

    U kunt deze velden verwijderen wanneer u de DCR maakt.

Een voorbeeldbestand maken om logboeken op te nemen in de Syslog-tabel

In dit scenario configureert u de Logstash-invoerinvoegtoepassing voor het verzenden van syslog-gebeurtenissen naar Microsoft Sentinel.

  1. Als u nog geen Syslog-berichten hebt doorgestuurd naar uw Logstash-computer, kunt u de logboekregistratieopdracht gebruiken om berichten te genereren. Bijvoorbeeld (voor 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. Kopieer de configuratie van de uitvoerinvoegtoepassing hieronder naar uw Logstash-configuratiebestand.

    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. Start Logstash om ervoor te zorgen dat het bestandspad bestaat voordat u het voorbeeldbestand maakt.

    De invoegtoepassing schrijft tien records naar een voorbeeldbestand met de naam sampleFile<epoch seconds>.json in het geconfigureerde pad. Bijvoorbeeld: c:\temp\sampleFile1648453501.json. Hier maakt u deel uit van een voorbeeldbestand dat door de invoegtoepassing wordt gemaakt:

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

    De invoegtoepassing voegt deze eigenschappen automatisch toe aan elke record:

    • ls_timestamp: Het tijdstip waarop de record wordt ontvangen van de invoerinvoegtoepassing
    • ls_version: de logstash-pijplijnversie.

    U kunt deze velden verwijderen wanneer u de DCR maakt.

De vereiste DCR-resources maken

Als u de op Microsoft Sentinel DCR gebaseerde Logstash-invoegtoepassing wilt configureren, moet u eerst de DCR-gerelateerde resources maken.

In deze sectie maakt u resources die u voor uw DCR wilt gebruiken in een van deze scenario's:

DCR-resources maken voor opname in een aangepaste tabel

Als u de gegevens wilt opnemen in een aangepaste tabel, volgt u deze stappen (op basis van de zelfstudie Gegevens verzenden naar Azure Monitor-logboeken met behulp van REST API (Azure Portal):

  1. Controleer de vereisten.

  2. Configureer de toepassing.

  3. Voeg een aangepaste logboektabel toe.

  4. Voorbeeldgegevens parseren en filteren met behulp van het voorbeeldbestand dat u in de vorige sectie hebt gemaakt.

  5. Verzamel informatie van de DCR.

  6. Wijs machtigingen toe aan de DCR.

    Sla de stap Voorbeeldgegevens verzenden over.

Als u problemen ondervindt, raadpleegt u de stappen voor probleemoplossing.

DCR-resources maken voor opname in een standaardtabel

Als u de gegevens wilt opnemen in een standaardtabel zoals Syslog of CommonSecurityLog, gebruikt u een proces op basis van de zelfstudie Gegevens verzenden naar Azure Monitor-logboeken met behulp van REST API-sjablonen (Resource Manager-sjablonen). In de zelfstudie wordt uitgelegd hoe u gegevens opneemt in een aangepaste tabel, maar u kunt het proces eenvoudig aanpassen om gegevens op te nemen in een standaardtabel. De onderstaande stappen geven relevante wijzigingen in de stappen aan.

  1. Controleer de vereisten.

  2. Werkruimtegegevens verzamelen.

  3. Configureer een toepassing.

    Sla de stap Nieuwe tabel maken in Log Analytics-werkruimte over. Deze stap is niet relevant bij het opnemen van gegevens in een standaardtabel, omdat de tabel al is gedefinieerd in Log Analytics.

  4. Maak de DCR. In deze stap:

    • Geef het voorbeeldbestand op dat u in de vorige sectie hebt gemaakt.
    • Gebruik het voorbeeldbestand dat u hebt gemaakt om de streamDeclarations eigenschap te definiëren. Elk van de velden in het voorbeeldbestand moet een overeenkomende kolom met dezelfde naam en het juiste type hebben (zie het onderstaande voorbeeld ).
    • Configureer de waarde van de outputStream eigenschap met de naam van de standaardtabel in plaats van de aangepaste tabel. In tegenstelling tot aangepaste tabellen hebben _CL standaardtabelnamen het achtervoegsel niet.
    • Het voorvoegsel van de tabelnaam moet Microsoft- in plaats van Custom-. In ons voorbeeld is Microsoft-Syslogde waarde van de outputStream eigenschap .

  5. Wijs machtigingen toe aan een DCR.

    Sla de stap Voorbeeldgegevens verzenden over.

Als u problemen ondervindt, raadpleegt u de stappen voor probleemoplossing.

Voorbeeld: DCR waarmee gegevens worden opgenomen in de Syslog-tabel

Opmerking:

  • De streamDeclarations kolomnamen en -typen moeten hetzelfde zijn als de voorbeeldbestandsvelden, maar u hoeft niet alle velden op te geven. In de onderstaande PRIDCR worden de velden type en ls_version velden bijvoorbeeld weggelaten uit de streamDeclarations kolom.
  • De dataflows eigenschap transformeert de invoer in de Syslog-tabelindeling en stelt de waarde outputStream in op 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'))]"
		}
	}
}

Logstash-configuratiebestand configureren

Als u het Logstash-configuratiebestand wilt configureren om de logboeken op te nemen in een aangepaste tabel, haalt u deze waarden op:

Veld Ophalen
client_app_Id De Application (client) ID waarde die u in stap 3 maakt wanneer u de DCR-resources maakt, volgens de zelfstudie die u in deze sectie hebt gebruikt.
client_app_secret De Application (client) ID waarde die u in stap 5 maakt wanneer u de DCR-resources maakt, volgens de zelfstudie die u in deze sectie hebt gebruikt.
tenant_id De tenant-id van uw abonnement. U vindt de tenant-id onder Overzicht basisinformatie over > Microsoft Entra-id > > voor Thuisgebruik.
data_collection_endpoint De waarde van de logsIngestion URI in stap 3 wanneer u de DCR-resources maakt, volgens de zelfstudie die u in deze sectie hebt gebruikt.
dcr_immutable_id De waarde van de DCR immutableId in stap 6 wanneer u de DCR-resources maakt, volgens de zelfstudie die u in deze sectie hebt gebruikt.
dcr_stream_name Voor aangepaste tabellen, zoals uitgelegd in stap 6 wanneer u de DCR-resources maakt, gaat u naar de JSON-weergave van de DCR en kopieert u de dataFlows>streams eigenschap. Zie het dcr_stream_name onderstaande voorbeeld .

Voor standaardtabellen is Custom-SyslogStreamde waarde .

Nadat u de vereiste waarden hebt opgehaald:

  1. Vervang de uitvoersectie van het Logstash-configuratiebestand dat u in de vorige stap hebt gemaakt door het onderstaande voorbeeld.
  2. Vervang de tijdelijke aanduidingen voor tekenreeksen in het onderstaande voorbeeld door de waarden die u hebt opgehaald.
  3. Zorg ervoor dat u het create_sample_file kenmerk wijzigt in false.

Optionele configuratie

Veld Beschrijving Default value
azure_cloud Wordt gebruikt om de naam op te geven van de Azure-cloud die wordt gebruikt, beschikbare waarden zijn: AzureCloud, AzureChinaClouden AzureUSGovernment. AzureCloud
key_names Een matrix met tekenreeksen. Geef dit veld op als u een subset van de kolommen naar Log Analytics wilt verzenden. Geen (veld is leeg)
plugin_flush_interval Definieert het maximale tijdsverschil (in seconden) tussen het verzenden van twee berichten naar Log Analytics. 5
retransmission_time Hiermee stelt u de hoeveelheid tijd in seconden in voor het opnieuw verzenden van berichten zodra het verzenden is mislukt. 10
compress_data Wanneer dit veld is True, worden de gebeurtenisgegevens gecomprimeerd voordat u de API gebruikt. Aanbevolen voor pijplijnen met hoge doorvoer. False
proxy Geef op welke proxy-URL moet worden gebruikt voor alle API-aanroepen. Geen (veld is leeg)
proxy_aad Geef op welke proxy-URL moet worden gebruikt voor API-aanroepen naar Microsoft Entra-id. Dezelfde waarde als 'proxy' (veld is leeg)
proxy_endpoint Geef op welke proxy-URL moet worden gebruikt voor API-aanroepen naar het eindpunt voor gegevensverzameling. Dezelfde waarde als 'proxy' (veld is leeg)

Voorbeeld: configuratiesectie van de uitvoerinvoegtoepassing

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

Als u andere parameters wilt instellen voor de Microsoft Sentinel Logstash-uitvoerinvoegtoepassing, raadpleegt u het leesmij-bestand van de uitvoerinvoegtoepassing.

Notitie

Om veiligheidsredenen raden we u aan niet impliciet de client_app_Idkenmerken , client_app_secret, tenant_iddata_collection_endpointen dcr_immutable_id kenmerken in uw Logstash-configuratiebestand te vermelden. U wordt aangeraden deze gevoelige informatie op te slaan in een Logstash KeyStore.

Logstash opnieuw starten

Start Logstash opnieuw met de bijgewerkte configuratie van de uitvoerinvoegtoepassing en zie dat gegevens worden opgenomen in de juiste tabel volgens uw DCR-configuratie.

Binnenkomende logboeken weergeven in Microsoft Sentinel

  1. Controleer of berichten naar de uitvoerinvoegtoepassing worden verzonden.

  2. Klik in het navigatiemenu van Microsoft Sentinel op Logboeken. Vouw onder de kop Tabellen de categorie Aangepaste logboeken uit. Zoek en klik op de naam van de tabel die u hebt opgegeven (met een _CL achtervoegsel) in de configuratie.

    Schermopname van aangepaste logboeken opgeslagen logboeken.

  3. Als u records in de tabel wilt zien, voert u een query uit op de tabel met behulp van de tabelnaam als het schema.

    Schermopname van een aangepaste logboekquery voor logboeken.

Auditlogboeken van de uitvoerinvoegtoepassing controleren

Als u de connectiviteit en activiteit van de Microsoft Sentinel-uitvoerinvoegtoepassing wilt bewaken, schakelt u het juiste Logstash-logboekbestand in. Zie het document voor de indeling van de Logstash-map voor de locatie van het logboekbestand.

Als u geen gegevens in dit logboekbestand ziet, genereert en verzendt u enkele gebeurtenissen lokaal (via de invoer- en filterinvoegtoepassingen) om ervoor te zorgen dat de uitvoerinvoegtoepassing gegevens ontvangt. Microsoft Sentinel biedt alleen ondersteuning voor problemen met betrekking tot de uitvoerinvoegtoepassing.

Netwerkbeveiliging

Netwerkinstellingen definiëren en netwerkisolatie inschakelen voor microsoft Sentinel Logstash-uitvoerinvoegtoepassing.

Servicetags voor virtueel netwerk

De Microsoft Sentinel-uitvoerinvoegtoepassing ondersteunt servicetags voor virtuele Netwerken van Azure. Zowel AzureMonitor - als AzureActiveDirectory-tags zijn vereist.

Azure Virtual Network-servicetags kunnen worden gebruikt om netwerktoegangsbeheer te definiëren voor netwerkbeveiligingsgroepen, Azure Firewall en door de gebruiker gedefinieerde routes. Gebruik servicetags in plaats van specifieke IP-adressen wanneer u beveiligingsregels en routes maakt. Voor scenario's waarin azure Virtual Network-servicetags niet kunnen worden gebruikt, worden de firewallvereisten hieronder gegeven.

Firewallvereisten

De volgende tabel bevat de firewallvereisten voor scenario's waarin servicetags voor virtuele Azure-netwerken niet kunnen worden gebruikt.

Cloud Eindpunt Doel Poort Richting HTTPS-inspectie overslaan
Azure Commercial https://login.microsoftonline.com Autorisatieserver (het Microsoft Identity Platform) Poort 443 Uitgaand Ja
Azure Commercial https://<data collection endpoint name>.<Azure cloud region>.ingest.monitor.azure.com Eindpunt voor gegevensverzameling Poort 443 Uitgaand Ja
Azure Government https://login.microsoftonline.us Autorisatieserver (het Microsoft Identity Platform) Poort 443 Uitgaand Ja
Azure Government Vervang '.com' hierboven door '.us' Eindpunt voor gegevensverzameling Poort 443 Uitgaand Ja
Microsoft Azure beheerd door 21Vianet https://login.chinacloudapi.cn Autorisatieserver (het Microsoft Identity Platform) Poort 443 Uitgaand Ja
Microsoft Azure beheerd door 21Vianet Vervang '.com' hierboven door '.cn' Eindpunt voor gegevensverzameling Poort 443 Uitgaand Ja

Beperkingen

  • Opname in standaardtabellen is alleen beperkt tot standaardtabellen die worden ondersteund voor opname van aangepaste logboeken.
  • De kolommen van de invoerstroom in de streamDeclarations eigenschap moeten beginnen met een letter. Als u een kolom met andere tekens start (bijvoorbeeld @ of _), mislukt de bewerking.
  • Het TimeGenerated datum/tijd-veld is vereist. U moet dit veld opnemen in de KQL-transformatie.
  • Raadpleeg de sectie probleemoplossing in de zelfstudie voor aanvullende mogelijke problemen.

Volgende stappen

In dit artikel hebt u geleerd hoe u Logstash gebruikt om externe gegevensbronnen te verbinden met Microsoft Sentinel. Zie de volgende artikelen voor meer informatie over Microsoft Sentinel: