Benutzerdefinierte Integration erstellen

Unterstützt in:

Google SecOps SOAR

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

Hinweis: Einen Leitfaden für ein standardisiertes Entwicklungsframework, Richtlinien zur Qualitätssicherung und Best Practices für das Erstellen und Einreichen 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 diese Vorgehensweise sind Kenntnisse in Python und objektorientierter Programmierung erforderlich.

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 settings Einstellungen Option aufgeführt, was darauf hinweist, dass es sich um eine benutzerdefinierte Integration handelt.

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

Hinweis: Skriptabhä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 Bibliothek „requests“ verwenden möchten, laden Sie sie aus 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 standardmäßiges CPython, das für die manylinux_2_17_x86_64 Architektur erstellt wurde. Wenn Sie eine .WHL Datei auswählen, prüfen Sie, ob sie mit diesem Tag kompatibel ist.
Wenn eine Bibliothek nicht in der virtuellen Umgebung installiert ist, greift die Integration auf die systemseitig installierte Version zurück.

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 (z. B. anyio, certifi, httpx, idna oder sniffio). Wenn verschachtelte Abhängigkeiten nicht aufgelöst werden, tritt ein generischer errorCode: 2000 Fehler auf. Eine vollständige Liste der erforderlichen Plattformbibliotheken finden Sie im Community-Leitfaden zum Abrufen von TIPCommon.

Wenn für ein Abhängigkeitspaket keine vorkompilierte Wheel (.WHL) Datei 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 das Definieren 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 Arten von Abhängigkeiten mit uv finden Sie in der uv Dokumentation unter Abhängigkeiten verwalten.

Empfohlener Workflow: Erweiterte Abhängigkeitsverwaltung mit der mp-CLI

Für Integrationen, die komplexe oder mehrschichtige externe Bibliotheken wie TIPCommon erfordern, empfiehlt Google, manuelle IDE-Uploads zu umgehen und sie lokal mit dem Tool Marketplace CLI (mp) zu entwickeln. Dieses Tool verfolgt und verpackt verschachtelte Abhängigkeiten automatisch mit dem uv Paketmanager.

Vorbereitung

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

Ersteinrichtung

1. Forken und klonen Sie das offizielle Content Hub-Repository in Ihre lokale Umgebung.
2. Installieren Sie das Tool mp 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 Legacy-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 mit dem CLI-Tool sind die Legacy-SOAR-Instanz-URL und das API Schlüsselformat erforderlich.
4. Konfigurieren Sie den Pfad zum 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 zu einer Integration hinzufügen

Wenn Sie eine in der IDE erstellte Integration haben, die TIPCommon oder andere mehrschichtige Bibliotheken benötigt, verwenden Sie den folgenden lokalen Workflow, um die Abhängigkeiten sicher zu verwalten:

1. Rufen Sie das Verzeichnis für die benutzerdefinierte Integration in Ihrem geklonten Repository auf:

   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 die erforderliche TIPCommon Wheel-Datei einzufügen. Dadurch werden die verschachtelten Unterabhängigkeits- Wheels automatisch verfolgt und in die Paketkonfiguration Ihrer lokalen Umgebung heruntergeladen:

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

5. Übertragen Sie die vollständig kompilierte Integration zusammen mit dem neu verfolgten Abhängigkeits baum wieder in Ihre Google SecOps-Instanz:

   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 die Schaltfläche Testen/Ausführen , um die Ausführung zu debuggen. Wenn das Skript ohne Fehler kompiliert wird und keine ModuleNotFoundError ausgelöst wird, werden Ihre verschachtelten Abhängigkeiten korrekt aufgelöst.

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 einen Namen für den Manager ein.
   
3. Bearbeiten und führen Sie das folgende Skript 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) The response to validate
       :param error_msg: (str) The error message to display
       """
       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, einen zu erstellen, wenn Sie kleine Aktionen zum 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, mit dem Sie eine Verbindung herstellen.
• API-Secret: Ein vertraulicher Schlüssel, der zur Authentifizierung Ihrer Anwendung beim Dienst verwendet wird.
• Kontrollkästchen SSL prüfen: Wenn diese Option aktiviert ist, wird geprüft, ob das SSL-Zertifikat für die Verbindung zum Armis-Server gültig ist.
• Kontrollkästchen Remote ausführen: Eine Einstellung, mit der festgelegt wird, 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 > Testen.

Hinweis:Klicken Sie nach dem Aktualisieren der Anmeldedaten immer auf Speichern. Für alle Drittanbieterintegrationen muss eine Ping -Aktion implementiert werden. Mit der Schaltfläche Testen wird diese Aktion ausgeführt, um die Verbindung zu prüfen.

Wenn die Ping -Aktion fehlt, schlägt die Schaltfläche Testen fehl und es wird ein rotes X angezeigt.

Ping-Aktion implementieren

Die Logik der Ping -Aktion entspricht einer erfolgreichen 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 auth-Methode von ArmisManager, um die Authentifizierung zu prüfen.

Integration aktivieren

So aktivieren Sie die Integration:

1. Klicken Sie unter Antwort > IDE auf den Schalter Aktivieren/Deaktivieren, um ihn auf EIN zu stellen.
2. Klicken Sie auf Speichern. Ein grüner Schalter bestätigt den Erfolg. Die Anmeldedaten aus dem Content Hub werden an ArmisManager übergeben. Wenn auth ohne Fehler abgeschlossen wird, wird auf der Schaltfläche 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 mit extract_action_param Parameter innerhalb der Aktion selbst definieren. Für die Ping -Aktion 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 Ersteinrichtung kein Image erstellt haben, wird das Standard-Image für benutzerdefinierte Integrationen zugewiesen. Beachten Sie, dass Content Hub-Updates keine benutzerdefinierten Integrationen überschreiben oder löschen.

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 Manager ist nicht automatisch enthalten.
• So exportieren Sie Integrationen:
• Klicken Sie auf Exportieren , um das Paket herunterzuladen.

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