Coletar registros de auditoria do Tines

Compatível com:

Google SecOps SIEM

Este documento explica como ingerir registros de auditoria do Tines no Google Security Operations usando o Google Cloud Storage.

O Tines é uma plataforma de automação sem código que permite que as equipes de segurança criem fluxos de trabalho e automatizem operações de segurança. Os registros de auditoria do Tines oferecem visibilidade das ações do usuário, das mudanças de configuração e dos eventos do sistema na plataforma Tines.

Antes de começar

Verifique se você atende os 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 Tines

Acessar o URL do Tines

No navegador, abra a interface do Tines para seu locatário.
Copie o domínio da barra de endereço. Você vai usá-lo como TINES_BASE_URL.
Formato: https://<tenant-domain> (por exemplo, https://<tenant-domain>.tines.com).

Crie uma chave de API do serviço Tines (recomendado) ou uma chave de API pessoal.

Valores a serem salvos para etapas posteriores:

TINES_BASE_URL — Por exemplo, https://<domain>.tines.com
TINES_API_KEY: o token que você vai criar nas etapas a seguir

Opção 1: chave de API de serviço (recomendada)

Acesse o Menu de navegação > Chaves de API.
Clique em + Nova chave.
Selecione Chave de API de serviço.
Insira um nome descritivo (por exemplo, SecOps Audit Logs).
Clique em Criar.
Copie o token gerado imediatamente e salve-o com segurança. Você vai usá-lo como TINES_API_KEY.

Opção 2: chave de API pessoal (se as chaves de serviço não estiverem disponíveis)

Acesse o Menu de navegação > Chaves de API.
Clique em + Nova chave.
Selecione Chave de API pessoal.
Insira um nome descritivo.
Clique em Criar.
Copie e salve o token gerado com segurança.

Observação: as chaves de API de serviço são preferíveis porque estão vinculadas a contas de serviço com permissões específicas, em vez de herdar todas as permissões de uma conta de usuário.

Conceder a permissão de leitura do registro de auditoria

Faça login como proprietário do locatário ou peça para alguém fazer isso.
Acesse Configurações > Administrador > Administração de usuários ou clique no nome da sua equipe no menu superior esquerdo e selecione Usuários.
Encontre o usuário da conta de serviço associado à chave da API Service (ele terá o mesmo nome da sua chave de API). Se você estiver usando uma chave de API pessoal, encontre sua própria conta de usuário.
Clique no usuário para abrir o perfil dele.
Na seção Permissões do locatário, ative AUDIT_LOG_READ.
Clique em Salvar.

Verifique as permissões

Para verificar se a conta tem as permissões necessárias:

Faça login no Tines.
Acesse Configurações > Monitoramento > Registros de auditoria.
Se você conseguir ver as entradas de registro de auditoria, terá as permissões necessárias.
Se essa opção não estiver disponível, entre em contato com o proprietário do locatário para conceder a permissão AUDIT_LOG_READ.

Testar o acesso à API

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

# Replace with your actual credentials
TINES_BASE_URL="https://<tenant-domain>.tines.com"
TINES_API_KEY="<your-api-key>"

# Test API access
curl -X GET "${TINES_BASE_URL}/api/v1/audit_logs?per_page=1" \
  -H "Authorization: Bearer ${TINES_API_KEY}" \
  -H "Content-Type: application/json"

Você vai receber uma resposta JSON com entradas de registro de auditoria.

Criar um bucket do Google Cloud Storage

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

Informe os seguintes detalhes de configuração:

Configuração	Valor
Nomeie seu bucket	Insira um nome exclusivo globalmente, por exemplo, `tines-audit-logs`.
Tipo de local	Escolha com base nas 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

Clique em Criar.

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

No Console do GCP, acesse IAM e administrador > Contas de serviço.
Clique em Criar conta de serviço.
Informe os seguintes detalhes de configuração:
- Nome da conta de serviço: insira tines-audit-to-gcs-sa.
- Descrição da conta de serviço: insira Service account for Cloud Run function to collect Tines Audit Logs.
Clique em Criar e continuar.
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.
Clique em Continuar.
Clique em Concluído.

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

