Strömma logg till Microsoft Sentinel med Logstash och DCR-baserat API

Microsoft Sentinels Logstash-utdataplugin stöder pipelineomvandlingar och avancerad konfiguration via datainsamlingsregler (DCR:er). 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 utdatapluginen för Microsoft Sentinel i Logstash

Så här konfigurerar du plugin-programmet:

• Gå igenom Logstash-pluginets förkunskaper
• 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 utdataplugin

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 (dessa versioner kräver en säkerhetsuppdatering, enligt Logstash)

  • 8.11 - 8.15 (dessa versioner kräver en säkerhetsuppdatering, enligt Logstash)

  • 8.19.2 (denna version kräver en säkerhetsuppdatering, enligt Logstash)

  • 9.0.8 (denna version kräver en säkerhetsuppdatering, enligt Logstash)

  • 9.1.10 (denna version kräver en säkerhetsuppdatering, enligt Logstash)

  • 9.2.4 - 9.2.5 (dessa versioner kräver en säkerhetsuppdatering, enligt Logstash)

  • 9.3.3

  • 9.4.0

    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

Microsoft Sentinel-utdatapluginen är tillgänglig 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-indatapluginen för att skicka händelser till Microsoft Sentinel. I det här exemplet används insticksprogrammet generator input för att simulera händelser. Du kan använda vilket annat insticksprogram för indata som helst.

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.

   Pluginen 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 sampla eller när Logstash-processen avslutas på ett kontrollerat sätt. 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
       ...
   
       ]    
   

   Pluginet lägger automatiskt till dessa egenskaper i varje post:

   • ls_timestamp: Tiden då posten tas emot från indatapluginet
   • ls_version: Logstash-pipelineversionen.

   Du kan ta bort dessa fält när du skapar DCR.

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

I det här scenariot konfigurerar du Logstash-indatapluginen 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å indatapluggen för Logstash:

   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.

   Pluginen 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 sampla eller när Logstash-processen avslutas på ett kontrollerat sätt. 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"
           }
   ]    
   
   

   Pluginet lägger automatiskt till dessa egenskaper i varje post:

   • ls_timestamp: Tiden då posten tas emot från indatapluginet
   • ls_version: Logstash-pipelineversionen.

   Du kan ta bort dessa fält när du skapar DCR.

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 i en anpassad tabell gör du så här (baserat på självstudien Skicka data till Azure Monitor Logs med REST API (Azure-portalen)):

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

   Hoppa över steget Skicka exempeldata.

Om du stöter på några problem, se felsökningsstegen i Logs Ingestion API.

Skapa DCR-resurser för inmatning till en standardtabell

