Cette page a été traduite par l'API Cloud Translation.

Créer des actions personnalisées

Compatible avec :

Google SecOps SOAR

Dans votre première intégration personnalisée, vous avez défini ses paramètres et créé une action Ping pour tester la connexion. Ce document vous explique comment créer deux actions pour votre intégration personnalisée :

Obtenir les détails du domaine : récupère les informations du domaine et présente le résultat au format JSON.
Enrichir les entités : enrichit les entités avec des détails sur le domaine.

Créer une action personnalisée

Pour créer une action personnalisée, procédez comme suit :

Accédez à l'environnement de développement intégré (IDE), puis cliquez sur Ajouter pour ajouter un élément d'IDE.
Cochez la case d'option Action.
Nommez l'action Get Domain Details et sélectionnez l'intégration.
Cliquez sur Créer. L'IDE génère un modèle avec des commentaires et des explications intégrés.

Configurer les paramètres d'action

D'après la documentation de l'API XML WHOIS, l'action Get Domain Details (Obtenir les détails du domaine) nécessite deux paramètres : Check Availability et Domain Name. Pour configurer ces paramètres, procédez comme suit :

Dans le module IDE, cliquez sur Ajouter.
Créez le premier paramètre : renseignez les champs pour Vérifier la disponibilité, puis cliquez sur Enregistrer. Ce paramètre indique si le domaine est disponible ou non. Son résultat sera utilisé dans l'automatisation que vous créerez ultérieurement.
Créez le deuxième paramètre : remplissez les champs pour Nom de domaine, puis cliquez sur Enregistrer. Utilisez ce champ pour saisir le domaine que l'action doit vérifier.

Modifier l'action "Obtenir les détails du domaine"

Pour modifier l'action Obtenir les détails du domaine, procédez comme suit :

Copiez le code fourni pour Get Domain Details (Obtenir les détails du domaine) et collez-le dans l'IDE. Examinez le code. L'objet doit utiliser la méthode end de la classe pour renvoyer un message de sortie et une valeur de résultat, par exemple :
siemplify.end(msg, None)

Extraire les paramètres d'intégration et d'action : les paramètres d'intégration, tels que la clé API, sont extraits à l'aide de la fonction siemplify.extract_configuration_param. De même, les paramètres d'action que vous avez configurés, y compris Domain Name et Check availability, sont extraits avec la fonction siemplify.extract_action_param.


    api_key =
    siemplify.extract_configuration_param(provider_name=INTEGRATION_NAME,
    param_name="API Key") 
url = f"https://www.whoisxmlapi.com/whoisserver/WhoisService?apiKey={api_key}&outputFormat=json" 
    domain = siemplify.extract_action_param(param_name="Domain Name",
    print_value=True) availability_check =
    siemplify.extract_action_param(param_name="Check availability",
    is_mandatory=False, print_value=True)

Créez la requête et traitez le résultat :

Une fois que vous avez extrait les paramètres d'intégration et d'action, vous pouvez créer l'URL de la requête. L'URL est construite en fonction de la valeur booléenne du paramètre availability_check.
Une fois l'URL prête, envoyez une demande au site WHOIS.
Analysez la réponse du site et ajoutez les données pertinentes au résultat de l'action.

Définissez le message de sortie qui sera présenté à l'utilisateur et incluez le résultat JSON.


  # Add domain to scan
      url = f"{url}&domainName={domain}"
      # Determine availability check
      if availability_check.lower() == 'true':
          availability_check_qs = 1
      else:
          availability_check_qs = 0
      url = f"{url}&da={availability_check_qs}"
      response = requests.get(url)
      response.raise_for_status()
      # Add a Json result that can be used in the next steps of the playbook.
      siemplify.result.add_result_json(response.json())
      # Add the Json to the action result presented in the context details.
      siemplify.result.add_json("WhoisDetails", response.json())
      msg = f"Fetched data for {domain}"
      siemplify.end(msg, None)
  if __name__ == "__main__":
      main()

Ajouter un résultat JSON à l'action

Dans l'action Obtenir les détails du domaine, cliquez sur Obtenir les détails du domaine pour ajouter un exemple JSON. Utilisez l'exemple JSON dans le concepteur de playbooks de la procédure Créer votre première automatisation pour extraire un champ spécifique du JSON.

Obtenez le fichier JSON : copiez le fichier JSON à partir de l'exemple JSON du site WHOIS.
Activez l'icône JSON : dans l'onglet Détails de l'IDE, activez l'option Inclure le résultat JSON pour rendre l'icône JSON visible en haut de l'IDE.
Importez le fichier JSON : cliquez sur file_json Gérer l'exemple JSON> login Importer un exemple JSON.

Tester l'action

Pour tester l'action que vous avez créée, procédez comme suit :

Accédez à l'onglet Test.
Dans Champ d'application, sélectionnez votre cas de test et votre instance d'intégration.
Cliquez sur slideshow Lire dans l'IDE.
Consultez le résultat de l'action dans l'onglet Test. Vous pouvez également consulter les journaux et les impressions en cochant l'onglet Sortie de débogage une fois le test terminé.

Créer un scénario de test

