Raccogliere i log di Fivetran

Supportato in:

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

Fivetran è una piattaforma di integrazione dei dati che automatizza le pipeline di dati da varie origini ai data warehouse. Fivetran genera eventi operativi, inclusi eventi di sincronizzazione del connettore, eventi di trasformazione e modifiche dello stato della connessione. Questi eventi possono essere inviati a endpoint esterni tramite webhook in uscita per il monitoraggio, gli avvisi e l'analisi della sicurezza.

Prima di iniziare

Assicurati di soddisfare i seguenti prerequisiti:

  • Un'istanza Google SecOps
  • Un account Fivetran con autorizzazioni a livello di amministratore o account
  • Accesso a Google Cloud Console (per la creazione della chiave API)
  • Account Fivetran con piano Business Critical o Enterprise (per la funzionalità webhook)

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, Fivetran Events).
  5. Seleziona Webhook come Tipo di origine.
  6. Seleziona Fivetran come Tipo di log.
  7. Fai clic su Avanti.
  8. Specifica i valori per i seguenti parametri di input:
    • Delimitatore di divisione (facoltativo): lascia vuoto (ogni richiesta webhook contiene un singolo evento JSON)
    • 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 Google Cloud Console.

Crea la chiave API

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

Limitare la chiave API

  1. Nella pagina delle impostazioni Chiave API:
    • Nome: inserisci un nome descrittivo (ad esempio, Google SecOps Webhook API Key).
  2. In Limitazioni API:
    1. Seleziona Limita chiave.
    2. Nell'elenco 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 Fivetran

Costruisci 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 utilizzando l'API REST di Fivetran

I webhook Fivetran vengono configurati tramite l'API REST. Puoi creare webhook a livello di account (tutti i gruppi) o a livello di gruppo (gruppo di destinazione specifico).

Ottenere le credenziali API Fivetran

  1. Accedi al tuo account Fivetran.
  2. Fai clic sul tuo nome utente nell'angolo in alto a destra.
  3. Vai a Impostazioni account > Configurazione API.
  4. Se non hai una chiave API:
    1. Fai clic su Genera chiave API.
    2. Copia e salva in modo sicuro la chiave API e il secret API.

Creare un webhook a livello di account

Utilizza questo metodo per ricevere eventi da tutti i connettori in tutti i gruppi del tuo account.

  1. Apri un terminale o un client API.

  2. Crea il webhook utilizzando il seguente comando curl:

    curl -X POST https://api.fivetran.com/v1/webhooks/account \
    -u "API_KEY:API_SECRET" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{
        "url": "https://malachiteingestion-pa.googleapis.com/v2/unstructuredlogentries:batchCreate?key=YOUR_SECOPS_API_KEY",
        "events": [
            "sync_start",
            "sync_end",
            "transformation_start",
            "transformation_succeeded",
            "transformation_failed",
            "connection_successful",
            "connection_failure",
            "create_connector",
            "pause_connector",
            "resume_connector",
            "edit_connector",
            "delete_connector",
            "force_update_connector",
            "resync_connector",
            "resync_table"
        ],
        "active": true,
        "secret": "YOUR_SECOPS_SECRET_KEY"
    }'

  3. Sostituisci i seguenti valori:

    • API_KEY: la tua chiave API Fivetran
    • API_SECRET: il tuo API secret di Fivetran
    • YOUR_SECOPS_API_KEY: la chiave API Google Cloud creata in precedenza
    • YOUR_SECOPS_SECRET_KEY: La chiave segreta di Google SecOps creata durante la creazione del feed

  4. La risposta conterrà l'ID webhook:

    {
    "code": "Success",
    "message": "Operation performed.",
    "data": {
        "id": "webhook_abc123",
        "type": "account",
        "url": "https://malachiteingestion-pa.googleapis.com/...",
        "events": ["sync_start", "sync_end", ...],
        "active": true,
        "secret": "******",
        "created_at": "2025-01-15T10:30:00Z",
        "created_by": "user_id"
    }
}

  5. Salva l'ID webhook per riferimento futuro.

(Facoltativo) Crea un webhook a livello di gruppo

Utilizza questo metodo per ricevere eventi dai connettori in un gruppo di destinazioni specifico.

  1. Recupera l'ID gruppo:

    1. Accedi a Fivetran.
    2. Vai al gruppo di destinazione che vuoi monitorare.
    3. L'ID gruppo si trova nell'URL: https://fivetran.com/dashboard/groups/GROUP_ID

  2. Crea il webhook utilizzando il seguente comando curl:

    curl -X POST https://api.fivetran.com/v1/webhooks/group/GROUP_ID \
    -u "API_KEY:API_SECRET" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{
        "url": "https://malachiteingestion-pa.googleapis.com/v2/unstructuredlogentries:batchCreate?key=YOUR_SECOPS_API_KEY",
        "events": [
            "sync_start",
            "sync_end",
            "transformation_start",
            "transformation_succeeded",
            "transformation_failed",
            "connection_successful",
            "connection_failure"
        ],
        "active": true,
        "secret": "YOUR_SECOPS_SECRET_KEY"
    }'

  3. Sostituisci GROUP_ID con l'ID del gruppo di destinazione.

