Benutzerdefinierte Transformationsfunktionen und logische Operatoren

Unterstützt in:

Google SecOps SOAR

Hinweis: Dieses Feature unterliegt den Bedingungen des Pre-GA-Angebots in den dienstspezifischen Nutzungsbedingungen für Google Security Operations. Pre-GA-Features werden eventuell nur eingeschränkt unterstützt und Änderungen an diesen Features sind möglicherweise nicht mit anderen Pre-GA-Versionen kompatibel. Weitere Informationen finden Sie in den Richtlinien für den technischen Support von Google SecOps und den dienstspezifischen Nutzungsbedingungen für Google SecOps.

Sie können benutzerdefinierte Python-basierte Transformationsfunktionen und logische Operatoren direkt in der IDE erstellen und in Ihren Playbooks für komplexe und vielseitige Anwendungsfälle verwenden.

Erweiterungspakete

Ein Erweiterungspaket ist ein spezieller Integrationstyp, der als Container für benutzerdefinierte Transformationsfunktionen und logische Operatoren dient. Im Gegensatz zu Standardintegrationen erfordern Erweiterungspakete keine Instanzkonfiguration und können direkt in der IDE erstellt werden.

Best Practices für Erweiterungspakete

• Konsolidierung:Erstellen Sie ein Haupt-Erweiterungspaket und fügen Sie ihm mehrere Transformationsfunktionen oder logische Operatoren hinzu.
• Trennung:Erstellen Sie ein neues Erweiterungspaket, wenn Sie eine andere Gruppe von Python-Bibliotheken (Abhängigkeiten) benötigen, die mit dem Hauptpaket in Konflikt stehen könnten.

Wichtig:Zum Erstellen von Erweiterungspaketen in der IDE ist die Berechtigung Alle Umgebungen erforderlich.

Erweiterungspaket erstellen

So erstellen Sie ein neues Erweiterungspaket:

1. Klicken Sie auf Antwort > IDE.
2. Klicken Sie auf Hinzufügen Neues Element erstellen.
3. Wählen Sie im Drop-down-Menü die Option Extension Pack (Erweiterungspaket) aus.
4. Geben Sie einen eindeutigen Namen für das Erweiterungspaket an.
Hinweis:Der Name kann nach dem Erstellen nicht mehr geändert werden.
5. Klicken Sie auf Speichern.

Abhängigkeiten hochladen

Wie bei Standardintegrationen werden Erweiterungspakete in einer virtuellen Umgebung ausgeführt, in der Sie Python-Bibliotheken verwalten können.

So verwalten Sie Ihre Bibliotheken:

1. Öffnen Sie die Extension Pack-Einstellungen in der IDE.
2. Fügen Sie erforderliche Python-Bibliotheken aus PyPi hinzu oder laden Sie sie von Ihrem Computer hoch.

Diese Abhängigkeiten sind für alle Transformer und logischen Operatoren verfügbar, die in diesem Erweiterungspaket enthalten sind.

Importieren und exportieren

Sie können Erweiterungspakete manuell direkt über die IDE-Oberfläche importieren und exportieren.

Hinweis:Import und Export sind möglicherweise nicht für Kunden verfügbar, die die Migration der 2. Phase noch nicht abgeschlossen haben. Weitere Informationen finden Sie in der Übersicht über die SOAR-Migration.

Benutzerdefinierte Transformatoren

Benutzerdefinierte Transformer sind benutzerdefinierte Python-Funktionen, die die integrierten Funktionen im Ausdrucksgenerator erweitern. Sie können sie direkt in der IDE erstellen, um Daten zu extrahieren und zu bearbeiten. Außerdem können sie zusammen mit vorhandenen integrierten Funktionen verwendet werden.

Benutzerdefinierten Transformer erstellen

So definieren Sie einen neuen benutzerdefinierten Transformer:

1. Suchen Sie in der IDE nach dem Zielerweiterungspaket.
2. Wählen Sie das Ziel-Erweiterungspaket aus, dem Sie ein neues Element hinzufügen möchten.
3. Wählen Sie Benutzerdefinierte Transformationsfunktion aus.
4. Geben Sie einen Namen ein.
Hinweis:Der Name kann nach dem Erstellen nicht mehr geändert werden.
5. Optional: Fügen Sie eine Beschreibung hinzu. Diese Beschreibung wird angezeigt, wenn Sie den Mauszeiger im Ausdrucks-Editor auf den benutzerdefinierten Transformer bewegen.
6. Definieren Sie die Skriptlogik mit Python. Sie können die bereitgestellte Standardvorlage als Ausgangspunkt verwenden.
   • Das Skript muss eine main-Funktion enthalten, wie in der vordefinierten Vorlage gezeigt.
   • Das Skript muss dem Ausdrucks-Builder ein Ergebnis zurückgeben. Verwenden Sie dazu die SDK-Funktion end.
   • Die Eingabe des benutzerdefinierten Transformers kann verschiedene Typen haben, z. B. String oder Liste. Achten Sie darauf, dass Sie ihn in Ihrer main-Funktion in den erwarteten Typ konvertieren.
   • Sie können nur eine Teilmenge der SDK-Methoden in der IDE für Transformer verwenden:
     • transformer.extract_param("ParamName"): Zum Abrufen von Eingabewerten.
     • transformer.LOGGER: Zum Schreiben von Logs für das Debugging.
     • transformer.end(result): Gibt den transformierten Wert zurück.
7. Parameter erstellen:
   • Jede benutzerdefinierte Transformer-Funktion enthält einen Standardparameter Input. Dieser Parameter stellt die Eingabedaten dar, also den Platzhalter, auf den sich die Funktion bezieht. Dieser Parameter kann nicht gelöscht werden.
   • Außerdem können Sie optionale Parameter hinzufügen, die in Ihrer Funktion verwendet werden sollen.
8. Dokumentation (optional): Definieren Sie die In-Product-Dokumentation für den Ausdrucksgenerator:
   • Erwartete Eingabe:Beschreiben Sie den Datentyp, den die Funktion für diesen Transformer erwartet (z. B. „String“ oder „Liste von Strings“).
   • Erwartete Ausgabe:Beschreiben Sie den Datentyp, den die Funktion für diesen Transformer zurückgeben soll (z. B. „boolean“).
   • Verwendungsbeispiel:Geben Sie ein Beispiel dafür an, wie die Funktion aufgerufen wird (z. B. if_empty("new_value")).

Sie können die Logik Ihrer benutzerdefinierten Transformationsfunktion direkt in der IDE testen, bevor Sie sie in einem Playbook verwenden. So können Sie prüfen, ob Ihr Python-Script verschiedene Eingabetypen und Parameter korrekt verarbeitet und die erwarteten Ergebnisse zurückgibt.

Zeitlimit

• Standard-Zeitlimit:1 Minute.
• Maximales Zeitlimit:3 Minuten.

Hinweis: Da die Plattform auf den Abschluss der Funktion wartet, müssen Sie die Ausführungszeit minimieren. Konzentrieren Sie sich auf direkte Datentransformationen und vermeiden Sie umfangreiche Verarbeitung oder das Abfragen externer Quellen.

Benutzerdefinierte Transformer im Ausdrucks-Builder verwenden

Nach dem Speichern werden benutzerdefinierte Transformer in der Funktionsliste des Ausdrucks-Generators neben den integrierten Funktionen angezeigt. Sie sind durch das Format ExtensionPackName.TransformerName gekennzeichnet. Wenn Sie den Mauszeiger auf die Funktion bewegen, wird die Dokumentation angezeigt, die aus Ihren Parameterbeschreibungen generiert wurde.

Unterstützung aller Platzhalter (JSON und nicht JSON)

Der Ausdruck-Builder unterstützt alle Platzhalter, die im Playbook Designer verfügbar sind, einschließlich Nicht-JSON-Ergebnissen.

Für Platzhalter, die nicht im JSON-Format sind:

• Sie können manuell Beispieldaten in den Ausdrucks-Generator eingeben, um die Logik für verschiedene Eingabetypen zu testen: String, Liste (kommagetrennte Werte) und JSON.
• Wenn Sie einen Eingabetyp testen, wird nicht garantiert, dass der Platzhalter zur Laufzeit diesen bestimmten Typ zurückgibt.
• Die meisten Platzhalter werden als Strings aufgelöst, mit Ausnahme bestimmter Typen, die je nach Menge als String oder Liste aufgelöst werden (z. B. entity.identifier). Bei diesen Typen empfiehlt es sich, die Eingabe immer als Liste zu behandeln.

