Coletar registros de isolamento do navegador da Web Proofpoint

Compatível com:

Este documento explica como ingerir registros de isolamento do navegador da Web do Proofpoint no Google Security Operations usando o Google Cloud Storage V2.

O isolamento do navegador da Web da Proofpoint é um serviço de isolamento de navegador remoto que protege os usuários contra ameaças baseadas na Web renderizando o conteúdo da Web em um ambiente de nuvem seguro, impedindo que códigos maliciosos cheguem ao endpoint. Ele fornece registros de atividade de navegação pela API Proofpoint TAP SIEM. O analisador extrai campos de dados de eventos de isolamento e os mapeia para o modelo de dados unificado (UDM), capturando classificações de URL, ações do usuário, disposições de segurança e metadados da sessão de navegação.

Antes de começar

Verifique se você tem os pré-requisitos a seguir:

  • Uma instância do Google SecOps
  • Um projeto do GCP com a API Storage do Cloud ativada
  • Permissões para criar e gerenciar intervalos do GCS
  • Permissões para gerenciar políticas do IAM em buckets do GCS
  • Permissões para criar serviços do Cloud Run, tópicos do Pub/Sub e jobs do Cloud Scheduler
  • Acesso privilegiado ao Proofpoint com credenciais da API TAP SIEM (entidade de serviço e chave secreta da API)

Criar um bucket do Google Cloud Storage

  1. Acesse o Console do Google Cloud.
  2. Selecione ou crie um projeto.
  3. No menu de navegação, acesse Cloud Storage > Buckets.
  4. Clique em Criar bucket.

  5. Informe os seguintes detalhes de configuração:

    Configuração Valor
    Nomeie seu bucket Insira um nome globalmente exclusivo, por exemplo, proofpoint-wbi-logs.
    Tipo de local Escolha de acordo com suas necessidades (região, birregional, multirregional)
    Local Selecione o local (por exemplo, us-central1).
    Classe de armazenamento Padrão (recomendado para registros acessados com frequência)
    Controle de acesso Uniforme (recomendado)
    Ferramentas de proteção Opcional: ativar o controle de versões de objetos ou a política de retenção

  6. Clique em Criar.

Coletar credenciais da API SIEM do Proofpoint TAP

Receber credenciais de API

  1. Faça login no painel do Proofpoint TAP.
  2. Acesse Configurações > Aplicativos conectados.
  3. Clique em Criar nova credencial ou use uma credencial de API do SIEM.

  4. Copie e armazene com segurança as seguintes credenciais:

    • Principal de serviço: copie esse valor.
    • Chave secreta da API: copie esse valor.

Verifique as permissões

Para verificar se as credenciais da API têm as permissões necessárias:

  1. Faça login no painel do Proofpoint TAP.
  2. Acesse Configurações > Aplicativos conectados.
  3. Confirme se a credencial está listada e tem o status Ativa.
  4. Verifique se a credencial tem acesso à API SIEM ativado.

Testar o acesso à API

  • Teste suas credenciais antes de prosseguir com a integração:

    # Replace with your actual credentials
SERVICE_PRINCIPAL="<your-service-principal>"
API_SECRET="<your-api-secret>"

# Test TAP SIEM API access - fetch events from last hour
curl -v -u "${SERVICE_PRINCIPAL}:${API_SECRET}" \
  "https://tap-api-v2.proofpoint.com/v2/siem/all?format=json&sinceSeconds=3600"

Criar uma conta de serviço para a função do Cloud Run

A função do Cloud Run precisa de uma conta de serviço com permissões para gravar no bucket do GCS e ser invocada pelo Pub/Sub.

Criar conta de serviço

  1. No console do GCP, acesse IAM e administrador > Contas de serviço.
  2. Clique em Criar conta de serviço.
  3. Informe os seguintes detalhes de configuração:
    • Nome da conta de serviço: insira proofpoint-wbi-collector-sa
    • Descrição da conta de serviço: insira Service account for Cloud Run function to collect Proofpoint Web Browser Isolation logs
  4. Clique em Criar e continuar.
  5. Na seção Conceder acesso a essa conta de serviço ao projeto, adicione os seguintes papéis:
    1. Clique em Selecionar papel.
    2. Pesquise e selecione Administrador de objetos do Storage.
    3. Clique em + Adicionar outro papel.
    4. Pesquise e selecione Invocador do Cloud Run.
    5. Clique em + Adicionar outro papel.
    6. Pesquise e selecione Invocador de funções do Cloud.
  6. Clique em Continuar.
  7. Clique em Concluído.