Eventi webhook disponibili

Seleziona gli eventi che vuoi monitorare:

Evento Descrizione
sync_start Sincronizzazione del connettore avviata
sync_end Sincronizzazione del connettore completata
transformation_start Trasformazione avviata
transformation_succeeded Trasformazione completata
transformation_failed Trasformazione non riuscita
connection_successful Test della connessione riuscito
connection_failure Test di connessione non riuscito
create_connector Nuovo connettore creato
pause_connector Connettore in pausa
resume_connector Connettore ripreso
edit_connector Configurazione del connettore modificata
delete_connector Connettore eliminato
force_update_connector Aggiornamento forzato del connettore attivato
resync_connector Risincronizzazione del connettore attivata
resync_table Risincronizzazione della tabella attivata

Testare il webhook

  1. Testa il webhook utilizzando l'API Fivetran:

    curl -X POST https://api.fivetran.com/v1/webhooks/WEBHOOK_ID/test \
    -u "API_KEY:API_SECRET" \
    -H "Accept: application/json"

  2. Sostituisci WEBHOOK_ID con l'ID webhook della risposta di creazione.

  3. Fivetran invierà un evento di test a Google SecOps.

  4. Verifica l'evento in Google SecOps:

    1. Vai a Impostazioni SIEM > Feed.
    2. Fai clic sul feed Fivetran.
    3. Vai alla scheda Log.
    4. Verifica che sia stato ricevuto un evento di test.

Formato payload webhook

  • Fivetran invia eventi webhook nel seguente formato JSON:

    {
    "event": "sync_end",
    "created": "2025-01-15T10:30:00.386Z",
    "connector_type": "salesforce",
    "connector_id": "mystified_presiding",
    "connector_name": "Salesforce Production",
    "sync_id": "abc123-def456-ghi789",
    "destination_group_id": "deck_enjoy",
    "data": {
        "status": "SUCCESSFUL"
    }
}

Autenticazione webhook

Fivetran firma i payload webhook utilizzando HMAC SHA-256 con il secret che hai fornito. La firma viene inviata nell'intestazione X-Fivetran-Signature-256.

Google SecOps convalida automaticamente la firma utilizzando la chiave segreta configurata durante la creazione del feed.

Comportamento di nuovi tentativi del webhook

Fivetran esegue automaticamente nuovi tentativi per i webhook non riusciti:

Riprova Tempo dopo il tentativo iniziale
Tentativo iniziale 0 minuti
1° tentativo 6 minuti
2° tentativo 27 minuti
3° tentativo 1 ora e 45 minuti
4° tentativo 6 ore e 25 minuti
5° tentativo 23 ore e 13 minuti
  • Fivetran riprova per un massimo di 24 ore.
  • I webhook hanno un timeout di 10 secondi.
  • I webhook vengono disattivati automaticamente dopo 3 giorni di errori costanti.

Gestisci webhook

Elenca tutti i webhook

  • bash curl -X GET https://api.fivetran.com/v1/webhooks \ -u "API_KEY:API_SECRET" \ -H "Accept: application/json"

Visualizzare i dettagli del webhook

  • bash curl -X GET https://api.fivetran.com/v1/webhooks/WEBHOOK_ID \ -u "API_KEY:API_SECRET" \ -H "Accept: application/json"

Aggiorna webhook

  • bash curl -X PATCH https://api.fivetran.com/v1/webhooks/WEBHOOK_ID \ -u "API_KEY:API_SECRET" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "active": true, "events": ["sync_start", "sync_end"] }'

Elimina webhook

  • bash curl -X DELETE https://api.fivetran.com/v1/webhooks/WEBHOOK_ID \ -u "API_KEY:API_SECRET" \ -H "Accept: application/json"

Riferimento ai metodi di autenticazione

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

Fivetran non supporta le intestazioni HTTP personalizzate per i webhook in uscita. Utilizza parametri di ricerca per trasmettere le credenziali.

  • Formato dell'URL:

    <ENDPOINT_URL>?key=<API_KEY>

    Esempio:

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

    Autenticazione:

    • Chiave API nel parametro di query dell'URL
    • Chiave segreta convalidata tramite la firma HMAC nell'intestazione X-Fivetran-Signature-256

Metodo 2: intestazioni personalizzate (non supportato da Fivetran)

I webhook in uscita di Fivetran non supportano le intestazioni HTTP personalizzate. Utilizza il metodo 1.

Limiti e best practice per i webhook

Limiti per le richieste

Limite Valore
Dimensioni massime della richiesta 4 MB
QPS max (query al secondo) 15.000
Timeout richieste 10 secondi (Fivetran) / 30 secondi (Google SecOps)
Comportamento di ripetizione Automatico con backoff esponenziale

