Recolha registos do TeamViewer

Compatível com:

Google secops SIEM

Nota: esta funcionalidade está abrangida pelos Termos das Ofertas de Pré-DG dos Termos Específicos do serviço Google Security Operations. As funcionalidades de pré-DG podem ter suporte limitado e as alterações às funcionalidades de pré-DG podem não ser compatíveis com outras versões de pré-DG. Para mais informações, consulte as diretrizes dos serviços de apoio técnico do Google SecOps e os Termos Específicos dos Serviços do Google SecOps.

Este documento explica como carregar registos do TeamViewer para o Google Security Operations através do Amazon S3. O analisador extrai os eventos de auditoria de registos formatados em JSON. Itera os detalhes dos eventos, mapeando propriedades específicas para campos do modelo de dados unificado (UDM), processando informações de participantes e apresentadores, e categorizando eventos com base na atividade do utilizador. O analisador também realiza transformações de dados, como a união de etiquetas e a conversão de datas/horas num formato padronizado.

Antes de começar

Certifique-se de que cumpre os seguintes pré-requisitos:

• Uma instância do Google SecOps.
• Acesso privilegiado ao TeamViewer.
• Acesso privilegiado à AWS (S3, Identity and Access Management [IAM], Lambda e EventBridge).

Obtenha os pré-requisitos do TeamViewer

1. Inicie sessão na consola de gestão do TeamViewer como administrador.
2. Aceda a O meu perfil > Apps.
3. Clique em Criar app.
4. Indique os seguintes detalhes de configuração:
   • Nome da app: introduza um nome descritivo (por exemplo, Google SecOps Integration).
   • Descrição: introduza uma descrição da app.
   • Autorizações: selecione as autorizações para acesso ao registo de auditoria.
5. Clique em Criar e guarde as credenciais da API geradas numa localização segura.
6. Registe o URL base da API TeamViewer (por exemplo, https://webapi.teamviewer.com/api/v1).
7. Copie e guarde numa localização segura os seguintes detalhes:
   • CLIENT_ID
   • CLIENT_SECRET
   • API_BASE_URL

Configure o contentor do AWS S3 e o IAM para o Google SecOps

1. Crie um contentor do Amazon S3 seguindo este guia do utilizador: Criar um contentor
2. Guarde o nome e a região do contentor para referência futura (por exemplo, teamviewer-logs).
3. Crie um utilizador seguindo este guia do utilizador: criar um utilizador do IAM.
4. Selecione o utilizador criado.
5. Selecione o separador Credenciais de segurança.
6. Clique em Criar chave de acesso na secção Chaves de acesso.
7. Selecione Serviço de terceiros como Exemplo de utilização.
8. Clicar em Seguinte.
9. Opcional: adicione a etiqueta de descrição.
10. Clique em Criar chave de acesso.
11. Clique em Transferir ficheiro CSV para guardar a chave de acesso e a chave de acesso secreta para referência futura.
12. Clique em Concluído.
13. Selecione o separador Autorizações.
14. Clique em Adicionar autorizações na secção Políticas de autorizações.
15. Selecione Adicionar autorizações.
16. Selecione Anexar políticas diretamente.
17. Pesquise a política AmazonS3FullAccess.
18. Selecione a política.
19. Clicar em Seguinte.
20. Clique em Adicionar autorizações.

Configure a política e a função de IAM para carregamentos do S3

1. Na consola da AWS, aceda a IAM > Políticas.
2. Clique em Criar política > separador JSON.
3. Copie e cole a seguinte política.

4. JSON da política (substitua teamviewer-logs se tiver introduzido um nome de contentor diferente):

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "AllowPutObjects",
         "Effect": "Allow",
         "Action": "s3:PutObject",
         "Resource": "arn:aws:s3:::teamviewer-logs/*"
       },
       {
         "Sid": "AllowGetStateObject",
         "Effect": "Allow",
         "Action": "s3:GetObject",
         "Resource": "arn:aws:s3:::teamviewer-logs/teamviewer/audit/state.json"
       }
     ]
   }
   

5. Clique em Seguinte > Criar política.

6. Aceda a IAM > Funções > Criar função > Serviço AWS > Lambda.

7. Anexe a política criada recentemente.

8. Dê o nome TeamViewerToS3Role à função e clique em Criar função.

Crie a função Lambda

