Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Migra de la API de SIEM heredada a la API de Chronicle

Se admite en los siguientes sistemas operativos:

Google SecOps SIEM

Este documento te ayuda a administrar las aplicaciones que llaman a cualquiera de las APIs de SIEM heredadas (API de Backstory y API de Ingestion). En él, se describen los pasos que debes seguir para configurar el acceso programático y actualizar cualquier referencia de los extremos de la API del SIEM heredado a los extremos modernos de la API de Chronicle.

Para obtener una descripción general rápida del proceso de migración, mira el video incorporado.

La superficie de la API de Chronicle presenta varias mejoras diseñadas para optimizar tu proceso de desarrollo y alinearse con los Google Cloud estándares de la API para mejorar la confiabilidad, la seguridad, el rendimiento y una integración más sólida con los Registros de auditoría de Cloud, Cloud Monitoring, Cloud Identity y Identity and Access Management (IAM). También aborda muchas de las limitaciones y complejidades de las APIs heredadas.

¿Qué aspectos cambiarán?

Todas las solicitudes programáticas a los extremos heredados de la API de Backstory y la API de Ingestion deben migrarse a la API de Chronicle moderna. Si tu organización usa integraciones personalizadas, secuencias de comandos de automatización o herramientas de terceros que realizan llamadas a estos extremos heredados, debes actualizar esas cargas de trabajo para que usen extremos y flujos de autenticación modernos antes del 20 de julio de 2027. Además, si tu organización usa Google Security Operations SOAR, debes actualizar tus integraciones y conectores de SOAR (como la integración de Google Chronicle) para usar la API de Chronicle. Para obtener más información, consulta Migra las integraciones de SOAR.

Qué se mantendrá igual

Las acciones que se realizan directamente en la interfaz de usuario (IU) de Google Security Operations ya invocan la API de Chronicle moderna. Si tu organización solo interactúa con Google SecOps a través de la IU, o si tus integraciones ya llaman a los extremos de la API de Chronicle, no es necesario que realices ninguna acción.

Cambios y mejoras clave

En la siguiente tabla, se destacan las principales diferencias entre la API de SIEM heredada y la API de Chronicle:

Área de características	API de SIEM heredada	API de Chronicle	Detalles
Administración de credenciales	Proceso manual que involucra a representantes de Google	Administración de autoservicio de cuentas de servicio, credenciales y permisos de IAM	La administración de IAM y credenciales de autoservicio simplifica la incorporación y elimina la dependencia de las solicitudes de asistencia manual.
Estándares de cumplimiento	Compatibilidad limitada	Compatibilidad integrada con los controles de residencia de datos, los Controles del servicio de VPC, la Transparencia de acceso, CMEK y FedRAMP	Los controles de infraestructura integrados modernos cumplen con los estándares de cumplimiento y reglamentarios de la industria.
Registro y auditoría	Flujos de auditoría heredados	Registros de auditoría de Cloud integrados en tu Google Cloud proyecto	La integración directa proporciona registros de auditoría y supervisión centralizados.
Autenticación	Token de API y credenciales de cuenta de servicio	OAuth 2.0 con compatibilidad para métodos de autenticación modernos, como Workload Identity y cuentas de servicio, como se describe en Autenticación para Google Cloud APIs y servicios	Estos métodos de autenticación modernos proporcionan mayor seguridad y estandarizan el flujo de credenciales.
Modelos de datos y diseño de APIs	Estructuras planas y exclusivas	Diseño orientado a los recursos, arquitectura RESTful y nomenclatura estandarizada según las AIPs	Este diseño moderno mejora la coherencia de los datos, hace que la API sea más intuitiva y simplifica la manipulación de objetos.
Nombres de extremos	Incoherente	Estandarizada y RESTful	Los nombres coherentes hacen que la API sea más intuitiva y fácil de integrar.
Ecosistema	Muy limitado	Integración con MCP, Terraform, bibliotecas cliente y SDKs	Amplia compatibilidad con herramientas modernas de la nube y frameworks de automatización
Autorización de socio	Token de socio o clave de API que se usa directamente en los códigos de los clientes	Delegación de IAM entre proyectos para recursos de usuarios; métodos de TenantService con alcance de socio	Los métodos de TenantService se ejecutan en el proyecto del socio. Todas las demás APIs de inquilino requieren la delegación de IAM entre proyectos que otorga el inquilino en el proyecto de inquilino.

