Développer des transformateurs personnalisés

Compatible avec :

Google SecOps SOAR

Remarque : Cette fonctionnalité est couverte par les Conditions des offres avant disponibilité générale des Conditions spécifiques du service Google Security Operations. Les fonctionnalités pré-DG (avant disponibilité générale) sont susceptibles de présenter une compatibilité limitée, et les modifications apportées à ces fonctionnalités peuvent ne pas être compatibles avec d'autres versions avant disponibilité générale. Pour en savoir plus, consultez les Consignes relatives aux services d'assistance technique Google SecOps et les Conditions spécifiques aux services Google SecOps.
Si cette fonctionnalité n'est pas visible dans votre environnement, consultez Gérer les fonctionnalités en avant-première ou contactez votre administrateur système.

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 pour les fonctions de transformation personnalisées et les opérateurs logiques. Contrairement aux intégrations standards, les packs d'extensions ne nécessitent pas de configuration d'instance et peuvent être créés directement à partir de l'IDE.

Bonnes pratiques pour les packs d'extensions

• 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'extensions lorsque vous avez besoin d'un ensemble différent de bibliothèques Python (dépendances) qui pourraient entrer en conflit avec le pack principal.

Important : Pour créer des packs d'extensions dans l'IDE, vous devez disposer de l'autorisation Tous les environnements.

Créer un pack d'extensions

Pour créer un pack d'extensions :

1. Accédez à Réponse > IDE.
2. Cliquez sur Ajouter Créer un élément.
3. Sélectionnez Pack d'extension dans le menu déroulant.
4. Attribuez un nom unique au pack d'extensions.
Remarque : Une fois le nom créé, il ne peut plus être modifié.
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 :

1. Ouvrez les paramètres du pack d'extensions dans l'IDE.
2. Ajoutez les bibliothèques Python requises depuis 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'extensions directement dans l'interface de l'IDE.

Remarque : L'importation et l'exportation peuvent ne pas être disponibles pour les clients qui n'ont pas encore terminé la migration de l'étape 2. Pour en savoir plus, consultez la présentation de la migration SOAR.

Transformateurs personnalisés

Les transformateurs personnalisés sont des fonctions Python définies par l'utilisateur qui étendent les fonctions prédéfinies de l'éditeur 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 votre pack d'extensions cible.
2. Sélectionnez le pack d'extension cible pour ajouter un élément au pack.
3. Sélectionnez Fonction de transformation personnalisée.
4. Indiquez un nom.
Remarque : Une fois le nom créé, il ne peut plus être modifié.
5. Facultatif : ajoutez une description. Elle s'affiche lorsque vous pointez sur le transformateur personnalisé dans le générateur 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 générateur d'expressions à l'aide de la fonction end du SDK.
   • L'entrée du transformateur personnalisé peut être de différents types (par exemple, une chaîne ou une liste). Assurez-vous de le convertir au type attendu dans votre fonction main.
   • 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éer des paramètres :
   • Chaque fonction de transformateur personnalisée 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 générateur d'expressions :
   • Entrée attendue : décrivez le type de données que la fonction s'attend à recevoir pour ce transformateur (par exemple, "String" ou "List of strings").
   • Sortie attendue : décrivez le type de données que la fonction doit renvoyer pour ce transformateur (par exemple, "booléen").
   • Exemple d'utilisation : fournissez un exemple d'invocation 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ées et paramètres, et qu'il renvoie les résultats attendus.

Timeout

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

Remarque : Étant donné que la plate-forme attend que la fonction se termine, vous devez réduire le temps d'exécution. Concentrez-vous sur les transformations directes des données et évitez les traitements lourds ou les requêtes de sources externes.

Utiliser des transformateurs personnalisés dans l'outil de création d'expressions

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

Prise en charge de tous les espaces réservés (JSON et non JSON)

Le générateur d'expressions est compatible avec tous les espaces réservés exposés dans le concepteur de playbook, 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 générateur d'expressions pour tester la logique par rapport à différents types d'entrées : 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 sous forme de chaînes, à l'exception de types spécifiques qui sont résolus sous forme de chaîne ou de liste en fonction de leur quantité (par exemple, entity.identifier). Pour ceux-ci, il est recommandé de toujours traiter l'entrée comme une liste.

Remarque : Les données échantillonnées sont temporaires et ne seront pas enregistrées après la fermeture de l'outil de création d'expressions ni après l'enregistrement de l'expression. Vous devrez saisir à nouveau les données échantillons si vous rouvrez le générateur.

Gestion des exceptions

Si une fonction de transformation personnalisée rencontre une erreur lors de l'exécution, l'action du 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 le problème de 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 nouvel opérateur logique :

1. Dans l'IDE, localisez votre Extension Pack cible.
2. Sélectionnez Opérateur logique personnalisé.
3. Indiquez un nom.
Remarque : Le nom ne peut pas être modifié après la création.
4. Facultatif : Ajoutez une description du 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 votre logique d'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 bon résultat booléen (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 et désactivable 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).

Timeout

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

Remarque : Étant donné que la plate-forme attend la fin de l'exécution de la fonction, vous devez minimiser le temps d'exécution. Il est recommandé de se concentrer sur les transformations directes des données et d'éviter d'interroger des sources externes ou d'effectuer un traitement intensif.

Utilisation dans les playbooks

Les opérateurs logiques personnalisés s'affichent dans le menu des opérateurs sous 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 même temps que les opérateurs standards (par exemple, "Est égal à" ou "Contient").

Gestion des exceptions

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

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 de membres de la communauté et de professionnels Google SecOps.