收集 Smartsheet 日志

支持的平台：

Google SecOps SIEM

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

Smartsheet 是一个协作式工作管理平台，可为企业团队提供类似电子表格的项目管理、任务跟踪和工作流自动化功能。Event Reporting API 提供涵盖 100 多种事件类型的审核日志，包括用户操作、数据访问权限、共享更改以及整个 Smartsheet 组织中的管理操作。

准备工作

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

• Google SecOps 实例
• 已启用 Cloud Storage API 的 GCP 项目
• 创建和管理 GCS 存储分区的权限
• 管理 GCS 存储分区的 IAM 政策的权限
• 创建 Cloud Run 函数、Pub/Sub 主题和 Cloud Scheduler 作业的权限
• 已启用“事件报告”插件的 Smartsheet 企业版方案
• 具有 API 访问权限的 Smartsheet 系统管理员账号

收集 Smartsheet API 凭据

生成 API 访问令牌

1. 使用系统管理员账号登录您的 Smartsheet 账号。
2. 在左侧导航栏底部，选择您的账号（个人资料照片），然后前往个人设置。
3. 前往 API 访问权限标签页。
4. 点击生成新访问令牌。
5. 输入令牌的名称（例如，SecOps SIEM Integration）。
6. 点击确定。

7. 复制并妥善保存访问令牌。

   注意： 访问令牌仅显示一次。如果令牌丢失，您必须撤消该令牌并生成新令牌。只有采用商务版和企业版方案的许可 Smartsheet 用户才能访问该 API。

验证权限

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

1. 登录您的 Smartsheet 账号。
2. 依次前往账号（个人资料图片）> 个人设置 > API 访问权限。
3. 如果您可以查看管理 API 访问令牌页面并生成令牌，则表示您拥有所需的权限。
4. 如果您无法访问这些选项，请与 Smartsheet 系统管理员联系，以获取 API 访问权限。

测试 API 访问权限

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

  # Replace with your actual access token
  SMARTSHEET_TOKEN="<your-access-token>"
  
  # Test Event Reporting API access
  curl -v -H "Authorization: Bearer ${SMARTSHEET_TOKEN}" \
    "https://api.smartsheet.com/2.0/events?since=$(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)&maxCount=10"
  

如果您看到以下错误，请执行相应操作：

• HTTP 401：验证访问令牌是否正确。
• HTTP 403：确认相应账号具有系统管理员权限，并且您的方案已启用“活动报告”加购项。

创建 Google Cloud Storage 存储桶

1. 前往 Google Cloud 控制台。
2. 选择您的项目或创建新项目。
3. 在导航菜单中，依次前往 Cloud Storage > 存储分区。
4. 点击创建存储分区。

5. 提供以下配置详细信息：

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

6. 点击创建。

为 Cloud Run 函数创建服务账号

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

创建服务账号

1. 在 GCP 控制台中，依次前往 IAM 和管理 > 服务账号。
2. 点击创建服务账号。
3. 提供以下配置详细信息：
   • 服务账号名称：输入 smartsheet-logs-sa。
   • 服务账号说明：输入 Service account for Cloud Run function to collect Smartsheet audit 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. 点击您的存储桶名称（例如 smartsheet-audit-logs）。
3. 前往权限标签页。
4. 点击授予访问权限。
5. 提供以下配置详细信息：
   • 添加主账号：输入服务账号电子邮件地址（例如 smartsheet-logs-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：输入 smartsheet-logs-trigger。
   • 将其他设置保留为默认值。
4. 点击创建。

创建 Cloud Run 函数以收集日志

Cloud Run 函数将由来自 Cloud Scheduler 的 Pub/Sub 消息触发，以从 Smartsheet Event Reporting API 中提取日志并将其写入 GCS。

1. 在 GCP 控制台中，前往 Cloud Run。
2. 点击创建服务。
3. 选择函数（使用内嵌编辑器创建函数）。

4. 在配置部分中，提供以下配置详细信息：

   设置	值
   Service 名称	smartsheet-logs-to-gcs
   区域	选择与您的 GCS 存储桶匹配的区域（例如 us-central1）
   运行时	选择 Python 3.12 或更高版本

