Consignes de contribution de la communauté pour les intégrations de réponses

Compatible avec :

Google SecOps SOAR

Ce document décrit les consignes à suivre pour envoyer des intégrations de réponses à Google SecOps par le biais de contributions de la communauté. Toutes les intégrations envoyées sont examinées par l'équipe Google SecOps officielle, en particulier en ce qui concerne les exigences mises en évidence dans ce document.

Métadonnées d'intégration des réponses

Nom

Le nom doit correspondre au nom du produit avec lequel l'intégration va être intégrée et ne doit contenir aucun caractère spécial.

Le nom à afficher doit être écrit avec des espaces, par exemple Vertex AI et non VertexAI.

Identifiant de l'intégration

L'identifiant d'intégration est un identifiant unique de l'intégration. Une fois l'intégration créée, cette valeur ne peut plus être modifiée. L'identifiant doit avoir la même valeur que Name, mais sans espaces.

L'identifiant est disponible dans la plupart des endroits de la plate-forme.

Description

La description doit fournir un aperçu général du produit avec lequel l'intégration est créée et ne doit pas dépasser 500 caractères. Il doit comporter les informations suivantes :

This integration is owned by the "{vendor name}". Support Contact: {email}.

Évitez d'inclure des URL dans la description.

Logos

Chaque intégration doit être associée à une icône SVG. Cette icône doit s'adapter aux thèmes de la plate-forme. Les icônes ne doivent hériter du thème que de la plate-forme.

Vous devez valider le logo sur les pages suivantes :

• Réponse > Configuration de l'intégration
• Réponse > Playbooks > Concepteur de playbooks
• Demandes > Alerte > Afficher le playbook d'alerte

Voici un exemple de logo SVG conçu pour correspondre à notre guide de style :

        <?xml version="1.0" encoding="UTF-8"?><svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 21 23"> <defs> <style> .cls-1 { stroke-width: 0px; } </style> </defs> <path class="cls-1" d="M15.51,4.79H5.49c-.4,0-.72.32-.72.72v5.75c0,2.3,1.71,4.15,3.69,5.38.54.34,1.1.62,1.66.86l.09.04c.06.02.12.05.18.06.03,0,.07,0,.1,0,.1,0,.19-.03.28-.07l.09-.04c.76-.33,2.22-1.03,3.46-2.24,1.24-1.22,1.89-2.6,1.89-4v-5.75c0-.4-.32-.72-.72-.72ZM14.32,11.26c0,.88-.44,1.77-1.32,2.63-.65.64-1.55,1.22-2.5,1.68-.95-.46-1.84-1.04-2.5-1.68-.88-.86-1.32-1.75-1.32-2.63v-4.55h7.64v4.55ZM20.28,0H.72c-.4,0-.72.32-.72.72v10.77c0,2.56,1.18,4.99,3.51,7.21,2.29,2.18,5.12,3.56,6.61,4.2l.09.04s.1.04.15.05c.04,0,.09.01.13.01.1,0,.19-.02.28-.06l.09-.04c.53-.23,1.23-.55,2.02-.97,1.42-.75,3.11-1.82,4.59-3.23,2.33-2.22,3.51-4.64,3.51-7.21V.72c0-.4-.32-.72-.72-.72ZM16.17,17.31c-1.9,1.81-4.24,3.04-5.67,3.69-1.43-.65-3.77-1.88-5.67-3.69-1.94-1.84-2.92-3.8-2.92-5.82V1.92h17.18v9.57c0,2.02-.98,3.98-2.92,5.82Z"/></svg>
        

Veillez à encoder le fichier SVG avant de l'ajouter au fichier de définition de l'intégration, comme vous pouvez le voir dans d'autres intégrations de la place de marché.

Lien vers la documentation

Dans le cadre de l'intégration, vous pouvez ajouter un lien qui redirige les utilisateurs vers la documentation. Vous devez héberger cette documentation.

Les utilisateurs peuvent accéder au lien de la documentation depuis la section Paramètres de la boîte de dialogue Configurer l'instance.

