Creare azioni personalizzate

Supportato in:

Nella tua prima integrazione personalizzata, hai definito i parametri e creato un'azione Ping per testare la connessione. Questo documento spiega come creare due nuove azioni per l'integrazione personalizzata:

  • Ottieni dettagli dominio: recupera le informazioni sul dominio e presenta il risultato in formato JSON.
  • Arricchisci entità: arricchisce le entità con i dettagli del dominio.

Creare un'azione personalizzata

Per creare un'azione personalizzata:

  1. Vai all'ambiente di sviluppo integrato (IDE) e fai clic su Aggiungi per aggiungere un nuovo elemento IDE.
  2. Seleziona il pulsante di opzione Azione.
  3. Assegna all'azione il nome Get Domain Details e seleziona l'integrazione.
  4. Fai clic su Crea. L'IDE genera un nuovo modello con commenti ed spiegazioni del codice integrati.

Configurare i parametri dell'azione

In base alla documentazione dell'API WHOIS XML, l'azione Recupera dettagli dominio richiede due parametri: Check Availability e Domain Name. Per configurare questi parametri:

  1. Nel modulo IDE, fai clic su Aggiungi.
  2. Crea il primo parametro: compila i campi per Verifica disponibilità e fai clic su Salva. Questo parametro indica se il dominio è disponibile o meno e il risultato verrà utilizzato nell'automazione che creerai in un secondo momento.
  3. Crea il secondo parametro: compila i campi per Nome dominio e fai clic su Salva. Utilizza questo campo per inserire il dominio che vuoi che l'azione controlli.

Modifica l'azione Recupera dettagli dominio

Per modificare l'azione Ottieni dettagli dominio:

  1. Copia il codice fornito per Get Domain Details e incollalo nell'IDE. Rivedi il codice. L'oggetto deve utilizzare il metodo end della classe per restituire un messaggio di output e un valore di risultato, ad esempio:
    siemplify.end(msg, None)
  2. Estrai i parametri di integrazione e azione: i parametri di integrazione, come la chiave API, vengono estratti utilizzando la funzione siemplify.extract_configuration_param. Allo stesso modo, i parametri di azione che hai configurato, inclusi Domain Name e Check availability, vengono estratti con la funzione 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. Crea la richiesta ed elabora il risultato:
    1. Dopo aver estratto i parametri di integrazione e azione, puoi creare l'URL della richiesta. L'URL viene creato in base al valore booleano del parametro availability_check.
    2. Una volta pronto l'URL, invia una richiesta al sito WHOIS.
    3. Analizza la risposta del sito e aggiungi i dati pertinenti al risultato dell'azione.
    4. Definisci il messaggio di output che verrà presentato all'utente e includi il risultato 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()

Aggiungi un risultato JSON all'azione

Nell'ambito dell'azione Ottieni dettagli dominio, fai clic su Ottieni dettagli dominio per aggiungere un esempio JSON. Utilizza l'esempio JSON nel designer del playbook nella procedura "Crea la tua prima automazione" per estrarre un campo specifico nel JSON.

  1. Recupera il JSON: copia il JSON dall'esempio JSON del sito WHOIS.
  2. Attiva l'icona JSON: nella scheda Dettagli dell'IDE, attiva il pulsante di attivazione/disattivazione Includi risultato JSON per rendere visibile l'icona JSON nella parte superiore dell'IDE.
  3. Importa il file JSON: fai clic su file_json Gestisci esempio JSON > login Importa esempio JSON.

Testare l'azione

Per testare l'azione che hai creato:

  1. Vai alla scheda Test.
  2. In Ambito, seleziona lo Scenario di test e l'Istanza di integrazione.
  3. Fai clic su presentazione Riproduci nell'IDE.
  4. Visualizza il risultato dell'azione nella scheda Test. Puoi anche esaminare i log e le stampe selezionando la scheda Output di debug al termine del test.

Creare uno scenario di test

Se non hai casi di test nel tuo ambiente, vai a Casi > Inserisci avviso come caso di test per crearne uno. Questa azione crea uno scenario di test che viene visualizzato con l'etichetta Test nella coda delle richieste. Dopo aver creato lo scenario di test, torna all'IDE e scegli lo scenario di test dall'elenco.

Per creare uno scenario di test:

  1. Vai alla pagina Richieste e seleziona una richiesta.
  2. Importa l'avviso come scenario di test. Viene creato un nuovo caso con l'etichetta Test nella coda dei casi.

Dopo aver creato un caso di test, torna all'IDE e selezionalo dall'elenco.

Crea un'azione di arricchimento

Questa parte della procedura si concentra sulla creazione di un'azione di arricchimento per aggiungere nuovi dati alle entità. I dati arricchiti possono poi essere visualizzati in Esplora entità. Per creare un'azione di arricchimento:

  1. Nell'IDE, crea una nuova azione e chiamala Enrich Entities.
  2. Copia e incolla il seguente codice nell'azione: 
    
  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. Estrai i parametri. Lo script estrae la chiave API dalla configurazione dell'integrazione. Questa chiave è necessaria per autenticare le richieste all'API WHOIS XML.
  4. Identifica le entità target. Lo script identifica le entità da elaborare. Esegue l'iterazione su tutte le entità e si concentra solo su due tipi:
    • Nomi host non interni
    • 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. Scansiona il dominio e definisci il passaggio di arricchimento dell'azione e il messaggio di output. Questa azione viene eseguita in un ambito Entità e, pertanto, non richiede la configurazione di parametri specifici, che sono già incorporati nel codice: 
    
  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. Attiva l'azione e fai clic su Salva. Ora hai creato un'integrazione personalizzata con tre azioni personalizzate:
    • Un'azione Ping per testare la connessione al prodotto API WHOIS XML.
    • Un'azione Ottieni dettagli dominio per estrarre i dati relativi a un dominio e presentarli come risultato JSON.
    • Un'azione Arricchisci entità per aggiungere dati aggiuntivi alle entità di destinazione, che puoi visualizzare nel modulo Esplora entità.

    Ora puoi creare la tua prima automazione utilizzando le azioni che hai personalizzato.

Hai bisogno di ulteriore assistenza? Ricevi risposte dai membri della community e dai professionisti di Google SecOps.