收集 Virtru Email Encryption 記錄

支援的服務:

本文說明如何使用 Google Cloud Storage V2,將 Virtru Email Encryption 記錄檔擷取至 Google Security Operations。

Virtru Email Encryption 是端對端電子郵件加密平台,提供存取控管、資料遺失防護和稽核記錄功能,可保護企業通訊內容。Cloud Run 函式會定期輪詢 Virtru Audit API,將記錄以 NDJSON 格式寫入 GCS bucket,Google SecOps 則透過 GCS V2 動態饋給擷取這些記錄。

事前準備

請確認您符合下列必要條件:

  • Google SecOps 執行個體
  • 已啟用 Cloud Storage API 的 GCP 專案
  • 建立及管理 GCS bucket 的權限
  • 具備管理 GCS bucket IAM 政策的權限
  • 建立 Cloud Run 服務、Pub/Sub 主題和 Cloud Scheduler 工作的權限
  • 具備管理員權限,可存取 Virtru 資訊主頁

建立 Google Cloud Storage bucket

  1. 前往 Google Cloud 控制台。
  2. 選取專案或建立新專案。
  3. 在導覽選單中,依序前往「Cloud Storage」>「Bucket」。
  4. 按一下「建立值區」。
  5. 提供下列設定詳細資料:

    設定 值
    為 bucket 命名 輸入全域不重複的名稱 (例如 virtru-email-encryption-logs)
    位置類型 請根據需求選擇 (單一區域、雙區域、多區域)
    位置 選取位置 (例如 us-central1)
    儲存空間級別 標準 (建議用於經常存取的記錄)
    存取控管 統一 (建議)
    保護工具 選用:啟用物件版本管理或資料保留政策
  6. 點選「建立」。

收集 Virtru Email Encryption API 憑證

產生 API 權杖

  1. 以管理員身分登入 Virtru 資訊主頁。
  2. 依序前往「Settings」>「API Keys」。
  3. 按一下「產生 API 金鑰」。
  4. 輸入金鑰標籤 (例如 Google Security Operations Integration)。
  5. 複製下列詳細資料,並儲存至安全位置:
    • API 權杖:用於驗證的 API 不記名權杖。
  6. 點選「建立」。

驗證權限

如要確認帳戶具備必要權限,請按照下列步驟操作:

  1. 登入 Virtru 資訊主頁。
  2. 依序前往「Settings」>「API Keys」。
  3. 如果能看到「API 金鑰」部分並產生金鑰,代表您具備必要的管理員權限。
  4. 如果找不到這個選項,請與 Virtru 管理員聯絡,要求授予管理員存取權。

測試 API 存取權

  • 請先測試憑證,再繼續整合:

    # Replace with your actual credentials
    API_TOKEN="your-api-token"
    
    # Test API access
    curl -v -H "Authorization: Bearer ${API_TOKEN}" \
      "https://api.virtru.com/audit/api/messages?start=2024-01-01T00:00:00Z&end=2024-01-02T00:00:00Z&limit=1"
    

建立 Cloud Run 函式的服務帳戶

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

建立服務帳戶

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

這些角色適用於:

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

授予 GCS bucket 的 IAM 權限

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

  1. 依序前往「Cloud Storage」>「Bucket」。
  2. 按一下 bucket 名稱 (例如 virtru-email-encryption-logs)。
  3. 前往「權限」分頁。
  4. 按一下「授予存取權」。
  5. 提供下列設定詳細資料:
    • 新增主體:輸入服務帳戶電子郵件地址 (例如 virtru-logs-collector-sa@your-project.iam.gserviceaccount.com)。
    • 指派角色:選取「Storage 物件管理員」。
  6. 按一下「儲存」。

建立 Pub/Sub 主題

建立 Pub/Sub 主題,Cloud Scheduler 會發布至該主題,Cloud Run 函式則會訂閱該主題。

  1. 在 GCP 控制台中,依序前往「Pub/Sub」>「主題」。
  2. 按一下「建立主題」。
  3. 提供下列設定詳細資料:
    • 主題 ID:輸入 virtru-logs-trigger。
    • 其他設定保留預設值。
  4. 點選「建立」。

建立 Cloud Run 函式來收集記錄

