收集 Bitwarden Enterprise 事件記錄

支援的國家/地區：

Google SecOps SIEM

本文說明如何使用 Google Cloud Storage，將 Bitwarden Enterprise 事件記錄檔擷取至 Google Security Operations。剖析器會將原始 JSON 格式的事件記錄轉換為符合 SecOps UDM 的結構化格式。這項功能會擷取使用者詳細資料、IP 位址和事件類型等相關欄位，並將這些欄位對應至相應的 UDM 欄位，以進行一致的安全性分析。

事前準備

請確認您已完成下列事前準備事項：

Google SecOps 執行個體
Bitwarden 租戶的特殊存取權
已啟用 Cloud Storage API 的 GCP 專案
建立及管理 GCS 值區的權限
管理 Google Cloud Storage 值區 IAM 政策的權限
建立 Cloud Run 服務、Pub/Sub 主題和 Cloud Scheduler 工作的權限

取得 Bitwarden API 金鑰和網址

在 Bitwarden 管理控制台中，依序前往「Settings」>「Organization info」>「View API key」。
複製下列詳細資料並儲存到安全位置：
- 用戶端 ID
- 用戶端密碼
根據區域決定 Bitwarden 端點：
- IDENTITY_URL = https://identity.bitwarden.com/connect/token (歐盟：https://identity.bitwarden.eu/connect/token)
- API_BASE = https://api.bitwarden.com (歐盟：https://api.bitwarden.eu)
注意： Bitwarden 企業機構通常需要啟用「事件」功能，才能使用機構活動。如果沒有透過 API 收到事件，請前往管理控制台的「設定」> 機構設定，確認已啟用「事件」。
注意： 只有機構擁有者 (以及 Bitwarden 允許的其他角色) 可以查看或輪替機構 API 金鑰。這裡使用的機構 API 金鑰必須是機構 API (範圍為 api.organization，且 client_id 以「organization.」開頭)，而非個人 API 金鑰。

建立 Google Cloud Storage 值區

前往 Google Cloud 控制台。
選取專案或建立新專案。
在導覽選單中，依序前往「Cloud Storage」>「Bucket」。
按一下「建立值區」。

請提供下列設定詳細資料：

設定	值
為 bucket 命名	輸入全域不重複的名稱 (例如 `bitwarden-events`)
位置類型	根據需求選擇 (區域、雙區域、多區域)
位置	選取位置 (例如 `us-central1`)
儲存空間級別	標準 (建議用於經常存取的記錄)
存取控管	統一 (建議)
保護工具	選用：啟用物件版本管理或保留政策

點選「建立」。

收集 Bitwarden API 先決條件

您已在上一個步驟中收集 Bitwarden API 憑證：

用戶端 ID：Bitwarden 管理控制台的機構用戶端 ID
用戶端密鑰：Bitwarden 管理控制台的機構用戶端密鑰
IDENTITY_URL：https://identity.bitwarden.com/connect/token (或歐盟端點)
API_BASE：https://api.bitwarden.com (或歐盟端點)

為 Cloud Run 函式建立服務帳戶

Cloud Run 函式需要具備 GCS bucket 寫入權限的服務帳戶，並由 Pub/Sub 叫用。

建立服務帳戶

在 GCP 主控台中，依序前往「IAM & Admin」(IAM 與管理) >「Service Accounts」(服務帳戶)。
按一下 [Create Service Account] (建立服務帳戶)。
請提供下列設定詳細資料：
- 服務帳戶名稱：輸入 bitwarden-events-collector-sa。
- 服務帳戶說明：輸入 Service account for Cloud Run function to collect Bitwarden Enterprise Event logs。
按一下「建立並繼續」。
在「將專案存取權授予這個服務帳戶」部分，新增下列角色：
1. 按一下「選擇角色」。
2. 搜尋並選取「Storage 物件管理員」。
3. 點選「+ 新增其他角色」。
4. 搜尋並選取「Cloud Run Invoker」。
5. 點選「+ 新增其他角色」。
6. 搜尋並選取「Cloud Functions Invoker」(Cloud Functions 叫用者)。
按一下「繼續」。
按一下 [完成]。

這些角色適用於：

Storage 物件管理員：將記錄檔寫入 GCS 值區，並管理狀態檔案
Cloud Run 叫用者：允許 Pub/Sub 叫用函式
Cloud Functions 叫用者：允許函式叫用

授予 GCS 值區的 IAM 權限

