Utiliser Logstash pour diffuser en continu les journaux avec l’API de collecte de données HTTP (héritée)

  • Article

Important

La fonctionnalité d'ingestion de données à l'aide du plug-in de sortie Logstash est actuellement en préversion publique. Cette fonctionnalité est fournie sans contrat de niveau de service et est déconseillée pour les charges de travail de production. Pour plus d’informations, consultez Conditions d’Utilisation Supplémentaires relatives aux Évaluations Microsoft Azure.

Notes

Une version plus récente du plug-in Logstash peut transférer des journaux à partir de sources de données externes vers des tables personnalisées et standard à l’aide de l’API basée sur DCR. Le nouveau plug-in permet un contrôle total sur le schéma de sortie, y compris la configuration des noms et types de colonnes.

Le plug-in de sortie Microsoft Sentinel dédié au moteur de collecte de données Logstash permet d’utiliser Logstash pour envoyer tout type de journaux à votre espace de travail Log Analytics dans Microsoft Sentinel. Vos journaux seront envoyés à une table personnalisée que vous définirez à l'aide du plug-in de sortie. Cette version du plug-in utilise l’API de collecte de données HTTP.

Pour en savoir plus sur l'utilisation du moteur de collecte de données Logstash, consultez Prise en main de Logstash.

Vue d’ensemble

Architecture et contexte

Diagram of the Logstash architecture.

Le moteur Logstash est constitué de trois composants :

  • Plug-ins d’entrée : collection personnalisée de données provenant de sources diverses.
  • Plug-ins de filtrage : manipulation et normalisation des données en fonction de critères spécifiés.
  • Plug-ins de sortie : envoi personnalisé des données collectées et traitées vers diverses destinations.

Notes

  • Microsoft prend en charge uniquement le plug-in de sortie Logstash fourni par Microsoft Sentinel abordé ici. La version actuelle de ce plug-in est v1.0.0, publiée le 25/08/2020. Vous pouvez ouvrir un ticket de support pour tous les problèmes concernant le plug-in de sortie.

  • Microsoft ne prend pas en charge les plug-ins de sortie Logstash tiers pour Microsoft Sentinel, ni aucun autre plug-in Logstash de quelque type que ce soit.

  • Le plug-in de sortie Logstash de Microsoft Sentinel prend uniquement en charge les versions 7.0 à 7.17.10 de Logstash, et les versions 8.0 à 8.9 et 8.11. Si vous utilisez Logstash 8, nous vous recommandons de désactiver ECS dans le pipeline.

Le plug-in de sortie Microsoft Sentinel pour Logstash envoie des données au format JSON à votre espace de travail Log Analytics, en utilisant l’API REST du collecteur de données HTTP de Log Analytics. Les données sont ingérées dans des journaux personnalisés.

Déployer le plug-in de sortie Microsoft Sentinel dans Logstash

Étape 1 : Installation

Le plug-in de sortie Microsoft Sentinel est disponible dans la collection Logstash.

Étape 2 : Configuration

Utilisez les informations du document Structure d’un fichier de configuration de Logstash et ajoutez le plug-in de sortie Microsoft Sentinel à la configuration avec les clés et valeurs suivantes. (La syntaxe appropriée du fichier de configuration est indiquée après le tableau.)

