Collecter les journaux Fivetran

Compatible avec :

Ce document explique comment configurer Fivetran pour envoyer des journaux à Google Security Operations à l'aide de webhooks.

Fivetran est une plate-forme d'intégration de données qui automatise les pipelines de données de diverses sources vers les entrepôts de données. Fivetran génère des événements opérationnels, y compris des événements de synchronisation de connecteur, des événements de transformation et des changements d'état de connexion. Ces événements peuvent être envoyés à des points de terminaison externes via des webhooks sortants pour la surveillance, les alertes et l'analyse de la sécurité.

Avant de commencer

Assurez-vous de remplir les conditions préalables suivantes :

  • Une instance Google SecOps
  • Un compte Fivetran avec des autorisations d'administrateur ou au niveau du compte
  • Accès à la Google Cloud Console (pour créer une clé API)
  • Compte Fivetran avec un forfait Business Critical ou Enterprise (pour la fonctionnalité de webhook)

Créer un flux de webhook dans Google SecOps

Créer le flux

  1. Accédez à Paramètres SIEM> Flux.
  2. Cliquez sur Add New Feed (Ajouter un flux).
  3. Sur la page suivante, cliquez sur Configurer un seul flux.
  4. Dans le champ Nom du flux, saisissez un nom pour le flux (par exemple, Fivetran Events).
  5. Sélectionnez Webhook comme type de source.
  6. Sélectionnez Fivetran comme type de journal.
  7. Cliquez sur Suivant.
  8. Spécifiez les valeurs des paramètres d'entrée suivants :
    • Délimiteur de fractionnement (facultatif) : laissez ce champ vide (chaque requête de webhook contient un seul événement JSON).
    • Espace de noms de l'élément : espace de noms de l'élément
    • Libellés d'ingestion : libellé à appliquer aux événements de ce flux
  9. Cliquez sur Suivant.
  10. Vérifiez la configuration de votre nouveau flux sur l'écran Finaliser, puis cliquez sur Envoyer.

Générer et enregistrer une clé secrète

Après avoir créé le flux, vous devez générer une clé secrète pour l'authentification :

  1. Sur la page d'informations sur le flux, cliquez sur Générer une clé secrète.
  2. Une boîte de dialogue affiche la clé secrète.
  3. Copiez et enregistrez la clé secrète de manière sécurisée.

Obtenir l'URL du point de terminaison du flux

  1. Accédez à l'onglet Détails du flux.
  2. Dans la section Endpoint Information (Informations sur le point de terminaison), copiez l'URL du point de terminaison du flux.

  3. Le format d'URL est le suivant :

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

    ou

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

  4. Enregistrez cette URL pour les étapes suivantes.

  5. Cliquez sur OK.

Créer une clé API Google Cloud

Google SecOps nécessite une clé API pour l'authentification. Créez une clé API restreinte dans la Google Cloud Console.

Créer la clé API

  1. Accédez à la page Identifiants de la console Google Cloud.
  2. Sélectionnez votre projet (celui associé à votre instance Google SecOps).
  3. Cliquez sur Créer des identifiants > Clé API. Une clé API est créée et affichée dans une boîte de dialogue.
  4. Cliquez sur Modifier la clé API pour la restreindre.

Restreindre la clé API

  1. Sur la page des paramètres de la clé API :
    • Nom : saisissez un nom descriptif (par exemple, Google SecOps Webhook API Key).
  2. Sous Restrictions relatives aux API :
    1. Sélectionnez Restreindre la clé.
    2. Dans la liste Sélectionner des API, recherchez et sélectionnez API Google SecOps (ou API Chronicle).
  3. Cliquez sur Enregistrer.
  4. Copiez la valeur de la clé API dans le champ Clé API en haut de la page.
  5. Enregistrez la clé API de manière sécurisée.

Configurer le webhook Fivetran

Créer l'URL du webhook

  • Combinez l'URL du point de terminaison Google SecOps et la clé API :

    <ENDPOINT_URL>?key=<API_KEY>

    Exemple :

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

Créer un webhook à l'aide de l'API REST Fivetran

Les Webhooks Fivetran sont configurés via l'API REST. Vous pouvez créer des webhooks au niveau du compte (tous les groupes) ou au niveau du groupe (groupe de destinations spécifique).

Obtenir les identifiants de l'API Fivetran

  1. Connectez-vous à votre compte Fivetran.
  2. Cliquez sur votre nom d'utilisateur en haut à droite.
  3. Accédez à Paramètres du compte> Configuration de l'API.
  4. Si vous ne disposez pas de clé API :
    1. Cliquez sur Générer une clé API.
    2. Copiez et enregistrez la clé API et le secret de l'API de manière sécurisée.

Créer un webhook au niveau du compte

