Exporta registros sin procesar a un bucket de Google Cloud Storage autoadministrado

Compatible con:

La API de Exportación de datos facilita la exportación masiva de tus datos de seguridad de Google Security Operations a un bucket de Google Cloud Storage que controlas. Esta capacidad admite la retención de datos críticos a largo plazo, el análisis forense histórico y los requisitos de cumplimiento estrictos (como SOX y GDPR).

Para obtener información detallada de referencia de la API, consulta API de exportación de datos (mejorada).

La API de Data Export proporciona una solución escalable y confiable para las exportaciones de datos de un momento determinado y controla solicitudes de hasta 100 TB.

Como canalización administrada, ofrece funciones esenciales de nivel empresarial, incluidas las siguientes:

  • Reintentos automáticos en caso de errores transitorios
  • Supervisión integral del estado de los trabajos
  • Un registro de auditoría completo para cada trabajo de exportación

La API particiona de forma lógica los datos exportados por fecha y hora dentro de tu bucket de Google Cloud Storage.

Esta función te permite crear flujos de trabajo de descarga de datos a gran escala. Google SecOps administra la complejidad del proceso de exportación para proporcionar estabilidad y rendimiento.

Ventajas clave

La API de Exportación de datos proporciona una solución resiliente y auditable para administrar el ciclo de vida de tus datos de seguridad, con los siguientes beneficios clave:

  • Confiabilidad: El servicio controla las transferencias de datos a gran escala. El sistema usa una estrategia de retirada exponencial para reintentar automáticamente los trabajos de exportación que encuentran problemas transitorios (por ejemplo, problemas de red temporales), lo que lo hace resiliente. Si tu trabajo de exportación falla debido a un error transitorio, se vuelve a intentar automáticamente varias veces. Si un trabajo falla de forma permanente después de todos los reintentos, el sistema actualiza su estado a FINISHED_FAILURE, y la respuesta de la API para ese trabajo contiene un mensaje de error detallado que explica la causa.
  • Auditabilidad integral: Para cumplir con los estrictos estándares de cumplimiento y seguridad, el sistema captura todas las acciones relacionadas con un trabajo de exportación en un registro de auditoría inmutable. Este registro incluye la creación, el inicio, el éxito o el fracaso de cada trabajo, junto con el usuario que inició la acción, una marca de tiempo y los parámetros del trabajo.

  • Optimizado para el rendimiento y el escalamiento: La API usa un sistema sólido de administración de trabajos. Este sistema incluye la puesta en cola y la priorización para proporcionar estabilidad a la plataforma y evitar que un solo usuario monopolice los recursos.

  • Mejora la integridad y la accesibilidad de los datos: El sistema organiza automáticamente los datos en una estructura de directorio lógica dentro de tu bucket de Google Cloud Storage, lo que te ayuda a ubicar y consultar períodos específicos para el análisis histórico.

  • Seguridad: La API está diseñada para cumplir por completo con las claves de encriptación administradas por el cliente (CMEK) (seguridad de confianza cero) y el RBAC de datos (acceso con privilegios mínimos). Los trabajos de exportación heredan el permiso de visibilidad de los datos del usuario que activa la solicitud para evitar la extracción de datos no autorizada. La canalización de exportación también está completamente integrada en Google Cloud Key Management Service, y los datos permanecen encriptados en reposo en tu bucket de Google Cloud Storage con tus propias claves.

Términos y conceptos clave

  • Trabajo de exportación: Es una operación asíncrona única para exportar un período específico de datos de registro a un bucket de Google Cloud Storage. El sistema hace un seguimiento de cada trabajo con un dataExportId único.
  • Estado del trabajo: Es el estado actual de un trabajo de exportación en su ciclo de vida (por ejemplo, IN_QUEUE, PROCESSING, FINISHED_SUCCESS).
  • Bucket de Google Cloud Storage: Es un bucket de Google Cloud Storage propiedad del usuario que sirve como destino para los datos exportados.
  • Tipos de registros: Son las categorías específicas de registros que puedes exportar (por ejemplo, NIX_SYSTEM, WINDOWS_DNS, CB_EDR). Para obtener más detalles, consulta la lista de todos los tipos de registros admitidos.

Comprende la estructura de los datos exportados

Cuando un trabajo se completa de forma correcta, el sistema escribe los datos en tu bucket de Cloud Storage. Usa una estructura de directorios particionada específica para simplificar el acceso a los datos y las consultas.

