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 in formato JSON. Itera i dettagli degli eventi, mappando proprietà specifiche ai campi Unified Data Model (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 disporre dei seguenti prerequisiti:
- Un'istanza Google SecOps
- Un progetto GCP con l'API Cloud Storage abilitata
- Autorizzazioni per creare e gestire bucket GCS
- Autorizzazioni per gestire le policy IAM nei bucket GCS
- Autorizzazioni per creare servizi Cloud Run, argomenti Pub/Sub e job Cloud Scheduler
- Accesso privilegiato alla console di gestione di TeamViewer
- Licenza TeamViewer Business, Premium, Corporate o Tensor (necessaria per l'accesso API)
Creazione di 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, doppia regione, più regioni) Località Seleziona la posizione (ad esempio, us-central1).Classe di archiviazione Standard (consigliato per i log a cui si accede di frequente) Controllo dell'accesso Uniforme (consigliato) Strumenti di protezione (Facoltativo) Attiva il controllo delle versioni degli oggetti o la policy di conservazione Fai clic su Crea.
Requisiti di TeamViewer
- Accedi alla 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 account > Visualizza dati dell'account
- Gestione delle sessioni > Visualizza i dati della 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
Verifica 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 -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 ricevi una risposta 200 con dati JSON, le tue credenziali sono configurate correttamente.
Crea un service account per la funzione Cloud Run
La funzione Cloud Run richiede un service account con autorizzazioni di scrittura nel bucket GCS e di invocazione da parte di Pub/Sub.
Crea service account
- Nella console Google Cloud, vai a IAM e amministrazione > Service Accounts.
- Fai clic su Crea service account.
- Fornisci i seguenti dettagli di configurazione:
- Nome del service account: inserisci
teamviewer-collector-sa. - Descrizione service account: inserisci
Service account for Cloud Run function to collect TeamViewer logs.
- Nome del service account: inserisci
- Fai clic su Crea e continua.
- Nella sezione Concedi a questo service account l'accesso al progetto, aggiungi i seguenti ruoli:
- Fai clic su Seleziona un ruolo.
- Cerca e seleziona Amministratore oggetti di archiviazione.
- Fai clic su + Aggiungi un altro ruolo.
- Cerca e seleziona Cloud Run Invoker.
- Fai clic su + Aggiungi un altro ruolo.
- Cerca e seleziona Invoker di Cloud Functions.
- Fai clic su Continua.
- Fai clic su Fine.
Questi ruoli sono necessari per: - Storage Object Admin: scrivere i log nel bucket GCS e gestire i file di stato - Cloud Run Invoker: consentire a Pub/Sub di richiamare la funzione - Cloud Functions Invoker: consentire la chiamata di funzioni
Concedi autorizzazioni IAM sul bucket GCS
Concedi al service account le autorizzazioni di scrittura sul bucket GCS:
- 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 service account (ad es.
teamviewer-collector-sa@PROJECT_ID.iam.gserviceaccount.com). - Assegna i ruoli: seleziona Storage Object Admin.
- Aggiungi entità: inserisci l'email del service account (ad es.
- Fai clic su Salva.
Crea argomento Pub/Sub
Crea un argomento Pub/Sub a cui Cloud Scheduler pubblicherà e a cui la funzione Cloud Run si iscriverà.
- Nella console GCP, vai a Pub/Sub > Argomenti.
- Fai clic su Crea argomento.
- Fornisci i seguenti dettagli di configurazione:
- ID argomento: inserisci
teamviewer-logs-trigger. - Lascia le altre impostazioni sui valori predefiniti.
- 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 scriverli in GCS.
- Nella console GCP, vai a Cloud Run.
- Fai clic su Crea servizio.
- Seleziona Funzione (usa 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 tuo bucket GCS (ad esempio us-central1)Runtime 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).
Scorri verso il basso ed espandi Container, networking, sicurezza.
Vai alla scheda Sicurezza:
- Service account: seleziona il service account (
teamviewer-collector-sa).
- Service account: seleziona il service account (
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, scorri verso il basso fino 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 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, 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- 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 job Cloud Scheduler
Cloud Scheduler pubblica messaggi nell'argomento Pub/Sub a intervalli regolari, attivando la funzione Cloud Run.
- Nella console di GCP, 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, all'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.
- Aspetta 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 visualizzi errori nei log:
- 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 sulle connessioni > Visualizza report sulle connessioni
- HTTP 429: limitazione della frequenza: la funzione riproverà automaticamente con backoff esponenziale
- Variabili di ambiente mancanti: verifica che tutte le variabili richieste (
GCS_BUCKET,API_BASE_URL,SCRIPT_TOKEN) siano impostate
Recuperare il service account Google SecOps
Google SecOps utilizza un service account univoco per leggere i dati dal tuo bucket GCS. Devi concedere a questo service account l'accesso al tuo bucket.
Recuperare l'email del service account
- 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 service account univoca, ad esempio:
chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.comCopia questo indirizzo email per utilizzarlo nel passaggio successivo.
Concedi le autorizzazioni IAM al service account Google SecOps
Il service account Google SecOps deve avere il ruolo Visualizzatore oggetti Storage nel bucket GCS.
- 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 service account Google SecOps.
- Assegna i 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 del bucket di archiviazione: inserisci l'URI del bucket GCS con il percorso del prefisso:
gs://teamviewer-logs/teamviewer/audit/Sostituisci:
teamviewer-logs: il nome del bucket GCS.teamviewer/audit/: il percorso del prefisso/della cartella in cui sono 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 del 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 | Funzione 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 di 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. |
| Nome evento | 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 in TEAMVIEWER. | |
| metadata.product_name | Codificato in modo permanente in TEAMVIEWER. | |
| network.application_protocol | Codificato in modo permanente in TEAMVIEWER. |
Hai bisogno di ulteriore assistenza? Ricevi risposte dai membri della community e dai professionisti di Google SecOps.