Envoi de notifications CMA via des webhooks

Vue d'ensemble

L'application de gestion Cato (CMA) génère des notifications pour un large éventail d'événements de sécurité et réseau dans votre compte. Vous pouvez utiliser des intégrations de webhook pour livrer automatiquement ces notifications à des plateformes tierces telles que ServiceNow, Jira, Slack ou Zendesk. Cela permet aux systèmes externes de consommer des données d'événements Cato en temps réel et de déclencher des flux de travail automatisés pour le suivi et la réponse aux incidents.

Cato prend en charge deux types d'intégrations de webhook :

Les webhooks standard utilisent les requêtes HTTP pour créer ou mettre à jour des éléments dans des plateformes externes.
Les webhooks corrélés s'intègrent au service XOps. Ils utilisent des identifiants de corrélation pour créer et mettre à jour des éléments qui représentent le cycle de vie des histoires de sécurité et réseau XOps dans des outils tiers. Une licence XOps est requise.

Les intégrations de webhook sont entièrement configurables. Vous définissez la méthode HTTP (POST ou PUT), l'URL cible, la méthode d'authentification et le corps de la requête. Les modèles et les variables de champ vous permettent d'adapter la structure de la charge utile aux exigences de la plateforme tierce.

Comprendre les intégrations de webhook Cato

Types d'intégration de webhook

Cato prend en charge ces types de webhooks pour intégrer votre compte avec des plateformes tierces et créer des flux d'automatisation :

Les webhooks standard prennent en charge un large éventail de notifications CMA, telles que des notifications basées sur des alertes de compte ou de système, et des notifications basées sur des règles. Ils vous permettent de livrer ces données à des plateformes externes et de configurer si le webhook crée de nouveaux enregistrements ou met à jour ceux existants.
Les webhooks corrélés sont conçus pour le service XOps. Ils étendent la fonctionnalité du webhook aux histoires de sécurité et de réseau, de sorte que chaque histoire dans la CMA est mappée à un enregistrement dans le système externe et mise à jour à mesure que l'histoire progresse. Une licence XOps est requise.

Flux de Webhook - Créer ou Mettre à jour

Les flux de webhook définissent comment la CMA communique avec une plateforme tierce, soit en créant de nouveaux enregistrements, soit en mettant à jour ceux existants :

POST (Créer) - Crée un nouvel élément dans la plateforme tierce chaque fois que le webhook est déclenché. Exemple : ouvrir un nouveau ticket ServiceNow chaque fois que la règle de pare-feu Internet bloque un flux de trafic.
PUT (Mettre à jour) – Met à jour un élément existant dans la plateforme tierce. La demande inclut un ID d'élément valide dans l'URL ou le corps.

Méthodes d'authentification

Lors de la création d'une intégration de Webhook, il existe différentes méthodes d'authentification parmi lesquelles choisir :

Base - Nom d'utilisateur et mot de passe
Bearer - Jeton porteur
Personnalisé - En-têtes personnalisés pour les services nécessitant une authentification unique. Ajoutez des paires clé-valeur au besoin.

Remarque : Si l'accès au service tierce est limité à des adresses IP spécifiques, veuillez vous référer à cet article pour la liste des adresses IP de Cato que vous devez autoriser (vous devez être connecté pour voir cet article).

Personnaliser le contenu des notifications

Le champ content dans le modèle contient le résumé lisible généré de l'alerte, similaire au contenu de l'alerte par courriel. Vous pouvez choisir ces formats pour le contenu : contentText, contentMarkdown, ou contentHTML.

Si vous choisissez de personnaliser le corps, il existe un certain nombre de champs de données que vous pouvez utiliser dans le contenu du message. Ainsi, vous pouvez définir un corps (ou une structure) personnalisé, puis intégrer les champs de données Cato. Lorsque vous entrez $, les champs de données disponibles s'affichent, puis vous sélectionnez le champ requis. Les champs utilisent la complétion automatique pour filtrer la liste. Pour plus d'informations sur les champs de Cato, voir Comprendre les champs JSON pour les Intégrations d'Alerte.

Valeur Par défaut pour Champs du Webhook

