Diese Seite wurde von der Cloud Translation API übersetzt.

Benutzerdefinierte Aktionen erstellen

Unterstützt in:

Google SecOps SOAR

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 präsentiert das Ergebnis im JSON-Format.
Entitäten anreichern: Reichert Entitäten mit Domaindetails an.

Benutzerdefinierte Aktion erstellen

So erstellen Sie eine benutzerdefinierte Aktion:

Rufen Sie die integrierte Entwicklungsumgebung (IDE) auf und klicken Sie auf Hinzufügen, um ein neues IDE-Element hinzuzufügen.
Wählen Sie das Optionsfeld Aktion aus.
Geben Sie der Aktion den Namen Get Domain Details und wählen Sie die Integration aus.
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 zwei Parameter erforderlich: Check Availability und Domain Name. So konfigurieren Sie diese Parameter:

Klicken Sie im IDE-Modul auf Hinzufügen.
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.
Zweiten Parameter erstellen: Füllen Sie die Felder für Domain Name aus und klicken Sie auf Save (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 (Domänendetails abrufen):

Kopieren Sie den bereitgestellten Code für Get Domain Details (Domaindetails abrufen) 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)

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)

Erstellen Sie die Anfrage und verarbeiten Sie das Ergebnis:

Nachdem Sie die Integrations- und Aktionsparameter extrahiert haben, können Sie die Anfrage-URL erstellen. Die URL wird basierend auf dem booleschen Wert des Parameters availability_check erstellt.
Sobald die URL bereit ist, senden Sie eine Anfrage an die WHOIS-Website.
Parsen Sie die Antwort der Website und fügen Sie die relevanten Daten dem Ergebnis der Aktion hinzu.

Definieren Sie die Ausgabenachricht, die dem Nutzer präsentiert 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()

JSON-Ergebnis zur Aktion hinzufügen

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 zu extrahieren.

JSON abrufen: Kopieren Sie das JSON aus dem JSON-Beispiel auf der WHOIS-Website.
JSON-Symbol aktivieren: Aktivieren Sie auf dem Tab Details der IDE die Ein/Aus-Schaltfläche Include JSON Result (JSON-Ergebnis einfügen), damit das JSON-Symbol oben in der IDE angezeigt wird.
JSON importieren: Klicken Sie auf file_json JSON-Beispielcode verwalten > login JSON-Beispiel importieren.

Aktion testen

So testen Sie die erstellte Aktion:

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

Testlauf erstellen

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

So erstellen Sie einen Testlauf:

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

Nachdem Sie einen Testfall 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:

Erstellen Sie in der IDE eine neue Aktion und nennen Sie sie Enrich Entities.

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()

Parameter extrahieren Das Skript extrahiert den API-Schlüssel aus der Konfiguration der Integration. Dieser Schlüssel ist erforderlich, um Anfragen an die WHOIS XML API zu authentifizieren.
Zielentitäten identifizieren Das Skript ermittelt, welche Einheiten verarbeitet werden sollen. Es 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

Scannen Sie die Domain und definieren Sie den Anreicherungsschritt der Aktion und die Ausgabenachricht. Diese Aktion wird im Entity-Bereich 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)

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 der Daten als JSON-Ergebnis.
Eine Enrich Entities-Aktion (Entitäten anreichern), um den Zielentitäten zusätzliche Daten hinzuzufügen, die Sie im Modul Entity Explorer (Entitäten-Explorer) sehen können.

Jetzt können Sie Ihre erste Automatisierung erstellen und dabei die angepassten Aktionen verwenden.

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