将原始日志导出到自行管理的 Google Cloud Storage 存储桶
借助数据导出 API,您可以将安全数据从 Google Security Operations 批量导出到您控制的 Google Cloud Storage 存储桶。此功能支持关键的长期数据保留,并支持历史取证分析和严格的合规性要求(例如 SOX 和 GDPR)。
如需详细了解 API 参考文档,请参阅 数据导出 API(增强版)。
Data Export API 为时间点数据导出提供了可伸缩且可靠的解决方案,并可处理高达 100 TB 的请求。
作为一项代管式流水线服务,它提供以下重要的企业级功能:
- 遇到暂时性错误时自动重试
- 全面的作业状态监控
- 每个导出作业的完整审计跟踪记录
该 API 会在 Google Cloud Storage 存储桶中按日期和时间对导出的数据进行逻辑分区。
借助此功能,您可以构建大规模数据分流工作流。 Google SecOps 会管理导出流程的复杂性,以提供稳定性和性能。
主要优势
数据导出 API 提供了一种弹性且可审核的解决方案,用于管理安全数据的生命周期,具有以下主要优势:
- 可靠性:该服务可处理大规模数据传输。系统会使用指数退避算法策略自动重试遇到暂时性问题(例如临时网络问题)的导出作业,从而提高其弹性。如果导出作业因暂时性错误而失败,它会自动重试多次。如果作业在所有重试后永久失败,系统会将其状态更新为
FINISHED_FAILURE,并且该作业的 API 响应会包含一条详细的错误消息,说明原因。 全面的可审核性:为满足严格的法规遵从和安全标准,系统会在不可变的审计跟踪记录中捕获与导出作业相关的每项操作。此跟踪记录包括每个作业的创建、启动、成功或失败,以及发起操作的用户、时间戳和作业参数。
针对性能和规模进行了优化:该 API 使用强大的作业管理系统。此系统包含排队和优先级设置功能,可提供平台稳定性并防止任何单个租户垄断资源。
增强的数据完整性和可访问性:系统会自动将数据整理到 Google Cloud Storage 存储桶内的逻辑目录结构中,这有助于您查找和查询特定时间范围的数据,以进行历史分析。
安全性:该 API 旨在完全符合客户管理的加密密钥 (CMEK)(零信任安全性)和数据 RBAC(最小权限访问)。导出作业会沿用触发请求的用户的数据可见性范围,以防止未经授权的数据提取。导出流水线还与 Google Cloud Key Management Service 完全集成,数据在 Google Cloud Storage 存储桶中保持静态加密状态,并使用您自己的密钥。
关键术语和概念
- 导出作业:将特定时间范围内的日志数据导出到 Google Cloud Storage 存储桶的单次异步操作。系统会使用唯一的
dataExportId跟踪每个作业。 - 作业状态:导出作业在其生命周期中的当前状态(例如
IN_QUEUE、PROCESSING、FINISHED_SUCCESS)。 - Google Cloud Storage 存储桶:用户拥有的 Google Cloud Storage 存储桶,用作导出数据的目标位置。
- 日志类型:您可以导出的特定日志类别(例如
NIX_SYSTEM、WINDOWS_DNS、CB_EDR)。如需了解详情,请参阅所有受支持日志类型的列表。
了解导出的数据结构
作业成功完成后,系统会将数据写入您的 Google Cloud Storage 存储桶。它使用特定的分区目录结构来简化数据访问和查询。
目录路径结构:gs://GCS_BUCKET_NAME/EXPORT_JOB_NAME/LOGTYPE/EVENT_TIME_BUCKET/EPOCH_EXECUTION_TIME/logdata-SHARD_INDEX.csv
其中:
- GCS_BUCKET_NAME:指 Google Cloud Storage 存储桶的名称。
- EXPORT_JOB_NAME:指导出作业的唯一
dataExportIdUUID(对象路径中不含连字符)。 - LOGTYPE:指所导出数据的日志类型名称(例如
GCP_DNS或WINDOWS_DNS)。 - EVENT_TIME_BUCKET:指导出日志的事件时间戳的小时分桶,向下舍入到 UTC 小时 (
YYYY/MM/DD/HH/00/00) 的开始时间。例如,2025/08/25/01/00/00包含 2025 年 8 月 25 日01:00:00 UTC至01:59:59 UTC之间事件时间戳的日志。 - EPOCH_EXECUTION_TIME:指 20 位零填充的 Unix 纪元时间戳(以微秒为单位),表示导出作业执行开始的时间(例如
00001756083600000000)。 logdata-SHARD_INDEX.csv:指包含原始日志的 0 索引分片文件(例如logdata-0.csv和logdata-1.csv)。每个文件分片的目标大小约为 100 MB。
导出的对象路径示例:
gs://my-archive-bucket/b4a3c2d1e8f76a5b4c3d2e1f0a9b8c7d/GCP_DNS/2025/08/25/01/00/00/00001756083600000000/logdata-0.csv
导出完成清单 (exported_paths.txt):
当导出作业以 FINISHED_SUCCESS 状态完成并写入至少一个日志文件时,流水线还会将清单文件写入 gs://GCS_BUCKET_NAME/EXPORT_JOB_NAME/exported_paths.txt(如果没有日志与导出过滤条件或时间范围匹配,则不会写入清单文件,并且 dataExportStatus.exportedGlobPatterns 为空)。exported_paths.txt 中的每一行都列出了一个 glob 格式,该格式使用 /bigstore/ 前缀(/bigstore/GCS_BUCKET_NAME/EXPORT_JOB_NAME/LOGTYPE/EVENT_TIME_BUCKET/EPOCH_EXECUTION_TIME/*,映射到 gs://GCS_BUCKET_NAME/.../*)来表示作业写入的每小时分区目录。下游自动化或压缩作业可以读取此清单,以枚举所有导出的分区,而无需列出整个存储桶。
性能和限制
为确保平台稳定性和公平的资源分配,该服务具有以下特定限制:
- 每个作业的数据量上限:每个导出作业最多可以请求 100 TB 的数据。对于较大的数据集,Google 建议将导出作业拆分为多个时间范围较小的作业。
- 并发作业:每个客户租户最多可以同时运行或将三个导出作业加入队列。系统会拒绝任何超出此限制的新作业创建请求。
- 作业完成时间:导出的数据量决定了作业完成时间。单个作业最长可能需要 18 小时。
- 导出格式和数据范围:该 API 支持批量、时间点导出,具有以下限制和功能:
- 仅限原始日志:您只能导出原始日志(不能导出 UDM 日志、UDM 事件或检测结果)。如需了解如何导出 UDM 数据,请参阅导出到自行管理的 BigQuery 项目。
- 文件格式和数据压缩:API 会将数据导出为未压缩、以换行符分隔的原始日志字符串,并将其存储在名为
logdata-SHARD_INDEX.csv的文件中(每个分片的大小约为 100 MB)。尽管文件扩展名为 CSV,但这些文件并非采用以英文逗号分隔的列格式:每个原始日志条目(例如原始 JSON 对象、syslog 行或 CEF 记录)都会逐字写入,后跟换行符 (\n),而不会对嵌入的换行符进行转义,因此多行原始日志(例如 XML 载荷或堆栈轨迹)可能会跨越分片文件中的多行。无法通过 API 更改输出文件格式;如需以压缩列格式(例如 Apache Parquet)存储归档,请在导出作业达到FINISHED_SUCCESS后运行下游压缩步骤。
前提条件和架构
本部分概述了使用数据导出 API 的系统架构和必要要求,并详细介绍了系统架构。您可以使用此信息来验证您的环境是否已正确配置。
在使用数据导出 API 之前,请完成以下前提步骤,设置 Google Cloud Storage 目标位置并授予必要的权限:
向用户授予权限。如需使用数据导出 API,您需要在与 Google SecOps 租户关联的 BYOP Google Cloud 项目中拥有以下权限:
- chronicle.dataExports.fetchServiceAccountForDataExport
- chronicle.dataExports.create
- chronicle.dataExports.cancel
- chronicle.dataExports.get
- chronicle.dataExports.list
这些权限属于以下预定义 IAM 角色:
- Chronicle API Admin:授予使用 API 创建、更新、取消和查看导出作业的完整权限。此角色可授予全局访问权限。
- Chronicle API Viewer:授予只读权限,以便使用 API 查看作业配置和历史记录。如果没有
restrictedDataAccess角色,拥有此角色的用户可以查看所有数据(请参阅+ 添加其他角色步骤和添加条件)。
向用户应用数据 RBAC 范围。如需将用户限制为特定数据访问权限范围,请执行以下操作:
- 确保您要应用的数据 RBAC 范围已在设置 > 访问管理 > 数据访问 > 范围下创建。记下您要分配给用户的每个范围的全名。
创建用于数据导出管理的 Identity and Access Management (IAM) 自定义角色。由于预定义角色可能会授予过多访问权限,或者不具备特定的权限组合,因此请执行以下操作,创建专为在限定范围内管理数据导出而定制的自定义角色:
- 在 Google Cloud 控制台中,前往 IAM 和管理 > 角色。
- 点击 + 创建角色。
- 输入标题(例如
SecOps Scoped Data Export User)。 - 输入 ID(例如
secopsScopedDataExportUser)。 - 点击 + 添加权限。
- 过滤 Chronicle 权限,并添加第一步(向 API 用户授予权限)中列出的相关权限。
- 点击创建。
向用户授予 IAM 角色。在 IAM 页面上,执行以下操作,为您的用户分配必要的角色:
- 前往 IAM 和管理 > IAM。
- 点击 + 授予访问权限。
- 在新的主账号中,输入用户的邮箱。
请执行以下操作来分配角色:
- 添加您创建的自定义角色(例如
SecOps Scoped Data Export User)。 - 点击 + 添加其他角色,然后添加 Chronicle API Restricted Data Access (
restrictedDataAccess) 角色。此角色对于将用户标记为受数据范围约束至关重要。
- 添加您创建的自定义角色(例如
向
Chronicle API Restricted Data Access角色绑定添加 IAM Condition。请执行以下操作,将用户关联到特定数据范围:- 点击添加 IAM 条件。
- 使用条件构建器或条件编辑器定义允许的范围,并将第一步中创建的范围名称用作资源名称。例如,如需使用名为
scope_test的范围,请设置条件resource.name.endsWith("/dataAccessScopes/scope_test")。
如需详细了解如何为数据导出 API 实现数据 RBAC,请参阅数据 RBAC 如何应用于数据导出 API。
创建 Google Cloud Storage 存储桶。在 Google Cloud项目中,在 Google SecOps 租户所在的区域中创建一个新的 Google Cloud Storage 存储桶(导出数据的目标位置)。将其设为私有,以防止未经授权的访问。对于长期归档,请为存储桶配置
STANDARD默认存储类别,以便进行初始导出写入和验证(或可选的下游 Parquet 压缩),并使用对象生命周期管理(SetStorageClass规则)将对象转换为COLDLINE或ARCHIVE存储。如需了解详情,请参阅创建存储桶。向服务账号授予权限。请执行以下操作,向与您的 Google SecOps 租户关联的 Google SecOps 服务账号授予必要的 IAM 角色,以便将数据写入您的存储桶:
调用
FetchServiceAccountForDataExportAPI 端点,以识别 Google SecOps 实例的唯一服务账号。API 会返回服务账号邮箱。示例请求:
{ "parent": "projects/myproject/locations/us/instances/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }示例响应:
{ "service_account_email": "service-1234@gcp-sa-chronicle.iam.gserviceaccount.com" }向 Google SecOps 服务账号主账号授予目标 Google Cloud Storage 存储桶的以下 IAM 角色,以便 Google SecOps 服务将导出的数据文件写入 Google Cloud Storage 存储桶:
Storage object administrator (roles/storage.objectAdmin)Legacy bucket reader (roles/storage.legacyBucketReader)
如需了解详情,请参阅向 Google SecOps 服务账号授予访问权限。
完成身份验证。数据导出 API 会对您的调用进行身份验证。如需设置此身份验证,请按照以下部分中的说明操作:
主要应用场景和核心工作流
Data Export API 提供了一套端点,用于创建数据导出作业并管理批量数据导出的整个生命周期。您可以使用 API 调用执行所有互动。
以下用例介绍了如何创建、监控和管理数据导出作业。
创建新的数据导出作业
系统会将数据导出作业规范存储在父级资源 Google SecOps 实例中。此实例是导出作业的日志数据的来源。
如需了解如何识别 Google SecOps 实例的唯一服务账号,请参阅 FetchServiceAccountForDataExports。
如需开始新的导出,请向
dataExports.create端点发送POST请求。如需了解详情,请参阅CreateDataExport端点。
监控数据导出作业状态
您可以查看特定导出作业的数据导出作业详细信息和状态,也可以配置过滤条件以查看特定类型的作业。
如需了解如何查看特定导出作业,请参阅 GetDataExport。
如需了解如何使用过滤条件列出特定类型的数据导出作业,请参阅 ListDataExport。
取消已加入队列的作业
您可以在作业状态为 IN_QUEUE 时取消作业。
如需了解如何取消已加入队列的作业,请参阅 CancelDataExport。
数据 RBAC 如何应用于数据导出 API
导出作业会继承创建导出作业的用户的 RBAC 范围,从而防止未经授权的数据提取。
如果您尝试导出的数据超出了数据访问权限范围,API 会在执行导出作业时自动排除此类数据。已完成作业(即状态为 FINISHED_SUCCESS 的作业)的元数据中 dataRbacFiltered 字段的值表示是否排除了数据。如果 dataRbacFiltered 为 true,则为导出作业选择的部分或全部数据已被排除,因为这些数据超出了适用于作业创建者的数据 RBAC 范围。如果 dataRbacFiltered 为 false,则导出作业未受数据 RBAC 范围限制的影响,并且作业中包含的所有数据均已成功导出。
API 会应用在创建作业时适用于创建者的数据 RBAC 范围。数据 RBAC 范围的任何更改都不会追溯应用于已创建的作业。
如需详细了解数据 RBAC,请参阅数据 RBAC 概览。
排查常见问题
该 API 会提供详细的出错提示,以帮助诊断问题。
| 规范代码 | 出错提示 |
|---|---|
INVALID_ARGUMENT |
INVALID_REQUEST: Invalid request parameter PARAMETER_1, PARAMETER_2, ... PARAMETER_N. Please fix the request parameters and try again. |
PERMISSION_DENIED |
INSUFFICIENT_PERMISSIONS: Unable to validate request with the current CMEK key. Please fix the CMEK key and try again |
NOT_FOUND |
BUCKET_NOT_FOUND: The destination Google Cloud Storage bucket BUCKET_NAME does not exist. Please create the destination Google Cloud Storage bucket and try again. |
NOT_FOUND |
REQUEST_NOT_FOUND: The dataExportId:DATA_EXPORT_ID does not exist. Please add a valid dataExportId and try again. |
FAILED_PRECONDITION |
BUCKET_INVALID_REGION: The Google Cloud Storage bucket BUCKET_ID's region:REGION_1 is not the same region as the SecOps tenant region:REGION_2. Please create the Google Cloud Storage bucket in the same region as SecOps tenant and try again. |
FAILED_PRECONDITION |
INSUFFICIENT_PERMISSIONS: The Service Account P4SA does not have storage.objects.create, storage.objects.get and storage.buckets.get permissions on the destination Google Cloud Storage bucket BUCKET_NAME. Please provide the required access to the Service Account and try again. |
FAILED_PRECONDITION |
INVALID_CANCELLATION: The request status is in the STATUS stage and can't be cancelled. You can only cancel the request if the status is in the IN_QUEUE stage. |
RESOURCE_EXHAUSTED |
CONCURRENT_REQUEST_LIMIT_EXCEEDED: Maximum concurrent requests limit LIMIT reached for the request size SIZE_LIMIT. Please wait for the existing requests to complete and try again. |
RESOURCE_EXHAUSTED |
REQUEST_SIZE_LIMIT_EXCEEDED: The estimated export volume: ESTIMATED_VOLUME for the request is greater than maximum allowed export volume: ALLOWED_VOLUME per request. Please try again with a request within the allowed export volume limit. |
INTERNAL |
INTERNAL_ERROR: An Internal error occurred. Please try again. |
需要更多帮助?获得社区成员和 Google SecOps 专业人士的解答。