Estructura de la ruta de acceso del directorio: gs://GCS_BUCKET_NAME/EXPORT_JOB_NAME/LOGTYPE/EVENT_TIME_BUCKET/EPOCH_EXECUTION_TIME/logdata-SHARD_INDEX.csv

Aquí:

  • GCS_BUCKET_NAME: hace referencia al nombre de tu bucket de Google Cloud Storage.
  • EXPORT_JOB_NAME: hace referencia al UUID único de dataExportId de tu trabajo de exportación (sin guiones en la ruta de acceso del objeto).
  • LOGTYPE: hace referencia al nombre del tipo de registro de los datos exportados (por ejemplo, GCP_DNS o WINDOWS_DNS).
  • EVENT_TIME_BUCKET: Se refiere al bucket de horas de las marcas de tiempo de los eventos de los registros exportados, redondeado hacia abajo al inicio de la hora UTC (YYYY/MM/DD/HH/00/00). Por ejemplo, 2025/08/25/01/00/00 contiene registros con marcas de tiempo de eventos entre las 01:00:00 UTC y las 01:59:59 UTC del 25 de agosto de 2025.
  • EPOCH_EXECUTION_TIME: Se refiere a la marca de tiempo Unix epoch de 20 dígitos rellenada con ceros en microsegundos que indica cuándo comenzó la ejecución del trabajo de exportación (por ejemplo, 00001756083600000000).
  • logdata-SHARD_INDEX.csv: Se refiere a los archivos fragmentados con índice 0 que contienen registros sin procesar (por ejemplo, logdata-0.csv y logdata-1.csv). Cada fragmento de archivo tiene un tamaño aproximado de 100 MB.

Ejemplo de ruta de objeto exportado:

gs://my-archive-bucket/b4a3c2d1e8f76a5b4c3d2e1f0a9b8c7d/GCP_DNS/2025/08/25/01/00/00/00001756083600000000/logdata-0.csv

Manifiesto de finalización de la exportación (exported_paths.txt):

Cuando un trabajo de exportación finaliza con el estado FINISHED_SUCCESS y escribe al menos un archivo de registro, la canalización también escribe un archivo de manifiesto en gs://GCS_BUCKET_NAME/EXPORT_JOB_NAME/exported_paths.txt (si ningún registro coincide con los filtros de exportación o el período, no se escribe ningún archivo de manifiesto y dataExportStatus.exportedGlobPatterns queda vacío). Cada línea de exported_paths.txt enumera un patrón de glob con el prefijo /bigstore/ (/bigstore/GCS_BUCKET_NAME/EXPORT_JOB_NAME/LOGTYPE/EVENT_TIME_BUCKET/EPOCH_EXECUTION_TIME/*, que se asigna a gs://GCS_BUCKET_NAME/.../*) para un directorio de partición por hora que escribe el trabajo. Los trabajos de automatización o compactación downstream pueden leer este manifiesto para enumerar todas las particiones exportadas sin enumerar todo el bucket.

Rendimiento y limitaciones

El servicio tiene los siguientes límites específicos para garantizar la estabilidad de la plataforma y la asignación justa de recursos:

  • Volumen máximo de datos por trabajo: Cada trabajo de exportación individual puede solicitar hasta 100 TB de datos. Para conjuntos de datos más grandes, Google recomienda dividir la exportación en varios trabajos con períodos más cortos.
  • Trabajos simultáneos: Cada usuario de cliente puede ejecutar o poner en cola un máximo de tres trabajos de exportación de forma simultánea. El sistema rechaza cualquier solicitud de creación de trabajos nuevos que supere este límite.
  • Tiempos de finalización de los trabajos: El volumen de datos exportados determina los tiempos de finalización de los trabajos. Un solo trabajo puede tardar hasta 18 horas.
  • Formato de exportación y alcance de los datos: La API admite exportaciones masivas en un momento determinado, con las siguientes limitaciones y características:
    • Solo registros sin procesar: Solo puedes exportar registros sin procesar (no registros de UDM, eventos de UDM ni detecciones). Para obtener información sobre cómo exportar datos de UDM, consulta Exporta a un proyecto de BigQuery autoadministrado.
    • Formato de archivo y compresión de datos: La API exporta datos como cadenas de registro sin procesar, sin comprimir y delimitadas por saltos de línea dentro de archivos llamados logdata-SHARD_INDEX.csv (con un tamaño aproximado de 100 MB por fragmento). A pesar de la extensión de nombre de archivo CSV, los archivos no tienen el formato de columnas separadas por comas: cada entrada de registro sin procesar (por ejemplo, un objeto JSON sin procesar, una línea de syslog o un registro CEF) se escribe de forma literal seguida de un carácter de línea nueva (\n) sin omitir las líneas nuevas incorporadas, por lo que los registros sin procesar de varias líneas (como cargas útiles XML o seguimientos de pila) pueden abarcar varias líneas dentro de un archivo de fragmento. El formato del archivo de salida no se puede cambiar a través de la API. Para almacenar archivos en formatos de columnas comprimidos, como Apache Parquet, ejecuta un paso de compactación descendente después de que el trabajo de exportación alcance el estado FINISHED_SUCCESS.

