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

Compatible con:

Este documento te ayuda a administrar las aplicaciones que llaman a cualquiera de las APIs de SIEM heredadas (la API de Backstory y la 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 de la API de Chronicle moderna.

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 el proceso de desarrollo y alinearse con Google Cloud los estándares de la API para mejorar la confiabilidad, la seguridad, el rendimiento y una integración más sólida con 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 de la API de Backstory y la API de Ingestion heredadas deben pasar 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 usar extremos y flujos de autenticación modernos antes del 20 de julio de 2027.

¿Qué no cambiará?

Las acciones que se realizan directamente en la interfaz de usuario (IU) de Google SecOps 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 autoservicio de credenciales y de IAM 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 con métodos de autenticación modernos, incluidas las cuentas de servicio y la federación de Workload Identity, como se describe en Autenticación para Google Cloud APIs y servicios Estos métodos de autenticación modernos proporcionan seguridad mejorada y estandarizan el flujo de credenciales.
Modelos de datos y diseño de la API Estructuras planas y propietarias Diseño orientado a recursos, arquitectura 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.
Nombres de extremos Incoherente RESTful y estandarizado La nomenclatura coherente 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.

Programa de baja

Está previsto que la API de SIEM heredada se cierre 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 (la API de Backstory y la API de Ingestion) desde instancias nuevas.
  • Para el 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:

Migra a la API de Chronicle

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

  1. Audita el uso de la API: Identifica todas las secuencias de comandos y las integraciones de tu entorno que invocan extremos heredados.
  2. Configura la autenticación y la autorización: Configura tu entorno para autenticar y autorizar solicitudes a la API de Chronicle.
  3. Asigna extremos y actualiza URLs: Reemplaza los extremos heredados por sus equivalentes regionales modernos.
  4. Actualiza la lógica de la API: Ajusta las cargas útiles de la solicitud y el manejo de respuestas para que coincidan con los modelos de datos de la API moderna.
  5. 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 que invoquen backstory.googleapis.com o malachiteingestion-pa.googleapis.com. Puedes identificar estas integraciones revisando tu base de código, las secuencias de comandos de automatización y las herramientas de terceros.

Configura la autenticación y la autorización

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

  1. 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 enumerados. 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.

  2. Otorga permisos de IAM: Otorga los permisos de IAM necesarios a la identidad (ya sea la cuenta de servicio o la entidad externa) que se usa para la autenticación. Asigna los roles de IAM necesarios a tu identidad según el nivel de acceso requerido. Consulta Administra el acceso a proyectos, carpetas y organizaciones para obtener más detalles. Los roles predefinidos incluyen lo siguiente:

    Te recomendamos que uses el principio de privilegio mínimo para otorgar solo los permisos necesarios para tus automatizaciones aprovechando los roles de IAM personalizados o predefinidos.

  3. Establece 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) estableciendo la variable de entorno GOOGLE_APPLICATION_CREDENTIALS. Esta variable debe apuntar al archivo JSON de clave de cuenta de servicio descargado o al archivo de configuración de credenciales de la federación de identidades para cargas de trabajo. Las Google Cloud bibliotecas cliente detectan automáticamente esta variable para autenticar solicitudes:

    export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"

  4. 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 superficie 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 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 de servicio

Actualiza la URL base de tus llamadas a la API para que apunte 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 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: Una dirección de servicio regional
  • api_version: La versión de la API que se consultará Puede ser v1alpha, v1beta o v1.
  • project_id: Tu ID del proyecto (el mismo proyecto que definiste para tus permisos de IAM)
  • location: La ubicación de tu proyecto (región); es la misma que los extremos regionales
  • instance_id: Tu ID de cliente de Google Security Operations 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 Service endpoint.

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 de 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 REST de la API 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.

Usar las 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 lasbibliotecas cliente oficiales 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 una integración de etapa de pruebas antes de implementarla en producción:

  1. Crea un plan de pruebas: Define casos de prueba que abarquen todas las funcionalidades migradas.
  2. Ejecuta pruebas: Ejecuta pruebas automatizadas y manuales para confirmar la exactitud y la validez.
  3. 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 los errores comunes que puedes encontrar durante la migración.

HTTP 403 Forbidden o PERMISSION_DENIED

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

  • Método de autenticación y entidad: Asegúrate de usar las credenciales correctas.
    • Si usas la federación de identidades para cargas de trabajo, verifica que la entidad externa coincida con la entidad 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 extremos modernos de la API de Chronicle.
  • Roles de IAM: Verifica que a la cuenta de servicio o a la entidad externa se le hayan otorgado los roles de IAM predefinidos o personalizados necesarios (como Chronicle API Viewer o Chronicle API Editor) en tu Google Cloud proyecto. Para obtener permisos de extremos granulares, 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 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é establecida 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.

HTTP 404 Not Found o desajustes regionales

Si tus llamadas a la API muestran 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 coincida 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.