Autorización de socio

Para los flujos de trabajo de socios multiusuario, la autorización en la API de Chronicle depende de la propiedad del recurso. El proyecto que aloja un recurso determina qué credenciales y permisos de IAM necesita un socio. Limitar el alcance de las operaciones del arrendatario a las credenciales delegadas por el arrendatario se alinea con el principio de seguridad fundamental de que los socios no deben poder acceder, recuperar ni modificar los datos del arrendatario sin el permiso explícito que este les otorgue. En la siguiente tabla, se compara la autorización de socios en la API heredada de Backstory y la API de Chronicle:

API	Métodos	Permiso del recurso	Autorización
API de Backstory heredada	`/v1/partner/customer/*` extremos	Todos los códigos de cliente del socio	Los socios llaman a estos extremos directamente con sus propios tokens de socio o claves de API.
API de Chronicle: `TenantService`	`CreateTenant`, `ListTenants` y `UpdateTenant`	Instancia del socio: `projects/{partner_project}/locations/{location}/instances/{partner_instance}/tenants/*`	Los socios llaman a estos métodos directamente con sus propias cuentas de servicio o credenciales que tienen permisos de `chronicle.googleapis.com/tenants.*` en el proyecto del socio.
API de Chronicle: Otros servicios, como `InstanceService` y `ForwarderService`	`GetInstance`, `UpdateInstance`, `GenerateForwarderFiles` y otros métodos con alcance para el arrendatario	Instancia del usuario: `projects/{tenant_project}/locations/{location}/instances/{tenant_instance}/...`	Las credenciales de socio por sí solas no pueden acceder a los datos del arrendatario ni modificarlos. El administrador del arrendatario debe otorgar roles de IAM, como `roles/chronicle.admin`, `roles/chronicle.viewer` o un rol personalizado, a la cuenta de servicio del socio o al principal de la federación de identidades para cargas de trabajo en el proyecto Google Cloud del arrendatario.

Programa de baja

Está previsto que la API de SIEM heredada se dé de baja el 20 de julio de 2027. Te recomendamos que completes la migración antes de esta fecha para evitar interrupciones en el servicio:

A partir del 26 de octubre de 2026, ya no podrás llamar a las APIs heredadas (API de Backstory y API de Ingestion) desde instancias nuevas.
Antes del 20 de julio de 2027, debes migrar todas las instancias existentes a la API de Chronicle, ya que las APIs heredadas ya no estarán disponibles.

Antes de comenzar

Antes de migrar a la API de Chronicle, asegúrate de completar lo siguiente:

Implementación en la infraestructura de SIEM moderna: Asegúrate de que la instancia se implemente en tu proyecto o en el de tu socio de MSSP Google Cloud con la infraestructura de SIEM moderna. Para obtener instrucciones detalladas, consulta la descripción general de la migración del SIEM.
Habilita la API de Chronicle: En la consola de Google Cloud , navega al proyecto que aloja tu instancia y habilita la API de Chronicle (chronicle.googleapis.com). Para obtener más detalles, consulta Cómo habilitar una API en tu proyecto de Google Cloud .
Identifica las integraciones de SOAR: Si tu entorno conecta Google SecOps SOAR con Google Security Operations SIEM, verifica tus conectores existentes. Para obtener más información, consulta Migra las integraciones de SOAR.

Migra las integraciones de SOAR

Si tu organización conecta Google SecOps SOAR a Google SecOps SIEM, debes migrar tus integraciones y conectores de SOAR (como la integración de Google Chronicle) para usar la API de Chronicle.

Para obtener instrucciones detalladas sobre cómo actualizar la integración y los conectores de Google Chronicle para usar la API de Chronicle, lo que incluye cómo ubicar la raíz de la API de Chronicle de tu entorno y configurar las credenciales de autenticación, consulta Migración de la API de Backstory a la API de Chronicle.

Migra a la API de Chronicle

Para migrar tus secuencias de comandos e integraciones personalizadas de las APIs heredadas a la API de Chronicle, completa los siguientes pasos:

Audita el uso de la API: Identifica todas las secuencias de comandos personalizadas y las integraciones de tu entorno que invocan extremos heredados.
Configura la autenticación y la autorización: Configura tu entorno para autenticar y autorizar solicitudes a la API de Chronicle.
Asigna extremos y actualiza URLs: Reemplaza los extremos heredados por sus equivalentes regionales modernos.
Actualiza la lógica de la API: Ajusta las cargas útiles de las solicitudes y el control de respuestas para que coincidan con los modelos de datos de la API moderna.
Prueba tu integración: Valida los cambios en un entorno de pruebas antes de implementarlos en producción.

Audita el uso de la API

Audita tu entorno para identificar secuencias de comandos o integraciones personalizadas que invoquen backstory.googleapis.com o malachiteingestion-pa.googleapis.com. Puedes identificar estas integraciones revisando tu base de código, tus secuencias de comandos de automatización y tus herramientas de terceros. Si tu organización también usa Google SecOps SOAR, consulta Migra las integraciones de SOAR.

Configura la autenticación y la autorización

Configura tu entorno para autenticar y autorizar solicitudes a la API de Chronicle:

Elige un método de autenticación: Elige cómo se autenticarán tus cargas de trabajo en la API de Chronicle con uno de los métodos que se indican. Te recomendamos que uses la federación de identidades para cargas de trabajo para mejorar la seguridad, ya que evita la administración y el almacenamiento de claves de cuentas de servicio de larga duración. Para situaciones avanzadas de autenticación (como la identidad temporal como cuenta de servicio), consulta Autenticación en la API de Chronicle.
- Federación de identidades para cargas de trabajo (recomendado): Configura la federación de identidades para cargas de trabajo para permitir que las cargas de trabajo que se ejecutan fuera de Google Cloud se autentiquen con identidades externas.
- Cuentas de servicio: Si debes usar cuentas de servicio, crea una cuenta de servicio en tu proyecto de Google Cloud y genera y descarga una clave privada en formato JSON. Protege esta clave.
Otorga permisos de IAM: Otorga los permisos de IAM necesarios a la identidad (ya sea la cuenta de servicio o la principal de identidad externa) que se usa para la autenticación. Consulta la asignación de extremo de API SIEM para encontrar los permisos de IAM específicos que se requieren para los extremos modernos que reemplazan tus llamadas heredadas.
- Rol personalizado (recomendado): Crea un rol personalizado de IAM con los permisos necesarios y otorga el rol personalizado a la cuenta de servicio o a la principal de identidad externa.
- Rol predefinido: Otorga un rol predefinido de Google SecOps a la cuenta de servicio o a la identidad externa principal. Es probable que esto otorgue más acceso del necesario para una automatización específica.
- Delegación de socios de múltiples usuarios: Si eres un MSSP o un socio que administra recursos de usuarios fuera de TenantService (como GetInstance, UpdateInstance o GenerateForwarderFiles), el administrador del usuario debe otorgar explícitamente a tu cuenta de servicio o principal de federación de identidades para cargas de trabajo los roles de IAM necesarios en el proyecto Google Cloud del usuario.
Configura la variable de entorno de las credenciales: Configura tu entorno de ejecución para usar las credenciales con las credenciales predeterminadas de la aplicación (ADC) estableciendo la variable de entorno GOOGLE_APPLICATION_CREDENTIALS. Esta variable debe apuntar al archivo JSON de la clave de la cuenta de servicio descargado o al archivo de configuración de credenciales de la federación de identidades para cargas de trabajo. Las bibliotecas cliente deGoogle Cloud detectan automáticamente esta variable para autenticar solicitudes:
```
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"
```
Actualiza los permisos de OAuth: Actualiza la cadena de permisos si tus secuencias de comandos de integración heredadas solicitaron de forma explícita permisos de OAuth para la generación de tokens. El permiso heredado no otorga acceso a la superficie de la API moderna:
- Alcance de la historia de fondo heredada: https://www.googleapis.com/auth/chronicle-backstory
- Alcance de Chronicle: https://www.googleapis.com/auth/chronicle (o el alcance más amplio https://www.googleapis.com/auth/cloud-platform).

Asigna extremos y actualiza URLs

Familiarízate con la superficie de la API de Chronicle, asigna tus llamadas heredadas y actualiza los extremos de servicio en tu aplicación.

Revisa la documentación de referencia

Familiarízate con la documentación completa de la API de Chronicle.

Asigna extremos a la API de Chronicle

