Développer votre première action personnalisée

Compatible avec :

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 sur le 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 :

  1. Accédez à l'environnement de développement intégré (IDE), puis cliquez sur Ajouter pour ajouter un élément IDE.
  2. Sélectionnez la case d'option Action.
  3. Nommez l'action Get Domain Details et sélectionnez l'intégration.
  4. Cliquez sur Créer. L'IDE génère un nouveau modèle avec des commentaires et des explications de code 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 :

  1. Dans le module IDE, cliquez sur Ajouter.
  2. Créez le premier paramètre : remplissez les champs pour Check Availability (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.
  3. Créez le deuxième paramètre : renseignez 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 :

  1. 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)
  2. 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)
  3. Créez la requête et traitez le résultat :
    1. 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.
    2. Une fois l'URL prête, envoyez une requête au site WHOIS.
    3. Analysez la réponse du site et ajoutez les données pertinentes au résultat de l'action.
    4. 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 Get Domain Details (Obtenir les détails du domaine), cliquez sur Get Domain Details (Obtenir les détails du domaine) pour ajouter un exemple JSON. Utilisez l'exemple JSON dans le concepteur de playbook de la procédure Créer votre première automatisation pour extraire un champ spécifique du fichier JSON.

  1. Obtenez le code JSON : copiez le code JSON à partir de l'exemple JSON du site WHOIS.
  2. 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.
  3. 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 :

  1. Accédez à l'onglet Test.
  2. Dans Champ d'application, sélectionnez votre scénario de test et votre instance d'intégration.
  3. Dans l'IDE, cliquez sur slideshow Play (Lire).
  4. Affichez le résultat de l'action dans l'onglet Test. Vous pouvez également consulter les journaux et les impressions dans 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 > Ingérer l'alerte en tant que scénario de test pour en créer un. Cette action crée un scénario 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 scénario de test dans la liste.

Pour créer un cas de test :

  1. Accédez à la page Demandes et sélectionnez une demande.
  2. Ingérez l'alerte en tant que scénario de test. Une demande portant le libellé Test est alors créée 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 :

  1. Dans l'IDE, créez une action et nommez-la Enrich Entities.
  2. 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()
  3. Extraire des 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.
  4. Identifiez les entités cibles. Le script identifie les entités à traiter. Il parcourt toutes les entités et ne se concentre que 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
  5. Analysez le domaine, puis définissez l'étape d'enrichissement de l'action et le message de sortie. Cette action s'exécute dans un champ d'application Entity et ne nécessite donc pas de configuration de paramètres spécifiques. Elle est déjà intégrée 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)
  6. 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 d'API WHOIS XML.
    • 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.