Vous pouvez définir des valeurs par défaut personnalisées pour les champs de webhook dynamiques afin d’ajouter de la flexibilité lorsque les données de notification n’incluent pas de valeur. Cela vous permet de remplacer la valeur Par défaut NA dans l'URL du webhook, les en-têtes ou le corps. Utilisez le format ${field:defaultValue} pour définir la valeur de repli. Par exemple, vous pouvez définir ${level:medium} si le champ niveau n'est pas renseigné. Dans un flux corrélé, vous pouvez également utiliser un ID de ticket de repli dans l'URL du webhook, tel que https://EXAMPLE-INSTANCE.service-now.com/api/now/table/incident/${correlationId:12345}, afin que les notifications non corrélées soient capturées dans un ticket ServiceNow par défaut.

Intégrations standard de Webhook

Les webhooks standard vous permettent d'envoyer des notifications CMA à des plateformes tierces pour un large éventail de cas d'utilisation. Tout d'abord, définissez le webhook à intégrer à la plateforme. Ensuite, sélectionnez les notifications et les règles de politique CMA, telles que les actions de pare-feu, qui généreront des notifications à l'aide du webhook.

Définir une intégration de Webhook

Créez une intégration de webhook qui envoie des notifications via des éléments (ticket, message Slack, etc.) dans votre outil tiers. Vous pouvez configurer un webhook pour créer de nouveaux éléments avec une demande POST ou mettre à jour des éléments existants avec une demande PUT. L'intégration inclut des paramètres pour l'URL, le corps de la requête, la méthode d'authentification et en option les en-têtes personnalisés et le corps du message.

Après avoir défini les détails, vous pouvez tester la connexion et valider son bon fonctionnement.

Pour définir une intégration de Webhook:

Dans le menu de navigation, cliquez sur Compte > Abonnements et sélectionnez l'onglet Webhooks.
Cliquez sur Nouveau Webhook. Le panneau Nouvelle Intégration de Webhook s'ouvre.
Configurez les détails du Webhook:
1. Entrez le Nom de l'intégration.
2. Cliquez sur le curseur pour activer (vert) ou désactiver (gris) l'intégration (elle est activée par défaut).
Configurez les paramètres du modèle JSON pour l'intégration :
- Dans Démarrer à partir du modèle, sélectionnez le modèle JSON par défaut qui remplit les paramètres d'intégration.
  
  Vous pouvez ajuster et modifier les champs pour le Corps personnalisé (voir ci-dessous l'étape 7).
Remarque : Si vous choisissez un modèle différent, les champs du Corps personnalisé sont réinitialisés. Pour plus d'informations sur les modèles, voir ci-dessous Modèles et Champs.
Configurez les Détails de Connexion :
1. Entrez l'URL pour le service qui reçoit le Webhook.
  
  Vous pouvez utiliser des champs comme variables dans l'URL. Tapez $ pour voir les champs disponibles.
2. Dans Méthode de Requête, sélectionnez le flux pour ce webhook : POST ou PUT.
3. Si nécessaire, configurez le Méthode d'Authentification et les paramètres pour le service.
(Facultatif) Dans En-têtes Personnalisés, définissez la Clé et la Valeur pour chaque en-tête HTTP supplémentaire pour l'intégration.
Dans Corps personnalisé, définissez le contenu de la notification de Webhook :
1. (Facultatif) Personnaliser le contenu dans Modifier le corps.
  - Entrez / en tant que caractère d'échappement pour utiliser $ dans le corps
  - Entrez $ pour intégrer d'autres champs
  L'identifiant de corrélation de la réponse Response Correlation ID n'est pas utilisé pour les intégrations standard de webhooks
2. Pour définir une valeur par défaut, utilisez le format ${field:defaultValue}, par exemple ${ID:12345}
Cliquez sur Tester. La CMA envoie une requête HTTP de test avec un contenu généré automatiquement pour les champs.

Si l'intégration peut se connecter au service, un message de Test réussi est affiché.

En cas d'erreur de connexion, la page affiche le code d'erreur HTTP et le message signalé par le service.
Cliquez sur Sauvegarder. L'intégration du webhook est enregistrée et ajoutée à l'onglet Intégrations dans la page Abonnements.

Définez le Déclencheur pour les Intégrations Webhook Standard

Les webhooks standard sont activés par les notifications de la CMA. Vous pouvez configurer ces types de notifications : one autres

Notifications CMA : la CMA peut envoyer de manière proactive des notifications concernant votre # Compte, tels que des utilisateurs verrouillés, des administrateurs ou des mises à jour de licence. Ces notifications peuvent être envoyées directement via une intégration de webhook.

Pour plus d'informations, voir Alertes de niveau de # Compte et notifications système.
Notifications de règle de politique : Vous pouvez configurer le paramètre Suivre dans une règle de politique pour envoyer une notification à un webhook chaque fois que la règle est respectée.

Lors de la définition de règles dans les politiques, vous pouvez utiliser la zone Actions pour envoyer des notifications via des intégrations de webhook.

Intégrations de Webhook Corrélées

Le service XOps prend en charge les webhooks corrélés qui vous permettent d’intégrer le cycle de vie des histoires de sécurité et des réseaux XOps avec une plate-forme tierce. Une fois l'intégration configurée, la plateforme tierce crée automatiquement un nouveau ticket, problème ou message lorsqu'une histoire commence, puis le met à jour au fur et à mesure que l'histoire progresse ou est résolue.

Ces intégrations utilisent des champs de corrélation des Histoires XOps pour mapper chaque histoire dans la CMA à un ticket, un problème ou un message dans la plateforme externe. Ceci garantit que les mises à jour sont systématiquement appliquées à l'élément correct. Une licence XOps est requise.

Ces Intégrations requièrent :

Une Intégration Webhook Standard
Une Intégration Webhook Corrélée
Deux types de Déclencheurs (un pour chaque Intégration)

Définez un Webhook Standard

Créer une intégration Webhook standard pour créer les éléments initiaux (ticket, message Slack, etc.) dans votre outil tiers. Ces éléments seront ensuite mis à jour par l'intégration Webhook corrélée.

Après avoir défini les détails, vous pouvez tester la connexion et valider son bon fonctionnement.

Pour définir une intégration Webhook standard :

Dans le menu de navigation, cliquez sur Compte > Abonnements et sélectionnez l'onglet Webhooks.
Cliquez sur Nouveau Webhook. Le panneau Nouvelle Intégration Webhook s'ouvre.
Configurez les Détails du Webhook :
1. Entrez le Nom de l'intégration.
2. Cliquez sur le curseur pour activer (vert) ou désactiver (gris) l'intégration (c'est activé par défaut).
Configurez les paramètres pour le modèle JSON pour l'intégration :
- Dans Commencer à partir du modèle, sélectionnez le modèle JSON par défaut qui remplit les paramètres de l'intégration.
  
  Vous pouvez ajuster et modifier les champs pour le Corps Personnalisé (voir ci-dessous étape 7).
Note : Si vous choisissez un autre modèle, les champs du Corps Personnalisé sont réinitialisés. Pour plus d'informations sur les modèles, voir ci-dessous Modèles et Champs.
Configurer les Détails de la connexion :
1. Entrez l'URL du service qui reçoit le Webhook.
  
  Vous pouvez utiliser des champs comme variables dans l'URL. Tapez $ pour voir les champs disponibles.
2. Dans la Méthode de Requête, sélectionnez POST.
3. Si nécessaire, configurez la Méthode d'authentification et les paramètres pour le service.
(Facultatif) Dans En-têtes Personnalisés, définissez la Clé et la Valeur pour chaque en-tête HTTP supplémentaire pour l'intégration.
Dans le Corps Personnalisé, définissez le contenu de la notification Webhook :
1. Dans ID de Corrélation de la Réponse, définissez l'élément dans votre outil tiers que vous utiliserez pour la corrélation dans l'URL. Par exemple, dans ServiceNow, cela pourrait être result.sys_id, et dans Zendesk, cela pourrait être ticket.id.
2. (Facultatif) Personnalisez le contenu dans Modifier le Corps.
  - Entrez / comme caractère d'échappement pour utiliser $ dans le corps.
  - Entrez $ pour incorporer d'autres champs.
