收集 Privacy-i 日志

支持的平台:

本文档介绍了如何使用 Google Cloud Storage V2 将 Privacy-i 日志注入到 Google Security Operations。

Privacy-i 是由 Somansa(现已被 Mitsui Bussan Secure Directions 收购)开发的端点数据隐私权和合规性监控平台。该平台可在各个端点上提供敏感数据发现、分类和政策强制执行功能。Privacy-i REST API 可通过程序化方式访问日志、突发事件报告和代理活动数据。

准备工作

请确保满足以下前提条件:

  • Google SecOps 实例
  • 已启用 Cloud Storage API 的 GCP 项目
  • 创建和管理 GCS 存储分区的权限
  • 管理 GCS 存储分区的 IAM 政策的权限
  • 创建 Cloud Run 服务、Pub/Sub 主题和 Cloud Scheduler 作业的权限
  • 对 Privacy-i 管理控制台的管理员访问权限
  • Privacy-i REST API 的 API 凭据(API 密钥或 OAuth2 凭据)

创建 Google Cloud Storage 存储桶

  1. 前往 Google Cloud 控制台
  2. 选择您的项目或创建新项目。
  3. 在导航菜单中,依次前往 Cloud Storage > 存储分区
  4. 点击创建存储分区
  5. 提供以下配置详细信息:

    设置
    为存储桶命名 输入一个全局唯一的名称(例如 privacy-i-logs
    位置类型 根据您的需求进行选择(区域级、双区域、多区域)
    位置 选择营业地点(例如 us-central1
    存储类别 标准(建议用于经常访问的日志)
    访问权限控制 均匀(推荐)
    保护工具 可选:启用对象版本控制或保留政策
  6. 点击创建

收集 Privacy-i API 凭据

获取 API 密钥

  1. 使用管理员凭据登录 Privacy-i 管理控制台
  2. 依次前往设置 > API 管理(或系统 > API 配置)。
  3. 点击 Generate API Key
  4. 输入 API 密钥的名称(例如 Google SecOps Integration)。
  5. 复制以下详细信息并将其保存在安全的位置:

    • API 密钥:生成的 API 密钥值
    • 服务器网址:Privacy-i 管理服务器网址(例如 https://privacy-i.your-domain.com

确定 API 基准网址

Privacy-i API 基准网址是您的管理服务器网址:

格式 示例
服务器网址 https://privacy-i.your-domain.com/api

测试 API 访问权限

  • 在继续进行集成之前,请先测试您的凭据:

    # Replace with your actual credentials
    PRIVACY_I_API_KEY="your-api-key"
    PRIVACY_I_BASE_URL="https://privacy-i.your-domain.com/api"
    
    # Test API access - list recent events
    curl -s -X GET "${PRIVACY_I_BASE_URL}/v1/events?limit=1" \
      -H "Authorization: Bearer ${PRIVACY_I_API_KEY}" \
      -H "Accept: application/json"
    

为 Cloud Run 函数创建服务账号

Cloud Run 函数需要一个服务账号,该账号具有写入 GCS 存储桶的权限,并且可以由 Pub/Sub 调用。

创建服务账号

  1. GCP 控制台中,依次前往 IAM 和管理 > 服务账号
  2. 点击创建服务账号
  3. 提供以下配置详细信息:
    • 服务账号名称:输入 privacy-i-logs-collector-sa
    • 服务账号说明:输入 Service account for Cloud Run function to collect Privacy-i logs
  4. 点击创建并继续
  5. 向此服务账号授予对项目的访问权限部分中,添加以下角色:
    1. 点击选择角色
    2. 搜索并选择 Storage Object Admin
    3. 点击 + 添加其他角色
    4. 搜索并选择 Cloud Run Invoker
    5. 点击 + 添加其他角色
    6. 搜索并选择 Cloud Functions Invoker
  6. 点击继续
  7. 点击完成

必须拥有这些角色,才能:

  • Storage Object Admin:将日志写入 GCS 存储桶并管理状态文件
  • Cloud Run Invoker:允许 Pub/Sub 调用函数
  • Cloud Functions Invoker:允许调用函数

授予对 GCS 存储桶的 IAM 权限

向服务账号授予对 GCS 存储桶的写入权限:

  1. 前往 Cloud Storage > 存储分区
  2. 点击您的存储桶名称(例如 privacy-i-logs)。
  3. 前往权限标签页。
  4. 点击授予访问权限
  5. 提供以下配置详细信息:
    • 添加主账号:输入服务账号电子邮件地址(例如 privacy-i-logs-collector-sa@PROJECT_ID.iam.gserviceaccount.com
    • 分配角色:选择 Storage Object Admin
  6. 点击保存

创建 Pub/Sub 主题

创建一个 Pub/Sub 主题,Cloud Scheduler 将向该主题发布消息,而 Cloud Run 函数将订阅该主题。

  1. GCP 控制台中,前往 Pub/Sub > 主题
  2. 点击创建主题
  3. 提供以下配置详细信息:
    • 主题 ID:输入 privacy-i-logs-trigger
    • 将其他设置保留为默认值
  4. 点击创建

创建 Cloud Run 函数以收集日志

Cloud Run 函数将由来自 Cloud Scheduler 的 Pub/Sub 消息触发,以从 Privacy-i REST API 中提取日志并将其写入 GCS。

  1. GCP 控制台中,前往 Cloud Run
  2. 点击创建服务
  3. 选择函数(使用内嵌编辑器创建函数)。
  4. 配置部分中,提供以下配置详细信息:

    设置
    Service 名称 privacy-i-logs-collector
    区域 选择与您的 GCS 存储桶匹配的区域(例如 us-central1
    运行时 选择 Python 3.12 或更高版本
  5. 触发器(可选)部分中:

    1. 点击 + 添加触发器
    2. 选择 Cloud Pub/Sub
    3. 选择 Cloud Pub/Sub 主题部分,选择主题 privacy-i-logs-trigger
    4. 点击保存
  6. 身份验证部分中:

    1. 选择需要进行身份验证
    2. 检查 Identity and Access Management (IAM)
  7. 向下滚动并展开容器、网络、安全性

  8. 前往安全性标签页:

    • 服务账号:选择服务账号 privacy-i-logs-collector-sa
  9. 前往容器标签页:

    1. 点击变量和密钥
    2. 为每个环境变量点击+ 添加变量
    变量名称 示例值 说明
    GCS_BUCKET privacy-i-logs GCS 存储桶名称
    GCS_PREFIX privacy-i 日志文件的前缀
    STATE_KEY privacy-i/state.json 状态文件路径
    PRIVACY_I_API_KEY your-api-key Privacy-i API 密钥
    PRIVACY_I_BASE_URL https://privacy-i.your-domain.com/api Privacy-i API 基本网址
    MAX_RECORDS 5000 每次运行的记录数上限
    PAGE_SIZE 1000 每页记录数
    LOOKBACK_HOURS 24 初始回溯期
  10. 变量和 Secret 部分中,向下滚动到请求

    • 请求超时:输入 600 秒(10 分钟)
  11. 前往设置标签页:

    • 资源部分中:
      • 内存:选择 512 MiB 或更高值
      • CPU:选择 1
  12. 修订版本伸缩部分中:

    • 实例数下限:输入 0
    • 实例数上限:输入 100(或根据预期负载进行调整)
  13. 点击创建

  14. 等待服务创建完成(1-2 分钟)。

  15. 创建服务后,系统会自动打开内嵌代码编辑器

添加函数代码

  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', 'privacy-i')
      STATE_KEY = os.environ.get('STATE_KEY', 'privacy-i/state.json')
      PRIVACY_I_API_KEY = os.environ.get('PRIVACY_I_API_KEY')
      PRIVACY_I_BASE_URL = os.environ.get('PRIVACY_I_BASE_URL')
      MAX_RECORDS = int(os.environ.get('MAX_RECORDS', '5000'))
      PAGE_SIZE = int(os.environ.get('PAGE_SIZE', '1000'))
      LOOKBACK_HOURS = int(os.environ.get('LOOKBACK_HOURS', '24'))
      
      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 Privacy-i
        inspection and incident logs and write to GCS.
      
        Args:
          cloud_event: CloudEvent object containing Pub/Sub message
        """
      
        if not all([GCS_BUCKET, PRIVACY_I_API_KEY, PRIVACY_I_BASE_URL]):
          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"])
              # Overlap by 2 minutes to catch any delayed events
              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 from multiple endpoints
          all_records = []
          newest_event_time = None
      
          for endpoint_type in ['events', 'incidents']:
            records, newest_time = fetch_logs(
              endpoint_type=endpoint_type,
              start_time=last_time,
              end_time=now,
              page_size=PAGE_SIZE,
              max_records=MAX_RECORDS,
            )
            all_records.extend(records)
            if newest_time:
              if newest_event_time is None or parse_datetime(newest_time) > parse_datetime(newest_event_time):
                newest_event_time = newest_time
      
          if not all_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 all_records]) + '\n'
          blob.upload_from_string(ndjson, content_type='application/x-ndjson')
      
          print(f"Wrote {len(all_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(all_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(endpoint_type: str, start_time: datetime, end_time: datetime, page_size: int, max_records: int):
        """
        Fetch logs from Privacy-i REST API
        with offset-based pagination and rate limiting.
      
        Args:
          endpoint_type: API endpoint type (events, incidents)
          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)
        """
        api_base = PRIVACY_I_BASE_URL.rstrip('/')
        endpoint = f"{api_base}/v1/{endpoint_type}"
      
        headers = {
          'Authorization': f'Bearer {PRIVACY_I_API_KEY}',
          'Accept': 'application/json',
          'User-Agent': 'GoogleSecOps-PrivacyICollector/1.0'
        }
      
        records = []
        newest_time = None
        page_num = 0
        offset = 0
        backoff = 1.0
      
        start_iso = start_time.strftime('%Y-%m-%dT%H:%M:%SZ')
        end_iso = end_time.strftime('%Y-%m-%dT%H:%M:%SZ')
      
        while True:
          page_num += 1
      
          if len(records) >= max_records:
            print(f"Reached max_records limit ({max_records}) for {endpoint_type}")
            break
      
          url = f"{endpoint}?startDate={start_iso}&endDate={end_iso}&limit={min(page_size, max_records - len(records))}&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 records, newest_time
      
            data = json.loads(response.data.decode('utf-8'))
      
            page_results = data.get('data', data.get('results', data.get('items', [])))
      
            if not page_results:
              print(f"No more results (empty page) for {endpoint_type}")
              break
      
            print(f"{endpoint_type} page {page_num}: Retrieved {len(page_results)} events")
      
            # Add endpoint type for identification
            for event in page_results:
              event['_privacy_i_log_type'] = endpoint_type
      
            records.extend(page_results)
      
            # Track newest event time
            for event in page_results:
              try:
                event_ts = event.get('timestamp') or event.get('eventTime') or event.get('createdAt')
                if event_ts:
                  event_time = str(event_ts)
                  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
            total = data.get('total', data.get('totalCount', 0))
            if total and (offset + len(page_results)) >= total:
              print(f"No more pages for {endpoint_type} (reached total)")
              break
      
            if len(page_results) < page_size:
              print(f"No more pages for {endpoint_type} (last page not full)")
              break
      
            offset += len(page_results)
      
          except Exception as e:
            print(f"Error fetching {endpoint_type} logs: {e}")
            return records, newest_time
      
        print(f"Retrieved {len(records)} total {endpoint_type} 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 Console 中,前往 Cloud Scheduler
  2. 点击创建作业
  3. 提供以下配置详细信息:

    设置
    名称 privacy-i-logs-collector-hourly
    区域 选择与 Cloud Run 函数相同的区域
    频率 0 * * * *(每小时一次,整点时)
    时区 选择时区(建议选择世界协调时间 [UTC])
    目标类型 Pub/Sub
    主题 选择主题 privacy-i-logs-trigger
    消息正文 {}(空 JSON 对象)
  4. 点击创建

时间表频率选项

根据日志量和延迟时间要求选择频次:

频率 Cron 表达式 使用场景
每隔 5 分钟 */5 * * * * 大批量、低延迟
每隔 15 分钟 */15 * * * * 搜索量中等
每小时 0 * * * * 标准(推荐)
每 6 小时 0 */6 * * * 低成交量、批处理
每天 0 0 * * * 历史数据收集

测试集成

  1. Cloud Scheduler 控制台中,找到您的作业。
  2. 点击强制运行以手动触发作业。
  3. 等待几秒钟。
  4. 前往 Cloud Run > 服务
  5. 点击 privacy-i-logs-collector
  6. 点击日志标签页。
  7. 验证函数是否已成功执行。请查找以下内容:

    Fetching logs from YYYY-MM-DDTHH:MM:SS+00:00 to YYYY-MM-DDTHH:MM:SS+00:00
    events page 1: Retrieved X events
    incidents page 1: Retrieved X events
    Wrote X records to gs://privacy-i-logs/privacy-i/logs_YYYYMMDD_HHMMSS.ndjson
    Successfully processed X records
    
  8. 前往 Cloud Storage > 存储分区

  9. 点击您的存储桶名称 (privacy-i-logs)。

  10. 转到 privacy-i/ 文件夹。

  11. 验证是否已创建具有当前时间戳的新 .ndjson 文件。

如果您在日志中看到错误,请执行以下操作:

  • HTTP 401:检查环境变量中的 API 密钥
  • HTTP 403:在 Privacy-i 管理控制台中验证 API 密钥是否具有所需权限
  • HTTP 429:速率限制 - 函数将自动重试并进行退避
  • 缺少环境变量:检查是否已设置所有必需的变量

在 Google SecOps 中配置 Feed 以注入 Privacy-i 日志

  1. 依次前往 SIEM 设置 > Feed
  2. 点击添加新 Feed
  3. 点击配置单个 Feed
  4. Feed 名称字段中,输入 Feed 的名称(例如 Privacy-i Logs)。
  5. 选择 Google Cloud Storage V2 作为来源类型
  6. 选择 Privacy-i 作为日志类型
  7. 点击获取服务账号。系统会显示一个唯一的服务账号电子邮件地址,例如:

    chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.com
    
  8. 复制此电子邮件地址。

  9. 点击下一步

  10. 为以下输入参数指定值:

    • 存储桶网址:输入带有前缀路径的 GCS 存储桶 URI:

      gs://privacy-i-logs/privacy-i/
      
      • 替换:
        • privacy-i-logs:您的 GCS 存储桶名称。
        • privacy-i:存储日志的可选前缀/文件夹路径(留空表示根目录)。
    • 来源删除选项:根据您的偏好选择删除选项:

      • 永不:转移后永不删除任何文件(建议用于测试)。
      • 删除已转移的文件:在成功转移后删除文件。
      • 删除已转移的文件和空目录:成功转移后删除文件和空目录。

    • 文件存在时间上限:包含在过去指定天数内修改的文件(默认值为 180 天)

    • 资产命名空间资产命名空间

    • 注入标签:要应用于此 Feed 中事件的标签

  11. 点击下一步

  12. 最终确定界面中查看新的 Feed 配置,然后点击提交

向 Google SecOps 服务账号授予 IAM 权限

  • Google SecOps 服务账号需要您的 GCS 存储桶的 Storage Object Viewer 角色。
  1. 前往 Cloud Storage > 存储分区
  2. 点击您的存储桶名称。
  3. 前往权限标签页。
  4. 点击授予访问权限
  5. 提供以下配置详细信息:
    • 添加主账号:粘贴 Google SecOps 服务账号电子邮件地址
    • 分配角色:选择 Storage Object Viewer
  6. 点击保存

UDM 映射表

日志字段 UDM 映射 逻辑
has_principal、has_target_file、has_user metadata.event_type 如果具有委托人和目标文件,则设置为 SCAN_FILE;如果具有用户,则设置为 USER_UNCATEGORIZED;如果具有委托人,则设置为 STATUS_UPDATE;否则设置为 GENERIC_EVENT
elog_incidentlogguid、efile_incidentlogguid、guid metadata.product_log_id 如果 elog_incidentlogguid 不为空,则使用该值;否则,如果 efile_incidentlogguid 不为空,则使用该值;否则,使用 guid
数据类型 metadata.product_event_type 直接复制值
productversion metadata.product_version 直接复制值
metadata.product_name 设置为“PRIVACY_I”
metadata.vendor_name 设置为“PRIVACY_I”
dfile_agentip, ip principal.asset.ip 如果不为空,则从 dfile_agentip 合并;如果不为空,则从 ip 合并
dfile_agentip, ip principal.ip 如果不为空,则从 dfile_agentip 合并;如果不为空,则从 ip 合并
dfile_computername principal.asset.asset_id 串联为“Computer:%{dfile_computername}”
computername principal.asset.hostname 串联为“Computer:%{computername}”
osserial_label、computerguid_label principal.asset.attribute.labels 从 osserial_label 和 computerguid_label 合并而来
productid principal.asset.product_object_id 直接复制值
dlog_ostype, osname principal.platform 根据 dlog_ostype 枚举 (0=WINDOWS,1=LINUX,2=MAC) 设置,然后根据 osname 正则表达式覆盖
macaddr principal.mac 从 macaddr 合并
dfile_userid、userid、admin_id principal.user.userid 设置为 dfile_userid,然后如果非空,则由 userid 覆盖,如果仍非空,则由 admin_id 覆盖
dfile_username、empname、admin_name principal.user.user_display_name 设置为 dfile_username,然后如果 empname 不为空,则将其覆盖,如果 admin_name 不为空,则再将其覆盖
dfile_deptname principal.user.department 直接复制值
logintime principal.user.last_login_time 已使用日期格式 yyyy-MM-dd HH:mm:ss 进行转换
作业 principal.user.title 直接复制值
dfile_patterninfo security_result 从 JSON 中提取并结构化为检测字段
类别 security_result.category_details 直接复制值
logtype security_result.action 直接复制值
elog_detectedapplicationname target.application 直接复制值
dfile_filecreatedtime target.file.create_time 使用日期格式 ISO8601 进行转换
dfile_fileextension target.file.mime_type 直接复制值
dfile_filename target.file.names 从 dfile_filename 合并
dfile_filesize target.file.size 转换为整数
dfile_firstscannedpath target.file.full_path 直接复制值
dfile_firstscannedtime target.file.first_seen_time 使用日期格式 ISO8601 进行转换
dfile_filemodifiedtime target.file.last_modification_time 使用日期格式 ISO8601 进行转换
efile_fileaccessedtime target.file.last_access_time 已使用日期格式 yyyy-MM-dd HH:mm:ss 进行转换
efile_resulttime target.file.last_analysis_time 使用日期格式 ISO8601 进行转换
efile_patternguid_label、dfile_dataformatname_label、dfile_filerelationguid_label、dfile_inspectcount_label、dfile_inspectendtime_label、dfile_inspectstarttime_label、dfile_inspectfilecount_label、dfile_inspectpropertycount_label、dfile_inspectpropertyfilecount_label、dfile_inspectlogtime_label、dfile_filetype_label、dlog_inspectinfo_label、dlog_inspectexaminationtype_label、dlog_inspecttype_label、dfile_encryptfiletype_label、dfile_scanlogtype_label、dfile_policyname_label、elog_mediaguid_label、elog_mediaid_label、loggroup_label、agent_id_label、logouttime_label、packageinstalledtime_label、registeredtime_label、detail_label additional.fields 从多个标签字段合并

更新日志

查看相应解析器的更改日志

需要更多帮助?获得社区成员和 Google SecOps 专业人士的解答。