GitGuardian Enterprise-Logs erfassen

Parserversion: 1.0

Unterstützt in:

In diesem Dokument wird beschrieben, wie Sie GitGuardian Enterprise so konfigurieren, dass Logs über Webhooks an Google Security Operations gesendet werden.

GitGuardian Enterprise ist eine Plattform zur Erkennung und Behebung von Secret-Lecks, die Quellcode-Repositories, CI/CD-Pipelines und Entwickler-Workstations auf offengelegte Anmeldedaten und sensible Daten überwacht. Sie erhalten Echtzeitbenachrichtigungen, wenn Secrets erkannt werden, und Sicherheitsteams können Workflows zur Behebung von Vorfällen verwalten.

Hinweis

Prüfen Sie, ob folgende Voraussetzungen erfüllt sind:

  • Eine Google SecOps-Instanz
  • GitGuardian Enterprise-Arbeitsbereich mit Zugriffsebene „Manager“
  • Zugriff auf die Google Cloud Console (zum Erstellen von API-Schlüsseln)
  • GitGuardian Business-Abo oder höher (für die Unterstützung benutzerdefinierter Webhooks)

Webhook-Feed in Google SecOps erstellen

Feed erstellen

  1. Rufen Sie die Einstellungen > Datenverwaltung > Feeds auf. Wenn Sie eine reine SIEM-Plattform verwenden, rufen Sie die Einstellungen > Feeds auf.
  2. Klicken Sie auf Neuen Feed hinzufügen.
  3. Klicken Sie auf der nächsten Seite auf Einzelnen Feed konfigurieren.
  4. Geben Sie im Feld Feedname einen Namen für den Feed ein, z. B. GitGuardian Enterprise Incidents.
  5. Wählen Sie Webhook als Quelltyp aus.
  6. Wählen Sie GitGuardian Enterprise als Protokolltyp aus.
  7. Klicken Sie auf Weiter.
  8. Geben Sie Werte für die folgenden Eingabeparameter an:

    • Trennzeichen für Aufteilung (optional): Leer lassen (jede Webhook-Anfrage enthält ein einzelnes Ereignis)
    • Asset-Namespace: Der Asset-Namespace
    • Labels für Datenaufnahme: Das Label, das auf die Ereignisse aus diesem Feed angewendet werden soll.
  9. Klicken Sie auf Weiter.

  10. Prüfen Sie die neue Feedkonfiguration auf dem Bildschirm Abschließen und klicken Sie dann auf Senden.

Secret-Schlüssel generieren und speichern

Nachdem Sie den Feed erstellt haben, müssen Sie einen Secret-Schlüssel für die Authentifizierung generieren:

  1. Klicken Sie auf der Feed-Detailseite auf Geheimen Schlüssel generieren.
  2. In einem Dialogfeld wird der geheime Schlüssel angezeigt.
  3. Kopieren und speichern Sie den geheimen Schlüssel an einem sicheren Ort.

Feed-Endpunkt-URL abrufen

  1. Gehen Sie zum Tab Details des Feeds.
  2. Kopieren Sie im Abschnitt Endpunktinformationen die Feed-Endpunkt-URL.
  3. Das URL-Format lautet:

    https://{region}-chronicle.googleapis.com/v1/{parent}/logs:import
    

    Dabei ist {region} die Region Ihrer Google SecOps-Instanz (z. B. us, europe oder asia-southeast1) und {parent} der Ressourcenpfad im Format projects/<PROJECT_ID>/locations/<LOCATION>/instances/<INSTANCE_ID>/logTypes/<LOG_TYPE>.

  4. Speichern Sie diese URL für die nächsten Schritte.

  5. Klicken Sie auf Fertig.

Google Cloud API-Schlüssel erstellen

Google SecOps erfordert einen API-Schlüssel für die Authentifizierung. Erstellen Sie in der Google Cloud Console einen eingeschränkten API-Schlüssel.