Essas funções são necessárias para:

  • Administrador de objetos do Storage: grava registros no bucket do GCS e gerencia arquivos de estado.
  • Invocador do Cloud Run: permite que o Pub/Sub invoque a função.
  • Invocador do Cloud Functions: permite a invocação de funções.

Conceder permissões do IAM no bucket do GCS

Conceda permissões de gravação à conta de serviço no bucket do GCS:

  1. Acesse Cloud Storage > Buckets.
  2. Clique no nome do bucket (por exemplo, proofpoint-wbi-logs).
  3. Acesse a guia Permissões.
  4. Clique em Conceder acesso.
  5. Informe os seguintes detalhes de configuração:
    • Adicionar principais: insira o e-mail da conta de serviço (por exemplo, proofpoint-wbi-collector-sa@PROJECT_ID.iam.gserviceaccount.com).
    • Atribuir papéis: selecione Administrador de objetos do Storage.
  6. Clique em Salvar.

Criar um tópico do Pub/Sub

Crie um tópico do Pub/Sub em que o Cloud Scheduler vai publicar e a função do Cloud Run vai se inscrever.

  1. No Console do GCP, acesse Pub/Sub > Tópicos.
  2. Selecione Criar tópico.
  3. Informe os seguintes detalhes de configuração:
    • ID do tópico: insira proofpoint-wbi-trigger
    • Não mude as outras configurações.
  4. Clique em Criar.

Criar uma função do Cloud Run para coletar registros

A função do Cloud Run será acionada por mensagens do Pub/Sub do Cloud Scheduler para buscar eventos de isolamento do navegador na API do SIEM do Proofpoint TAP e gravá-los no GCS.

  1. No console do GCP, acesse o Cloud Run.
  2. Clique em Criar serviço.
  3. Selecione Função (use um editor in-line para criar uma função).

  4. Na seção Configurar, forneça os seguintes detalhes de configuração:

    Configuração Valor
    Nome do serviço proofpoint-wbi-collector
    Região Selecione a região correspondente ao seu bucket do GCS (por exemplo, us-central1).
    Ambiente de execução Selecione Python 3.12 ou uma versão mais recente.

  5. Na seção Gatilho (opcional):

    1. Clique em + Adicionar gatilho.
    2. Selecione Cloud Pub/Sub.
    3. Em Selecionar um tópico do Cloud Pub/Sub, escolha o tópico do Pub/Sub (proofpoint-wbi-trigger).
    4. Clique em Salvar.

  6. Na seção Autenticação:

    1. Selecione Exigir autenticação.
    2. Confira o Identity and Access Management (IAM).

  7. Role a tela para baixo e abra Contêineres, rede, segurança.

  8. Acesse a guia Segurança:

    • Conta de serviço: selecione a conta de serviço (proofpoint-wbi-collector-sa).

  9. Acesse a guia Contêineres:

    1. Clique em Variáveis e secrets.
    2. Clique em + Adicionar variável para cada variável de ambiente:
    Nome da variável Valor de exemplo Descrição
    GCS_BUCKET proofpoint-wbi-logs Nome do bucket do GCS
    GCS_PREFIX wbi-logs Prefixo para arquivos de registro
    STATE_KEY wbi-logs/state.json Caminho do arquivo de estado
    SERVICE_PRINCIPAL your-service-principal Principal de serviço do Proofpoint TAP
    API_SECRET your-api-secret Chave secreta da API TAP do Proofpoint
    LOOKBACK_SECONDS 3600 Período de lookback em segundos (padrão: 1 hora)

  10. Na seção Variáveis e secrets, role a tela para baixo até Solicitações:

    • Tempo limite da solicitação: insira 600 segundos (10 minutos)

  11. Acesse a guia Configurações:

    • Na seção Recursos:
      • Memória: selecione 512 MiB ou mais.
      • CPU: selecione 1

  12. Na seção Escalonamento de revisão:

    • Número mínimo de instâncias: insira 0
    • Número máximo de instâncias: insira 100 ou ajuste com base na carga esperada.

  13. Clique em Criar.

  14. Aguarde a criação do serviço (1 a 2 minutos).

  15. Depois que o serviço for criado, o editor de código inline será aberto automaticamente.

