Coletar registros do Splunk Attack Analyzer

Compatível com:

Neste documento, explicamos como ingerir registros do Splunk Attack Analyzer no Google Security Operations usando o Google Cloud Storage V2.

O Splunk Attack Analyzer (antigo TwinWave) é uma plataforma automatizada de análise de ameaças que detecta phishing e malware por meio de análise comportamental. Ele fornece resultados de jobs concluídos e dados forenses normalizados por uma API REST.

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 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 Splunk Attack Analyzer com permissões de geração de chaves de API

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, splunk-attack-analyzer-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 Splunk Attack Analyzer

Gerar chave de API

  1. Faça login no Splunk Attack Analyzer.
  2. Selecione seu nome de usuário no canto superior direito e, em seguida, selecione Chaves de API.
  3. Clique em + Nova chave.
  4. Insira um nome descritivo para a chave (por exemplo, Google Security Operations Integration).
  5. Clique em Criar.
  6. Copie e salve a chave secreta da API exibida no modal em um local seguro.

Verifique as permissões

Para verificar se a chave de API tem o acesso necessário:

  1. Faça login no Splunk Attack Analyzer.
  2. Selecione seu nome de usuário no canto superior direito e, em seguida, selecione Chaves de API.
  3. Verifique se a chave de API está listada e ativa.

