Migra los extremos de SOAR a la API de Chronicle

Compatible con:

Este documento se aplica a ti si llamas a la API de SOAR de forma programática con integraciones, secuencias de comandos personalizadas o acciones personalizadas. En este documento, se describen los pasos y las consideraciones para ayudarte a actualizar las referencias de la API programática a los nuevos extremos de la API de SOAR como parte de la API de Chronicle.

La plataforma de la API de Chronicle presenta varias mejoras diseñadas para optimizar tu proceso de desarrollo. También aborda las limitaciones y complejidades presentes en la API anterior.

La API heredada de SOAR y las claves de API estarán disponibles hasta el 30 de septiembre de 2026, después de lo cual dejarán de funcionar.

Requisitos previos

Antes de realizar la migración de la API de SOAR, debes hacer lo siguiente:

Cambios y mejoras clave

En la siguiente tabla, se destacan las principales diferencias entre las plataformas de API antiguas y nuevas:

Área de características API antigua API nueva Detalles
Autenticación Token de API OAuth 2.0 El nuevo método de autenticación proporciona mayor seguridad y estandariza el proceso.
Modelos de datos Estructuras planas Diseño orientado a recursos Este nuevo diseño mejora la coherencia de los datos y simplifica la manipulación de objetos.
Nombres de extremos Incoherente RESTful y estandarizado La coherencia en los nombres hace que la API sea más intuitiva y fácil de integrar.

Programa de baja

Está previsto que la plataforma de la API anterior para SOAR deje de estar disponible por completo el 30 de septiembre de 2026. Te recomendamos que completes la migración antes de esta fecha para evitar interrupciones en el servicio.

Pasos para la migración

En esta sección, se describen los pasos para migrar correctamente tus aplicaciones a la API de Chronicle:

Revisa la documentación

Familiarízate con la documentación completa de la nueva API, incluida la guía de referencia de la API de Chronicle.

Asigna extremos a la nueva plataforma de la API

Identifica los nuevos extremos correspondientes para cada una de las llamadas a la API anterior que realiza tu aplicación. Del mismo modo, asigna los modelos de datos anteriores a los nuevos, teniendo en cuenta los cambios estructurales o los campos nuevos. Para obtener más información, consulta la tabla de asignación de extremos de la API.

Opcional: Crea una integración de etapa de pruebas

Si editas una integración personalizada o un componente de una integración comercial, te recomendamos que primero envíes los cambios a una integración de etapa de pruebas. Este proceso te permite realizar pruebas sin afectar los flujos de automatización de producción. Si migras una aplicación personalizada que usa la API de SOAR, puedes pasar al siguiente paso. Para obtener más información sobre la etapa de pruebas de integración, consulta Prueba las integraciones en modo de etapa de pruebas.

Actualiza el extremo y las URLs del servicio

Un extremo de servicio es la URL base que especifica la dirección de red de un servicio de API. Un solo servicio puede tener varios extremos de servicio. Chronicle es un servicio regional y solo admite extremos regionales.

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

[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://chronicle.africa-south1.rep.googleapis.com

  • asia-northeast1: https://chronicle.asia-northeast1.rep.googleapis.com

  • asia-south1: https://chronicle.asia-south1.rep.googleapis.com

  • asia-southeast1: https://chronicle.asia-southeast1.rep.googleapis.com

  • asia-southeast2: https://chronicle.asia-southeast2.rep.googleapis.com

  • australia-southeast1: https://chronicle.australia-southeast1.rep.googleapis.com

  • europe-west12: https://chronicle.europe-west12.rep.googleapis.com

  • europe-west2: https://chronicle.europe-west2.rep.googleapis.com

  • europe-west3: https://chronicle.europe-west3.rep.googleapis.com

  • europe-west6: https://chronicle.europe-west6.rep.googleapis.com

  • europe-west9: https://chronicle.europe-west9.rep.googleapis.com

  • me-central1: https://chronicle.me-central1.rep.googleapis.com

  • me-central2: https://chronicle.me-central2.rep.googleapis.com

  • me-west1: https://chronicle.me-west1.rep.googleapis.com

  • northamerica-northeast2: https://chronicle.northamerica-northeast2.rep.googleapis.com

  • southamerica-east1: https://chronicle.southamerica-east1.rep.googleapis.com

  • us: https://chronicle.us.rep.googleapis.com

  • eu: https://chronicle.eu.rep.googleapis.com

Por ejemplo, para obtener una lista de todos los casos de un proyecto en EE.UU., haz lo siguiente:

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

Actualiza el método de autenticación

La nueva API usa Google Cloud IAM para la autenticación. Deberás actualizar tu aplicación o integración de respuesta para implementar este nuevo flujo de autenticación. Asegúrate de que el usuario que ejecuta la secuencia de comandos tenga los permisos correctos para los extremos a los que intenta acceder. Para implementar este nuevo flujo, debes actualizar tus integraciones o aplicaciones de respuesta. Asegúrate de que el usuario que ejecuta la secuencia de comandos tenga los permisos necesarios para los extremos objetivo. Para obtener instrucciones detalladas, consulta la página Autenticación en la API de Chronicle.

Asigna la cuenta de servicio o la identidad de carga de trabajo a los parámetros de SOAR

Si usas una cuenta de servicio o una federación de identidades para cargas de trabajo para autenticarte en la API de Chronicle, debes autorizarla en la plataforma para asegurarte de que pueda comunicarse correctamente con Google SecOps. Esta asignación es necesaria para proporcionar a la cuenta de servicio o a la identidad de carga de trabajo el acceso necesario a los roles y entornos de SOC.

Para asignar tu cuenta de servicio, haz lo siguiente:

  1. Ve a Configuración de SOAR > Avanzada > Asignación de grupos.

  2. Haz clic en add Agregar.

  3. En el diálogo Agregar rol, ingresa la dirección de correo electrónico completa de tu cuenta de servicio o la cadena principal de Workload Identity en el campo Rol de IAM / Grupo de IdP.

  4. Selecciona los roles de SOC y los entornos adecuados.

  5. Haz clic en Agregar.

Para obtener información más detallada sobre la asignación de usuarios y cuentas de servicio, consulta Asigna usuarios en la plataforma con un proveedor de identidad externo o Asigna usuarios en la plataforma con Cloud Identity.

Actualiza la lógica de la API

Analiza los nuevos modelos de datos y las estructuras de extremos que se proporcionan en la referencia de la API. No todos los métodos cambiaron de manera significativa, y se puede volver a usar parte del código existente. El objetivo principal es revisar la nueva documentación de referencia y, para cada caso de uso específico, identificar e implementar los cambios necesarios en los nombres de los campos y las estructuras de datos dentro de la lógica de tu aplicación.

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 funciones migradas.
  2. Ejecuta pruebas: Ejecuta pruebas automatizadas y manuales para confirmar la precisión y la validez.
  3. Supervisa el rendimiento: Evalúa el rendimiento de tu aplicación con la nueva API.

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