Requisitos previos y arquitectura

En esta sección, se describen la arquitectura del sistema y los requisitos necesarios para usar la API de Exportación de datos, y se detalla la arquitectura del sistema. Usa esta información para verificar que tu entorno esté configurado de forma correcta.

Antes de usar la API de Exportación de datos, completa los siguientes pasos de requisitos previos para configurar tu destino de Google Cloud Storage y otorgar los permisos necesarios:

  1. Otorga permisos al usuario. Para usar la API de Exportación de datos, necesitas los siguientes permisos en el proyecto de BYOP Google Cloud vinculado a tu usuario de Google SecOps:

    Estos permisos forman parte de los siguientes roles predefinidos de IAM:

  2. Aplica permisos de RBAC de datos a un usuario. Sigue estos pasos para restringir el acceso de un usuario a permisos de acceso a datos específicos:

    1. Asegúrate de que los permisos de RBAC de datos que deseas aplicar ya estén creados en Configuración > Administración de accesos > Acceso a los datos > Permisos. Anota el nombre completo de cada permiso que quieras asignarle al usuario.
    2. Crea un rol personalizado de Identity and Access Management (IAM) para administrar la exportación de datos. Debido a que los roles predefinidos pueden otorgar demasiado acceso o no tener la combinación específica de permisos, haz lo siguiente para crear un rol personalizado adaptado para administrar las exportaciones de datos dentro de un contexto con alcance:

      1. En la consola de Google Cloud , ve a IAM y administración > Roles.
      2. Haz clic en + Crear rol.
      3. Ingresa un título (por ejemplo, SecOps Scoped Data Export User).
      4. Ingresa un ID (por ejemplo, secopsScopedDataExportUser).
      5. Haz clic en + Agregar permisos.
      6. Filtra por permisos de Chronicle y agrega los permisos pertinentes que se indican en el primer paso (Otorga permisos al usuario de la API).
      7. Haz clic en Crear.
  3. Otorga roles de IAM al usuario. En la página de IAM, haz lo siguiente para asignar los roles necesarios a tu usuario:

    1. Ve a IAM y administración > IAM.
    2. Haz clic en + Otorgar acceso.
    3. En Principales nuevas, ingresa la dirección de correo electrónico del usuario.
    4. Para asignar roles, haz lo siguiente:

      1. Agrega el rol personalizado que creaste (por ejemplo, SecOps Scoped Data Export User).
      2. Haz clic en + Agregar otro rol y agrega el rol Acceso a los datos restringidos de la API de Chronicle (restrictedDataAccess). Este rol es fundamental para marcar al usuario como sujeto a los permisos de datos.
  4. Agrega una condición de IAM a la vinculación de rol de Chronicle API Restricted Data Access. Para vincular al usuario con permisos de datos específicos, haz lo siguiente:

    1. Haz clic en Agregar condición de IAM.
    2. Usa el Creador de condiciones o el Editor de condiciones para definir los permisos permitidos, con el nombre del permiso creado en el primer paso como el nombre del recurso. Por ejemplo, para usar un permiso llamado scope_test, establece la condición resource.name.endsWith("/dataAccessScopes/scope_test").

    Para obtener más información sobre cómo se implementa el RBAC de datos para la API de exportación de datos, consulta Cómo se aplica el RBAC de datos a la API de exportación de datos.

  5. Crea un bucket de Google Cloud Storage. En tu proyecto de Google Cloud, crea un nuevo bucket de Google Cloud Storage (el destino de tus datos exportados) en la misma región que tu usuario de Google SecOps. Hazlo privado para evitar el acceso no autorizado. Para el archivado a largo plazo, configura el bucket con la clase de almacenamiento predeterminada STANDARD para las escrituras y la verificación de la exportación inicial (o la compactación opcional de Parquet posterior) y usa la Administración del ciclo de vida de los objetos (reglas SetStorageClass) para transferir objetos al almacenamiento COLDLINE o ARCHIVE. Para obtener más detalles, consulta Crea un bucket.

  6. Otorga permisos a la cuenta de servicio. Sigue estos pasos para otorgar a la cuenta de servicio de Google SecOps, que está vinculada a tu inquilino de Google SecOps, los roles de IAM necesarios para escribir datos en tu bucket:

    1. Llama al extremo de la API de FetchServiceAccountForDataExport para identificar la cuenta de servicio única de tu instancia de Google SecOps. La API devuelve el correo electrónico de la cuenta de servicio.

      Solicitud de ejemplo:

      {
        "parent": "projects/myproject/locations/us/instances/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
      }
      

      Respuesta de ejemplo:

      {
        "service_account_email": "service-1234@gcp-sa-chronicle.iam.gserviceaccount.com"
      }
      
    2. Otorga a la principal de la cuenta de servicio de Google SecOps los siguientes roles de IAM para el bucket de Google Cloud Storage de destino, que permiten que el servicio de Google SecOps escriba archivos de datos exportados en tu bucket de Google Cloud Storage:

      • Storage object administrator (roles/storage.objectAdmin)
      • Legacy bucket reader (roles/storage.legacyBucketReader)

      Para obtener más detalles, consulta Otorga acceso a la cuenta de servicio de Google SecOps.

  7. Completa la autenticación. La API de exportación de datos autentica tus llamadas. Para configurar esta autenticación, sigue las instrucciones que se indican en las siguientes secciones:

    1. Métodos de autenticación para los servicios de Google Cloud
    2. Credenciales predeterminadas de la aplicación

