Utiliser Logstash pour diffuser en continu des journaux avec des transformations de pipeline via l’API basée sur les règles de collecte de données
Important
La fonctionnalité d’ingestion de données à l’aide du plug-in de sortie Logstash avec des Règles de collecte des données (DCR) est actuellement en préversion publique. Cette fonctionnalité est fournie sans contrat de niveau de service. Pour plus d’informations, consultez Conditions d’Utilisation Supplémentaires relatives aux Évaluations Microsoft Azure.
Le nouveau 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 tout type de journaux provenant de sources de données externes dans des tables personnalisées ou standard dans Log Analytics ou Microsoft Sentinel.
Dans cet article, vous apprendrez à configurer le nouveau plug-in Logstash pour diffuser les données dans Log Analytics ou Microsoft Sentinel à l'aide de DCR, avec un contrôle total sur le schéma de sortie. Découvrez comment déployer le plug-in.
Notes
Une version précédente du plug-in Logstash vous permet de connecter des sources de données via Logstash avec l’API de collecte de données.
Avec le nouveau plug-in, vous pouvez :
- Contrôler la configuration des noms et des types de colonnes.
- Effectuer des transformations au moment de l’ingestion, comme le filtrage ou l’enrichissement.
- Ingérez des journaux personnalisés dans une table personnalisée ou ingérez un flux d'entrée Syslog dans la table Log Analytics Syslog.
L’ingestion dans des tables standard est limitée 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
Architecture et contexte
Le moteur Logstash se compose 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. Le plugin actuel est nommé microsoft-sentinel-log-analytics-logstash-output-plugin, v1.1.0. 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.
Consultez les conditions préalables à la prise en charge de la version Logstash du plug-in.
Le plug-in de sortie Microsoft Sentinel pour Logstash envoie des données au format JSON à votre espace de travail Log Analytics, à l'aide de l'API Log Analytics Log Ingestion. Les données sont ingérées dans des journaux personnalisés ou une table standard.
- En savoir plus sur l'API d'ingestion de journaux.
Déployer le plug-in de sortie Microsoft Sentinel dans Logstash
Pour configurer le plug-in, procédez comme suit :
- évaluer les prérequis
- Installation du plug-in
- Créer un exemple de fichier
- Créer les ressources liées aux règles de collecte de données 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
Configuration requise
Installez une version prise en charge de Logstash. Le plug-in prend en charge les versions Logstash suivantes :
- 7.0 - 7.17.13
- 8.0 - 8.9
- 8.11 – 8.13
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 des droits de contributeur.
Vérifiez que vous disposez des autorisations nécessaires pour créer des objets DCR dans l’espace de travail.
Installation du plug-in
Le plug-in de sortie Microsoft Sentinel est disponible dans la collection Logstash.
- Suivez les instructions du document Logstash Utilisation des plug-ins pour installer le plug-in microsoft-sentinel-log-analytics-logstash-output-plugin.
- Si votre système Logstash n'a pas accès à Internet, suivez les instructions du document Logstash Gestion des plug-ins hors connexion pour préparer et utiliser un pack de plug-ins hors connexion. (Il vous faudra pour cela créer 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 des 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. Pour cet exemple, nous utilisons 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 de Logstash ressemble à ceci :
input {
generator {
lines => [
"This is a test log message"
]
count => 10
}
}
Copiez la configuration de 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. } }Pour vous assurer que le chemin du fichier référencé existe avant de créer l’exemple de fichier, démarrez Logstash.
Le plug-in écrit dix enregistrements dans un exemple de fichier nommé
sampleFile<epoch seconds>.jsondans le chemin configuré. 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éels_version: version du pipeline Logstash.
Vous pouvez supprimer ces champs lorsque vous créez la règle de collecte de données.
Créer un exemple de fichier pour ingérer des 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.
Si vous n’avez pas encore de messages Syslog transférés vers votre ordinateur Logstash, vous pouvez utiliser la commande d’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 Here is an example for the Logstash input plugin: input { syslog { port => 514 } }Copiez la configuration de 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. } }Pour vous assurer que le chemin du fichier existe avant de créer l’exemple de fichier, démarrez Logstash.
Le plug-in écrit dix enregistrements dans un exemple de fichier nommé
sampleFile<epoch seconds>.jsondans le chemin configuré. 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éels_version: version du pipeline Logstash.
Vous pouvez supprimer ces champs lorsque vous créez la règle de collecte de données.
Créer les ressources liées aux règles de collecte de données requises
Pour configurer le plug-in Logstash basé sur les règles de collecte de données Microsoft Sentinel, vous devez d’abord créer les ressources liées aux règles de collecte de données.
Dans cette section, vous allez créer des ressources à utiliser pour vos règles de collecte de données, dans l’un des scénarios suivants :
- Créer des ressources de règles de collecte de données pour l’ingestion dans une table personnalisée
- Créer des ressources de règles de collecte de données pour l’ingestion dans une table standard
Créer des ressources de règles de collecte de données pour l’ingestion dans une table personnalisée
Pour ingérer les données dans une table personnalisée, procédez comme suit (en suivant le tutoriel Envoyer des données aux journaux Azure Monitor à l’aide de l’API REST (Portail Azure) ) :
Examinez les conditions préalables.
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.
Attribuer des autorisations à une règle 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 de règles de collecte de données 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 tutoriel Envoyer des données aux journaux Azure Monitor à 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.
Examinez les conditions préalables.
-
Passez 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.
Créez la règle de collecte de données. Au cours de cette étape :
- Fournissez le fichier d’exemple que vous avez créé dans la section précédente.
- Utilisez l’exemple de fichier que vous avez créé pour définir la propriété
streamDeclarations. 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 propriété
outputStreamavec 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 suffixe_CL. - Le préfixe du nom de la table doit être
Microsoft-au lieu deCustom-. Dans notre exemple, la valeur de la propriétéoutputStreamestMicrosoft-Syslog.
Attribuer des autorisations à une règle 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 : Règle de collecte de données qui ingère des données dans la table Syslog
Notez les points suivants :
- Les noms et types de colonnes
streamDeclarationsdoivent être identiques aux champs de l’exemple de fichier, mais vous n’avez pas besoin de les spécifier tous. Par exemple, dans la règle de collecte de données ci-dessous, les champsPRI,typeetls_versionsont omis de la colonnestreamDeclarations. - La propriété
dataflowstransforme l’entrée au format de table Syslog et définitoutputStreamsurMicrosoft-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": "westus2",
"allowedValues": [
"westus2",
"eastus2",
"eastus2euap"
],
"type": "String",
"metadata": {
"description": "Specifies the location in which to create the Data Collection Rule."
}
},
"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
Pour configurer le fichier de configuration Logstash afin d’ingérer les journaux dans une table personnalisée, récupérez les valeurs suivantes :
| Champ | Comment récupérer |
|---|---|
client_app_Id |
La valeur Application (client) ID que vous créez à l’étape 3 lorsque vous créez les ressources de règles de collecte de données, conformément au tutoriel que vous avez utilisé dans cette section. |
client_app_secret |
La valeur Application (client) ID que vous créez à l’étape 5 lorsque vous créez les ressources de règles de collecte de données, conformément au tutoriel que vous avez utilisé dans cette section. |
tenant_id |
ID de locataire de votre abonnement. Vous trouverez l’ID de locataire sous Accueil > Microsoft Entra ID > Vue d’ensemble > Informations de base. |
data_collection_endpoint |
La valeur de l’URI logsIngestion à l’étape 3 lorsque vous créez les ressources de règles de collecte de données, conformément au tutoriel que vous avez utilisé dans cette section. |
dcr_immutable_id |
La valeur de la règle de collecte de données immutableId à l’étape 6 lorsque vous créez les ressources de règles de collecte de données, conformément au tutoriel que vous avez utilisé dans cette section. |
dcr_stream_name |
Pour les tables personnalisées, comme expliqué à l’étape 6 lorsque vous créez les ressources de règles de collecte de données, accédez à la vue JSON de la règle de collecte de données, puis copiez la propriété dataFlows>streams. Voir dcr_stream_name dans l’exemple ci-dessous.Pour les tables standard, la valeur est Custom-SyslogStream. |
Après avoir récupéré les valeurs requises :
- Remplacez la section de sortie du fichier de configuration Logstash que vous avez créé à l’étape précédente par l’exemple ci-dessous.
- Remplacez les chaînes d’espace réservé dans l’exemple ci-dessous par les valeurs que vous avez récupérées.
- Veillez à remplacer l’attribut
create_sample_fileparfalse.
Configuration facultative
| Champ | Description | Valeur par défaut |
|---|---|---|
azure_cloud |
Sert à spécifier le nom du cloud Azure utilisé. Les valeurs disponibles sont les suivantes : AzureCloud, AzureChinaCloud et AzureUSGovernment. |
AzureCloud |
key_names |
Tableau de chaînes. Fournissez ce champ si vous souhaitez envoyer un sous-ensemble des colonnes à Log Analytics. | Aucun (champ vide) |
plugin_flush_interval |
Définit la différence de temps maximale (en secondes) entre l’envoi de deux messages à Log Analytics. | 5 |
retransmission_time |
Définit la durée en secondes de la retransmission des messages après l’échec de l’envoi. | 10 |
compress_data |
Lorsque ce champ est True, les données d’événement sont compressées avant d’utiliser l’API. Recommandé pour les pipelines à haut débit. |
False |
proxy |
Spécifiez l’URL de proxy à utiliser pour tous les appels d’API. | Aucun (champ vide) |
proxy_aad |
Spécifiez l'URL de proxy à utiliser pour les appels d'API vers Microsoft Entra ID. | Même valeur que 'proxy' (le champ est vide) |
proxy_endpoint |
Spécifiez l'URL proxy à utiliser pour les appels d'API vers le point de terminaison de collecte de données. | Même valeur que 'proxy' (le champ est vide) |
Exemple : Section de configuration du plug-in de sortie
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"
proxy => "http://proxy.example.com"
}
}
Pour définir d’autres paramètres pour le plug-in de sortie Microsoft Sentinel Logstash, consultez le fichier readme du plug-in de sortie.
Notes
Pour des raisons de sécurité, nous vous recommandons de ne pas indiquer implicitement les attributs client_app_Id, client_app_secret, tenant_id, data_collection_endpoint et dcr_immutable_id dans votre fichier de configuration Logstash. Nous vous recommandons de stocker ces informations sensibles dans un magasin de clés Logstash.
Redémarrer Logstash
Redémarrez Logstash avec la configuration de plug-in de sortie mise à jour et vérifiez que les données sont ingérées dans la table appropriée en fonction de votre configuration de règles de collecte de données.
Afficher les journaux entrants dans Microsoft Sentinel
Vérifiez que les messages sont envoyés au plug-in de sortie.
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.
Pour afficher les enregistrements de la table, interrogez-la en utilisant son nom 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 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.
Sécurité du réseau
Définissez les paramètres réseau et activez l’isolation réseau pour le plug-in de sortie Microsoft Sentinel Logstash.
Balises de service du réseau virtuel
Le plug-in de sortie Microsoft Sentinel prend en charge les étiquettes de service de réseau virtuel Azure. Les étiquettes AzureMonitor et AzureActiveDirectory sont toutes deux requises.
Vous pouvez utiliser des étiquettes de service Réseau virtuel Azure pour définir des contrôles d’accès au réseau sur des groupes de sécurité du réseau, Pare-feu Azure et des routes définies par l’utilisateur. Utilisez des balises de service à la place d'adresses IP spécifiques lorsque vous créez des règles de sécurité et des routes. Pour les scénarios où les étiquettes de service Réseau virtuel Azure ne peuvent pas être utilisées, les exigences du 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ù les étiquettes de service Réseau virtuel Azure ne peuvent pas être utilisées.
| Cloud | Point de terminaison | Objectif | Port | Direction | Ignorer l’inspection HTTPS |
|---|---|---|---|---|---|
| Azure Commercial | https://login.microsoftonline.com | Serveur d’autorisation (plateforme d’identités Microsoft) | Port 443 | Règle de trafic sortant | Oui |
| Azure Commercial | https://<data collection endpoint name>.<Azure cloud region>.ingest.monitor.azure.com |
Point de terminaison de collecte de données | Port 443 | Règle de trafic sortant | Oui |
| Azure Government | https://login.microsoftonline.us | Serveur d’autorisation (plateforme d’identités Microsoft) | Port 443 | Règle de trafic sortant | Oui |
| Azure Government | Remplacez « .com » ci-dessus par « .us » | Point de terminaison de collecte de données | Port 443 | Règle de trafic sortant | Oui |
| Microsoft Azure géré par 21Vianet | https://login.chinacloudapi.cn | Serveur d’autorisation (plateforme d’identités Microsoft) | Port 443 | Règle de trafic sortant | Oui |
| Microsoft Azure géré par 21Vianet | Remplacez « .com » ci-dessus par « .cn » | Point de terminaison de collecte de données | Port 443 | Règle de trafic sortant | Oui |
Limites
- L’ingestion dans des tables standard est limitée aux tables standard prises en charge pour l’ingestion des journaux personnalisés.
- Les colonnes du flux d’entrée dans la propriété
streamDeclarationsdoivent commencer par une lettre. Si vous commencez une colonne avec d’autres caractères (par exemple@ou_), l’opération échoue. - Le champ datetime
TimeGeneratedest obligatoire. Vous devez inclure ce champ dans la transformation KQL. - Pour d’autres problèmes possibles, consultez section résolution des problèmes du tutoriel.
Étapes suivantes
Dans cet article, 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 :
- Découvrez comment avoir une visibilité sur vos données et les menaces potentielles.
- Prise en main de la détection des menaces avec Microsoft Sentinel.