Testar o acesso à API

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

    # Replace with your actual API key
    API_KEY="your-api-key"
    
    # Test API access - list completed jobs
    curl -v -H "Authorization: Bearer ${API_KEY}" \
      "https://app.twinwave.io/api/v1/jobs?done=true&limit=1"
    

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 saa-collector-sa.
    • Descrição da conta de serviço: insira Service account for Cloud Run function to collect Splunk Attack Analyzer 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, splunk-attack-analyzer-logs).
  3. Acesse a guia Permissões.
  4. Clique em Conceder acesso.
  5. Informe os seguintes detalhes de configuração:
    • Adicionar participantes: insira o e-mail da conta de serviço (por exemplo, saa-collector-sa@your-project.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 saa-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 registros da API Splunk Attack Analyzer 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 saa-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 saa-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 saa-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 splunk-attack-analyzer-logs Nome do bucket do GCS
    GCS_PREFIX saa Prefixo para arquivos de registro
    STATE_KEY saa/state.json Caminho do arquivo de estado
    API_KEY your-api-key Chave de API do Splunk Attack Analyzer
    API_BASE https://app.twinwave.io URL de base da API
    MAX_RECORDS 5000 Máximo de registros por execução
    PAGE_SIZE 100 Registros por página
    LOOKBACK_HOURS 24 Período de lookback inicial
  10. Role para baixo na guia Variáveis e secrets até Solicitações:

    • Tempo limite da solicitação: insira 600 segundos (10 minutos).
  11. Acesse a guia Configurações em Contêineres:

    • 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 em Ponto de entrada da função.
  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
      
      # 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', 'saa')
      STATE_KEY = os.environ.get('STATE_KEY', 'saa/state.json')
      API_KEY = os.environ.get('API_KEY', '')
      API_BASE = os.environ.get('API_BASE', 'https://app.twinwave.io').rstrip('/')
      MAX_RECORDS = int(os.environ.get('MAX_RECORDS', '5000'))
      PAGE_SIZE = int(os.environ.get('PAGE_SIZE', '100'))
      LOOKBACK_HOURS = int(os.environ.get('LOOKBACK_HOURS', '24'))
      
      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 Splunk Attack Analyzer logs and write to GCS.
      
        Args:
          cloud_event: CloudEvent object containing Pub/Sub message
        """
      
        if not all([GCS_BUCKET, API_KEY]):
          print('Error: Missing required environment variables')
          return
      
        try:
          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 jobs from {last_time.isoformat()} to {now.isoformat()}")
      
          # Fetch completed jobs
          jobs, newest_event_time = fetch_jobs(
            start_time=last_time,
            end_time=now,
            page_size=PAGE_SIZE,
            max_records=MAX_RECORDS,
          )
      
          if not jobs:
            print("No new completed jobs found.")
            save_state(bucket, STATE_KEY, now.isoformat())
            return
      
          # Fetch forensics for each job
          all_records = []
          for job in jobs:
            job_id = job.get('id', '')
            if not job_id:
              continue
      
            forensics = fetch_forensics(job_id)
            if forensics:
              # Combine job metadata with forensics
              record = {
                'job': job,
                'forensics': forensics
              }
              all_records.append(record)
      
          if not all_records:
            print("No forensics data retrieved.")
            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}")
      
          if newest_event_time:
            save_state(bucket, STATE_KEY, newest_event_time)
          else:
            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_jobs(start_time: datetime, end_time: datetime, page_size: int, max_records: int):
        """
        Fetch completed jobs from Splunk Attack Analyzer API with pagination and rate limiting.
      
        Args:
          start_time: Start time for job query
          end_time: End time for job query
          page_size: Number of records per page
          max_records: Maximum total records to fetch
      
        Returns:
          Tuple of (jobs list, newest_event_time ISO string)
        """
        endpoint = f"{API_BASE}/api/v1/jobs"
      
        headers = {
          'Authorization': f'Bearer {API_KEY}',
          'Accept': 'application/json',
          'User-Agent': 'GoogleSecOps-SAACollector/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"{endpoint}?done=true&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'))
      
            page_results = data.get('jobs', [])
      
            if not page_results:
              print(f"No more results (empty page)")
              break
      
            # Filter by time window
            filtered = []
            for job in page_results:
              created = job.get('created_at', '')
              if created:
                try:
                  job_time = parse_datetime(created)
                  if start_time <= job_time <= end_time:
                    filtered.append(job)
                    if newest_time is None or job_time > parse_datetime(newest_time):
                      newest_time = created
                except Exception as e:
                  print(f"Warning: Could not parse job time: {e}")
                  filtered.append(job)
      
            print(f"Page {page_num}: Retrieved {len(page_results)} jobs, {len(filtered)} in time window")
            records.extend(filtered)
      
            if len(page_results) < page_size:
              print(f"Reached last page (size={len(page_results)} < limit={page_size})")
              break
      
            offset += len(page_results)
      
          except Exception as e:
            print(f"Error fetching jobs: {e}")
            return [], None
      
        print(f"Retrieved {len(records)} total jobs from {page_num} pages")
        return records, newest_time
      
      def fetch_forensics(job_id: str):
        """
        Fetch normalized forensics for a specific job.
      
        Args:
          job_id: The job ID
      
        Returns:
          Forensics data dict or None
        """
        endpoint = f"{API_BASE}/api/v1/jobs/{job_id}/normalizedforensics"
      
        headers = {
          'Authorization': f'Bearer {API_KEY}',
          'Accept': 'application/json',
          'User-Agent': 'GoogleSecOps-SAACollector/1.0'
        }
      
        backoff = 1.0
        max_retries = 3
      
        for attempt in range(max_retries):
          try:
            response = http.request('GET', endpoint, headers=headers)
      
            if response.status == 429:
              retry_after = int(response.headers.get('Retry-After', str(int(backoff))))
              print(f"Rate limited (429) on forensics for job {job_id}. Retrying after {retry_after}s...")
              time.sleep(retry_after)
              backoff = min(backoff * 2, 30.0)
              continue
      
            if response.status != 200:
              print(f"Warning: Could not fetch forensics for job {job_id}: HTTP {response.status}")
              return None
      
            return json.loads(response.data.decode('utf-8'))
      
          except Exception as e:
            print(f"Warning: Error fetching forensics for job {job_id}: {e}")
            if attempt < max_retries - 1:
              time.sleep(backoff)
              backoff = min(backoff * 2, 30.0)
              continue
            return None
      
        return None
      
    • 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 saa-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 saa-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 (saa-collector-hourly).
  2. Clique em Forçar execução para acionar manualmente.
  3. Aguarde alguns segundos e acesse Cloud Run > Serviços > saa-collector > Registros.
  4. Verifique se a função foi executada com sucesso. Procure por:

    Fetching jobs from YYYY-MM-DDTHH:MM:SS+00:00 to YYYY-MM-DDTHH:MM:SS+00:00
    Page 1: Retrieved X jobs, Y in time window
    Wrote Z records to gs://splunk-attack-analyzer-logs/saa/logs_YYYYMMDD_HHMMSS.ndjson
    Successfully processed Z records
    
  5. Verifique o bucket do GCS (splunk-attack-analyzer-logs) para confirmar se os registros foram gravados.

Se você encontrar erros nos registros:

  • HTTP 401: verifique a chave de API nas variáveis de ambiente.
  • HTTP 403: verifique se a chave de API tem as permissões necessárias.
  • 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.

Configurar um feed no Google SecOps para ingerir registros do Splunk Attack Analyzer

  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, Splunk Attack Analyzer Logs).
  5. Selecione Google Cloud Storage V2 como o Tipo de origem.
  6. Selecione Splunk Attack Analyzer como o Tipo de registro.
  7. Clique em Get Service Account. Um e-mail exclusivo da conta de serviço será exibido, por exemplo:

    chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.com
    
  8. Copie o endereço de e-mail. Você vai usá-la na próxima etapa.

  9. Clique em Próxima.

  10. 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://splunk-attack-analyzer-logs/saa/
      
      • Substitua:
        • splunk-attack-analyzer-logs: o nome do bucket do GCS.
        • saa: 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 a ser aplicado aos eventos desse feed.

  11. Clique em Próxima.

  12. Revise a configuração do novo feed de notícias 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 (splunk-attack-analyzer-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 de UDM Lógica
quando metadata.event_timestamp Quando o evento ocorreu
deviceName principal.hostname Nome do host do principal
ID da mensagem metadata.id Identificador exclusivo do evento
ação security_result.action Ação realizada pelo produto de segurança
protocolo network.ip_protocol Protocolo IP
srcAddr principal.ip Endereço IP do principal
srcPort principal.port Número da porta do principal
dstAddr target.ip Endereço IP do destino
dstPort target.port Número da porta do destino
metadata.event_type Tipo de evento
metadata.product_name Nome do produto
metadata.vendor_name Nome do fornecedor/da empresa
Attack Analyzer metadata.product_name Mapeado do registro de alterações
Splunk metadata.vendor_name 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.