Benutzerdefinierte Integrationen erstellen

Unterstützt in:

Google SecOps SOAR

In diesem Dokument werden die Workflows zum Erstellen benutzerdefinierter Integrationen für Google SecOps beschrieben. Die aktuelle Best Practice besteht darin, Integrationen lokal mit Ihrer bevorzugten IDE zu entwickeln und sie über GitHub mit modernen GitOps-Workflows zu verwalten. Für Legacy-Umgebungen oder schnelle Prototypen können Sie Integrationen auch direkt in der integrierten SOAR-IDE erstellen.

Hinweis: Ein standardisiertes Entwicklungs-Framework, Richtlinien zur Qualitätssicherung und Best Practices für das Erstellen und Einreichen benutzerdefinierter Integrationen finden Sie im Leitfaden für benutzerdefinierte Integrationen.

Lokale IDE und GitHub-Workflow (empfohlen)

Der empfohlene Workflow ist, Integrationen lokal zu entwickeln und über GitHub zu verwalten. Dieser Ansatz entspricht modernen GitOps-Verfahren und ermöglicht eine bessere Versionsverwaltung, Zusammenarbeit und automatisierte Abhängigkeitsverwaltung.

Detaillierte technische Schritte, Installationsanleitungen und moderne Befehle mit dem Marketplace CLI-Tool und dem uv-Paketmanager finden Sie im offiziellen Chronicle Content Hub GitHub-Repository.

Konzeptionelle Workflowübersicht

Wenn Sie benutzerdefinierte Integrationen lokal entwickeln möchten, sollten Sie diesen GitOps-Lebenszyklus befolgen. Die genaue, aktuelle Syntax dieser Befehle finden Sie in der offiziellen MP CLI-Dokumentation auf GitHub.

1. Verzweigen und klonen: Klonen Sie das offizielle content-hub-Repository auf Ihren lokalen Entwicklungscomputer.
2. Tools installieren: Installieren Sie das mp-Befehlszeilentool und den uv-Python-Paketmanager.
3. Authentifizieren: Melden Sie sich über die MP-Befehlszeile mit Ihrer Instanz-URL und Ihren API-Schlüsseln in Ihrer Google SecOps-Umgebung an.
4. Lokal entwickeln: Verwenden Sie Ihre bevorzugte IDE (z. B. VS Code oder PyCharm), um Ihren Integrationscode zu schreiben. Nutzen Sie dabei lokale Debugging- und Testtools.
5. Abhängigkeiten verwalten: Verwenden Sie uv, um Abhängigkeiten (wie TIPCommon) in Ihrer lokalen pyproject.toml-Datei zu deklarieren und zu verwalten.
6. Synchronisieren: Verwenden Sie die Befehle mp pull und mp push, um Ihren lokalen Code mit Ihrer Google SecOps-Instanz zu synchronisieren, um ihn zu testen und bereitzustellen.

Alternative: Benutzerdefinierte Integration in der integrierten IDE erstellen

Wenn Sie Legacy-Integrationen verwalten, ein Skript schnell testen oder in einer Umgebung arbeiten, in der die lokale Entwicklung eingeschränkt ist, können Sie die integrierte IDE verwenden.

Anwendungsfall: Benutzerdefinierte Armis-Integration erstellen

So erstellen Sie die benutzerdefinierte Integration in der IDE:

1. Gehen Sie im Hauptmenü zu Antwort > IDE.
2. Klicken Sie auf Neues Element erstellen und wählen Sie Integration aus.
3. Geben Sie einen Namen ein und klicken Sie auf Erstellen.

Die Integration wird jetzt mit der Option Einstellungen Einstellungen aufgeführt, was darauf hinweist, dass es sich um eine benutzerdefinierte Integration handelt.

Klicken Sie auf Einstellungen Einstellungen, um die Integrationseinstellungen aufzurufen. Dort können Sie das Symbol, die Beschreibung, Python-Abhängigkeiten und Integrationsparameter definieren.

Hinweis: Scriptabhängigkeiten sind Python-Bibliotheken, die für Ihre benutzerdefinierte Integration erforderlich sind. Abhängigkeiten können als .WHL-, .TAR-, .GZ- oder .PY-Dateien hochgeladen werden. Jede Integration wird in einer eigenen virtuellen Umgebung ausgeführt. So können Sie bestimmte Bibliotheksversionen verwenden, unabhängig davon, was auf dem zugrunde liegenden System installiert ist.

Wenn Sie eine benutzerdefinierte oder proprietäre .WHL-Datei (z. B. TIPCommon) verwenden, die verschachtelte Unterabhängigkeiten erfordert, müssen Sie vor dem Speichern einzelne Wheel-Dateien für den gesamten Abhängigkeitsbaum manuell hochladen. Wenn verschachtelte Abhängigkeiten nicht aufgelöst werden, führt dies zu einem allgemeinen errorCode: 2000-Fehler. Für ein erweitertes Abhängigkeitstracking können Sie den Workflow für lokale IDE und GitHub verwenden.

Benutzerdefinierten Manager erstellen

Manager sind Wrapper für APIs von Drittanbietertools. Sie sind zwar nicht obligatorisch, werden aber für Integrationen empfohlen, die mit externen Tools interagieren. Manager sollten nicht aus dem SDK importieren. Nach der Erstellung können Sie sie in Connectors, Aktionen und Jobs importieren.

So erstellen Sie einen benutzerdefinierten Manager:

1. Klicken Sie in der IDE auf Neues Element erstellen und wählen Sie Manager aus.
2. Wählen Sie die Armis-Integration aus und geben Sie den Namen eines Managers ein.
   
