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

Compatible con:

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 las referencias de los extremos de la API de SIEM heredada 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 estándares de la API de Google Cloud 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 realizar la transición 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 detalles, consulta Migra integraciones de SOAR.

Qué se mantiene 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 credenciales y de IAM de autoservicio simplifica la incorporación y elimina la dependencia de las solicitudes de asistencia manuales.
Estándares de cumplimiento	Asistencia limitada	Compatibilidad integrada con los controles de residencia de datos, los Controles del servicio de VPC, la Transparencia de acceso, las CMEK y FedRAMP	Los controles de infraestructura integrados modernos cumplen con los estándares regulatorios y de cumplimiento de la industria.
Registro y auditoría	Flujos de auditoría heredados	Registros de auditoría de Cloud integrados en tu proyecto de Google Cloud	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 con métodos de autenticación modernos, incluidas las cuentas de servicio y Workload Identity, como se describe en Autenticación para las APIs y los servicios de Google Cloud	Estos métodos de autenticación modernos proporcionan una seguridad mejorada y estandarizan el flujo de credenciales.
Modelos de datos y diseño de APIs	Estructuras planas y de propiedad	Diseño orientado a recursos, arquitectura de RESTful y nombres estandarizados que siguen las AIP	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.
Asignación de nombres de extremos	Incoherente	RESTful y estandarizada	La coherencia en los nombres hace 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 socios	Token de socio o clave de API que se usa directamente en los códigos de cliente	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 usuario requieren la delegación de IAM entre proyectos que otorga el usuario en el proyecto de usuario.

Autorización de socios

En el caso de los flujos de trabajo de socios multiusuario, la autorización en la API de Chronicle depende de la propiedad de los recursos. El proyecto que aloja un recurso determina qué credenciales y permisos de IAM necesita un socio. Limitar las operaciones de los inquilinos a las credenciales delegadas por ellos se alinea con el principio de seguridad fundamental de que los socios no deben poder acceder a los datos de los inquilinos, recuperarlos ni modificarlos sin el permiso explícito otorgado por el inquilino. En la siguiente tabla, se compara la autorización de socios en la API de Backstory heredada 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 de usuario	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 usuario ni modificarlos. El administrador del usuario debe otorgar roles de IAM, como `roles/chronicle.admin`, `roles/chronicle.viewer` o un rol personalizado, a la cuenta de servicio del socio o a la principal de la federación de identidades para cargas de trabajo en el proyecto de Google Cloud del usuario.

Para obtener una tabla de reemplazo método por método y guías detalladas de paridad de solicitudes y respuestas para los endpoints de API heredados de la API de Management de Customer (como CreateCustomer a CreateTenant y GetCustomer a GetInstance), consulta las filas Partner (Customer Management) en Asignación de extremo de API de SIEM.

Programa de baja

La API de SIEM heredada se cerrará 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 dejarán de estar disponibles.

Antes de comenzar

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

Implementa en una 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 Descripción general de la migración de 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 Habilita 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 detalles, consulta Migra 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, incluida la ubicación de la raíz de la API de Chronicle de tu entorno y la configuración de 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 y, también, 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 y las integraciones personalizadas 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 las 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 manejo de las respuestas para que coincidan con los modelos de datos de la API moderna.
Prueba tu integración: Valida los cambios en un entorno de etapa 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. Para identificar estas integraciones, revisa tu base de código, las secuencias de comandos de automatización y las herramientas de terceros. Si tu organización también usa Google SecOps SOAR, consulta Migra 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 autentican 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 administrar y almacenar claves de cuentas de servicio de larga duración. Para situaciones de autenticación avanzadas (como la identidad temporal como cuenta de servicio), consulta Autentícate 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 de SIEM para encontrar los permisos de IAM específicos que se requieren para los endpoints modernos que reemplazan tus llamadas heredadas.
- Rol personalizado (recomendado): Crea un rol de IAM personalizado con los permisos necesarios y otórgalo 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 principal de identidad externa. 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 de usuarios debe otorgar de forma explícita a tu cuenta de servicio o principal de la federación de identidades para cargas de trabajo los roles de IAM necesarios en el proyecto de Google Cloud del usuario.
Configura la variable de entorno de credenciales: Configura tu entorno de ejecución para usar las credenciales con las credenciales predeterminadas de la aplicación (ADC) configurando 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 las 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 explícitamente permisos de OAuth para la generación de tokens. El permiso heredado no otorga acceso a la plataforma de la API moderna:
- Permiso de Backstory heredado: https://www.googleapis.com/auth/chronicle-backstory
- Permiso de Chronicle: https://www.googleapis.com/auth/chronicle (o el permiso https://www.googleapis.com/auth/cloud-platform más amplio).

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 cualquier cambio de esquema o campo adicional. Para obtener asignaciones de métodos en paralelo y guías detalladas de paridad de solicitudes y respuestas en todos los endpoints de SIEM, incluidas la API de Backstory, la API de Customer Management y la API de Ingestion, consulta Asignación de extremo de API de SIEM. Si tu flujo de trabajo también interactúa con los 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 del 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 extremo moderno:

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

Esta estructura hace que la dirección final al extremo sea la siguiente:

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 el ID de tu proyecto (el mismo que definiste para tus permisos de IAM).
location: Es la ubicación de tu proyecto (región), igual que los extremos regionales.
instance_id: Es el 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 compatibles, 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

Verifica la configuración del firewall

Si usas firewalls o proxies autenticados entre tu entorno y la Internet, configura reglas para permitir conexiones HTTPS salientes en el puerto TCP 443. Permite el acceso a los siguientes hosts:

Endpoint de API de Chronicle: <var>REGION</var>-chronicle.googleapis.com o chronicle.<var>REGION</var>.rep.googleapis.com
Extremos de autenticación de Google: oauth2.googleapis.com, www.googleapis.com y accounts.google.com (además de sts.googleapis.com y iamcredentials.googleapis.com si usas la federación de identidades para cargas de trabajo o la identidad temporal como cuenta de servicio)

Para obtener detalles completos sobre los extremos, orientación sobre el rango de IP de Google, opciones de conectividad privada y pasos de verificación, consulta Verifica la configuración del firewall para la API de Chronicle.

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 las bibliotecas cliente de Google Cloud

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 API de Chronicle es compatible con 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 la 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 funciones migradas.
Ejecuta pruebas: Ejecuta 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 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 al principal de identidad externa se le hayan otorgado los roles de IAM predefinidos o personalizados requeridos (como Chronicle API Viewer o Chronicle API Editor) en tu proyecto de Google Cloud . Para conocer los permisos detallados de los endpoints de API, consulta Asignación de extremo de API SIEM.

HTTP 401 No autorizado o NO AUTENTICADO

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 correcto en tu entorno de ejecución.

Error HTTP 404 No encontrado o discrepancias regionales

Si tus llamadas a la API devuelven un error 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.