Raccogliere i log di TeamViewer
Questo documento spiega come importare i log di TeamViewer in Google Security Operations utilizzando Google Cloud Storage. Il parser estrae gli eventi di controllo dai log formattati in JSON. Scorre i dettagli degli eventi, mappando proprietà specifiche nei campi del modello di dati unificato (UDM), gestendo le informazioni su partecipanti e relatori e classificando gli eventi in base all'attività utente. Il parser esegue anche trasformazioni dei dati, come l'unione delle etichette e la conversione dei timestamp in un formato standardizzato.
Prima di iniziare
Assicurati di soddisfare i seguenti prerequisiti:
- Un'istanza Google SecOps
- Un progetto Google Cloud con l'API Storage di Cloud abilitata
- Autorizzazioni per creare e gestire bucket Cloud Storage
- Autorizzazioni per gestire le policy IAM nei bucket Cloud Storage
- Autorizzazioni per creare servizi Cloud Run, argomenti Pub/Sub e job Cloud Scheduler
- Accesso con privilegi alla console di gestione di TeamViewer
- Licenza TeamViewer Business, Premium, Corporate o Tensor (necessaria per l'accesso all'API)
Crea un bucket Google Cloud Storage
- Vai alla console Google Cloud.
- Seleziona il tuo progetto o creane uno nuovo.
- Nel menu di navigazione, vai a Cloud Storage > Bucket.
- Fai clic su Crea bucket.
Fornisci i seguenti dettagli di configurazione:
Impostazione Valore Assegna un nome al bucket Inserisci un nome univoco globale (ad esempio teamviewer-logs).Tipo di località Scegli in base alle tue esigenze (regione singola, a due regioni, multiregionale) Località Seleziona la posizione (ad esempio, us-central1).Classe di archiviazione Standard (consigliato per i log a cui si accede di frequente) Controllo degli accessi Uniforme (consigliato) Strumenti di protezione (Facoltativo) Abilita il controllo delle versioni degli oggetti o la policy di conservazione Fai clic su Crea.
Requisiti di TeamViewer
- Accedi a TeamViewer Management Console all'indirizzo https://login.teamviewer.com/.
- Fai clic sull'icona utente nell'angolo in alto a destra e seleziona Modifica profilo.
- Seleziona App.
- Fai clic su Crea token script.
- Fornisci i seguenti dettagli di configurazione:
- Nome token: inserisci un nome descrittivo (ad esempio,
Google SecOps Integration). - Autorizzazioni: seleziona le seguenti autorizzazioni:
- Gestione dell'account > Visualizza dati dell'account
- Gestione sessioni > Visualizza dati sessione
- Report sulle connessioni > Visualizza report sulle connessioni
- Nome token: inserisci un nome descrittivo (ad esempio,
- Fai clic su Crea.
Copia e salva il token dello script generato in un luogo sicuro.
Registra l'URL di base dell'API TeamViewer:
https://webapi.teamviewer.com/api/v1
Verifica le autorizzazioni
Per verificare che l'account disponga delle autorizzazioni richieste:
- Accedi alla console di gestione di TeamViewer.
- Vai a Modifica profilo > App.
- Individua il token dello script nell'elenco.
- Verifica che l'opzione Report sulle connessioni > Visualizza report sulle connessioni sia attivata.
- Se questa autorizzazione non è abilitata, modifica il token e aggiungi l'autorizzazione richiesta.
Testare l'accesso API
Testa le tue credenziali prima di procedere con l'integrazione:
# Replace with your actual script token SCRIPT_TOKEN="your-script-token" API_BASE="https://webapi.teamviewer.com/api/v1" # Test API access curl -v -X POST -H "Authorization: Bearer ${SCRIPT_TOKEN}" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{"StartDate": "2024-01-01T00:00:00Z", "EndDate": "2024-01-01T01:00:00Z"}' \ "${API_BASE}/EventLogging"
Se ricevi una risposta 200 con dati JSON, le tue credenziali sono configurate correttamente.
Crea un account di servizio per la funzione Cloud Run
La funzione Cloud Run richiede un account di servizio con autorizzazioni di scrittura nel bucket Cloud Storage e di invocazione da parte di Pub/Sub.
Crea il account di servizio
- Nella Google Cloud console, vai a IAM e amministrazione > Service Account.
- Fai clic su Crea account di servizio.
- Fornisci i seguenti dettagli di configurazione:
- Nome service account: inserisci
teamviewer-collector-sa. - Descrizione del service account: inserisci
Service account for Cloud Run function to collect TeamViewer logs.
- Nome service account: inserisci
- Fai clic su Crea e continua.
- Nella sezione Concedi a questo account di servizio l'accesso al progetto, aggiungi i seguenti ruoli:
- Fai clic su Seleziona un ruolo.
- Cerca e seleziona Storage Object Admin.
- Fai clic su + Aggiungi un altro ruolo.
- Cerca e seleziona Cloud Run Invoker.
- Fai clic su + Aggiungi un altro ruolo.
- Cerca e seleziona Cloud Functions Invoker.
- Fai clic su Continua.
- Fai clic su Fine.
Questi ruoli sono necessari per:
- Storage Object Admin: scrive i log nel bucket Cloud Storage e gestisce i file di stato
- Cloud Run Invoker: consente a Pub/Sub di richiamare la funzione
- Cloud Functions Invoker: consente la chiamata di funzioni
Concedere le autorizzazioni IAM sul bucket Cloud Storage
Concedi all'account di servizio le autorizzazioni di scrittura sul bucket Cloud Storage:
- Vai a Cloud Storage > Bucket.
- Fai clic sul nome del bucket (ad esempio
teamviewer-logs). - Vai alla scheda Autorizzazioni.
- Fai clic su Concedi l'accesso.
- Fornisci i seguenti dettagli di configurazione:
- Aggiungi entità: inserisci l'email del account di servizio (ad esempio,
teamviewer-collector-sa@PROJECT_ID.iam.gserviceaccount.com). - Assegna i ruoli: seleziona Storage Object Admin.
- Aggiungi entità: inserisci l'email del account di servizio (ad esempio,
- Fai clic su Salva.
Crea un argomento Pub/Sub
Crea un argomento Pub/Sub a cui Cloud Scheduler pubblicherà e a cui la funzione Cloud Run si iscriverà.
- Nella Google Cloud console, vai a Pub/Sub > Argomenti.
- Fai clic su Crea argomento.
- Fornisci i seguenti dettagli di configurazione:
- ID argomento: inserisci
teamviewer-logs-trigger. - Lascia invariate le altre impostazioni predefinite.
- ID argomento: inserisci
- Fai clic su Crea.
Crea una funzione Cloud Run per raccogliere i log
La funzione Cloud Run viene attivata dai messaggi Pub/Sub di Cloud Scheduler per recuperare i log dall'API TeamViewer e li scrive in Cloud Storage.
- Nella Google Cloud console, vai a Cloud Run.
- Fai clic su Crea servizio.
- Seleziona Funzione (utilizza un editor in linea per creare una funzione).
Nella sezione Configura, fornisci i seguenti dettagli di configurazione:
Impostazione Valore Nome servizio teamviewer-logs-collectorRegione Seleziona la regione corrispondente al bucket Cloud Storage (ad esempio, us-central1)Tempo di esecuzione Seleziona Python 3.12 o versioni successive. Nella sezione Trigger (facoltativo):
- Fai clic su + Aggiungi trigger.
- Seleziona Cloud Pub/Sub.
- In Seleziona un argomento Cloud Pub/Sub, scegli l'argomento Pub/Sub (
teamviewer-logs-trigger). - Fai clic su Salva.
Nella sezione Autenticazione:
- Seleziona Richiedi autenticazione.
- Controlla Identity and Access Management (IAM).
Vai a Container, networking, sicurezza ed espandilo.
Vai alla scheda Sicurezza:
- Service account: seleziona il account di servizio (
teamviewer-collector-sa).
- Service account: seleziona il account di servizio (
Vai alla scheda Container:
- Fai clic su Variabili e secret.
- Fai clic su + Aggiungi variabile per ogni variabile di ambiente:
Nome variabile Valore di esempio GCS_BUCKETteamviewer-logsGCS_PREFIXteamviewer/audit/STATE_KEYteamviewer/audit/state.jsonWINDOW_SECONDS3600HTTP_TIMEOUT60MAX_RETRIES3USER_AGENTteamviewer-to-gcs/1.0SCRIPT_TOKENyour-script-token(dai prerequisiti di TeamViewer)API_BASE_URLhttps://webapi.teamviewer.com/api/v1Nella sezione Variabili e secret, vai a Richieste:
- Timeout richiesta: inserisci
600secondi (10 minuti).
- Timeout richiesta: inserisci
Vai alla scheda Impostazioni:
- Nella sezione Risorse:
- Memoria: seleziona 512 MiB o un valore superiore.
- CPU: seleziona 1.
- Nella sezione Risorse:
Nella sezione Scalabilità della revisione:
- Numero minimo di istanze: inserisci
0. - Numero massimo di istanze: inserisci
100(o modifica in base al carico previsto).
- Numero minimo di istanze: inserisci
Fai clic su Crea.
Attendi la creazione del servizio (1-2 minuti).
Dopo aver creato il servizio, si apre automaticamente l'editor di codice incorporato.
Aggiungi il codice per la funzione
- Inserisci main in Entry point della funzione
Nell'editor di codice incorporato, crea due file:
- Primo file: 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) print(f'Fetching TeamViewer audit data from: {url}') # Fetch audit data with retries and pagination all_records = [] continuation_token = None # Inside main() loop: while True: blob_data, content_type, next_token = fetch_audit_data( url, script_token, user_agent, http_timeout, max_retries, from_ts, to_ts, continuation_token ) # Validate JSON data try: audit_data = json.loads(blob_data) records = audit_data.get('AuditEvents', []) all_records.extend(records) print(f"Retrieved {len(records)} audit records (total: {len(all_records)})") # Check for pagination if next_token: continuation_token = next_token print(f"Fetching next page with ContinuationToken: {continuation_token}") 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({'AuditEvents': 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): """Build URL for TeamViewer audit API endpoint.""" return f"{api_base_url.rstrip('/')}/EventLogging" def fetch_audit_data(url, script_token, user_agent, http_timeout, max_retries, from_ts, to_ts, continuation_token=None): """Fetch audit data from TeamViewer API with retries and pagination support.""" # Construct JSON payload payload = { "StartDate": iso_format(from_ts), "EndDate": iso_format(to_ts) } if continuation_token: payload["ContinuationToken"] = continuation_token attempt = 0 while True: req = urllib.request.Request(url, method='POST') req.add_header('User-Agent', user_agent) req.add_header('Authorization', f'Bearer {script_token}') req.add_header('Content-Type', 'application/json') req.add_header('Accept', 'application/json') # Encode payload as bytes for POST body data = json.dumps(payload).encode('utf-8') try: with urllib.request.urlopen(req, data=data, timeout=http_timeout) as r: response_data = r.read() content_type = r.headers.get('Content-Type') or 'application/json' try: data = json.loads(response_data) next_token = data.get('ContinuationToken') except: next_token = None return response_data, content_type, next_token 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- Secondo file: requirements.txt::
functions-framework==3.* google-cloud-storage==2.*Fai clic su Esegui il deployment per salvare la funzione ed eseguirne il deployment.
Attendi il completamento del deployment (2-3 minuti).
Crea un job Cloud Scheduler
Cloud Scheduler pubblica messaggi nell'argomento Pub/Sub a intervalli regolari, attivando la funzione Cloud Run.
- Nella Google Cloud console, vai a Cloud Scheduler.
- Fai clic su Crea job.
Fornisci i seguenti dettagli di configurazione:
Impostazione Valore Nome teamviewer-logs-collector-hourlyRegione Seleziona la stessa regione della funzione Cloud Run Frequenza 0 * * * *(ogni ora, allo scoccare dell'ora)Fuso orario Seleziona il fuso orario (UTC consigliato) Tipo di target Pub/Sub Argomento Seleziona l'argomento Pub/Sub ( teamviewer-logs-trigger).Corpo del messaggio {}(oggetto JSON vuoto)Fai clic su Crea.
Opzioni di frequenza di pianificazione
Scegli la frequenza in base al volume dei log e ai requisiti di latenza:
| Frequenza | Espressione cron | Caso d'uso |
|---|---|---|
| Ogni 5 minuti | */5 * * * * |
Volume elevato, bassa latenza |
| Ogni 15 minuti | */15 * * * * |
Volume medio |
| Ogni ora | 0 * * * * |
Standard (consigliato) |
| Ogni 6 ore | 0 */6 * * * |
Volume basso, elaborazione batch |
| Ogni giorno | 0 0 * * * |
Raccolta dei dati storici |
Testare l'integrazione
- Nella console Cloud Scheduler, trova il tuo job (
teamviewer-logs-collector-hourly). - Fai clic su Forza esecuzione per attivare il job manualmente.
- Attendi alcuni secondi.
- Vai a Cloud Run > Servizi.
- Fai clic sul nome della funzione (
teamviewer-logs-collector). - Fai clic sulla scheda Log.
Verifica che la funzione sia stata eseguita correttamente. Cerca quanto segue:
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_...jsonVai a Cloud Storage > Bucket.
Fai clic sul nome del bucket (
teamviewer-logs).Vai alla cartella del prefisso (
teamviewer/audit/).Verifica che sia stato creato un nuovo file
.jsoncon il timestamp corrente.
Se nei log vengono visualizzati errori:
- HTTP 401: verifica che la variabile di ambiente
SCRIPT_TOKENcorrisponda al token dello script di TeamViewer - HTTP 403: verifica che il token dello script disponga dell'autorizzazione Report connessione > Visualizza report connessione
- HTTP 429: limitazione della frequenza: la funzione verrà ritentata automaticamente con backoff esponenziale
- Variabili di ambiente mancanti: controlla che tutte le variabili richieste (
GCS_BUCKET,API_BASE_URL,SCRIPT_TOKEN) siano impostate
Recuperare il account di servizio Google SecOps
Google SecOps utilizza un account di servizio univoco per leggere i dati dal tuo bucket Cloud Storage. Devi concedere a questo account di servizio l'accesso al tuo bucket.
Recupera l'email del account di servizio
- Vai a Impostazioni SIEM > Feed.
- Fai clic su Aggiungi nuovo feed.
- Fai clic su Configura un singolo feed.
- Nel campo Nome feed, inserisci un nome per il feed (ad esempio,
TeamViewer logs). - Seleziona Google Cloud Storage V2 come Tipo di origine.
- Seleziona TeamViewer come Tipo di log.
Fai clic su Ottieni service account. Viene visualizzata un'email del account di servizio univoca, ad esempio:
chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.comCopia questo indirizzo email per utilizzarlo nel passaggio successivo.
Concedi le autorizzazioni IAM al account di servizio Google SecOps
Il account di servizio Google SecOps deve disporre del ruolo Storage Object Viewer nel bucket Cloud Storage.
- Vai a Cloud Storage > Bucket.
- Fai clic sul nome del bucket (
teamviewer-logs). - Vai alla scheda Autorizzazioni.
- Fai clic su Concedi l'accesso.
- Fornisci i seguenti dettagli di configurazione:
- Aggiungi entità: incolla l'email del account di servizio Google SecOps.
- Assegna ruoli: seleziona Visualizzatore oggetti Storage.
Fai clic su Salva.
Configura un feed in Google SecOps per importare i log di TeamViewer
- Vai a Impostazioni SIEM > Feed.
- Fai clic su Aggiungi nuovo feed.
- Fai clic su Configura un singolo feed.
- Nel campo Nome feed, inserisci un nome per il feed (ad esempio,
TeamViewer logs). - Seleziona Google Cloud Storage V2 come Tipo di origine.
- Seleziona TeamViewer come Tipo di log.
- Fai clic su Avanti.
Specifica i valori per i seguenti parametri di input:
URL bucket di archiviazione: inserisci l'URI del bucket Cloud Storage con il percorso del prefisso:
gs://teamviewer-logs/teamviewer/audit/Sostituisci:
teamviewer-logs: il nome del bucket Cloud Storage.teamviewer/audit/: Prefisso o percorso in cui vengono archiviati i log.
Opzione di eliminazione dell'origine: seleziona l'opzione di eliminazione in base alle tue preferenze:
- Mai: non elimina mai i file dopo i trasferimenti (opzione consigliata per i test).
- Elimina file trasferiti: elimina i file dopo il trasferimento riuscito.
Elimina file trasferiti e directory vuote: elimina i file e le directory vuote dopo il trasferimento riuscito.
Età massima file: includi i file modificati nell'ultimo numero di giorni. Il valore predefinito è 180 giorni.
Spazio dei nomi dell'asset: lo spazio dei nomi dell'asset.
Etichette di importazione: l'etichetta da applicare agli eventi di questo feed.
Fai clic su Avanti.
Controlla la nuova configurazione del feed nella schermata Finalizza e poi fai clic su Invia.
Tabella di mappatura UDM
| Campo log | mappatura UDM | Logica |
|---|---|---|
| AffectedItem | metadata.product_log_id | Il valore di AffectedItem del log non elaborato viene mappato direttamente a questo campo UDM. |
| EventDetails.NewValue | principal.resource.attribute.labels.value | Se PropertyName contiene (server), NewValue viene utilizzato come valore di un'etichetta in principal.resource.attribute.labels. |
| EventDetails.NewValue | principal.user.user_display_name | Se PropertyName è Name of participant, NewValue viene utilizzato come nome visualizzato dell'utente per il principal. |
| EventDetails.NewValue | principal.user.userid | Se PropertyName è l'ID del partecipante, NewValue viene utilizzato come ID utente per il principal. |
| EventDetails.NewValue | security_result.about.labels.value | Per tutti gli altri valori PropertyName (tranne quelli gestiti da condizioni specifiche), NewValue viene utilizzato come valore di un'etichetta all'interno dell'array security_result.about.labels. |
| EventDetails.NewValue | target.file.full_path | Se PropertyName è Source file, NewValue viene utilizzato come percorso completo per il file di destinazione. |
| EventDetails.NewValue | target.resource.attribute.labels.value | Se PropertyName contiene (client), NewValue viene utilizzato come valore di un'etichetta in target.resource.attribute.labels. |
| EventDetails.NewValue | target.user.user_display_name | Se PropertyName è Name of presenter, NewValue viene analizzato. Se è un numero intero, viene ignorato. In caso contrario, viene utilizzato come nome visualizzato dell'utente per la destinazione. |
| EventDetails.NewValue | target.user.userid | Se PropertyName è ID relatore, NewValue viene utilizzato come ID utente per la destinazione. |
| EventDetails.PropertyName | principal.resource.attribute.labels.key | Se PropertyName contiene (server), PropertyName viene utilizzato come chiave di un'etichetta in principal.resource.attribute.labels. |
| EventDetails.PropertyName | security_result.about.labels.key | Per tutti gli altri valori di PropertyName (ad eccezione di quelli gestiti da condizioni specifiche), PropertyName viene utilizzato come chiave di un'etichetta all'interno dell'array security_result.about.labels. |
| EventDetails.PropertyName | target.resource.attribute.labels.key | Se PropertyName contiene (client), PropertyName viene utilizzato come chiave di un'etichetta in target.resource.attribute.labels. |
| EventName | metadata.product_event_type | Il valore di EventName del log non elaborato viene mappato direttamente a questo campo UDM. |
| Timestamp | metadata.event_timestamp | Il valore di Timestamp del log non elaborato viene analizzato e utilizzato come timestamp dell'evento nei metadati. |
| metadata.event_type | Imposta USER_UNCATEGORIZED se src_user (derivato dall'ID del partecipante) non è vuoto, altrimenti imposta USER_RESOURCE_ACCESS. | |
| metadata.vendor_name | Codificato in modo permanente su TEAMVIEWER. | |
| metadata.product_name | Codificato in modo permanente su TEAMVIEWER. | |
| network.application_protocol | Codificato in modo permanente su TEAMVIEWER. |
Log delle modifiche
Visualizza il log delle modifiche per questo parser
Hai bisogno di ulteriore assistenza? Ricevi risposte dai membri della community e dai professionisti di Google SecOps.