Coletar registros do PhishLabs

Compatível com:

Este documento explica como ingerir registros do PhishLabs no Google Security Operations usando o Google Cloud Storage V2.

O PhishLabs (agora Fortra Brand Protection) é uma plataforma de proteção contra riscos digitais para detectar e mitigar phishing, abuso de marca e ameaças em mídias sociais. Ele fornece dados de incidentes e indicadores de comprometimento (IOCs) por meio da API Incident Data e da API IOC. O analisador extrai campos dos dados de eventos do PhishLabs e os mapeia para o modelo de dados unificado (UDM), capturando metadados de e-mail, classificações de segurança e detalhes de inteligência contra ameaças.

Antes de começar

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

  • Uma instância do Google SecOps
  • Um projeto do GCP com a API Cloud Storage ativada
  • Permissões para criar e gerenciar buckets 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 PhishLabs com um token de API válido para a API Incident Data e a API IOC.

Criar um bucket do Google Cloud Storage

  1. Acesse o Console do Google Cloud.
  2. Selecione seu projeto ou crie um novo.
  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, phishlabs-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 PhishLabs

Receber token de API

  1. Faça login no portal do PhishLabs.
  2. Acesse as configurações da sua conta ou entre em contato com o representante da sua conta da PhishLabs (Fortra) para receber um token de API.
  3. Copie e armazene com segurança o token da API (token do portador).

Verifique as permissões

Para verificar se o token da API tem as permissões necessárias:

  1. Faça login no portal do PhishLabs.
  2. Acesse as configurações da conta.
  3. Confirme se o token da API está ativo e tem acesso à API Incident Data.
  4. Se não conseguir acessar as configurações da API, entre em contato com o representante da sua conta da PhishLabs.

Testar o acesso à API

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

    # Replace with your actual credentials
    API_TOKEN="<your-api-token>"
    
    # Test Incident Data API access
    curl -v -H "Authorization: Bearer ${API_TOKEN}" \
      "https://caseapi.phishlabs.com/idapi/v1/incidents?limit=5&offset=0"
    

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 phishlabs-collector-sa.
    • Descrição da conta de serviço: insira Service account for Cloud Run function to collect PhishLabs 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 do Cloud Functions.
  6. Clique em Continuar.
  7. Clique em Concluído.

Esses papéis são necessários para:

  • Administrador de objetos do Storage: gravar registros no bucket do GCS e gerenciar 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 à conta de serviço permissões de gravação no bucket do GCS:

  1. Acesse Cloud Storage > Buckets.
  2. Clique no nome do bucket (por exemplo, phishlabs-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, phishlabs-collector-sa@PROJECT_ID.iam.gserviceaccount.com)
    • Atribuir papéis: selecione Administrador de objetos do Storage.
  6. Clique em Salvar.