授予服務帳戶 GCS bucket 的寫入權限：

依序前往「Cloud Storage」>「Buckets」。
按一下 bucket 名稱。
前往「權限」分頁標籤。
按一下「授予存取權」。
請提供下列設定詳細資料：
- 新增主體：輸入服務帳戶電子郵件地址 (例如 bitwarden-events-collector-sa@PROJECT_ID.iam.gserviceaccount.com)。
- 指派角色：選取「Storage 物件管理員」。
按一下 [儲存]。

建立 Pub/Sub 主題

建立 Pub/Sub 主題，Cloud Scheduler 會將訊息發布至該主題，而 Cloud Run 函式會訂閱該主題。

在 GCP Console 中，前往「Pub/Sub」>「Topics」(主題)。
按一下「建立主題」。
請提供下列設定詳細資料：
- 主題 ID：輸入 bitwarden-events-trigger。
- 其他設定保留預設值。
點選「建立」。

建立 Cloud Run 函式來收集記錄

Cloud Run 函式會由 Cloud Scheduler 的 Pub/Sub 訊息觸發，從 Bitwarden Events API 擷取記錄，並將記錄寫入 GCS。

前往 GCP Console 的「Cloud Run」。
按一下「Create service」(建立服務)。
選取「函式」 (使用內嵌編輯器建立函式)。
在「設定」部分，提供下列設定詳細資料：

設定值

服務名稱 bitwarden-events-collector

區域選取與 GCS bucket 相符的區域 (例如 us-central1)

執行階段 選取「Python 3.12」以上版本
在「Trigger (optional)」(觸發條件 (選用)) 專區：
1. 按一下「+ 新增觸發條件」。
2. 選取「Cloud Pub/Sub」。
3. 在「選取 Cloud Pub/Sub 主題」中，選擇 Pub/Sub 主題 (bitwarden-events-trigger)。
4. 按一下 [儲存]。
在「Authentication」(驗證) 部分：
1. 選取「需要驗證」。
2. 檢查 Identity and Access Management (IAM)。
注意： 叫用函式時，Pub/Sub 會自動處理驗證。
向下捲動並展開「Containers, Networking, Security」。
前往「安全性」分頁：
- 服務帳戶：選取服務帳戶 (bitwarden-events-collector-sa)。

設定	值
服務名稱	`bitwarden-events-collector`
區域	選取與 GCS bucket 相符的區域 (例如 `us-central1`)
執行階段	選取「Python 3.12」以上版本

前往「容器」分頁：

按一下「變數與密鑰」。
針對每個環境變數，按一下「+ 新增變數」：

變數名稱	範例值
`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`

在「變數與密鑰」部分，向下捲動至「要求」：
- 要求逾時：輸入 600 秒 (10 分鐘)。
前往「設定」分頁：
- 在「資源」部分：
  - 記憶體：選取 512 MiB 以上。
  - CPU：選取 1。
在「修訂版本資源調度」部分：
- 執行個體數量下限：輸入 0。
- 「Maximum number of instances」(執行個體數量上限)：輸入 100 (或根據預期負載調整)。
點選「建立」。
等待服務建立完成 (1 到 2 分鐘)。
服務建立完成後，系統會自動開啟內嵌程式碼編輯器。

新增函式程式碼

在「Function entry point」(函式進入點) 中輸入 main

在內嵌程式碼編輯器中建立兩個檔案：

第一個檔案：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

第二個檔案：requirements.txt:

functions-framework==3.*
google-cloud-storage==2.*
urllib3>=2.0.0

點選「部署」來儲存並部署函式。
等待部署作業完成 (2 到 3 分鐘)。

注意：Pub/Sub 觸發條件設定會自動建立必要的訂閱項目和權限。
注意：Bitwarden 的 Public API 會強制執行速率限制，且在要求量偏高時可能會傳回 HTTP 429 回應。如果遇到 429 回應，函式會自動以指數輪詢方式重試。如果經常發生頻率限制，請考慮調整 MAX_PAGES 或排程頻率。

建立 Cloud Scheduler 工作

Cloud Scheduler 會定期將訊息發布至 Pub/Sub 主題，觸發 Cloud Run 函式。

前往 GCP 主控台的「Cloud Scheduler」。
點選「建立工作」。

請提供下列設定詳細資料：

