Développer des transformateurs personnalisés

Compatible avec :

Vous pouvez créer des fonctions de transformation et des opérateurs logiques personnalisés basés sur Python directement dans l'IDE, et les utiliser dans vos playbooks pour des cas d'utilisation complexes et polyvalents.

Packs d'extension

Un pack d'extension est un type d'intégration spécialisé conçu pour servir de conteneur aux fonctions de transformation et aux opérateurs logiques personnalisés. Contrairement aux intégrations standards, les packs d'extension ne nécessitent pas de configuration d'instance et peuvent être créés directement à partir de l'IDE.

Bonnes pratiques concernant les packs d'extension

  • Consolidation : créez un pack d'extension principal et ajoutez-y plusieurs fonctions de transformation ou opérateurs logiques.
  • Séparation : créez un pack d'extension lorsque vous avez besoin d'un ensemble différent de bibliothèques Python (dépendances) qui pourraient entrer en conflit avec le pack principal.

Créer un pack d'extension

Pour créer un pack d'extension, procédez comme suit :

  1. Accédez à Réponse > IDE.
  2. Cliquez sur add Créer un élément.
  3. Sélectionnez Pack d'extension dans le menu déroulant.
  4. Indiquez un nom unique pour le pack d'extension.
  5. Cliquez sur Enregistrer.

Importer des dépendances

Comme les intégrations standards, les packs d'extension s'exécutent dans un environnement virtuel où vous pouvez gérer les bibliothèques Python.

Pour gérer vos bibliothèques, procédez comme suit :

  1. Ouvrez les paramètres du pack d'extension dans l'IDE.
  2. Ajoutez les bibliothèques Python requises à partir de PyPi ou importez-les depuis votre ordinateur.

Ces dépendances sont disponibles pour tous les transformateurs et opérateurs logiques contenus dans ce pack d'extension spécifique.

Importer et exporter

Vous pouvez importer et exporter manuellement des packs d'extension directement dans l'interface de l'IDE.

Transformateurs personnalisés

Les transformateurs personnalisés sont des fonctions Python définies par l'utilisateur qui étendent les fonctions prédéfinies dans le créateur d'expressions. Vous pouvez les créer directement dans l'IDE pour extraire et manipuler des données, et les utiliser en parallèle des fonctions intégrées existantes.

Créer un transformateur personnalisé

Pour définir un transformateur personnalisé, procédez comme suit :

  1. Dans l'IDE, recherchez le pack d'extension cible.
  2. Sélectionnez le pack d'extension cible pour ajouter un élément sous le pack.
  3. Sélectionnez Fonction de transformation personnalisée.
  4. Indiquez un nom.
  5. Facultatif : ajoutez une description. Elle s'affiche lorsque vous passez le curseur sur le transformateur personnalisé dans le créateur d'expressions.
  6. Définissez la logique du script à l'aide de Python. Vous pouvez utiliser le modèle par défaut fourni comme point de départ.
    • Le script doit inclure une fonction main, comme indiqué dans le modèle prédéfini.
    • Le script doit renvoyer un résultat au créateur d'expressions à l'aide de la fonction end du SDK.
    • L'entrée du transformateur personnalisé peut être de différents types (par exemple, chaîne ou liste). Assurez-vous de la convertir au type attendu dans votre main fonction.
    • Vous ne pouvez utiliser qu'un sous-ensemble des méthodes du SDK dans l'IDE pour les transformateurs:
      • transformer.extract_param("ParamName") : Pour récupérer les valeurs d'entrée.
      • transformer.LOGGER : pour écrire des journaux à des fins de débogage.
      • transformer.end(result) : pour renvoyer la valeur transformée.
  7. Créez des paramètres :
    • Chaque fonction de transformateur personnalisé inclut un paramètre Entrée par défaut. Ce paramètre représente les données d'entrée, qui sont l' espace réservé auquel la fonction s'applique. Vous ne pouvez pas supprimer ce paramètre.
    • Vous pouvez également ajouter des paramètres facultatifs à utiliser dans votre fonction.
  8. Documentation (facultatif) : définissez la documentation intégrée pour le créateur d'expressions :
    • Entrée attendue : décrivez le type de données que la fonction s'attend à recevoir pour ce transformateur (par exemple, « Chaîne » ou « Liste de chaînes »).
    • Sortie attendue : décrivez le type de données que la fonction s'attend à renvoyer pour ce transformateur (par exemple, « booléen »).
    • Exemple d'utilisation : fournissez un exemple d'appel de la fonction (par exemple, if_empty("new_value")).

