收集 Cisco Umbrella 审计日志

解析器版本:3.0

支持的国家/地区:

本文档介绍了如何使用 Cloud Storage V2 将 Cisco Umbrella 审计日志注入 Google Security Operations。Cisco Umbrella 审计日志会捕获在 Cisco Umbrella 信息中心内执行的管理操作,包括政策更改、用户管理活动和配置修改。这些日志可提供审计跟踪记录,用于对 Umbrella 部署进行法规遵从和安全监控。

准备工作

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

  • Google SecOps 实例
  • 启用了 Cloud Storage API 的 Google Cloud 项目
  • 创建和管理 Cloud Storage 存储桶的权限
  • 管理 Cloud Storage 存储桶上的 Identity and Access Management (IAM) 政策的权限
  • 创建 Cloud Run 服务、Pub/Sub 主题和 Cloud Scheduler 作业的权限
  • 具有管理员权限的 Cisco Umbrella 账号
  • 具有 reports:read 范围的 Cisco Umbrella API 凭证(API 密钥和密钥)

收集 Cisco Umbrella API 凭证

创建 Umbrella API 密钥

  1. 登录 Cisco Umbrella 信息中心。
  2. 依次前往管理 > API 密钥。
  3. 点击创建 API 密钥。
  4. 提供以下配置详细信息:
    • 密钥名称:输入描述性名称(例如 Google SecOps Audit Log Integration)。
    • 密钥范围:选择具有只读权限的报告。
  5. 点击创建。
  6. 复制并妥善保存以下值:

    • API 密钥:复制此值。
    • API 密钥:复制此值。
  7. 请记下 API 密钥页面顶部显示的组织 ID。您稍后需要用到此值。

验证 API 访问权限

