Raccogli i log di GitGuardian Enterprise
Parser Version: 1.0
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 secret che monitora i repository di codice sorgente, le pipeline CI/CD e le workstation degli sviluppatori per individuare credenziali e dati sensibili esposti. Fornisce avvisi in tempo reale quando vengono rilevati secret e aiuta i team di sicurezza a gestire i workflow 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 console Google Cloud (per la creazione delle chiavi API)
- Piano GitGuardian Business o superiore (per il supporto dei webhook personalizzati)
Crea un feed webhook in Google SecOps
Crea il feed
- Vai a Impostazioni > Gestione dei dati > Feed. Se utilizzi una piattaforma solo SIEM, vai a Impostazioni > Feed.
- Fai clic su Aggiungi nuovo feed.
- Nella pagina successiva, fai clic su Configura un singolo feed.
- Nel campo Nome feed, inserisci un nome per il feed (ad es.
GitGuardian Enterprise Incidents). - Seleziona Webhook come Tipo di origine.
- Seleziona GitGuardian Enterprise come Tipo di log.
- Fai clic su Avanti.
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.
Fai clic su Avanti.
Controlla la nuova configurazione del feed di notizie 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:
- Nella pagina dei dettagli del feed, fai clic su Genera chiave segreta.
- Viene visualizzata una finestra di dialogo con la chiave segreta.
Copia e salva la chiave segreta in modo sicuro.
Ottieni l'URL dell'endpoint del feed
- Vai alla scheda Dettagli del feed.
- Nella sezione Endpoint Information (Informazioni sull'endpoint), copia l'URL endpoint del feed.
Il formato dell'URL è:
https://{region}-chronicle.googleapis.com/v1/{parent}/logs:importDove
{region}è la regione dell'istanza Google SecOps (ad esempious,europeoasia-southeast1) e{parent}è il percorso della risorsa nel formatoprojects/<PROJECT_ID>/locations/<LOCATION>/instances/<INSTANCE_ID>/logTypes/<LOG_TYPE>.Salva questo URL per i passaggi successivi.
Fai clic su Fine.
Crea una chiave API Google Cloud
Google SecOps richiede una chiave API per l'autenticazione. Crea una chiave API limitata nella console Google Cloud .
Crea la chiave API
- Vai alla pagina Credenziali della console Google Cloud.
- Seleziona il tuo progetto (il progetto associato alla tua istanza di Google SecOps).
- Fai clic su Crea credenziali > Chiave API.
- Viene creata una chiave API, che viene visualizzata in una finestra di dialogo.
- Fai clic su Modifica chiave API per limitare la chiave.
Limita la chiave API
Nella pagina delle impostazioni della chiave API:
- Nome: inserisci un nome descrittivo (ad esempio
Google SecOps GitGuardian Webhook API Key)
- Nome: inserisci un nome descrittivo (ad esempio
In Restrizioni delle API:
- Seleziona Limita chiave.
- Nel menu a discesa Seleziona API, cerca e seleziona API Google SecOps (o API Chronicle).
Fai clic su Salva.
Copia il valore della chiave API dal campo Chiave API nella parte superiore della pagina.
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://{region}-chronicle.googleapis.com/v1/{parent}/logs:import?key=AIzaSyD...
Crea un webhook personalizzato in GitGuardian
Per lo spazio di lavoro personale:
- Accedi alla dashboard di GitGuardian.
- Vai a Impostazioni > Workspace > Integrazioni > Destinazioni > Webhook personalizzato.
- Fai clic su Aggiungi un webhook personalizzato o Crea un nuovo webhook personalizzato.
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 di Google SecOps.
- (Facoltativo) Intestazione personalizzata: lascia vuoto questo campo, a meno che tu non debba specificare tag di ambiente o di servizio.
- Nome: inserisci un nome descrittivo (ad esempio
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
- ☑ Incident Severity changed
- ☑ 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
- Incidenti:
Fai clic su Crea o Salva.
GitGuardian invia un messaggio di prova per verificare che il webhook sia operativo.
Per l'area di lavoro aziendale:
- Accedi alla dashboard di GitGuardian.
Determina l'ambito del webhook:
- Per tutti gli incidenti nello spazio di lavoro: vai al team Tutti gli incidenti.
- Per incidenti di team specifici: vai al team che ti interessa.
Vai a Impostazioni > Workspace > Integrazioni > Destinazioni > Webhook personalizzato.
- In alternativa, dalla pagina del team, vai a Integrations > Custom webhook (Integrazioni > Webhook personalizzato).
Fai clic su Aggiungi un webhook personalizzato o Crea un nuovo webhook personalizzato.
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 di Google SecOps.
- (Facoltativo) Intestazione personalizzata: lascia vuoto questo campo, a meno che tu non debba specificare tag di ambiente o di servizio.
- Nome: inserisci un nome descrittivo (ad esempio
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
- ☑ Incident Severity changed
- ☑ 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
- Incidenti:
Fai clic su Crea o Salva.
GitGuardian invia un messaggio di prova per verificare che il webhook sia operativo.
Verifica la pubblicazione del webhook
- Nella dashboard di GitGuardian, vai alla configurazione del webhook personalizzato.
- Fai clic su Invia messaggio di prova o Testa webhook.
- GitGuardian invia un payload di esempio a Google SecOps.
- In Google SecOps, vai a Impostazioni > Gestione dei dati > Feed. Se utilizzi una piattaforma solo SIEM, vai a Impostazioni > Feed.
- Individua il feed GitGuardian e verifica che l'evento di test sia stato ricevuto.
Controlla che lo stato del feed sia Attivo con il timestamp di importazione recente.
Riferimento ai metodi di autenticazione
I feed webhook di Google SecOps supportano diversi metodi di autenticazione. Scegli il metodo supportato dal tuo fornitore.
Metodo 1: parametri di query (consigliato per GitGuardian)
I webhook personalizzati di GitGuardian funzionano meglio con le credenziali aggiunte all'URL.
Formato dell'URL:
<ENDPOINT_URL>?key=<API_KEY>Esempio:
https://{region}-chronicle.googleapis.com/v1/{parent}/logs:import?key=AIzaSyD...Configurazione del webhook GitGuardian:
- URL: URL completo dell'endpoint 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 le 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 dei webhook utilizzando HMAC-SHA256 per garantire l'autenticità e impedire la manomissione.
Intestazioni della firma
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
- timestamp: valore dell'intestazione
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
Timestampimpedisce gli attacchi di tipo replay. Se il timestamp corrente differisce da quello 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 degli incidenti.
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 |
Il feedback è stato inviato per questo incidente |
| Nuovo commento | incident_note_created |
È stata creata una nuova nota per questo incidente |
Struttura del payload di esempio
Tutti i payload dei 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 (query al secondo) max | 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: archivia il token di firma in modo sicuro e non eseguirne mai il commit nel codice sorgente.
- Monitoraggio: controlla regolarmente lo stato di recapito dei webhook nella dashboard di GitGuardian.
- Test: utilizza la funzionalità dei messaggi di test per verificare la configurazione del webhook prima dell'utilizzo in produzione.
Garanzie di consegna
Importante: l'invio dei webhook è un'operazione best effort e non è garantito. 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 | Conversione 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 | Imposta 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.