Erste benutzerdefinierte Aktion entwickeln

Unterstützt in:

In Ihrer ersten benutzerdefinierten Integration haben Sie die Parameter definiert und eine Ping-Aktion erstellt, um die Verbindung zu testen. In diesem Dokument wird beschrieben, wie Sie zwei neue Aktionen für Ihre benutzerdefinierte Integration erstellen:

  • Domaindetails abrufen: Ruft Domaininformationen ab und stellt das Ergebnis im JSON-Format dar.
  • Entitäten anreichern: Reichert Entitäten mit Domaindetails an.

Benutzerdefinierte Aktion erstellen

So erstellen Sie eine benutzerdefinierte Aktion:

  1. Rufen Sie die integrierte Entwicklungsumgebung (IDE) auf und klicken Sie auf Hinzufügen, um ein neues IDE-Element hinzuzufügen.
  2. Wählen Sie das Optionsfeld Aktion aus.
  3. Geben Sie der Aktion den Namen Get Domain Details und wählen Sie die Integration aus.
  4. Klicken Sie auf Erstellen. Die IDE generiert eine neue Vorlage mit integrierten Codekommentaren und Erklärungen.

Aktionsparameter konfigurieren

Gemäß der WHOIS XML API-Dokumentation sind für die Aktion Get Domain Details (Domaindetails abrufen) zwei Parameter erforderlich: Check Availability und Domain Name. So konfigurieren Sie diese Parameter:

  1. Klicken Sie im IDE-Modul auf Hinzufügen.
  2. Erstellen Sie den ersten Parameter: Füllen Sie die Felder für Verfügbarkeit prüfen aus und klicken Sie auf Speichern. Dieser Parameter gibt an, ob die Domain verfügbar ist oder nicht. Das Ergebnis wird in der Automatisierung verwendet, die Sie später erstellen.
  3. Erstellen Sie den zweiten Parameter: Füllen Sie die Felder für Domainname aus und klicken Sie auf Speichern. Geben Sie in diesem Feld die Domain ein, die von der Aktion geprüft werden soll.

Aktion „Domaindetails abrufen“ bearbeiten

So bearbeiten Sie die Aktion Get Domain Details (Domaindetails abrufen):

  1. Kopieren Sie den bereitgestellten Code für Get Domain Details und fügen Sie ihn in die IDE ein. Sehen Sie sich den Code an. Das Objekt muss die end-Methode der Klasse verwenden, um eine Ausgabenachricht und einen Ergebniswert zurückzugeben, z. B.:
    siemplify.end(msg, None)
  2. Integrations- und Aktionsparameter extrahieren: Die Integrationsparameter, z. B. der API-Schlüssel, werden mit der Funktion siemplify.extract_configuration_param extrahiert. Ebenso werden die von Ihnen konfigurierten Aktionsparameter, einschließlich Domain Name und Check availability, mit der Funktion siemplify.extract_action_param extrahiert. 
    
    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. Anfrage erstellen und Ergebnis verarbeiten:
    1. Nachdem Sie die Integrations- und Aktionsparameter extrahiert haben, können Sie die Anfrage-URL erstellen. Die URL wird auf Grundlage des booleschen Werts des Parameters availability_check erstellt.
    2. Sobald die URL verfügbar ist, senden Sie eine Anfrage an die WHOIS-Website.
    3. Analysieren Sie die Antwort der Website und fügen Sie die relevanten Daten dem Ergebnis der Aktion hinzu.
    4. Definieren Sie die Ausgabenachricht, die dem Nutzer angezeigt wird, und fügen Sie das JSON-Ergebnis ein.
      
  # 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()

Fügen Sie der Aktion ein JSON-Ergebnis hinzu.

Klicken Sie im Rahmen der Aktion Get Domain Details (Domaindetails abrufen) auf Get Domain Details (Domaindetails abrufen), um ein JSON-Beispiel hinzuzufügen. Verwenden Sie das JSON-Beispiel im Playbook-Designer im Abschnitt Erste Automatisierung erstellen, um ein bestimmtes Feld im JSON-Code zu extrahieren.

  1. JSON abrufen: Kopieren Sie das JSON aus dem JSON-Beispiel der WHOIS-Website.
  2. JSON-Symbol aktivieren: Aktivieren Sie auf dem Tab Details der IDE die Option JSON-Ergebnis einbeziehen, damit das JSON-Symbol oben in der IDE angezeigt wird.
  3. Importieren Sie die JSON-Datei: Klicken Sie auf file_json JSON-Beispiel verwalten > login JSON-Beispiel importieren.

