Coletar registros do Fivetran

Compatível com:

Este documento explica como configurar o Fivetran para enviar registros ao Google Security Operations usando webhooks.

O Fivetran é uma plataforma de integração de dados que automatiza pipelines de dados de várias fontes para data warehouses. O Fivetran gera eventos operacionais, incluindo eventos de sincronização de conector, eventos de transformação e mudanças no status da conexão. Esses eventos podem ser enviados a endpoints externos por webhooks de saída para monitoramento, alertas e análise de segurança.

Antes de começar

Verifique se você atende aos seguintes pré-requisitos:

  • Uma instância do Google SecOps
  • Uma conta do Fivetran com permissões de administrador ou no nível da conta
  • Acesso ao console do Google Cloud (para criação de chaves de API)
  • Conta do Fivetran no plano Business Critical ou Enterprise (para funcionalidade de webhook)

Criar um feed de webhook no Google SecOps

Criar o feed

  1. Acesse Configurações do SIEM > Feeds.
  2. Clique em Adicionar novo feed.
  3. Na próxima página, clique em Configurar um único feed.
  4. No campo Nome do feed, insira um nome para o feed (por exemplo, Fivetran Events).
  5. Selecione Webhook como o Tipo de origem.
  6. Selecione Fivetran como o Tipo de registro.
  7. Clique em Próxima.
  8. Especifique valores para os seguintes parâmetros de entrada:
    • Delimitador de divisão (opcional): deixe em branco (cada solicitação de webhook contém um único evento JSON)
    • Namespace do recurso: o namespace do recurso.
    • Rótulos de ingestão: o rótulo a ser aplicado aos eventos deste feed
  9. Clique em Próxima.
  10. Revise a nova configuração do feed na tela Finalizar e clique em Enviar.

Gerar e salvar a chave secreta

Depois de criar o feed, gere uma chave secreta para autenticação:

  1. Na página de detalhes do feed, clique em Gerar chave secreta.
  2. Uma caixa de diálogo mostra a chave secreta.
  3. Copie e salve a chave secreta com segurança.

Receber o URL do endpoint do feed

  1. Acesse a guia Detalhes do feed.
  2. Na seção Informações do endpoint, copie o URL do endpoint do feed.

  3. O formato do URL é:

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

    ou

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

  4. Salve esse URL para as próximas etapas.

  5. Clique em Concluído.

Criar chave de API do Google Cloud

O Google SecOps exige uma chave de API para autenticação. Crie uma chave de API restrita no console do Google Cloud.

Criar a chave de API

  1. Acesse a página "Credenciais" do Console do Google Cloud.
  2. Selecione seu projeto (o projeto associado à sua instância do Google SecOps).
  3. Clique em Criar credenciais > Chave de API. Uma chave de API é criada e exibida em uma caixa de diálogo.
  4. Clique em Editar chave de API para restringir a chave.

Restringir a chave de API

  1. Na página de configurações da chave de API:
    • Nome: insira um nome descritivo, por exemplo, Google SecOps Webhook API Key.
  2. Em Restrições de API:
    1. Selecione Restringir chave.
    2. Na lista Selecionar APIs, pesquise e selecione API Google SecOps (ou API Chronicle).
  3. Clique em Salvar.
  4. Copie o valor da chave de API do campo Chave de API na parte de cima da página.
  5. Salve a chave de API com segurança.

Configurar o webhook do Fivetran

Criar o URL do webhook

  • Combine o URL do endpoint do Google SecOps e a chave de API:

    <ENDPOINT_URL>?key=<API_KEY>

    Exemplo:

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

Criar um webhook usando a API REST do Fivetran

Os webhooks do Fivetran são configurados pela API REST. É possível criar webhooks no nível da conta (todos os grupos) ou no nível do grupo (grupo de destino específico).

Receber credenciais da API Fivetran

  1. Faça login na sua conta do Fivetran.
  2. Clique no seu nome de usuário no canto superior direito.
  3. Acesse Configurações da conta > Configuração da API.
  4. Se você não tiver uma chave de API:
    1. Clique em Gerar chave de API.
    2. Copie e salve a chave de API e o segredo da API com segurança.

Criar um webhook no nível da conta