Cloud Run 函式會由 Cloud Scheduler 的 Pub/Sub 訊息觸發,從 Virtru Audit API 擷取記錄,並寫入 GCS。

  1. 在 GCP 控制台中,前往「Cloud Run」。
  2. 按一下「Create service」(建立服務)。
  3. 選取「函式」(使用直接修改建立函式)。
  4. 在「Configure」(設定) 部分,提供下列設定詳細資料:

    設定 值
    服務名稱 virtru-logs-collector
    區域 選取與 GCS bucket 相符的區域 (例如 us-central1)
    執行階段 選取「Python 3.12」或更新版本
  5. 在「Trigger (optional)」(觸發條件 (選用)) 部分:

    1. 按一下「+ 新增觸發條件」。
    2. 選取「Cloud Pub/Sub」。
    3. 在「Select a Cloud Pub/Sub topic」(選取 Cloud Pub/Sub 主題) 中,選擇主題 virtru-logs-trigger。
    4. 按一下「儲存」。
  6. 在「Authentication」(驗證) 部分:

    1. 選取「需要驗證」。
    2. Identity and Access Management (IAM)。
  7. 向下捲動並展開「容器、網路、安全性」。

  8. 前往「安全性」分頁:

    • 「Service account」(服務帳戶):選取服務帳戶 virtru-logs-collector-sa。
  9. 前往「容器」分頁:

    1. 按一下「Variables & Secrets」(變數與密鑰)。
    2. 針對每個環境變數,按一下「+ 新增變數」:
    變數名稱 範例值 說明
    GCS_BUCKET virtru-email-encryption-logs GCS bucket 名稱
    GCS_PREFIX virtru 記錄檔的前置字串
    STATE_KEY virtru/state.json 狀態檔案路徑
    VIRTRU_API_TOKEN your-api-token Virtru API 不記名權杖
    MAX_RECORDS 10000 每次執行的記錄數上限
    PAGE_SIZE 500 每頁記錄數
    LOOKBACK_HOURS 24 初始回溯期
  10. 在「變數與密鑰」分頁中,向下捲動至「要求」:

    • 要求逾時:輸入 600 秒 (10 分鐘)。
  11. 前往「容器」的「設定」分頁:

    • 在「Resources」(資源) 部分:
      • 「記憶體」:選取「512 MiB」或以上。
      • CPU:選取「1」。
    • 按一下「完成」。
  12. 向下捲動至「Execution environment」(執行環境):

    • 選取「預設」(建議)。
  13. 在「Revision scaling」(修訂版本資源調度) 部分:

    • 「Minimum number of instances」(執行個體數量下限):輸入 0。
    • 「執行個體數量上限」:輸入 100 (或依預期負載調整)。
  14. 點選「建立」。

  15. 等待服務建立完成 (1 至 2 分鐘)。

  16. 服務建立後,內嵌程式碼編輯器會自動開啟。