5. 在触发器（可选）部分中：

   1. 点击 + 添加触发器。
   2. 选择 Cloud Pub/Sub。
   3. 在选择 Cloud Pub/Sub 主题中，选择 smartsheet-logs-trigger。
   4. 点击保存。

6. 在身份验证部分中：

   1. 选择需要进行身份验证。
   2. 检查 Identity and Access Management (IAM)。
   注意： 调用函数时，Pub/Sub 会自动处理身份验证。

7. 向下滚动并展开容器、网络、安全性。

8. 前往安全性标签页：

   • 服务账号：选择 smartsheet-logs-sa。

9. 前往容器标签页：

   1. 点击变量和密钥。
   2. 为每个环境变量点击+ 添加变量：

   变量名称	示例值
   GCS_BUCKET	smartsheet-audit-logs
   GCS_PREFIX	smartsheet/events/
   STATE_KEY	smartsheet/events/state.json
   SMARTSHEET_TOKEN	<your-smartsheet-access-token>
   MAX_COUNT	1000
   TIMEOUT	30

   注意： MAX_COUNT 值用于控制每个 API 请求返回的最大事件数。Smartsheet Event Reporting API 支持每个请求最多包含 10,000 个事件；建议使用 1,000 个事件，以确保性能稳定。

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
     import uuid
     import gzip
     import io
     
     # 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', 'smartsheet/events/')
     STATE_KEY = os.environ.get('STATE_KEY', 'smartsheet/events/state.json')
     SMARTSHEET_TOKEN = os.environ.get('SMARTSHEET_TOKEN')
     MAX_COUNT = int(os.environ.get('MAX_COUNT', '1000'))
     TIMEOUT = int(os.environ.get('TIMEOUT', '30'))
     
     EVENTS_URL = "https://api.smartsheet.com/2.0/events"
     
     @functions_framework.cloud_event
     def main(cloud_event):
       """
       Cloud Run function triggered by Pub/Sub to fetch Smartsheet
       Event Reporting audit logs and write to GCS.
     
       Args:
         cloud_event: CloudEvent object containing Pub/Sub message
       """
     
       if not all([GCS_BUCKET, SMARTSHEET_TOKEN]):
         print('Error: Missing required environment variables')
         return
     
       try:
         bucket = storage_client.bucket(GCS_BUCKET)
     
         # Load state
         state = load_state(bucket, STATE_KEY)
         stream_position = state.get('stream_position')
     
         print(f'Fetching events from stream position: {stream_position or "latest"}')
     
         # Fetch events
         total_written = 0
         has_more = True
     
         while has_more:
           events, new_position, more = fetch_events(stream_position)
     
           if events:
             write_chunk(bucket, events, datetime.now(timezone.utc))
             total_written += len(events)
     
           if new_position:
             stream_position = new_position
     
           has_more = more and total_written < 50000
     
         # Save state
         state['stream_position'] = stream_position
         save_state(bucket, STATE_KEY, state)
     
         print(f'Successfully processed {total_written} events')
     
       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: {str(e)}')
     
       return {}
     
     def save_state(bucket, key, state):
       """Save state to GCS."""
       try:
         state['updated_at'] = datetime.now(timezone.utc).isoformat()
         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 write_chunk(bucket, items, ts):
       """Write log chunk to GCS as compressed NDJSON."""
       key = f"{GCS_PREFIX}{ts:%Y/%m/%d}/smartsheet-events-{uuid.uuid4()}.json.gz"
     
       buf = io.BytesIO()
       with gzip.GzipFile(fileobj=buf, mode='w') as gz:
         for rec in items:
           gz.write((json.dumps(rec) + '\n').encode('utf-8'))
     
       buf.seek(0)
       blob = bucket.blob(key)
       blob.upload_from_file(buf, content_type='application/gzip')
     
       print(f'Wrote {len(items)} events to {key}')
       return key
     
     def fetch_events(stream_position):
       """
       Fetch events from Smartsheet Event Reporting API.
     
       The API uses a streaming model with streamPosition for pagination.
       On first call (no streamPosition), it returns the current position
       without events. Subsequent calls return events since the position.
     
       Returns:
         Tuple of (events list, new stream position, has more data)
       """
       headers = {
         'Authorization': f'Bearer {SMARTSHEET_TOKEN}',
         'Accept': 'application/json'
       }
     
       params = [f'maxCount={MAX_COUNT}']
       if stream_position:
         params.append(f'streamPosition={stream_position}')
     
       url = f"{EVENTS_URL}?{'&'.join(params)}"
     
       response = http.request(
         'GET',
         url,
         headers=headers,
         timeout=TIMEOUT
       )
     
       if response.status == 429:
         retry_after = int(response.headers.get('Retry-After', '60'))
         print(f'Rate limited (429). Retry-After: {retry_after}s')
         import time
         time.sleep(min(retry_after, 120))
         return fetch_events(stream_position)
     
       if response.status != 200:
         print(f'API request failed: {response.status}')
         response_text = response.data.decode('utf-8')
         print(f'Response body: {response_text}')
         raise Exception(f'Failed to fetch events: {response.status}')
     
       data = json.loads(response.data.decode('utf-8'))
     
       events = data.get('data', []) or []
       new_position = data.get('nextStreamPosition')
       more_available = data.get('moreEventsAvailable', False)
     
       if events:
         print(f'Retrieved {len(events)} events')
     
       return events, new_position, more_available
     

   • 第二个文件：requirements.txt:：

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

