收集 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 密钥
- 登录 Cisco Umbrella 信息中心。
- 依次前往管理 > API 密钥。
- 点击创建 API 密钥。
- 提供以下配置详细信息:
- 密钥名称:输入描述性名称(例如
Google SecOps Audit Log Integration)。 - 密钥范围:选择具有只读权限的报告。
- 密钥名称:输入描述性名称(例如
- 点击创建。
复制并妥善保存以下值:
- API 密钥:复制此值。
- API 密钥:复制此值。
请记下 API 密钥页面顶部显示的组织 ID。您稍后需要用到此值。
验证 API 访问权限
Cisco Umbrella API 使用 OAuth 2.0 身份验证。在继续集成之前,请先测试您的凭证:
获取访问令牌:
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"使用令牌检索审计日志:
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 存储桶
- 前往 Google Cloud 控制台。
- 选择您的项目或创建一个新项目。
- 在导航菜单中,前往 Cloud Storage > 存储桶。
- 点击创建存储分区。
提供以下配置详细信息:
设置 值 指定存储桶的名称 输入一个全局唯一的名称(例如 cisco-umbrella-audit-logs)位置类型 根据您的需求进行选择(单区域、双区域、多区域) 位置 选择位置(例如 us-central1)存储类别 标准(推荐用于频繁访问的日志) 访问权限控制 统一(推荐) 保护工具 可选:启用对象版本控制或保留政策 点击创建。
为 Cloud Run 函数创建服务账号
该 Cloud Run 函数需要一个服务账号,该账号应具有向 Cloud Storage 存储桶写入数据的权限,并且可由 Pub/Sub 调用。
创建服务账号
- 在 Google Cloud 控制台中,依次前往 IAM 和管理 > 服务账号。
- 点击创建服务账号。
- 提供以下配置详细信息:
- 服务账号名称:输入
umbrella-audit-collector-sa - 服务账号说明:输入
Service account for Cloud Run function to collect Cisco Umbrella Audit logs
- 服务账号名称:输入
- 点击创建并继续。
- 在为此服务账号授予项目访问权限部分,添加以下角色:
- 点击选择角色。
- 搜索并选择 Storage Object Admin。
- 点击 + 添加其他角色。
- 搜索并选择 Cloud Run Invoker。
- 点击 + 添加其他角色。
- 搜索并选择 Cloud Functions Invoker。
- 点击继续。
- 点击完成。
以下操作需要这些角色:
- Storage Object Admin:将日志写入 Cloud Storage 存储桶并管理状态文件
- Cloud Run Invoker:允许 Pub/Sub 调用函数
- Cloud Functions Invoker:允许调用函数
授予对 Cloud Storage 存储桶的 IAM 权限
向服务账号授予对 Cloud Storage 存储桶的写入权限:
- 前往 Cloud Storage > 存储桶。
- 点击您的存储桶名称。
- 前往权限标签页。
- 点击授予访问权限。
- 提供以下配置详细信息:
- 添加主账号:输入服务账号邮箱(例如
umbrella-audit-collector-sa@PROJECT_ID.iam.gserviceaccount.com) - 分配角色:选择 Storage Object Admin
- 添加主账号:输入服务账号邮箱(例如
- 点击保存。
创建 Pub/Sub 主题
创建一个 Pub/Sub 主题,Cloud Scheduler 将向其发布消息,Cloud Run 函数将订阅该主题。
- 在 Google Cloud 控制台中,依次前往 Pub/Sub > 主题。
- 点击创建主题。
- 提供以下配置详细信息:
- 主题 ID:输入
umbrella-audit-trigger - 其他设置保留默认值
- 主题 ID:输入
- 点击创建。
创建 Cloud Run 函数以收集日志
Cloud Run 函数将由来自 Cloud Scheduler 的 Pub/Sub 消息触发,以从 Cisco Umbrella Audit API 提取日志并将其写入 Cloud Storage。
- 在 Google Cloud 控制台中,前往 Cloud Run。
- 点击创建服务。
- 选择函数(使用直接修改器创建函数)。
在配置部分中,提供以下配置详细信息:
设置 值 Service 名称 umbrella-audit-collector区域 选择与您的 Cloud Storage 存储桶匹配的区域(例如 us-central1)运行时 选择 Python 3.12 或更高版本 在触发器(可选)部分中:
- 点击 + 添加触发器。
- 选择 Cloud Pub/Sub。
- 在选择 Cloud Pub/Sub 主题中,选择 Pub/Sub 主题
umbrella-audit-trigger。 - 点击保存。
在身份验证部分中:
- 选择需要进行身份验证。
- 查看 Identity and Access Management (IAM)。
向下滚动并展开容器、网络、安全性。
前往安全性标签页:
- 服务账号:选择
umbrella-audit-collector-sa
- 服务账号:选择
前往容器标签页:
- 点击变量和密钥。
- 针对每个环境变量,点击 + 添加变量:
变量名称 示例值 说明 GCS_BUCKETcisco-umbrella-audit-logsCloud Storage 存储桶名称 GCS_PREFIXumbrella-audit日志文件的前缀 STATE_KEYumbrella-audit/state.json状态文件路径 UMBRELLA_API_KEYyour-api-keyUmbrella API 密钥(OAuth 2.0 客户端 ID) UMBRELLA_API_SECRETyour-api-secretUmbrella API 密钥(OAuth 2.0 客户端密钥) UMBRELLA_ORG_IDyour-org-id伞形组织 ID MAX_RECORDS1000每次运行的记录数上限 PAGE_SIZE100每页记录数 LOOKBACK_HOURS24初始回溯期 在变量和密钥部分中,向下滚动到请求:
- 请求超时:输入
600秒(10 分钟)
- 请求超时:输入
前往设置标签页:
- 在资源部分中:
- 内存:选择 512 MiB 或更高
- CPU:选择 1
- 在资源部分中:
在修订版本伸缩部分:
- 实例数下限:输入
0 - 实例数上限:输入
100(或根据预期负载进行调整)
- 实例数下限:输入
点击创建。
等待服务创建完成(1-2 分钟)。
创建服务后,内嵌代码编辑器会自动打开。
添加函数代码
- 在入口点字段中输入 main。
在内嵌代码编辑器中,创建两个文件:
- 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点击部署以保存和部署函数。
等待部署完成(2-3 分钟)。
创建 Cloud Scheduler 作业
Cloud Scheduler 将定期向 Pub/Sub 主题发布消息,从而触发 Cloud Run 函数。
- 在 Google Cloud 控制台中,前往 Cloud Scheduler。
- 点击创建作业。
提供以下配置详细信息:
设置 值 名称 umbrella-audit-collector-hourly区域 选择与 Cloud Run 函数相同的区域 频率 0 * * * *(每小时整点)时区 选择时区(建议选择世界协调时间 [UTC]) 目标类型 Pub/Sub 主题 选择 Pub/Sub 主题 umbrella-audit-trigger邮件正文 {}(空 JSON 对象)点击创建。
测试集成
- 在 Cloud Scheduler 控制台中,找到您的作业。
- 点击强制运行以手动触发作业。
- 等待几秒钟。
- 前往 Cloud Run > 服务。
- 点击函数名称 (
umbrella-audit-collector)。 - 点击日志标签页。
验证函数是否已成功执行。查找:
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前往 Cloud Storage > 存储桶。
点击您的存储桶名称。
转到
umbrella-audit/文件夹。验证是否已创建带有当前时间戳的新
.ndjson文件。
如果您在日志中看到错误,请执行以下操作:
- HTTP 401:检查环境变量中的 API 凭证
- HTTP 403:验证 API 密钥是否具有审计日志读取范围
- HTTP 429:速率限制 - 函数将自动重试并采用退避算法
- 缺少环境变量:检查是否已设置所有必需变量
检索 Google SecOps 服务账号
Google SecOps 使用唯一服务账号从 Cloud Storage 存储桶读取数据。您必须向此服务账号授予对存储桶的访问权限。
获取服务账号邮箱
- 依次前往设置 > 数据管理 > Feed。如果您使用的是 SIEM-only 平台,请依次前往设置 > Feed。
- 点击添加新新闻信息流。
- 点击配置单个 Feed。
- 在 Feed 名称字段中,输入 Feed 的名称(例如
Cisco Umbrella Audit Logs)。 - 选择 Google Cloud Storage V2 作为来源类型。
- 选择 Cisco Umbrella Audit 作为日志类型。
- 点击获取服务账号。
系统会显示一个专属的服务账号邮箱,例如:
chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.com复制此邮箱,以便在下一步中使用。
点击下一步。
为以下输入参数指定值:
存储桶网址:输入带有前缀路径的 Cloud Storage 存储桶 URI:
gs://cisco-umbrella-audit-logs/umbrella-audit/
来源删除选项:根据您的偏好选择删除选项:
- 永不:转移后永不删除任何文件(建议在测试时使用)。
- 删除已转移的文件:在成功转移后删除文件。
- 删除已转移的文件和空目录:在成功转移后删除文件和空目录。
文件存在时间上限:包含过去指定天数内修改过的文件(默认值为 180 天)
资产命名空间:资产命名空间
注入标签:要应用于此 Feed 中事件的标签
点击下一步。
在最终确定界面中查看新的新闻信息流配置,然后点击提交。
向 Google SecOps 服务账号授予 IAM 权限
Google SecOps 服务账号需要对您的 Cloud Storage 存储桶拥有 Storage Object Viewer 角色。
- 前往 Cloud Storage > 存储桶。
- 点击您的存储桶名称。
- 前往权限标签页。
- 点击授予访问权限。
- 提供以下配置详细信息:
- 添加主账号:粘贴 Google SecOps 服务账号邮箱
- 分配角色:选择 Storage Object Viewer
点击保存。
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 |
从更新日志映射 |