新增函式程式碼

  1. 在「函式進入點」中輸入 main。
  2. 在內嵌程式碼編輯器中,建立兩個檔案:

    • 第一個檔案:main.py:
    import functions_framework
    from google.cloud import storage
    import json
    import os
    import urllib3
    from datetime import datetime, timezone, timedelta
    import time
    
    # 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', 'virtru')
    STATE_KEY = os.environ.get('STATE_KEY', 'virtru/state.json')
    API_TOKEN = os.environ.get('VIRTRU_API_TOKEN')
    MAX_RECORDS = int(os.environ.get('MAX_RECORDS', '10000'))
    PAGE_SIZE = int(os.environ.get('PAGE_SIZE', '500'))
    LOOKBACK_HOURS = int(os.environ.get('LOOKBACK_HOURS', '24'))
    
    API_BASE = 'https://api.virtru.com'
    
    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 Virtru Email Encryption
        audit logs and write to GCS.
    
        Args:
            cloud_event: CloudEvent object containing Pub/Sub message
        """
    
        if not all([GCS_BUCKET, API_TOKEN]):
            print('Error: Missing required environment variables')
            return
    
        try:
            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_event_time"):
                try:
                    last_time = parse_datetime(state["last_event_time"])
                    last_time = last_time - timedelta(minutes=2)
                except Exception as e:
                    print(f"Warning: Could not parse last_event_time: {e}")
    
            if last_time is None:
                last_time = now - timedelta(hours=LOOKBACK_HOURS)
    
            print(f"Fetching logs from {last_time.isoformat()} to {now.isoformat()}")
    
            # Fetch logs
            records, newest_event_time = fetch_logs(
                start_time=last_time,
                end_time=now,
                page_size=PAGE_SIZE,
                max_records=MAX_RECORDS,
            )
    
            if not records:
                print("No new log records found.")
                save_state(bucket, STATE_KEY, now.isoformat())
                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 event time
            if newest_event_time:
                save_state(bucket, STATE_KEY, newest_event_time)
            else:
                save_state(bucket, STATE_KEY, now.isoformat())
    
            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_event_time_iso: str):
        """Save the last event timestamp to GCS state file."""
        try:
            state = {'last_event_time': last_event_time_iso}
            blob = bucket.blob(key)
            blob.upload_from_string(
                json.dumps(state, indent=2),
                content_type='application/json'
            )
            print(f"Saved state: last_event_time={last_event_time_iso}")
        except Exception as e:
            print(f"Warning: Could not save state: {e}")
    
    def fetch_logs(start_time: datetime, end_time: datetime, page_size: int, max_records: int):
        """
        Fetch audit logs from Virtru API with pagination and rate limiting.
    
        Args:
            start_time: Start time for log query
            end_time: End time for log query
            page_size: Number of records per page
            max_records: Maximum total records to fetch
    
        Returns:
            Tuple of (records list, newest_event_time ISO string)
        """
        endpoint = f"{API_BASE}/audit/api/messages"
    
        headers = {
            'Authorization': f'Bearer {API_TOKEN}',
            'Accept': 'application/json',
            'User-Agent': 'GoogleSecOps-VirtruCollector/1.0'
        }
    
        records = []
        newest_time = None
        page_num = 0
        backoff = 1.0
        offset = 0
    
        while True:
            page_num += 1
    
            if len(records) >= max_records:
                print(f"Reached max_records limit ({max_records})")
                break
    
            start_iso = start_time.strftime('%Y-%m-%dT%H:%M:%SZ')
            end_iso = end_time.strftime('%Y-%m-%dT%H:%M:%SZ')
            current_limit = min(page_size, max_records - len(records))
    
            url = f"{endpoint}?start={start_iso}&end={end_iso}&limit={current_limit}&offset={offset}"
    
            try:
                response = http.request('GET', url, headers=headers)
    
                # 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)
                    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 [], None
    
                data = json.loads(response.data.decode('utf-8'))
    
                page_results = data if isinstance(data, list) else data.get('messages', data.get('data', []))
    
                if not page_results:
                    print(f"No more results (empty page)")
                    break
    
                print(f"Page {page_num}: Retrieved {len(page_results)} events")
                records.extend(page_results)
    
                # Track newest event time
                for event in page_results:
                    try:
                        event_time = event.get('timestamp') or event.get('date') or event.get('created')
                        if event_time:
                            if newest_time is None or parse_datetime(event_time) > parse_datetime(newest_time):
                                newest_time = event_time
                    except Exception as e:
                        print(f"Warning: Could not parse event time: {e}")
    
                # Check for more results
                if len(page_results) < page_size:
                    print(f"Reached last page (size={len(page_results)} < limit={page_size})")
                    break
    
                offset += len(page_results)
    
            except Exception as e:
                print(f"Error fetching logs: {e}")
                return [], None
    
        print(f"Retrieved {len(records)} total records from {page_num} pages")
        return records, newest_time
    
    • 第二個檔案:requirements.txt:
    functions-framework==3.*
    google-cloud-storage==2.*
    urllib3>=2.0.0
    
  3. 按一下「部署」,即可儲存並部署函式。

  4. 等待部署作業完成 (2 至 3 分鐘)。

建立 Cloud Scheduler 工作

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

  1. 在 GCP 控制台中,前往「Cloud Scheduler」。
  2. 點選「建立工作」。
  3. 提供下列設定詳細資料:

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

排程頻率選項

根據記錄量和延遲時間需求選擇頻率:

頻率 Cron 運算式 用途
每 5 分鐘 */5 * * * * 高流量、低延遲
每 15 分鐘 */15 * * * * 中等音量
每小時 0 * * * * 標準 (建議)
每 6 小時 0 */6 * * * 低量、批次處理
每天 0 0 * * * 歷來資料集合

測試整合

  1. 在 Cloud Scheduler 控制台中,找到您的工作 (virtru-logs-collector-hourly)。
  2. 按一下「強制執行」,手動觸發。
  3. 稍候幾秒,然後依序前往「Cloud Run」>「服務」>「virtru-logs-collector」>「記錄」。
  4. 確認函式是否執行成功。尋找:

    Fetching logs from YYYY-MM-DDTHH:MM:SS+00:00 to YYYY-MM-DDTHH:MM:SS+00:00
    Page 1: Retrieved X events
    Wrote X records to gs://virtru-email-encryption-logs/virtru/logs_YYYYMMDD_HHMMSS.ndjson
    Successfully processed X records
    
  5. 檢查 GCS bucket (virtru-email-encryption-logs),確認記錄已寫入。

如果記錄中顯示錯誤:

  • HTTP 401:檢查環境變數中的 API 權杖
  • HTTP 403:確認帳戶在 Virtru 資訊主頁中具備管理員權限
  • HTTP 429:頻率限制 - 函式會自動重試,並採用輪詢機制
  • 缺少環境變數:確認已設定所有必要變數

在 Google SecOps 中設定動態饋給,擷取 Virtru 電子郵件加密記錄

  1. 依序前往「設定」>「資料管理」>「動態饋給」。如果使用的是 SIEM 專用平台,請依序前往「設定」>「動態饋給」。
  2. 按一下「新增動態饋給」。
  3. 按一下「設定單一動態饋給」。
  4. 在「Feed name」(動態饋給名稱) 欄位中,輸入動態饋給名稱 (例如 Virtru Email Encryption Logs)。
  5. 選取「Google Cloud Storage V2」做為「來源類型」。
  6. 在「Log type」部分選取「Virtru Email Encryption」。
  7. 按一下「Get Service Account」。系統會顯示專屬服務帳戶電子郵件地址,例如:

    chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.com
    
  8. 複製這個電子郵件地址。後續步驟會用到。

  9. 點選「下一步」。

  10. 指定下列輸入參數的值:

    • Storage bucket URL:輸入 GCS bucket URI,並加上前置字元路徑:

      gs://virtru-email-encryption-logs/virtru/
      
      • 取代:
        • virtru-email-encryption-logs:GCS bucket 名稱。
        • virtru/::記錄檔的儲存前置字元/資料夾路徑。
    • 來源刪除選項:根據偏好選取刪除選項:

      • Never:轉移後一律不刪除任何檔案 (建議用於測試)。
      • 刪除已轉移的檔案:在成功轉移後刪除檔案。
      • 刪除已轉移的檔案和空白目錄:成功轉移後,刪除檔案和空白目錄。

    • 檔案存在時間上限:納入過去幾天內修改過的檔案 (預設為 180 天)。

    • Asset namespace:資產命名空間。

    • 擷取標籤:要套用至這個動態饋給事件的標籤。

  11. 點選「下一步」。

  12. 在「完成」畫面中檢查新的新聞動態消息設定,然後按一下「提交」。

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

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

  1. 依序前往「Cloud Storage」>「Bucket」。
  2. 按一下 bucket 名稱 (virtru-email-encryption-logs)。
  3. 前往「權限」分頁。
  4. 按一下「授予存取權」。
  5. 提供下列設定詳細資料:
    • 新增主體:貼上 Google SecOps 服務帳戶電子郵件地址。
    • 指派角色:選取「Storage 物件檢視者」。
  6. 按一下「儲存」。

UDM 對應表

記錄欄位 UDM 對應 邏輯
audit_RecordId additional.fields 已合併
audit_RecordType additional.fields 已合併
objid_label additional.fields 已合併
objtype_label additional.fields 已合併
orgId_label additional.fields 已合併
platform_label additional.fields 已合併
attributelabel.value metadata.description 直接對應
desc metadata.description 直接對應
timestamp metadata.event_timestamp 剖析為 ISO8601
has_principal metadata.event_type 對應:true → STATUS_UPDATE
has_user metadata.event_type 對應:true → USER_UNCATEGORIZED
eventMetaData.auditDataType metadata.product_event_type 直接對應
id metadata.product_log_id 直接對應
object.name network.email.subject 已合併
email network.email.to 對應:^.+@.+$ → email
clientInfo.userAgent network.http.parsed_user_agent 已重新命名/對應
clientInfo.userAgent network.http.user_agent 直接對應
prin_host principal.asset.hostname 直接對應
clientInfo.requestIp principal.asset.ip 已合併
prin_ip principal.asset.ip 已合併
actorattributes.value principal.group.email_addresses 已合併
prin_host principal.hostname 直接對應
clientInfo.requestIp principal.ip 已合併
prin_ip principal.ip 已合併
pid principal.process.pid 直接對應
actor_attri_label principal.resource.attribute.labels 已合併
actor.id principal.user.email_addresses 已合併
object.name principal.user.email_addresses 已合併
actor.id principal.user.user_display_name 直接對應
action_label security_result.detection_fields 已合併
action_result_label security_result.detection_fields 已合併
attributelabel.value src.user.user_display_name 直接對應
object.name target.file.full_path 直接對應
attributelabel.value target.group.email_addresses 已合併
attrikey target.group.email_addresses 對應:virtru:data:org:1e148cd2-139d-4d27-9891-98f7275550a2:group → attributelabel.value
attri_label target.resource.attribute.labels 已合併
email target.user.email_addresses 對應:^.+@.+$ → email
不適用 metadata.event_type 常數:EMAIL_TRANSACTION
不適用 metadata.product_name 常數:virtru encrytion
不適用 metadata.vendor_name 常數:virtru

變更記錄

查看這個剖析器的變更記錄

還有其他問題嗎?向社群成員和 Google SecOps 專業人員尋求解答。