Créer des intégrations personnalisées

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 trouver et configurer des intégrations personnalisées dans le hub de contenu 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 disponible, comme pour les autres éléments de l'IDE.

Remarque : Pour obtenir des informations sur 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.

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 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 spécifiques de bibliothèques, quelle que soit la version installée sur le système sous-jacent. 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.
 Pour les dépendances qui nécessitent une roue binaire précompilée (comme les packages avec des extensions C), la plate-forme SOAR utilise cpython standard compilé par rapport à l'architecture manylinux_2_17_x86_64. Lorsque vous sélectionnez un fichier .WHL, vérifiez qu'il est compatible avec cette balise.
Si une bibliothèque n'est pas installée dans l'environnement virtuel, l'intégration revient à la version installée sur le système.

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 des dépendances (par exemple, anyio, certifi, httpx, idna ou sniffio) avant d'enregistrer. Si vous ne parvenez pas à résoudre les dépendances imbriquées, une erreur errorCode: 2000 générique se produira. Pour obtenir la liste complète des bibliothèques de plate-forme requises, consultez le guide de la communauté sur la récupération de TIPCommon.

Si un package de dépendances ne dispose pas d'un fichier wheel précompilé (.WHL) disponible pour l'architecture manylinux_2_17_x86_64 ou si vous avez besoin d'une version spécifique du code source, vous pouvez fournir une URL directe vers le code source (par exemple, un fichier .tar.gz). Le résolveur de dépendances de la plate-forme, uv, permet de définir ces URL sources dans le tableau [tool.uv.sources] de votre fichier pyproject.toml. Exemple :

[project]
# ... other project fields ...

[tool.uv.sources]
compressed-rtf = { url = "https://files.pythonhosted.org/packages/.../compressed_rtf-1.0.6.tar.gz" }
dkimpy = { url = "https://files.pythonhosted.org/packages/.../dkimpy-1.1.8.tar.gz" }

Pour en savoir plus sur la définition de différents types de dépendances à l'aide de uv, consultez la documentation Gestion des dépendances de uv.

Workflow recommandé : gestion avancée des dépendances à l'aide de mp CLI

Pour les intégrations nécessitant des bibliothèques externes complexes ou multicouches comme TIPCommon, Google recommande de contourner complètement les importations manuelles d'IDE et de les développer localement à l'aide de l'outil Marketplace CLI (mp). Cet outil suit et regroupe automatiquement les dépendances imbriquées à l'aide du gestionnaire de paquets uv.

Prérequis

• Python 3.11 ou version ultérieure installé sur votre ordinateur de développement local.
• Le gestionnaire de paquets Python uv est installé (consultez le guide d'installation uv).

Configuration initiale

1. Dupliquez et clonez le dépôt Content Hub officiel dans votre environnement local.
2. Installez l'outil mp à l'aide de uv :

   uv tool install mp --from git+https://github.com/chronicle/content-hub.git#subdirectory=packages/mp

3. Connectez-vous à votre environnement Google SecOps à l'aide de l'URL racine de votre instance et de votre ancienne clé API :

   mp login --api-root https://{YOUR_INSTANCE}.siemplify-soar.com --api-key {YOUR_LEGACY_API_KEY}

   Remarque : L'outil CLI nécessite l'URL de votre ancienne instance SOAR et le format de clé API pour l'authentification.
4. Configurez le chemin d'accès à votre dépôt racine local :

   mp config --root-path /path/to/cloned/content-hub

5. Créez un sous-répertoire personnalisé pour vos intégrations propriétaires dans la mise en page du dépôt à l'adresse suivante : content-hub/content/response_integrations/custom/.

Ajouter des dépendances TIPCommon ou complexes à une intégration

Si vous avez créé une intégration dans l'IDE qui nécessite TIPCommon ou d'autres bibliothèques multicouches, utilisez le workflow local suivant pour gérer ses dépendances de manière sécurisée :

1. Accédez au répertoire de votre intégration personnalisée dans le dépôt cloné :

   cd content-hub/content/response_integrations/custom/

2. Extrayez la structure d'intégration existante de votre instance Google SecOps :

   mp pull --type integration --name "{INTEGRATION_NAME}"

3. Remplacez le répertoire par le dossier d'intégration que vous venez d'extraire :

   cd {INTEGRATION_NAME}

4. Utilisez uv pour injecter le package de fichier wheel TIPCommon requis. Cela permet de suivre et de télécharger automatiquement les roues de sous-dépendances imbriquées dans la configuration du package de votre environnement local :

   uv pip install /path/to/wheels/TIPCommon-your-version-py3-none-any.whl

5. Transférez l'intégration entièrement compilée ainsi que son nouvel arbre de dépendances suivi vers votre instance Google SecOps :

   mp push --type integration --name "{INTEGRATION_NAME}"

Vérifier l'installation

Pour vérifier que vos dépendances ont bien été empaquetées sans boucle errorCode: 2000, procédez comme suit :

• Ouvrez votre intégration personnalisée dans l'IDE.
• Ajoutez une ligne de test pour importer un module à partir du package, par exemple : from TIPCommon.extraction import extract_action_param
• Cliquez sur le bouton Tester/Lire pour déboguer l'exécution. Si le script se compile correctement sans générer d'erreur ModuleNotFoundError, vos dépendances imbriquées sont correctement résolues.

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 des connecteurs, des actions et des jobs.

Pour créer un gestionnaire personnalisé :

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) La réponse à valider
       :param error_msg: (str) Le message d'erreur à afficher
       """
       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 du hub de contenus Google SecOps et action Ping

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

• 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 permet de vérifier 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 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 du Content Hub 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 le Hub de contenu.

Afficher les intégrations personnalisées

Accédez au hub de contenu 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 du Hub de contenu 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 le Hub de contenu.
2. Cliquez sur Importer. L'intégration apparaît à la fois dans l'IDE et dans le Hub de contenu.
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.