Raccogli i log di GitGuardian Enterprise

Parser Version: 1.0

Supportato in:

Questo documento spiega come configurare GitGuardian Enterprise per inviare i log a Google Security Operations utilizzando i webhook.

GitGuardian Enterprise è una piattaforma di rilevamento e correzione dei segreti che monitora i repository di codice sorgente, le pipeline CI/CD e le workstation degli sviluppatori per rilevare credenziali e dati sensibili esposti. Fornisce avvisi in tempo reale quando vengono rilevati segreti e aiuta i team di sicurezza a gestire i flussi di lavoro di correzione degli incidenti.

Prima di iniziare

Assicurati di soddisfare i seguenti prerequisiti:

  • Un'istanza Google SecOps
  • Workspace GitGuardian Enterprise con livello di accesso Gestore
  • Accesso alla Google Cloud console (per la creazione di chiavi API)
  • Piano GitGuardian Business o superiore (per il supporto di webhook personalizzati)

Crea un feed webhook in Google SecOps

Creare il feed

  1. Vai a Impostazioni SIEM > Feed.
  2. Fai clic su Aggiungi nuovo feed.
  3. Nella pagina successiva, fai clic su Configura un singolo feed.
  4. Nel campo Nome feed, inserisci un nome per il feed (ad esempio GitGuardian Enterprise Incidents).
  5. Seleziona Webhook come Tipo di origine.
  6. Seleziona GitGuardian Enterprise come Tipo di log.
  7. Fai clic su Avanti.

  8. Specifica i valori per i seguenti parametri di input:

    • (Facoltativo) Delimitatore di suddivisione: lascia vuoto (ogni richiesta webhook contiene un singolo evento)
    • Spazio dei nomi dell'asset: lo spazio dei nomi dell'asset
    • Etichette di importazione: l'etichetta da applicare agli eventi di questo feed

  9. Fai clic su Avanti.

  10. Controlla la nuova configurazione del feed nella schermata Finalizza e poi fai clic su Invia.

Genera e salva la chiave segreta

Dopo aver creato il feed, devi generare una chiave segreta per l'autenticazione:

  1. Nella pagina dei dettagli del feed, fai clic su Genera chiave segreta.
  2. Una finestra di dialogo mostra la chiave segreta.

  3. Copia e salva la chiave segreta in modo sicuro.

