Benutzerdefinierte Integrationen erstellen

Unterstützt in:

Google SecOps SOAR

In diesem Dokument wird beschrieben, wie Sie benutzerdefinierte Integrationen in der integrierten Entwicklungsumgebung (Integrated Development Environment, IDE) mit derselben Struktur wie kommerzielle Integrationen erstellen. Im Content Hub finden Sie benutzerdefinierte Integrationen für verschiedene Umgebungen, die Sie dort auch konfigurieren können. Anschließend können Sie sie in Playbooks, manuellen Aktionen und Remote-Agents verwenden. Import- und Exportfunktionen werden wie bei anderen IDE-Elementen unterstützt.

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

Benutzerdefinierte Integration in der IDE erstellen

Sie können eine benutzerdefinierte Integration für das Armis-Produkt erstellen und einen Manager zusammen mit einer Ping-Aktion erstellen. Für dieses Verfahren werden Kenntnisse von Python und der objektorientierten Programmierung vorausgesetzt.

Anwendungsfall: Benutzerdefinierte Armis-Integration erstellen

So erstellen Sie die benutzerdefinierte Integration in der IDE:

1. Klicken Sie im Hauptmenü auf 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. Das bedeutet, 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, die Python-Abhängigkeiten und die Integrationsparameter definieren.

Hinweis:Script-Abhä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 beispielsweise eine andere Version der „requests“-Bibliothek verwenden möchten, laden Sie sie von einer vertrauenswürdigen Quelle wie PyPI oder GitHub herunter und fügen Sie sie als Skriptabhängigkeit hinzu.
Für Abhängigkeiten, die ein vorkompiliertes binäres Wheel erfordern (z. B. Pakete mit C-Erweiterungen), verwendet die SOAR-Plattform Standard-CPython, das für die manylinux_2_17_x86_64-Architektur erstellt wurde. Achten Sie beim Auswählen einer .WHL-Datei darauf, dass sie mit diesem Tag kompatibel ist.
Wenn eine Bibliothek nicht in der virtuellen Umgebung installiert ist, wird auf die systemseitig installierte Version zurückgegriffen.

Wenn Sie eine benutzerdefinierte oder proprietäre .WHL-Datei (z. B. TIPCommon) verwenden, für die untergeordnete Unterabhängigkeiten erforderlich sind, müssen Sie vor dem Speichern die einzelnen Wheel-Dateien für den gesamten Abhängigkeitsbaum manuell hochladen (z. B. anyio, certifi, httpx, idna oder sniffio). Wenn verschachtelte Abhängigkeiten nicht aufgelöst werden, führt dies zu einem allgemeinen errorCode: 2000-Fehler. Eine vollständige Liste der erforderlichen Plattformbibliotheken finden Sie im Community Guide on Retrieving TIPCommon.

Wenn für ein Abhängigkeitspaket keine vorkompilierte Wheel-Datei (.WHL) für die manylinux_2_17_x86_64-Architektur verfügbar ist oder Sie eine bestimmte Quellcodeversion benötigen, können Sie eine direkte URL zum Quellcode angeben (z. B. eine .tar.gz-Datei). Der Abhängigkeitsresolver der Plattform, uv, unterstützt die Definition dieser Quell-URLs in der Tabelle [tool.uv.sources] in Ihrer pyproject.toml-Datei. Beispiel:

[project]
# ... other project fields ...

[tool.uv.sources]
compressed-rtf = { url = "https://files.pythonhosted.org/packages/.../compressed_rtf-1.0.6.tar.gz" }
dkimpy = { url = "https://files.pythonhosted.org/packages/.../dkimpy-1.1.8.tar.gz" }

Weitere Informationen zum Definieren verschiedener Abhängigkeitstypen mit uv finden Sie in der uv-Dokumentation unter Abhängigkeiten verwalten.

Empfohlener Workflow: Erweiterte Abhängigkeitsverwaltung mit der mp CLI

Bei Integrationen, für die komplexe oder mehrschichtige externe Bibliotheken wie TIPCommon erforderlich sind, empfiehlt Google, manuelle IDE-Uploads vollständig zu umgehen und die Integrationen lokal mit dem Tool Marketplace CLI (mp) zu entwickeln. Mit diesem Tool werden verschachtelte Abhängigkeiten automatisch mit dem Paketmanager uv verfolgt und verpackt.

Vorbereitung

• Python 3.11 oder höher ist auf Ihrer lokalen Entwicklungsmaschine installiert.
• Der uv-Python-Paketmanager ist installiert (siehe Installationsanleitung für uv).

Ersteinrichtung