Vous pouvez tester la logique de votre fonction de transformation personnalisée directement dans l' IDE avant de l'utiliser dans un playbook. Cela vous permet de vérifier que votre script Python gère correctement différents types d'entrée et paramètres, et qu'il renvoie les résultats attendus.

Délai avant expiration

  • Délai avant expiration par défaut : 1 minute.
  • Délai avant expiration maximal : 3 minutes.

Utiliser des transformateurs personnalisés dans le créateur d'expressions

Une fois enregistrés, les transformateurs personnalisés s'affichent dans la liste des fonctions du créateur d'expressions, à côté des fonctions intégrées. Ils sont identifiés par le format suivant : ExtensionPackName.TransformerName. Lorsque vous passez le curseur sur la fonction, la documentation générée à partir des descriptions de vos paramètres s'affiche.

Compatibilité avec tous les espaces réservés (JSON et non JSON)

Le créateur d'expressions est compatible avec tous les espaces réservés exposés dans le concepteur de playbooks, y compris les résultats non JSON.

Pour les espaces réservés non JSON :

  • Vous pouvez saisir manuellement des exemples de données dans le créateur d'expressions pour tester la logique par rapport à différents types d'entrée : chaîne, liste (valeurs séparées par une virgule) et JSON.
  • Le test avec un type d'entrée ne garantit pas que l'espace réservé renverra ce type spécifique au moment de l'exécution.
  • La plupart des espaces réservés sont résolus en tant que chaînes, à l'exception de types spécifiques qui sont résolus en tant que chaîne ou liste en fonction de leur quantité (par exemple, entity.identifier). Pour ces derniers, il est recommandé de toujours traiter l'entrée comme une liste.

Traitement des erreurs

Si une fonction de transformation personnalisée rencontre une erreur lors de l'exécution, l'action de playbook qui utilise ce transformateur échoue. Le message d'erreur spécifique généré par le script Python s'affiche à l'écran dans la vue d'exécution du playbook, ce qui vous permet de résoudre directement les problèmes liés à la logique.

Opérateurs logiques personnalisés

Les opérateurs logiques personnalisés vous permettent de définir votre propre logique booléenne pour comparer des valeurs.

Créer un opérateur logique personnalisé

Pour définir un opérateur logique, procédez comme suit :

  1. Dans l'IDE, recherchez le pack d'extension cible.
  2. Sélectionnez Opérateur logique personnalisé.
  3. Indiquez un nom.
  4. Facultatif : ajoutez une description pour le menu des opérateurs logiques dans le concepteur de playbooks.
  5. Définissez la logique du script à l'aide de Python. Vous pouvez utiliser le modèle prédéfini fourni comme point de départ.
    • Le script doit inclure une fonction main.
    • Le script doit renvoyer un résultat booléen à la condition en utilisant la fonction end du SDK.
    • Vous ne pouvez utiliser qu'un sous-ensemble des méthodes du SDK dans l'IDE pour les opérateurs logiques :
      • logical_operator.extract_param("ParamName") : pour récupérer les valeurs d'entrée.
      • logical_operator.LOGGER : pour écrire des journaux à des fins de débogage.
      • logical_operator.end(result) : le résultat est une valeur booléenne (true ou false).

Vous pouvez tester la logique de votre opérateur logique personnalisé directement dans l'IDE. Cela vous permet de saisir des valeurs de test pour les arguments et de vérifier que la fonction renvoie le résultat booléen correct (True ou False) en fonction des conditions que vous avez définies.

Paramètres

Les opérateurs logiques personnalisés acceptent deux paramètres : Côté gauche (obligatoire et non modifiable) et Côté droit (facultatif ; peut être désactivé par l'utilisateur).

  • Exemple 1 : if [left side] not in [right side].
  • Exemple 2 : if [left side] is greater than 80 (pas de côté droit).

Délai avant expiration

  • Délai avant expiration par défaut : 1 minute.
  • Délai avant expiration maximal : 3 minutes.

Utilisation dans les playbooks

Les opérateurs logiques personnalisés s'affichent dans le menu des opérateurs dans Conditions du playbook, Conditions de l'action précédente et Sélection d'entités.

Les opérateurs logiques personnalisés peuvent être sélectionnés en parallèle des opérateurs standards (par exemple, "Égal à" ou "Contient").

Traitement des erreurs

Si une fonction d'opérateur logique personnalisé rencontre une erreur lors de l'exécution, la condition ou l'étape du playbook qui utilise cet opérateur échoue. Le message d'erreur renvoyé par le script Python s'affiche dans la vue d'exécution du playbook pour vous aider à résoudre le problème.

Limites

  • Les fonctions de transformation personnalisées et les opérateurs logiques ne sont pas compatibles avec les déclencheurs ni les webhooks.

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