Raccogliere i log eventi di Bitwarden Enterprise

Parser Version: 1.0

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 soddisfare i seguenti prerequisiti:

  • Un'istanza Google SecOps
  • Accesso privilegiato 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

Recuperare 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)

Crea 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, 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

  6. Fai clic su Crea.

Raccogli 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 di 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 account di servizio per la funzione Cloud Run

La funzione Cloud Run richiede un account di servizio 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 account.
  2. Fai clic su Crea account di servizio.
  3. Fornisci i seguenti dettagli di configurazione:
    • Nome service account: inserisci bitwarden-events-collector-sa.
    • Descrizione del 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 account di servizio l'accesso al progetto, aggiungi i seguenti ruoli:
    1. Fai clic su Seleziona un ruolo.
    2. Cerca e seleziona Storage Object Admin.
    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 Cloud Functions Invoker.
  6. Fai clic su Continua.
  7. Fai clic su Fine.

Questi ruoli sono necessari per:

  • Storage Object Admin: 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 account di servizio 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 account di servizio (ad esempio, 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 Google Cloud, 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 invariate le altre impostazioni predefinite.
  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 Google Cloud, vai a Cloud Run.
  2. Fai clic su Crea servizio.
  3. Seleziona Funzione (utilizza 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)
    Tempo di esecuzione 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 account di servizio (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 Google Cloud, 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, allo scoccare dell'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 tuo job.
  2. Fai clic su Forza esecuzione per attivare il job manualmente.
  3. Attendi 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. Cerca:

    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 nei log vengono visualizzati errori:

  • 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 verrà ritentata automaticamente con backoff
  • Variabili di ambiente mancanti: controlla che tutte le variabili richieste siano impostate

Recuperare il account di servizio Google SecOps

Google SecOps utilizza un account di servizio univoco per leggere i dati dal tuo bucket GCS. Devi concedere a questo account di servizio l'accesso al tuo bucket.

Recupera l'email del account di servizio

  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à visualizzato un indirizzo email del account di servizio univoco, 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 account di servizio Google SecOps

Il account di servizio Google SecOps deve avere il ruolo Visualizzatore oggetti Storage nel tuo 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 account di servizio Google SecOps.
    • Assegna ruoli: seleziona Visualizzatore oggetti Storage.

  6. Fai clic su Salva.

Configura 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 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 Logica
actingUserId target.user.userid Se enriched.actingUser.userId è vuoto o null, 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 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 del 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 valore all'interno di target.labels con il valore di enriched.actingUser.object.
enriched.actingUser.resetPasswordEnrolled target.labels.key Imposta il valore su "ResetPasswordEnrolled" in 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 del 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 principale 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.