将原始日志导出到自行管理的 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:指导出作业的唯一 dataExportId UUID(对象路径中不含连字符)。
  • 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 目标位置并授予必要的权限:

  1. 向用户授予权限。如需使用数据导出 API,您需要在与 Google SecOps 租户关联的 BYOP Google Cloud 项目中拥有以下权限:

    这些权限属于以下预定义 IAM 角色:

    • Chronicle API Admin:授予使用 API 创建、更新、取消和查看导出作业的完整权限。此角色可授予全局访问权限。
    • Chronicle API Viewer:授予只读权限,以便使用 API 查看作业配置和历史记录。如果没有 restrictedDataAccess 角色,拥有此角色的用户可以查看所有数据(请参阅+ 添加其他角色步骤和添加条件)。
  2. 向用户应用数据 RBAC 范围。如需将用户限制为特定数据访问权限范围,请执行以下操作:

    1. 确保您要应用的数据 RBAC 范围已在设置 > 访问管理 > 数据访问 > 范围下创建。记下您要分配给用户的每个范围的全名。
    2. 创建用于数据导出管理的 Identity and Access Management (IAM) 自定义角色。由于预定义角色可能会授予过多访问权限,或者不具备特定的权限组合,因此请执行以下操作,创建专为在限定范围内管理数据导出而定制的自定义角色:

      1. 在 Google Cloud 控制台中,前往 IAM 和管理 > 角色。
      2. 点击 + 创建角色。
      3. 输入标题(例如 SecOps Scoped Data Export User)。
      4. 输入 ID(例如 secopsScopedDataExportUser)。
      5. 点击 + 添加权限。
      6. 过滤 Chronicle 权限,并添加第一步(向 API 用户授予权限)中列出的相关权限。
      7. 点击创建。
  3. 向用户授予 IAM 角色。在 IAM 页面上,执行以下操作,为您的用户分配必要的角色:

    1. 前往 IAM 和管理 > IAM。
    2. 点击 + 授予访问权限。
    3. 在新的主账号中,输入用户的邮箱。
    4. 请执行以下操作来分配角色:

      1. 添加您创建的自定义角色(例如 SecOps Scoped Data Export User)。
      2. 点击 + 添加其他角色,然后添加 Chronicle API Restricted Data Access (restrictedDataAccess) 角色。此角色对于将用户标记为受数据范围约束至关重要。
  4. 向 Chronicle API Restricted Data Access 角色绑定添加 IAM Condition。请执行以下操作,将用户关联到特定数据范围:

    1. 点击添加 IAM 条件。
    2. 使用条件构建器或条件编辑器定义允许的范围,并将第一步中创建的范围名称用作资源名称。例如,如需使用名为 scope_test 的范围,请设置条件 resource.name.endsWith("/dataAccessScopes/scope_test")。

    如需详细了解如何为数据导出 API 实现数据 RBAC,请参阅数据 RBAC 如何应用于数据导出 API。

  5. 创建 Google Cloud Storage 存储桶。在 Google Cloud项目中,在 Google SecOps 租户所在的区域中创建一个新的 Google Cloud Storage 存储桶(导出数据的目标位置)。将其设为私有,以防止未经授权的访问。对于长期归档,请为存储桶配置 STANDARD 默认存储类别,以便进行初始导出写入和验证(或可选的下游 Parquet 压缩),并使用对象生命周期管理(SetStorageClass 规则)将对象转换为 COLDLINE 或 ARCHIVE 存储。如需了解详情,请参阅创建存储桶。

  6. 向服务账号授予权限。请执行以下操作,向与您的 Google SecOps 租户关联的 Google SecOps 服务账号授予必要的 IAM 角色,以便将数据写入您的存储桶:

    1. 调用 FetchServiceAccountForDataExport API 端点,以识别 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"
      }
      
    2. 向 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 服务账号授予访问权限。

  7. 完成身份验证。数据导出 API 会对您的调用进行身份验证。如需设置此身份验证,请按照以下部分中的说明操作:

    1. Google Cloud 服务的身份验证方法
    2. 应用默认凭证

主要应用场景和核心工作流

Data Export API 提供了一套端点,用于创建数据导出作业并管理批量数据导出的整个生命周期。您可以使用 API 调用执行所有互动。

以下用例介绍了如何创建、监控和管理数据导出作业。

创建新的数据导出作业

系统会将数据导出作业规范存储在父级资源 Google SecOps 实例中。此实例是导出作业的日志数据的来源。

监控数据导出作业状态

您可以查看特定导出作业的数据导出作业详细信息和状态,也可以配置过滤条件以查看特定类型的作业。

  • 如需了解如何查看特定导出作业,请参阅 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 专业人士的解答。