Stream journaux à Microsoft Sentinel avec Logstash et l’API basée sur DCR

Le plug-in de sortie Logstash de Microsoft Sentinel prend en charge les transformations de pipeline et la configuration avancée via des règles de collecte de données (DCR). Le plug-in transfère les journaux des sources de données externes vers des tables personnalisées ou standard dans Log Analytics ou Microsoft Sentinel.

Dans cet article, découvrez comment configurer le plug-in Logstash pour diffuser des données dans Log Analytics ou Microsoft Sentinel à l’aide de DCR, avec un contrôle total sur le schéma de sortie.

Avec le plug-in, vous pouvez :

• Contrôlez la configuration des noms et des types de colonnes.
• Effectuez des transformations au moment de l’ingestion, telles que le filtrage ou l’enrichissement.
• Ingérer des journaux personnalisés dans une table personnalisée ou ingérer un flux d’entrée Syslog dans la table Syslog Log Analytics.

L’ingestion dans les tables standard est limitée uniquement aux tables standard prises en charge pour l’ingestion des journaux personnalisés.

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

Vue d’ensemble de l’architecture

Le moteur Logstash est composé de trois composants :

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

Le plug-in envoie des données au format JSON à votre espace de travail Log Analytics à l’aide de l’API d’ingestion des journaux. Les données sont ingérées dans des journaux personnalisés ou une table standard.

• En savoir plus sur l’API d’ingestion des journaux.

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

Pour configurer le plug-in, procédez comme suit :

• Passer en revue les prérequis
• Installer le plug-in
• Créer un exemple de fichier
• Créer les ressources DCR requises
• Configurer le fichier de configuration Logstash
• Redémarrer Logstash
• Afficher les journaux entrants dans Microsoft Sentinel
• Surveiller les journaux d’audit du plug-in de sortie

Prérequis du plug-in Logstash

• Installez une version prise en charge de Logstash. Le plug-in prend en charge les versions de Logstash suivantes :

  • 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

  Remarque

  Si vous utilisez Logstash 8, nous vous recommandons de désactiver ECS dans le pipeline.

• Vérifiez que vous disposez d’un espace de travail Log Analytics avec au moins contributeur droits.

• Vérifiez que vous disposez des autorisations nécessaires pour créer des objets DCR dans l’espace de travail.

Installer le plug-in

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

• Suivez les instructions du document Logstash Utilisation des plug-ins pour installer le plug-in microsoft-sentinel-log-analytics-logstash-output-plugin . Pour installer sur une installation Logstash existante, exécutez la commande suivante :

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

• Si votre système Logstash n’a pas accès à Internet, suivez les instructions du document Gestion des plug-ins hors connexion Logstash pour préparer et utiliser un pack de plug-ins hors connexion. (Cela nécessite la création d’un autre système Logstash avec accès à Internet.)

Créer un exemple de fichier

Dans cette section, vous allez créer un exemple de fichier dans l’un des scénarios suivants :

• Créer un exemple de fichier pour les journaux personnalisés
• Créer un exemple de fichier pour ingérer les journaux dans la table Syslog

Créer un exemple de fichier pour les journaux personnalisés

Dans ce scénario, vous configurez le plug-in d’entrée Logstash pour envoyer des événements à Microsoft Sentinel. Cet exemple utilise le plug-in d’entrée du générateur pour simuler des événements. Vous pouvez utiliser n’importe quel autre plug-in d’entrée.

Dans cet exemple, le fichier de configuration Logstash ressemble à ceci :

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

Pour créer l’exemple de fichier, procédez comme suit :

1. Copiez la configuration du plug-in de sortie ci-dessous dans votre fichier de configuration Logstash.

   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. Vérifiez que le chemin du fichier référencé existe déjà, puis démarrez Logstash.

   Le plug-in écrit dix enregistrements dans un exemple de fichier nommé sampleFile<epoch seconds>.json dans le chemin configuré une fois qu’il y a 10 événements à échantillonner ou lorsque le processus Logstash se termine correctement. Par exemple : c :\temp\sampleFile1648453501.json. Voici une partie d’un exemple de fichier créé par le plug-in :

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

   Le plug-in ajoute automatiquement ces propriétés à chaque enregistrement :

   • ls_timestamp: heure à laquelle l’enregistrement est reçu du plug-in d’entrée
   • ls_version: version du pipeline Logstash.

   Vous pouvez supprimer ces champs lorsque vous créez la DCR.