3. Bearbeiten Sie das folgende Script und führen Sie es aus:

import requests


class ArmisManager:
   def init(self, api_root, api_token):
       self.api_root = api_root
       self.api_token = api_token
       self.session = requests.session()
       self.session.headers = {"Accept": "application/json"}


   def auth(self):
       endpoint = "{}/api/vi/access_token/*"
       params = {"secret_key" : self.api_token}
       response = self.session.post(endpoint.format(self.api_root), params=params)
       self.validate_response(response)
       access_token = response.json()["data"]["access_token"]
       self.session.headers.update({"Authorization": access_token})
       return True


   def get_device_by_ip(self, device_ip):
       endpoint = "{}/api/vi/devices/"
       params = {"ip": device_ip}
       response = self.session.get(endpoint.format(self.api_root), params=params)
       self.validate_response(response)
       return response.json()["data"]["data"]


   @staticmethod
   def validate_response(res, error_msg="An error occurred"):
       """Validate a response


       :param res: (requests. Response) Die zu validierende Antwort
       :param error_msg: (str) Die anzuzeigende Fehlermeldung
       """
       try:
           res.raise_for_status()
       except requests.HTTPError as error:
           raise Exception("(error_msg): (error) (text)".format(
               error_msg=error_msg,
               error=error,
               text=error.response.content
           ))

Hinweis: Für grundlegende Aktionen ist kein Manager erforderlich. Wir empfehlen jedoch, eine zu erstellen, wenn Sie kleine Aktionen für das Parsen und Transformieren von Daten gruppieren.

Parameter, Google SecOps Content Hub-Konfiguration und die Ping-Aktion

In den Integrationseinstellungen definierte Parameter werden in der Google SecOps Content Hub-Konfiguration angezeigt. Zu den Parametern gehören:

• API-Stamm: Die Basis-URL für den Dienst, zu dem Sie eine Verbindung herstellen.
• API-Secret: Ein vertraulicher Schlüssel, der zur Authentifizierung Ihrer Anwendung beim Dienst verwendet wird.
• Kästchen SSL überprüfen: Wenn diese Option aktiviert ist, wird geprüft, ob das SSL-Zertifikat für die Verbindung zum Armis-Server gültig ist.
• Kästchen Remote ausführen: Eine Einstellung, die festlegt, ob der Code oder die Aufgabe auf einem Remote-Server statt lokal ausgeführt wird. Wenn diese Option aktiviert ist, sendet das System die erforderlichen Anweisungen und Daten zur Verarbeitung an einen dedizierten Server.

So aktualisieren Sie die Parameter:

1. Geben Sie die richtigen Anmeldedaten ein.
2. Klicken Sie auf Speichern > Testen.

Hinweis: Klicken Sie nach dem Aktualisieren der Anmeldedaten immer auf Speichern. Alle Integrationen von Drittanbietern müssen eine Ping-Aktion implementieren. Mit dem Button Testen wird diese Aktion ausgeführt, um die Verbindung zu prüfen.

Wenn die Aktion Ping fehlt, schlägt der Test fehl und es wird ein rotes X angezeigt.

Ping-Aktion implementieren

Die Logik der Ping-Aktion verhält sich wie eine erfolgreiche Authentifizierung.

So implementieren Sie eine Ping-Aktion:

1. Erstellen Sie in der IDE eine neue Aktion in der Armis-Integration mit dem Namen Ping.
2. Verwenden Sie die Methode ArmisManager auth, um die Authentifizierung zu prüfen.

Integration aktivieren

So aktivieren Sie die Integration:

1. Klicken Sie unter Antwort > IDE auf den Ein/Aus-Button Aktivieren/Deaktivieren, um die Position EIN festzulegen.
2. Klicken Sie auf Speichern. Ein grüner Schalter bestätigt den Erfolg. Anmeldedaten aus dem Content Hub werden an ArmisManager übergeben. Wenn auth ohne Fehler abgeschlossen wird, wird auf dem Button Test ein grünes Häkchen angezeigt.

Verwenden Sie die Methode extract_configuration_param, um Parameter aus der Integrationskonfiguration zu importieren. Alternativ können Sie extract_action_param verwenden, um Parameter innerhalb der Aktion selbst zu definieren. Für die Aktion Ping sollten jedoch immer Konfigurationsparameter verwendet werden, da diese vom Content Hub getestet werden.

Benutzerdefinierte Integrationen ansehen

Rufen Sie den Content Hub auf und suchen Sie nach der benutzerdefinierten Integration, die Sie erstellt haben. Wenn Sie bei der Erstkonfiguration kein Image erstellt haben, wird ihm das benutzerdefinierte Standard-Image zugewiesen. Beachten Sie, dass Content Hub-Updates keine benutzerdefinierten Integrationen überschreiben oder löschen.

Export und Import in der IDE

Führen Sie eine der folgenden Aktionen aus:

• So importieren Sie Integrationen:
1. Laden Sie eine ZIP-Datei mit der richtigen Ordnerstruktur hoch. Die Integration wird in der IDE und im Content Hub angezeigt.
2. Klicken Sie auf Importieren. Die Integration wird sowohl in der IDE als auch im Content Hub angezeigt.
3. Das System generiert eine ZIP-Datei mit der Definition, den Skripts und der Konfiguration. Der Ordner Manager wird nicht automatisch einbezogen.
• So exportieren Sie Integrationen:
• Klicken Sie auf Exportieren, um das Paket herunterzuladen.

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