Raccogliere i log della piattaforma ZeroFox
Questo documento spiega come importare i log della piattaforma ZeroFox in Google Security Operations utilizzando Google Cloud Storage. La piattaforma ZeroFox fornisce protezione dai rischi digitali monitorando e analizzando le minacce su social media, app mobile, cloud, email e altri canali digitali.
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 al tenant della piattaforma ZeroFox
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 zerofox-platform-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.
Raccogliere le credenziali della piattaforma ZeroFox
Ottenere il token di accesso personale ZeroFox
- Accedi alla piattaforma ZeroFox all'indirizzo https://cloud.zerofox.com.
- Vai a Impostazioni > Connessioni dati > Feed di dati API.
- URL diretto (dopo l'accesso): https://cloud.zerofox.com/data_connectors/api
- Nota: se non vedi questa voce di menu, contatta l'amministratore di ZeroFox per l'accesso. Il menu potrebbe anche essere etichettato come Connettori dati > Feed di dati API a seconda della versione dell'interfaccia utente del tenant.
- Fai clic su Genera token o Crea token di accesso personale.
- Fornisci i seguenti dettagli di configurazione:
- Nome: inserisci un nome descrittivo (ad esempio,
Google SecOps GCS Ingestion). - Scadenza: seleziona un periodo di rotazione in base alle norme di sicurezza della tua organizzazione.
- Autorizzazioni/Feed: seleziona le autorizzazioni di lettura per:
- Avvisi
- Feed CTI
- Altri tipi di dati da esportare
- Nome: inserisci un nome descrittivo (ad esempio,
- Fai clic su Genera.
- Copia e salva il token di accesso personale generato in una posizione sicura (non potrai visualizzarlo di nuovo).
Salva ZEROFOX_BASE_URL:
https://api.zerofox.com(valore predefinito per la maggior parte dei tenant).
Verifica le autorizzazioni
Per verificare che l'account disponga delle autorizzazioni richieste:
- Accedi alla piattaforma ZeroFox.
- Vai a Impostazioni (⚙️) > Connessioni dati > Feed di dati API.
- Se riesci a visualizzare la sezione Feed di dati API e a generare token, disponi delle autorizzazioni necessarie.
- Se non riesci a visualizzare questa opzione, contatta il tuo amministratore per concedere le autorizzazioni di accesso all'API.
Testare l'accesso API
Verifica le tue credenziali prima di procedere con l'integrazione:
# Replace with your actual credentials ZEROFOX_API_TOKEN="your-personal-access-token" ZEROFOX_BASE_URL="https://api.zerofox.com" # Test API access (example endpoint - adjust based on your data type) curl -v -H "Authorization: Bearer $ZEROFOX_API_TOKEN" \ -H "Accept: application/json" \ "$ZEROFOX_BASE_URL/v1/alerts?limit=1"
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
zerofox-logs-collector-sa. - Descrizione service account: inserisci
Service account for Cloud Run function to collect ZeroFox Platform 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:
- Amministratore oggetti Storage: scrive i log nel bucket GCS 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
Concedi autorizzazioni IAM sul bucket GCS
Concedi al service account (zerofox-logs-collector-sa) le autorizzazioni di scrittura sul bucket GCS:
- Vai a Cloud Storage > Bucket.
- Fai clic sul nome del bucket (ad esempio
zerofox-platform-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.
zerofox-logs-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
zerofox-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 ZeroFox Platform 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 zerofox-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 (
zerofox-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 (
zerofox-logs-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 Descrizione GCS_BUCKETzerofox-platform-logsNome bucket GCS GCS_PREFIXzerofox/platformPrefisso per i file di log STATE_KEYzerofox/platform/state.jsonPercorso file di stato ZEROFOX_BASE_URLhttps://api.zerofox.comURL di base dell'API ZEROFOX_API_TOKENyour-zerofox-personal-access-tokenToken di accesso personale LOOKBACK_HOURS24Periodo di ricerca iniziale PAGE_SIZE200Record per pagina MAX_PAGES20Numero massimo di pagine per esecuzione HTTP_TIMEOUT60Timeout richiesta HTTP in secondi HTTP_RETRIES3Numero di nuovi tentativi HTTP URL_TEMPLATE(facoltativo) Modello di URL personalizzato con {SINCE},{PAGE_TOKEN},{PAGE_SIZE}Nella 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 urllib3 from datetime import datetime, timezone, timedelta import time import urllib.parse # 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', 'zerofox/platform') STATE_KEY = os.environ.get('STATE_KEY', 'zerofox/platform/state.json') ZEROFOX_BASE_URL = os.environ.get('ZEROFOX_BASE_URL', 'https://api.zerofox.com') ZEROFOX_API_TOKEN = os.environ.get('ZEROFOX_API_TOKEN') LOOKBACK_HOURS = int(os.environ.get('LOOKBACK_HOURS', '24')) PAGE_SIZE = int(os.environ.get('PAGE_SIZE', '200')) 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')) URL_TEMPLATE = os.environ.get('URL_TEMPLATE', '') 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 ZeroFox Platform logs and write to GCS. Args: cloud_event: CloudEvent object containing Pub/Sub message """ if not all([GCS_BUCKET, ZEROFOX_BASE_URL, ZEROFOX_API_TOKEN]): 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_since"): try: last_time = parse_datetime(state["last_since"]) # 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_since: {e}") if last_time is None: last_time = now - timedelta(hours=LOOKBACK_HOURS) since_iso = last_time.strftime('%Y-%m-%dT%H:%M:%SZ') print(f"Fetching logs since {since_iso}") # Fetch logs records, newest_since = fetch_logs( api_base=ZEROFOX_BASE_URL, api_token=ZEROFOX_API_TOKEN, since=since_iso, page_size=PAGE_SIZE, max_pages=MAX_PAGES, ) if not records: print("No new log records found.") save_state(bucket, STATE_KEY, since_iso) 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 timestamp if newest_since: save_state(bucket, STATE_KEY, newest_since) else: save_state(bucket, STATE_KEY, since_iso) 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_since: str): """Save the last since timestamp to GCS state file.""" try: state = {'last_since': last_since} blob = bucket.blob(key) blob.upload_from_string( json.dumps(state, indent=2), content_type='application/json' ) print(f"Saved state: last_since={last_since}") except Exception as e: print(f"Warning: Could not save state: {e}") def fetch_logs(api_base: str, api_token: str, since: str, page_size: int, max_pages: int): """ Fetch logs from ZeroFox Platform API with pagination and rate limiting. Args: api_base: API base URL api_token: Personal access token since: ISO timestamp for filtering logs page_size: Number of records per page max_pages: Maximum pages to fetch Returns: Tuple of (records list, newest_since ISO string) """ # Use URL_TEMPLATE if provided, otherwise construct default alerts endpoint if URL_TEMPLATE: base_url = URL_TEMPLATE.replace("{SINCE}", urllib.parse.quote(since)) else: base_url = f"{api_base}/v1/alerts?since={urllib.parse.quote(since)}" headers = { 'Authorization': f'Bearer {api_token}', 'Accept': 'application/json', 'Content-Type': 'application/json', 'User-Agent': 'GoogleSecOps-ZeroFoxCollector/1.0' } records = [] newest_since = since page_num = 0 page_token = "" backoff = 1.0 while page_num < max_pages: page_num += 1 # Construct URL with pagination if URL_TEMPLATE: url = (base_url .replace("{PAGE_TOKEN}", urllib.parse.quote(page_token)) .replace("{PAGE_SIZE}", str(page_size))) else: url = f"{base_url}&limit={page_size}" if page_token: url += f"&page_token={urllib.parse.quote(page_token)}" attempt = 0 while attempt <= HTTP_RETRIES: 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) attempt += 1 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 records, newest_since data = json.loads(response.data.decode('utf-8')) # Extract results (try multiple possible keys) page_results = [] for key in ('results', 'data', 'alerts', 'items', 'logs', 'events'): if isinstance(data.get(key), list): page_results = data[key] break if not page_results: print(f"No more results (empty page)") return records, newest_since print(f"Page {page_num}: Retrieved {len(page_results)} events") records.extend(page_results) # Track newest timestamp for event in page_results: try: # Try multiple possible timestamp fields event_time = (event.get('timestamp') or event.get('created_at') or event.get('last_modified') or event.get('event_time') or event.get('log_time') or event.get('updated_at')) if event_time and isinstance(event_time, str): if event_time > newest_since: newest_since = event_time except Exception as e: print(f"Warning: Could not parse event time: {e}") # Check for next page token next_token = (data.get('next') or data.get('next_token') or data.get('nextPageToken') or data.get('next_page_token')) if isinstance(next_token, dict): next_token = (next_token.get('token') or next_token.get('cursor') or next_token.get('value')) if not next_token: print("No more pages (no next token)") return records, newest_since page_token = str(next_token) break except urllib3.exceptions.HTTPError as e: if attempt < HTTP_RETRIES: print(f"HTTP error (attempt {attempt + 1}/{HTTP_RETRIES}): {e}") time.sleep(1 + attempt) attempt += 1 continue else: print(f"Error fetching logs after {HTTP_RETRIES} retries: {e}") return records, newest_since except Exception as e: print(f"Error fetching logs: {e}") return records, newest_since print(f"Retrieved {len(records)} total records from {page_num} pages") return records, newest_since- Secondo file: requirements.txt::
functions-framework==3.* google-cloud-storage==2.* urllib3>=2.0.0Fai 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 (zerofox-logs-trigger) 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 zerofox-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 ( zerofox-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 (
zerofox-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 (
zerofox-logs-collector). - Fai clic sulla scheda Log.
Verifica che la funzione sia stata eseguita correttamente. Cerca quanto segue:
Fetching logs since YYYY-MM-DDTHH:MM:SSZ Page 1: Retrieved X events Wrote X records to gs://zerofox-platform-logs/zerofox/platform/logs_YYYYMMDD_HHMMSS.ndjson Successfully processed X recordsVai a Cloud Storage > Bucket.
Fai clic sul nome del bucket (
zerofox-platform-logs).Vai alla cartella del prefisso (
zerofox/platform/).Verifica che sia stato creato un nuovo file
.ndjsoncon il timestamp corrente.
Se visualizzi errori nei log:
- HTTP 401: controlla le credenziali API nelle variabili di ambiente. Verifica che il
ZEROFOX_API_TOKENsia corretto e non sia scaduto. - HTTP 403: verifica che l'account ZeroFox disponga delle autorizzazioni richieste per i feed di avvisi e CTI. Vai a Impostazioni > Connessioni dati > Feed di dati API e controlla le autorizzazioni dei token.
- HTTP 404: l'endpoint
/v1/alertspredefinito potrebbe non essere corretto per il tuo tenant. Imposta la variabile di ambienteURL_TEMPLATEin modo che corrisponda alla documentazione dell'API ZeroFox o contatta l'assistenza ZeroFox. - HTTP 429: limitazione della frequenza: la funzione verrà ritentata automaticamente con backoff esponenziale.
- Variabili di ambiente mancanti: verifica che tutte le variabili richieste siano impostate nella configurazione della funzione Cloud Run.
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,
ZeroFox Platform Logs). - Seleziona Google Cloud Storage V2 come Tipo di origine.
- Seleziona ZeroFox Platform 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 (
zerofox-platform-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 della piattaforma ZeroFox
- 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,
ZeroFox Platform Logs). - Seleziona Google Cloud Storage V2 come Tipo di origine.
- Seleziona ZeroFox Platform 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://zerofox-platform-logs/zerofox/platform/Sostituisci:
zerofox-platform-logs: il nome del bucket GCS.zerofox/platform: 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.
Hai bisogno di ulteriore assistenza? Ricevi risposte dai membri della community e dai professionisti di Google SecOps.