Stream loggar för att Microsoft Sentinel med Logstash- och DCR-baserat API

Microsoft Sentinel logstash-utdata-plugin-programmet stöder pipelinetransformeringar och avancerad konfiguration via datainsamlingsregler (DCR). Plugin-programmet vidarebefordrar loggar från externa datakällor till anpassade tabeller eller standardtabeller i Log Analytics eller Microsoft Sentinel.

I den här artikeln får du lära dig hur du konfigurerar Logstash-plugin-programmet för att strömma data till Log Analytics eller Microsoft Sentinel med dcrs, med fullständig kontroll över utdataschemat.

Med plugin-programmet kan du:

• Kontrollera konfigurationen av kolumnnamnen och typerna.
• Utför inmatningstidstransformeringar som filtrering eller berikning.
• Mata in anpassade loggar i en anpassad tabell eller mata in en Syslog-indataström i Log Analytics Syslog-tabellen.

Inmatning i standardtabeller är begränsad till standardtabeller som stöds för inmatning av anpassade loggar.

Mer information om hur du arbetar med Logstash-datainsamlingsmotorn finns i Komma igång med Logstash.

Översikt över arkitektur

Logstash-motorn består av tre komponenter:

• Plugin-program för indata: Anpassad insamling av data från olika källor.
• Filter-plugin-program: Manipulering och normalisering av data enligt angivna kriterier.
• Plugin-program för utdata: Anpassad sändning av insamlade och bearbetade data till olika mål.

Plugin-programmet skickar JSON-formaterade data till Log Analytics-arbetsytan med hjälp av LOGS Ingestion-API:et. Data matas in i anpassade loggar eller i en standardtabell.

• Läs mer om API:et för logginmatning.

Distribuera plugin-programmet för Microsoft Sentinel-utdata i Logstash

Så här konfigurerar du plugin-programmet:

• Granska förutsättningarna
• Installera plugin-programmet
• Skapa en exempelfil
• Skapa nödvändiga DCR-relaterade resurser
• Konfigurera Logstash-konfigurationsfilen
• Starta om Logstash
• Visa inkommande loggar i Microsoft Sentinel
• Övervaka granskningsloggar för plugin-utdata

Krav för Logstash-plugin-programmet

• Installera en version av Logstash som stöds. Plugin-programmet stöder följande Logstash-versioner:

  • 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

  Obs!

  Om du använder Logstash 8 rekommenderar vi att du inaktiverar ECS i pipelinen.

• Kontrollera att du har en Log Analytics-arbetsyta med minst deltagarbehörighet.

• Kontrollera att du har behörighet att skapa DCR-objekt på arbetsytan.

Installera plugin-programmet

Plugin-programmet Microsoft Sentinel utdata är tillgängligt i Logstash-samlingen på RubyGems.

• Följ anvisningarna i dokumentet Logstash Working with plugins (Arbeta med plugin-program ) för att installera plugin-programmet microsoft-sentinel-log-analytics-logstash-output-plugin . Kör följande kommando för att installera till en befintlig Logstash-installation:

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

• Om ditt Logstash-system inte har internetåtkomst följer du anvisningarna i dokumentet Logstash Offline Plugin Management för att förbereda och använda ett offline-plugin-paket. (Detta kräver att du skapar ett annat Logstash-system med internetåtkomst.)

Skapa en exempelfil

I det här avsnittet skapar du en exempelfil i något av följande scenarier:

• Skapa en exempelfil för anpassade loggar
• Skapa en exempelfil för att mata in loggar i syslog-tabellen

Skapa en exempelfil för anpassade loggar

I det här scenariot konfigurerar du logstash-indata-plugin-programmet för att skicka händelser till Microsoft Sentinel. I det här exemplet används plugin-programmet generatorindata för att simulera händelser. Du kan använda andra plugin-program för indata.

I det här exemplet ser Logstash-konfigurationsfilen ut så här:

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

Följ dessa steg för att skapa exempelfilen:

1. Kopiera plugin-konfigurationen för utdata nedan till logstash-konfigurationsfilen.

   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. Kontrollera att sökvägen till den refererade filen redan finns och starta sedan Logstash.

   Plugin-programmet skriver tio poster till en exempelfil med namnet sampleFile<epoch seconds>.json i den konfigurerade sökvägen när det finns 10 händelser att exempel på eller när Logstash-processen avslutas korrekt. Till exempel: c:\temp\sampleFile1648453501.json. Här är en del av en exempelfil som plugin-programmet skapar:

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

   Plugin-programmet lägger automatiskt till dessa egenskaper i varje post:

   • ls_timestamp: Tiden då posten tas emot från plugin-programmet för indata
   • ls_version: Logstash-pipelineversionen.

   Du kan ta bort de här fälten när du skapar domänkontrollanten.

Skapa en exempelfil för att mata in loggar i syslog-tabellen

I det här scenariot konfigurerar du logstash-indata-plugin-programmet för att skicka syslog-händelser till Microsoft Sentinel.

1. Om du inte redan har syslog-meddelanden vidarebefordrade till din Logstash-dator kan du använda loggningskommandot för att generera meddelanden. Till exempel (för 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
   

   Här är ett exempel på plugin-programmet logstash-indata:

   input {
        syslog {
            port => 514
       }
   }
   

2. Kopiera plugin-konfigurationen för utdata nedan till logstash-konfigurationsfilen.

   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. Kontrollera att filsökvägen redan finns och starta sedan Logstash.

   Plugin-programmet skriver tio poster till en exempelfil med namnet sampleFile<epoch seconds>.json i den konfigurerade sökvägen när det finns 10 händelser att exempel på eller när Logstash-processen avslutas korrekt. Till exempel: c:\temp\sampleFile1648453501.json. Här är en del av en exempelfil som plugin-programmet skapar:

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

   Plugin-programmet lägger automatiskt till dessa egenskaper i varje post:

   • ls_timestamp: Tiden då posten tas emot från plugin-programmet för indata
   • ls_version: Logstash-pipelineversionen.

   Du kan ta bort de här fälten när du skapar domänkontrollanten.

Skapa nödvändiga DCR-resurser

Om du vill konfigurera det Microsoft Sentinel DCR-baserade Logstash-plugin-programmet skapar du först dcr-relaterade resurser.

I det här avsnittet skapar du resurser som ska användas för din domänkontrollant i något av följande scenarier:

• Skapa DCR-resurser för inmatning i en anpassad tabell
• Skapa DCR-resurser för inmatning till en standardtabell

Skapa DCR-resurser för inmatning i en anpassad tabell

Om du vill mata in data till en anpassad tabell följer du dessa steg (baserat på självstudien Skicka data till Azure Övervaka loggar med hjälp av REST API (Azure Portal):

1. Granska förutsättningarna.

2. Konfigurera programmet.

3. Lägg till en anpassad loggtabell.

4. Parsa och filtrera exempeldata med exempelfilen som du skapade i föregående avsnitt.

5. Samla in information från DCR.

6. Tilldela behörigheter till domänkontrollanten.

   Hoppa över steget Skicka exempeldata.

Om du stöter på problem kan du läsa felsökningsstegen.

Skapa DCR-resurser för inmatning till en standardtabell

Om du vill mata in data till en standardtabell som Syslog eller CommonSecurityLog använder du en process som baseras på självstudiekursen Skicka data till Azure Övervaka loggar med hjälp av REST API (Resource Manager-mallar). I självstudien förklaras hur du matar in data i en anpassad tabell, men du kan enkelt justera processen för att mata in data i en standardtabell. Stegen nedan anger relevanta ändringar i stegen.

1. Granska förutsättningarna.

2. Samla in information om arbetsytan.

3. Konfigurera ett program.

   Hoppa över steget Skapa ny tabell i Log Analytics-arbetsytan. Det här steget är inte relevant när du matar in data i en standardtabell, eftersom tabellen redan har definierats i Log Analytics.

4. Skapa domänkontrollanten. I det här steget:

   • Ange exempelfilen som du skapade i föregående avsnitt.
   • Använd exempelfilen som du skapade för att definiera streamDeclarations egenskapen. Vart och ett av fälten i exempelfilen ska ha en motsvarande kolumn med samma namn och lämplig typ (se exemplet nedan).
   • Konfigurera värdet för outputStream egenskapen med namnet på standardtabellen i stället för den anpassade tabellen. Till skillnad från anpassade tabeller har standardtabellnamn inte suffixet _CL .
   • Prefixet för tabellnamnet ska vara Microsoft- i stället för Custom-. I det här exemplet är Microsoft-Syslogegenskapsvärdet outputStream .

5. Tilldela behörigheter till en domänkontrollant.

   Hoppa över steget Skicka exempeldata.

Om du stöter på problem kan du läsa felsökningsstegen.

Exempel: DCR som matar in data i Syslog-tabellen

Tänk på följande:

• Kolumnnamnen streamDeclarations och typerna ska vara samma som exempelfilfälten, men du behöver inte ange alla. I DCR nedan utelämnas till exempel fälten PRI, type och ls_version från streamDeclarations kolumnen .
• Egenskapen dataflows transformerar indata till Syslog-tabellformatet och anger outputStream till 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'))]"
    }
  }
}

