Créer des intégrations personnalisées

Compatible avec :

Google SecOps SOAR

Ce document explique les workflows permettant de créer des intégrations personnalisées pour Google SecOps. La bonne pratique actuelle consiste à développer des intégrations localement à l'aide de l'IDE de votre choix et à les gérer via GitHub à l'aide de workflows GitOps modernes. Pour les environnements anciens ou les prototypes rapides, vous pouvez également créer des intégrations directement dans l'IDE SOAR intégré.

Remarque : Pour obtenir un framework de développement standardisé, des consignes d'assurance qualité et des bonnes pratiques pour créer et envoyer des intégrations personnalisées, consultez le guide des intégrations personnalisées.

IDE local et workflow GitHub (recommandé)

Le workflow recommandé consiste à développer des intégrations localement et à les gérer via GitHub. Cette approche s'aligne sur les pratiques GitOps modernes, ce qui permet d'améliorer le contrôle des versions, la collaboration et la gestion automatisée des dépendances.

Pour obtenir des instructions techniques détaillées, des guides d'installation et des commandes modernes utilisant l'outil Marketplace CLI et le gestionnaire de packages uv, consultez le dépôt GitHub officiel de Chronicle Content Hub.

Présentation du workflow conceptuel

Pour développer des intégrations personnalisées en local, nous vous recommandons de suivre ce cycle de vie GitOps. Pour connaître la syntaxe exacte et à jour de ces commandes, consultez la documentation officielle de la CLI MP sur GitHub.

1. Dupliquer et cloner : clonez le dépôt content-hub officiel sur votre ordinateur de développement local.
2. Installer les outils : installez l'outil de CLI mp et le gestionnaire de packages Python uv.
3. S'authentifier : connectez-vous à votre environnement Google SecOps via la CLI MP à l'aide de l'URL de votre instance et de vos clés API.
4. Développer en local : utilisez l'IDE de votre choix (comme VS Code ou PyCharm) pour écrire votre code d'intégration, en profitant des outils de débogage et de test locaux.
5. Gérer les dépendances : utilisez uv pour déclarer et gérer les dépendances (comme TIPCommon) dans votre fichier pyproject.toml local.
6. Synchroniser : utilisez les commandes mp pull et mp push pour synchroniser votre code local avec votre instance Google SecOps à des fins de test et de déploiement.

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

Si vous gérez des intégrations anciennes, que vous testez rapidement un script ou que vous travaillez dans un environnement où le développement local est limité, vous pouvez utiliser l'IDE intégré.

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 settings Paramètres, ce qui indique qu'il s'agit d'une intégration personnalisée.

Cliquez sur Paramètres   pour afficher les paramètres d'intégration, où vous pouvez 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 requises par votre intégration personnalisée. Les dépendances peuvent être importé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 des versions de bibliothèque spécifiques, indépendamment de ce qui est installé sur le système sous-jacent.

Si vous utilisez un fichier .WHL personnalisé ou propriétaire (tel que TIPCommon) qui nécessite des sous-dépendances imbriquées, vous devez importer manuellement les fichiers wheel individuels pour l'ensemble de l'arborescence de dépendances avant d'enregistrer. Si vous ne parvenez pas à résoudre les dépendances imbriquées, un échec errorCode: 2000 générique se produit. Pour un suivi avancé des dépendances, envisagez d'utiliser le workflow IDE local et GitHub.

Créer un gestionnaire personnalisé

Les gestionnaires sont des wrappers pour les API d'outils tiers. Bien qu'ils ne soient pas obligatoires, nous les recommandons pour les intégrations qui interagissent avec des outils externes. Les gestionnaires ne doivent pas importer depuis le SDK. Après les avoir créés, importez-les dans des connecteurs, des actions et des 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 gestionnaire.
   
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 gestionnaire 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 Content Hub et action Ping

Les paramètres définis dans les paramètres d'intégration s'affichent dans la configuration de Google SecOps Content Hub. Les paramètres sont les suivants :

• Racine de l'API : URL de base du service auquel vous vous connectez.
• Code secret de l'API : clé confidentielle utilisée pour authentifier votre application auprès du service.
• Case à cocher Valider SSL : si cette option est activée, elle vérifie que le certificat SSL de 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 plutôt que 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 mettre à jour 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 agit 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 vérifier l'authentification.

Activer l'intégration

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

1. Dans Réponse > IDE, activez l'option Activer/Désactiver.
2. Cliquez sur Enregistrer. Un bouton vert confirme que l'opération a réussi. Les identifiants du Content Hub sont transmis à ArmisManager. Si auth se termine sans erreur, le bouton Tester affiche une coche verte.

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 Content Hub.

Afficher les intégrations personnalisées

Accédez au Content Hub 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 Content Hub ne remplacent ni ne suppriment les intégrations personnalisées.

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 dossiers appropriée. L'intégration apparaît dans l'IDE et Content Hub.
2. Cliquez sur Importer. L'intégration apparaît à la fois dans l'IDE et dans le Content Hub.
3. Le système génère un fichier ZIP contenant la définition, les scripts et la configuration. Le dossier Managers 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.