Créer un exemple de fichier pour ingérer les journaux dans la table Syslog

Dans ce scénario, vous configurez le plug-in d’entrée Logstash pour envoyer des événements syslog à Microsoft Sentinel.

1. Si vous n’avez pas encore de messages syslog transférés sur votre ordinateur Logstash, vous pouvez utiliser la commande enregistreur d’événements pour générer des messages. Par exemple (pour 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
   

   Voici un exemple pour le plug-in d’entrée Logstash :

   input {
        syslog {
            port => 514
       }
   }
   

2. Copiez la configuration du plug-in de sortie ci-dessous dans votre fichier de configuration Logstash.

   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. Vérifiez que le chemin du fichier existe déjà, puis démarrez Logstash.

   Le plug-in écrit dix enregistrements dans un exemple de fichier nommé sampleFile<epoch seconds>.json dans le chemin configuré une fois qu’il y a 10 événements à échantillonner ou lorsque le processus Logstash se termine correctement. Par exemple : c :\temp\sampleFile1648453501.json. Voici une partie d’un exemple de fichier créé par le plug-in :

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

   Le plug-in ajoute automatiquement ces propriétés à chaque enregistrement :

   • ls_timestamp: heure à laquelle l’enregistrement est reçu du plug-in d’entrée
   • ls_version: version du pipeline Logstash.

   Vous pouvez supprimer ces champs lorsque vous créez la DCR.

Créer les ressources DCR requises

Pour configurer l’Microsoft Sentinel plug-in Logstash basé sur DCR, commencez par créer les ressources associées à la DCR.

Dans cette section, vous allez créer des ressources à utiliser pour votre DCR, dans l’un des scénarios suivants :

• Créer des ressources DCR pour l’ingestion dans une table personnalisée
• Créer des ressources DCR pour l’ingestion dans une table standard

Créer des ressources DCR pour l’ingestion dans une table personnalisée

Pour ingérer les données dans une table personnalisée, procédez comme suit (en fonction du didacticiel Envoyer des données à Azure surveiller les journaux à l’aide de l’API REST (Portail Azure) ) :

1. Passez en revue les prérequis.

2. Configurez l’application.

3. Ajoutez une table de journaux personnalisée.

4. Analysez et filtrez les exemples de données à l’aide de l’exemple de fichier que vous avez créé dans la section précédente.

5. Collecter des informations à partir de la DCR.

6. Attribuez des autorisations à la DCR.

   Ignorez l’étape Envoyer un exemple de données.

Si vous rencontrez des problèmes, consultez les étapes de résolution des problèmes.

Créer des ressources DCR pour l’ingestion dans une table standard

Pour ingérer les données dans une table standard comme Syslog ou CommonSecurityLog, vous utilisez un processus basé sur le didacticiel Envoyer des données à Azure Surveiller les journaux à l’aide de l’API REST (modèles Resource Manager). Bien que le tutoriel explique comment ingérer des données dans une table personnalisée, vous pouvez facilement ajuster le processus pour ingérer des données dans une table standard. Les étapes ci-dessous indiquent les modifications pertinentes dans les étapes.

1. Passez en revue les prérequis.

2. Collecter les détails de l’espace de travail.

3. Configurer une application.

   Ignorez l’étape Créer une table dans l’espace de travail Log Analytics. Cette étape n’est pas pertinente lors de l’ingestion de données dans une table standard, car la table est déjà définie dans Log Analytics.

4. Créez la DCR. Dans cette étape :

   • Fournissez l’exemple de fichier que vous avez créé dans la section précédente.
   • Utilisez l’exemple de fichier que vous avez créé pour définir la streamDeclarations propriété . Chacun des champs de l’exemple de fichier doit avoir une colonne correspondante portant le même nom et le type approprié (voir l’exemple ci-dessous).
   • Configurez la valeur de la outputStream propriété avec le nom de la table standard au lieu de la table personnalisée. Contrairement aux tables personnalisées, les noms de table standard n’ont pas le _CL suffixe .
   • Le préfixe du nom de la table doit être Microsoft- au lieu de Custom-. Dans cet exemple, la valeur de la outputStream propriété est Microsoft-Syslog.

5. Attribuer des autorisations à une DCR.

   Ignorez l’étape Envoyer un exemple de données.

Si vous rencontrez des problèmes, consultez les étapes de résolution des problèmes.

Exemple : DCR qui ingère des données dans la table Syslog

Gardez ces points à l’esprit :

• Les streamDeclarations noms et types de colonnes doivent être identiques aux champs de l’exemple de fichier, mais vous n’avez pas à les spécifier tous. Par exemple, dans la DCR ci-dessous, les PRIchamps et typels_version sont omis de la streamDeclarations colonne .
• La dataflows propriété transforme l’entrée au format de table Syslog et affecte la outputStream valeur à 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'))]"
    }
  }
}