Hinweis:Beispieldaten sind temporär und werden nicht gespeichert, nachdem Sie den Ausdrucks-Generator geschlossen oder den Ausdruck gespeichert haben. Wenn Sie den Builder noch einmal öffnen, müssen Sie die Beispieldaten noch einmal eingeben.

Fehlerbehandlung

Wenn bei der Ausführung einer benutzerdefinierten Transformationsfunktion ein Fehler auftritt, schlägt die Playbook-Aktion fehl, in der diese Transformation verwendet wird. Die spezifische Fehlermeldung, die vom Python-Skript generiert wird, wird auf dem Bildschirm in der Ansicht für die Playbook-Ausführung angezeigt. So können Sie die Logik direkt beheben.

Benutzerdefinierte logische Operatoren

Mit benutzerdefinierten logischen Operatoren können Sie Ihre eigene boolesche Logik zum Vergleichen von Werten definieren.

Benutzerdefinierten logischen Operator erstellen

So definieren Sie einen neuen logischen Operator:

1. Suchen Sie in der IDE nach dem gewünschten Extension Pack.
2. Wählen Sie Benutzerdefinierter logischer Operator aus.
3. Geben Sie einen Namen ein.
Hinweis:Der Name kann nach dem Erstellen nicht mehr geändert werden.
4. Optional: Fügen Sie im Playbook Designer eine Beschreibung für das Menü mit logischen Operatoren hinzu.
5. Definieren Sie die Skriptlogik mit Python. Sie können die bereitgestellte vordefinierte Vorlage als Ausgangspunkt verwenden.
   • Das Skript muss eine main-Funktion enthalten.
   • Das Skript muss ein boolesches Ergebnis für die Bedingung zurückgeben. Verwenden Sie dazu die SDK-Funktion end.
   • Sie können nur eine Teilmenge der SDK-Methoden in der IDE für logische Operatoren verwenden:
   • logical_operator.extract_param("ParamName"): Zum Abrufen von Eingabewerten.
   • logical_operator.LOGGER: Zum Schreiben von Logs für das Debugging.
   • logical_operator.end(result): Das Ergebnis ist ein boolescher Wert (true oder false).

Sie können die Logik Ihres benutzerdefinierten logischen Operators direkt in der IDE testen. So können Sie Testwerte für die Argumente eingeben und prüfen, ob die Funktion basierend auf den von Ihnen definierten Bedingungen das richtige boolesche Ergebnis (True oder False) zurückgibt.

Parameter

Benutzerdefinierte logische Operatoren akzeptieren zwei Parameter: Linke Seite (erforderlich und nicht bearbeitbar) und Rechte Seite (optional; kann vom Nutzer deaktiviert werden).

• Beispiel 1:if [left side] not in [right side].
• Beispiel 2:if [left side] is greater than 80 (keine rechte Seite).

Zeitlimit

• Standard-Zeitlimit:1 Minute.
• Maximales Zeitlimit:3 Minuten.

Hinweis:Da die Plattform wartet, bis die Funktion abgeschlossen ist, müssen Sie die Ausführungszeit minimieren. Es empfiehlt sich, sich auf direkte Datentransformationen zu konzentrieren und keine externen Quellen abzufragen oder aufwendige Verarbeitungsschritte durchzuführen.

In Playbooks verwenden

Benutzerdefinierte logische Operatoren werden im Operatormenü unter Playbook-Bedingungen, Bedingungen für vorherige Aktionen und Entität auswählen angezeigt.

Benutzerdefinierte logische Operatoren können neben Standardoperatoren wie „Gleich“ oder „Enthält“ ausgewählt werden.

Fehlerbehandlung

Wenn bei der Ausführung einer benutzerdefinierten Funktion für logische Operatoren ein Fehler auftritt, schlägt die Playbook-Bedingung oder der Playbook-Schritt, in dem dieser Operator verwendet wird, fehl. Die vom Python-Skript zurückgegebene Fehlermeldung wird in der Playbook-Ausführungsansicht angezeigt, um die Fehlerbehebung zu erleichtern.

Beschränkungen

• Benutzerdefinierte Transformationsfunktionen und logische Operatoren werden in Triggern oder Webhooks nicht unterstützt.

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