Raccogliere i log eventi di Bitwarden Enterprise

Supportato in:

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

  1. Nella Console di amministrazione Bitwarden, vai a Impostazioni > Informazioni sull'organizzazione > Visualizza chiave API.
  2. Copia e salva i seguenti dettagli in una posizione sicura:
    • ID client
    • Client secret
  3. 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)

Creazione di un bucket Google Cloud Storage

  1. Vai alla console Google Cloud.
  2. Seleziona il tuo progetto o creane uno nuovo.
  3. Nel menu di navigazione, vai a Cloud Storage > Bucket.
  4. Fai clic su Crea bucket.
  5. 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
  6. 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

  1. Nella console Google Cloud, vai a IAM e amministrazione > Service Accounts.
  2. Fai clic su Crea service account.
  3. 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.
  4. Fai clic su Crea e continua.
  5. Nella sezione Concedi a questo service account l'accesso al progetto, aggiungi i seguenti ruoli:
    1. Fai clic su Seleziona un ruolo.
    2. Cerca e seleziona Amministratore oggetti di archiviazione.
    3. Fai clic su + Aggiungi un altro ruolo.
    4. Cerca e seleziona Cloud Run Invoker.
    5. Fai clic su + Aggiungi un altro ruolo.
    6. Cerca e seleziona Invoker di Cloud Functions.
  6. Fai clic su Continua.
  7. 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:

  1. Vai a Cloud Storage > Bucket.
  2. Fai clic sul nome del bucket.
  3. Vai alla scheda Autorizzazioni.
  4. Fai clic su Concedi l'accesso.
  5. 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.
  6. 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à.

  1. Nella console GCP, vai a Pub/Sub > Argomenti.
  2. Fai clic su Crea argomento.
  3. Fornisci i seguenti dettagli di configurazione:
    • ID argomento: inserisci bitwarden-events-trigger.
    • Lascia le altre impostazioni sui valori predefiniti.
  4. 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.

  1. Nella console GCP, vai a Cloud Run.
  2. Fai clic su Crea servizio.
  3. Seleziona Funzione (usa un editor in linea per creare una funzione).
  4. Nella sezione Configura, fornisci i seguenti dettagli di configurazione:

    Impostazione Valore
    Nome servizio bitwarden-events-collector
    Regione Seleziona la regione corrispondente al tuo bucket GCS (ad esempio us-central1)
    Runtime Seleziona Python 3.12 o versioni successive
  5. Nella sezione Trigger (facoltativo):

    1. Fai clic su + Aggiungi trigger.
    2. Seleziona Cloud Pub/Sub.
    3. In Seleziona un argomento Cloud Pub/Sub, scegli l'argomento Pub/Sub (bitwarden-events-trigger).
    4. Fai clic su Salva.
  6. Nella sezione Autenticazione:

    1. Seleziona Richiedi autenticazione.
    2. Controlla Identity and Access Management (IAM).
  7. Scorri verso il basso ed espandi Container, networking, sicurezza.

  8. Vai alla scheda Sicurezza:

    • Service account: seleziona il service account (bitwarden-events-collector-sa).
  9. Vai alla scheda Container:

    1. Fai clic su Variabili e secret.
    2. Fai clic su + Aggiungi variabile per ogni variabile di ambiente:
    Nome variabile Valore di esempio
    GCS_BUCKET bitwarden-events
    GCS_PREFIX bitwarden/events
    STATE_KEY bitwarden/events/state.json
    BW_CLIENT_ID organization.your-client-id
    BW_CLIENT_SECRET your-client-secret
    IDENTITY_URL https://identity.bitwarden.com/connect/token
    API_BASE https://api.bitwarden.com
    MAX_PAGES 10
  10. Nella sezione Variabili e secret, scorri verso il basso fino a Richieste:

    • Timeout richiesta: inserisci 600 secondi (10 minuti).
  11. Vai alla scheda Impostazioni:

    • Nella sezione Risorse:
      • Memoria: seleziona 512 MiB o un valore superiore.
      • CPU: seleziona 1.
  12. Nella sezione Scalabilità della revisione:

    • Numero minimo di istanze: inserisci 0.
    • Numero massimo di istanze: inserisci 100 (o modifica in base al carico previsto).
  13. Fai clic su Crea.

  14. Attendi la creazione del servizio (1-2 minuti).

  15. Dopo aver creato il servizio, si apre automaticamente l'editor di codice incorporato.

Aggiungi codice per la funzione

  1. Inserisci main in Entry point della funzione
  2. 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.0
    
  3. Fai clic su Esegui il deployment per salvare la funzione ed eseguirne il deployment.

  4. 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.

  1. Nella console di GCP, vai a Cloud Scheduler.
  2. Fai clic su Crea job.
  3. Fornisci i seguenti dettagli di configurazione:

    Impostazione Valore
    Nome bitwarden-events-hourly
    Regione 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)
  4. 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

  1. Nella console Cloud Scheduler, trova il job.
  2. Fai clic su Forza esecuzione per attivare il job manualmente.
  3. Aspetta alcuni secondi.
  4. Vai a Cloud Run > Servizi.
  5. Fai clic sul nome della funzione (bitwarden-events-collector).
  6. Fai clic sulla scheda Log.
  7. 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 pages
    
  8. Vai a Cloud Storage > Bucket.

  9. Fai clic sul nome del bucket.

  10. Vai alla cartella del prefisso (bitwarden/events/).

  11. Verifica che sia stato creato un nuovo file .jsonl con 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

  1. Vai a Impostazioni SIEM > Feed.
  2. Fai clic su Aggiungi nuovo feed.
  3. Fai clic su Configura un singolo feed.
  4. Nel campo Nome feed, inserisci un nome per il feed (ad esempio, Bitwarden Events).
  5. Seleziona Google Cloud Storage V2 come Tipo di origine.
  6. Seleziona Eventi Bitwarden come Tipo di log.
  7. Fai clic su Ottieni service account. Verrà visualizzata un'email univoca del service account, ad esempio:

    chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.com
    
  8. Copia 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.

  1. Vai a Cloud Storage > Bucket.
  2. Fai clic sul nome del bucket.
  3. Vai alla scheda Autorizzazioni.
  4. Fai clic su Concedi l'accesso.
  5. Fornisci i seguenti dettagli di configurazione:
    • Aggiungi entità: incolla l'email del service account Google SecOps.
    • Assegna i ruoli: seleziona Visualizzatore oggetti Storage.
  6. Fai clic su Salva.

Configurare un feed in Google SecOps per importare i log eventi di Bitwarden Enterprise

  1. Vai a Impostazioni SIEM > Feed.
  2. Fai clic su Aggiungi nuovo feed.
  3. Fai clic su Configura un singolo feed.
  4. Nel campo Nome feed, inserisci un nome per il feed (ad esempio, Bitwarden Events).
  5. Seleziona Google Cloud Storage V2 come Tipo di origine.
  6. Seleziona Eventi Bitwarden come Tipo di log.
  7. Fai clic su Avanti.
  8. 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.

  9. Fai clic su Avanti.

  10. 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.