Cisco Umbrella API 使用 OAuth 2.0 身份验证。在继续集成之前,请先测试您的凭证:

  1. 获取访问令牌:

    API_KEY="<your-api-key>"
    API_SECRET="<your-api-secret>"
    
    TOKEN=$(curl -s -u "$API_KEY:$API_SECRET" \
      --url "https://api.umbrella.com/auth/v2/token" \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -d "grant_type=client_credentials" | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")
    
    echo "$TOKEN"
    
  2. 使用令牌检索审计日志:

    ORG_ID="<your-org-id>"
    
    curl -s -H "Authorization: Bearer $TOKEN" \
      "https://api.umbrella.com/reports/v2/audit?organizationId=$ORG_ID&limit=1"
    

创建 Cloud Storage 存储桶

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

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

为 Cloud Run 函数创建服务账号

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

创建服务账号

  1. 在 Google Cloud 控制台中,依次前往 IAM 和管理 > 服务账号。
  2. 点击创建服务账号。
  3. 提供以下配置详细信息:
    • 服务账号名称:输入 umbrella-audit-collector-sa
    • 服务账号说明:输入 Service account for Cloud Run function to collect Cisco Umbrella 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. 点击您的存储桶名称。
  3. 前往权限标签页。
  4. 点击授予访问权限。
  5. 提供以下配置详细信息:
    • 添加主账号:输入服务账号邮箱(例如 umbrella-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:输入 umbrella-audit-trigger
    • 其他设置保留默认值
  4. 点击创建。

创建 Cloud Run 函数以收集日志

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

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

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

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

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

  8. 前往安全性标签页:

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

    1. 点击变量和密钥。
    2. 针对每个环境变量,点击 + 添加变量:
    变量名称 示例值 说明
    GCS_BUCKET cisco-umbrella-audit-logs Cloud Storage 存储桶名称
    GCS_PREFIX umbrella-audit 日志文件的前缀
    STATE_KEY umbrella-audit/state.json 状态文件路径
    UMBRELLA_API_KEY your-api-key Umbrella API 密钥(OAuth 2.0 客户端 ID)
    UMBRELLA_API_SECRET your-api-secret Umbrella API 密钥(OAuth 2.0 客户端密钥)
    UMBRELLA_ORG_ID your-org-id 伞形组织 ID
    MAX_RECORDS 1000 每次运行的记录数上限
    PAGE_SIZE 100 每页记录数
    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
    import time
    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()
    
    # Environment variables
    GCS_BUCKET = os.environ.get('GCS_BUCKET')
    GCS_PREFIX = os.environ.get('GCS_PREFIX', 'umbrella-audit')
    STATE_KEY = os.environ.get('STATE_KEY', 'umbrella-audit/state.json')
    API_KEY = os.environ.get('UMBRELLA_API_KEY')
    API_SECRET = os.environ.get('UMBRELLA_API_SECRET')
    ORG_ID = os.environ.get('UMBRELLA_ORG_ID')
    MAX_RECORDS = int(os.environ.get('MAX_RECORDS', '1000'))
    PAGE_SIZE = int(os.environ.get('PAGE_SIZE', '100'))
    LOOKBACK_HOURS = int(os.environ.get('LOOKBACK_HOURS', '24'))
    
    # OAuth 2.0 token endpoint
    TOKEN_URL = 'https://api.umbrella.com/auth/v2/token'
    
    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)
    
    def get_access_token(api_key, api_secret):
      """
      Obtain an OAuth 2.0 access token from the Cisco Umbrella API
      using the client credentials grant.
    
      Returns:
        Access token string
      """
      auth_string = f"{api_key}:{api_secret}"
      auth_bytes = auth_string.encode('utf-8')
      auth_b64 = base64.b64encode(auth_bytes).decode('utf-8')
    
      headers = {
        'Authorization': f'Basic {auth_b64}',
        'Content-Type': 'application/x-www-form-urlencoded',
      }
    
      response = http.request(
        'POST',
        TOKEN_URL,
        headers=headers,
        body='grant_type=client_credentials',
      )
    
      if response.status != 200:
        raise RuntimeError(
          f"Failed to obtain access token: HTTP {response.status} "
          f"- {response.data.decode('utf-8')}"
        )
    
      token_data = json.loads(response.data.decode('utf-8'))
      return token_data['access_token']
    
    @functions_framework.cloud_event
    def main(cloud_event):
      """
      Cloud Run function triggered by Pub/Sub to fetch Cisco Umbrella Audit logs
      and write to GCS.
    
      Args:
        cloud_event: CloudEvent object containing Pub/Sub message
      """
    
      if not all([GCS_BUCKET, API_KEY, API_SECRET, ORG_ID]):
        print('Error: Missing required environment variables')
        return
    
      try:
        bucket = storage_client.bucket(GCS_BUCKET)
        state = load_state(bucket, STATE_KEY)
    
        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()}")
    
        # Obtain OAuth 2.0 access token
        access_token = get_access_token(API_KEY, API_SECRET)
        print("Successfully obtained OAuth 2.0 access token")
    
        records, newest_event_time = fetch_logs(
          access_token=access_token,
          org_id=ORG_ID,
          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
    
        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}")
    
        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(access_token, org_id, start_time, end_time, page_size, max_records):
      """
      Fetch audit logs from Cisco Umbrella Reports API with pagination
      and rate limiting. Uses OAuth 2.0 bearer token authentication.
    
      Returns:
        Tuple of (records list, newest_event_time ISO string)
      """
      endpoint = f"https://api.umbrella.com/reports/v2/audit"
    
      headers = {
        'Authorization': f'Bearer {access_token}',
        'Accept': 'application/json',
        'User-Agent': 'GoogleSecOps-UmbrellaAuditCollector/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})")
          break
    
        limit = min(page_size, max_records - len(records))
        url = (
          f"{endpoint}"
          f"?organizationId={org_id}"
          f"&from={start_iso}&to={end_iso}"
          f"&limit={limit}&offset={offset}"
        )
    
        try:
          response = http.request('GET', url, headers=headers)
    
          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('data', [])
    
          if not page_results:
            print("No more results (empty page)")
            break
    
          print(f"Page {page_num}: Retrieved {len(page_results)} events")
          records.extend(page_results)
    
          for event in page_results:
            try:
              event_time = event.get('createdAt')
              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}")
    
          if len(page_results) < limit:
            print(
              f"Reached last page (size={len(page_results)} < limit={limit})"
            )
            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. 在 Google Cloud 控制台中,前往 Cloud Scheduler。
  2. 点击创建作业。
  3. 提供以下配置详细信息:

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

