Benutzerdefinierten Connector erstellen

Unterstützt in:

Google SecOps SOAR

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

In diesem Dokument erfahren Sie, wie mit dem SOAR SDK benutzerdefinierte Integrationen für Drittanbietertools erstellt werden, 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 erfasst Basisereignisdaten, 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

Verwaltungskonto 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 vorgefertigten 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 generische Vorlage mit Codekommentaren, in denen die grundlegende Struktur und die Anforderungen eines Connector-Skripts beschrieben werden.

Die Connector-Logik kann variieren, der Prozess umfasst jedoch in der Regel die folgenden Kernschritte:

1. Verwenden Sie die API des Drittanbietertools, um Benachrichtigungen, Erkennungen oder Ereignisse abzurufen. Im Fall von Netskope wird dies durch die Methode get_alerts() gehandhabt. Damit Benachrichtigungen nicht dupliziert werden, senden Sie eine Abfrage nach Zeitstempel und aktualisieren Sie sie nach jedem Lauf.
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, um Probleme mit verschachtelten Listen und Wörterbüchern 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 für die Verwendung in der nächsten Abfrage.

Hinweis:Eine Benachrichtigung kann mehrere Ereignisse enthalten. SIEM-Plattformen korrelieren beispielsweise mehrere Ereignisse zu einem einzelnen Alarm (z. B. Trellix ESM) oder Verstoß (z. B. QRadar). Im Gegensatz dazu wird mit 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 main()-Funktion des Connectors instanziiert. Das Script endet, wenn dieses Objekt mit der Methode return_package() eine Liste von Benachrichtigungen 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 Kernfunktionen, einschließlich der Zeitverarbeitung, unerlässlich sind.

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

Hinweis:Bei älteren Connectors kann CaseInfo aus SiemplifyConnectors verwendet werden. Dies ist dieselbe Klasse wie AlertInfo und entspricht einer verworfenen 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 Properties, die definiert werden müssen, damit die Anwendung die Benachrichtigung richtig verarbeiten kann. Die Funktion build_alert_info empfängt eine Netskope-Benachrichtigung (im Roh-JSON-Format, von der API empfangen) und das Siemplify-Objekt als Eingaben. Anschließend wird die Netskope-Benachrichtigung geparst und den Feldern `alert_info` werden die entsprechenden Werte zugewiesen.

In dieser 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 Property 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 Logik einfügen, um jedes Ereignis angemessen zu verarbeiten. In diesem Beispiel enthält jede Benachrichtigung nur ein Ereignis. Die Standardimplementierung ist also ausreichend.

Mit der Methode dict_to_flat wird die Roh-JSON-Struktur vereinfacht. So lassen sich Probleme mit verschachtelten Listen und Dictionaries vermeiden. Geglättete Schlüssel/Wert-Paare sind leicht modifizierte Versionen der Originale.

Sehen Sie sich die folgende Logik in Abbildung 2 an:

• display_id wird ein zufällig generierter Wert aus der uuid-Bibliothek 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 sie display_id entspricht. Beide Felder müssen pro Benachrichtigung im System eindeutig sein. Diese Eindeutigkeit wird durch das Generieren einer zufälligen UUID gewährleistet.
• name ist der Name der Benachrichtigung und wird in der Benutzeroberfläche angezeigt.
• rule_generator bezieht sich auf die Regel, die die Benachrichtigung im Quellsystem generiert hat. Dieses Feld ist in den Rohdaten möglicherweise nicht immer vorhanden. Wenn er fehlt, können Sie einen beliebigen String-Wert zuweisen. Er darf jedoch nicht leer gelassen werden.
• start_time und end_time stehen für die Zeitstempel der Benachrichtigung. In diesem Beispiel enthält die Netskope-Benachrichtigung 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 basierend auf der Priorität der zugehörigen Benachrichtigung eine Priorität zu. In der Google SecOps API werden numerische Werte mithilfe des folgenden Schemas den visuellen Labels zugeordnet, wobei der ganzzahlige Wert im Connector übergeben wird: {"Informative": -1, "Low": 40, "Medium": 60, "High": 80, "Critical": 100}, wobei der ganzzahlige Wert 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 nicht einheitlich 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 wichtig, 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) wird das Basisereignis-Dictionary durch den Connector geändert, indem ein neuer Schlüssel, product_name, mit dem Wert „Netskope“ hinzugefügt wird. 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 bearbeiten

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

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

• Der output_handler-Decorator wird zu Debugging-Zwecken verwendet und ist nicht Gegenstand dieses Dokuments.
• 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 nach Skriptzeile an:

Abbildung 3: Basisereignis bearbeiten

• 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 steuert den größten Teil des Laufzeitverhaltens des Connectors.
• In Zeile 61 wird eine Instanz von Connector Allowlist erstellt. Sie wird zwar nicht in diesem Connector verwendet, aber häufig in anderen Connectors. Sie wird in dieser Anleitung nicht behandelt.
• In den Zeilen 67–69 werden Variablen für Connector-Parameter wie Anmeldedaten für die Authentifizierung 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 für die Authentifizierung wird in diesem Beispiel nicht gezeigt.
• In Zeile 73 wird ein Zeitstempel aus einer lokalen Datei abgerufen, die bei vorherigen 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 Sekunden seit der Unix-Epoche zu konvertieren. 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 auszufü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 Warnung in der Liste ausgewählt (Zeilen 79–80).

Überlauflogik

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 overflow verarbeitet.
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:

• Wenn in den Zeilen 104–105 eine alert nicht als Überlauf klassifiziert wird, wird sie 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 den letzten abgerufenen Hinweis widerzuspiegeln. So wird verhindert, dass dieselben Benachrichtigungen während des nächsten Ausführungszyklus noch einmal aufgenommen werden. Die Liste all_alerts 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 überlaufenen Benachrichtigungen an die Anwendung gesendet, wo die Benachrichtigungen dann erstellt und in der Benutzeroberfläche angezeigt werden.
• In den Zeilen 128–131 wird ermittelt, ob der Connector im Testmodus ausgeführt wird. Systemargumente, die von der Anwendung übergeben werden, z. B. wenn auf dem Tab Testen auf Connector einmal ausführen geklickt wird, werden verwendet, um diese Entscheidung zu treffen.
  

  

  Abbildung 5: Beenden der Connector-Ausführung

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