Coletar registros do TeamViewer

Compatível com:

Google SecOps SIEM

Este documento explica como ingerir registros do TeamViewer no Google Security Operations usando o Google Cloud Storage. O analisador extrai os eventos de auditoria dos registros formatados em JSON. Ele itera pelos detalhes do evento, mapeando propriedades específicas para campos do modelo de dados unificado (UDM, na sigla em inglês), processando informações de participantes e apresentadores e categorizando eventos com base na atividade do usuário. O analisador também realiza transformações de dados, como mesclar rótulos e converter carimbos de data/hora em um formato padronizado.

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 console de gerenciamento do TeamViewer
Licença do TeamViewer Business, Premium, Corporate ou Tensor (necessária para acesso à API)

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, `teamviewer-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.

Conferir os pré-requisitos do TeamViewer

Faça login no TeamViewer Management Console em https://login.teamviewer.com/.
Clique no ícone do usuário no canto superior direito e selecione Editar perfil.
Selecione Apps.
Clique em Criar token de script.
Informe os seguintes detalhes de configuração:
- Nome do token: insira um nome descritivo, por exemplo, Google SecOps Integration.
- Permissões: selecione as seguintes permissões:
  - Gerenciamento de contas > Ver dados da conta
  - Gerenciamento de sessões > Ver dados da sessão
  - Relatórios de conexão > Ver relatórios de conexão
Clique em Criar.
Copie e salve o token de script gerado em um local seguro.

Observação: o token de script será exibido apenas uma vez. Se você perder o token, será necessário criar outro. O token de script precisa incluir a permissão de relatórios de conexão correspondente ao escopo Connections.Read exigido por /api/v1/reports/connections.
Registre o URL base da API TeamViewer: https://webapi.teamviewer.com/api/v1

Verifique as permissões

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

Faça login no TeamViewer Management Console.
Acesse Editar perfil > Apps.
Localize o token de script na lista.
Verifique se a opção Relatórios de conexão > Ver relatórios de conexão está ativada.
Se essa permissão não estiver ativada, edite o token e adicione a permissão necessária.

Testar o acesso à API

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

# Replace with your actual script token
SCRIPT_TOKEN="your-script-token"
API_BASE="https://webapi.teamviewer.com/api/v1"

# Test API access
curl -v -H "Authorization: Bearer ${SCRIPT_TOKEN}" \
  -H "Accept: application/json" \
  "${API_BASE}/reports/connections?from_date=2024-01-01T00:00:00Z&to_date=2024-01-01T01:00:00Z"

Se você receber uma resposta 200 com dados JSON, suas credenciais estarão configuradas corretamente.

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 teamviewer-collector-sa.
- Descrição da conta de serviço: insira Service account for Cloud Run function to collect TeamViewer 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: gravar registros no bucket do GCS e gerenciar arquivos de estado - Invocador do Cloud Run: permitir que o Pub/Sub invoque a função - Invocador do Cloud Functions: permitir 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 (por exemplo, teamviewer-logs).
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, teamviewer-collector-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 teamviewer-logs-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 TeamViewer 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	`teamviewer-logs-collector`
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 (teamviewer-logs-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 (teamviewer-collector-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
`GCS_BUCKET`	`teamviewer-logs`
`GCS_PREFIX`	`teamviewer/audit/`
`STATE_KEY`	`teamviewer/audit/state.json`
`WINDOW_SECONDS`	`3600`
`HTTP_TIMEOUT`	`60`
`MAX_RETRIES`	`3`
`USER_AGENT`	`teamviewer-to-gcs/1.0`
`SCRIPT_TOKEN`	`your-script-token` (dos pré-requisitos do TeamViewer)
`API_BASE_URL`	`https://webapi.teamviewer.com/api/v1`

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 urllib.request
import urllib.parse
import urllib.error
from datetime import datetime, timezone
import time
import uuid

# Initialize Storage client
storage_client = storage.Client()