Casos de uso clave y flujo de trabajo principal

La API de Data Export proporciona un conjunto de extremos para crear trabajos de exportación de datos y administrar todo el ciclo de vida de la exportación masiva de datos. Todas las interacciones se realizan con llamadas a la API.

En los siguientes casos de uso, se describe cómo crear, supervisar y administrar trabajos de exportación de datos.

Crea un trabajo de exportación de datos nuevo

El sistema almacena las especificaciones del trabajo de exportación de datos en la instancia de Google SecOps del recurso superior. Esta instancia es la fuente de los datos de registro para el trabajo de exportación.

  • Para aprender a identificar la cuenta de servicio única de tu instancia de Google SecOps, consulta FetchServiceAccountForDataExports.

  • Para iniciar una exportación nueva, envía una solicitud POST al extremo dataExports.create. Para obtener más información, consulta Extremo CreateDataExport.

Supervisa el estado del trabajo de exportación de datos

Puedes ver los detalles y el estado de un trabajo de exportación de datos específico, o bien configurar un filtro para ver ciertos tipos de trabajos.

  • Para obtener información sobre cómo ver un trabajo de exportación específico, consulta GetDataExport.

  • Para aprender a enumerar ciertos tipos de trabajos de exportación de datos con un filtro, consulta ListDataExport.

Cancela trabajos en cola

Puedes cancelar un trabajo cuando su estado es IN_QUEUE.

Para obtener información sobre cómo cancelar un trabajo en cola, consulta CancelDataExport.

Cómo se aplica el RBAC de datos a la API de exportación de datos

Los trabajos de exportación heredan el permiso de RBAC de datos de los usuarios que crean un trabajo de exportación, lo que evita la extracción de datos no autorizada.

Si intentas exportar datos que están fuera del alcance de tu acceso a los datos, la API los excluye automáticamente cuando se ejecuta el trabajo de exportación. El valor del campo dataRbacFiltered en los metadatos de los trabajos completados (es decir, los trabajos con el estado FINISHED_SUCCESS) indica si se excluyeron datos. Si dataRbacFiltered es true, se excluyeron algunos o todos los datos seleccionados para el trabajo de exportación porque estaban fuera de los permisos de RBAC de datos aplicables al creador del trabajo. Si dataRbacFiltered es false, el trabajo de exportación no se vio afectado por las restricciones de permisos del RBAC de datos, y todos los datos incluidos como parte del trabajo se exportaron correctamente.

La API aplica los permisos de RBAC de datos que corresponden al creador en el momento de la creación del trabajo. Los cambios en los permisos de RBAC de datos no se aplican de forma retroactiva a los trabajos que ya se crearon.

Para obtener más información sobre el RBAC de datos, consulta Descripción general del RBAC de datos.

Soluciona los problemas comunes.

La API proporciona mensajes de error detallados para ayudar a diagnosticar problemas.

Código canónico Mensaje de error
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.

¿Necesitas más ayuda? Obtén respuestas de miembros de la comunidad y profesionales de Google SecOps.