Best practice

  • Iscriviti solo agli eventi necessari per ridurre al minimo le richieste HTTP.
  • Monitora lo stato di consegna dei webhook nella dashboard di Fivetran.
  • Configura gli avvisi per la disattivazione dei webhook.
  • Utilizza i webhook a livello di account per il monitoraggio centralizzato.
  • Utilizza i webhook a livello di gruppo per il monitoraggio di destinazioni specifiche.
  • Rivedi e aggiorna regolarmente gli abbonamenti agli eventi.

Risoluzione dei problemi

La creazione del webhook non riesce

Errore: richiesta non valida HTTP 400 durante la creazione del webhook.

Causa: l'endpoint Google SecOps non è raggiungibile o restituisce uno stato diverso da 2xx.

Soluzione:

  1. Verifica che l'URL dell'endpoint Google SecOps sia corretto.
  2. Verifica che la chiave API sia valida e abbia accesso all'API Google SecOps.

  3. Testa manualmente l'endpoint:

    curl -X POST "https://malachiteingestion-pa.googleapis.com/v2/unstructuredlogentries:batchCreate?key=YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -H "x-chronicle-auth: YOUR_SECRET_KEY" \
    -d '{"test": "event"}'

  4. Crea il webhook con "active": false per saltare la convalida iniziale, poi attivalo in un secondo momento.

Webhook disattivato

Causa: il webhook non è riuscito a funzionare in modo coerente per più di 3 giorni.

Soluzione:

  1. Verifica che il feed Google SecOps sia attivo e integro.
  2. Controlla la presenza di errori nei log dei feed di Google SecOps.
  3. Verifica che la chiave API e la chiave segreta siano ancora valide.

  4. Riattiva il webhook:

    curl -X PATCH https://api.fivetran.com/v1/webhooks/WEBHOOK_ID \
    -u "API_KEY:API_SECRET" \
    -H "Content-Type: application/json" \
    -d '{"active": true}'

Eventi non visualizzati in Google SecOps

Causa:gli eventi vengono inviati, ma non importati.

Soluzione:

  1. Vai a Impostazioni SIEM > Feed in Google SecOps.
  2. Fai clic sul feed Fivetran.
  3. Vai alla scheda Log.
  4. Controlla la presenza di errori di importazione.
  5. Verifica che il tipo di log sia impostato su Fivetran.
  6. Verifica che la chiave segreta corrisponda a quella configurata nel webhook.

La convalida della firma HMAC non riesce

Causa: mancata corrispondenza della chiave segreta.

Soluzione:

  1. Verifica che la chiave segreta nel feed Google SecOps corrisponda a quella utilizzata nella creazione del webhook.
  2. Se necessario, rigenera la chiave segreta di Google SecOps.

  3. Aggiorna il webhook Fivetran con il nuovo secret:

    curl -X PATCH https://api.fivetran.com/v1/webhooks/WEBHOOK_ID \
    -u "API_KEY:API_SECRET" \
    -H "Content-Type: application/json" \
    -d '{"secret": "NEW_SECOPS_SECRET_KEY"}'

Tabella di mappatura UDM

Campo log Mappatura UDM Logic
jsonPayload.connector_id additional.connector_id Valore copiato direttamente
jsonPayload.connector_type additional.connector_type Valore copiato direttamente
jsonPayload.data.executionTime additional.executionTime Convertito in stringa
insertId additional.insertId Valore copiato se non è vuoto
labels.levelName additional.levelName Valore copiato se non è vuoto
labels.levelValue additional.levelValue Valore copiato se non è vuoto
jsonPayload.data.number additional.number Convertito in stringa
jsonPayload.data.query additional.query Valore copiato direttamente
resource.type additional.type Valore copiato se non è vuoto
metadata.event_type Impostato su "RESOURCE_READ" se has_principal_user == "true" e has_target == "true", altrimenti se has_principal_user == "true" allora "USER_COMMUNICATION", altrimenti se has_principal == "true" allora "STATUS_UPDATE", altrimenti "GENERIC_EVENT"
jsonPayload.event metadata.product_event_type Valore copiato direttamente
jsonPayload.sync_id metadata.product_log_id Valore copiato direttamente
jsonPayload.connector_name principal.asset.hostname Valore copiato direttamente
jsonPayload.connector_name principal.hostname Valore copiato direttamente
resource.labels.email_id principal.user.email_addresses Unito se corrisponde a "^.+@.+$"
resource.labels.project_id principal.user.product_object_id Valore copiato se non è vuoto
resource.labels.unique_id principal.user.userid Valore copiato se non presente in ["", "null", " "]
gravità security_result.severity Imposta su "INFORMATIONAL" se corrisponde a "INFO"
logName target.resource.name Valore copiato se non è vuoto
target.resource.type Impostato su "DATABASE"
metadata.product_name Impostato su "FIVETRAN"
metadata.vendor_name Impostato su "FIVETRAN"

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