Benutzerdefinierten Connector erstellen

Unterstützt in:

Google SecOps SOAR

Hinweis:In diesem Dokument wird davon ausgegangen, dass Sie mit Python und der objektorientierten Programmierung vertraut sind.

In diesem Dokument erfahren Sie, wie Sie mit dem SOAR SDK benutzerdefinierte Integrationen für Drittanbietertools erstellen, die möglicherweise nicht im Content Hub verfügbar sind. Connectors werden verwendet, um Daten aus Datenquellen aufzunehmen, die in der Regel, aber nicht immer, eine Art Benachrichtigungswarteschlange haben. Vorgänge, Benachrichtigungen und Ereignisse werden in der Plattform erstellt, wenn der Connector mit der Google SecOps-Anwendung interagiert. Ein Connector nimmt Basisereignisdaten auf, weist sie einer Benachrichtigung zu und sendet die Benachrichtigung dann an die Google SecOps-Anwendung und ihre Datenverarbeitungspipeline.

Hinweis:Weitere Informationen zur TIP Common-Bibliothek

So erstellen Sie einen benutzerdefinierten Connector:

1. Erstellen Sie eine Manager-Klasse, die die API-Logik für das Drittanbietertool enthält.
2. Connector mit der IDE erstellen

Manager erstellen

Der erste Schritt beim Erstellen eines Connectors besteht darin, eine Manager-Klasse zu erstellen, die die gesamte erforderliche API-Logik für die Technologie enthält, die Sie einbinden. Die Netskope-Integration in Google SecOps enthält beispielsweise einen vordefinierten Manager. Dieser Manager enthält die gesamte Logik, die für die Interaktion mit der Netskope API erforderlich ist, und kann als Modell für Ihre eigene Implementierung verwendet werden.

Connector erstellen

Erstellen Sie in der IDE einen neuen Connector. Folgen Sie dazu der Anleitung unter Benutzerdefinierte Integration erstellen. Die IDE generiert eine allgemeine Vorlage mit Codekommentaren, die die grundlegende Struktur und die Anforderungen eines Connector-Scripts beschreiben.

Die Connector-Logik kann variieren, aber der Prozess umfasst im Allgemeinen die folgenden Hauptschritte:

1. Verwenden Sie die API des Drittanbietertools, um Benachrichtigungen, Erkennungen oder Ereignisse abzurufen. Bei Netskope wird dies über die Methode get_alerts() gehandhabt. Damit Warnungen nicht dupliziert werden, senden Sie eine Abfrage nach Zeitstempel und aktualisieren Sie sie nach jedem Durchlauf.
2. Erstellen Sie eine Benachrichtigung mit der Klasse AlertInfo (früher CaseInfo) und weisen Sie alle erforderlichen Felder zu.
3. Rufen Sie die zugehörigen Ereignisdaten ab und reduzieren Sie sie auf eine Ebene, um Probleme mit verschachtelten Listen und Dictionaries zu vermeiden. Hängen Sie die reduzierten Ereignisse dann an die Benachrichtigung an.
4. Sortieren Sie die Benachrichtigungen nach Zeit und speichern Sie den neuesten Zeitstempel, um ihn in der nächsten Abfrage zu verwenden.

Hinweis:Eine Benachrichtigung kann mehrere Ereignisse enthalten. SIEM-Plattformen korrelieren beispielsweise mehrere Ereignisse zu einem einzigen Alarm (z. B. Trellix ESM) oder Verstoß (z. B. QRadar). Im Gegensatz dazu wird bei Endpunkterkennungstools in der Regel ein Ereignis pro Benachrichtigung generiert. Die Connector-Logik sollte die Struktur der Datenquelle widerspiegeln.

Importe und das SDK

Jeder Connector muss Folgendes tun:

• Importieren Sie die Klasse SiemplifyConnectorExecution aus SiemplifyConnectors. Diese Klasse wird in der Regel in der Funktion main() des Connectors instanziiert. Das Script endet, wenn dieses Objekt eine Liste von Benachrichtigungen mit der Methode return_package() an die Google SecOps-Anwendung übergibt.
• Importieren Sie die Klasse AlertInfo aus SiemplifyConnectorsDataModel. Durch das Instanziieren dieser Klasse wird das Benachrichtigungsobjekt erstellt. In diesem Beispiel wird sie in SiemplifyAlertInfo umbenannt, um Verwechslungen mit den integrierten Benachrichtigungsobjekten des Quellsystems (Netskope) zu vermeiden. Diese Umbenennung ist optional.