Adicionar código da função

  1. Insira main no campo Ponto de entrada.

  2. No editor de código inline, crie dois arquivos:

    • Primeiro arquivo:main.py:

      import functions_framework
from google.cloud import storage
import json
import os
import urllib3
from datetime import datetime, timezone, timedelta
import time
import base64

# Initialize HTTP client with timeouts
http = urllib3.PoolManager(
  timeout=urllib3.Timeout(connect=5.0, read=60.0),
  retries=False,
)

# Initialize Storage client
storage_client = storage.Client()

# Environment variables
GCS_BUCKET = os.environ.get('GCS_BUCKET')
GCS_PREFIX = os.environ.get('GCS_PREFIX', 'wbi-logs')
STATE_KEY = os.environ.get('STATE_KEY', 'wbi-logs/state.json')
SERVICE_PRINCIPAL = os.environ.get('SERVICE_PRINCIPAL')
API_SECRET = os.environ.get('API_SECRET')
LOOKBACK_SECONDS = int(os.environ.get('LOOKBACK_SECONDS', '3600'))

TAP_API_BASE = "https://tap-api-v2.proofpoint.com/v2/siem"

def parse_datetime(value: str) -> datetime:
  """Parse ISO datetime string to datetime object."""
  if value.endswith("Z"):
    value = value[:-1] + "+00:00"
  return datetime.fromisoformat(value)

@functions_framework.cloud_event
def main(cloud_event):
  """
  Cloud Run function triggered by Pub/Sub to fetch Proofpoint
  Web Browser Isolation events via TAP SIEM API and write to GCS.

  Args:
    cloud_event: CloudEvent object containing Pub/Sub message
  """

  if not all([GCS_BUCKET, SERVICE_PRINCIPAL, API_SECRET]):
    print('Error: Missing required environment variables')
    return

  try:
    # Get GCS bucket
    bucket = storage_client.bucket(GCS_BUCKET)

    # Load state
    state = load_state(bucket, STATE_KEY)

    now = datetime.now(timezone.utc)

    # Determine since_seconds from state
    since_seconds = LOOKBACK_SECONDS
    if isinstance(state, dict) and state.get("last_event_time"):
      try:
        last_time = parse_datetime(state["last_event_time"])
        elapsed = (now - last_time).total_seconds()
        # Add 120 seconds overlap to catch delayed events
        since_seconds = int(elapsed) + 120
        # TAP API maximum is 1 hour (3600 seconds)
        since_seconds = min(since_seconds, 3600)
      except Exception as e:
        print(f"Warning: Could not parse last_event_time: {e}")

    print(f"Fetching events from last {since_seconds} seconds")

    # Build auth header (Basic auth)
    auth_string = f"{SERVICE_PRINCIPAL}:{API_SECRET}"
    auth_bytes = auth_string.encode('utf-8')
    auth_b64 = base64.b64encode(auth_bytes).decode('utf-8')

    # Fetch all SIEM events
    records = fetch_siem_events(
      auth_b64=auth_b64,
      since_seconds=since_seconds,
    )

    if not records:
      print("No new events found.")
      save_state(bucket, STATE_KEY, now.isoformat())
      return

    # Write to GCS as NDJSON
    timestamp = now.strftime('%Y%m%d_%H%M%S')
    object_key = f"{GCS_PREFIX}/logs_{timestamp}.ndjson"
    blob = bucket.blob(object_key)

    ndjson = '\n'.join([json.dumps(record, ensure_ascii=False) for record in records]) + '\n'
    blob.upload_from_string(ndjson, content_type='application/x-ndjson')

    print(f"Wrote {len(records)} records to gs://{GCS_BUCKET}/{object_key}")

    # Update state
    save_state(bucket, STATE_KEY, now.isoformat())

    print(f"Successfully processed {len(records)} records")

  except Exception as e:
    print(f'Error processing logs: {str(e)}')
    raise

def load_state(bucket, key):
  """Load state from GCS."""
  try:
    blob = bucket.blob(key)
    if blob.exists():
      state_data = blob.download_as_text()
      return json.loads(state_data)
  except Exception as e:
    print(f"Warning: Could not load state: {e}")

  return {}

def save_state(bucket, key, last_event_time_iso: str):
  """Save the last event timestamp to GCS state file."""
  try:
    state = {'last_event_time': last_event_time_iso}
    blob = bucket.blob(key)
    blob.upload_from_string(
      json.dumps(state, indent=2),
      content_type='application/json'
    )
    print(f"Saved state: last_event_time={last_event_time_iso}")
  except Exception as e:
    print(f"Warning: Could not save state: {e}")

