收集 CloudM 日志

解析器版本:6.0

支持的国家/地区:

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

CloudM 是一个适用于 Google Workspace 和 Microsoft 365 的 SaaS 平台,可为用户入职和离职、数据备份、归档和迁移提供工作流自动化。CloudM Automate 会生成一份完整的审核日志,记录在您的网域中执行的所有操作,包括用户管理事件、离职工作流步骤、配置更改和安全相关操作。过去一年的审计日志数据会保留。

准备工作

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

  • Google SecOps 实例
  • 启用了 Cloud Storage API 的 Google Cloud 项目
  • 创建和管理 Cloud Storage 存储桶的权限
  • 管理 Cloud Storage 存储桶上的 Identity and Access Management (IAM) 政策的权限
  • 创建 Cloud Run 服务、Pub/Sub 主题和 Cloud Scheduler 作业的权限
  • 对 CloudM Automate 实例的管理员访问权限,以及修改全局设置权限
  • 您的 CloudM Automate 实例网址(例如 yourcompany.cloudm.io)
  • 您的 CloudM 网域 ID

收集 CloudM Automate 凭据

创建用于 API 日志访问的自定义角色

  1. 登录您的 CloudM Automate 实例。
  2. 前往设置 > 角色。
  3. 点击添加角色以创建新角色。
  4. 在角色名称字段中,输入一个描述性名称(例如 Google SecOps Log Reader)。
  5. 在权限列表中,启用以下权限:

    • 查看日志:授予查看所有应用日志的权限。
  6. 保存该角色。

创建服务账号并分配角色

  1. 在 CloudM Automate 中,依次前往设置 > 角色。
  2. 创建或确定要用于 API 访问的服务账号。
  3. 将 Google SecOps Log Reader 角色分配给服务账号。
  4. 确保该角色是在全局范围内分配的,以便服务账号可以访问整个网域中的日志。

获取服务账号访问令牌

  1. 为服务账号生成访问令牌。
  2. 在向 CloudM Logs API 发出 API 请求时,访问令牌会作为不记名令牌在 Authorization 标头中使用。
  3. 记录以下值:

    • Automate 实例网址:您的 CloudM Automate 实例网址(例如 yourcompany.cloudm.io)
    • 网域 ID:您的 CloudM 网域标识符
    • 服务账号访问令牌:用于 API 身份验证的不记名令牌

验证权限

如需验证账号是否具有所需权限,请执行以下操作:

  1. 登录 CloudM Automate。
  2. 前往设置 > 角色。
  3. 验证服务账号是否具有在全局范围内分配的查看日志权限。
  4. 如果您看不到此选项,请联系管理员,让其授予您修改全局设置和查看日志权限。

测试 API 访问权限

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

    # Replace with your actual credentials
    CLOUDM_INSTANCE="yourcompany.cloudm.io"
    DOMAIN_ID="your-domain-id"
    ACCESS_TOKEN="your-access-token"
    
    # Test API access
    curl -v -H "Authorization: Bearer ${ACCESS_TOKEN}" \
      "https://${CLOUDM_INSTANCE}/_ah/api/events/v1/${DOMAIN_ID}?from=$(date -u +%Y-%m-%d)&to=$(date -u +%Y-%m-%d)"
    

    成功的响应会返回一个包含审核日志事件的 JSON 数组。

所需 API 权限

  • 服务账号需要具有以下权限:

    权限 访问权限级别 用途
    查看日志 全球 从 CloudM Automate 检索所有审核日志事件

创建 Cloud Storage 存储桶

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

    设置 值
    指定存储桶的名称 输入一个全局唯一的名称(例如 cloudm-audit-logs)
    位置类型 根据您的需求进行选择(单区域、双区域、多区域)
    位置 选择位置(例如 us-central1)
    存储类别 标准(推荐用于频繁访问的日志)
    访问权限控制 统一(推荐)
    保护工具 可选:启用对象版本控制或保留政策
  6. 点击创建。

为 Cloud Run 函数创建服务账号

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

创建服务账号

  1. 在 Google Cloud 控制台中,依次前往 IAM 和管理 > 服务账号。
  2. 点击创建服务账号。
  3. 提供以下配置详细信息:
    • 服务账号名称:输入 cloudm-audit-collector-sa
    • 服务账号说明:输入 Service account for Cloud Run function to collect CloudM audit logs
  4. 点击创建并继续。
  5. 在为此服务账号授予项目访问权限部分,添加以下角色:

    1. 点击选择角色。
    2. 搜索并选择 Storage Object Admin。
    3. 点击 + 添加其他角色。
    4. 搜索并选择 Cloud Run Invoker。
    5. 点击 + 添加其他角色。
    6. 搜索并选择 Cloud Functions Invoker。
  6. 点击继续。

  7. 点击完成。

    以下操作需要这些角色:

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