Use esse método para receber eventos de todos os conectores em todos os grupos da sua conta.

  1. Abra um terminal ou um cliente de API.

  2. Crie o webhook usando o seguinte 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. Substitua os seguintes valores:

    • API_KEY: sua chave de API do Fivetran
    • API_SECRET: sua chave secreta da API do Fivetran
    • YOUR_SECOPS_API_KEY: a chave de API do Google Cloud criada anteriormente.
    • YOUR_SECOPS_SECRET_KEY: a chave secreta do Google SecOps da criação do feed

  4. A resposta vai conter o ID do 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. Salve o ID do webhook para referência futura.

Criar um webhook no nível do grupo (opcional)

Use esse método para receber eventos de conectores em um grupo de destino específico.

  1. Consiga o ID do grupo:

    1. Faça login no Fivetran.
    2. Acesse o grupo de destino que você quer monitorar.
    3. O ID do grupo está no URL: https://fivetran.com/dashboard/groups/GROUP_ID

  2. Crie o webhook usando o seguinte 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. Substitua GROUP_ID pelo ID do grupo de destino.

Eventos de webhook disponíveis

Selecione os eventos que você quer monitorar:

Evento Descrição
sync_start A sincronização do conector foi iniciada
sync_end Sincronização do conector concluída
transformation_start Transformação iniciada
transformation_succeeded A transformação foi concluída
transformation_failed Falha na transformação
connection_successful Teste de conexão concluído
connection_failure Falha no teste de conexão
create_connector Novo conector criado
pause_connector Conector pausado
resume_connector O conector foi retomado
edit_connector Configuração do conector editada
delete_connector Conector excluído
force_update_connector Atualização forçada do conector acionada
resync_connector Resincronização do conector acionada
resync_table Resincronização da tabela acionada

Testar o webhook

  1. Teste o webhook usando a API Fivetran:

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

  2. Substitua WEBHOOK_ID pelo ID do webhook da resposta de criação.

  3. O Fivetran vai enviar um evento de teste para o Google SecOps.

  4. Verifique o evento no Google SecOps:

    1. Acesse Configurações do SIEM > Feeds.
    2. Clique no seu feed do Fivetran.
    3. Acesse a guia Registros.
    4. Verifique se um evento de teste foi recebido.

Formato do payload do webhook

  • O Fivetran envia eventos de webhook no seguinte 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"
    }
}

Autenticação de webhook

A Fivetran assina payloads de webhook usando HMAC SHA-256 com o segredo que você forneceu. A assinatura é enviada no cabeçalho X-Fivetran-Signature-256.

O Google SecOps valida automaticamente a assinatura usando a chave secreta configurada durante a criação do feed.

Comportamento de nova tentativa do webhook

O Fivetran repete automaticamente os webhooks com falha:

Tentar novamente Tempo após a tentativa inicial
Tentativa inicial 0 minutos
1ª nova tentativa 6 minutos
2ª tentativa 27 minutos
3ª tentativa 1 hora e 45 minutos
4ª tentativa 6 horas e 25 minutos
5ª tentativa 23 horas e 13 minutos
  • O Fivetran tenta novamente por até 24 horas.
  • Os webhooks têm um tempo limite de 10 segundos.
  • Os webhooks são desativados automaticamente após três dias de falhas consistentes.

Gerenciar webhooks

Listar todos os webhooks

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

Receber detalhes do webhook

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

Atualize o 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"] }'

Excluir webhook

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

Referência de métodos de autenticação

Os feeds de webhook do Google SecOps são compatíveis com vários métodos de autenticação. Escolha o método compatível com seu fornecedor.

O Fivetran não é compatível com cabeçalhos HTTP personalizados para webhooks de saída. Use parâmetros de consulta para transmitir credenciais.

  • Formato do URL:

    <ENDPOINT_URL>?key=<API_KEY>

    Exemplo:

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

    Autenticação:

    • Chave de API no parâmetro de consulta do URL
    • Chave secreta validada por uma assinatura HMAC no cabeçalho X-Fivetran-Signature-256

Método 2: cabeçalhos personalizados (não compatível com a Fivetran)

Os webhooks de saída do Fivetran não são compatíveis com cabeçalhos HTTP personalizados. Use o método 1.

Limites e práticas recomendadas de webhook

Limites de solicitações

