Usare Logstash per trasmettere i log con l'API raccolta dati HTTP (legacy)

  • Articolo

Importante

L'inserimento dei dati tramite il plug-in di output Logstash è attualmente disponibile in anteprima pubblica. Questa funzionalità viene fornita senza un contratto di servizio e non è consigliata per i carichi di lavoro di produzione. Per altre informazioni, vedere le Condizioni supplementari per l'uso delle anteprime di Microsoft Azure.

Nota

Una versione più recente del plug-in Logstash può inoltrare i log da origini dati esterne in tabelle personalizzate e standard usando l'API basata su DCR. Il nuovo plug-in consente il controllo completo sullo schema di output, inclusa la configurazione dei nomi e dei tipi di colonna.

Usando il plug-in di output di Microsoft Sentinel per il motore di raccolta dati Logstash, è possibile inviare qualsiasi tipo di log desiderato tramite Logstash direttamente all'area di lavoro Log Analytics in Microsoft Sentinel. I log verranno inviati a una tabella personalizzata definita usando il plug-in di output. Questa versione del plug-in usa l'API raccolta dati HTTP.

Per altre informazioni sull'uso del motore di raccolta dati Logstash, vedere Introduzione a Logstash.

Panoramica

Architettura e sfondo

Diagram of the Logstash architecture.

Il motore Logstash è costituito 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 di dati raccolti ed elaborati in varie destinazioni.

Nota

  • Microsoft supporta solo il plug-in di output Logstash fornito da Microsoft Sentinel descritto qui. La versione corrente di questo plug-in è v1.0.0, rilasciata 2020-08-25. È 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.

  • Il plug-in di output Logstash di Microsoft Sentinel supporta solo logstash versioni da 7.0 a 7.17.10 e versioni da 8.0 a 8.9 e 8.11. Se si usa Logstash 8, è consigliabile disabilitare ECS nella pipeline.

Il plug-in di output di Microsoft Sentinel per Logstash invia dati in formato JSON all'area di lavoro Log Analytics usando l'API REST dell'agente di raccolta dati HTTP di Log Analytics. I dati vengono inseriti in log personalizzati.

  • Altre informazioni sull'API REST di Log Analytics.
  • Altre informazioni sui log personalizzati.

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

Passaggio 1: Installazione

Il plug-in di output di Microsoft Sentinel è disponibile nella raccolta Logstash.

Passaggio 2: Configurazione

Usare le informazioni contenute nel documento Logstash Structure di un file di configurazione e aggiungere il plug-in di output di Microsoft Sentinel alla configurazione con le chiavi e i valori seguenti. La sintassi corretta del file di configurazione viene visualizzata dopo la tabella.

Nome campo Tipo di dati Descrizione
workspace_id stringa Immettere il GUID dell'ID dell'area di lavoro (vedere Suggerimento).
workspace_key stringa Immettere il GUID della chiave primaria dell'area di lavoro (vedere Suggerimento).
custom_log_table_name stringa Impostare il nome della tabella in cui verranno inseriti i log. È possibile configurare un solo nome di tabella per ogni plug-in di output. La tabella di log verrà visualizzata in Microsoft Sentinel in Log, in Tabelle nella categoria Log personalizzati, con un _CL suffisso.
endpoint stringa Campo facoltativo. Per impostazione predefinita, si tratta dell'endpoint di Log Analytics. Usare questo campo per impostare un endpoint alternativo.
time_generated_field stringa Campo facoltativo. Questa proprietà esegue l'override del campo TimeGenerated predefinito in Log Analytics. Immettere il nome del campo timestamp nell'origine dati. I dati nel campo devono essere conformi al formato ISO 8601 (YYYY-MM-DDThh:mm:ssZ)
key_names array Immettere un elenco di campi dello schema di output di Log Analytics. Ogni voce di elenco deve essere racchiusa tra virgolette singole e gli elementi separati da virgole e l'intero elenco racchiuso tra parentesi quadre. Vedi l'esempio seguente.
plugin_flush_interval Numero Campo facoltativo. Impostare per definire l'intervallo massimo , espresso in secondi, tra le trasmissioni dei messaggi a Log Analytics. L'impostazione predefinita è 5.
amount_resizing boolean True o false. Abilitare o disabilitare il meccanismo di ridimensionamento automatico, che regola le dimensioni del buffer dei messaggi in base al volume dei dati di log ricevuti.
max_items Numero Campo facoltativo. Si applica solo se amount_resizing è impostato su "false". Usare per impostare un limite per le dimensioni del buffer dei messaggi (nei record). Il valore predefinito è 2000.
azure_resource_id stringa Campo facoltativo. Definisce l'ID della risorsa di Azure in cui si trovano i dati.
Il valore dell'ID risorsa è particolarmente utile se si usa il controllo degli accessi in base al ruolo del contesto delle risorse per fornire l'accesso solo a dati specifici.