Configurer le fichier de configuration Logstash

Le plug-in prend en charge deux méthodes d’authentification : le principal de service (informations d’identification du client) et l’identité managée (sans mot de passe). Choisissez la méthode qui convient à votre environnement.

Authentification du principal de service

Pour configurer le fichier de configuration Logstash pour ingérer les journaux dans une table personnalisée à l’aide de l’authentification du principal de service, récupérez les valeurs suivantes :

Après avoir récupéré les valeurs requises :

1. Remplacez la section de sortie du fichier de configuration Logstash que vous avez créé à l’étape précédente par l’exemple ci-dessous.
2. Remplacez les chaînes d’espace réservé dans l’exemple ci-dessous par les valeurs que vous avez récupérées.
3. Veillez à remplacer l’attribut par create_sample_filefalse.

Exemple : configuration du plug-in de sortie du principal de service

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

Authentification d’identité managée (sans mot de passe)

Lorsque managed_identity est défini sur true, le plug-in s’authentifie sans clé secrète client. Le plug-in détecte automatiquement le mécanisme d’identité approprié au moment de l’exécution dans l’ordre suivant :

1. Identité de la charge de travail AKS : si les variables AZURE_CLIENT_IDd’environnement , AZURE_TENANT_IDet AZURE_FEDERATED_TOKEN_FILE sont présentes (définies automatiquement par AKS), le plug-in effectue un échange de jetons OIDC.
2. Azure Arc : si le Azure Connected Machine Agent (azcmagent) est détecté sur l’hôte, le plug-in utilise le point de terminaison d’identité managée Arc Azure pour les serveurs hybrides et locaux.
3. IMDS : sinon, le plug-in revient au Azure Instance Metadata Service (IMDS) pour Azure machines virtuelles et VMSS.

Configuration requise pour l’identité managée :

Exemple : identité managée affectée par le système

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

Exemple : identité managée affectée par l’utilisateur

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

Configuration facultative

Redémarrer Logstash

Redémarrez Logstash avec la configuration du plug-in de sortie mise à jour. Vérifiez que les données sont ingérées dans la table appropriée en fonction de votre configuration DCR.

Afficher les journaux entrants dans Microsoft Sentinel

Pour vérifier que les données de journal atteignent votre espace de travail, procédez comme suit :

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

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

   

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

   

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 Disposition du répertoire 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 filtre pour vous assurer que le plug-in de sortie reçoit des données. Microsoft Sentinel prend uniquement en charge les problèmes liés au plug-in de sortie.

Sécurité réseau

Définissez les paramètres réseau et activez l’isolation réseau pour le plug-in de sortie Microsoft Sentinel Logstash.

Étiquettes de service de réseau virtuel

Microsoft Sentinel plug-in de sortie prend en charge Azure balises de service de réseau virtuel. Les balises AzureMonitor et AzureActiveDirectory sont requises.