Utilisez cette méthode pour recevoir des événements de tous les connecteurs et de tous les groupes de votre compte.

  1. Ouvrez un terminal ou un client API.

  2. Créez le webhook à l'aide de la commande curl suivante :

    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. Remplacez les valeurs suivantes :

    • API_KEY : votre clé API Fivetran
    • API_SECRET : code secret de votre API Fivetran
    • YOUR_SECOPS_API_KEY : clé API Google Cloud créée précédemment
    • YOUR_SECOPS_SECRET_KEY : clé secrète Google SecOps issue de la création du flux

  4. La réponse contiendra l'ID du 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. Enregistrez l'ID du webhook pour référence ultérieure.

Créer un webhook au niveau du groupe (facultatif)

Utilisez cette méthode pour recevoir des événements provenant de connecteurs dans un groupe de destinations spécifique.

  1. Obtenez l'ID de votre groupe :

    1. Connectez-vous à Fivetran.
    2. Accédez au groupe de destinations que vous souhaitez surveiller.
    3. L'ID du groupe se trouve dans l'URL : https://fivetran.com/dashboard/groups/GROUP_ID

  2. Créez le webhook à l'aide de la commande curl suivante :

    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. Remplacez GROUP_ID par l'ID de votre groupe de destinations.

Événements de webhook disponibles

Sélectionnez les événements que vous souhaitez surveiller :

Événement Description
sync_start Synchronisation du connecteur démarrée
sync_end Synchronisation du connecteur terminée
transformation_start Transformation démarrée
transformation_succeeded La transformation a bien été effectuée
transformation_failed Échec de la transformation
connection_successful Test de connexion réussi
connection_failure Échec du test de connexion
create_connector Connecteur créé
pause_connector Connecteur mis en veille
resume_connector Connecteur réactivé
edit_connector Configuration du connecteur modifiée
delete_connector Connecteur supprimé
force_update_connector Mise à jour forcée du connecteur déclenchée
resync_connector Resynchronisation du connecteur déclenchée
resync_table Resynchronisation de la table déclenchée

Tester le webhook

  1. Testez le webhook à l'aide de 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. Remplacez WEBHOOK_ID par l'ID du webhook issu de la réponse de création.

  3. Fivetran enverra un événement test à Google SecOps.

  4. Vérifiez l'événement dans Google SecOps :

    1. Accédez à Paramètres SIEM> Flux.
    2. Cliquez sur votre flux Fivetran.
    3. Accédez à l'onglet Journaux.
    4. Vérifiez qu'un événement de test a été reçu.

Format de la charge utile du webhook

  • Fivetran envoie des événements webhook au format JSON suivant :

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

Authentification de webhook

Fivetran signe les charges utiles de webhook à l'aide de HMAC-SHA256 avec le secret que vous avez fourni. La signature est envoyée dans l'en-tête X-Fivetran-Signature-256.

Google SecOps valide automatiquement la signature à l'aide de la clé secrète configurée lors de la création du flux.

Comportement de nouvelle tentative du webhook

Fivetran relance automatiquement les webhooks ayant échoué :

Réessayer Délai après la première tentative
Première tentative 0 minute
1re tentative 6 minutes
2e tentative 27 minutes
3e tentative 1 heure 45 minutes
4e tentative 6 heures 25 minutes
5e tentative 23 heures 13 minutes
  • Fivetran réessaie pendant 24 heures maximum.
  • Les webhooks ont un délai avant expiration de 10 secondes.
  • Les Webhooks sont automatiquement désactivés après trois jours d'échecs consécutifs.

Gérer les webhooks

Lister tous les webhooks

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

Obtenir les détails du webhook

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

Mettre à jour le 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"] }'

Supprimer le webhook

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

Référence des méthodes d'authentification

Les flux de webhook Google SecOps sont compatibles avec plusieurs méthodes d'authentification. Choisissez la méthode acceptée par votre fournisseur.

Fivetran n'est pas compatible avec les en-têtes HTTP personnalisés pour les Webhooks sortants. Utilisez des paramètres de requête pour transmettre les identifiants.

  • Format de l'URL :

    <ENDPOINT_URL>?key=<API_KEY>

    Exemple :

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

    Authentification :

    • Clé API dans le paramètre de requête d'URL
    • Clé secrète validée via la signature HMAC dans l'en-tête X-Fivetran-Signature-256

Méthode 2 : En-têtes personnalisés (non compatibles avec Fivetran)

Les Webhooks sortants Fivetran ne sont pas compatibles avec les en-têtes HTTP personnalisés. Utilisez plutôt la méthode 1.

Limites et bonnes pratiques concernant les webhooks

Limites de requêtes