Paramètres de configuration

Toutes les intégrations doivent contenir des paramètres de configuration (paramètres racine de l'API et d'authentification), sauf si l'API sous-jacente ne nécessite aucune authentification et que la racine de l'API peut être codée en dur. Pour toutes les intégrations nécessitant une authentification, un paramètre Verify SSL doit être présent.

Tous les paramètres doivent comporter une description. La description doit aider les utilisateurs à configurer l'intégration depuis la plate-forme. Évitez d'insérer des URL dans la description des paramètres.

Action de ping

L'action Ping est une action spéciale utilisée par la plate-forme pour valider la connectivité de l'API. Cette action est obligatoire, même si votre intégration n'en comporte aucune autre. Chaque fois que l'utilisateur appuie sur le bouton Tester dans la configuration de l'intégration, un état précis de la connectivité doit s'afficher.

Notes de version

La structure générale des notes de version doit respecter le format suivant :

• {integration item} - {update}
• Par exemple : Get Case Details - Added ability to fetch information about affected IOCs

Selon la situation, des notes de version spécifiques sont disponibles pour certains scénarios :

• S'il s'agit d'une nouvelle intégration : New Integration Added - {integration name}
• Si une nouvelle action est ajoutée : New Action Added - {action name}
• Si un nouveau connecteur est ajouté : New Connector Added - {connector name}
• Si un nouveau job est ajouté : New Job Added - {job name}
• Si un widget prédéfini est ajouté à une action : {action name} - Added Predefined Widget.
• Si un widget prédéfini est mis à jour : {action name} - Updated Predefined Widget.
• Pour les modifications qui affectent tous les éléments d'intégration : Integration - {Update}
• Pour les modifications qui affectent toutes les actions : Integration's Actions - {Update}
• Pour les modifications qui affectent tous les connecteurs : Integration's Connectors - {Update}
• Pour les modifications qui affectent tous les jobs : Integration's Jobs - {Update}

Si la version contenait une modification régressive, vous devez spécifier REGRESSIVE! dans la note de version. Par exemple : Google Chronicle - Chronicle Alerts Connector - REGRESSIVE! Updated mapping.

Les notes de version sont disponibles dans le panneau latéral Détails de l'intégration qui s'affiche lorsque vous cliquez sur le bouton Détails dans l'intégration.

Gestion des versions

Chaque mise à jour de l'intégration doit être suivie d'une mise à jour +1 de la version de l'intégration. Les versions doivent être représentées sous la forme d'un nombre entier. Les versions mineures telles que 11.1.3 ou 11.1 ne sont pas autorisées.

Tags

Vous pouvez éventuellement ajouter des tags à votre intégration. Évitez de créer de nouveaux types de balises. Utilisez celles qui sont déjà dans la plate-forme. Si vous ne trouvez pas de tag qui vous convient, contactez l'équipe de validation.

Remarques générales

• Testez chaque contenu d'intégration avant de l'envoyer.
• Examinez tout le contenu de l'intégration pour détecter d'éventuelles failles et dépendances vulnérables.
• Utilisez toujours la dernière version compatible de Python lors du développement (Python 3.11).

Actions

Nom

Le nom de l'action doit pointer vers l'activité en cours (par exemple, Get Case Details, List Entity Events ou Execute Search).

Si l'action est conçue pour fonctionner principalement avec des entités, il est préférable de placer Entity dans le nom, par exemple Enrich Entities.

Les noms d'action doivent être exprimés en deux ou trois mots.

Description

La description de l'action doit indiquer à l'utilisateur le résultat de l'exécution de l'action.

Si l'action fonctionne avec des entités, vous devez ajouter des informations sur les types d'entités compatibles. Exemple :

Add a vote to entities in VirusTotal. Supported entities: File Hash, URL, Hostname, Domain, IP Address. Note: only MD5, SHA-1 and SHA-256 Hash types are supported.

Si l'action fonctionne en mode Async, vous devez ajouter la note suivante dans la description :

Note: Action is running as async, adjust script timeout value in Google SecOps IDE for action, as needed.

Essayez de limiter la description à 500 caractères.

Paramètres d'action

Les paramètres de configuration des actions doivent avoir un nom intuitif. Évitez d'utiliser des caractères spéciaux et essayez de limiter le nom du paramètre d'action à deux à quatre mots.

La description du paramètre doit expliquer à l'utilisateur l'impact de ce paramètre sur l'exécution de l'action. Si le paramètre accepte un nombre prédéterminé de valeurs, ajoutez la section suivante dans la description : Possible Values: {value 1}, {value 2}.

Sortie de l'action (résultat du script)

Le résultat du script doit représenter un résultat simple de l'action. Dans la plupart des cas, il doit simplement pointer vers une variable appelée is_success, qui peut prendre les valeurs true ou false.

En général, si l'action a terminé son exécution et effectué une opération, is_success doit être défini sur true.

Sortie de l'action (résultat JSON)

Le résultat JSON est la sortie la plus importante de l'action. Toutes les données disponibles dans le résultat JSON seront accessibles lors de l'exécution du playbook. Vérifiez qu'un objet JSON valide est envoyé à la sortie.

La taille des résultats JSON est limitée à 15 Mo.

Lorsque vous créez un résultat JSON, assurez-vous qu'aucune clé ne sera unique lors de l'exécution. Par exemple, l'objet JSON suivant représente une structure de mauvaise qualité, car il serait inutilisable dans les playbooks :

{
   "10.10.10.10": {
      "is_malicious": "false"
   }
}
    

Mettez-le plutôt en forme comme suit :

[
   {
      "is_malicious": "false",
      "ip": "10.10.10.10"
   }
]
   

Si vous utilisez des entités dans l'action et que vous renvoyez des résultats par entité, la bonne pratique consiste à structurer le résultat JSON comme suit :

[
   {
       "Entity": "10.10.10.10",
       "EntityResult": {
           "is_malicious": "false",
       }
   }
]
    

Pensez toujours à la façon dont le résultat de l'action peut être utilisé dans l'automatisation.

Assurez-vous qu'il existe un exemple JSON pour votre action.

L'exemple JSON est utilisé par la plate-forme dans le générateur d'expressions lors du processus de création du playbook. Un exemple JSON précis améliore considérablement l'expérience de création de playbook. Supprimez toute information permettant d'identifier personnellement l'utilisateur des exemples JSON.

Sorties d'action (enrichissement d'entités)

Si des actions sont exécutées sur des entités, vous pouvez leur ajouter des métadonnées supplémentaires lors de l'exécution de l'action. La structure de ces métadonnées doit respecter le format suivant : {integration identifier}_{key}. Par exemple : WebRisk_is_malicious.

Vous trouverez les métadonnées ajoutées sur la page d'informations sur les entités.

Sorties d'action (message de sortie)

Le message de sortie doit expliquer à l'utilisateur comment l'exécution de l'action s'est déroulée de manière plus descriptive. Il doit indiquer à l'utilisateur le résultat de l'exécution de l'action.

Si certaines entités ont été enrichies, mais pas d'autres, nous vous recommandons de fournir des informations sur l'état de chaque entité fournie dans le message.

Si vous pensez qu'une erreur critique s'est produite lors de l'exécution de l'action, assurez-vous qu'un message détaillé est prévu pour cette situation et que l'action échoue. En cas d'échec de l'action, le playbook correspondant arrête l'exécution jusqu'à ce que l'erreur soit résolue ou ignorée manuellement.

Voici quelques exemples de messages de sortie :

• Successfully enriched the following entities using information from VirusTotal: {entity.identifier}
• Action wasn't able to find any information for the following entities using VirusTotal: {entity.identifier}
• None of the provided entities were found in VirusTotal.
• Successfully executed query "{query}" in Google SecOps.

Si l'action doit échouer et arrêter l'exécution du playbook, il est recommandé de structurer le message de sortie comme suit :

"Error executing action "{action name}". Reason: {error}'

Évitez de fournir la trace complète des erreurs. Au lieu de cela, essayez d'indiquer à l'utilisateur le problème réel en langage naturel.

Connecteurs

Nom

Le nom du connecteur doit indiquer à l'utilisateur les données qui vont être ingérées. En général, la structure du nom doit être la suivante :

• {integration display name} - {data that is being ingested} Connector
• Par exemple : Crowdstrike - Pull Alerts Connector

Description

La description du connecteur doit indiquer à l'utilisateur ce qui sera ingéré par le connecteur (par exemple, Pull alerts from Crowdstrike). Vous devez également fournir des informations sur la compatibilité avec les listes dynamiques, par exemple Dynamic List works with the display_name parameter..

Dans ce cas, la description finale se présentera comme suit :

Pull alerts from Crowdstrike. Dynamic List works with the display_name parameter.

Essayez de limiter la description à 500 caractères.

Paramètres du connecteur

Les paramètres de configuration du connecteur doivent avoir un nom intuitif. Évitez d'utiliser des caractères spéciaux et essayez de limiter le nom du paramètre d'action à deux à quatre mots.

La description du paramètre doit expliquer à l'utilisateur l'impact de ce paramètre sur l'exécution du connecteur.

Si le paramètre accepte un nombre prédéterminé de valeurs, ajoutez la section suivante dans la description : Possible Values: {value 1}, {value 2}. doit comporter les paramètres suivants :

• Nombre maximal d'alertes à récupérer : indique le nombre d'objets {object} à traiter lors d'une itération du connecteur.
• Max {Hours/Days} Backwards : définit l'heure de début de la première itération du connecteur. Par exemple, si Heures max. en arrière est défini sur 1, le connecteur commencera à extraire les données une heure plus tôt.
• Vérifier le protocole SSL : vérifie la connectivité à l'API/l'instance.

Mappage d'ontologies

Pour chaque connecteur créé, il est recommandé de fournir un mappage d'ontologie afin de vérifier que les clients mutuels bénéficient de la meilleure expérience possible.

Le mappage d'ontologie est utilisé pour créer automatiquement des entités (IOC et composants). Vous y trouverez également les métadonnées critiques des champs système, comme Heure de début et Heure de fin.

Liste dynamique

La liste dynamique est une fonctionnalité facultative qui vous permet de créer un filtre avancé pour l'ingestion. Vous pouvez créer n'importe quelle logique personnalisée avec, tout en bénéficiant d'une UX unique. Le cas d'utilisation le plus courant consiste à définir une liste d'autorisation ou une liste de blocage pour l'ingestion.

Si vous créez une logique personnalisée pour la liste dynamique, assurez-vous qu'elle est fournie dans la description du connecteur. Il est également recommandé d'utiliser le paramètre Utiliser la liste dynamique comme liste de blocage pour prendre en charge la logique inverse.

Jobs

Nom

Le nom du job doit expliquer à l'utilisateur ce que ce job effectue. En général, la structure du nom doit être la suivante :

• {integration display name} - {process} Job
• Par exemple : ServiceNow - Sync Incidents Job

Description

La description du job doit indiquer à l'utilisateur ce que le job fait pendant les itérations, par exemple This job will synchronize Security Command Center based cases created by the Urgent Posture Findings connector..

Essayez de limiter la description à 500 caractères.

Paramètres du job

Les paramètres de configuration des jobs doivent avoir un nom intuitif. Évitez d'utiliser des caractères spéciaux et essayez de limiter le nom du paramètre d'action à deux à quatre mots.

La description du paramètre doit expliquer à l'utilisateur l'impact de ce paramètre sur l'exécution du job.

Si le paramètre accepte un nombre prédéterminé de valeurs, ajoutez la section suivante dans la description :

Possible Values: {value 1}, {value 2}.

En plus des paramètres d'authentification, tous les jobs doivent comporter les paramètres suivants :

• Max {Hours/Days} Backwards (Max {heures/jours} en arrière) : détermine l'heure de début de la première itération du job.
• Vérifier le protocole SSL : vérifie la connectivité à l'API/l'instance.

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