Administrador de objetos do Storage: grava registros em um 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:

Acesse Cloud Storage > Buckets.
Clique no nome do bucket.
Acesse a guia Permissões.
Clique em Conceder acesso.
Informe os seguintes detalhes de configuração:
- Adicionar principais: insira o e-mail da conta de serviço (por exemplo, tines-audit-to-gcs-sa@PROJECT_ID.iam.gserviceaccount.com).
- Atribuir papéis: selecione Administrador de objetos do Storage.
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.

No Console do GCP, acesse Pub/Sub > Tópicos.
Selecione Criar tópico.
Informe os seguintes detalhes de configuração:
- ID do tópico: insira tines-audit-trigger.
- Não altere as outras configurações.
Clique em Criar.

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

A função do Cloud Run é acionada por mensagens do Pub/Sub do Cloud Scheduler para buscar registros da API Tines e gravá-los no GCS.

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

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

Configuração	Valor
Nome do serviço	`tines-audit-to-gcs`
Região	Selecione a região que corresponde ao seu bucket do GCS (por exemplo, `us-central1`).
Ambiente de execução	Selecione Python 3.12 ou uma versão mais recente.

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 (tines-audit-trigger).
4. Clique em Salvar.
Na seção Autenticação:
1. Selecione Exigir autenticação.
2. Confira o Identity and Access Management (IAM).
Observação: o Pub/Sub processa automaticamente a autenticação ao invocar a função.
Role a tela para baixo e abra Contêineres, rede, segurança.
Acesse a guia Segurança:
- Conta de serviço: selecione a conta de serviço (tines-audit-to-gcs-sa).

Acesse a guia Contêineres:

Clique em Variáveis e secrets.
Clique em + Adicionar variável para cada variável de ambiente:

Nome da variável	Valor de exemplo	Descrição
`GCS_BUCKET`	`tines-audit-logs`	Nome do bucket do GCS
`GCS_PREFIX`	`tines/audit/`	Prefixo para arquivos de registro
`STATE_KEY`	`tines/audit/state.json`	Caminho do arquivo de estado
`TINES_BASE_URL`	`https://your-tenant.tines.com`	URL base da API
`TINES_API_KEY`	`your-tines-api-key`	Chave de API
`LOOKBACK_SECONDS`	`3600`	Período de lookback inicial
`PAGE_SIZE`	`500`	Registros por página
`MAX_PAGES`	`20`	Número máximo de páginas por execução
`HTTP_TIMEOUT`	`60`	Tempo limite da solicitação HTTP
`HTTP_RETRIES`	`3`	Tentativas de repetição HTTP

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).
Acesse a guia Configurações:
- Na seção Recursos:
  - Memória: selecione 512 MiB ou mais.
  - CPU: selecione 1.
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.
Clique em Criar.
Aguarde a criação do serviço (1 a 2 minutos).
Depois que o serviço é criado, o editor de código inline é aberto automaticamente.

Adicionar código da função

Insira main em Ponto de entrada da função.

