Fonctions de transformation personnalisées et opérateurs logiques

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 Instructions relatives aux services d'assistance technique Google SecOps et les Conditions spécifiques du service Google SecOps.

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

Packs d'extension

Un pack d'extensions est un type d'intégration spécialisé conçu pour servir de conteneur aux fonctions de transformation personnalisées et aux 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'extension 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, procédez comme suit :

1. Accédez à Réponse > IDE.
2. Cliquez sur Ajouter Créer un élément.
3. Sélectionnez Pack d'extensions dans le menu déroulant.
4. Attribuez un nom unique au pack d'extensions.
Remarque : Le nom ne peut pas être modifié après la création.
5. Cliquez sur Enregistrer.

Importer les dépendances

Comme les intégrations standards, les packs d'extensions 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'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 le pack d'extensions cible.
2. Sélectionnez le pack d'extension cible pour ajouter un élément.
3. Sélectionnez Fonction de transformation personnalisée.
4. Indiquez un nom.
Remarque : Le nom ne peut pas être modifié après la création.
5. Facultatif : ajoutez une description. Cette description 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 en utilisant 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 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 de débogage.
     • transformer.end(result) : renvoie la valeur transformée.
7. Créez des paramètres :
   • Chaque fonction de transformateur personnalisé inclut un paramètre Input (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, "boolean").
   • 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ées et paramètres, et 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 la fin de l'exécution de la fonction, vous devez minimiser le temps d'exécution. Concentrez-vous sur les transformations directes des données et évitez les traitements lourds ou les requêtes sur des 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 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 générateur 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.
• Tester avec un type d'entrée ne garantit pas que le substitut 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 exemples de données sont temporaires et ne seront pas enregistrés après la fermeture du générateur d'expressions ou l'enregistrement de l'expression. Vous devez saisir à nouveau les données d'exemple si vous rouvrez le générateur.

Traitement des erreurs

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 les problèmes 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, procédez comme suit :

1. Dans l'IDE, localisez votre pack d'extensions 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 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 et pouvant ê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).

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 des conditions de playbook, des conditions d'action précédente et de la 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, "É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 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 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 de membres de la communauté et de professionnels Google SecOps.