Limite Valor
Tamanho máximo da solicitação 4 MB
QPS máximo (consultas por segundo) 15.000
Tempo limite da solicitação 10 segundos (Fivetran) / 30 segundos (Google SecOps)
Comportamento de repetição Automática com espera exponencial

Práticas recomendadas

  • Inscreva-se apenas nos eventos necessários para minimizar as solicitações HTTP.
  • Monitore o status de entrega do webhook no painel do Fivetran.
  • Configure alertas para a desativação do webhook.
  • Use webhooks no nível da conta para monitoramento centralizado.
  • Use webhooks no nível do grupo para monitoramento de destino específico.
  • Revise e atualize as inscrições em eventos regularmente.

Solução de problemas

Falha na criação do webhook

Erro:solicitação inválida HTTP 400 durante a criação do webhook.

Causa:o endpoint do Google SecOps não pode ser acessado ou retorna um status diferente de 2xx.

Solução:

  1. Verifique se o URL do endpoint do Google SecOps está correto.
  2. Verifique se a chave de API é válida e tem acesso à API Google SecOps.

  3. Teste o endpoint manualmente:

    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. Crie o webhook com "active": false para pular a validação inicial e ative-o mais tarde.

O webhook está desativado

Causa:o webhook falhou consistentemente por mais de três dias.

Solução:

  1. Verifique se o feed do Google SecOps está ativo e íntegro.
  2. Verifique se há erros nos registros de feed do Google SecOps.
  3. Verifique se a chave de API e a chave secreta ainda são válidas.

  4. Reative o 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}'

Os eventos não aparecem no Google SecOps

Causa:os eventos estão sendo enviados, mas não ingeridos.

Solução:

  1. Acesse Configurações do SIEM > Feeds no Google SecOps.
  2. Clique no seu feed do Fivetran.
  3. Acesse a guia Registros.
  4. Verifique se há erros de ingestão.
  5. Verifique se o tipo de registro está definido como Fivetran.
  6. Verifique se a chave secreta corresponde à configurada no webhook.

A validação da assinatura HMAC falha

Causa:incompatibilidade de chave secreta.

Solução:

  1. Verifique se a chave secreta no feed do Google SecOps corresponde à usada na criação do webhook.
  2. Regenere a chave secreta do Google SecOps, se necessário.

  3. Atualize o webhook do Fivetran com o novo 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"}'

Tabela de mapeamento do UDM

Campo de registro Mapeamento do UDM Lógica
jsonPayload.connector_id additional.connector_id Valor copiado diretamente
jsonPayload.connector_type additional.connector_type Valor copiado diretamente
jsonPayload.data.executionTime additional.executionTime Convertido em string
insertId additional.insertId Valor copiado se não estiver vazio
labels.levelName additional.levelName Valor copiado se não estiver vazio
labels.levelValue additional.levelValue Valor copiado se não estiver vazio
jsonPayload.data.number additional.number Convertido em string
jsonPayload.data.query additional.query Valor copiado diretamente
resource.type additional.type Valor copiado se não estiver vazio
metadata.event_type Definido como "RESOURCE_READ" se has_principal_user == "true" e has_target == "true". Caso contrário, se has_principal_user == "true", será "USER_COMMUNICATION". Se has_principal == "true", será "STATUS_UPDATE". Caso contrário, será "GENERIC_EVENT".
jsonPayload.event metadata.product_event_type Valor copiado diretamente
jsonPayload.sync_id metadata.product_log_id Valor copiado diretamente
jsonPayload.connector_name principal.asset.hostname Valor copiado diretamente
jsonPayload.connector_name principal.hostname Valor copiado diretamente
resource.labels.email_id principal.user.email_addresses Unido se corresponder a "^.+@.+$"
resource.labels.project_id principal.user.product_object_id Valor copiado se não estiver vazio
resource.labels.unique_id principal.user.userid Valor copiado se não estiver em ["", "null", " "]
gravidade, security_result.severity Defina como "INFORMATIONAL" se corresponder a "INFO"
logName target.resource.name Valor copiado se não estiver vazio
target.resource.type Definido como "DATABASE"
metadata.product_name Defina como "FIVETRAN".
metadata.vendor_name Defina como "FIVETRAN".

Precisa de mais ajuda? Receba respostas de membros da comunidade e profissionais do Google SecOps.