Recuperare l'URL dell'endpoint del feed

  1. Vai alla scheda Dettagli del feed.
  2. Nella sezione Endpoint Information (Informazioni sull'endpoint), copia l'URL dell'endpoint del feed.

  3. Il formato dell'URL è:

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

    o

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

  4. Salva questo URL per i passaggi successivi.

  5. Fai clic su Fine.

Crea una chiave API Google Cloud

Google SecOps richiede una chiave API per l'autenticazione. Crea una chiave API con limitazioni nella console Google Cloud .

Crea la chiave API

  1. Vai alla pagina Credenziali della console Google Cloud.
  2. Seleziona il tuo progetto (quello associato alla tua istanza Google SecOps).
  3. Fai clic su Crea credenziali > Chiave API.
  4. Viene creata una chiave API e visualizzata in una finestra di dialogo.
  5. Fai clic su Modifica chiave API per limitare la chiave.

Limitare la chiave API

  1. Nella pagina delle impostazioni della chiave API:

    • Nome: inserisci un nome descrittivo (ad esempio, Google SecOps GitGuardian Webhook API Key)

  2. In Restrizioni delle API:

    1. Seleziona Limita chiave.
    2. Nel menu a discesa Seleziona API, cerca e seleziona API Google SecOps (o API Chronicle).

  3. Fai clic su Salva.

  4. Copia il valore della chiave API dal campo Chiave API nella parte superiore della pagina.

  5. Salva la chiave API in modo sicuro.

Configura il webhook GitGuardian Enterprise

Crea l'URL webhook

  • Combina l'URL dell'endpoint Google SecOps e la chiave API:

    <ENDPOINT_URL>?key=<API_KEY>

    Esempio:

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

Crea un webhook personalizzato in GitGuardian

Per lo spazio di lavoro personale:

  1. Accedi alla dashboard di GitGuardian.
  2. Vai a Impostazioni > Workspace > Integrazioni > Destinazioni > Webhook personalizzato.
  3. Fai clic su Aggiungi un webhook personalizzato o Crea nuovo webhook personalizzato.

  4. Fornisci i seguenti dettagli di configurazione:

    • Nome: inserisci un nome descrittivo (ad esempio, Google SecOps SIEM Integration).
    • URL: incolla l'URL completo dell'endpoint con la chiave API riportata sopra.
    • Token di firma: incolla la chiave segreta dalla creazione del feed Google SecOps.
    • Intestazione personalizzata (facoltativo): lascia vuoto a meno che tu non debba specificare tag di ambiente o servizio.

  5. Nella sezione Sottoscrizione agli eventi, seleziona gli eventi che vuoi inviare a Google SecOps:

    • Incidenti:
      • ☑ Nuovo incidente rilevato
      • ☑ Nuova occorrenza rilevata
      • ☑ Incidente risolto
      • ☑ Incidente ignorato
      • ☑ Incidente riaperto
      • ☑ Regressione degli incidenti
      • ☑ Incidente assegnato
      • ☑ Incidente riassegnato
      • ☑ Incidente non assegnato
      • ☑ Gravità dell'incidente modificata
      • ☑ Validità dell'incidente modificata
      • ☑ Accesso all'incidente concesso
      • ☑ Accesso all'incidente revocato
      • ☑ Incidente condiviso pubblicamente
      • ☑ Incidente non condiviso pubblicamente
      • ☑ Feedback inviato
      • ☑ Nuovo commento su un incidente

  6. Fai clic su Crea o Salva.

  7. GitGuardian invia un messaggio di prova per verificare che il webhook sia operativo.

Per lo spazio di lavoro aziendale:

  1. Accedi alla dashboard di GitGuardian.

  2. Determina l'ambito del webhook:

    • Per tutti gli incidenti nello spazio di lavoro: vai al team Tutti gli incidenti.
    • Per incidenti specifici del team: vai al team che ti interessa.

  3. Vai a Impostazioni > Workspace > Integrazioni > Destinazioni > Webhook personalizzato.

    • In alternativa, dalla pagina del team, vai a Integrazioni > Webhook personalizzato.

  4. Fai clic su Aggiungi un webhook personalizzato o Crea nuovo webhook personalizzato.

  5. Fornisci i seguenti dettagli di configurazione:

    • Nome: inserisci un nome descrittivo (ad esempio, Google SecOps SIEM Integration).
    • URL: incolla l'URL completo dell'endpoint con la chiave API riportata sopra.
    • Token di firma: incolla la chiave segreta dalla creazione del feed Google SecOps.
    • Intestazione personalizzata (facoltativo): lascia vuoto a meno che tu non debba specificare tag di ambiente o servizio.

  6. Nella sezione Sottoscrizione agli eventi, seleziona gli eventi che vuoi inviare a Google SecOps:

    • Incidenti:
      • ☑ Nuovo incidente rilevato
      • ☑ Nuova occorrenza rilevata
      • ☑ Incidente risolto
      • ☑ Incidente ignorato
      • ☑ Incidente riaperto
      • ☑ Regressione degli incidenti
      • ☑ Incidente assegnato
      • ☑ Incidente riassegnato
      • ☑ Incidente non assegnato
      • ☑ Gravità dell'incidente modificata
      • ☑ Validità dell'incidente modificata
      • ☑ Accesso all'incidente concesso
      • ☑ Accesso all'incidente revocato
      • ☑ Incidente condiviso pubblicamente
      • ☑ Incidente non condiviso pubblicamente
      • ☑ Feedback inviato
      • ☑ Nuovo commento su un incidente

  7. Fai clic su Crea o Salva.

  8. GitGuardian invia un messaggio di prova per verificare che il webhook sia operativo.

Verifica la pubblicazione dei webhook

  1. Nella dashboard di GitGuardian, vai alla configurazione del webhook personalizzato.
  2. Fai clic su Invia messaggio di prova o Testa webhook.
  3. GitGuardian invia un payload di esempio a Google SecOps.
  4. Nella console Google SecOps, vai a Impostazioni SIEM > Feed.
  5. Individua il feed GitGuardian e verifica che l'evento di test sia stato ricevuto.

  6. Controlla che lo stato dei feed sia Attivo con il timestamp di importazione recente.

Riferimento ai metodi di autenticazione

I feed webhook di Google SecOps supportano più metodi di autenticazione. Scegli il metodo supportato dal tuo fornitore.

I webhook personalizzati di GitGuardian funzionano meglio con le credenziali aggiunte all'URL.

  • Formato URL:

    <ENDPOINT_URL>?key=<API_KEY>

    Esempio:

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

    Configurazione del webhook GitGuardian:

    • URL: URL dell'endpoint completo con il parametro della chiave API
    • Token di firma: chiave segreta di Google SecOps (per la verifica HMAC)

  • Formato della richiesta:

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

Metodo 2: intestazioni personalizzate (alternativa)

Se preferisci non includere le credenziali nell'URL, utilizza intestazioni personalizzate.

  • Formato della richiesta:

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

Verifica della firma del webhook GitGuardian

GitGuardian firma tutti i payload webhook utilizzando HMAC-SHA256 per garantire l'autenticità e impedire la manomissione.

Intestazioni delle firme

GitGuardian include le seguenti intestazioni nelle richieste webhook:

  • Gitguardian-Signature: firma HMAC-SHA256 nel formato sha256=<hex_digest>
  • Timestamp: timestamp Unix di invio della richiesta
  • X-GitGuardian-Signature: intestazione deprecata (ancora supportata per la compatibilità con le versioni precedenti)

Algoritmo di firma

  • La firma viene calcolata come segue:

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

    Dove:

    • timestamp: valore dell'intestazione Timestamp
    • signature_token: la chiave segreta configurata nelle impostazioni del webhook di GitGuardian
    • payload: corpo della richiesta JSON non elaborato come stringa UTF-8

Esempio di verifica (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)

Protezione dagli attacchi di replay

  • L'intestazione Timestamp impedisce gli attacchi di replay. Se il timestamp attuale differisce dal timestamp del webhook di più di qualche secondo (consigliato: 300 secondi), rifiuta la richiesta.

Tipi di eventi e struttura del payload

GitGuardian invia diversi tipi di eventi in base alle modifiche del ciclo di vita dell'incidente.

Eventi di incidenti

Tipo di evento Valore dell'azione Descrizione
Nuovo incidente rilevato incident_triggered È stato rilevato un nuovo incidente relativo ai secret
Nuova occorrenza rilevata new_occurrence È stata trovata una nuova occorrenza di un incidente esistente
Incidente risolto incident_resolved L'incidente è stato contrassegnato come risolto
Incidente ignorato incident_ignored L'incidente è stato contrassegnato come ignorato
Incidente riaperto incident_reopened Un incidente chiuso in precedenza è stato riaperto
Regressione degli incidenti incident_regression È stata rilevata una nuova regressione per questo incidente
Incidente assegnato incident_assigned L'incidente è stato assegnato a un utente
Incidente riassegnato incident_reassigned L'incidente è stato riassegnato a un altro utente
Incidente non assegnato incident_unassigned L'assegnazione di un utente a questo incidente è stata annullata
Gravità modificata incident_severity_changed Il livello di gravità è stato aggiornato
Validità modificata incident_validity_changed Lo stato di validità è stato aggiornato
Accesso concesso incident_access_granted A un utente è stato concesso l'accesso a questo incidente
Accesso revocato incident_access_revoked L'accesso a questo incidente è stato revocato per un utente
Condiviso pubblicamente incident_shared_publicly È stato generato un link di condivisione pubblica
Non più condiviso pubblicamente incident_unshared_publicly Il link di condivisione pubblica è stato disattivato
Feedback inviato issue_feedback_received È stato inviato un feedback per questo incidente
New comment incident_note_created È stata creata una nuova nota per questo incidente

Struttura del payload di esempio

  • Tutti i payload webhook seguono questa struttura:

    {
    "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"
    }
}

