Raccogliere i log eventi di Bitwarden Enterprise
Questo documento spiega come importare i log eventi di Bitwarden Enterprise in Google Security Operations utilizzando Google Cloud Storage. Il parser trasforma i log eventi non elaborati in formato JSON in un formato strutturato conforme a UDM di SecOps. Estrae i campi pertinenti, come i dettagli utente, gli indirizzi IP e i tipi di eventi, mappandoli ai campi UDM corrispondenti per un'analisi della sicurezza coerente.
Prima di iniziare
Assicurati di disporre dei seguenti prerequisiti:
- Un'istanza Google SecOps
- Accesso con privilegi al tenant Bitwarden
- 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
Ottenere la chiave API e l'URL di Bitwarden
- Nella Console di amministrazione Bitwarden, vai a Impostazioni > Informazioni sull'organizzazione > Visualizza chiave API.
- Copia e salva i seguenti dettagli in una posizione sicura:
- ID client
- Client secret
Determina gli endpoint Bitwarden (in base alla regione):
- IDENTITY_URL =
https://identity.bitwarden.com/connect/token(UE:https://identity.bitwarden.eu/connect/token) - API_BASE =
https://api.bitwarden.com(UE:https://api.bitwarden.eu)
- IDENTITY_URL =
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 bitwarden-events).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 i prerequisiti dell'API Bitwarden
Hai già raccolto le credenziali dell'API Bitwarden nel passaggio precedente:
- ID client: ID client dell'organizzazione dalla Console di amministrazione Bitwarden
- Client Secret: il client secret dell'organizzazione dalla console di amministrazione di Bitwarden
- IDENTITY_URL:
https://identity.bitwarden.com/connect/token(o endpoint UE) - API_BASE:
https://api.bitwarden.com(o endpoint UE)
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
bitwarden-events-collector-sa. - Descrizione service account: inserisci
Service account for Cloud Run function to collect Bitwarden Enterprise Event 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 le autorizzazioni di scrittura sul bucket GCS:
- Vai a Cloud Storage > Bucket.
- Fai clic sul nome del bucket.
- 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.
bitwarden-events-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
bitwarden-events-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 Bitwarden Events e li scrive 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 bitwarden-events-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 (
bitwarden-events-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 (
bitwarden-events-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_BUCKETbitwarden-eventsGCS_PREFIXbitwarden/eventsSTATE_KEYbitwarden/events/state.jsonBW_CLIENT_IDorganization.your-client-idBW_CLIENT_SECRETyour-client-secretIDENTITY_URLhttps://identity.bitwarden.com/connect/tokenAPI_BASEhttps://api.bitwarden.comMAX_PAGES10Nella 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 import base64 # 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() @functions_framework.cloud_event def main(cloud_event): """ Cloud Run function triggered by Pub/Sub to fetch events from Bitwarden API 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', 'bitwarden/events').strip('/') state_key = os.environ.get('STATE_KEY', 'bitwarden/events/state.json') # Bitwarden API credentials identity_url = os.environ.get('IDENTITY_URL', 'https://identity.bitwarden.com/connect/token') api_base = os.environ.get('API_BASE', 'https://api.bitwarden.com').rstrip('/') client_id = os.environ.get('BW_CLIENT_ID') client_secret = os.environ.get('BW_CLIENT_SECRET') max_pages = int(os.environ.get('MAX_PAGES', '10')) if not all([bucket_name, client_id, client_secret]): print('Error: Missing required environment variables') return try: # Get GCS bucket bucket = storage_client.bucket(bucket_name) # Load state (continuation token) state = load_state(bucket, state_key) continuation_token = state.get('continuationToken') print(f'Processing events with continuation token: {continuation_token}') # Get OAuth token access_token = get_oauth_token(identity_url, client_id, client_secret) # Fetch events from Bitwarden API run_timestamp = int(datetime.now(timezone.utc).timestamp()) pages = 0 total_events = 0 written_files = [] while pages < max_pages: events_data = fetch_events(api_base, access_token, continuation_token) # Extract events array from API response events = events_data.get('data', []) # Only write file if there are events if events: gcs_key = write_events_jsonl(bucket, events, prefix, run_timestamp, pages) if gcs_key: written_files.append(gcs_key) total_events += len(events) pages += 1 # Check for next page token next_token = events_data.get('continuationToken') if next_token: continuation_token = next_token continue else: # No more pages break # Save state only if there are more pages to continue in next run # If we hit MAX_PAGES and there's still a continuation token, save it # Otherwise, clear the state (set to None) save_state(bucket, state_key, { 'continuationToken': continuation_token if pages >= max_pages and continuation_token else None }) print(f'Successfully processed {total_events} events across {pages} pages') print(f'Files written: {len(written_files)}') except Exception as e: print(f'Error processing events: {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), content_type='application/json' ) except Exception as e: print(f'Warning: Could not save state: {str(e)}') def get_oauth_token(identity_url, client_id, client_secret): """Get OAuth 2.0 access token from Bitwarden.""" body_data = { 'grant_type': 'client_credentials', 'scope': 'api.organization', 'client_id': client_id, 'client_secret': client_secret } encoded_data = '&'.join([f'{k}={v}' for k, v in body_data.items()]).encode('utf-8') response = http.request( 'POST', identity_url, body=encoded_data, headers={'Content-Type': 'application/x-www-form-urlencoded'} ) if response.status != 200: raise Exception(f'Failed to get OAuth token: {response.status} {response.data.decode("utf-8")}') token_data = json.loads(response.data.decode('utf-8')) return token_data['access_token'] def fetch_events(api_base, access_token, continuation_token=None): """Fetch events from Bitwarden API with pagination.""" url = f'{api_base}/public/events' if continuation_token: url += f'?continuationToken={continuation_token}' response = http.request( 'GET', url, headers={ 'Authorization': f'Bearer {access_token}', 'Accept': 'application/json' } ) if response.status == 429: retry_after = int(response.headers.get('Retry-After', '60')) print(f'Rate limited (429). Retrying after {retry_after}s...') import time time.sleep(retry_after) return fetch_events(api_base, access_token, continuation_token) if response.status != 200: raise Exception(f'Failed to fetch events: {response.status} {response.data.decode("utf-8")}') return json.loads(response.data.decode('utf-8')) def write_events_jsonl(bucket, events, prefix, run_timestamp, page_index): """ Write events in JSONL format (one JSON object per line). Only writes if there are events to write. Returns the GCS key of the written file. """ if not events: return None # Build JSONL content: one event per line lines = [json.dumps(event, separators=(',', ':')) for event in events] jsonl_content = '\n'.join(lines) + '\n' # JSONL format with trailing newline # Generate unique filename with page number to avoid conflicts timestamp_str = datetime.fromtimestamp(run_timestamp, tz=timezone.utc).strftime('%Y/%m/%d/%H%M%S') key = f'{prefix}/{timestamp_str}-page{page_index:05d}-bitwarden-events.jsonl' blob = bucket.blob(key) blob.upload_from_string( jsonl_content, content_type='application/x-ndjson' ) print(f'Wrote {len(events)} events to {key}') return key- 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 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 bitwarden-events-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 ( bitwarden-events-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 job.
- Fai clic su Forza esecuzione per attivare il job manualmente.
- Aspetta alcuni secondi.
- Vai a Cloud Run > Servizi.
- Fai clic sul nome della funzione (
bitwarden-events-collector). - Fai clic sulla scheda Log.
Verifica che la funzione sia stata eseguita correttamente. Ecco alcuni esempi da tenere in considerazione:
Processing events with continuation token: None Page 1: Retrieved X events Wrote X events to bitwarden/events/YYYY/MM/DD/HHMMSS-page00000-bitwarden-events.jsonl Successfully processed X events across 1 pagesVai a Cloud Storage > Bucket.
Fai clic sul nome del bucket.
Vai alla cartella del prefisso (
bitwarden/events/).Verifica che sia stato creato un nuovo file
.jsonlcon il timestamp corrente.
Se visualizzi errori nei log:
- HTTP 401: controlla le credenziali API nelle variabili di ambiente
- HTTP 403: verifica che l'account disponga delle autorizzazioni richieste e che la funzionalità Eventi sia attivata nelle impostazioni dell'organizzazione
- HTTP 429: limitazione della frequenza: la funzione riproverà automaticamente con backoff
- Variabili di ambiente mancanti: controlla che tutte le variabili richieste 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,
Bitwarden Events). - Seleziona Google Cloud Storage V2 come Tipo di origine.
- Seleziona Eventi Bitwarden come Tipo di log.
Fai clic su Ottieni service account. Verrà visualizzata un'email univoca del service account, 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.
- 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.
Configurare un feed in Google SecOps per importare i log eventi di Bitwarden Enterprise
- 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,
Bitwarden Events). - Seleziona Google Cloud Storage V2 come Tipo di origine.
- Seleziona Eventi Bitwarden 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://bitwarden-events/bitwarden/events/Sostituisci:
bitwarden-events: il nome del bucket GCS.bitwarden/events/: 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 |
|---|---|---|
| actingUserId | target.user.userid | Se enriched.actingUser.userId è vuoto o nullo, questo campo viene utilizzato per compilare il campo target.user.userid. |
| collectionID | security_result.detection_fields.key | Compila il campo chiave all'interno di detection_fields in security_result. |
| collectionID | security_result.detection_fields.value | Compila il campo del valore all'interno di detection_fields in security_result. |
| data | metadata.event_timestamp | Analizzato e convertito in un formato timestamp e mappato a event_timestamp. |
| enriched.actingUser.accessAll | security_result.rule_labels.key | Imposta il valore su "Access_All" in rule_labels in security_result. |
| enriched.actingUser.accessAll | security_result.rule_labels.value | Compila il campo valore all'interno di rule_labels in security_result con il valore di enriched.actingUser.accessAll convertito in stringa. |
| enriched.actingUser.email | target.user.email_addresses | Compila il campo email_addresses all'interno di target.user. |
| enriched.actingUser.id | metadata.product_log_id | Compila il campo product_log_id all'interno dei metadati. |
| enriched.actingUser.id | target.labels.key | Imposta il valore su "ID" in target.labels. |
| enriched.actingUser.id | target.labels.value | Compila il campo valore all'interno di target.labels con il valore di enriched.actingUser.id. |
| enriched.actingUser.name | target.user.user_display_name | Compila il campo user_display_name all'interno di target.user. |
| enriched.actingUser.object | target.labels.key | Imposta il valore su "Object" all'interno di target.labels. |
| enriched.actingUser.object | target.labels.value | Compila il campo del valore all'interno di target.labels con il valore di enriched.actingUser.object. |
| enriched.actingUser.resetPasswordEnrolled | target.labels.key | Imposta il valore su "ResetPasswordEnrolled" all'interno di target.labels. |
| enriched.actingUser.resetPasswordEnrolled | target.labels.value | Compila il campo valore all'interno di target.labels con il valore di enriched.actingUser.resetPasswordEnrolled convertito in stringa. |
| enriched.actingUser.twoFactorEnabled | security_result.rule_labels.key | Imposta il valore su "Two Factor Enabled" (Autenticazione a due fattori attivata) in rule_labels in security_result. |
| enriched.actingUser.twoFactorEnabled | security_result.rule_labels.value | Compila il campo valore all'interno di rule_labels in security_result con il valore di enriched.actingUser.twoFactorEnabled convertito in stringa. |
| enriched.actingUser.userId | target.user.userid | Compila il campo userid all'interno di target.user. |
| enriched.collection.id | additional.fields.key | Imposta il valore su "ID raccolta" in additional.fields. |
| enriched.collection.id | additional.fields.value.string_value | Compila il campo string_value all'interno di additional.fields con il valore di enriched.collection.id. |
| enriched.collection.object | additional.fields.key | Imposta il valore su "Collection Object" in additional.fields. |
| enriched.collection.object | additional.fields.value.string_value | Compila il campo string_value all'interno di additional.fields con il valore di enriched.collection.object. |
| enriched.type | metadata.product_event_type | Compila il campo product_event_type all'interno dei metadati. |
| groupId | target.user.group_identifiers | Aggiunge il valore all'array group_identifiers all'interno di target.user. |
| ipAddress | principal.ip | Indirizzo IP estratto dal campo e mappato a principal.ip. |
| N/D | extensions.auth | Il parser crea un oggetto vuoto. |
| N/D | metadata.event_type | Determinato in base a enriched.type e alla presenza di informazioni su entità e target. Valori possibili: USER_LOGIN, STATUS_UPDATE, GENERIC_EVENT. |
| N/D | security_result.action | Determinato in base a enriched.type. Valori possibili: ALLOW, BLOCK. |
| oggetto | additional.fields.key | Imposta il valore su "Object" in additional.fields. |
| oggetto | additional.fields.value | Compila il campo del valore all'interno di additional.fields con il valore dell'oggetto. |
Hai bisogno di ulteriore assistenza? Ricevi risposte dai membri della community e dai professionisti di Google SecOps.