1. Na consola da AWS, aceda a Lambda > Functions > Create function.
2. Clique em Criar do zero.

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

   Definição	Valor
   Nome	teamviewer_to_s3
   Runtime	Python 3.13
   Arquitetura	x86_64
   Função de execução	TeamViewerToS3Role

4. Depois de criar a função, abra o separador Código, elimine o fragmento e cole o seguinte código (teamviewer_to_s3.py).

   #!/usr/bin/env python3
   # Lambda: Pull TeamViewer audit logs and store raw JSON payloads to S3
   # - Time window via {FROM}/{TO} placeholders (UTC ISO8601), URL-encoded.
   # - Preserves vendor-native JSON format for audit and session data.
   # - Retries with exponential backoff; unique S3 keys to avoid overwrites.
   
   import os, json, time, uuid, urllib.parse
   from urllib.request import Request, urlopen
   from urllib.error import URLError, HTTPError
   
   import boto3
   
   S3_BUCKET   = os.environ["S3_BUCKET"]
   S3_PREFIX   = os.environ.get("S3_PREFIX", "teamviewer/audit/")
   STATE_KEY   = os.environ.get("STATE_KEY", "teamviewer/audit/state.json")
   WINDOW_SEC  = int(os.environ.get("WINDOW_SECONDS", "3600"))  # default 1h
   HTTP_TIMEOUT= int(os.environ.get("HTTP_TIMEOUT", "60"))
   API_BASE_URL = os.environ["API_BASE_URL"]
   CLIENT_ID   = os.environ["CLIENT_ID"]
   CLIENT_SECRET = os.environ["CLIENT_SECRET"]
   MAX_RETRIES = int(os.environ.get("MAX_RETRIES", "3"))
   USER_AGENT  = os.environ.get("USER_AGENT", "teamviewer-to-s3/1.0")
   
   s3 = boto3.client("s3")
   
   def _load_state():
       try:
           obj = s3.get_object(Bucket=S3_BUCKET, Key=STATE_KEY)
           return json.loads(obj["Body"].read())
       except Exception:
           return {}
   
   def _save_state(st):
       s3.put_object(
           Bucket=S3_BUCKET,
           Key=STATE_KEY,
           Body=json.dumps(st, separators=(",", ":")).encode("utf-8"),
           ContentType="application/json",
       )
   
   def _iso(ts: float) -> str:
       return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(ts))
   
   def _get_access_token() -> str:
       # OAuth2 Client Credentials flow for TeamViewer API
       token_url = f"{API_BASE_URL.rstrip('/')}/oauth2/token"
       data = urllib.parse.urlencode({
           'grant_type': 'client_credentials',
           'client_id': CLIENT_ID,
           'client_secret': CLIENT_SECRET
       }).encode('utf-8')
   
       req = Request(token_url, data=data, method="POST")
       req.add_header("Content-Type", "application/x-www-form-urlencoded")
       req.add_header("User-Agent", USER_AGENT)
   
       with urlopen(req, timeout=HTTP_TIMEOUT) as r:
           response = json.loads(r.read())
           return response["access_token"]
   
   def _build_audit_url(from_ts: float, to_ts: float, access_token: str) -> str:
       # Build URL for TeamViewer audit API endpoint
       base_endpoint = f"{API_BASE_URL.rstrip('/')}/reports/connections"
       params = {
           "from_date": _iso(from_ts),
           "to_date": _iso(to_ts)
       }
       query_string = urllib.parse.urlencode(params)
       return f"{base_endpoint}?{query_string}"
   
   def _fetch_audit_data(url: str, access_token: str) -> tuple[bytes, str]:
       attempt = 0
       while True:
           req = Request(url, method="GET")
           req.add_header("User-Agent", USER_AGENT)
           req.add_header("Authorization", f"Bearer {access_token}")
           req.add_header("Accept", "application/json")
   
           try:
               with urlopen(req, timeout=HTTP_TIMEOUT) as r:
                   return r.read(), (r.headers.get("Content-Type") or "application/json")
           except (HTTPError, URLError) as e:
               attempt += 1
               print(f"HTTP error on attempt {attempt}: {e}")
               if attempt > MAX_RETRIES:
                   raise
               # exponential backoff with jitter
               time.sleep(min(60, 2 ** attempt) + (time.time() % 1))
   
   def _put_audit_data(blob: bytes, content_type: str, from_ts: float, to_ts: float) -> str:
       # Create unique S3 key for audit data
       ts_path = time.strftime("%Y/%m/%d", time.gmtime(to_ts))
       uniq = f"{int(time.time()*1e6)}_{uuid.uuid4().hex[:8]}"
       key = f"{S3_PREFIX}{ts_path}/teamviewer_audit_{int(from_ts)}_{int(to_ts)}_{uniq}.json"
   
       s3.put_object(
           Bucket=S3_BUCKET, 
           Key=key, 
           Body=blob, 
           ContentType=content_type,
           Metadata={
               'source': 'teamviewer-audit',
               'from_timestamp': str(int(from_ts)),
               'to_timestamp': str(int(to_ts))
           }
       )
       return key
   
   def lambda_handler(event=None, context=None):
       st = _load_state()
       now = time.time()
       from_ts = float(st.get("last_to_ts") or (now - WINDOW_SEC))
       to_ts = now
   
       # Get OAuth2 access token
       access_token = _get_access_token()
   
       url = _build_audit_url(from_ts, to_ts, access_token)
       print(f"Fetching TeamViewer audit data from: {url}")
   
       blob, ctype = _fetch_audit_data(url, access_token)
   
       # Validate that we received valid JSON data
       try:
           audit_data = json.loads(blob)
           print(f"Successfully retrieved {len(audit_data.get('records', []))} audit records")
       except json.JSONDecodeError as e:
           print(f"Warning: Invalid JSON received: {e}")
   
       key = _put_audit_data(blob, ctype, from_ts, to_ts)
   
       st["last_to_ts"] = to_ts
       st["last_successful_run"] = now
       _save_state(st)
   
       return {
           "statusCode": 200,
           "body": {
               "success": True, 
               "s3_key": key, 
               "content_type": ctype,
               "from_timestamp": from_ts,
               "to_timestamp": to_ts
           }
       }
   
   if __name__ == "__main__":
       print(lambda_handler())
   