Identifica los extremos modernos correspondientes para cada una de las llamadas a la API heredada que realiza tu aplicación. Del mismo modo, asigna tus modelos de datos existentes a las estructuras modernas, teniendo en cuenta los cambios de esquema o los campos adicionales. Para obtener detalles sobre todos los extremos de SIEM, consulta Asignación de extremo de API SIEM. Si tu flujo de trabajo también interactúa con extremos de SOAR, consulta la tabla de asignación de extremo de API SOAR.

Actualiza el extremo del servicio

Actualiza la URL base de tus llamadas a la API para que apunten al extremo de servicio regional correcto. La API de Chronicle es un servicio regional, por lo que debes llamar al extremo de servicio regional que coincida con la ubicación de tu instancia de Google SecOps.

Todos los extremos modernos usan un prefijo coherente, lo que hace que la dirección del extremo final sea predecible. En el siguiente ejemplo, se muestra la estructura de la URL del endpoint moderno:

[api_version]/projects/[project_id]/locations/[location]/instances/[instance_id]/...

Esta estructura crea la dirección final del extremo de la siguiente manera:

https://[service_endpoint]/[api_version]/projects/[project_id]/locations/[location]/instances/[instance_id]/...

Aquí:

service_endpoint: Es una dirección de servicio regional.
api_version: Es la versión de la API que se consultará. Puede ser v1alpha, v1beta o v1.
project_id: Es tu ID del proyecto (el mismo que definiste para tus permisos de IAM).
location: Es la ubicación de tu proyecto (región), que es la misma que la de los extremos regionales.
instance_id: Es tu ID de cliente de Google SecOps SIEM.

Direcciones regionales:

africa-south1: https://africa-south1-chronicle.googleapis.com o https://chronicle.africa-south1.rep.googleapis.com
asia-northeast1: https://asia-northeast1-chronicle.googleapis.com o https://chronicle.asia-northeast1.rep.googleapis.com
asia-south1: https://asia-south1-chronicle.googleapis.com o https://chronicle.asia-south1.rep.googleapis.com
asia-southeast1: https://asia-southeast1-chronicle.googleapis.com o https://chronicle.asia-southeast1.rep.googleapis.com
asia-southeast2: https://asia-southeast2-chronicle.googleapis.com o https://chronicle.asia-southeast2.rep.googleapis.com
australia-southeast1: https://australia-southeast1-chronicle.googleapis.com o https://chronicle.australia-southeast1.rep.googleapis.com
europe-west12: https://europe-west12-chronicle.googleapis.com o https://chronicle.europe-west12.rep.googleapis.com
europe-west2: https://europe-west2-chronicle.googleapis.com o https://chronicle.europe-west2.rep.googleapis.com
europe-west3: https://europe-west3-chronicle.googleapis.com o https://chronicle.europe-west3.rep.googleapis.com
europe-west6: https://europe-west6-chronicle.googleapis.com o https://chronicle.europe-west6.rep.googleapis.com
europe-west9: https://europe-west9-chronicle.googleapis.com o https://chronicle.europe-west9.rep.googleapis.com
me-central1: https://me-central1-chronicle.googleapis.com o https://chronicle.me-central1.rep.googleapis.com
me-central2: https://me-central2-chronicle.googleapis.com o https://chronicle.me-central2.rep.googleapis.com
me-west1: https://me-west1-chronicle.googleapis.com o https://chronicle.me-west1.rep.googleapis.com
northamerica-northeast2: https://northamerica-northeast2-chronicle.googleapis.com o https://chronicle.northamerica-northeast2.rep.googleapis.com
southamerica-east1: https://southamerica-east1-chronicle.googleapis.com o https://chronicle.southamerica-east1.rep.googleapis.com
Estados Unidos (us): https://us-chronicle.googleapis.com o https://chronicle.us.rep.googleapis.com
Europa (eu): https://eu-chronicle.googleapis.com o https://chronicle.eu.rep.googleapis.com

Para obtener una lista completa de todos los extremos admitidos, consulta la referencia oficial en la documentación del extremo de servicio de la API de Chronicle.

Por ejemplo, para enumerar todas las reglas de detección de una instancia en la ubicación us, envía la siguiente solicitud:

GET
  https://us-chronicle.googleapis.com/v1alpha/projects/my-project-name-or-id/locations/us/instances/408bfb7b-5746-4a50-885a-50a323023529/rules

Del mismo modo, para consultar recursos de SOAR, como casos, con el alias del extremo regional (rep), envía la siguiente solicitud:

GET
  https://chronicle.us.rep.googleapis.com/v1alpha/projects/my-project-name-or-id/locations/us/instances/408bfb7b-5746-4a50-885a-50a323023529/cases

Actualiza la lógica de la API

Revisa la referencia de la API de REST de Chronicle para identificar e implementar cambios en los nombres de los campos y las estructuras de datos de tu aplicación. Si bien algunos extremos heredados pueden seguir siendo similares, debes actualizar tus integraciones para que coincidan con los modelos de datos y las estructuras de extremos más recientes.

Usa Google Cloud bibliotecas cliente

Simplifica tu integración para controlar automáticamente la autenticación, la actualización de tokens y los detalles de transporte. Te recomendamos que uses las bibliotecas cliente oficiales de Google Cloud para hacerlo. La compatibilidad con la API de Chronicle está disponible en ocho lenguajes de programación, incluidos Python, Go, Java, Node.js y C#. Para obtener detalles sobre la instalación y el uso, consulta Bibliotecas cliente y SDK.

Prueba tu integración

Prueba tu aplicación actualizada en un entorno de pruebas antes de implementarla en producción:

Crea un plan de pruebas: Define casos de prueba que abarquen todas las funcionalidades migradas.
Ejecuta pruebas: Realiza pruebas automatizadas y manuales para confirmar la precisión y la validez.
Supervisa el rendimiento: Evalúa el rendimiento de tu aplicación con la API moderna.

Solucionar problemas

En esta sección, se describe cómo resolver errores comunes que puedes encontrar durante la migración.

HTTP 403 prohibido o PERMISSION_DENIED

Si tus llamadas a la API devuelven un error HTTP 403 Forbidden o PERMISSION_DENIED, verifica lo siguiente:

Método de autenticación y principal: Asegúrate de usar las credenciales correctas.
- Si usas la federación de identidades para cargas de trabajo, verifica que la principal de identidad externa coincida con la principal vinculada a los roles de IAM en tu proyecto.
- Si usas una cuenta de servicio, verifica que se esté usando la cuenta de servicio correcta y que no se haya inhabilitado. No uses cuentas de servicio heredadas (que suelen contener bk o malachite-cx en su dirección de correo electrónico) para los endpoints de API de Chronicle modernos.
Roles de IAM: Verifica que a la cuenta de servicio o a la identidad externa principal se le hayan otorgado los roles de IAM predefinidos o personalizados necesarios (como Chronicle API Viewer o Chronicle API Editor) en tu proyecto Google Cloud . Para obtener información sobre los permisos detallados de los endpoints de API, consulta Asignación de extremo de API SIEM.

HTTP 401 Unauthorized o UNAUTHENTICATED

Si tus llamadas a la API fallan con HTTP 401 Unauthorized o UNAUTHENTICATED, verifica lo siguiente:

Permisos de OAuth: Verifica que tus secuencias de comandos personalizadas soliciten el permiso moderno: https://www.googleapis.com/auth/chronicle (o el permiso más amplio https://www.googleapis.com/auth/cloud-platform). El permiso heredado (https://www.googleapis.com/auth/chronicle-backstory) no otorga acceso a la API de Chronicle moderna.
Variable de entorno: Confirma que la variable de entorno GOOGLE_APPLICATION_CREDENTIALS esté configurada y apunte al archivo de claves JSON o al archivo de configuración de la federación de identidades para cargas de trabajo correctos en tu entorno de ejecución.

Error HTTP 404 Not Found o discrepancias regionales

Si tus llamadas a la API devuelven un HTTP 404 Not Found o no se conectan, verifica tus extremos regionales:

Extremo regional: La API de Chronicle es un servicio regional. Verifica que estés llamando al extremo que coincide con la región de tu instancia de Google SecOps (por ejemplo, https://europe-west3-chronicle.googleapis.com para una instancia en Frankfurt). Si envías solicitudes a una región diferente, se producirán errores. Para obtener una lista completa de las direcciones regionales, consulta Actualiza el extremo de servicio o la referencia oficial del extremo de servicio.

¿Qué sigue?

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