授予对 Cloud Storage 存储桶的 IAM 权限

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

  1. 前往 Cloud Storage > 存储桶。
  2. 点击您的存储桶名称 (cloudm-audit-logs)。
  3. 前往权限标签页。
  4. 点击授予访问权限。
  5. 提供以下配置详细信息:

    • 添加主账号:输入服务账号邮箱 (cloudm-audit-collector-sa@PROJECT_ID.iam.gserviceaccount.com)
    • 分配角色:选择 Storage Object Admin
  6. 点击保存。

创建 Pub/Sub 主题

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

  1. 在 Google Cloud 控制台中,依次前往 Pub/Sub > 主题。
  2. 点击创建主题。
  3. 提供以下配置详细信息:

    • 主题 ID:输入 cloudm-audit-trigger
    • 其他设置保留默认值
  4. 点击创建。

创建 Cloud Run 函数以收集日志

Cloud Run 函数将由来自 Cloud Scheduler 的 Pub/Sub 消息触发,以从 CloudM Automate Logs API 提取日志并将其写入 Cloud Storage。

  1. 在 Google Cloud 控制台中,前往 Cloud Run。
  2. 点击创建服务。
  3. 选择函数(使用直接修改器创建函数)。
  4. 在配置部分中,提供以下配置详细信息:

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

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

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

  8. 前往安全性标签页:

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

    1. 点击变量和密钥。
    2. 针对每个环境变量,点击 + 添加变量:

      变量名称 示例值 说明
      GCS_BUCKET cloudm-audit-logs Cloud Storage 存储桶名称
      GCS_PREFIX cloudm-audit 日志文件的前缀
      STATE_KEY cloudm-audit/state.json 状态文件路径
      CLOUDM_INSTANCE_URL yourcompany.cloudm.io CloudM Automate 实例网址
      CLOUDM_DOMAIN_ID your-domain-id CloudM 网域标识符
      CLOUDM_ACCESS_TOKEN your-access-token CloudM 服务账号不记名令牌
      LOOKBACK_HOURS 24 初始回溯期
  10. 在变量和密钥部分中,向下滚动到请求:

    • 请求超时:输入 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
      
      http = urllib3.PoolManager(
        timeout=urllib3.Timeout(connect=10.0, read=60.0),
        retries=False,
      )
      
      storage_client = storage.Client()
      
      GCS_BUCKET = os.environ.get('GCS_BUCKET')
      GCS_PREFIX = os.environ.get('GCS_PREFIX', 'cloudm-audit')
      STATE_KEY = os.environ.get('STATE_KEY', 'cloudm-audit/state.json')
      CLOUDM_INSTANCE_URL = os.environ.get('CLOUDM_INSTANCE_URL', '').rstrip('/')
      CLOUDM_DOMAIN_ID = os.environ.get('CLOUDM_DOMAIN_ID')
      CLOUDM_ACCESS_TOKEN = os.environ.get('CLOUDM_ACCESS_TOKEN')
      LOOKBACK_HOURS = int(os.environ.get('LOOKBACK_HOURS', '24'))
      
      @functions_framework.cloud_event
      def main(cloud_event):
        if not all([GCS_BUCKET, CLOUDM_INSTANCE_URL, CLOUDM_DOMAIN_ID, CLOUDM_ACCESS_TOKEN]):
          print('Error: Missing required environment variables')
          return
      
        try:
          bucket = storage_client.bucket(GCS_BUCKET)
          state = load_state(bucket)
          now = datetime.now(timezone.utc)
      
          if isinstance(state, dict) and state.get('last_event_date'):
            try:
              last_date = state['last_event_date']
              last_time = datetime.strptime(last_date, '%Y-%m-%d').replace(tzinfo=timezone.utc)
            except Exception as e:
              print(f"Warning: Could not parse last_event_date: {e}")
              last_time = now - timedelta(hours=LOOKBACK_HOURS)
          else:
            last_time = now - timedelta(hours=LOOKBACK_HOURS)
      
          from_date = last_time.strftime('%Y-%m-%d')
          to_date = now.strftime('%Y-%m-%d')
      
          print(f"Fetching logs from {from_date} to {to_date}")
      
          records = fetch_logs(from_date, to_date)
      
          if not records:
            print("No new log records found.")
            save_state(bucket, to_date)
            return
      
          timestamp = now.strftime('%Y%m%d_%H%M%S')
          object_key = f"{GCS_PREFIX}/cloudm_audit_{timestamp}.ndjson"
          blob = bucket.blob(object_key)
      
          ndjson = '\n'.join(
            [json.dumps(record, ensure_ascii=False, default=str) 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}")
      
          save_state(bucket, to_date)
      
          print(f"Successfully processed {len(records)} records")
      
        except Exception as e:
          print(f'Error processing logs: {str(e)}')
          raise
      
      def fetch_logs(from_date, to_date):
        instance = CLOUDM_INSTANCE_URL
        if not instance.startswith('https://'):
          instance = f"https://{instance}"
      
        endpoint = f"{instance}/_ah/api/events/v1/{CLOUDM_DOMAIN_ID}"
      
        headers = {
          'Authorization': f'Bearer {CLOUDM_ACCESS_TOKEN}',
          'Accept': 'application/json',
          'User-Agent': 'GoogleSecOps-CloudMCollector/1.0'
        }
      
        url = f"{endpoint}?from={from_date}&to={to_date}"
      
        try:
          response = http.request('GET', url, headers=headers)
      
          if response.status == 429:
            retry_after = int(response.headers.get('Retry-After', '60'))
            print(f"Rate limited (429). Retry after {retry_after}s.")
            return []
      
          if response.status != 200:
            print(f"HTTP Error: {response.status}")
            response_text = response.data.decode('utf-8')
            print(f"Response body: {response_text}")
            return []
      
          data = json.loads(response.data.decode('utf-8'))
      
          if isinstance(data, list):
            records = data
          elif isinstance(data, dict):
            records = data.get('items', data.get('events', [data]))
          else:
            records = []
      
          print(f"Retrieved {len(records)} events")
          return records
      
        except Exception as e:
          print(f"Error fetching logs: {e}")
          return []
      
      def load_state(bucket):
        try:
          blob = bucket.blob(STATE_KEY)
          if blob.exists():
            return json.loads(blob.download_as_text())
        except Exception as e:
          print(f"Warning: Could not load state: {e}")
        return {}
      
      def save_state(bucket, last_event_date):
        try:
          state = {
            'last_event_date': last_event_date,
            'last_run': datetime.now(timezone.utc).isoformat()
          }
          blob = bucket.blob(STATE_KEY)
          blob.upload_from_string(
            json.dumps(state, indent=2),
            content_type='application/json'
          )
          print(f"Saved state: last_event_date={last_event_date}")
        except Exception as e:
          print(f"Warning: Could not save state: {e}")
      
    • 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. 在 Google Cloud 控制台中,前往 Cloud Scheduler。
  2. 点击创建作业。
  3. 提供以下配置详细信息:

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

测试集成

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

    Fetching logs from YYYY-MM-DD to YYYY-MM-DD
    Retrieved X events
    Wrote X records to gs://cloudm-audit-logs/cloudm-audit/cloudm_audit_YYYYMMDD_HHMMSS.ndjson
    Successfully processed X records
    
  8. 前往 Cloud Storage > 存储桶。

  9. 点击 cloudm-audit-logs。

  10. 转到 cloudm-audit/ 文件夹。

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

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

  • HTTP 401:验证 CLOUDM_ACCESS_TOKEN 环境变量是否正确。
  • HTTP 403:验证服务账号是否具有全局范围的查看日志权限。
  • HTTP 429:速率限制 - 函数将停止,并在下次预定运行时恢复。
  • 缺少环境变量:验证 Cloud Run 函数配置中是否设置了所有必需的变量

检索 Google SecOps 服务账号

Google SecOps 使用唯一服务账号从 Cloud Storage 存储桶读取数据。您必须向此服务账号授予对存储桶的访问权限。

获取服务账号邮箱

  1. 依次前往设置 > 数据管理 > Feed。如果您使用的是 SIEM-only 平台,请依次前往设置 > Feed。
  2. 点击添加新新闻信息流。
  3. 点击配置单个 Feed。
  4. 在 Feed 名称字段中,输入 Feed 的名称(例如 CloudM Audit Logs)。
  5. 选择 Google Cloud Storage V2 作为来源类型。
  6. 选择 CloudM 作为日志类型。
  7. 点击获取服务账号。

    系统会显示一个专属的服务账号邮箱,例如:

    chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.com
    
  8. 复制此邮箱,以便在下一步中使用。

  9. 点击下一步。

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

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

      gs://cloudm-audit-logs/cloudm-audit/
      
    • 来源删除选项:根据您的偏好选择删除选项:

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

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

    • 资产命名空间:资产命名空间。

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

  11. 点击下一步。

  12. 在最终确定界面中查看新的新闻信息流配置,然后点击提交。

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

Google SecOps 服务账号需要对您的 Cloud Storage 存储桶拥有 Storage Object Viewer 角色。

  1. 前往 Cloud Storage > 存储桶。
  2. 点击 cloudm-audit-logs。
  3. 前往权限标签页。
  4. 点击授予访问权限。
  5. 提供以下配置详细信息:

    • 添加主账号:粘贴 Google SecOps 服务账号邮箱
    • 分配角色:选择 Storage Object Viewer
  6. 点击保存。

CloudM Logs API 参数

CloudM Logs API 支持使用以下查询参数来过滤日志事件:

参数 格式 说明
byUser 电子邮件地址 按执行操作的用户过滤事件(类似于 CloudM 界面中的用户)
from yyyy-MM-dd 日期范围过滤条件的开始日期
至 yyyy-MM-dd 日期范围过滤条件的结束日期
contextType 字符串 按上下文类型(例如个人资料、群组、组织部门)过滤
contextName 字符串 按操作目标(例如,特定用户离职)进行过滤
operation 字符串 按操作类型(例如分配别名、已暂停的用户)过滤
国家/地区 国家/地区代码 按地理位置国家/地区代码过滤

UDM 映射表

日志字段 UDM 映射 逻辑
关于 关于 直接复制的值
Context_Name about.labels 从 about_Context_Name、about_Context_Type、labels0 合并为键值对
Context_Type about.labels
Login_Type about.labels
颁发者 additional.fields 从 additional_field0、additional_field1、additional_field2 合并
SAML_code additional.fields
SAML_ACS_Url additional.fields
操作 extensions.auth.type 如果 Operation 与 SSORequest 匹配,则设置为 SSO;如果 Context_Type 为 LoginUser,则设置为 AUTHTYPE_UNSPECIFIED
Context_Type extensions.auth.type
时间戳 metadata.event_timestamp 从时间戳中提取日期时间和时区,将时区转换为偏移量,串联并解析为时间戳
操作 metadata.event_type 如果 Operation 与 Update/Delete/SuspendUser/UnsuspendUser/Create 匹配,则设置为 USER_UNCATEGORIZED;如果 Operation 与 SSORequest/SSORequestFail 匹配或 Context_Type 为 LoginUser,则设置为 USER_LOGIN;如果 IP 不为空,则设置为 STATUS_UPDATE;否则设置为 GENERIC_EVENT
Context_Type metadata.event_type
User_Agent network.http.user_agent 直接复制的值
主体 主体 如果 Context_Type != LoginUser,则从 principal 重命名;否则从 target 重命名
目标 主体
Organization_Unit principal.administrative_domain 直接复制的值
IP principal.ip 直接复制的值
城市 principal.location.city 直接复制的值
国家/地区 principal.location.country_or_region 直接复制的值
地理定位 principal.location.region_latitude 使用 grok 从地理位置中提取的纬度
地理定位 principal.location.region_longitude 使用 grok 从地理位置中提取的经度
区域 principal.location.state 直接复制的值
执行者 principal.user.attribute.roles 如果 Actor 不是电子邮件地址且不为空,则设置为 role.name,然后合并
执行者 principal.user.email_addresses 如果操作者与电子邮件正则表达式匹配,则直接复制值
消息 principal.user.userid 使用 grok 从消息中提取了用户名
security_result security_result 合并了 security_result 对象
SAML_code security_result.action 如果 SAML_code 与 Success 匹配,则设置为 ALLOW;如果为 RequestDenied,则设置为 BLOCK
消息 security_result.description 直接复制的值
严重级别 security_result.severity 如果为 Error/Critical,则设置为大写;如果为 Info,则设置为 INFORMATIONAL;如果为 Warning,则设置为 MEDIUM;否则设置为 UNKNOWN_SEVERITY
操作 security_result.summary 直接复制的值
目标 目标 如果 Context_Type != LoginUser,则从目标重命名,否则从主账号重命名
主体 目标
metadata.product_name metadata.product_name 设置为“CLOUDM”
metadata.vendor_name metadata.vendor_name 设置为“CLOUDM”

更新日志

查看此解析器的更新日志

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