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 vertraulichen Informationen, die Quellcode-Repositories, CI/CD-Pipelines und Entwickler-Workstations auf offengelegte Anmeldedaten und vertrauliche 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-Abo „Business“ oder höher (für die Unterstützung benutzerdefinierter Webhooks)

Webhook-Feed in Google SecOps erstellen

Feed erstellen

  1. Rufen Sie die SIEM-Einstellungen > Feeds auf.
  2. Klicken Sie auf Neuen Feed hinzufügen.
  3. Klicken Sie auf der nächsten Seite auf Einen 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 Log type (Protokolltyp) aus.
  7. Klicken Sie auf Weiter.

  8. Geben Sie Werte für die folgenden Eingabeparameter an:

    • Trennzeichen für Aufteilung (optional): Feld 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. Ein Dialogfeld mit dem geheimen Schlüssel wird angezeigt.

  3. Kopieren und speichern Sie den geheimen Schlüssel an einem sicheren Ort.

Feed-Endpunkt-URL abrufen

  1. Rufen Sie den Tab Details des Feeds auf.
  2. Kopieren Sie im Bereich Endpunktinformationen die Feed-Endpunkt-URL.

  3. Das URL-Format lautet:

    https://malachiteingestion-pa.googleapis.com/v2/unstructuredlogentries:batchCreate

    oder

    https://<REGION>-malachiteingestion-pa.googleapis.com/v2/unstructuredlogentries:batchCreate

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

  5. Klicken Sie auf Fertig.

Google Cloud API-Schlüssel erstellen

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

API-Schlüssel erstellen

  1. Rufen Sie die Seite „Anmeldedaten“ in der Google 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 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 Google SecOps API (oder Chronicle API) und wählen Sie die API aus.

  3. Klicken Sie auf Speichern.

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

  5. Speichern Sie den API-Schlüssel sicher.

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://malachiteingestion-pa.googleapis.com/v2/unstructuredlogentries:batchCreate?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> „Workspace“ > „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 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 Event Subscription (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
      • ☑ Regression von Vorfällen
      • ☑ Vorfall zugewiesen
      • ☑ Vorfall neu zugewiesen
      • ☑ Zuweisung des Vorfalls aufgehoben
      • ☑ Schweregrad des Vorfalls geändert
      • ☑ Gültigkeit des Vorfalls geändert
      • ☑ Zugriff auf Vorfall gewährt
      • ☑ Zugriff auf Vorfall entzogen
      • ☑ Vorfall öffentlich geteilt
      • ☑ Vorfall wurde 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 Arbeitsbereiche für Unternehmen:

  1. Melden Sie sich im GitGuardian-Dashboard an.

  2. Legen Sie den Umfang für Ihren Webhook fest:

    • Alle Vorfälle im Arbeitsbereich: Rufen Sie das Team „Alle Vorfälle“ auf.
    • Bestimmte Teamvorfälle: Rufen Sie das gewünschte Team auf.

  3. Gehen Sie zu Einstellungen> „Workspace“ > „Integrationen“ > „Ziele“ > „Benutzerdefinierter Webhook“.

    • Alternativ können Sie auf der Teamseite zu Integrationen > Benutzerdefinierter Webhook wechseln.

  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 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 Event Subscription (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
      • ☑ Regression von Vorfällen
      • ☑ Vorfall zugewiesen
      • ☑ Vorfall neu zugewiesen
      • ☑ Zuweisung des Vorfalls aufgehoben
      • ☑ Schweregrad des Vorfalls geändert
      • ☑ Gültigkeit des Vorfalls geändert
      • ☑ Zugriff auf Vorfall gewährt
      • ☑ Zugriff auf Vorfall entzogen
      • ☑ Vorfall öffentlich geteilt
      • ☑ Vorfall wurde 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 Beispielnutzlast an Google SecOps.
  4. Rufen Sie in der Google SecOps-Konsole die SIEM-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 als Aktiv mit einem aktuellen Zeitstempel für die Aufnahme angezeigt wird.

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 Webhooks von GitGuardian funktionieren am besten mit Anmeldedaten, die an die URL angehängt werden.

  • URL-Format:

    <ENDPOINT_URL>?key=<API_KEY>

    Beispiel:

    https://malachiteingestion-pa.googleapis.com/v2/unstructuredlogentries:batchCreate?key=AIzaSyD...

    GitGuardian-Webhook-Konfiguration:

    • URL: Vollständige Endpunkt-URL mit API-Schlüsselparameter
    • Signatur-Token: Geheimer Google SecOps-Schlüssel (für die HMAC-Bestätigung)

  • 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": {...}
}

Überprüfung der GitGuardian-Webhook-Signatur

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

Signatur-Header

GitGuardian fügt Webhook-Anfragen die folgenden Header hinzu:

  • Gitguardian-Signatur: HMAC-SHA256-Signatur im Format sha256=<hex_digest>
  • Zeitstempel: Unix-Zeitstempel, der angibt, wann die Anfrage gesendet wurde
  • X-GitGuardian-Signature: Veralteter Header (wird weiterhin für die Abwärtskompatibilität 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: Roh-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 Replay-Angriffen

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

Ereignistypen und Nutzlaststruktur

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

Vorfallereignisse

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
Regression von Vorfällen 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.
Vorfall nicht zugewiesen 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 generiert
Nicht öffentlich freigegeben incident_unshared_publicly Der Link für die öffentliche Freigabe wurde deaktiviert.
Feedback gesendet issue_feedback_received Für diesen Vorfall wurde Feedback gesendet
Neuer Kommentar incident_note_created Für diesen Vorfall wurde ein neuer Hinweis erstellt

Beispiel für die Struktur der Nutzlast

  • 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 Anfragengröße 4 MB
Maximale Anzahl von 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 Rauschen zu reduzieren.
  • Teambereich: In Arbeitsbereichen für Unternehmen können Sie Webhooks auf Teamebene erstellen, um Vorfälle nach Teameigentum zu filtern.
  • Signaturüberprüfung: Speichern Sie das Signatur-Token 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-Übermittlung erfolgt auf Best-Effort-Basis und ist nicht garantiert. Wenn Ihr Google SecOps-Endpunkt nicht erreichbar ist oder Netzwerkprobleme auftreten, werden Webhook-Ereignisse möglicherweise nicht empfangen. Webhooks sind zwar in der Regel zuverlässig, die Zustellung kann jedoch nicht garantiert werden.

Bei kritischen Anwendungsfällen sollten Sie Webhooks durch regelmäßiges API-Polling 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 Auf „GitGuardian Enterprise“ festgelegt
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