API-Schlüssel erstellen

  1. Rufen Sie die Seite „Anmeldedaten“ derGoogle Cloud Console auf.
  2. Wählen Sie Ihr Projekt aus (das Projekt, das mit Ihrer Google SecOps-Instanz verknüpft ist).
  3. Klicken Sie auf Anmeldedaten erstellen > API-Schlüssel.
  4. Ein API-Schlüssel wird erstellt und in einem Dialogfeld angezeigt.
  5. Klicken Sie auf API-Schlüssel bearbeiten, um den Schlüssel einzuschränken.

API-Schlüssel einschränken

  1. Auf der Seite mit den Einstellungen für den API-Schlüssel:

    • Name: Geben Sie einen aussagekräftigen Namen ein (z. B. Google SecOps GitGuardian Webhook API Key).
  2. Gehen Sie unter API-Einschränkungen so vor:

    1. Wählen Sie Schlüssel einschränken aus.
    2. Suchen Sie im Drop-down-Menü APIs auswählen nach der Google SecOps API (oder Chronicle API) und wählen Sie sie aus.
  3. Klicken Sie auf Speichern.

  4. Kopieren Sie den Wert des API-Schlüssels aus dem Feld API-Schlüssel oben auf der Seite.

  5. Speichern Sie den API-Schlüssel an einem sicheren Ort.

GitGuardian Enterprise-Webhook konfigurieren

Webhook-URL erstellen

  • Kombinieren Sie die Google SecOps-Endpunkt-URL und den API-Schlüssel:

    <ENDPOINT_URL>?key=<API_KEY>
    

    Beispiel:

    https://{region}-chronicle.googleapis.com/v1/{parent}/logs:import?key=AIzaSyD...
    

Benutzerdefinierten Webhook in GitGuardian erstellen

Für den persönlichen Arbeitsbereich:

  1. Melden Sie sich im GitGuardian-Dashboard an.
  2. Gehen Sie zu Einstellungen > Arbeitsbereich > Integrationen > Ziele > Benutzerdefinierter Webhook.
  3. Klicken Sie auf Benutzerdefinierten Webhook hinzufügen oder Neuen benutzerdefinierten Webhook erstellen.
  4. Geben Sie die folgenden Konfigurationsdetails an:

    • Name: Geben Sie einen aussagekräftigen Namen ein (z. B. Google SecOps SIEM Integration).
    • URL: Fügen Sie die vollständige Endpunkt-URL mit dem API-Schlüssel von oben ein.
    • Signaturtoken: Fügen Sie den geheimen Schlüssel aus der Google SecOps-Feederstellung ein.
    • Benutzerdefinierter Header (optional): Lassen Sie dieses Feld leer, es sei denn, Sie müssen Umgebungs- oder Dienst-Tags angeben.
  5. Wählen Sie im Bereich Ereignisabo die Ereignisse aus, die Sie an Google SecOps senden möchten:

    • Vorfälle:
      • ☑ Neuer Vorfall erkannt
      • ☑ Neues Vorkommen erkannt
      • ☑ Vorfall behoben
      • ☑ Vorfall ignoriert
      • ☑ Vorfall wieder geöffnet
      • ☑ Vorfallregression
      • ☑ Vorfall zugewiesen
      • ☑ Vorfall neu zugewiesen
      • ☑ Vorfall nicht zugewiesen
      • ☑ Schweregrad des Vorfalls geändert
      • ☑ Gültigkeit des Vorfalls geändert
      • ☑ Zugriff auf Vorfall gewährt
      • ☑ Zugriff auf Vorfall entzogen
      • ☑ Vorfall öffentlich geteilt
      • ☑ Vorfall nicht öffentlich geteilt
      • ☑ Feedback gesendet
      • ☑ Neuer Kommentar zu einem Vorfall
  6. Klicken Sie auf Erstellen oder Speichern.

  7. GitGuardian sendet eine Testnachricht, um zu prüfen, ob der Webhook funktioniert.