3. Pour définir une valeur par défaut, utilisez le format ${field:defaultValue}, par exemple ${ID:12345}
Cliquez sur Test. La CMA envoie une requête HTTP de test avec un contenu généré automatiquement pour les champs.

Si l'intégration peut se connecter au service, alors un message Test réussi s'affiche.

En cas d'erreur de connexion, la page affiche le code d'erreur HTTP et le message signalé par le service.
Cliquez sur Sauvegarder. L'intégration Webhook est enregistrée et ajoutée à l'onglet Intégrations dans la page Abonnements.

Définir un Webhook Corrélé

Créez une intégration Webhook corrélée qui envoie des notifications via des éléments (ticket, message Slack, etc.) dans votre outil tiers en mettant à jour les éléments existants créés lors de la procédure précédente.

Lorsque vous configurez un webhook corrélé, l'URL utilise l'ID de corrélation pour mettre à jour l'élément correct dans la plateforme tierce. Si la valeur de l'ID de corrélation est vide, la mise à jour ne peut pas être associée à l'élément existant et est perdue. Pour éviter cela, ajoutez l'élément ID au Corps Personnalisé du webhook standard qui crée le ticket, problème ou message d'origine. Cela permet au webhook corrélé d'utiliser cet ID comme valeur de repli pour le champ de corrélation, de sorte que les mises à jour ultérieures continuent de s'appliquer à l'élément d'origine tout au long du cycle de vie de l'histoire.

Après avoir défini les détails, vous pouvez tester la connexion et valider son fonctionnement.

Pour définir une intégration Webhook corrélée :

Dans le menu de navigation, cliquez sur Compte > Abonnements et sélectionnez l'onglet Webhooks.
Cliquez sur Nouveau Webhook. Le panneau Nouvelle Intégration Webhook s'ouvre.
Configurez les Détails du Webhook :
1. Entrez le Nom de l'intégration.
2. Cliquez sur le curseur pour activer (vert) ou désactiver (gris) l'intégration (c'est activé par défaut).
Configurez les paramètres pour le modèle JSON pour l'intégration :
- Dans Commencer à partir du modèle, sélectionnez le modèle JSON par défaut qui remplit les paramètres de l'intégration.
  
  Vous pouvez ajuster et modifier les champs pour le Corps Personnalisé (voir ci-dessous étape 7).
Note : Si vous choisissez un autre modèle, les champs du Corps Personnalisé sont réinitialisés. Pour plus d'informations sur les modèles, voir ci-dessous Modèles et Champs.
Configurer les Détails de la connexion :
1. Entrez l'URL du service qui reçoit le Webhook. Corrélez cela avec un élément existant en ajoutant le champ ID de l'Élément Corrélé.
  
  Vous pouvez utiliser des champs comme variables dans l'URL. Tapez $ pour voir les champs disponibles.
2. Dans la Méthode de Requête, sélectionnez PUT.
3. Si nécessaire, configurez la Méthode d'authentification et les paramètres pour le service.
(Facultatif) Dans En-têtes Personnalisés, définissez la Clé et la Valeur pour chaque en-tête HTTP supplémentaire pour l'intégration.
Dans le Corps Personnalisé, définissez le contenu de la notification Webhook :
1. (Facultatif) Personnalisez le contenu dans Modifier le Corps.
  - Entrez / comme caractère d'échappement pour utiliser $ dans le corps.
  - Entrez $ pour incorporer d'autres champs.
2. Pour définir une valeur par défaut, utilisez le format ${field:defaultValue}, par exemple ${ID:12345}
Cliquez sur Test. La CMA envoie une requête HTTP de test avec un contenu généré automatiquement pour les champs.

Si l'intégration peut se connecter au service, alors un message Test réussi s'affiche.

En cas d'erreur de connexion, la page affiche le code d'erreur HTTP et le message signalé par le service.
Cliquez sur Sauvegarder. L'intégration Webhook est enregistrée et ajoutée à l'onglet Intégrations dans la page Abonnements.

Définir Le Déclencheur pour L'Intégration Webhook Standard

Les webhooks standard sont activés par des notifications de la CMA. Vous pouvez configurer deux types de notifications :