5. Aceda a Configuração > Variáveis de ambiente.

6. Clique em Editar > Adicionar nova variável de ambiente.

7. Introduza as variáveis de ambiente fornecidas na tabela seguinte, substituindo os valores de exemplo pelos seus valores.

   Variáveis de ambiente

   Chave	Valor de exemplo
   S3_BUCKET	teamviewer-logs
   S3_PREFIX	teamviewer/audit/
   STATE_KEY	teamviewer/audit/state.json
   WINDOW_SECONDS	3600
   HTTP_TIMEOUT	60
   MAX_RETRIES	3
   USER_AGENT	teamviewer-to-s3/1.0
   API_BASE_URL	https://webapi.teamviewer.com/api/v1
   CLIENT_ID	your-client-id (do passo 2)
   CLIENT_SECRET	your-client-secret (do passo 2)

8. Depois de criar a função, permaneça na respetiva página (ou abra Lambda > Functions > a sua função).

9. Selecione o separador Configuração.

10. No painel Configuração geral, clique em Editar.

11. Altere Tempo limite para 5 minutos (300 segundos) e clique em Guardar.

Nota: o limite de tempo é um limite superior rígido, o que significa que, se a função ainda estiver em execução quando o temporizador atingir 5 minutos, o AWS Lambda termina-a. Qualquer execução mais curta termina normalmente. A faturação é feita apenas com base no tempo de execução real.

Crie um horário do EventBridge

1. Aceda a Amazon EventBridge > Scheduler > Create schedule.
2. Indique os seguintes detalhes de configuração:
   • Agenda recorrente: Taxa (1 hour).
   • Destino: a sua função Lambda teamviewer_to_s3.
   • Nome: teamviewer-audit-1h.
3. Clique em Criar programação.

(Opcional) Crie um utilizador e chaves da IAM só de leitura para o Google SecOps

1. Aceda a AWS Console > IAM > Users > Add users.
2. Clique em Adicionar utilizadores.
3. Indique os seguintes detalhes de configuração:
   • Utilizador: introduza secops-reader.
   • Tipo de acesso: selecione Chave de acesso – Acesso programático.
4. Clique em Criar utilizador.
5. Anexe a política de leitura mínima (personalizada): Users > secops-reader > Permissions > Add permissions > Attach policies directly > Create policy.

6. JSON:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": ["s3:GetObject"],
         "Resource": "arn:aws:s3:::teamviewer-logs/*"
       },
       {
         "Effect": "Allow",
         "Action": ["s3:ListBucket"],
         "Resource": "arn:aws:s3:::teamviewer-logs"
       }
     ]
   }
   

