Contribuer à des intégrations de réponses de la communauté

Compatible avec :

Ce document décrit les consignes à suivre pour envoyer des intégrations de réponses à Google SecOps via des contributions de la communauté. Toutes les intégrations envoyées sont soumises à un processus de validation par l'équipe officielle Google SecOps, qui se concentre sur les exigences mises en évidence dans ce document.

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

Nom

Le nom doit correspondre au nom du produit avec lequel l' intégration sera 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 d'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. Elle doit contenir les informations suivantes :

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

Évitez de placer des URL dans la description.

Logos

Chaque intégration doit être fournie avec 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 :

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 SVG avant de l'ajouter au fichier de définition de l'intégration, comme vous pouvez le voir dans d'autres intégrations du Hub de contenu.

Dans le cadre de l'intégration, vous pouvez ajouter un lien qui redirigera les utilisateurs vers la documentation. Cette documentation doit être hébergée de votre côté.

Les utilisateurs peuvent accéder au lien de la documentation depuis la section Parameters de la boîte de dialogue Configure Instance (Configurer l'instance).

Paramètres de configuration

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

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

Action 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 ne comporte aucune autre action. Chaque fois que l'utilisateur appuie sur le bouton Test (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 de la note de version doit respecter le format suivant : format :

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

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

  • S'il s'agit d'une nouvelle intégration : New Integration Added - {integration name} (Nouvelle intégration ajoutée – {nom de l'intégration})
  • Si une nouvelle action est ajoutée : New Action Added - {action name} (Nouvelle action ajoutée – {nom de l'action})
  • Si un nouveau connecteur est ajouté : New Connector Added - {connector name} (Nouveau connecteur ajouté – {nom du connecteur})
  • Si une nouvelle tâche est ajoutée : New Job Added - {job name} (Nouvelle tâche ajoutée – {nom de la tâche})
  • Si un widget prédéfini est ajouté à une action : {action name} - Added Predefined Widget. ({nom de l'action} – Widget prédéfini ajouté)
  • Si un widget prédéfini est mis à jour : {action name} - Updated Predefined Widget. ({nom de l'action} – Widget prédéfini mis à jour)
  • Pour les modifications qui affectent tous les éléments d'intégration : Integration - {Update} (Intégration – {Mise à jour})
  • 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 toutes les tâches : 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 tiroir latéral Integration Details (Détails de l’intégration) qui s’affiche lorsque vous cliquez sur le bouton Details (Détails) de 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 forme d'entier. Les versions mineures telles que 11.1.3 ou 11.1 ne sont pas autorisées.

Tags

Si vous le souhaitez, vous pouvez ajouter des tags à votre intégration. Évitez de créer de nouveaux types de tags. Utilisez ceux qui se trouvent déjà dans la plate-forme. Si vous ne trouvez pas de tag qui vous convient, consultez l'équipe de validation.

Remarques générales

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

Actions

Nom

Le nom de l'action doit pointer vers l'activité en cours d'exécution, par exemple Get Case Details (Obtenir les détails du cas), List Entity Events (Lister les événements d'entité) ou Execute Search (Exécuter la recherche).

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 le type d'entités compatibles. Par 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 (Asynchrone), vous devez fournir 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 de l'action 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 quel impact ce paramètre a sur l'exécution de l'action. Si le paramètre accepte un nombre prédéterminé de valeurs compatibles, fournissez 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 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 execution. 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 médiocre, car il serait inutilisable dans les playbooks :


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

À la place, formatez-le comme suit :


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

Si vous utilisez des entités dans l'action et 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",
       }
   }
]

Tenez toujours compte de la manière dont la sortie de l'action peut être utilisée 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 du playbook. Supprimez toutes les informations personnelles identifiables des exemples JSON.

Sorties de l'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 des entités.

Sorties de l'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, la bonne pratique consiste à 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 disponible pour cette situation et que l'action échoue. Lorsque l'action échoue, le playbook correspondant arrête son 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é que le message de sortie ait la structure suivante :

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

Évitez de placer l'intégralité de la trace d'erreur. Essayez plutôt 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 seront ingérées. En général, la structure du nom doit être la suivante : ceci :

  • {integration display name} - {data that is being ingested} Connector
    • Par exemple : Crowdstrike - Pull Alerts Connector (Crowdstrike – Connecteur d'extraction d'alertes)

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ésente 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 quel impact ce paramètre a sur l'exécution du connecteur.

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

  • Max Alerts To Fetch (Nombre maximal d'alertes à extraire) : indique le nombre d'{object} à traiter lors d'une itération du connecteur.
  • Max {Hours/Days} Backwards (Nombre maximal d'{heures/jours} en arrière) : indique l'heure de début de la première itération du connecteur. Par exemple, si Max Hours Backwards est défini sur 1, le connecteur commence à extraire les données à partir d'une heure plus tôt.
  • Verify SSL (Vérifier le protocole SSL) : vérifie la connectivité à l'API/l'instance.

Mappage d'ontologie

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 permet de créer automatiquement des entités (indicateurs de compromission et éléments). De plus, les métadonnées critiques des champs système tels que Start Time (Heure de début) et End Time (Heure de fin) y sont définies.

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 elle, tout en bénéficiant d'une expérience utilisateur 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'avoir un paramètre Use Dynamic List as a blocklist (Utiliser la liste dynamique comme liste de blocage) pour que la logique inverse soit également prise en charge.

Tâches

Nom

Le nom de la tâche doit expliquer à l'utilisateur ce que cette tâche est en train d'effectuer. En général, la structure du nom doit être la suivante :

  • {integration display name} - {process} Job
    • Par exemple : ServiceNow - Sync Incidents Job (ServiceNow – Tâche de synchronisation des incidents)

Description

La description de la tâche doit indiquer à l'utilisateur ce que la tâche effectue lors des 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 de la tâche

Les paramètres de configuration de la tâche 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 la tâche.

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

Possible Values: {value 1}, {value 2} (Valeurs possibles : {valeur 1}, {valeur 2})

Au-delà des paramètres d'authentification, toutes les tâches doivent comporter les paramètres suivants :

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

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