Für Workspace-Konten von Unternehmen:

  1. Melden Sie sich im GitGuardian-Dashboard an.
  2. Legen Sie den Bereich für Ihren Webhook fest:

    • Für alle Vorfälle im Arbeitsbereich: Rufen Sie das Team für alle Vorfälle auf.
    • Für Vorfälle, die ein bestimmtes Team betreffen: Rufen Sie das gewünschte Team auf.
  3. Gehen Sie zu Einstellungen > Arbeitsbereich > Integrationen > Ziele > Benutzerdefinierter Webhook.

    • Alternativ können Sie auf der Teamseite zu Integrationen > Benutzerdefinierter Webhook gehen.
  4. Klicken Sie auf Benutzerdefinierten Webhook hinzufügen oder Neuen benutzerdefinierten Webhook erstellen.

  5. Geben Sie die folgenden Konfigurationsdetails an:

    • Name: Geben Sie einen aussagekräftigen Namen ein (z. B. Google SecOps SIEM Integration).
    • URL: Fügen Sie die vollständige Endpunkt-URL mit dem API-Schlüssel von oben ein.
    • Signaturtoken: Fügen Sie den geheimen Schlüssel aus der Google SecOps-Feederstellung ein.
    • Benutzerdefinierter Header (optional): Lassen Sie dieses Feld leer, es sei denn, Sie müssen Umgebungs- oder Dienst-Tags angeben.
  6. Wählen Sie im Bereich Ereignisabo die Ereignisse aus, die Sie an Google SecOps senden möchten:

    • Vorfälle:
      • ☑ Neuer Vorfall erkannt
      • ☑ Neues Vorkommen erkannt
      • ☑ Vorfall behoben
      • ☑ Vorfall ignoriert
      • ☑ Vorfall wieder geöffnet
      • ☑ Vorfallregression
      • ☑ Vorfall zugewiesen
      • ☑ Vorfall neu zugewiesen
      • ☑ Vorfall nicht zugewiesen
      • ☑ Schweregrad des Vorfalls geändert
      • ☑ Gültigkeit des Vorfalls geändert
      • ☑ Zugriff auf Vorfall gewährt
      • ☑ Zugriff auf Vorfall entzogen
      • ☑ Vorfall öffentlich geteilt
      • ☑ Vorfall nicht öffentlich geteilt
      • ☑ Feedback gesendet
      • ☑ Neuer Kommentar zu einem Vorfall
  7. Klicken Sie auf Erstellen oder Speichern.

  8. GitGuardian sendet eine Testnachricht, um zu prüfen, ob der Webhook funktioniert.

Webhook-Zustellung überprüfen

  1. Rufen Sie im GitGuardian-Dashboard Ihre benutzerdefinierte Webhook-Konfiguration auf.
  2. Klicken Sie auf Testnachricht senden oder Webhook testen.
  3. GitGuardian sendet eine Beispiel-Nutzlast an Google SecOps.
  4. Rufen Sie in Google SecOps die Einstellungen > Datenverwaltung > Feeds auf. Wenn Sie eine reine SIEM-Plattform verwenden, rufen Sie die Einstellungen > Feeds auf.
  5. Suchen Sie Ihren GitGuardian-Feed und prüfen Sie, ob das Testereignis empfangen wurde.
  6. Prüfen Sie, ob der Feedstatus Aktiv ist und einen aktuellen Zeitstempel für die Aufnahme enthält.

Referenz zu Authentifizierungsmethoden

Google SecOps-Webhook-Feeds unterstützen mehrere Authentifizierungsmethoden. Wählen Sie die Methode aus, die von Ihrem Anbieter unterstützt wird.

Benutzerdefinierte GitGuardian-Webhooks funktionieren am besten mit Anmeldedaten, die an die URL angehängt sind.

  • URL-Format:

    <ENDPOINT_URL>?key=<API_KEY>
    

    Beispiel:

    https://{region}-chronicle.googleapis.com/v1/{parent}/logs:import?key=AIzaSyD...
    

    GitGuardian-Webhook-Konfiguration:

    • URL: Vollständige Endpunkt-URL mit API-Schlüsselparameter
    • Signaturtoken: Geheimer Google SecOps-Schlüssel (für die HMAC-Verifizierung)
  • Anfrageformat:

    POST <ENDPOINT_URL>?key=<API_KEY> HTTP/1.1
    Content-Type: application/json
    Timestamp: 1234567890
    Gitguardian-Signature: sha256=abc123...
    
    {
        "source": "GitGuardian",
        "timestamp": "2025-01-15T10:30:00Z",
        "action": "incident_triggered",
        "incident": {...}
    }
    