Criar tópico 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 phishlabs-logs-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 dados de incidentes e IOCs das APIs da PhishLabs 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 phishlabs-collector
    Região Selecione a região correspondente ao bucket do GCS (por exemplo, us-central1).
    Ambiente de execução Selecione Python 3.12 ou mais recente.
  5. Na seção Acionador (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 (phishlabs-logs-trigger).
    4. Clique em Salvar.
  6. Na seção Autenticação:

    1. Selecione Exigir autenticação.
    2. Verifique o Identity and Access Management (IAM).
  7. Role 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 (phishlabs-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 phishlabs-logs Nome do bucket do GCS
    GCS_PREFIX phishlabs Prefixo para arquivos de registro
    STATE_KEY phishlabs/state.json Caminho do arquivo de estado
    API_TOKEN your-bearer-token Token do portador da API PhishLabs
    COLLECT_IOCS true Também coletar dados de IOC (verdadeiro/falso)
    MAX_RECORDS 1000 Máximo de registros por execução
    PAGE_SIZE 50 Registros por página
    LOOKBACK_HOURS 24 Período de lookback inicial
  10. Na seção Variáveis e secrets, role 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:

    • main.py:
    import functions_framework
    from google.cloud import storage
    import json
    import os
    import urllib3
    from datetime import datetime, timezone, timedelta
    import time
    
    # Initialize HTTP client with timeouts
    http = urllib3.PoolManager(
      timeout=urllib3.Timeout(connect=5.0, read=30.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', 'phishlabs')
    STATE_KEY = os.environ.get('STATE_KEY', 'phishlabs/state.json')
    API_TOKEN = os.environ.get('API_TOKEN')
    COLLECT_IOCS = os.environ.get('COLLECT_IOCS', 'true').lower() == 'true'
    MAX_RECORDS = int(os.environ.get('MAX_RECORDS', '1000'))
    PAGE_SIZE = int(os.environ.get('PAGE_SIZE', '50'))
    LOOKBACK_HOURS = int(os.environ.get('LOOKBACK_HOURS', '24'))
    
    INCIDENT_API_BASE = "https://caseapi.phishlabs.com/idapi/v1"
    IOC_API_BASE = "https://ioc.phishlabs.com/api/v1"
    
    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 PhishLabs
      incident and IOC data and write to GCS.
    
      Args:
        cloud_event: CloudEvent object containing Pub/Sub message
      """
    
      if not all([GCS_BUCKET, API_TOKEN]):
        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)
    
        # Determine time window
        now = datetime.now(timezone.utc)
        last_time = None
    
        if isinstance(state, dict) and state.get("last_event_time"):
          try:
            last_time = parse_datetime(state["last_event_time"])
            last_time = last_time - timedelta(minutes=2)
          except Exception as e:
            print(f"Warning: Could not parse last_event_time: {e}")
    
        if last_time is None:
          last_time = now - timedelta(hours=LOOKBACK_HOURS)
    
        print(f"Fetching logs from {last_time.isoformat()} to {now.isoformat()}")
    
        all_records = []
    
        # Fetch incidents from Incident Data API
        incidents, newest_incident_time = fetch_incidents(
          token=API_TOKEN,
          page_size=PAGE_SIZE,
          max_records=MAX_RECORDS,
        )
        if incidents:
          all_records.extend(incidents)
          print(f"Collected {len(incidents)} incidents")
    
        # Fetch IOCs if enabled
        if COLLECT_IOCS:
          lookback_seconds = int((now - last_time).total_seconds())
          iocs, newest_ioc_time = fetch_iocs(
            token=API_TOKEN,
            since_seconds=lookback_seconds,
          )
          if iocs:
            all_records.extend(iocs)
            print(f"Collected {len(iocs)} IOCs")
    
        if not all_records:
          print("No new records 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 all_records]) + '\n'
        blob.upload_from_string(ndjson, content_type='application/x-ndjson')
    
        print(f"Wrote {len(all_records)} records to gs://{GCS_BUCKET}/{object_key}")
    
        # Update state
        save_state(bucket, STATE_KEY, now.isoformat())
    
        print(f"Successfully processed {len(all_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_incidents(token: str, page_size: int, max_records: int):
      """
      Fetch incidents from the PhishLabs Incident Data API with pagination.
    
      Args:
        token: Bearer token for authentication
        page_size: Number of records per page
        max_records: Maximum total records to fetch
    
      Returns:
        Tuple of (records list, newest_event_time ISO string)
      """
      headers = {
        'Authorization': f'Bearer {token}',
        'Accept': 'application/json',
        'User-Agent': 'GoogleSecOps-PhishLabsCollector/1.0',
      }
    
      records = []
      newest_time = None
      page_num = 0
      backoff = 1.0
      offset = 0
    
      while True:
        page_num += 1
    
        if len(records) >= max_records:
          print(f"Reached max_records limit ({max_records})")
          break
    
        current_limit = min(page_size, max_records - len(records))
        url = f"{INCIDENT_API_BASE}/incidents?limit={current_limit}&offset={offset}"
    
        try:
          response = http.request('GET', url, headers=headers)
    
          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
    
          backoff = 1.0
    
          if response.status != 200:
            print(f"HTTP Error: {response.status}")
            response_text = response.data.decode('utf-8')
            print(f"Response body: {response_text}")
            return [], None
    
          data = json.loads(response.data.decode('utf-8'))
    
          if isinstance(data, list):
            page_results = data
          else:
            page_results = data.get('incidents', data.get('results', []))
    
          if not page_results:
            print(f"No more incident results (empty page)")
            break
    
          print(f"Incidents page {page_num}: Retrieved {len(page_results)} events")
          records.extend(page_results)
    
          # Track newest event time
          for event in page_results:
            try:
              event_time = event.get('createdAt') or event.get('dateCreated')
              if event_time:
                if newest_time is None or parse_datetime(event_time) > parse_datetime(newest_time):
                  newest_time = event_time
            except Exception as e:
              print(f"Warning: Could not parse event time: {e}")
    
          if len(page_results) < current_limit:
            print(f"Reached last page (size={len(page_results)} < limit={current_limit})")
            break
    
          offset += len(page_results)
    
        except Exception as e:
          print(f"Error fetching incidents: {e}")
          return [], None
    
      print(f"Retrieved {len(records)} total incidents from {page_num} pages")
      return records, newest_time
    
    def fetch_iocs(token: str, since_seconds: int):
      """
      Fetch IOCs from the PhishLabs IOC API.
    
      Args:
        token: Bearer token for authentication
        since_seconds: Fetch IOCs from the last N seconds
    
      Returns:
        Tuple of (records list, newest_event_time ISO string)
      """
      headers = {
        'Authorization': f'Bearer {token}',
        'Accept': 'application/json',
        'User-Agent': 'GoogleSecOps-PhishLabsCollector/1.0',
      }
    
      # Convert seconds to a relative time string
      since_hours = max(1, since_seconds // 3600)
      url = f"{IOC_API_BASE}/iocs?since={since_hours}h"
    
      try:
        response = http.request('GET', url, headers=headers)
    
        if response.status != 200:
          print(f"IOC API HTTP Error: {response.status}")
          return [], None
    
        data = json.loads(response.data.decode('utf-8'))
    
        if isinstance(data, list):
          iocs = data
        else:
          iocs = data.get('iocs', data.get('results', []))
    
        print(f"Retrieved {len(iocs)} IOCs")
        return iocs, None
    
      except Exception as e:
        print(f"Error fetching IOCs: {e}")
        return [], None
    
    • 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 phishlabs-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 Selecione o fuso horário (UTC recomendado)
    Tipo de destino Pub/Sub
    Tópico Selecione o tópico do Pub/Sub (phishlabs-logs-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)
A cada 6 horas 0 */6 * * * Processamento em lote de baixo volume
Diário 0 0 * * * Coleta de dados históricos

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 (phishlabs-collector).
  6. Clique na guia Registros.
  7. Verifique se a função foi executada com sucesso. Procure por:

    Fetching logs from YYYY-MM-DDTHH:MM:SS+00:00 to YYYY-MM-DDTHH:MM:SS+00:00
    Incidents page 1: Retrieved X events
    Collected X incidents
    Retrieved X IOCs
    Wrote X records to gs://phishlabs-logs/phishlabs/logs_YYYYMMDD_HHMMSS.ndjson
    Successfully processed X records
    
  8. Acesse Cloud Storage > Buckets.

  9. Clique no nome do bucket (phishlabs-logs).

  10. Navegue até a pasta de prefixo (phishlabs/).

  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 token da API nas variáveis de ambiente.
  • HTTP 403: verifique se o token de API tem acesso à API Incident Data e à API IOC.
  • HTTP 429: limitação de taxa. A função vai tentar novamente de forma automática 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 bucket do GCS. É necessário conceder a essa conta de serviço acesso ao bucket.

Encontrar o e-mail da conta de serviço

  1. Acesse Configurações > Gerenciamento de dados > Feeds. Se você estiver em uma plataforma somente SIEM, acesse Configurações > 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, PhishLabs Logs).
  5. Selecione Google Cloud Storage V2 como o Tipo de origem.
  6. Selecione PhishLabs como o Tipo de registro.
  7. Clique em Get Service Account.
  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://phishlabs-logs/phishlabs/
      
      • Substitua:
        • phishlabs-logs: o nome do bucket do GCS.
        • phishlabs: prefixo/caminho de pasta opcional em que 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 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 nos últimos dias (o padrão é 180 dias).

    • Namespace do recurso: o namespace do recurso

    • Rótulos de ingestão: o rótulo que será aplicado aos eventos desse feed.

  12. Clique em Próxima.

  13. Revise a configuração do novo 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 bucket do GCS.

  1. Acesse Cloud Storage > Buckets.
  2. Clique no nome do bucket (por exemplo, phishlabs-logs).
  3. Acesse a guia Permissões.
  4. Clique em Conceder acesso.
  5. Informe os seguintes detalhes de configuração:
    • Adicionar participantes: 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 de UDM Lógica
service, closed, status, details.emailReportedBy, details.emailReceivedDate, details.payloadFamily, details.offlineUponReview additional.fields Dados de eventos adicionais específicos do fornecedor que não podem ser representados adequadamente nas seções formais do modelo do UDM
descrição metadata.description A descrição do evento
metadata.event_type Tipo de evento (por exemplo, USER_LOGIN, NETWORK_CONNECTION)
ID metadata.product_log_id Identificador exclusivo da entrada de registro do produto
sender_email network.email.from Endereço de e-mail do remetente
details.messageID network.email.mail_id Identificador exclusivo da mensagem de e-mail
emailData.address network.email.reply_to Endereço de e-mail para resposta
título network.email.subject Linha de assunto do e-mail
emailData.address network.email.to Endereços de e-mail do destinatário
duration network.session_duration.seconds Duração da sessão em segundos
detailUrl.url principal.process.file.embedded_urls URLs incorporados em arquivos associados ao processo
src_email principal.user.email_addresses Endereços de e-mail associados ao usuário
user_name principal.user.user_display_name Nome de exibição do usuário
details.classification, details.severity, details.furtherReviewReason, details.subClassification, details.caseType, details.emailBody, details.submissionMethod, detailUrl.url, detailUrl.malicious, detailUrl.maliciousDomain security_result Classificação ou ação de segurança feita por um produto de segurança
metadata.product_name Nome do produto
metadata.vendor_name Nome do fornecedor
details.urls.url", "details.urls.malicious", and "details.urls.maliciousDomain security_result.detection_fields Mapeado do registro de alterações

Registro de alterações

Confira o registro de alterações deste analisador

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