Das Modul SiemplifyUtils bietet häufig verwendete Methoden für die Protokollierung, die Verarbeitung von Datenformaten, Zeitumrechnungen und mehr. Wir empfehlen, output_handler, dict_to_flat und unix_now zu importieren, da sie für die Hauptfunktionen, einschließlich der Zeitverarbeitung, unerlässlich sind.

Die meisten Connectors importieren auch die Manager-Klasse der Integration. Einige Integrationen umfassen mehr als einen Manager. Je nach Anwendungsfall können auch zusätzliche Standard-Python-Bibliotheken importiert werden.

Hinweis:Ältere Connectors können CaseInfo aus SiemplifyConnectors verwenden. Dies ist dieselbe Klasse wie AlertInfo und entspricht einer veralteten Namenskonvention.

Konstante Variablen

Es empfiehlt sich, einige konstante Variablen für die spätere Verwendung zu deklarieren.

Abbildung 1: Konstante Variablen

Beispiel für ein Script zum Erstellen der Google SecOps-Benachrichtigung

Eine Benachrichtigung wird erstellt, indem ein Objekt der Klasse AlertInfo instanziiert wird, wie bereits beschrieben. In diesem Beispiel wird sie in SiemplifyAlertInfo() umbenannt, um Verwechslungen mit dem Quellsystem zu vermeiden. Das alert_info-Objekt enthält mehrere erforderliche Eigenschaften, die definiert werden müssen, damit die Anwendung die Benachrichtigung richtig verarbeiten kann. Die Funktion build_alert_info empfängt eine Netskope-Benachrichtigung (im JSON-Rohformat, von der API empfangen) und das Objekt Siemplify als Eingaben. Anschließend wird die Netskope-Benachrichtigung geparst und den Feldern `alert_info` werden die entsprechenden Werte zugewiesen.

Für diese Funktion werden auch zuvor definierte Konstanten verwendet. Alle Eigenschaften, die für das alert_info-Objekt festgelegt sind, werden Teil des Benachrichtigungsobjekts in der Google SecOps-Anwendung.

In Zeile 35 (Abbildung 2) wird ein wichtiger Teil dieses Prozesses hervorgehoben: Die Benachrichtigung wird mit der Methode dict_to_flat vereinfacht und dann an die Eigenschaft events angehängt.

Abbildung 2: Beispiel für ein Skript zum Erstellen einer Benachrichtigung

 

Eine Benachrichtigung kann mehrere Ereignisse enthalten. In diesem Fall müssen Sie eine Logik einfügen, mit der jedes Ereignis angemessen verarbeitet wird. In diesem Beispiel enthält jede Benachrichtigung nur ein Ereignis, sodass die Standardimplementierung ausreicht.

Die Methode dict_to_flat wird verwendet, um die Roh-JSON-Struktur zu vereinfachen. So lassen sich Probleme mit verschachtelten Listen und Wörterbüchern vermeiden. Vereinfachte Schlüssel/Wert-Paare sind leicht modifizierte Versionen der Originale.

Sehen Sie sich die folgende Logik in Abbildung 2 an:

• display_id wird mit der uuid-Bibliothek ein zufällig generierter Wert zugewiesen. Netskope-Benachrichtigungen enthalten kein UUID-Feld. Wenn eines verfügbar wäre, könnte es stattdessen verwendet werden.
• ticket_id ist so eingestellt, dass es mit display_id übereinstimmt. Beide Felder müssen pro Benachrichtigung im System eindeutig sein. Diese Eindeutigkeit wird durch die Generierung einer zufälligen UUID gewährleistet.
• name ist der Name der Benachrichtigung und wird in der GUI angezeigt.
• rule_generator bezieht sich auf die Regel, die die Benachrichtigung im Quellsystem generiert hat. Dieses Feld ist möglicherweise nicht immer in den Rohdaten vorhanden. Wenn er fehlt, können Sie einen beliebigen Stringwert zuweisen. Er darf jedoch nicht leer bleiben.
• start_time und end_time stehen für die Zeitstempel der Benachrichtigung. In diesem Beispiel enthält die Netskope-Meldung einen Unix-Epochen-Zeitstempel, der mit 1.000 multipliziert werden muss, um ihn in Millisekunden zu konvertieren. Dies ist das erwartete Format für Google SecOps. Wenn die Quelle ein anderes Format verwendet, müssen Sie sie konvertieren. Im SiemplifyUtils.py-Modul finden Sie hilfreiche Methoden zur Zeitumrechnung.
• priority: Die Google SecOps-Anwendung weist jedem Fall eine Priorität basierend auf der Priorität der zugehörigen Benachrichtigung zu. In der Google SecOps API werden numerische Werte mithilfe des folgenden Schemas den visuellen Labels zugeordnet, wobei der Ganzzahlwert im Connector übergeben wird: {"Informative": -1, "Low": 40, "Medium": 60, "High": 80, "Critical": 100}, wobei der Ganzzahlwert im Connector übergeben wird. Wenn Sie beispielsweise `100` übergeben, wird die Benachrichtigung in der Benutzeroberfläche als Kritisch gekennzeichnet. In diesem Connector wird eine zusätzliche Hilfsfunktion verwendet, um die Schweregrade von Netskope mithilfe der Konstanten `SEVERITY_MAP` dieser Prioritätsskala zuzuordnen. Da die Schweregradfelder von Netskope jedoch inkonsistent sind, ist für die Zuordnung zusätzliche Logik erforderlich, um mehrere Felder auszuwerten.
• device_vendor und device_product werden Werte aus Konstanten zugewiesen, die zuvor im Script definiert wurden.
• environment ist entscheidend, wenn Sie mehrere Umgebungen in Google SecOps verwenden. In diesem Fall stammt sie aus dem siemplify-Objekt und entspricht der Umgebung, die für den Connector auf der Plattform ausgewählt wurde.
• In Zeile 37 (Abbildung 3) ändert der Connector das Basisereignis-Dictionary, indem er einen neuen Schlüssel, product_name, mit dem Wert „Netskope“ hinzufügt. Das ist erforderlich, da die Rohdaten kein einheitliches Produktfeld enthalten, das für die Zuordnung und Modellierung in der Ontologie der Plattform verwendet werden kann.

  

  Abbildung 3: Basisereignis ändern

Beispiel für ein Skript zum Ausführen des Connectors

Die Funktion main enthält die Kernausführungslogik für den Connector:

• Der Decorator output_handler wird für die Fehlerbehebung verwendet und wird in diesem Dokument nicht behandelt.
• Die Funktion main enthält den optionalen Parameter is_test_run, der standardmäßig auf False festgelegt ist. Wie der Name schon sagt, bestimmt dieser Parameter, ob der Connector Benachrichtigungen in der Produktion aufnehmen oder im Testmodus auf dem Tab Connector Testing (Connector-Tests) in der Anwendung ausgeführt werden soll.

Sehen Sie sich die Aufschlüsselung der wichtigsten Ausführungslogik pro Skriptzeile an:

Abbildung 3: Basisereignis ändern