Suggerimento

  • È possibile trovare l'ID dell'area di lavoro e la chiave primaria nella risorsa dell'area di lavoro, in Gestione agenti.
  • Tuttavia, poiché la presenza di credenziali e altre informazioni riservate archiviate in testo non crittografato nei file di configurazione non è conforme alle procedure consigliate per la sicurezza, è consigliabile usare l'archivio chiavi Logstash per includere in modo sicuro l'IDdell'area di lavoro e la chiave primaria dell'area di lavoro nella configurazione. Per istruzioni, vedere la documentazione di Elastic.

Configurazioni di esempio

Ecco alcune configurazioni di esempio che usano alcune opzioni diverse.

  • Configurazione di base che usa una pipe di input filebeat:

      input {
      beats {
          port => "5044"
      }
  }
  filter {
  }
  output {
      microsoft-logstash-output-azure-loganalytics {
        workspace_id => "<your workspace id>"
        workspace_key => "<your workspace key>"
        custom_log_table_name => "tableName"
      }
  }

  • Configurazione di base che usa una pipe di input TCP:

      input {
      tcp {
          port => "514"
          type => syslog #optional, will effect log type in table
      }
  }
  filter {
  }
  output {
      microsoft-logstash-output-azure-loganalytics {
        workspace_id => "<your workspace id>"
        workspace_key =>  "<your workspace key>"
        custom_log_table_name => "tableName"
      }
  }

  • Configurazione avanzata:

      input {
      tcp {
          port => 514
          type => syslog
      }
  }
  filter {
      grok {
          match => { "message" => "<%{NUMBER:PRI}>1 (?<TIME_TAG>[0-9]{4}-[0-9]{1,2}-[0-9]{1,2}T[0-9]{1,2}:[0-9]{1,2}:[0-9]{1,2})[^ ]* (?<HOSTNAME>[^ ]*) %{GREEDYDATA:MSG}" }
      }
  }
  output {
      microsoft-logstash-output-azure-loganalytics {
          workspace_id => "<WS_ID>"
          workspace_key => "${WS_KEY}"
          custom_log_table_name => "logstashCustomTable"
          key_names => ['PRI','TIME_TAG','HOSTNAME','MSG']
          plugin_flush_interval => 5
      }
  }

  • Una configurazione più avanzata per analizzare un timestamp personalizzato e una stringa JSON da dati di testo non strutturati e registrare un set selezionato di campi in Log Analytics con il timestamp estratto:

      # Example log line below:
  # Mon Nov 07 20:45:08 2022: { "name":"_custom_time_generated", "origin":"test_microsoft", "sender":"test@microsoft.com", "messages":1337}
  # take an input
  input {
      file {
          path => "/var/log/test.log"
      }
  }
  filter {
  # extract the header timestamp and the Json section
      grok {
          match => {
              "message" => ["^(?<timestamp>.{24}):\s(?<json_data>.*)$"]
          }
      }
  # parse the extracted header as a timestamp
  date {
      id => 'parse_metric_timestamp'
          match => [ 'timestamp', 'EEE MMM dd HH:mm:ss yyyy' ]
          timezone => 'Europe/Rome'
          target => 'custom_time_generated'
      }
  json {
      source => "json_data"
      }
  }
  # output to a file for debugging (optional)
  output {
      file {
          path => "/tmp/test.txt"
          codec => line { format => "custom format: %{message} %{custom_time_generated} %{json_data}"}
      }
  }
  # output to the console output for debugging (optional)
  output {
      stdout { codec => rubydebug }
  }
  # log into Log Analytics
  output {
      microsoft-logstash-output-azure-loganalytics {
          workspace_id => '[REDACTED]'
          workspace_key => '[REDACTED]'
          custom_log_table_name => 'RSyslogMetrics'
          time_generated_field => 'custom_time_generated'
          key_names => ['custom_time_generated','name','origin','sender','messages']
      }
  }

    Nota

    Visitare il repository GitHub del plug-in di output per altre informazioni sulle funzioni interne, la configurazione e le impostazioni delle prestazioni.

Passaggio 3: Riavviare Logstash

Passaggio 4: Visualizzare i log in ingresso in Microsoft Sentinel

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

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

    Screenshot of log stash custom logs.

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

    Screenshot of a log stash custom logs query.

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 Logstash Directory Layout (Layout 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.

Passaggi successivi

In questo documento si è appreso come usare Logstash per connettere origini dati esterne a Microsoft Sentinel. Per altre informazioni su Microsoft Sentinel, vedere gli articoli seguenti: