GitSync

Unterstützt in:

GitSync ist eine robuste Integration, die vom Google Security Operations SOAR Professional Services-Team entwickelt wurde und zum Synchronisieren von Google Security Operations SOAR-Komponenten mit einem Git-Repository dient. Es verwendet die internen Vorgänge von Git, um direkt in das Repository zu schreiben, wodurch es im Wesentlichen als Dateispeicherdienst fungiert. Sie bietet Methoden für die folgenden Aufgaben:

  • Assets zwischen Google Security Operations SOAR-Instanzen migrieren

  • Google Security Operations SOAR-Assets sichern

  • Automatische Dokumentation

  • Erstellt einen „Speicher“ zum Teilen von Assets/Wissen

  • Versionsverwaltung

Die Integration besteht aus mehreren Google Security Operations SOAR-Jobs – Push- und Pull-Jobs für jedes unterstützte Asset sowie Push-/Pull-Jobs für die gesamte Google Security Operations SOAR-Instanz. Diese Jobs müssen nicht regelmäßig ausgeführt werden, da sie für die manuelle Ausführung über die IDE konzipiert wurden. Sie können jedoch als reguläre Jobs verwendet werden, z. B. zum Hochladen eines täglichen Commits. 

GitSync verwendet die Google Security Operations SOAR API, um das relevante Asset abzurufen, z. B. eine Integration oder eine visuelle Familie, und alle verfügbaren Informationen aus diesem Asset zu parsen. Diese Informationen werden später in einer README.md-Datei gerendert, die normalerweise beim Durchsuchen des Repositorys angezeigt wird. Anschließend werden die JSON-Definition des Assets und die gerenderte README-Datei in das lokale Repository geschrieben und per Push in das Remote-Repository übertragen.

Eine weitere Verwendung von GitSync ist der Wissensaustausch. Mit dieser Integration kann ein Git-Repository als „Speicher“ für Assets wie Playbooks oder Ontologieeinstellungen dienen, die zuvor entwickelt wurden. Dabei werden die Best Practices von Google Security Operations SOAR genutzt, um die Plattform optimal zu nutzen.

Vorbereitung

Vorhandenes Repository per Push/Pull übertragen:

  • Authentifizierungsmethode für Git. Unterstützt werden eine Kombination aus Nutzername und Passwort (nicht empfohlen), ein Zugriffstoken (empfohlen) und ein Base64-codierter privater SSH-Schlüssel (empfohlen). Wenn Sie die beiden letztgenannten verwenden, ist der Parameter „username“ nicht erforderlich.

  • Ein lokaler Google Security Operations SOAR-Nutzer. Wird zum Importieren von Assets verwendet. Dieser Nutzer muss die Berechtigung haben, das Zielmodul zu schreiben. Ein Nutzer ohne Zugriff auf die IDE kann beispielsweise keine Integrationen abrufen.

Neues Repository erstellen

  • Alle Punkte, die zuvor unter „Vorhandenes Repository pushen/pullen“ erwähnt wurden.

  • Ein Remote-Repository. Es wird empfohlen, mindestens eine Datei im Repository zu haben. Bei den meisten Git-Diensten haben Sie die Möglichkeit, beim Erstellen des Repositorys eine README-Datei zu erstellen.

Integration konfigurieren

Sie müssen die Integration als freigegebene Instanz konfigurieren. Sie kann nicht mit einer vorhandenen Umgebung in Google SecOps SOAR verbunden werden.

Integrationseigenschaften

Parametername

Beschreibung

Repository-URL

Repository-URL. Bei der Authentifizierung mit Nutzername und Passwort muss dieser Wert mit „https://“ beginnen. Wenn Sie die SSH-Authentifizierung verwenden, muss dieser Wert mit „git@“ oder „ssh://“ beginnen. Weitere Informationen finden Sie unten im Abschnitt „Repository-URL und Branch konfigurieren“.

Zweig

Der Zweig im Repository, mit dem synchronisiert werden soll.

Git-Passwort/Token/SSH-Schlüssel

Authentifizierungsmethode für Git. Dieser Wert kann ein Git-Passwort, ein Git-Token oder ein privater SSH-Schlüssel sein. Private Schlüssel sollten mit Base64 codiert werden. RSA und Ed25519 werden unterstützt.

Git-Nutzername

Git-Nutzername. Dieser Wert ist bei der Verwendung der SSH-Authentifizierung nicht obligatorisch.

Commit-Autor

Nicht erforderlich. Ermöglicht die Angabe des Autors des Commits. Dieser Wert muss das Format „Nutzername“ haben.

Google Security Operations SOAR Verify SSL

SSL für die Google Security Operations SOAR API überprüfen

Git Verify SSL

SSL mit dem Ziel-Git-Dienst überprüfen

Repository-URL und ‑Branch konfigurieren

In diesem Leitfaden zeigen wir, wie Sie die richtigen Werte in Bitbucket abrufen. Der Vorgang ist in GitHub derselbe.


  1. Suchen Sie das Repository in Bitbucket.

    gitsync1

  2. Klicken Sie oben rechts auf die Schaltfläche „Klonen“ („Code in GitHub“).

    • SSH-Authentifizierung: Die Repository-URL lautet git@bitbucket.org:siemplifyproserv/connectors.git.

      gitsync2

  3. Nutzer-/Passwort- oder Token-Authentifizierung: Die Repository-URL lautet https://bitbucket.org/siemplifyproserv/connectors.git . (Nutzername kann ignoriert werden)

    gitsync3

  4. Aktuellen Zweig prüfen (im Bild unten „master“)

    gitsync4

Nutzungsbeispiel

Jeder Job in GitSync enthält die folgenden Parameter:


Name

Beschreibung

Jobspezifisch: Connector-Name, Integrations-ID, Zulassungsliste für Playbooks usw.

Mit diesen Parametern wird angegeben, was in das Repository übertragen wird. In GitSync werden Assets anhand ihrer Kennungen referenziert. Bei diesen Werten wird zwischen Groß- und Kleinschreibung unterschieden.

Repo-URL und Branch

Unterstützung für mehrere Repositories mit denselben Anmeldedaten hinzugefügt. Sobald diese Parameter festgelegt sind, wird das in der Integrationsinstanz konfigurierte Repository ignoriert. 

Commit-Nachricht

Wenn Sie Assets in das Repository übertragen, ist eine Nachricht für den Commit erforderlich. Hier können Sie den Grund für das Pushen angeben und erläutern, was am Asset behoben, geändert oder hinzugefügt wurde.

Readme-Add‑on

Ermöglicht das Erweitern der Dokumentation der Assets beim Pushen. In diesem Wert können Sie Folgendes verwenden:

  • Markdown-Syntax – wird in README-Dateien von Git-Anbietern wie GitHub und Bitbucket unterstützt

  • Jinja: Zum Anzeigen von Informationen zum Asset. Beispiele finden Sie in den Konstanten des Integrationsmanagers.

Die Vorlage wird am Ende der Dokumentation hinzugefügt und in der Metadatendatei „GitSync.json“ im Stammverzeichnis des Repositorys gespeichert.


Assets abrufen

In diesem Beispiel rufen wir einen Connector mit den richtigen Zuordnungen und visuellen Familien ab.

  1. Prüfen Sie zuerst, ob sich das Asset im konfigurierten Repository befindet. Suchen Sie einfach in den Repository-Verzeichnissen und kopieren Sie den Asset-Bezeichner (in der Regel der Verzeichnisname oder der Titel der README-Datei).
    gitsync5

    Beispiel aus einem Repository in Bitbucket im Verzeichnis „Connectors“. Die Verzeichnisse sind die Integrationsnamen und enthalten die tatsächlichen IDs für die Connectors.

  2. Suchen Sie in der SOAR IDE von Google Security Operations nach dem passenden Job. In diesem Beispiel verwenden wir den Job „Pull Connector“.

    • Hinweis: Wenn Sie einen Connector entfernen, prüfen Sie, ob auch die Integration des Connectors installiert ist.

  3. Klicken Sie auf den Tab „Testen“ und konfigurieren Sie die Parameter. Da wir ein Repository verwenden, das bereits in der Integrationsinstanz konfiguriert ist, lassen wir die Parameter „Repo-URL“ und „Branch“ leer und legen die anderen Parameter auf die benötigten Werte fest.

  4. Führen Sie den Job aus.

  5. Das Log des Vorgangs finden Sie unter „Debug Output“ (Debug-Ausgabe). Wenn alles gut geht, wird das im Log angegeben.

  6. Rufen Sie Google Security Operations SOAR –> „Connectors“ auf und konfigurieren Sie den Connector.


Assets übertragen