Om du vill mata in data i en standardtabell som Syslog eller CommonSecurityLog använder du en process som baseras på självstudien Skicka data till Azure Monitor Logs med hjälp av REST-API:et (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 DCR:en. I det här steget:

   • Lämna in den provfil du skapade i Skapa en provfil.
   • 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 outputStreamegenskapsvärdet Microsoft-Syslog .

5. Tilldela behörigheter till en DCR.

   Hoppa över steget Skicka exempeldata.

Om du stöter på några problem, se felsökningsstegen i Logs Ingestion API.

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 med tjänsthuvudnamn

För att konfigurera Logstash-konfigurationsfilen att importera loggarna till en anpassad tabell med hjälp av service principal-autentisering, hämta följande värden: client_id, client_secret, , tenant_id, data_collection_endpoint, dcr_id, och stream_name.

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 utdataplugin för tjänsthuvudnamn

output {
    microsoft-sentinel-log-analytics-logstash-output-plugin {
      client_id => "<enter your client_id value here>"
      client_secret => "<enter your client_secret value here>"
      tenant_id => "<enter your tenant id here>"
      data_collection_endpoint => "<enter your logsIngestion URI here>"
      dcr_id => "<enter your DCR immutableId here>"
      stream_name => "<enter your stream name here>"
      create_sample_file=> false
      sample_file_path => "c:\\temp"
    }
}

Hanterad identitetsautentisering (lösenordsfri)

När du inte anger autentiseringsuppgifter för tjänstens huvudnamn (client_id, tenant_id och DefaultAzureCredential) autentiserar plugin-programmet med client_secret från Azure SDKs. DefaultAzureCredential försöker en sekvens av autentiseringsmetoder och använder den första som lyckas. I en servermiljö försöker man sig ut med relevanta metoder i denna ordning:

1. Miljövariabler: Läser inloggningsuppgifter från miljövariabler såsom AZURE_CLIENT_ID, AZURE_TENANT_ID, och AZURE_CLIENT_SECRET för att autentisera sig som tjänstehuvudansvarig.
2. Arbetsbelastningsidentitet: Om pluginet körs på en Azure-värd med arbetsbelastningsidentitet aktiverad (till exempel AKS med miljövariabeln AZURE_FEDERATED_TOKEN_FILE inställd), utför pluginet ett OIDC-tokenutbyte.
3. Hanterad identitet: Om värden har en hanterad identitet aktiverad, autentiserar pluginet genom att använda den identiteten. Denna metod täcker Azure-VM:er, Virtual Machine Scale Sets och Azure Arc-aktiverade servrar.

För hela sekvensen av inloggningsuppgifter som DefaultAzureCredential försöker, se Credential chains i Azure Identity-biblioteket för Java.

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

Exempel: Managed identity

output {
    microsoft-sentinel-log-analytics-logstash-output-plugin {
      data_collection_endpoint => "<enter your DCE logsIngestion URI here>"
      dcr_id => "<enter your DCR immutableId here>"
      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 utdatapluginen.

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 gör du en fråga mot tabellen genom att använda tabellnamnet som schema.

   

Övervaka granskningsloggar för utdataplugin

Om du vill övervaka anslutningen och aktiviteten för utdatapluginen för Microsoft Sentinel aktiverar du rätt loggfil för Logstash. Se dokumentet Logstash-kataloglayout för information om var loggfilen finns.

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 utdatapluginen.

Nätverkssäkerhet

Definiera nätverksinställningar och aktivera nätverksisolering för utdatapluginen för Microsoft Sentinel Logstash.

Tjänsttaggar för virtuellt nätverk

Microsoft Sentinel-plugin-programmet 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.5.0

• Tillägg av valfri proxykonfiguration per plugin för autentisering och inmatningstrafik med hjälp av proxy, proxy_aad, och proxy_endpoint.
• Uppdaterade Netty-handlare, HTTP-, HTTP/2- och DNS-komponenter från 4.1.133.Final till 4.1.136.Final.
• Uppdaterade Jackson Databind och Jackson Core från 2.18.6 till 2.18.8.

2.4.0

• Arbetstrådar körs nu som begränsade, av exekveraren schemalagda körningar: återställbara undantag loggas och arbetstråden fortsätter i nästa cykel; fatala JVM-fel loggas och kastas vidare.
• Fixad graciös avstängning så att batcher under flygning töms (batchers, sedan unifiers, sedan senders) innan arbetarna stannar, begränsade av max_graceful_shutdown_time_seconds.
• Lade till konfigurerbara tidsgränser för uppladdning connect_timeout_seconds (standardvärde 15) och write_timeout_seconds (standardvärde 60); anslutnings- och skrivtidsgränser försöks igen.
• Lade till tråd-ID, undantagstyp, batchstorlek och DCR-ström till batchfel-loggar.

2.3.3

• Fixerad förlust av numerisk och boolesk typ-fidelitet: fält som backas upp av Logstashs interna JRuby-typer (till exempel portar och byteantal) bevaras nu som inbyggda JSON-tal och booleaner istället för att konverteras till strängar, vilket säkerställer tillförlitlig inmatning i DCR:er med typade kolumner.

2.3.2

• Fixade tyst arbetstrådsdöd orsakad av oupptäckta undantag i arbetsprocesssloopen.
• Åtgärdade NullPointerException i SenderWorker när Azure returnerade en LogsUploadException med nullvärde som HTTP-svar.
• Lade till robust felhantering med spårning av på varandra följande fel för att minska risken för permanenta fel i arbetsprocesser.
• Lade till valfritt id konfigurationsvärde för telemetri.
• La till DCR-strömmen i loggningen av skickade batcher.

2.3.0

• Aktiverade funktionalitet med Logstash 9.4.
• Bumpade beroendeversioner för externa bibliotek (azure-sdk-bom, logback, slf4j, Netty).

2.2.1

• Lägger till en loggningslinje på informationsnivå när batcher skickas framgångsrikt.

2.2.0

• Lägger till möjligheten att använda antingen nya eller gamla konfigurationsvärden.

2.1.2

• Uppdateringar av dokumentationen.

2.1.0

• Korrigerade händelsenormalisering.

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 autentiseringsmetoden under körning baserat på miljön (miljövariabler för workload identity, Arc-agent eller IMDS i sista hand).
• 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-molnet 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å pluginet till microsoft-sentinel-log-analytics-logstash-output-plugin.

1.0.0

• Den första utgåvan av Logstash-utdatapluginen 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, öka värdet på max_waiting_time_for_batch_seconds och max_waiting_for_unifier_time_seconds till 60 eller mer. Du kan övervaka inmatningspayloaden med hjälp av DCR-måttvärden. För mer information om väntetidsvariablerna, se tabellen för valfri konfiguration .

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 datum och tid krävs. Du måste inkludera det här fältet i KQL-transformering.

• För ytterligare möjliga problem, granska felsökningsstegen i Logs Ingestion API.