Konfigurera Logstash-konfigurationsfilen

Plugin-programmet stöder två autentiseringsmetoder: tjänstens huvudnamn (klientautentiseringsuppgifter) och hanterad identitet (lösenordsfri). Välj den metod som passar din miljö.

Autentisering av tjänstens huvudnamn

Om du vill konfigurera Logstash-konfigurationsfilen för att mata in loggarna i en anpassad tabell med hjälp av autentisering med tjänstens huvudnamn hämtar du följande värden:

När du har hämtat de värden som krävs:

1. Ersätt utdataavsnittet i Logstash-konfigurationsfilen som du skapade i föregående steg med exemplet nedan.
2. Ersätt platshållarsträngarna i exemplet nedan med de värden som du hämtade.
3. Se till att du ändrar attributet create_sample_file till false.

Exempel: Konfiguration av plugin-programmet för utdata för tjänstens huvudnamn

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

Hanterad identitetsautentisering (lösenordsfri)

När managed_identity är inställt på trueautentiseras plugin-programmet utan en klienthemlighet. Plugin-programmet identifierar automatiskt lämplig identitetsmekanism vid körning i följande ordning:

1. AKS-arbetsbelastningsidentitet – Om miljövariablerna AZURE_CLIENT_ID, AZURE_TENANT_IDoch AZURE_FEDERATED_TOKEN_FILE finns (anges automatiskt av AKS) utför plugin-programmet ett OIDC-tokenutbyte.
2. Azure Arc – Om Azure Connected Machine Agent (azcmagent) identifieras på värden använder plugin-programmet slutpunkten Azure Arc-hanterad identitet för hybridservrar och lokala servrar.
3. IMDS – Annars återgår plugin-programmet till Azure Instance Metadata Service (IMDS) för Azure virtuella datorer och VMSS.

Nödvändig konfiguration för hanterad identitet:

Exempel: Systemtilldelad hanterad identitet

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

Exempel: Användartilldelad hanterad identitet

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

Valfri konfiguration

Starta om Logstash

Starta om Logstash med den uppdaterade plugin-konfigurationen för utdata. Kontrollera att data matas in i rätt tabell enligt dcr-konfigurationen.

Visa inkommande loggar i Microsoft Sentinel

Så här kontrollerar du att loggdata når din arbetsyta:

1. Kontrollera att meddelanden skickas till plugin-programmet för utdata.

2. På navigeringsmenyn Microsoft Sentinel väljer du Loggar. Under rubriken Tabeller expanderar du kategorin Anpassade loggar . Leta upp och välj namnet på den tabell som du angav (med ett _CL suffix) i konfigurationen.

   

3. Om du vill se poster i tabellen frågar du tabellen med tabellnamnet som schema.

   

Övervaka granskningsloggar för plugin-utdata

Om du vill övervaka anslutningen och aktiviteten för plugin-programmet Microsoft Sentinel utdata aktiverar du lämplig Logstash-loggfil. Se dokumentet Logstash-kataloglayout för loggfilens plats.

Om du inte ser några data i den här loggfilen genererar och skickar du några händelser lokalt via plugin-programmet för indata och filter för att kontrollera att plugin-programmet för utdata tar emot data. Microsoft Sentinel stöder endast problem som rör plugin-programmet för utdata.