In diesem Beispiel laden wir ein Playbook und einen Block in das Repository hoch.

  1. Wählen Sie die Playbooks aus, die Sie übertragen möchten. Hier wird ein neuer Block namens „Fehlgeschlagene Anmeldung“ und ein aktualisiertes Playbook namens „Böswillige Aktivitäten“ eingeführt.

    gitsync7

  2. Suchen Sie in der SOAR IDE von Google Security Operations nach dem passenden Job. In diesem Beispiel verwenden wir den Job „Push Playbook“.

  3. Klicken Sie auf den Tab „Testen“ und konfigurieren Sie die Parameter.

  4. Da sich beide im selben Ordner (Standard) befinden, können Sie stattdessen auch die Ordner-Zulassungsliste verwenden.

  5. Führen Sie den Job aus.

  6. Das Log des Vorgangs finden Sie unter „Debug Output“ (Debug-Ausgabe). Wenn alles gut geht, wird das im Log angegeben.

  7. Prüfen Sie, ob das Repository die neuesten Versionen der Playbooks enthält.


Neues Repository erstellen

Wenn Sie ein neues Repository erstellen, ist nur eines wichtig: Sie müssen eine einzelne Datei in das Repository aufnehmen, bevor Sie es mit GitSync konfigurieren. Das geht schnell, wenn Sie beim Erstellen des Repositorys eine README-Datei im Stammverzeichnis des Repositorys einfügen.
Bitbucket

gitsync8

GitHub

gitsync9

Bekannte Probleme und Beschränkungen

  • Nachdem das Repository zum ersten Mal festgelegt wurde, wird eine vordefinierte Verzeichnisstruktur verwendet, damit bekannt ist, wo sich die einzelnen Assets befinden. Wenn Sie die Verzeichnisstruktur mit einem benutzerdefinierten Commit oder Änderungen am Repository nicht einhalten, funktioniert die Integration nicht richtig. Das Schema der Repository-Verzeichnisstruktur finden Sie am Ende dieses Dokuments.

  • Seien Sie vorsichtig, wenn Sie diese Integration mit öffentlichen Repositorys verwenden. Google Security Operations SOAR-Assets verwenden Parameter, die Anwendungs-IDs, Client-IDs, Nutzernamen und andere vertrauliche Informationen enthalten. GitSync kann nicht erkennen, ob der Parameter vertraulich ist oder nicht. Daher wird jeder Parameter, der nicht vom Typ „Password“ ist, in das Repository hochgeladen. Beim Übertragen einer Google Security Operations SOAR-Instanz (Push Environment-Job) gibt es auch die Option „Passwörter übertragen“. Mit dieser Option wird GitSync angewiesen, alle Passwortparameter aus der Integrationskonfiguration zu exportieren. Legen Sie diesen Wert nicht auf „true“ fest, wenn das Repository öffentlich ist, da sonst alle Anmeldedaten online preisgegeben werden.

  • Wenn Sie eine Google Security Operations SOAR-Instanz abrufen (Pull Environment-Job), kann die Installation aller Integrationen mehr als 5 Minuten dauern. Der Job schlägt dann mit einem Zeitlimitfehler fehl. Es wird empfohlen, alle kommerziellen Integrationen aus dem Google Security Operations Marketplace manuell zu installieren, um Probleme zu vermeiden. Es ist aber auch möglich, den Job noch einmal auszuführen, wenn er mit einem Zeitüberschreitungsfehler fehlschlägt.

  • Kommerzielle und benutzerdefinierte Integrationen werden unterschiedlich behandelt. Die benutzerdefinierte Integration wird als vollständiger ZIP-Export der Integration für einen Import-/Exportvorgang übertragen. Kommerzielle Integrationen werden nur mit dem benutzerdefinierten Code übertragen. Nach dem Pull installiert GitSync die neueste Version der Integration aus dem Google SecOps Marketplace und speichert den benutzerdefinierten Code in der offiziellen Integration.

  • Wenn Sie Zuordnungen abrufen, werden sie erst dann in der Tabelle „Einstellungen“ -> „Ontologie“ -> „Ontologiestatus“ angezeigt, wenn die Ereignisse tatsächlich in Google Security Operations SOAR aufgenommen wurden, da sie noch nicht indexiert sind.

  • Das lokale Repository wird in /opt/siemplify/siemplify_server/GitSyncFiles/{RepoName} gespeichert. Da durch die Integration Git-Objekte und nicht Dateien geschrieben werden, stellt dieser Ordner nicht das Repository dar. Er wird bei jeder Ausführung eines Jobs mit allen Änderungen überschrieben. Es wird empfohlen, einen anderen Klon des Repositorys zu verwenden und nicht den von GitSync erstellten.

  • Für Playbooks mit eingeschränkten Berechtigungen (z. B. wenn die Standardberechtigungen auf Can View festgelegt sind) ist eine bestimmte Berechtigungskonfiguration im Quellsystem erforderlich, damit die Synchronisierung über GitSync erfolgreich ist. Weitere Informationen finden Sie unter Mit Playbook-Berechtigungen arbeiten.

  • Google SecOps unterstützt die Verwendung von GitSync zum Sichern von SOAR-Assets. Google SecOps unterstützt jedoch nicht die Verwendung von GitSync zum *Verteilen* von SOAR-Assets zwischen Systemen. Das kann zu unerwarteten Ergebnissen führen, da die Datenbankobjekte möglicherweise nicht eindeutig sind.