設定	值
名稱	`bitwarden-events-hourly`
區域	選取與 Cloud Run 函式相同的區域
頻率	`0 * * * *` (每小時整點)
時區	選取時區 (建議使用世界標準時間)
目標類型	Pub/Sub
主題	選取 Pub/Sub 主題 (`bitwarden-events-trigger`)
郵件內文	`{}` (空白 JSON 物件)

點選「建立」。

排程頻率選項

根據記錄檔量和延遲時間要求選擇頻率：

頻率	Cron 運算式	用途
每 5 分鐘	`/5 * * *`	高容量、低延遲
每 15 分鐘檢查一次	`/15 * * *`	普通量
每小時	`0 * * * *`	標準 (建議採用)
每 6 小時	`0 /6 * *`	少量、批次處理
每日	`0 0 * * *`	歷來資料集合

測試整合項目

在 Cloud Scheduler 控制台中找出您的工作。
按一下「強制執行」，手動觸發工作。
稍等幾秒鐘。
前往「Cloud Run」>「Services」。
按一下函式名稱 (bitwarden-events-collector)。
按一下 [Logs] (記錄) 分頁標籤。

確認函式是否已順利執行。尋找：

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

依序前往「Cloud Storage」>「Buckets」。
按一下 bucket 名稱。
前往前置字元資料夾 (bitwarden/events/)。
確認是否已建立含有目前時間戳記的新 .jsonl 檔案。

如果在記錄中發現錯誤：

HTTP 401：檢查環境變數中的 API 憑證
HTTP 403：確認帳戶具備必要權限，且機構設定中已啟用「活動」功能
HTTP 429：頻率限制 - 函式會自動重試並延遲
缺少環境變數：檢查是否已設定所有必要變數

擷取 Google SecOps 服務帳戶

Google SecOps 會使用專屬服務帳戶，從 GCS bucket 讀取資料。您必須授予這個服務帳戶值區存取權。

取得服務帳戶電子郵件地址

依序前往「SIEM 設定」>「動態饋給」。
按一下「新增動態消息」。
按一下「設定單一動態饋給」。
在「動態饋給名稱」欄位中輸入動態饋給名稱 (例如 Bitwarden Events)。
選取「Google Cloud Storage V2」做為「來源類型」。
選取「Bitwarden 事件」做為「記錄類型」。
按一下「取得服務帳戶」。系統會顯示不重複的服務帳戶電子郵件地址，例如：
```
chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.com
```
複製這個電子郵件地址，以便在下一步中使用。

注意： 每個 Google SecOps 執行個體都有專屬的服務帳戶。請勿使用其他說明文件或範例中的服務帳戶。

將 IAM 權限授予 Google SecOps 服務帳戶

Google SecOps 服務帳戶需要 GCS bucket 的「Storage 物件檢視者」角色。

依序前往「Cloud Storage」>「Buckets」。
按一下 bucket 名稱。
前往「權限」分頁標籤。
按一下「授予存取權」。
請提供下列設定詳細資料：
- 新增主體：貼上 Google SecOps 服務帳戶電子郵件地址。
- 指派角色：選取「Storage 物件檢視者」。
按一下 [儲存]。

注意： 如果打算使用「刪除已轉移的檔案」或「刪除已轉移的檔案並清空目錄」刪除選項，請授予「Storage 物件管理員」角色，而非「Storage 物件檢視者」角色。

在 Google SecOps 中設定動態饋給，以便擷取 Bitwarden Enterprise 事件記錄

依序前往「SIEM 設定」>「動態饋給」。
按一下「新增動態消息」。
按一下「設定單一動態饋給」。
在「動態饋給名稱」欄位中輸入動態饋給名稱 (例如 Bitwarden Events)。
選取「Google Cloud Storage V2」做為「來源類型」。
選取「Bitwarden 事件」做為「記錄類型」。
點選 [下一步]。
指定下列輸入參數的值：
- 儲存空間 bucket URL：輸入 GCS bucket URI，並加上前置路徑：
```
gs://bitwarden-events/bitwarden/events/
```
  - 取代：
    - bitwarden-events：您的 GCS bucket 名稱。
    - bitwarden/events/：儲存記錄的前置字元/資料夾路徑。
  注意： URI 結尾一律要加上尾端斜線 (/)。
