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 trouver et configurer des intégrations personnalisées dans le Content Hub 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.

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 sur les 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. Cette procédure suppose 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 de paramètres Paramètres Paramètres, ce qui indique qu'il s'agit d'une intégration personnalisée.

Cliquez sur settings 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 spécifiques de la bibliothèque, 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 créé sur l' manylinux_2_17_x86_64 architecture. Lorsque vous sélectionnez un .WHL fichier, vérifiez qu'il est compatible avec ce tag.
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 des fichiers de roue 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 générique errorCode: 2000 se produit. 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 de roue 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 [tool.uv.sources] tableau de votre pyproject.toml fichier. 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 uv sur la gestion des dépendances.

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 telles que TIPCommon, Google recommande de contourner complètement les importations manuelles dans l'IDE et de les développer localement à l'aide de l'outil Marketplace CLI (mp). Cet outil suit et empaquète automatiquement les dépendances imbriquées à l'aide de le uv gestionnaire de packages.

Prérequis

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

Configuration initiale

1. Dupliquez et clonez le dépôt officiel du Content Hub 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 TIPCommon ou des dépendances 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 en toute sécurité :

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

   cd content-hub/content/response_integrations/custom/

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

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

3. Remplacez le répertoire par le dossier d'intégration nouvellement extrait :

   cd {INTEGRATION_NAME}

4. Utilisez uv pour injecter le package de fichiers de roue 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 arborescence de dépendances nouvellement suivie , vers votre instance Google SecOps :

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

Vérifier l'installation

Pour vérifier que vos dépendances ont été empaquetées correctement sans rencontrer de errorCode: 2000 boucle, 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 Test/Play (Test/Lecture) 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 gestionnaires ne doivent pas importer à partir du SDK. Après leur création, 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 Créer un élément et sélectionnez 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 requis 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 Content Hub Google SecOps et action Ping

Les paramètres définis dans les paramètres d'intégration s'affichent dans la configuration du Content Hub Google SecOps. Les paramètres incluent les éléments suivants :

• 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 Vérifier le protocole 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 sera exécuté sur un serveur distant au lieu d'être exécuté 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 modifié 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 se comporte 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, cliquez sur le bouton Activer/Désactiver pour le mettre sur la position ON.
2. Cliquez sur Enregistrer. Un bouton vert confirme la réussite. 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 le 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 du Content Hub 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 dossiers appropriée. L' intégration s'affiche dans l'IDE et le Content Hub.
2. Cliquez sur Importer. L'intégration s'affiche à la fois dans l'IDE et le Content Hub.
3. Le système génère un fichier ZIP contenant la définition, les scripts et la configuration. Le dossier Gestionnaires 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 auprès des membres de la communauté et des professionnels Google SecOps.