Nom du champ Type de données Description
workspace_id string Entrez le GUID de l’ID de votre espace de travail (voir les conseils).
workspace_key string Entrez le GUID de la clé primaire de votre espace de travail (voir les conseils).
custom_log_table_name string Définissez le nom de la table dans laquelle les journaux seront ingérés. Vous ne pouvez configurer qu'un seul nom de table par plug-in de sortie. La table des journaux apparaîtra dans Microsoft Sentinel sous Journaux, dans Tables, catégorie Journaux personnalisés, avec le suffixe _CL.
endpoint string Champ facultatif. Par défaut, il s'agit du point de terminaison Log Analytics. Utilisez ce champ pour définir un autre point de terminaison.
time_generated_field string Champ facultatif. Cette propriété remplace le champ par défaut TimeGenerated dans Log Analytics. Entrez le nom du champ d'horodatage dans la source de données. Les données du champ doivent être conformes au format ISO 8601 (YYYY-MM-DDThh:mm:ssZ)
key_names tableau Entrez une liste de champs de schéma de sortie Log Analytics. Chaque élément de la liste doit être placé entre guillemets simples et les éléments séparés par des virgules, et toute la liste doit être placée entre crochets. Voir l'exemple ci-dessous.
plugin_flush_interval nombre Champ facultatif. Permet de définir l'intervalle maximum (en secondes) entre les transmissions de messages à Log Analytics. La valeur par défaut est 5.
amount_resizing boolean True ou false. Activez ou désactivez le mécanisme de mise à l'échelle automatique, qui ajuste la taille de la mémoire tampon des messages en fonction du volume de données de journal reçues.
max_items nombre Champ facultatif. S'applique uniquement si amount_resizing est défini sur « false ». Permet de fixer un plafond à la taille de la mémoire tampon des messages (dans les enregistrements). La valeur par défaut est 2000.
azure_resource_id string Champ facultatif. Définit l’ID de la ressource Azure où résident les données.
La valeur de l’ID de ressource est particulièrement utile si vous utilisez un RBAC dans le contexte de la ressource pour donne accès uniquement à des données spécifiques.

Conseil

  • Vous pouvez trouver l’ID et la clé primaire de l’espace de travail dans la ressource d’espace de travail, sous Gestion des agents.
  • Toutefois, étant donné que les informations d’identification et autres informations sensibles stockées en texte clair dans les fichiers de configuration ne sont pas conformes aux meilleures pratiques de sécurité, il est vivement recommandé d’utiliser le magasin de clés Logstash pour inclure en toute sécurité l'ID de l’espace de travail et la clé primaire de l’espace de travail dans la configuration. Pour obtenir des instructions, consultez la documentation d’Elastic.

Exemples de configurations

Voici quelques exemples de configurations qui utilisent des options différentes.

  • Configuration de base qui utilise un canal d’entrée 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"
      }
  }

  • Configuration de base qui utilise un canal d’entrée 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"
      }
  }

  • Configuration avancée :

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

  • Une configuration plus avancée permettant d’analyser un horodatage personnalisé et une chaîne JSON à partir de données de texte non structurées, puis de journaliser un ensemble de champs sélectionné dans Log Analytics avec l’horodatage extrait :

      # 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']
      }
  }

    Notes

    Visitez le dépôt GitHub du plug-in de sortie pour en savoir plus sur son fonctionnement interne, sa configuration et ses paramètres de performances.

Étape 3 : Redémarrer Logstash

Étape 4 : Afficher les journaux entrants dans Microsoft Sentinel

  1. Vérifiez que les messages sont envoyés au plug-in de sortie.

  2. Dans le menu de navigation de Microsoft Sentinel, cliquez sur Journaux. Sous l'en-tête Tables, développez la catégorie Journaux personnalisés. Recherchez et cliquez sur le nom de la table que vous avez spécifiée (avec le suffixe _CL) dans la configuration.

    Screenshot of log stash custom logs.

  3. Pour afficher les enregistrements de la table, interrogez-la en utilisant son nom comme schéma.

    Screenshot of a log stash custom logs query.

Surveiller les journaux d'audit du plug-in de sortie

Pour surveiller la connectivité et l’activité du plug-in de sortie Microsoft Sentinel, activez le fichier journal Logstash approprié. Consultez le document Structure des répertoires Logstash pour connaître l’emplacement du fichier journal.

Si vous ne voyez aucune donnée dans ce fichier journal, générez et envoyez des événements localement (via les plug-ins d'entrée et de filtrage) pour vous assurer que le plug-in de sortie reçoit des données. Microsoft Sentinel prendra uniquement en charge les problèmes liés au plug-in de sortie.

Étapes suivantes

Dans ce document, vous avez appris à utiliser Logstash pour connecter des sources de données externes à Microsoft Sentinel. Pour en savoir plus sur Microsoft Sentinel, consultez les articles suivants :