Si vous n'avez aucun scénario de test dans votre environnement, accédez à Cas d'utilisation> Ingérer l'alerte en tant que scénario de test pour en créer un. Cette action crée un cas de test qui s'affiche avec le libellé Test dans votre file d'attente des demandes. Après avoir créé le scénario de test, revenez à l'IDE et sélectionnez-le dans la liste.

Pour créer un cas de test, procédez comme suit :

Accédez à la page Demandes et sélectionnez une demande.
Ingérez l'alerte en tant que scénario de test. Cette opération crée une demande portant le libellé Test dans votre file d'attente.

Après avoir créé un scénario de test, revenez à l'IDE et sélectionnez-le dans la liste.

Créer une action d'enrichissement

Cette partie de la procédure se concentre sur la création d'une action d'enrichissement pour ajouter de nouvelles données aux entités. Vous pouvez ensuite afficher les données enrichies dans l'explorateur d'entités. Pour créer une action d'enrichissement, procédez comme suit :

Dans l'IDE, créez une action et nommez-la Enrich Entities.

Copiez et collez le code suivant dans l'action :


  from SiemplifyAction import SiemplifyAction 
  from SiemplifyUtils import output_handler 
  from SiemplifyDataModel import EntityTypes
  
  import requests
  
  # Example Consts: 
  INTEGRATION_NAME = "My first Integration - Whois XML API" 

  SCRIPT_NAME = "WHOIS XML API EnrichEntities"
  
  @output_handler 
  def main():    
      siemplify = SiemplifyAction()    
      siemplify.script_name = SCRIPT_NAME    
      siemplify.LOGGER.info("================= Main - Param Init =================")     

      api_key =
      siemplify.extract_configuration_param(provider_name=INTEGRATION_NAME,
      param_name="API Key") url =
      f"https://www.whoisxmlapi.com/whoisserver/WhoisService?apiKey={api_key}&outputFormat=json"
      
      
      siemplify.LOGGER.info("----------------- Main - Started -----------------")
      output_message = "output message :" # human readable message, showed in UI
      as the action result successful_entities = [] # In case this actions
      contains entity based logic, collect successful entity.identifiers 
      
    for entity in siemplify.target_entities:        
    siemplify.LOGGER.info(f"processing entity {entity.identifier}")
      if (entity.entity_type == EntityTypes.HOSTNAME and not entity.is_internal)
      or entity.entity_type == EntityTypes.URL: entity_to_scan = entity.identifier
      
            scan_url = f"{url}&domainName={entity_to_scan}"              response = requests.get(scan_url)            
            response.raise_for_status()            
            register_details = response.json().get("WhoisRecord", {}).get("registrant", {})            if register_details:                
        entity.additional_properties.update(register_details)        successful_entities.append(entity) 

      if successful_entities:        
        output_message += "\n Successfully processed entities:\n {}".format("\n
        ".join([x.identifier for x in successful_entities]))
        siemplify.update_entities(successful_entities) # This is the actual
        enrichment (this function sends the data back to the server) 
    else:        
        output_message += "\n No entities where processed."      
  result_value = len(successful_entities) 

      siemplify.LOGGER.info("----------------- Main - Finished -----------------")    
      siemplify.end(output_message, result_value) 

  if __name__ == "__main__":    
      main()

Extrayez les paramètres. Le script extrait la clé API de la configuration de l'intégration. Cette clé est nécessaire pour authentifier les requêtes adressées à l'API XML WHOIS.
Identifiez les entités cibles. Le script identifie les entités à traiter. Il parcourt toutes les entités et se concentre uniquement sur deux types :

Noms d'hôte non internes
URL


  for entity in siemplify.target_entities:        
        siemplify.LOGGER.info(f"processing entity {entity.identifier}") if
        (entity.entity_type == EntityTypes.HOSTNAME and not entity.is_internal) or
        entity.entity_type == EntityTypes.URL: entity_to_scan = entity.identifier

Analysez le domaine et définissez l'étape d'enrichissement de l'action et le message de sortie. Cette action s'exécute dans un champ d'application Entité et ne nécessite donc pas de configurer des paramètres spécifiques. Ceux-ci sont déjà intégrés au code :


  scan_url = f"{url}&domainName={entity_to_scan}"

              response = requests.get(scan_url) response.raise_for_status()
              register_details = response.json().get("WhoisRecord",
              {}).get("registrant", {}) if register_details:
                  entity.additional_properties.update(register_details)
                  successful_entities.append(entity)


      if successful_entities:
          output_message += "\n Successfully processed entities:\n {}".format("\n
          ".join([x.identifier for x in successful_entities]))
          siemplify.update_entities(successful_entities) # This is the actual
          enrichment (this function sends the data back to the server)
      else:
          output_message += "\n No entities where processed."


      result_value = len(successful_entities)

Activez l'action, puis cliquez sur Enregistrer. Vous avez créé une intégration personnalisée avec trois actions personnalisées :

Une action Ping pour tester la connexion au produit WHOIS XML API.
Une action Obtenir les détails du domaine pour extraire des données sur un domaine et les présenter sous forme de résultat JSON.
Une action Enrichir les entités pour ajouter des données aux entités cibles, que vous pouvez consulter dans le module Explorateur d'entités.

Vous êtes maintenant prêt à créer votre première automatisation à l'aide des actions que vous avez personnalisées.

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