7. Nome = secops-reader-policy.

8. Clique em Criar política > procure/selecione > Seguinte > Adicionar autorizações.

9. Crie uma chave de acesso para secops-reader: Credenciais de segurança > Chaves de acesso.

10. Clique em Criar chave de acesso.

11. Transfira o CSV. (Vai colar estes valores no feed).

Configure um feed no Google SecOps para carregar registos do TeamViewer

1. Aceda a Definições do SIEM > Feeds.
2. Clique em + Adicionar novo feed.
3. No campo Nome do feed, introduza um nome para o feed (por exemplo, TeamViewer logs).
4. Selecione Amazon S3 V2 como o Tipo de origem.
5. Selecione TeamViewer como o Tipo de registo.
6. Clicar em Seguinte.
7. Especifique valores para os seguintes parâmetros de entrada:
   • URI do S3: s3://teamviewer-logs/teamviewer/audit/
   • Opções de eliminação de origens: selecione a opção de eliminação de acordo com a sua preferência.
   • Idade máxima do ficheiro: inclua ficheiros modificados no último número de dias. A predefinição é 180 dias.
   • ID da chave de acesso: chave de acesso do utilizador com acesso ao contentor do S3.
   • Chave de acesso secreta: chave secreta do utilizador com acesso ao contentor do S3.
   • Espaço de nomes do recurso: o espaço de nomes do recurso.
   • Etiquetas de carregamento: a etiqueta aplicada aos eventos deste feed.
8. Clicar em Seguinte.
9. Reveja a nova configuração do feed no ecrã Finalizar e, de seguida, clique em Enviar.

Tabela de mapeamento do UDM

Campo de registo	Mapeamento do UDM	Lógica
AffectedItem	metadata.product_log_id	O valor de AffectedItem do registo não processado é mapeado diretamente para este campo da UDM.
EventDetails.NewValue	principal.resource.attribute.labels.value	Se PropertyName contiver (server), o NewValue é usado como o valor de uma etiqueta em principal.resource.attribute.labels.
EventDetails.NewValue	principal.user.user_display_name	Se PropertyName for Name of participant, o NewValue é usado como o nome a apresentar do utilizador para o principal.
EventDetails.NewValue	principal.user.userid	Se PropertyName for ID of participant, o NewValue é usado como o ID do utilizador para o principal.
EventDetails.NewValue	security_result.about.labels.value	Para todos os outros valores de PropertyName (exceto os processados por condições específicas), o NewValue é usado como o valor de uma etiqueta na matriz security_result.about.labels.
EventDetails.NewValue	target.file.full_path	Se PropertyName for Source file, NewValue é usado como o caminho completo para o ficheiro de destino.
EventDetails.NewValue	target.resource.attribute.labels.value	Se PropertyName contiver (client), o NewValue é usado como o valor de uma etiqueta em target.resource.attribute.labels.
EventDetails.NewValue	target.user.user_display_name	Se PropertyName for Name of presenter, o NewValue é analisado. Se for um número inteiro, é ignorado. Caso contrário, é usado como o nome a apresentar do utilizador para o alvo.
EventDetails.NewValue	target.user.userid	Se PropertyName for ID of presenter, o NewValue é usado como o ID do utilizador para o destino.
EventDetails.PropertyName	principal.resource.attribute.labels.key	Se PropertyName contiver (server), PropertyName é usado como a chave de uma etiqueta em principal.resource.attribute.labels.
EventDetails.PropertyName	security_result.about.labels.key	Para todos os outros valores de PropertyName (exceto os processados por condições específicas), o PropertyName é usado como a chave de uma etiqueta na matriz security_result.about.labels.
EventDetails.PropertyName	target.resource.attribute.labels.key	Se PropertyName contiver (client), PropertyName é usado como a chave de uma etiqueta em target.resource.attribute.labels.
EventName	metadata.product_event_type	O valor de EventName do registo não processado é mapeado diretamente para este campo da UDM.
Timestamp	metadata.event_timestamp	O valor de Timestamp do registo não processado é analisado e usado como a data/hora do evento nos metadados. Definido como USER_UNCATEGORIZED se src_user (derivado de ID of participant) não estiver vazio. Caso contrário, é definido como USER_RESOURCE_ACCESS. Codificado para TEAMVIEWER. Codificado para TEAMVIEWER. Codificado para TEAMVIEWER.

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