No editor de código em linha, 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', 'tines/audit/')
STATE_KEY = os.environ.get('STATE_KEY', 'tines/audit/state.json')
TINES_BASE_URL = os.environ.get('TINES_BASE_URL')
TINES_API_KEY = os.environ.get('TINES_API_KEY')
LOOKBACK_SECONDS = int(os.environ.get('LOOKBACK_SECONDS', '3600'))
PAGE_SIZE = int(os.environ.get('PAGE_SIZE', '500'))
MAX_PAGES = int(os.environ.get('MAX_PAGES', '20'))
HTTP_TIMEOUT = int(os.environ.get('HTTP_TIMEOUT', '60'))
HTTP_RETRIES = int(os.environ.get('HTTP_RETRIES', '3'))

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 Tines Audit Logs and write to GCS.

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

    if not all([GCS_BUCKET, TINES_BASE_URL, TINES_API_KEY]):
        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"])
                # Overlap by 2 minutes to catch any delayed events
                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(seconds=LOOKBACK_SECONDS)

        print(f"Fetching logs from {last_time.isoformat()} to {now.isoformat()}")

        # Fetch logs
        records, newest_event_time = fetch_logs(
            api_base=TINES_BASE_URL,
            api_key=TINES_API_KEY,
            start_time=last_time,
            page_size=PAGE_SIZE,
            max_pages=MAX_PAGES,
        )

        if not records:
            print("No new log 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 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 with newest event time
        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(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_logs(api_base: str, api_key: str, start_time: datetime, page_size: int, max_pages: int):
    """
    Fetch logs from Tines API with pagination and rate limiting.

    Args:
        api_base: API base URL
        api_key: Tines API key
        start_time: Start time for log query
        page_size: Number of records per page
        max_pages: Maximum pages to fetch

    Returns:
        Tuple of (records list, newest_event_time ISO string)
    """
    base_url = api_base.rstrip('/')
    endpoint = f"{base_url}/api/v1/audit_logs"

    headers = {
        'Authorization': f'Bearer {api_key}',
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'User-Agent': 'GoogleSecOps-TinesCollector/1.0'
    }

    records = []
    newest_time = None
    page_num = 1
    backoff = 1.0

    while page_num <= max_pages:
        # Build URL with query parameters
        params = {
            'page': page_num,
            'per_page': page_size
        }
        param_str = '&'.join([f"{k}={v}" for k, v in params.items()])
        url = f"{endpoint}?{param_str}"

        try:
            response = http.request('GET', url, headers=headers, timeout=HTTP_TIMEOUT)

            # 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

            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'))

            # Extract results
            page_results = []
            if isinstance(data, dict):
                page_results = data.get('audit_logs', [])
            elif isinstance(data, list):
                page_results = data

            if not page_results:
                print(f"No more results (empty page)")
                break

            # Filter by start_time
            filtered_results = []
            for event in page_results:
                try:
                    event_time = event.get('created_at')
                    if event_time:
                        event_dt = parse_datetime(event_time)
                        if event_dt >= start_time:
                            filtered_results.append(event)
                            # Track newest event time
                            if newest_time is None or event_dt > parse_datetime(newest_time):
                                newest_time = event_time
                except Exception as e:
                    print(f"Warning: Could not parse event time: {e}")
                    filtered_results.append(event)

            print(f"Page {page_num}: Retrieved {len(page_results)} events, {len(filtered_results)} after filtering")
            records.extend(filtered_results)

            # Check for more results
            if isinstance(data, dict):
                meta = data.get('meta', {})
                next_page = meta.get('next_page_number')
                if not next_page:
                    print("No more pages (no next_page_number)")
                    break
                page_num = next_page
            else:
                # If response is a list, check if we got fewer results than requested
                if len(page_results) < page_size:
                    print(f"Reached last page (size={len(page_results)} < limit={page_size})")
                    break
                page_num += 1

        except Exception as e:
            print(f"Error fetching logs: {e}")
            if page_num <= HTTP_RETRIES:
                print(f"Retrying... (attempt {page_num}/{HTTP_RETRIES})")
                time.sleep(backoff)
                backoff = min(backoff * 2, 30.0)
                continue
            return [], None

    print(f"Retrieved {len(records)} total records from {page_num} pages")
    return records, newest_time

Segundo arquivo: requirements.txt:

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

Clique em Implantar para salvar e implantar a função.
Aguarde a conclusão da implantação (2 a 3 minutos).

Criar o job do Cloud Scheduler

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

No Console do GCP, acesse o Cloud Scheduler.
Clique em Criar job.

Informe os seguintes detalhes de configuração:

Configuração	Valor
Nome	`tines-audit-hourly`
Região	Selecione a mesma região da função do Cloud Run
Frequência	`0 * * * *` (a cada hora, na 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 (`tines-audit-trigger`).
Corpo da mensagem	`{}` (objeto JSON vazio)

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 * *`	Baixo volume, processamento em lote
Diário	`0 0 * * *`	Coleta de dados históricos

Testar a integração

No console do Cloud Scheduler, encontre seu job (tines-audit-hourly).
Clique em Executar à força para acionar o job manualmente.
Aguarde alguns segundos.
Acesse Cloud Run > Serviços.
Clique no nome da função (tines-audit-to-gcs).
Clique na guia Registros.

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

Fetching logs from YYYY-MM-DDTHH:MM:SS+00:00 to YYYY-MM-DDTHH:MM:SS+00:00
Page 1: Retrieved X events
Wrote X records to gs://bucket-name/tines/audit/logs_YYYYMMDD_HHMMSS.ndjson
Successfully processed X records

Acesse Cloud Storage > Buckets.
Clique no nome do bucket (tines-audit-logs).
Navegue até a pasta tines/audit/.
Verifique se um novo arquivo .ndjson foi criado com o carimbo de data/hora atual.

Se você encontrar erros nos registros:

HTTP 401: verifique as credenciais da API nas variáveis de ambiente
HTTP 403: verifique se a conta tem a permissão AUDIT_LOG_READ
HTTP 429: limitação de taxa. A função vai tentar novamente 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

Acesse Configurações do SIEM > Feeds.
Clique em Adicionar novo feed.
Clique em Configurar um único feed.
No campo Nome do feed, insira um nome para o feed (por exemplo, Tines Audit Logs).
Selecione Google Cloud Storage V2 como o Tipo de origem.
Selecione Tines como o Tipo de registro.
Clique em Receber conta de serviço. Um e-mail exclusivo da conta de serviço é exibido, por exemplo:
```
chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.com
```
Copie esse endereço de e-mail para usar na próxima etapa.

Observação: cada instância do Google SecOps tem uma conta de serviço exclusiva. Não use contas de serviço de outras documentações ou exemplos.

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

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

Acesse Cloud Storage > Buckets.
Clique no nome do bucket (tines-audit-logs).
Acesse a guia Permissões.
Clique em Conceder acesso.
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.
Clique em Salvar.

Observação: se você planeja usar a opção de exclusão "Excluir arquivos transferidos" ou "Excluir arquivos transferidos e diretórios vazios", conceda o papel Administrador de objetos do Storage em vez de Leitor de objetos do Storage.

Configurar um feed no Google SecOps para ingerir registros de auditoria do Tines

Acesse Configurações do SIEM > Feeds.
Clique em Adicionar novo feed.
Clique em Configurar um único feed.
No campo Nome do feed, insira um nome para o feed (por exemplo, Tines Audit Logs).
Selecione Google Cloud Storage V2 como o Tipo de origem.
Selecione Tines como o Tipo de registro.
Clique em Próxima.
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://tines-audit-logs/tines/audit/
```
  - Substitua:
    - tines-audit-logs: o nome do bucket do GCS.
    - tines/audit/: prefixo/caminho da pasta onde os registros são armazenados.
  Observação: sempre inclua a barra (/) no final do URI.
- 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 bem-sucedida.
  - Excluir arquivos transferidos e diretórios vazios: exclui arquivos e diretórios vazios após a transferência bem-sucedida.
    
    Observação: se você selecionar uma opção de exclusão, a conta de serviço precisará ter o papel Administrador de objetos do Storage em vez de Leitor de objetos do Storage. Atualize as permissões do IAM de acordo com a necessidade.
- Idade máxima do arquivo: inclui arquivos modificados no último número de dias. O padrão é de 180 dias.
- Namespace do recurso: o namespace do recurso.
- Rótulos de ingestão: o rótulo a ser aplicado aos eventos deste feed.
Clique em Próxima.
Revise a nova configuração do feed na tela Finalizar e clique em Enviar.

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