Aperçu

Ce dépôt contient tout le nécessaire pour convertir les logs Corelight ou Zeek vers le standard de nommage Elastic Common Schema (ECS) et les stocker dans un déploiement Elastic Stack. Publié initialement en 2019, la même année que l'Elastic Common Schema, ce dépôt est toujours activement maintenu et mis à jour.

Il prend en charge plus de 200 logs et métriques différents et est conçu pour prendre en charge tous les environnements tout en permettant simultanément de personnaliser les options requises et souhaitées pour chaque environnement unique.
Un effort important a été investi pour garantir la prise en charge de tous les environnements, tout en permettant simultanément la personnalisation des options nécessaires et souhaitées pour chaque déploiement unique et respectif.

Le dépôt est principalement composé de deux éléments :

1. Modèles d'index Elasticsearch, modèles de composants, politiques ILM, paramètres et mappings
2. Script d'installation pour ce dépôt et les Ingest Pipelines OU Logstash Pipelines correspondants

Licence

Les fichiers et le script d'automatisation sont open-source sous licence BSD. Voir COPYING pour plus de détails.

Étapes d'installation

Veuillez lire toutes les sections avant d'exécuter le script.

1. Prérequis
2. Personnalisation
3. Installation
4. Post-installation

1. Prérequis

• Utiliser le script corelight_ecs.py de ce dépôt. L'installation manuelle des modèles et des pipelines n'est pas prise en charge car il y a des centaines de variables dans les fichiers qui sont remplacées par le script.
• Python 3.6 et plus
• Elasticsearch version 8.x et plus
• Si vous utilisez Logstash, alors une version Logstash 8.x ou supérieure, ou si vous êtes encore en version 7.x, alors 7.17 ou supérieure
• Stratégie d'indexation Datastream Elasticsearch

2. Personnalisation

La personnalisation des paramètres d'index, des mappings, des alias et des politiques ILM est encouragée. Par conséquent, le script est conçu pour prendre en charge de nombreux types de personnalisations (détaillés ci-dessous).
De nombreuses personnalisations ne seront pas nécessaires, mais il vaut mieux avoir l'option que de ne pas l'avoir. Il est toujours recommandé d'utiliser votre propre nombre de shards/réplicas et votre propre politique ILM, mais au-delà de cela, vous ne devriez pas avoir besoin de personnaliser beaucoup d'autres choses. Cependant, si vous personnalisez normalement de nombreux éléments dans les modèles d'index, les pipelines d'ingestion et les pipelines Logstash dans tous vos déploiements, vous en aurez toujours la possibilité.

• Noms d'index personnalisés
  le script vous le demandera et mettra automatiquement à jour tous les modèles, pipelines Logstash et/ou pipelines d'ingestion qui doivent être mis à jour
• Paramètres d'index
  • Nombre de shards
  • Nombre de réplicas
  • Remplacer d'autres paramètres d'index
  • Tout autre élément que vous jugez approprié dans le modèle de composant pour la partie paramètres
• Mappings d'index
  • Remplacer le mapping des champs d'index Elasticsearch
  • Tout autre élément que vous jugez approprié dans le modèle de composant pour la partie mappings
• Politiques ILM
  • Politique ILM personnalisée
• Alias d'index
  • Alias pour les index patterns, par exemple pour la rétrocompatibilité ou pour les désactiver
• Pipelines d'ingestion personnalisés
  • La possibilité d'appeler votre propre pipeline d'ingestion personnalisé avant que les pipelines d'ingestion Corelight soient appelés, sans modifier du tout les pipelines d'ingestion Corelight
  • La possibilité d'appeler votre propre pipeline d'ingestion personnalisé après que tous les pipelines d'ingestion Corelight ont été appelés, sans modifier du tout les pipelines d'ingestion Corelight
• Les pipelines Logstash personnalisés consistent simplement à créer un fichier avec un ordre alphanumérique inférieur et à le charger dans le même répertoire

Voir chaque section ci-dessous pour plus de détails.

Options d'index personnalisées

Noms d'index personnalisés

Le script vous demandera si vous souhaitez choisir des noms/modèles d'index personnalisés pour vos data streams. Cela vous permet de choisir votre propre convention de nommage des index. Par exemple, vous pourriez choisir :

• logs-corelight.conn-default
• ecs-corelight.conn-default
• call_it_what_you_will.conn-default
• logs-corelight.conn-remotesite1