Azure Réseau virtuel étiquettes de service peuvent être utilisées pour définir des contrôles d’accès réseau sur les groupes de sécurité réseau, les Pare-feu Azure et les itinéraires définis par l’utilisateur. Utilisez des étiquettes de service au lieu d’adresses IP spécifiques lorsque vous créez des règles de sécurité et des itinéraires. Pour les scénarios où Azure Réseau virtuel étiquettes de service ne peuvent pas être utilisées, les exigences de pare-feu sont indiquées ci-dessous.

Configuration requise du pare-feu

Le tableau suivant répertorie les exigences de pare-feu pour les scénarios où Azure étiquettes de service de réseau virtuel ne peuvent pas être utilisées.

Historique des versions du plug-in

2.1.0

• Correction de la normalisation des événements.

2.0.0

• Refactorisé le plug-in de Ruby vers Java.
• Ajout de l’authentification ManagedIdentity.
• Déplacement du codebase de GitHub vers Azure DevOps.
• Codebase fermé.

1.2.0

• Ajoute la prise en charge de l’authentification d’identité managée pour Azure machines virtuelles/VMSS (affectée par le système et affectée par l’utilisateur via IMDS).
• Ajoute la prise en charge des identités de charge de travail AKS via l’échange de jetons OIDC.
• Ajoute Azure prise en charge des identités managées Arc pour les serveurs hybrides et locaux.
• Détecte automatiquement la méthode d’authentification au moment de l’exécution en fonction de l’environnement (identité de charge de travail env vars, agent Arc ou secours IMDS).
• Migre le client HTTP de à rest-client pour améliorer la compatibilité de excon l’écosystème des plug-ins JRuby et Logstash.
• Renomme Azure références Active Directory en Microsoft Entra ID.

1.1.4

• Limite la excon version de la bibliothèque à une version inférieure à 1.0.0 pour garantir que le port est toujours utilisé lors de l’utilisation d’un proxy.

1.1.3

• Remplace la rest-client bibliothèque utilisée pour la connexion à Azure par la excon bibliothèque.

1.1.1

• Ajoute la prise en charge du cloud Azure gouvernement des États-Unis et de Microsoft Azure gérés par 21Vianet en Chine.

1.1.0

• Permet de définir différentes valeurs de proxy pour les connexions d’API.
• Met à niveau la version de l’API d’ingestion des journaux vers 2023-01-01.
• Renomme le plug-in microsoft-sentinel-log-analytics-logstash-output-plugin.

1.0.0

• Version initiale du plug-in de sortie Logstash pour Microsoft Sentinel. Ce plug-in utilise des règles de collecte de données (DCR) avec l’API d’ingestion des journaux d’Azure Monitor.

Problèmes connus

Lors de l’utilisation de Logstash installé sur une image Docker de Lite Ubuntu, l’avertissement suivant peut s’afficher :

java.lang.RuntimeException: getprotobyname_r failed

Pour résoudre cette erreur, installez le package netbase dans votre fichier Dockerfile :

USER root
RUN apt install netbase -y

Pour plus d’informations, consultez Régression JNR dans Logstash 7.17.0 (Docker).

Si le taux d’événements de votre environnement est faible, augmentez la valeur de plugin_flush_interval à 60 ou plus. Vous pouvez surveiller la charge utile d’ingestion à l’aide des métriques DCR. Pour plus d’informations sur plugin_flush_interval, consultez le tableau de configuration facultatif .

Limitations

• L’ingestion dans les tables standard est limitée uniquement aux tables standard prises en charge pour l’ingestion des journaux personnalisés.

• Les colonnes du flux d’entrée dans la streamDeclarations propriété doivent commencer par une lettre. Si vous démarrez une colonne avec d’autres caractères (par exemple @ ou _), l’opération échoue.

• Le TimeGenerated champ datetime est obligatoire. Vous devez inclure ce champ dans la transformation KQL.

• Pour d’autres problèmes possibles, consultez la section résolution des problèmes dans le tutoriel.