Limite Valeur
Taille maximale des requêtes 4 Mo
RPS (requêtes par seconde) max. 15 000
Délai avant expiration de la requête 10 secondes (Fivetran) / 30 secondes (Google SecOps)
Comportement de nouvelle tentative Automatique avec intervalle exponentiel entre les tentatives

Bonnes pratiques

  • Abonnez-vous uniquement aux événements dont vous avez besoin pour minimiser les requêtes HTTP.
  • Surveillez l'état de la diffusion des webhooks dans le tableau de bord Fivetran.
  • Configurer des alertes pour la désactivation des webhooks.
  • Utilisez des Webhooks au niveau du compte pour une surveillance centralisée.
  • Utilisez des Webhooks au niveau du groupe pour surveiller des destinations spécifiques.
  • Examinez et mettez à jour régulièrement les abonnements aux événements.

Dépannage

Échec de la création du webhook

Erreur : requête incorrecte HTTP 400 lors de la création du webhook.

Cause : Le point de terminaison Google SecOps n'est pas accessible ou renvoie un état autre que 2xx.

Solution :

  1. Vérifiez que l'URL du point de terminaison Google SecOps est correcte.
  2. Vérifiez que la clé API est valide et qu'elle permet d'accéder à l'API Google SecOps.

  3. Testez le point de terminaison manuellement :

    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. Créez le webhook avec "active": false pour ignorer la validation initiale, puis activez-le ultérieurement.

Le webhook est désactivé

Cause : le webhook a échoué de manière répétée pendant plus de trois jours.

Solution :

  1. Vérifiez que le flux Google SecOps est actif et en bon état.
  2. Recherchez les erreurs dans les journaux de flux Google SecOps.
  3. Vérifiez que la clé API et la clé secrète sont toujours valides.

  4. Réactivez le 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}'

Événements qui n'apparaissent pas dans Google SecOps

Cause : Des événements sont envoyés, mais ne sont pas ingérés.

Solution :

  1. Accédez à Paramètres SIEM> Flux dans Google SecOps.
  2. Cliquez sur votre flux Fivetran.
  3. Accédez à l'onglet Journaux.
  4. Vérifiez si des erreurs d'ingestion se sont produites.
  5. Vérifiez que le type de journal est défini sur Fivetran.
  6. Vérifiez que la clé secrète correspond à celle configurée dans le webhook.

Échec de la validation de la signature HMAC

Cause : la clé secrète ne correspond pas.

Solution :

  1. Vérifiez que la clé secrète du flux Google SecOps correspond à celle utilisée lors de la création du webhook.
  2. Si nécessaire, régénérez la clé secrète Google SecOps.

  3. Mettez à jour le webhook Fivetran avec le nouveau 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"}'

Table de mappage UDM

Champ du journal Mappage UDM Logique
jsonPayload.connector_id additional.connector_id Valeur copiée directement
jsonPayload.connector_type additional.connector_type Valeur copiée directement
jsonPayload.data.executionTime additional.executionTime Converti en chaîne
insertId additional.insertId Valeur copiée si elle n'est pas vide
labels.levelName additional.levelName Valeur copiée si elle n'est pas vide
labels.levelValue additional.levelValue Valeur copiée si elle n'est pas vide
jsonPayload.data.number additional.number Converti en chaîne
jsonPayload.data.query additional.query Valeur copiée directement
resource.type additional.type Valeur copiée si elle n'est pas vide
metadata.event_type Défini sur "RESOURCE_READ" si has_principal_user == "true" et has_target == "true", sur "USER_COMMUNICATION" si has_principal_user == "true", sur "STATUS_UPDATE" si has_principal == "true", ou sur "GENERIC_EVENT" dans les autres cas
jsonPayload.event metadata.product_event_type Valeur copiée directement
jsonPayload.sync_id metadata.product_log_id Valeur copiée directement
jsonPayload.connector_name principal.asset.hostname Valeur copiée directement
jsonPayload.connector_name principal.hostname Valeur copiée directement
resource.labels.email_id principal.user.email_addresses Fusionné si la valeur correspond à "^.+@.+$"
resource.labels.project_id principal.user.product_object_id Valeur copiée si elle n'est pas vide
resource.labels.unique_id principal.user.userid Valeur copiée si elle n'est pas dans ["", "null", " "]
de gravité, security_result.severity Définissez la valeur sur "INFORMATIONAL" si elle correspond à "INFO".
logName target.resource.name Valeur copiée si elle n'est pas vide
target.resource.type Défini sur "DATABASE"
metadata.product_name Définissez-le sur "FIVETRAN".
metadata.vendor_name Définissez-le sur "FIVETRAN".

Vous avez encore besoin d'aide ? Obtenez des réponses de membres de la communauté et de professionnels Google SecOps.