Créer une intégration personnalisée

Compatible avec :

Google SecOps SOAR

Ce document explique comment créer des intégrations personnalisées dans l'environnement de développement intégré (IDE) en utilisant la même structure que les intégrations commerciales. Vous pouvez rechercher et configurer des intégrations personnalisées dans le Google Security Operations Marketplace pour différents environnements. Vous pouvez ensuite les utiliser dans des playbooks, des actions manuelles et des agents à distance. La fonctionnalité d'importation et d'exportation est également prise en charge, comme pour les autres éléments de l'IDE.

Créer une intégration personnalisée dans l'IDE

Vous pouvez créer une intégration personnalisée pour le produit Armis et créer un gestionnaire avec une action Ping. Pour cette procédure, nous partons du principe que vous connaissez Python et la programmation orientée objet.

Cas d'utilisation : créer une intégration Armis personnalisée

Pour créer l'intégration personnalisée dans l'IDE, procédez comme suit :

1. Dans le menu principal, accédez à Réponse > IDE.
2. Cliquez sur Créer un élément, puis sélectionnez Intégration.
3. Saisissez un nom, puis cliquez sur Créer.

L'intégration est désormais listée avec l'option Paramètres Paramètres, ce qui indique qu'il s'agit d'une intégration personnalisée.

Cliquez sur settings Settings (Paramètres) pour afficher les paramètres d'intégration. Vous pourrez y définir l'icône, la description, les dépendances Python et les paramètres d'intégration.

Remarque : Les dépendances de script sont des bibliothèques Python que l'intégration personnalisée doit importer. Les dépendances peuvent être ajoutées sous forme de fichiers.WHL, .TAR, .GZ ou.PY. Chaque intégration s'exécute dans son propre environnement virtuel, ce qui vous permet d'utiliser différentes versions de bibliothèque, même si l'une d'elles est déjà installée sur le système. Par exemple, pour utiliser une autre version de la bibliothèque de requêtes, téléchargez-la à partir d'une source fiable telle que PyPI ou GitHub, puis ajoutez-la en tant que dépendance de script. Si elle n'est pas installée dans l'environnement virtuel, l'intégration revient à la version système.

Créer un gestionnaire personnalisé

Les gestionnaires sont des wrappers pour les API d'outils tiers. Bien que cela ne soit pas obligatoire, nous les recommandons pour les intégrations qui interagissent avec des outils externes. Les responsables ne doivent pas importer à partir du SDK. Après les avoir créés, importez-les dans les connecteurs, les actions et les jobs.

Pour créer un gestionnaire personnalisé, procédez comme suit :

1. Dans l'IDE, cliquez sur Create New Item (Créer un élément) et sélectionnez Manager (Gestionnaire).
2. Sélectionnez l'intégration Armis, puis saisissez le nom d'un responsable.
   
3. Modifiez et exécutez le script suivant :

import requests


class ArmisManager:
   def init(self, api_root, api_token):
       self.api_root = api_root
       self.api_token - api_token
       self.session = requests.session()
       self.session.headers = {"Accept": "application/json"}


   def auth(self):
       endpoint = "{}/api/vi/access_token/*"
       params = {"secret_key" : self.api_token}
       response = self.session.post(endpoint.format(self.api_root), params=params)
       self.validate_response(response)
       access_token = response.json()["data"]["access_token"]
       self.session.headers.update({"Authorization": access_token})
       return True


   def get_device_by_ip(self, device_ip):
       endpoint = "{}/api/vi/devices/"
       params = {"ip": device_ip}
       response = self.session.get(endpoint.format(self.api_root), params=params)
       self.validate_response(response)
       return response.json()["data"]["data"]


   @staticmethod
   def validate_response(res, error_msg="An error occurred"):
       """Validate a response


       :param res: (requests. Response) The response to validate
       :param error_msg: (str) The error message to display
       """
       try:
           res.raise_for_status()
       except requests.HTTPError as error:
           raise Exception("(error_msg): (error) (text)".format(
               error_msg=error_msg,
               error=error,
               text=error.response.content
           ))

Remarque : Un responsable n'est pas nécessaire pour les actions de base. Toutefois, nous vous recommandons d'en créer un lorsque vous regroupez de petites actions pour l'analyse et la transformation des données.

Paramètres, configuration de Google SecOps Marketplace et action Ping

Les paramètres définis dans les paramètres d'intégration s'affichent dans la configuration Google SecOps Marketplace. Voici les paramètres concernés :

• Racine de l'API : URL de base du service auquel vous vous connectez.
• Secret de l'API : clé confidentielle utilisée pour authentifier votre application auprès du service.
• Case à cocher Valider SSL : si elle est activée, elle permet de vérifier que le certificat SSL pour la connexion au serveur Armis est valide.
• Case à cocher Exécuter à distance : paramètre qui détermine si le code ou la tâche seront exécutés sur un serveur distant au lieu d'être exécutés localement. Lorsque cette option est activée, le système envoie les instructions et les données nécessaires à un serveur dédié pour traitement.

Pour modifier les paramètres, procédez comme suit :

1. Saisissez les bons identifiants.
2. Cliquez sur Enregistrer > Tester.

Remarque : Cliquez toujours sur Enregistrer après avoir mis à jour les identifiants. Toutes les intégrations tierces doivent implémenter une action Ping. Le bouton Tester exécute cette action pour valider la connectivité.

Si l'action Ping est manquante, le bouton Tester échoue et affiche un X rouge.

Implémenter une action Ping

La logique de l'action Ping fonctionne comme une authentification réussie.

Pour implémenter une action Ping, procédez comme suit :

1. Dans l'IDE, créez une action dans l'intégration Armis nommée Ping.
2. Utilisez la méthode ArmisManager auth pour valider l'authentification.

Activer l'intégration

Pour activer l'intégration, procédez comme suit :

1. Dans Réponse > IDE, cliquez sur le bouton Activer/Désactiver pour le mettre sur ON (ACTIVÉ).
2. Cliquez sur Enregistrer. Si le bouton bascule est vert, cela signifie que l'opération a réussi. Les identifiants de la place de marché sont transmis à ArmisManager. Si auth se termine sans erreur, une coche verte s'affiche sur le bouton Tester.

Utilisez la méthode extract_configuration_param pour importer des paramètres à partir de la configuration de l'intégration. Vous pouvez également utiliser extract_action_param pour définir des paramètres dans l'action elle-même. Toutefois, l'action Ping doit toujours utiliser des paramètres de configuration, car ils sont testés par Marketplace.

Afficher les intégrations personnalisées

Accédez au Google SecOps Marketplace et recherchez l'intégration personnalisée que vous avez créée. Si vous n'avez pas créé d'image lors de la configuration initiale, l'image personnalisée par défaut lui sera attribuée. Notez que les mises à jour de Google SecOps Marketplace ne remplacent ni ne suppriment aucune intégration personnalisée.

Exporter et importer dans l'IDE

Effectuez l'une des opérations suivantes :

• Pour importer des intégrations, procédez comme suit :
1. Importez un fichier ZIP avec la structure de dossier appropriée. L'intégration s'affiche dans l'IDE et sur la place de marché Google SecOps.
2. Cliquez sur Importer. L'intégration apparaît à la fois dans l'IDE et dans Marketplace.
3. Le système génère un fichier ZIP contenant la définition, les scripts et la configuration. Le dossier Administrateurs n'est pas inclus automatiquement.
• Pour exporter des intégrations, procédez comme suit :
• Cliquez sur Exporter pour télécharger le package.

Vous avez encore besoin d'aide ? Obtenez des réponses de membres de la communauté et de professionnels Google SecOps.