• In den Zeilen 56 und 57 werden zwei leere Listen initialisiert, die während der Ausführung verwendet werden.
• In Zeile 58 instanziiert die Klasse SiemplifyConnectorExecution das Objekt siemplify. Dieses Objekt verwaltet den Großteil des Laufzeitverhaltens des Connectors.
• In Zeile 61 wird eine Instanz von Connector Allowlist erstellt. Obwohl sie in diesem Connector nicht verwendet wird, wird sie häufig in anderen Connectors verwendet und in diesem Leitfaden nicht behandelt.
• In den Zeilen 67–69 werden Variablen für Connector-Parameter wie Authentifizierungsdaten oder Konfigurationseinstellungen definiert.
• In Zeile 71 wird das NetskopeManager-Objekt instanziiert und die relevanten Parameter werden übergeben, um eine erfolgreiche Authentifizierung zu ermöglichen. Die interne Manager-Logik, die die Authentifizierung verarbeitet, wird in diesem Beispiel nicht gezeigt.
• In Zeile 73 wird ein Zeitstempel aus einer lokalen Datei abgerufen, die bei früheren Connector-Ausführungen erstellt wurde. Dieser Zeitstempel wird verwendet, um zu vermeiden, dass dieselben Benachrichtigungen noch einmal verarbeitet werden.
• In den Zeilen 74 und 75 wird der Fall behandelt, in dem der Connector zum ersten Mal ausgeführt wird und der Zeitstempel noch nicht festgelegt ist (z. B. wenn er standardmäßig auf „0“ gesetzt ist). Da Netskope die Unix-Epochenzeit erfordert und „0“ nicht als gültige Startzeit akzeptiert, wird die Funktion „unix_now“ verwendet, um die aktuelle Zeit in Millisekunden abzurufen. Dieser Wert wird durch „1.000“ geteilt,um ihn in Unix-Epochensekunden umzuwandeln. Die resultierenden Start- und Endzeiten werden dann an die Methode `get_alerts` im Manager übergeben. Während für viele APIs nur eine Startzeit akzeptiert wird, sind für die Netskope API sowohl Start- als auch Endzeit für zeitbasierte Benachrichtigungsabfragen erforderlich.
Hinweis:Die Verarbeitung von Zeit und Zeitstempeln ist einer der komplexesten Aspekte beim Erstellen eines Connectors. Verschiedene Drittanbietersysteme geben Zeitstempel in unterschiedlichen Formaten zurück. Bei einigen ist es möglicherweise nicht möglich, Abfragen basierend auf dem Format durchzuführen, in dem sie zurückgegeben werden. Es sind eingehende Kenntnisse der API des Quellsystems erforderlich.
• In Zeile 77 wird eine Liste von Benachrichtigungen von Netskope abgerufen. Wenn der Connector im Testmodus ausgeführt wird, wird nur die letzte Benachrichtigung in der Liste ausgewählt (Zeilen 79–80).

Logik für Überlauf

Der Connector durchläuft dann die abgerufenen Benachrichtigungen und erstellt aus jeder Benachrichtigung eine Benachrichtigung mithilfe der zuvor definierten Funktion build_alert_info. Jede Benachrichtigung wird an die zuvor initialisierte Liste all_alerts angehängt. Im nächsten Teil der Connector-Logik wird der Überlauf behandelt.
Der Überlauf ist ein Schwellenwertmechanismus, der verhindert, dass innerhalb kurzer Zeit zu viele Benachrichtigungen aufgenommen werden, insbesondere wenn Benachrichtigungen dieselbe Umgebung, dasselbe Produkt und denselben Regelgenerator haben. Die Implementierung einer Overflow-Logik ist zwar nicht zwingend erforderlich, wird aber als Best Practice empfohlen, um Leistungseinbußen zu vermeiden.

In Abbildung 4 sehen Sie die Aufschlüsselung der Overflow-Logik nach Scriptzeile:

• In den Zeilen 104–105 wird ein alert, der nicht als Überlauf klassifiziert ist, an die Liste der zu erfassenden Benachrichtigungen angehängt.



Abbildung 4: Überlaufmechanismus.

Connector-Ausführung beenden

Wenn der Connector nicht im Testmodus ausgeführt wird, muss der Zeitstempel aktualisiert werden, um die letzte abgerufene Benachrichtigung widerzuspiegeln. So wird verhindert, dass dieselben Benachrichtigungen im nächsten Ausführungszyklus noch einmal aufgenommen werden. Die all_alerts-Liste ist nach Zeitstempel sortiert, sodass auch überlaufene Benachrichtigungen zur Bestimmung des letzten Zeitstempels beitragen.

In Abbildung 5 sehen Sie die Aufschlüsselung der Connector-Ausführungslogik nach Skriptzeile:

• In Zeile 126 wird die Liste der nicht übergelaufenen Benachrichtigungen an die Anwendung übergeben, wo die Benachrichtigungen dann erstellt und in der GUI angezeigt werden.
• In den Zeilen 128–131 wird ermittelt, ob der Connector im Testmodus ausgeführt wird. Dazu werden Systemargumente verwendet, die von der Anwendung übergeben werden, z. B. wenn Sie auf dem Tab Testen auf Connector einmal ausführen klicken.
  

  

  Abbildung 5: Beenden der Connector-Ausführung

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