Limiti e best practice dei webhook

Limiti per le richieste

Limite Valore
Dimensioni massime della richiesta 4 MB
QPS max (query al secondo) 15.000
Timeout richieste 30 secondi
Comportamento dei nuovi tentativi Automatico con backoff esponenziale

Best practice

  • Selezione degli eventi: iscriviti solo agli eventi pertinenti alle tue operazioni di sicurezza per ridurre il rumore.
  • Ambito del team: per gli spazi di lavoro aziendali, crea webhook a livello di team per filtrare gli incidenti in base alla proprietà del team.
  • Verifica della firma: memorizza il token di firma in modo sicuro e non eseguirne mai il commit nel codice sorgente.
  • Monitoraggio: controlla regolarmente lo stato di consegna dei webhook nella dashboard GitGuardian.
  • Test: utilizza la funzionalità di messaggio di test per verificare la configurazione del webhook prima dell'utilizzo in produzione.

Garanzie di consegna

Importante: la distribuzione dei webhook è un tentativo e non è garantita. Se l'endpoint di Google SecOps non è raggiungibile o si verificano problemi di rete, gli eventi webhook potrebbero non essere ricevuti. Sebbene i webhook siano generalmente affidabili, la consegna non può essere garantita.

Per i casi d'uso critici, valuta la possibilità di integrare i webhook con il polling periodico delle API per assicurarti di non perdere nessun incidente.

Tabella di mappatura UDM

Campo log Mappatura UDM Logica
data metadata.event_timestamp Convertito utilizzando il formato ISO8601
has_user metadata.event_type Impostato su "USER_UNCATEGORIZED" se has_user è true, altrimenti su "GENERIC_EVENT"
event_name metadata.product_event_type Valore copiato direttamente
id metadata.product_log_id Valore copiato direttamente
metadata.product_name Imposta su "GitGuardian Enterprise"
metadata.vendor_name Impostato su "GitGuardian"
member_email principal.user.email_addresses Unito da member_email
member_name principal.user.user_display_name Valore copiato direttamente
member_id principal.user.userid Convertito in stringa
action_type security_result.action_details Valore copiato direttamente
target_ids target.resource.product_object_id Valore ottenuto dal primo elemento di target_ids

Log delle modifiche

Visualizza il log delle modifiche per questo parser

Hai bisogno di ulteriore assistenza? Ricevi risposte dai membri della community e dai professionisti di Google SecOps.