Methode 2: Benutzerdefinierte Header (Alternative)

Wenn Sie Anmeldedaten nicht in der URL angeben möchten, verwenden Sie benutzerdefinierte Header.

  • Anfrageformat:

    POST <ENDPOINT_URL> HTTP/1.1
    Content-Type: application/json
    x-goog-chronicle-auth: <API_KEY>
    Timestamp: 1234567890
    Gitguardian-Signature: sha256=abc123...
    
    {
        "source": "GitGuardian",
        "timestamp": "2025-01-15T10:30:00Z",
        "action": "incident_triggered",
        "incident": {...}
    }
    

GitGuardian-Webhook-Signaturüberprüfung

GitGuardian signiert alle Webhook-Nutzlasten mit HMAC-SHA256, um die Authentizität zu gewährleisten und Manipulationen zu verhindern.

Signatur-Header

GitGuardian enthält die folgenden Header in Webhook-Anfragen:

  • Gitguardian-Signature: HMAC-SHA256-Signatur im Format sha256=<hex_digest>
  • Zeitstempel: Unix-Zeitstempel, der angibt, wann die Anfrage gesendet wurde
  • X-GitGuardian-Signature: Veralteter Header (wird aus Gründen der Abwärtskompatibilität weiterhin unterstützt)

Signaturalgorithmus

  • Die Signatur wird so berechnet:

    HMAC-SHA256(key=timestamp + signature_token, message=payload)
    

    Wobei:

    • timestamp: Wert aus dem Timestamp-Header
    • signature_token: Der geheime Schlüssel, der in den GitGuardian-Webhook-Einstellungen konfiguriert ist.
    • payload: Unformatierter JSON-Anfragetext als UTF-8-String

Beispiel für die Verifizierung (Python)

import hmac
import hashlib