@functions_framework.cloud_event
def main(cloud_event):
    """
    Cloud Run function triggered by Pub/Sub to fetch TeamViewer audit logs and write to GCS.

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

    # Get environment variables
    bucket_name = os.environ.get('GCS_BUCKET')
    prefix = os.environ.get('GCS_PREFIX', 'teamviewer/audit/')
    state_key = os.environ.get('STATE_KEY', 'teamviewer/audit/state.json')
    window_sec = int(os.environ.get('WINDOW_SECONDS', '3600'))
    http_timeout = int(os.environ.get('HTTP_TIMEOUT', '60'))
    max_retries = int(os.environ.get('MAX_RETRIES', '3'))
    user_agent = os.environ.get('USER_AGENT', 'teamviewer-to-gcs/1.0')

    # TeamViewer API credentials
    api_base_url = os.environ.get('API_BASE_URL')
    script_token = os.environ.get('SCRIPT_TOKEN')

    if not all([bucket_name, api_base_url, script_token]):
        print('Error: Missing required environment variables')
        return

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

        # Load state (last processed timestamp)
        state = load_state(bucket, state_key)
        now = time.time()
        from_ts = float(state.get('last_to_ts') or (now - window_sec))
        to_ts = now

        print(f'Fetching TeamViewer audit data from {iso_format(from_ts)} to {iso_format(to_ts)}')

        # Build audit API URL
        url = build_audit_url(api_base_url, from_ts, to_ts)

        print(f'Fetching TeamViewer audit data from: {url}')

        # Fetch audit data with retries and pagination
        all_records = []
        offset_id = None

        while True:
            blob_data, content_type, next_offset = fetch_audit_data(
                url, script_token, user_agent, http_timeout, max_retries, offset_id
            )

            # Validate JSON data
            try:
                audit_data = json.loads(blob_data)
                records = audit_data.get('records', [])
                all_records.extend(records)
                print(f"Retrieved {len(records)} audit records (total: {len(all_records)})")

                # Check for pagination
                if next_offset and len(records) == 1000:
                    offset_id = next_offset
                    print(f"Fetching next page with offset_id: {offset_id}")
                else:
                    break

            except json.JSONDecodeError as e:
                print(f"Warning: Invalid JSON received: {e}")
                break

        if all_records:
            # Write to GCS
            key = put_audit_data(bucket, prefix, json.dumps({'records': all_records}), 
                               'application/json', from_ts, to_ts)
            print(f'Successfully wrote {len(all_records)} audit records to {key}')
        else:
            print('No audit records found')

        # Update state
        state['last_to_ts'] = to_ts
        state['last_successful_run'] = now
        save_state(bucket, state_key, state)

    except Exception as e:
        print(f'Error processing TeamViewer 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: {str(e)}')
    return {}

def save_state(bucket, key, state):
    """Save state to GCS."""
    try:
        blob = bucket.blob(key)
        blob.upload_from_string(
            json.dumps(state, separators=(',', ':')),
            content_type='application/json'
        )
    except Exception as e:
        print(f'Warning: Could not save state: {str(e)}')

def iso_format(ts):
    """Convert Unix timestamp to ISO 8601 format."""
    return time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime(ts))

def build_audit_url(api_base_url, from_ts, to_ts):
    """Build URL for TeamViewer audit API endpoint."""
    base_endpoint = f"{api_base_url.rstrip('/')}/reports/connections"
    params = {
        'from_date': iso_format(from_ts),
        'to_date': iso_format(to_ts)
    }
    query_string = urllib.parse.urlencode(params)
    return f"{base_endpoint}?{query_string}"

def fetch_audit_data(url, script_token, user_agent, http_timeout, max_retries, offset_id=None):
    """Fetch audit data from TeamViewer API with retries and pagination support."""
    # Add offset_id parameter if provided
    if offset_id:
        separator = '&' if '?' in url else '?'
        url = f"{url}{separator}offset_id={offset_id}"

    attempt = 0
    while True:
        req = urllib.request.Request(url, method='GET')
        req.add_header('User-Agent', user_agent)
        req.add_header('Authorization', f'Bearer {script_token}')
        req.add_header('Accept', 'application/json')

        try:
            with urllib.request.urlopen(req, timeout=http_timeout) as r:
                response_data = r.read()
                content_type = r.headers.get('Content-Type') or 'application/json'

                # Extract next_offset from response if present
                try:
                    data = json.loads(response_data)
                    next_offset = data.get('next_offset')
                except:
                    next_offset = None

                return response_data, content_type, next_offset

        except urllib.error.HTTPError as e:
            if e.code == 429:
                attempt += 1
                print(f'Rate limited (429) on attempt {attempt}')
                if attempt > max_retries:
                    raise
                time.sleep(min(60, 2 ** attempt) + (time.time() % 1))
            else:
                print(f'HTTP error {e.code}: {e.reason}')
                raise
        except urllib.error.URLError as e:
            attempt += 1
            print(f'URL error on attempt {attempt}: {e}')
            if attempt > max_retries:
                raise
            time.sleep(min(60, 2 ** attempt) + (time.time() % 1))

def put_audit_data(bucket, prefix, blob_data, content_type, from_ts, to_ts):
    """Write audit data to GCS."""
    ts_path = time.strftime('%Y/%m/%d', time.gmtime(to_ts))
    uniq = f"{int(time.time() * 1e6)}_{uuid.uuid4().hex[:8]}"
    key = f"{prefix}{ts_path}/teamviewer_audit_{int(from_ts)}_{int(to_ts)}_{uniq}.json"

    blob = bucket.blob(key)
    blob.metadata = {
        'source': 'teamviewer-audit',
        'from_timestamp': str(int(from_ts)),
        'to_timestamp': str(int(to_ts))
    }
    blob.upload_from_string(blob_data, content_type=content_type)

    return key

Segundo arquivo: requirements.txt:

functions-framework==3.*
google-cloud-storage==2.*

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

Observação: o endpoint /api/v1/reports/connections é limitado a 1.000 registros por chamada. A implementação lê next_offset da resposta e faz um loop com offset_id até que todos os registros sejam recuperados.

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	`teamviewer-logs-collector-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 (`teamviewer-logs-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 (teamviewer-logs-collector-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 (teamviewer-logs-collector).
Clique na guia Registros.

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

Fetching TeamViewer audit data from YYYY-MM-DDTHH:MM:SSZ to YYYY-MM-DDTHH:MM:SSZ
Retrieved X audit records (total: X)
Successfully wrote X audit records to teamviewer/audit/YYYY/MM/DD/teamviewer_audit_...json

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

Se você encontrar erros nos registros:

HTTP 401: verifique se a variável de ambiente SCRIPT_TOKEN corresponde ao token de script do TeamViewer.
HTTP 403: verifique se o token de script tem a permissão Relatórios de conexão > Ver relatórios de conexão.
HTTP 429: limitação de taxa. A função vai tentar de novo automaticamente com espera exponencial.
Variáveis de ambiente ausentes: verifique se todas as variáveis necessárias (GCS_BUCKET, API_BASE_URL, SCRIPT_TOKEN) 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, TeamViewer logs).
Selecione Google Cloud Storage V2 como o Tipo de origem.
Selecione TeamViewer 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 (teamviewer-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 do TeamViewer

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, TeamViewer logs).
Selecione Google Cloud Storage V2 como o Tipo de origem.
Selecione TeamViewer 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://teamviewer-logs/teamviewer/audit/
```
  - Substitua:
    - teamviewer-logs: o nome do bucket do GCS.
    - teamviewer/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.

Tabela de mapeamento do UDM

Campo de registro	Mapeamento do UDM	Lógica
AffectedItem	metadata.product_log_id	O valor de "AffectedItem" do registro bruto é mapeado diretamente para esse campo do UDM.
EventDetails.NewValue	principal.resource.attribute.labels.value	Se PropertyName contiver (server), NewValue será usado como o valor de um rótulo em principal.resource.attribute.labels.
EventDetails.NewValue	principal.user.user_display_name	Se PropertyName for "Name of participant", o NewValue será usado como o nome de exibição do usuário para o principal.
EventDetails.NewValue	principal.user.userid	Se "PropertyName" for "ID do participante", "NewValue" será usado como o ID do usuário para o principal.
EventDetails.NewValue	security_result.about.labels.value	Para todos os outros valores de PropertyName (exceto aqueles processados por condições específicas), o NewValue é usado como o valor de um rótulo na matriz security_result.about.labels.
EventDetails.NewValue	target.file.full_path	Se "PropertyName" for "Source file", "NewValue" será usado como o caminho completo do arquivo de destino.
EventDetails.NewValue	target.resource.attribute.labels.value	Se PropertyName contiver (client), NewValue será usado como o valor de um rótulo em target.resource.attribute.labels.
EventDetails.NewValue	target.user.user_display_name	Se "PropertyName" for "Name of presenter", o "NewValue" será analisado. Se for um número inteiro, ele será descartado. Caso contrário, ele será usado como o nome de exibição do usuário para a meta.
EventDetails.NewValue	target.user.userid	Se "PropertyName" for "ID of presenter", "NewValue" será usado como o ID do usuário para o destino.
EventDetails.PropertyName	principal.resource.attribute.labels.key	Se PropertyName contiver (server), ele será usado como a chave de um rótulo em principal.resource.attribute.labels.
EventDetails.PropertyName	security_result.about.labels.key	Para todos os outros valores de PropertyName (exceto aqueles processados por condições específicas), o PropertyName é usado como a chave de um rótulo na matriz security_result.about.labels.
EventDetails.PropertyName	target.resource.attribute.labels.key	Se "PropertyName" contiver (client), ele será usado como a chave de um rótulo em "target.resource.attribute.labels".
EventName	metadata.product_event_type	O valor de "EventName" do registro bruto é mapeado diretamente para esse campo da UDM.
Carimbo de data/hora	metadata.event_timestamp	O valor do carimbo de data/hora do registro bruto é analisado e usado como o carimbo de data/hora do evento nos metadados.
metadata.event_type		Definido como USER_UNCATEGORIZED se src_user (derivado do ID do participante) não estiver vazio. Caso contrário, será USER_RESOURCE_ACCESS.
metadata.vendor_name		Fixado no código como TEAMVIEWER.
metadata.product_name		Fixado no código como TEAMVIEWER.
network.application_protocol		Fixado no código como TEAMVIEWER.

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