Stream logboeken Microsoft Sentinel met logstash en OP DCR gebaseerde API

de Logstash-uitvoerinvoegtoepassing van Microsoft Sentinel ondersteunt pijplijntransformaties en geavanceerde configuratie via regels voor gegevensverzameling (DCR's). De invoegtoepassing stuurt logboeken van externe gegevensbronnen door naar aangepaste of standaardtabellen in Log Analytics of Microsoft Sentinel.

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

Met de invoegtoepassing kunt u het volgende doen:

• De configuratie van de kolomnamen en -typen beheren.
• Opnametijdtransformaties uitvoeren, zoals filteren of verrijken.
• Neem aangepaste logboeken op in een aangepaste tabel of neem een Syslog-invoerstroom op 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 meer informatie over het werken met de Logstash-engine voor gegevensverzameling.

Overzicht van 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: Aangepaste verzending van verzamelde en verwerkte gegevens naar verschillende bestemmingen.

De invoegtoepassing verzendt gegevens in JSON-indeling naar uw Log Analytics-werkruimte met behulp van de Logboekopname-API. De gegevens worden opgenomen in aangepaste logboeken of een standaardtabel.

• Meer informatie over de logboekopname-API.

De Microsoft Sentinel-uitvoerinvoegtoepassing implementeren in Logstash

Volg deze stappen om de invoegtoepassing in te stellen:

• De vereisten controleren
• De invoegtoepassing installeren
• Een voorbeeldbestand maken
• De vereiste DCR-gerelateerde resources maken
• Logstash-configuratiebestand configureren
• Logstash opnieuw starten
• Binnenkomende logboeken weergeven in Microsoft Sentinel
• Auditlogboeken van uitvoerinvoegtoepassingen bewaken

Vereisten voor logstash-invoegtoepassing

• 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.15
  • 8.19.2
  • 9.0.8
  • 9.1.10
  • 9.2.4 - 9.2.5

  Opmerking

  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 machtigingen hebt om DCR-objecten te maken in de werkruimte.

De invoegtoepassing installeren

De Microsoft Sentinel-uitvoerinvoegtoepassing is beschikbaar in de logstash-verzameling op RubyGems.

• Volg de instructies in het document Logstash Working with plugins om de invoegtoepassing microsoft-sentinel-log-analytics-logstash-output-plugin te installeren. Voer de volgende opdracht uit om te installeren op een bestaande Logstash-installatie:

  logstash-plugin install microsoft-sentinel-log-analytics-logstash-output-plugin
  

• Als uw Logstash-systeem geen internettoegang heeft, volgt u de instructies in het document Logstash Offline Plugin Management om een offline invoegtoepassingspakket voor te bereiden en te gebruiken. (Hiervoor moet een ander Logstash-systeem met internettoegang worden gebouwd.)

Een voorbeeldbestand maken

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

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

Een voorbeeldbestand maken voor aangepaste logboeken

In dit scenario configureert u de Logstash-invoerinvoegtoepassing om gebeurtenissen te verzenden naar Microsoft Sentinel. In dit voorbeeld wordt de invoerinvoegtoepassing voor de generator gebruikt om gebeurtenissen te simuleren. U kunt elke andere invoerinvoegtoepassing gebruiken.

In dit voorbeeld ziet het logstash-configuratiebestand er als volgt uit:

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

Voer de volgende stappen uit om het voorbeeldbestand te maken:

1. Kopieer de onderstaande configuratie van de uitvoerinvoegtoepassing 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. Zorg ervoor dat het bestandspad waarnaar wordt verwezen al bestaat en start vervolgens Logstash.

   De invoegtoepassing schrijft tien records naar een voorbeeldbestand met de naam sampleFile<epoch seconds>.json in het geconfigureerde pad zodra er tien gebeurtenissen zijn om een steekproef te nemen of wanneer het Logstash-proces correct wordt afgesloten. Bijvoorbeeld: c:\temp\sampleFile1648453501.json. Dit is een onderdeel 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 om syslog-gebeurtenissen te verzenden naar Microsoft Sentinel.

1. Als u nog geen syslog-berichten hebt doorgestuurd naar uw Logstash-computer, kunt u de opdracht logger 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
   

   Hier volgt een voorbeeld van de Logstash-invoerinvoegtoepassing:

   input {
        syslog {
            port => 514
       }
   }
   

2. Kopieer de onderstaande configuratie van de uitvoerinvoegtoepassing 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. Controleer of het bestandspad al bestaat en start Logstash.

   De invoegtoepassing schrijft tien records naar een voorbeeldbestand met de naam sampleFile<epoch seconds>.json in het geconfigureerde pad zodra er tien gebeurtenissen zijn om een steekproef te nemen of wanneer het Logstash-proces correct wordt afgesloten. Bijvoorbeeld: c:\temp\sampleFile1648453501.json. Dit is een onderdeel 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 Microsoft Sentinel op DCR gebaseerde Logstash-invoegtoepassing wilt configureren, maakt u eerst de DCR-gerelateerde resources.

In deze sectie maakt u resources voor gebruik voor uw DCR, in een van de volgende scenario's:

• DCR-resources maken voor opname in een aangepaste tabel
• DCR-resources maken voor opname in een standaardtabel

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 Logboeken bewaken met behulp van REST API (Azure Portal):

1. Controleer de vereisten.

2. Configureer de toepassing.

3. Een aangepaste logboektabel toevoegen.

4. Parseert en filter voorbeeldgegevens met behulp van het voorbeeldbestand dat u in de vorige sectie hebt gemaakt.

5. Gegevens verzamelen uit 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 Logboeken bewaken met behulp van REST API (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. Een toepassing configureren.

   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 bijbehorende kolom hebben met dezelfde naam en het juiste type (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 standaardtabelnamen niet het _CL achtervoegsel.
   • Het voorvoegsel van de tabelnaam moet Microsoft- in plaats van Custom-zijn. In dit voorbeeld is Microsoft-Syslogde eigenschapswaarde outputStream .

5. Machtigingen toewijzen aan een DCR.

   Sla de stap Voorbeeldgegevens verzenden over.

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

Voorbeeld: DCR die gegevens opneemt in de Syslog-tabel

Houd rekening met deze punten:

• De streamDeclarations kolomnamen en -typen moeten hetzelfde zijn als de voorbeeldbestandsvelden, maar u hoeft ze niet allemaal op te geven. In de onderstaande DCR worden bijvoorbeeld de PRIvelden , type en ls_version weggelaten uit de streamDeclarations kolom.
• De dataflows eigenschap transformeert de invoer naar de Syslog-tabelindeling en stelt de 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": "[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

De invoegtoepassing ondersteunt twee verificatiemethoden: service-principal (clientreferenties) en beheerde identiteit (zonder wachtwoord). Kies de methode die bij uw omgeving past.

Verificatie van service-principal

Als u het Logstash-configuratiebestand wilt configureren om de logboeken op te nemen in een aangepaste tabel met behulp van service-principal-verificatie, haalt u deze waarden op:

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 aanduidingstekenreeksen in het onderstaande voorbeeld door de waarden die u hebt opgehaald.
3. Zorg ervoor dat u het create_sample_file kenmerk wijzigt in false.

Voorbeeld: Configuratie van invoegtoepassing voor uitvoer van service-principal

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

Verificatie van beheerde identiteit (zonder wachtwoord)

Wanneer managed_identity is ingesteld op true, wordt de invoegtoepassing geverifieerd zonder een clientgeheim. De invoegtoepassing detecteert automatisch het juiste identiteitsmechanisme tijdens runtime in de volgende volgorde:

1. AKS Workload Identity : als de omgevingsvariabelen AZURE_CLIENT_ID, AZURE_TENANT_IDen AZURE_FEDERATED_TOKEN_FILE aanwezig zijn (automatisch ingesteld door AKS), voert de invoegtoepassing een OIDC-tokenuitwisseling uit.
2. Azure Arc: als de Azure Connected Machine Agent (azcmagent) wordt gedetecteerd op de host, gebruikt de invoegtoepassing het Azure door Arc beheerde identiteitseindpunt voor hybride en on-premises servers.
3. IMDS: anders valt de invoegtoepassing terug op de Azure Instance Metadata Service (IMDS) voor Azure VM's en VMSS.

Vereiste configuratie voor beheerde identiteit:

Voorbeeld: Door het systeem toegewezen beheerde identiteit

output {
    microsoft-sentinel-log-analytics-logstash-output-plugin {
      managed_identity => true
      data_collection_endpoint => "<enter your DCE logsIngestion URI here>"
      dcr_immutable_id => "<enter your DCR immutableId here>"
      dcr_stream_name => "<enter your stream name here>"
    }
}

Voorbeeld: Door de gebruiker toegewezen beheerde identiteit

output {
    microsoft-sentinel-log-analytics-logstash-output-plugin {
      managed_identity => true
      managed_identity_object_id => "<enter the object ID of your user-assigned identity>"
      data_collection_endpoint => "<enter your DCE logsIngestion URI here>"
      dcr_immutable_id => "<enter your DCR immutableId here>"
      dcr_stream_name => "<enter your stream name here>"
    }
}

Optionele configuratie

Logstash opnieuw starten

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

Binnenkomende logboeken weergeven in Microsoft Sentinel

Voer de volgende stappen uit om te controleren of logboekgegevens uw werkruimte bereiken:

1. Controleer of er berichten worden verzonden naar de uitvoerinvoegtoepassing.

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

   

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

   

Auditlogboeken van uitvoerinvoegtoepassingen bewaken

Als u de connectiviteit en activiteit van de Microsoft Sentinel-uitvoerinvoegtoepassing wilt bewaken, schakelt u het juiste Logboekbestand van Logstash in. Zie het document Logstash Directory Layout 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 ondersteunt alleen problemen met betrekking tot de uitvoerinvoegtoepassing.

Netwerkbeveiliging

Definieer netwerkinstellingen en schakel netwerkisolatie in voor de Microsoft Sentinel Logstash-uitvoerinvoegtoepassing.

Servicetags voor virtuele netwerken

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

Azure Virtual Network servicetags kunnen worden gebruikt voor het definiëren van netwerktoegangsbeheer 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 beschreven.

Firewallvereisten

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

Versiegeschiedenis van invoegtoepassing

2.1.0

• Gebeurtenisnormalisatie is opgelost.

2.0.0

• De invoegtoepassing is herstructureerd van Ruby naar Java.
• ManagedIdentity-verificatie toegevoegd.
• Codebasis verplaatst van GitHub naar Azure DevOps.
• Gesloten codebasis.

1.2.0

• Voegt ondersteuning voor verificatie van beheerde identiteit toe voor Azure VM's/VMSS (door het systeem toegewezen en door de gebruiker toegewezen via IMDS).
• Voegt ondersteuning voor AKS-workloadidentiteit toe via OIDC-tokenuitwisseling.
• Voegt Azure ondersteuning voor beheerde arc-identiteiten toe voor hybride en on-premises servers.
• Hiermee wordt de verificatiemethode tijdens runtime automatisch gedetecteerd op basis van de omgeving (workload identity env vars, Arc-agent of IMDS-terugval).
• Migreert HTTP-client van excon naar rest-client voor verbeterde compatibiliteit van JRuby- en Logstash-invoegtoepassingsecosysteem.
• Hiermee wijzigt u de naam van Azure Active Directory-verwijzingen naar Microsoft Entra ID.

1.1.4

• Hiermee wordt excon de bibliotheekversie beperkt tot lager dan 1.0.0 om ervoor te zorgen dat de poort altijd wordt gebruikt wanneer u een proxy gebruikt.

1.1.3

• Vervangt de rest-client bibliotheek die wordt gebruikt om verbinding te maken met Azure met de excon bibliotheek.

1.1.1

• Hiermee wordt ondersteuning toegevoegd voor Azure cloud van de Amerikaanse overheid en Microsoft Azure beheerd door 21Vianet in China.

1.1.0

• Hiermee kunt u verschillende proxywaarden instellen voor API-verbindingen.
• Hiermee wordt de versie voor logboekopname-API bijgewerkt naar 01-01-2023.
• Wijzigt de naam van de invoegtoepassing in microsoft-sentinel-log-analytics-logstash-output-plugin.

1.0.0

• De eerste release voor de Logstash-uitvoerinvoegtoepassing voor Microsoft Sentinel. Deze invoegtoepassing maakt gebruik van gegevensverzamelingsregels (DCR's) met de Logboekopname-API van Azure Monitor.

Bekende problemen

Wanneer u Logstash gebruikt die is geïnstalleerd op een Docker-installatiekopie van Lite Ubuntu, kan de volgende waarschuwing worden weergegeven:

java.lang.RuntimeException: getprotobyname_r failed

U kunt deze fout oplossen door het netbase-pakket in uw Dockerfile te installeren:

USER root
RUN apt install netbase -y

Zie JNR-regressie in Logstash 7.17.0 (Docker) voor meer informatie.

Als de gebeurtenissnelheid van uw omgeving laag is, verhoogt u de waarde van plugin_flush_interval naar 60 of meer. U kunt de nettolading voor opname bewaken met behulp van DCR-metrische gegevens. Zie de tabel Optionele configuratie voor meer informatie over plugin_flush_interval.

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 start met andere tekens (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.