- 來源刪除選項：根據偏好設定選取刪除選項：
  - 永不：移轉後一律不刪除任何檔案 (建議用於測試)。
  - 刪除已轉移的檔案：成功轉移檔案後刪除檔案。
  - 刪除已轉移的檔案和空白目錄：成功轉移後刪除檔案和空白目錄。
    
    注意： 如果選取刪除選項，服務帳戶必須具備「Storage 物件管理員」角色，而非「Storage 物件檢視者」角色。請據此更新 IAM 權限。
- 檔案存在時間上限：包含在過去天數內修改的檔案。預設值為 180 天。
- 資產命名空間：資產命名空間。
- 擷取標籤：要套用至這個動態饋給事件的標籤。
點選 [下一步]。
在「Finalize」(完成) 畫面中檢查新的動態饋給設定，然後按一下「Submit」(提交)。

UDM 對應表

記錄欄位	UDM 對應	邏輯
actingUserId	target.user.userid	如果 enriched.actingUser.userId 為空白或空值，系統會使用這個欄位填入 target.user.userid 欄位。
collectionID	security_result.detection_fields.key	在 security_result 的 detection_fields 中填入 key 欄位。
collectionID	security_result.detection_fields.value	在 security_result 的 detection_fields 中填入值欄位。
日期	metadata.event_timestamp	系統會剖析並轉換為時間戳記格式，然後對應至 event_timestamp。
enriched.actingUser.accessAll	security_result.rule_labels.key	在 security_result 的 rule_labels 中，將值設為「Access_All」。
enriched.actingUser.accessAll	security_result.rule_labels.value	將 rule_labels 中 security_result 內的值欄位，填入從 enriched.actingUser.accessAll 轉換為字串的值。
enriched.actingUser.email	target.user.email_addresses	在 target.user 中填入 email_addresses 欄位。
enriched.actingUser.id	metadata.product_log_id	在 metadata 中填入 product_log_id 欄位。
enriched.actingUser.id	target.labels.key	將值設為 target.labels 內的「ID」。
enriched.actingUser.id	target.labels.value	使用 enriched.actingUser.id 中的值，填入 target.labels 中的值欄位。
enriched.actingUser.name	target.user.user_display_name	在 target.user 中填入 user_display_name 欄位。
enriched.actingUser.object	target.labels.key	將值設為 target.labels 內的「Object」。
enriched.actingUser.object	target.labels.value	使用 enriched.actingUser.object 中的值，填入 target.labels 中的值欄位。
enriched.actingUser.resetPasswordEnrolled	target.labels.key	在 target.labels 中將值設為「ResetPasswordEnrolled」。
enriched.actingUser.resetPasswordEnrolled	target.labels.value	將 enriched.actingUser.resetPasswordEnrolled 轉換為字串，並填入 target.labels 中的值欄位。
enriched.actingUser.twoFactorEnabled	security_result.rule_labels.key	在 security_result 的 rule_labels 中，將值設為「Two Factor Enabled」。
enriched.actingUser.twoFactorEnabled	security_result.rule_labels.value	在 security_result 的 rule_labels 中，以從 enriched.actingUser.twoFactorEnabled 轉換為字串的值，填入值欄位。
enriched.actingUser.userId	target.user.userid	在 target.user 中填入 userid 欄位。
enriched.collection.id	additional.fields.key	將值設為 additional.fields 中的「集合 ID」。
enriched.collection.id	additional.fields.value.string_value	使用 enriched.collection.id 中的值，填入 additional.fields 中的 string_value 欄位。
enriched.collection.object	additional.fields.key	將值設為 additional.fields 內的「Collection Object」。
enriched.collection.object	additional.fields.value.string_value	使用 enriched.collection.object 中的值，填入 additional.fields 中的 string_value 欄位。
enriched.type	metadata.product_event_type	在 metadata 中填入 product_event_type 欄位。
groupId	target.user.group_identifiers	將值新增至 target.user 中的 group_identifiers 陣列。
ipAddress	principal.ip	從欄位擷取的 IP 位址，並對應至 principal.ip。
不適用	extensions.auth	剖析器會建立空物件。
不適用	metadata.event_type	根據 enriched.type 和主體與目標資訊的存在與否判斷。可能的值：USER_LOGIN、STATUS_UPDATE、GENERIC_EVENT。
不適用	security_result.action	根據 enriched.type 判斷。可能的值：ALLOW、BLOCK。
物件	additional.fields.key	將 additional.fields 內的值設為「Object」。
物件	additional.fields.value	使用物件中的值填入 additional.fields 中的值欄位。

需要其他協助嗎？向社群成員和 Google SecOps 專業人員尋求答案。