Mit Playbook-Berechtigungen arbeiten

Wenn Sie GitSync verwenden, um Playbooks mit eingeschränkten Berechtigungen zu synchronisieren (z. B. wenn die Standardberechtigungen auf Can View festgelegt sind oder andere nicht standardmäßige Einstellungen verwendet werden), kann auf dem Zielsystem ein Fehler auftreten, wenn es nicht autorisiert ist, das Playbook zu ändern. Das liegt daran, dass GitSync einen internen System-API-Schlüssel mit der Administrator-SOC-Rolle verwendet, um Aktionen auszuführen. Damit Playbooks mit eingeschränkten Berechtigungen erfolgreich synchronisiert werden können, müssen Sie der SOC-Rolle Administrator die Berechtigung Can Edit (Kann bearbeiten) für diese Playbooks im Quellsystem gewähren.

GitSync aktivieren, um Playbooks mit eingeschränkten Berechtigungen abzurufen

  1. Im Quellsystem:
    1. Rufen Sie das Playbook auf, das Sie mit GitSync synchronisieren möchten.
    2. Öffnen Sie die Berechtigungseinstellungen des Playbooks.
    3. Achten Sie darauf, dass die Administrator-SOC-Rolle der Liste der Entitäten mit der Berechtigung Kann bearbeiten hinzugefügt wird.
  2. Nachdem Sie die Berechtigungen im Quellsystem angepasst haben, führen Sie in GitSync die Aktion Push Playbook aus, um das Git-Repository mit dem Playbook und seinen Berechtigungen zu aktualisieren.
  3. Führen Sie auf dem Zielsystem die Aktion Pull Playbook in GitSync aus.

SSH-Schlüssel für die Verwendung mit GitSync erstellen

  1. Generieren Sie zuerst ein Schlüsselpaar. Wenn Sie zur Eingabe einer Passphrase aufgefordert werden, drücken Sie die Eingabetaste: ssh-keygen -b 2048 -t rsa -f ./id_rsa

    Es werden zwei Dateien erstellt: „id_rsa“ (privater Schlüssel) und „id_rsa.pub“ (öffentlicher Schlüssel). Bewahren Sie den privaten Schlüssel an einem sicheren Ort auf.

  2. Legen Sie den öffentlichen Schlüssel im Repository fest. Geben Sie beispielsweise in Bitbucket die Einstellungen des Repositorys ein und klicken Sie auf „Access Keys“ (Zugriffsschlüssel). Klicken Sie auf „Schlüssel hinzufügen“ und fügen Sie den Inhalt von „id_rsa.pub“ in den Parameter „Schlüssel“ ein.

  3. Bevor der private Schlüssel der Integrationskonfiguration hinzugefügt werden kann, muss er Base64-codiert werden.

    Verwenden Sie diese Befehle, um die Datei zu codieren:

    • Linux:
      cat id_rsa | base64 -w 0
    • Windows:

      Öffnen Sie PowerShell, wo sich „id_rsa“ befindet, und fügen Sie Folgendes ein (das ist eine Zeile):

      Write-Output [System.Text.Encoding]::ASCII.GetString([convert]::ToBase64String(([IO.File]::ReadAllBytes((Join-Path (pwd) 'id_rsa')))))
  4. Kopieren Sie den ausgegebenen Wert in die Integrationseigenschaft „Password/Token/SSH Key“ (Passwort/Token/SSH-Schlüssel) und testen Sie die Verbindung der Integration.

Verzeichnisstruktur des GitSync-Repositorys

Die folgende Verzeichnisstruktur wird im Remote-Repository erwartet.

* Dies ist die Ausgabe des Befehls „tree“ für ein Beispiel-Repository. Kommentare sind rot.


gitsync10

gitsync11

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