def fetch_siem_events(auth_b64: str, since_seconds: int):
  """
  Fetch events from the Proofpoint TAP SIEM API.

  The TAP SIEM API returns all event types (clicks, messages, isolation)
  in a single response. The sinceSeconds parameter controls the lookback window
  (maximum 3600 seconds / 1 hour).

  Args:
    auth_b64: Base64-encoded Service Principal:API Secret for Basic auth
    since_seconds: Fetch events from the last N seconds (max 3600)

  Returns:
    List of event records
  """
  headers = {
    'Authorization': f'Basic {auth_b64}',
    'Accept': 'application/json',
    'User-Agent': 'GoogleSecOps-ProofpointWBICollector/1.0',
  }

  url = f"{TAP_API_BASE}/all?format=json&sinceSeconds={since_seconds}"
  backoff = 1.0
  max_retries = 3

  for attempt in range(max_retries):
    try:
      response = http.request('GET', url, headers=headers)

      # Handle rate limiting with exponential backoff
      if response.status == 429:
        retry_after = int(response.headers.get('Retry-After', str(int(backoff))))
        print(f"Rate limited (429). Retrying after {retry_after}s...")
        time.sleep(retry_after)
        backoff = min(backoff * 2, 30.0)
        continue

      if response.status != 200:
        print(f"HTTP Error: {response.status}")
        response_text = response.data.decode('utf-8')
        print(f"Response body: {response_text}")
        return []

      data = json.loads(response.data.decode('utf-8'))

      # TAP SIEM API returns events grouped by type
      all_events = []

      # Collect all event types
      for key in ['clicksPermitted', 'clicksBlocked', 'messagesDelivered', 'messagesBlocked']:
        events = data.get(key, [])
        if events:
          for event in events:
            event['_tap_event_type'] = key
          all_events.extend(events)
          print(f"Retrieved {len(events)} {key} events")

      print(f"Total events retrieved: {len(all_events)}")
      return all_events

    except Exception as e:
      print(f"Error fetching SIEM events (attempt {attempt + 1}): {e}")
      if attempt < max_retries - 1:
        time.sleep(backoff)
        backoff = min(backoff * 2, 30.0)

  return []

    • Segundo arquivo:requirements.txt:

      functions-framework==3.*
google-cloud-storage==2.*
urllib3>=2.0.0

  3. Clique em Implantar para salvar e implantar a função.

  4. Aguarde a conclusão da implantação (2 a 3 minutos).

Criar o job do Cloud Scheduler

O Cloud Scheduler vai publicar mensagens no tópico do Pub/Sub em intervalos regulares, acionando a função do Cloud Run.

  1. No console do GCP, acesse o Cloud Scheduler.
  2. Clique em Criar job.

  3. Informe os seguintes detalhes de configuração:

    Configuração Valor
    Nome proofpoint-wbi-collector-hourly
    Região Selecione a mesma região da função do Cloud Run
    Frequência 0 * * * * (de hora em hora)
    Fuso horário Selecionar fuso horário (UTC recomendado)
    Tipo de destino Pub/Sub
    Tópico Selecione o tópico do Pub/Sub (proofpoint-wbi-trigger).
    Corpo da mensagem {} (objeto JSON vazio)

  4. Clique em Criar.

Opções de frequência de programação

Escolha a frequência com base no volume de registros e nos requisitos de latência:

Frequência Expressão Cron Caso de uso
A cada 5 minutos */5 * * * * Alto volume e baixa latência
A cada 15 minutos */15 * * * * Volume médio
A cada hora 0 * * * * Padrão (recomendado)

Testar a integração

  1. No console do Cloud Scheduler, encontre seu job.
  2. Clique em Forçar execução para acionar o job manualmente.
  3. Aguarde alguns segundos.
  4. Acesse Cloud Run > Serviços.
  5. Clique no nome da função (proofpoint-wbi-collector).
  6. Clique na guia Registros.

  7. Verifique se a função foi executada com sucesso. Procure:

    Fetching events from last 3600 seconds