Aktion testen

So testen Sie die erstellte Aktion:

  1. Rufen Sie den Tab Testen auf.
  2. Wählen Sie unter Umfang Ihren Testlauf und Ihre Integrationsinstanz aus.
  3. Klicken Sie in der IDE auf Diashow Wiedergeben.
  4. Sehen Sie sich das Ergebnis der Aktion auf dem Tab Test an. Sie können die Logs und Ausgaben auch nach Abschluss des Tests auf dem Tab Debug-Ausgabe einsehen.

Testlauf erstellen

Wenn Sie keine Testläufe in Ihrer Umgebung haben, können Sie einen erstellen, indem Sie zu Fälle  > Benachrichtigung als Testlauf aufnehmen gehen. Mit dieser Aktion wird ein Testlauf erstellt, der in Ihrer Warteschlange für Kundenservicemitarbeiter mit dem Label Test angezeigt wird. Nachdem Sie den Testlauf erstellt haben, kehren Sie zur IDE zurück und wählen Sie den Testlauf aus der Liste aus.

So erstellen Sie einen Testlauf:

  1. Rufen Sie die Seite Fälle auf und wählen Sie einen Fall aus.
  2. Nehmen Sie die Benachrichtigung als Testfall auf. Dadurch wird ein neuer Fall mit dem Label Test in Ihrer Fallwarteschlange erstellt.

Nachdem Sie einen Testlauf erstellt haben, kehren Sie zur IDE zurück und wählen Sie ihn aus der Liste aus.

Anreicherungsaktion erstellen

In diesem Teil der Anleitung geht es darum, eine Anreicherungsaktion zu erstellen, um Entitäten neue Daten hinzuzufügen. Die angereicherten Daten können dann im Entity Explorer aufgerufen werden. So erstellen Sie eine Anreicherungsaktion:

  1. Erstellen Sie in der IDE eine neue Aktion und nennen Sie sie Enrich Entities.
  2. Kopieren Sie den folgenden Code und fügen Sie ihn in die Aktion ein: 
    
  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. Parameter extrahieren Das Script extrahiert den API-Schlüssel aus der Konfiguration der Integration. Dieser Schlüssel ist für die Authentifizierung von Anfragen an die WHOIS XML API erforderlich.
  4. Zielentitäten identifizieren Das Script ermittelt, welche Einheiten verarbeitet werden sollen. Dabei werden alle Entitäten durchlaufen und nur zwei Typen berücksichtigt:
    • Nicht interne Hostnamen
    • URLs
      • 
  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. Scannen Sie die Domain und definieren Sie den Anreicherungsschritt der Aktion und die Ausgabemeldung. Diese Aktion wird auf Entitätsebene ausgeführt. Daher müssen Sie keine bestimmten Parameter konfigurieren. Diese sind bereits im Code enthalten: 
    
  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. Aktivieren Sie die Aktion und klicken Sie auf Speichern. Sie haben jetzt eine benutzerdefinierte Integration mit drei benutzerdefinierten Aktionen erstellt:
    • Eine Ping-Aktion zum Testen der Verbindung zum WHOIS XML API-Produkt.
    • Eine Get Domain Details-Aktion zum Extrahieren von Daten zu einer Domain und zum Präsentieren dieser Daten als JSON-Ergebnis.
    • Eine Enrich Entities-Aktion (Entitäten anreichern), um zusätzliche Daten zu Zielentitäten hinzuzufügen, die Sie im Modul Entity Explorer (Entitäten-Explorer) sehen können.

    Jetzt kannst du mit den von dir angepassten Aktionen deine erste Automatisierung erstellen.

Benötigen Sie weitere Hilfe? Antworten von Community-Mitgliedern und Google SecOps-Experten erhalten