def verify_signature(signature: str, timestamp: str, signature_token: str, payload: str) -> bool:
    if not signature.startswith("sha256="):
        return False
    
    signature = signature.split("sha256=")[-1]
    
    hmac_digest = hmac.new(
        key=bytes(timestamp + signature_token, "utf-8"),
        msg=bytes(payload, "utf-8"),
        digestmod=hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(signature, hmac_digest)

Schutz vor Wiederholungsangriffen

  • Der Timestamp-Header verhindert Replay-Angriffe. Wenn der aktuelle Zeitstempel um mehr als ein paar Sekunden (empfohlen: 300 Sekunden) vom Webhook-Zeitstempel abweicht, lehnen Sie die Anfrage ab.

Ereignistypen und Nutzlaststruktur

GitGuardian sendet verschiedene Ereignistypen basierend auf Änderungen im Lebenszyklus von Vorfällen.

Vorfälle

Ereignistyp Aktionswert Beschreibung
Neuer Vorfall erkannt incident_triggered Ein neuer Secret-Vorfall wurde erkannt
Neues Vorkommen erkannt new_occurrence Ein neues Auftreten eines vorhandenen Vorfalls wurde gefunden
Vorfall behoben incident_resolved Der Vorfall wurde als behoben markiert.
Vorfall ignoriert incident_ignored Der Vorfall wurde als ignoriert markiert
Vorfall wieder geöffnet incident_reopened Ein zuvor geschlossener Vorfall wurde wieder geöffnet
Vorfallregression incident_regression Für diesen Vorfall wurde eine neue Regression gefunden
Vorfall zugewiesen incident_assigned Der Vorfall wurde einem Nutzer zugewiesen
Vorfall neu zugewiesen incident_reassigned Der Vorfall wurde einem anderen Nutzer zugewiesen
Zuweisung des Vorfalls aufgehoben incident_unassigned Ein Nutzer wurde von diesem Vorfall entfernt
Schweregrad geändert incident_severity_changed Der Schweregrad wurde aktualisiert
Gültigkeit geändert incident_validity_changed Der Gültigkeitsstatus wurde aktualisiert
Zugriff gewährt incident_access_granted Einem Nutzer wurde Zugriff auf diesen Vorfall gewährt
Zugriff entzogen incident_access_revoked Der Zugriff auf diesen Vorfall wurde für einen Nutzer widerrufen
Öffentlich geteilt incident_shared_publicly Ein Link für die öffentliche Freigabe wurde erstellt
Öffentliche Freigabe aufgehoben incident_unshared_publicly Der Link für die öffentliche Freigabe wurde deaktiviert
Feedback gesendet issue_feedback_received Für diesen Vorfall wurde Feedback eingereicht
Neuer Kommentar incident_note_created Für diesen Vorfall wurde eine neue Notiz erstellt

Beispiel für Nutzlaststruktur

  • Alle Webhook-Nutzlasten folgen dieser Struktur:

    {
        "source": "GitGuardian",
        "timestamp": "2025-01-15T10:30:00.123456Z",
        "action": "incident_triggered",
        "message": "A new incident has been detected.",
        "target_user": "john.doe@example.com",
        "target_team": "Security Team",
        "custom_webhook_name": "Google SecOps SIEM Integration",
        "incident": {
            "id": 12345,
            "date": "2025-01-15T10:29:58.123456Z",
            "detector": {
                "name": "aws_iam",
                "display_name": "AWS Keys",
                "nature": "specific",
                "family": "credentials"
            },
            "secret_hash": "abc123...",
            "secret_revoked": false,
            "validity": "valid",
            "occurrence_count": 1,
            "status": "triggered",
            "assignee_email": null,
            "severity": "high",
            "gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/incidents/12345"
        }
    }
    

Webhook-Limits und Best Practices

Anfragelimits

Limit Wert
Maximale Anfragegröße 4 MB
Maximale Abfragen pro Sekunde 15.000
Zeitlimit für Anfragen 30 Sekunden
Wiederholungsverhalten Automatisch mit exponentiellem Backoff

Best Practices

  • Ereignisauswahl: Abonnieren Sie nur Ereignisse, die für Ihre Sicherheitsvorgänge relevant sind, um die Anzahl der Benachrichtigungen zu reduzieren.
  • Teambereich: Für Arbeitsbereiche von Unternehmen können Sie Webhooks auf Teamebene erstellen, um Vorfälle nach Teameigentum zu filtern.
  • Signaturüberprüfung: Speichern Sie das Signaturtoken sicher und übertragen Sie es niemals in den Quellcode.
  • Monitoring: Prüfen Sie regelmäßig den Webhook-Zustellungsstatus im GitGuardian-Dashboard.
  • Testen: Verwenden Sie die Funktion für Testnachrichten, um die Webhook-Konfiguration vor der Verwendung in der Produktion zu prüfen.

Übermittlungsgarantien

Wichtig: Die Webhook-Zustellung erfolgt auf Best-Effort-Basis und ist nicht garantiert. Wenn Ihr Google SecOps-Endpunkt nicht erreichbar ist oder Netzwerkprobleme vorliegen, werden Webhook-Ereignisse möglicherweise nicht empfangen. Webhooks sind zwar im Allgemeinen zuverlässig, die Zustellung kann jedoch nicht garantiert werden.

Bei kritischen Anwendungsfällen sollten Sie Webhooks durch regelmäßige API-Abfragen ergänzen, damit keine Vorfälle übersehen werden.

UDM-Zuordnungstabelle

Logfeld UDM-Zuordnung Logik
date metadata.event_timestamp Konvertiert im ISO8601-Format
has_user metadata.event_type Wird auf „USER_UNCATEGORIZED“ gesetzt, wenn „has_user“ „true“ ist, andernfalls auf „GENERIC_EVENT“
event_name metadata.product_event_type Wert direkt kopiert
id metadata.product_log_id Wert direkt kopiert
metadata.product_name Legen Sie diesen Wert auf „GitGuardian Enterprise“ fest.
metadata.vendor_name Legen Sie diesen Wert auf „GitGuardian“ fest.
member_email principal.user.email_addresses Zusammengeführt aus member_email
member_name principal.user.user_display_name Wert direkt kopiert
member_id principal.user.userid In String umgewandelt
action_type security_result.action_details Wert direkt kopiert
target_ids target.resource.product_object_id Wert aus dem ersten Element von „target_ids“

Änderungsprotokoll

Änderungsprotokoll für diesen Parser ansehen

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