3. 点击部署以保存并部署该函数。

4. 等待部署完成（2-3 分钟）。

   注意： Pub/Sub 触发器配置会自动创建必要的订阅和权限。Smartsheet 事件报告 API 使用流式模型，并使用 streamPosition 进行分页。在首次运行（没有保存的流位置）时，API 会返回不含事件的当前位置。后续运行会提取自保存位置以来发生的事件。

创建 Cloud Scheduler 作业

Cloud Scheduler 会定期向 Pub/Sub 主题发布消息，从而触发 Cloud Run 函数。

1. 在 GCP Console 中，前往 Cloud Scheduler。
2. 点击创建作业。

3. 提供以下配置详细信息：

   设置	值
   名称	smartsheet-logs-schedule-15min
   区域	选择与 Cloud Run 函数相同的区域
   频率	*/15 * * * *（每 15 分钟）
   时区	选择时区（建议选择世界协调时间 [UTC]）
   目标类型	Pub/Sub
   主题	选择smartsheet-logs-trigger
   消息正文	{}（空 JSON 对象）

4. 点击创建。

时间表频率选项

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

频率	Cron 表达式	使用场景
每隔 5 分钟	*/5 * * * *	大批量、低延迟
每隔 15 分钟	*/15 * * * *	标准（推荐）
每小时	0 * * * *	音量低
每 6 小时	0 */6 * * *	批处理

测试集成

1. 在 Cloud Scheduler 控制台中，找到您的作业（例如 smartsheet-logs-schedule-15min）。
2. 点击强制运行以手动触发作业。
3. 等待几秒钟。
4. 前往 Cloud Run > 服务。
5. 点击函数名称 (smartsheet-logs-to-gcs)。
6. 点击日志标签页。

7. 验证函数是否已成功执行。请查找以下内容：

   Fetching events from stream position: <position>
   Retrieved X events
   Wrote X events to smartsheet/events/YYYY/MM/DD/smartsheet-events-UUID.json.gz
   Successfully processed X events
   

8. 前往 Cloud Storage > 存储分区。

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

10. 前往前缀文件夹 (smartsheet/events/)。

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

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

• HTTP 401：检查环境变量中的 Smartsheet 访问令牌
• HTTP 403：验证账号是否具有系统管理员权限，以及是否已启用事件报告
• HTTP 429：速率限制 - 函数将自动重试并进行退避
• 缺少环境变量：检查是否已在 Cloud Run 函数配置中设置所有必需的变量

检索 Google SecOps 服务账号

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

在 Google SecOps 中配置 Feed 以注入 Smartsheet 日志