Notifications CMA : La CMA peut envoyer de manière proactive des notifications concernant votre compte, telles que les utilisateurs et administrateurs verrouillés, ou les mises à jour de licence. Ces notifications peuvent être envoyées directement via une intégration webhook.

Pour plus d'informations, voir Alertes de Niveau de Compte et Notifications du Système.
Notifications de règle de politique : Vous pouvez configurer le paramètre Suivi dans une règle de politique pour envoyer une notification à un webhook chaque fois que la règle est correspondue.

Lors de la définition des règles dans les politiques, vous pouvez utiliser la zone Actions pour envoyer des notifications via des intégrations webhook.

Définir le Déclencheur pour l'Intégration Corrélée à l'aide des Notifications de Détection & Réponse

Avec les politiques de détection et de réponse, vous pouvez automatiser la création et la mise à jour des éléments dans des plateformes tierces pour les histoires XOps corrélées. Ainsi, votre système externe reflète toujours l'état actuel de l'histoire.

Vous pouvez configurer des règles dans la politique pour :

Histoire créée : Déclencher un webhook corrélé qui crée un nouvel élément
Histoire mise à jour : Déclencher un webhook corrélé qui met à jour le même élément à mesure que l'histoire progresse

Pour garder les histoires synchronisées, configurez deux règles : une pour créer l'élément lorsque l'histoire commence et une pour le mettre à jour lorsque l'histoire change.

Pour définir le déclencheur d'une notification de webhook :

Dans le menu de navigation, cliquez sur Accueil > Politique de Détection & Réponse.
Sélectionnez l'onglet Politique de Réponse.
Cliquez sur Nouvelle. Le panneau Ajouter à la Politique de Réponse s'ouvre.
Entrez un Nom pour la règle.
Dans la section Source, sélectionnez le type (par exemple : Hôte, Plage d'IP, Site) puis sélectionnez un ou plusieurs objets pour la source de l'histoire pour cette règle (ou vous pouvez entrer une adresse IP).

La valeur par défaut Source est Tout.
(Facultatif) Définir des Critères qui spécifient les caractéristiques qu'une histoire doit avoir pour correspondre à la règle.
Sélectionnez le Déclencheur pour la règle.
- Histoire créée pour créer de nouveaux éléments
- Histoire mise à jour pour mettre à jour les éléments existants
Dans l'onglet Réponse, sélectionnez Envoyer Notification.
Dans Envoyer des notifications à, sélectionnez Intégration.
Dans Intégration, sélectionnez l'intégration de webhooks qui envoie des notifications.
Cliquez sur Sauvegarder. La règle est ajoutée à la politique.

Modèles et Champs

Chaque webhook peut être entièrement personnalisé pour correspondre au format et au comportement de votre système tiers. Le webhook est fourni au format JSON et peut être ajusté pour correspondre à la structure de la plateforme cible. Utilisez les variables de champ Cato pour des charges utiles à la fois statiques et dynamiques.

Après avoir sélectionné un modèle, vous pouvez modifier le corps en tant que charge utile JSON et l'enregistrer en tant que modèle Personnalisé. Vous avez également la possibilité d'intégrer des champs de Données dans le JSON, ce qui placera la valeur pertinente dans la charge utile (ou NA si non disponible).

Lorsque vous tapez $, les champs disponibles sont affichés. Pour plus d'informations sur les champs Cato, voir Comprendre les champs JSON pour les intégrations d'alertes.

Vous pouvez choisir parmi ces modèles lors de la création d'un webhook :

Tous les champs - inclut tous les champs disponibles
Basique - un modèle avec les champs les plus couramment utilisés
Jira - un modèle Jira basique
Créer un ticket ServiceNow - crée un nouveau ticket dans ServiceNow
Mettre à jour un ticket ServiceNow - met à jour un ticket existant dans ServiceNow
Slack - envoie un message à un canal Slack
Créer un ticket Zendesk - crée un nouveau ticket dans Zendesk
Mettre à jour un ticket Zendesk - met à jour un ticket existant Zendesk
Personnalisé - personnalisez les paramètres d'un modèle

Vous pouvez également utiliser des champs lors de la définition de l'URL d'une intégration webhook.