Nätverkssäkerhet

Definiera nätverksinställningar och aktivera nätverksisolering för plugin-programmet Microsoft Sentinel Logstash-utdata.

Tjänsttaggar för virtuellt nätverk

Microsoft Sentinel plugin-program för utdata stöder Azure tjänsttaggar för virtuella nätverk. Både AzureMonitor - och AzureActiveDirectory-taggar krävs.

Azure Virtual Network tjänsttaggar kan användas för att definiera nätverksåtkomstkontroller i nätverkssäkerhetsgrupper, Azure Firewall och användardefinierade vägar. Använd tjänsttaggar i stället för specifika IP-adresser när du skapar säkerhetsregler och vägar. För scenarier där Azure Virtual Network tjänsttaggar inte kan användas anges brandväggskraven nedan.

Brandväggskrav

I följande tabell visas brandväggskraven för scenarier där Azure tjänsttaggar för virtuella nätverk inte kan användas.

Versionshistorik för plugin-program

2.1.0

• Händelsenormalisering har åtgärdats.

2.0.0

• Omstrukturerade plugin-programmet från Ruby till Java.
• ManagedIdentity-autentisering har lagts till.
• Flyttade kodbasen från GitHub till Azure DevOps.
• Stängd kodbas.

1.2.0

• Lägger till stöd för hanterad identitetsautentisering för Azure virtuella datorer/VMSS (systemtilldelad och användartilldelad via IMDS).
• Lägger till stöd för AKS-arbetsbelastningsidentitet via OIDC-tokenutbyte.
• Lägger till stöd för Azure Arc-hanterad identitet för hybridservrar och lokala servrar.
• Identifierar automatiskt autentiseringsmetod vid körning baserat på miljö (arbetsbelastningsidentitetsavvikelser, Arc-agent eller IMDS-återställning).
• Migrerar HTTP-klienten från excon till rest-client för förbättrad JRuby- och Logstash-plugin-ekosystemkompatibilitet.
• Byter namn på Azure Active Directory-referenser till Microsoft Entra ID.

1.1.4

• Begränsar excon biblioteksversionen till lägre än 1.0.0 för att säkerställa att porten alltid används när du använder en proxy.

1.1.3

• Ersätter det rest-client bibliotek som används för att ansluta till Azure med excon biblioteket.

1.1.1

• Lägger till stöd för Azure us government-moln och Microsoft Azure som drivs av 21Vianet i Kina.

1.1.0

• Tillåter inställning av olika proxyvärden för API-anslutningar.
• Uppgraderar versionen för logginmatnings-API till 2023-01-01.
• Byter namn på plugin-programmet till plugin-programmet microsoft-sentinel-log-analytics-logstash-output-plugin.

1.0.0

• Den första versionen för Logstash-utdata-plugin-programmet för Microsoft Sentinel. Det här plugin-programmet använder datainsamlingsregler (DCR: er) med Azure Monitor logs Ingestion API.

Kända problem

När du använder Logstash installerat på en Docker-avbildning av Lite Ubuntu kan följande varning visas:

java.lang.RuntimeException: getprotobyname_r failed

Lös det här felet genom att installera netbase-paketet i Din Dockerfile:

USER root
RUN apt install netbase -y

Mer information finns i JNR-regression i Logstash 7.17.0 (Docker).

Om din miljös händelsefrekvens är låg ökar du värdet för plugin_flush_interval till 60 eller mer. Du kan övervaka inmatningsnyttolasten med hjälp av DCR-mått. Mer information om plugin_flush_interval finns i den valfria konfigurationstabellen .

Begränsningar

• Inmatning i standardtabeller är begränsad till standardtabeller som stöds för inmatning av anpassade loggar.

• Kolumnerna i indataströmmen i streamDeclarations egenskapen måste börja med en bokstav. Om du startar en kolumn med andra tecken (till exempel @ eller _) misslyckas åtgärden.

• Fältet TimeGenerated datetime krävs. Du måste inkludera det här fältet i KQL-transformering.

• Ytterligare möjliga problem finns i felsökningsavsnittet i självstudien.