Il mettra ensuite à jour tous les modèles d'index nécessaires ainsi que, si vous avez choisi les pipelines d'ingestion ou les pipelines Logstash. Il n'est pas recommandé de modifier les valeurs par défaut, car les logs Corelight sont désormais configurés pour fonctionner avec tous les autres types de données ECS et pour pouvoir être utilisés depuis une vue de données Kibana telle que logs-*

Pour les environnements multi-locataires tels que les MSSP/CSSP ou les différents réseaux, vous pouvez non seulement choisir la partie organisation du data stream dans les invites du script (qui est la partie default dans les 3 exemples ci-dessus), mais si vous définissez data_stream.namespace dans filebeat ou par une autre méthode ou en branchant les pipelines, alors les pipelines sont configurés pour respecter cette variable si elle est déjà définie et ne pas l'écraser. Assurez-vous simplement que votre namespace est défini sur une valeur qu'Elasticsearch autorise pour un nom d'index (erreur courante qui n'est parfois pas évidente).

Vous pouvez voir les index patterns utilisés dans le Google Sheet et la valeur par défaut pour chaque log. Il répertorie également des informations supplémentaires telles que event.category, event.kind, etc. pour chaque log.

Paramètres d'index personnalisés, c.-à-d. Shards et réplicas

Chaque modèle d'index est spécifié pour appeler un modèle de composant que vous pouvez utiliser pour remplacer les paramètres d'index. Par conséquent, vous n'avez pas besoin de modifier les modèles d'index du dépôt pour utiliser vos propres paramètres d'index.

Créez les modèles de composants suivants ou modifiez-les après l'installation. Les noms des modèles de composants que vous pouvez modifier sont :

pour couvrir tous les logs (répartis en 5 catégories) :

• corelight-ecs-component-metric_log-base-settings@custom
• corelight-ecs-component-parse_failures-base-settings@custom
• corelight-ecs-component-protocol_log-base-settings@custom
• corelight-ecs-component-system_log-base-settings@custom
• corelight-ecs-component-unknown_log-base-settings@custom

pour couvrir des logs individuels au-delà de ce qui précède, qui nécessitent généralement leurs propres paramètres encore plus spécifiques :

• corelight-ecs-component-protocol_log-conn-base-settings@custom
• corelight-ecs-component-protocol_log-dns-base-settings@custom
• corelight-ecs-component-protocol_log-files-base-settings@custom
• corelight-ecs-component-protocol_log-http-base-settings@custom
• corelight-ecs-component-protocol_log-smb-base-settings@custom
• corelight-ecs-component-protocol_log-smtp-base-settings@custom
• corelight-ecs-component-protocol_log-ssl-base-settings@custom
• corelight-ecs-component-protocol_log-suricata_corelight-base-settings@custom
• corelight-ecs-component-protocol_log-syslog-base-settings@custom
• corelight-ecs-component-protocol_log-various-base-settings@custom

Personnalisation des mappings d'index, c.-à-d. champs

Chaque modèle d'index est spécifié pour appeler un modèle de composant que vous pouvez utiliser pour remplacer les mappings d'index pour des éléments tels que les types ou les noms de champs. Par conséquent, vous n'avez pas besoin de modifier les modèles d'index du dépôt pour utiliser vos propres mappings d'index.

Créez les modèles de composants suivants ou modifiez-les après l'installation. Les noms des modèles de composants que vous pouvez modifier sont :

pour couvrir tous les logs (répartis en 5 catégories) :

• corelight-ecs-component-metric_log-mappings@custom
• corelight-ecs-component-parse_failures-mappings@custom
• corelight-ecs-component-protocol_log-mappings@custom
• corelight-ecs-component-system_log-mappings@custom
• corelight-ecs-component-unknown_log-mappings@custom

pour couvrir des logs individuels au-delà de ce qui précède, qui nécessitent généralement leurs propres paramètres encore plus spécifiques :

• corelight-ecs-component-protocol_log-conn-mappings@custom
• corelight-ecs-component-protocol_log-dns-mappings@custom
• corelight-ecs-component-protocol_log-files-mappings@custom
• corelight-ecs-component-protocol_log-http-mappings@custom
• corelight-ecs-component-protocol_log-smb-mappings@custom
• corelight-ecs-component-protocol_log-smtp-mappings@custom
• corelight-ecs-component-protocol_log-ssl-mappings@custom
• corelight-ecs-component-protocol_log-suricata_corelight-mappings@custom
• corelight-ecs-component-protocol_log-syslog-mappings@custom
• corelight-ecs-component-protocol_log-various-mappings@custom