Retrieved X clicksPermitted events
Retrieved X messagesDelivered events
Total events retrieved: X
Wrote X records to gs://proofpoint-wbi-logs/wbi-logs/logs_YYYYMMDD_HHMMSS.ndjson
Successfully processed X records

  8. Acesse Cloud Storage > Buckets.

  9. Clique no nome do bucket (proofpoint-wbi-logs).

  10. Navegue até a pasta de prefixo (wbi-logs/).

  11. Verifique se um novo arquivo .ndjson foi criado com o carimbo de data/hora atual.

Se você encontrar erros nos registros:

  • HTTP 401: verifique o principal de serviço e a chave secreta da API nas variáveis de ambiente
  • HTTP 403: verifique se a credencial tem acesso à API SIEM e se os eventos de isolamento do navegador estão incluídos na sua assinatura.
  • HTTP 429: limitação de taxa. A função vai tentar de novo automaticamente com espera.
  • Variáveis de ambiente ausentes: verifique se todas as variáveis necessárias estão definidas.

Recuperar a conta de serviço do Google SecOps

O Google SecOps usa uma conta de serviço exclusiva para ler dados do seu bucket do GCS. Você precisa conceder a essa conta de serviço acesso ao seu bucket.

Receber o e-mail da conta de serviço

  1. Acesse Configurações do SIEM > Feeds.
  2. Clique em Adicionar novo feed.
  3. Clique em Configurar um único feed.
  4. No campo Nome do feed, insira um nome para o feed (por exemplo, Proofpoint Web Browser Isolation Logs).
  5. Selecione Google Cloud Storage V2 como o Tipo de origem.
  6. Selecione Isolamento do navegador da Web da Proofpoint como o Tipo de registro.
  7. Clique em Receber conta de serviço.

  8. Um e-mail exclusivo da conta de serviço será exibido, por exemplo:

    chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.com

  9. Copie esse endereço de e-mail para usar na próxima etapa.

  10. Clique em Próxima.

  11. Especifique valores para os seguintes parâmetros de entrada:

    • URL do bucket de armazenamento: insira o URI do bucket do GCS com o caminho do prefixo:

      gs://proofpoint-wbi-logs/wbi-logs/
      • Substitua:
        • proofpoint-wbi-logs: o nome do bucket do GCS.
        • wbi-logs: prefixo/caminho da pasta opcional onde os registros são armazenados (deixe em branco para a raiz).

    • Opção de exclusão da fonte: selecione a opção de exclusão de acordo com sua preferência:

      • Nunca: nunca exclui arquivos após as transferências (recomendado para testes).
      • Excluir arquivos transferidos: exclui os arquivos após a transferência.

      • Excluir arquivos transferidos e diretórios vazios: exclui arquivos e diretórios vazios após a transferência.

    • Idade máxima do arquivo: inclua arquivos modificados no último número de dias (o padrão é 180 dias).

    • Namespace do recurso: o namespace do recurso

    • Rótulos de ingestão: o rótulo a ser aplicado aos eventos deste feed

  12. Clique em Próxima.

  13. Revise a nova configuração do feed na tela Finalizar e clique em Enviar.

Conceder permissões do IAM à conta de serviço do Google SecOps

A conta de serviço do Google SecOps precisa do papel Leitor de objetos do Storage no seu bucket do GCS.

  1. Acesse Cloud Storage > Buckets.
  2. Clique no nome do bucket (por exemplo, proofpoint-wbi-logs).
  3. Acesse a guia Permissões.
  4. Clique em Conceder acesso.
  5. Informe os seguintes detalhes de configuração:
    • Adicionar principais: cole o e-mail da conta de serviço do Google SecOps.
    • Atribuir papéis: selecione Leitor de objetos do Storage.

  6. Clique em Salvar.

Tabela de mapeamento de UDM

Campo de registro Mapeamento do UDM Lógica
metadata.event_type Tipo do evento
categories metadata.product_event_type Tipo de evento específico do produto
parentPageURL metadata.url_back_to_product URL que vincula de volta ao produto
região principal.location.country_or_region País ou região da localização do principal
zona principal.location.name Nome do local principal
userId principal.user.product_object_id Identificador específico do produto para o usuário.
userName principal.user.userid Identificador de usuário
security_result security_result Detalhes do resultado de segurança
disposition security_result.action Ação de segurança realizada
disposition security_result.action_details Detalhes da ação de segurança
classificação security_result.detection_fields Campos relacionados à detecção
url target.url URL do recurso de destino
metadata.product_name Nome do produto
metadata.vendor_name Nome do fornecedor

Registro de alterações

Ver o registro de alterações deste analisador

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