测试集成

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

    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://cisco-umbrella-audit-logs/umbrella-audit/logs_YYYYMMDD_HHMMSS.ndjson
    Successfully processed X records
    
  8. 前往 Cloud Storage > 存储桶。

  9. 点击您的存储桶名称。

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

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

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

  • HTTP 401:检查环境变量中的 API 凭证
  • HTTP 403:验证 API 密钥是否具有审计日志读取范围
  • HTTP 429:速率限制 - 函数将自动重试并采用退避算法
  • 缺少环境变量:检查是否已设置所有必需变量

检索 Google SecOps 服务账号

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

获取服务账号邮箱

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

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

  10. 点击下一步。

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

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

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

      • 永不:转移后永不删除任何文件(建议在测试时使用)。
      • 删除已转移的文件:在成功转移后删除文件。
      • 删除已转移的文件和空目录:在成功转移后删除文件和空目录。
    • 文件存在时间上限:包含过去指定天数内修改过的文件(默认值为 180 天)

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

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

  12. 点击下一步。

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

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

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

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

UDM 映射表

日志字段 UDM 映射 逻辑
_field additional.fields 已合并
identities_label additional.fields 已合并
key additional.fields Mapped: ` "permissions", "dynamic", "bundleTypeId", "modifiedAt", "organizationId", "name", …
column1 metadata.event_timestamp 已解析为 yyyy-MM-dd HH:mm:ss
column2 metadata.event_timestamp 已解析为 ISO8601
createdAt metadata.event_timestamp 已解析为 ISO8601
date_time metadata.event_timestamp 已解析为 yyyy-MM-dd HH:mm:ss
has_principal metadata.event_type 已映射:true → STATUS_UPDATE
has_user metadata.event_type 已映射:true → USER_UNCATEGORIZED
network_dns_details_present metadata.event_type 已映射:true → NETWORK_DNS
product_log_id metadata.product_log_id 直接映射
network_dns_details_present network.application_protocol 已映射:true → DNS
question network.dns.questions 已合并
dns.response_code network.dns.response_code 已重命名/映射
mail_to network.email.to 已映射:^.+@.+$ → mail_to
action_type network.http.method 直接映射
identity principal.asset.hostname 直接映射
external_ip principal.asset.ip 已映射:internal_ip → external_ip
internal_ip principal.asset.ip 已合并
ip principal.asset.ip 已合并
principal_ip principal.asset.ip 已合并
identity principal.hostname 直接映射
external_ip principal.ip 已映射:internal_ip → external_ip
internal_ip principal.ip 已合并
ip principal.ip 已合并
principal_ip principal.ip 已合并
identity principal.location.city 直接映射
identity principal.location.name 直接映射
column5 principal.resource.name 直接映射
id principal.resource.product_object_id 直接映射
email principal.user.email_addresses 已映射:^.+@.+$ → email
principal_user_email principal.user.email_addresses 已映射:^.+@.+$ → principal_user_email
user_mail principal.user.email_addresses 已映射:^.+@.+$ → user_mail
displayname principal.user.user_display_name 直接映射
principal_user principal.user.user_display_name 直接映射
user principal.user.userid 直接映射
security_result_action security_result.action 已合并
action security_result.action_details 直接映射
action_type security_result.action_details 直接映射
categories_json.categories security_result.category_details 已重命名/映射
rule_name security_result.rule_name 直接映射
不适用 metadata.event_type 常量:NETWORK_DNS
不适用 metadata.product_name 常量:CISCO UMBERLLA
不适用 metadata.vendor_name 常量:CISCO UMBERLLA
不适用 network.application_protocol 常量:DNS
most_granular_identity", "most_granular_identity_type", "identity_types" and "blocked_categories additional.fields 从更新日志映射
internal_ip" and "external_ip principal.ip 从更新日志映射
dns_query_type network.dns.questions.type 从更新日志映射
dns_response_code network.dns.response_code 从更新日志映射
domain network.dns.questions.name 从更新日志映射

更新日志

查看此解析器的更新日志

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