Stratégie de politique ILM personnalisée

Chaque modèle d'index est spécifié pour appeler un modèle de composant que vous pouvez utiliser pour remplacer la politique ILM afin de définir votre propre rétention. Par conséquent, vous n'avez pas besoin de modifier les modèles d'index du dépôt pour utiliser votre propre politique ILM.

Créez les modèles de composants suivants ou modifiez-les après l'installation. Les noms des modèles de composants que vous pouvez modifier sont :

pour couvrir tous les logs (répartis en 5 catégories) :

• corelight-ecs-component-metric_log-ilm-settings@custom
• corelight-ecs-component-parse_failures-ilm-settings@custom
• corelight-ecs-component-protocol_log-ilm-settings@custom
• corelight-ecs-component-system_log-ilm-settings@custom
• corelight-ecs-component-unknown_log-ilm-settings@custom

ceux-ci couvriront les logs individuels au-delà de ce qui précède, qui nécessitent généralement leurs propres paramètres encore plus spécifiques :

• corelight-ecs-component-protocol_log-conn-ilm-settings@custom
• corelight-ecs-component-protocol_log-dns-ilm-settings@custom
• corelight-ecs-component-protocol_log-files-ilm-settings@custom
• corelight-ecs-component-protocol_log-http-ilm-settings@custom
• corelight-ecs-component-protocol_log-smb-ilm-settings@custom
• corelight-ecs-component-protocol_log-smtp-ilm-settings@custom
• corelight-ecs-component-protocol_log-ssl-ilm-settings@custom
• corelight-ecs-component-protocol_log-suricata_corelight-ilm-settings@custom
• corelight-ecs-component-protocol_log-syslog-ilm-settings@custom
• corelight-ecs-component-protocol_log-various-ilm-settings@custom

Alias d'index personnalisés

Chaque modèle d'index est spécifié pour appeler un modèle de composant que vous pouvez utiliser pour remplacer les alias d'index. Par conséquent, vous n'avez pas besoin de modifier les modèles d'index du dépôt pour utiliser vos propres alias ILM.

Créez les modèles de composants suivants ou modifiez-les après l'installation. Les noms des modèles de composants que vous pouvez modifier sont :

pour couvrir tous les logs (répartis en 5 catégories) :

• corelight-ecs-component-metric_log-aliases@custom
• corelight-ecs-component-parse_failures-aliases@custom
• corelight-ecs-component-protocol_log-aliases@custom
• corelight-ecs-component-system_log-aliases@custom
• corelight-ecs-component-unknown_log-aliases@custom

ceux-ci couvriront les logs individuels au-delà de ce qui précède, qui nécessitent généralement leurs propres paramètres encore plus spécifiques :

• corelight-ecs-component-protocol_log-conn-aliases@custom
• corelight-ecs-component-protocol_log-dns-aliases@custom
• corelight-ecs-component-protocol_log-files-aliases@custom
• corelight-ecs-component-protocol_log-http-aliases@custom
• corelight-ecs-component-protocol_log-smb-aliases@custom
• corelight-ecs-component-protocol_log-smtp-aliases@custom
• corelight-ecs-component-protocol_log-ssl-aliases@custom
• corelight-ecs-component-protocol_log-suricata_corelight-aliases@custom
• corelight-ecs-component-protocol_log-syslog-aliases@custom
• corelight-ecs-component-protocol_log-various-aliases@custom

Pipelines d'ingestion personnalisés

Règle fourre-tout du pipeline d'ingestion personnalisé de début

Au début des pipelines d'ingestion, avant que les pipelines Corelight soient appelés, il existe une fonction qui utilise le pipeline d'ingestion nommé corelight-ecs-main-pipeline@custom. Vous pouvez créer un pipeline d'ingestion portant ce nom si vous souhaitez faire des choses avant que les pipelines Corelight soient appelés. Si vous ne créez pas le pipeline, la fonction le laisse passer silencieusement ; il est donc optionnel.

Règle fourre-tout du pipeline d'ingestion personnalisé final

À la fin des pipelines d'ingestion, après que tous les pipelines Corelight ont été appelés, il existe une fonction qui utilise le pipeline d'ingestion nommé corelight-ecs-postprocess-final-main-pipeline@custom. Vous pouvez créer un pipeline d'ingestion portant ce nom si vous souhaitez faire des choses avant que les pipelines Corelight soient appelés. Si vous ne créez pas le pipeline, la fonction le laisse passer silencieusement ; il est donc optionnel.