1. 依次前往 SIEM 设置 > Feed。
2. 点击添加新 Feed。
3. 点击配置单个 Feed。
4. 在 Feed 名称字段中，输入 Feed 的名称（例如 Smartsheet Audit Logs）。
5. 选择 Google Cloud Storage V2 作为来源类型。
6. 选择 Smartsheet 作为日志类型。

7. 点击获取服务账号。系统会显示一个唯一的服务账号电子邮件地址，例如：

   [e-mail]
   

8. 复制此电子邮件地址。您将在下一步骤中用到它。

   注意： 每个 Google SecOps 实例都有一个唯一的服务账号。请勿使用其他文档或示例中的服务账号。

9. 点击下一步。

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

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

    gs://smartsheet-audit-logs/smartsheet/events/
    

    • 将

      • smartsheet-audit-logs：您的 GCS 存储桶名称。
      • smartsheet/events/：存储日志的前缀路径。
    注意： 请务必在 URI 末尾添加尾随斜杠 (/)。
    • 来源删除选项：根据您的偏好选择删除选项：
      • 永不：转移后永不删除任何文件（建议用于测试）。
      • 删除已转移的文件：在成功转移后删除文件。
      • 删除已转移的文件和空目录：成功转移后删除文件和空目录。
    注意： 如果您选择删除选项，服务账号必须具有 Storage Object Admin 角色，而不是 Storage Object Viewer 角色。相应地更新 IAM 权限。
    • 文件存在时间上限：包含在过去指定天数内修改的文件。默认值为 180 天。
    • 资产命名空间：资产命名空间。
    • 提取标签：要应用于相应 Feed 中事件的标签。

11. 点击下一步。

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

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

Google SecOps 服务账号需要您的 GCS 存储桶的 Storage Object Viewer 角色。

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

6. 点击保存。

   注意： 如果您打算使用“删除已转移的文件”或“删除已转移的文件和空目录”删除选项，请授予存储对象管理员角色，而不是存储对象查看者角色。

UDM 映射表

日志字段	UDM 映射	逻辑
accessLevel_label	additional.fields	已合并
appName_label	additional.fields	已合并
attachmentName_label	additional.fields	已合并
cellLinkSourceSheetId_label	additional.fields	已合并
dashboardName_label	additional.fields	已合并
folderName_label	additional.fields	已合并
formatType_label	additional.fields	已合并
includeAttachments_label	additional.fields	已合并
includeDiscussions_label	additional.fields	已合并
mergeType_label	additional.fields	已合并
rowCount_label	additional.fields	已合并
rowsMoved_label	additional.fields	已合并
sheetId_label	additional.fields	已合并
sheetName_label	additional.fields	已合并
sheetRowId_label	additional.fields	已合并
sourceFolderId_label	additional.fields	已合并
sourceObjectId_label	additional.fields	已合并
sourceSheetId_label	additional.fields	已合并
sourceType_label	additional.fields	已合并
tokenDisplayValue_label	additional.fields	已合并
tokenUserId_label	additional.fields	已合并
userId_label	additional.fields	已合并
workspaceId_label	additional.fields	已合并
additionalDetails.accessScopes	metadata.description	直接映射
additionalDetails_tokenExpirationTimestamp	metadata.event_timestamp	解析为 yyyy-MM-ddTHH:mm:ssZ
eventTimestamp	metadata.event_timestamp	解析为 yyyy-MM-ddTHH:mm:ssZ
has_principal	metadata.event_type	已映射：true → USER_UNCATEGORIZED
accessTokenName	metadata.product_log_id	直接映射
eventId	metadata.product_log_id	直接映射
additionalDetails.appClientId	principal.user.userid	直接映射
requestUserId	principal.user.userid	直接映射
object_id	security_result.about.labels	已合并
source_label	security_result.about.labels	已合并
object_type	security_result.about.resource.attribute.labels	已合并
action	security_result.action_details	直接映射
userId	target.user.userid	直接映射
不适用	metadata.event_type	常量：USER_UNCATEGORIZED

更新日志

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

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