1. Verzweigen und klonen Sie das offizielle Content Hub-Repository in Ihre lokale Umgebung.
2. Installieren Sie das mp-Tool mit uv:

   uv tool install mp --from git+https://github.com/chronicle/content-hub.git#subdirectory=packages/mp

3. Melden Sie sich mit der Stamm-URL Ihrer Instanz und Ihrem alten API-Schlüssel in Ihrer Google SecOps-Umgebung an:

   mp login --api-root https://{YOUR_INSTANCE}.siemplify-soar.com --api-key {YOUR_LEGACY_API_KEY}

   Hinweis:Für die Authentifizierung benötigt das CLI-Tool die URL Ihrer alten SOAR-Instanz und das API-Schlüsselformat.
4. Konfigurieren Sie den Pfad zu Ihrem lokalen Stamm-Repository:

   mp config --root-path /path/to/cloned/content-hub

5. Erstellen Sie ein benutzerdefiniertes Unterverzeichnis für Ihre proprietären Integrationen im Repository-Layout unter: content-hub/content/response_integrations/custom/

TIPCommon- oder komplexe Abhängigkeiten in eine Integration einfügen

Wenn Sie eine in der IDE erstellte Integration haben, für die TIPCommon oder andere mehrschichtige Bibliotheken erforderlich sind, verwenden Sie den folgenden lokalen Workflow, um die Abhängigkeiten sicher zu verwalten:

1. Wechseln Sie in Ihrem geklonten Repository zum Verzeichnis Ihrer benutzerdefinierten Integration:

   cd content-hub/content/response_integrations/custom/

2. Rufen Sie die vorhandene Integrationsstruktur aus Ihrer Google SecOps-Instanz ab:

   mp pull --type integration --name "{INTEGRATION_NAME}"

3. Wechseln Sie in den neu abgerufenen Integrationsordner:

   cd {INTEGRATION_NAME}

4. Verwenden Sie uv, um das erforderliche TIPCommon-Wheel-Datei-Paket einzufügen. Dadurch werden die verschachtelten Unterabhängigkeits-Wheels automatisch in der Paketkonfiguration Ihrer lokalen Umgebung verfolgt und heruntergeladen:

   uv pip install /path/to/wheels/TIPCommon-your-version-py3-none-any.whl

5. Laden Sie die vollständig kompilierte Integration zusammen mit dem neu erstellten Abhängigkeitsbaum in Ihre Google SecOps-Instanz hoch:

   mp push --type integration --name "{INTEGRATION_NAME}"

Installation überprüfen

So prüfen Sie, ob Ihre Abhängigkeiten erfolgreich verpackt wurden, ohne dass eine errorCode: 2000-Schleife aufgetreten ist:

• Öffnen Sie Ihre benutzerdefinierte Integration in der IDE.
• Fügen Sie eine Testzeile hinzu, um ein Modul aus dem Paket zu importieren, z. B. from TIPCommon.extraction import extract_action_param.
• Klicken Sie auf den Button Testen/Wiedergeben, um die Ausführung zu debuggen. Wenn das Script ohne ModuleNotFoundError kompiliert wird, werden die verschachtelten Abhängigkeiten korrekt aufgelöst.

Benutzerdefinierten Manager erstellen

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

So erstellen Sie einen benutzerdefinierten Manager:

1. Klicken Sie in der IDE auf Create New Item (Neues Element erstellen) und wählen Sie Manager (Verwaltung) aus.
2. Wählen Sie die Armis-Integration aus und geben Sie den Namen eines Managers ein.
   
3. Bearbeiten Sie das folgende Skript 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. Antwort) 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 zum Parsen und Transformieren von Daten gruppieren.

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

Parameter, die in den Integrationseinstellungen definiert sind, werden in der Konfiguration des Google SecOps Content Hub angezeigt. Zu den Parametern gehören:

• API-Stammverzeichnis: 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 überprüft, ob das SSL-Zertifikat für die Verbindung zum Armis-Server gültig ist.
• Kästchen Remote ausführen: Eine Einstellung, die bestimmt, ob der Code oder die Aufgabe auf einem Remote-Server anstelle von 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 > Test.

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

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

Ping-Aktion implementieren

Die Logik der Aktion Ping entspricht einer erfolgreichen Authentifizierung.

So implementieren Sie die Aktion Ping:

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 überprü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 Testen 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. Hinweis: Durch Content Hub-Aktualisierungen werden keine benutzerdefinierten Integrationen überschrieben oder gelöscht.

Exportieren und Importieren 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 Managers ist nicht automatisch enthalten.
• 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