Règle fourre-tout du pipeline d'ingestion personnalisé de début en cas d'échec d'analyse

Au début des pipelines d'ingestion, dans la règle fourre-tout on_failure pour les échecs des pipelines d'ingestion, avant que les pipelines Corelight soient appelés, il existe une fonction qui utilise le pipeline d'ingestion nommé corelight-ecs-parse_failures-pipeline@custom. Vous pouvez créer un pipeline d'ingestion portant ce nom si vous souhaitez faire des choses avant que les pipelines Corelight soient appelés. Si vous ne créez pas le pipeline, la fonction le laisse passer silencieusement ; il est donc optionnel.

Règle fourre-tout du pipeline d'ingestion personnalisé final en cas d'échec d'analyse

À la fin des pipelines d'ingestion, après que tous les pipelines Corelight ont été appelés, il existe une fonction qui utilise le pipeline d'ingestion nommé corelight-ecs-postprocess-final-main-pipeline@custom. Vous pouvez créer un pipeline d'ingestion portant ce nom si vous souhaitez faire des choses avant que les pipelines Corelight soient appelés. Si vous ne créez pas le pipeline, la fonction le laisse passer silencieusement ; il est donc optionnel.

3. Installation

Utilisation du script

git clone https://github.com/corelight/ecs-templates
cd ecs-templates
python3 corelight_ecs.py

Arguments du script

• --no-color : Désactiver les couleurs pour la journalisation.
• --debug : Activer la journalisation au niveau debug.
• --es-default-timeout=10 : Modifier le délai d'attente par défaut de la connexion à Elasticsearch.
• --es-default-retry=2 : Modifier le nombre de fois par défaut pour réessayer une connexion à Elasticsearch.
• --git-repository=corelight : Modifier le nombre de fois par défaut pour réessayer une connexion à Elasticsearch.
• --git-branch=main : Modifier le nombre de fois par défaut pour réessayer une connexion à Elasticsearch.

4. Post-installation

Logstash

Certaines valeurs devront peut-être être modifiées après l'installation pour s'adapter à votre environnement. Cela inclut des éléments tels qu'une autorité de certification personnalisée pour la connexion Elasticsearch, divers topics Kafka, etc. Comme il y a plus de 20 options dans la sortie Elasticsearch et plus de 60 options réparties sur 5 entrées différentes, l'installateur ne fournit pas, ne demande pas et ne vérifie pas la validité de toutes ces options. Cependant, pour vous aider, le script vous indiquera quels fichiers modifier. De plus, pour ceux qui utilisent une automatisation complète de tous les éléments, un script d'exemple a été fourni pour montrer qu'il est possible d'automatiser le processus de modification des valeurs dans les fichiers après l'installation tout en décommentant simultanément les lignes des variables utilisées.

Personnalisez vos modèles

Voir la section Personnalisation pour plus de détails.

Configuration du capteur Corelight - Exporter Elastic

• utiliser un index pattern uniquement pour pouvoir atteindre les pipelines d'ingestion, par exemple pour une appliance Corelight ou pour des tests. Définissez le préfixe sur temporary_corelight_routing_index
• Désactiver les index système
• Activer les Data Streams - Selon la version, il s'agira d'une case à cocher dans l'exporter ou, dans la configuration avancée, vous pouvez activer bro.export.elasticsearch.use_data_streams

Journal des modifications (en cours)

voir le fichier changelog.md pour un journal complet des modifications du dépôt.

Liste des tâches à faire (en cours)

voir le fichier todo.md pour une liste complète des tâches à faire pour le dépôt.

Gestion des versions

Le versionnage de ce dépôt est basé sur la version de l'Elastic Common Schema (ECS) qu'il prend en charge. Des champs sont ajoutés à chaque log :

• labels.corelight.ecs_version
• labels.corelight.ecs_method
• labels.corelight.ecs_method_version

Définitions des dépôts GitHub

Modèles Elasticsearch (ce dépôt)

https://github.com/corelight/ecs-templates

• Modèles d'index Elasticsearch, modèles de composants, politiques ILM, paramètres et mappings
• Script d'installation

Pipelines Logstash

https://github.com/corelight/ecs-logstash-mappings

• Configurations des pipelines Logstash

Pipelines d'ingestion

https://github.com/corelight/ecs-mapping

• Configurations des pipelines d'ingestion

Tableaux de bord et visualisations Kibana

https://github.com/corelight/ecs-dashboards

Règles de sécurité et alertes Kibana

https://github.com/corelight/Elasticsearch_rules