Migra 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 endpoints de 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 31 de marzo de 2027, 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 Si los nombres son coherentes, la API es más intuitiva y fácil de integrar.

Programa de baja

Está previsto que la plataforma de API antigua para SOAR deje de estar disponible por completo el 31 de marzo de 2027. 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 API

Identifica los nuevos extremos correspondientes para cada una de las llamadas a la API antigua que realiza tu aplicación. Del mismo modo, asigna los modelos de datos antiguos 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 endpoints de 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 Workload Identity 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 Workload Identity el acceso necesario a los roles y entornos del SOC.

Para otorgar acceso a una cuenta de servicio o acceso a la federación de identidades para cargas de trabajo a Google SecOps, debes asignar la identidad a los parámetros de control de acceso de la plataforma. Esta asignación es un paso obligatorio para proporcionar a la identidad el acceso necesario a los roles del SOC y los entornos necesarios para realizar tareas automatizadas o operaciones de API.

  1. Ve a Configuración de SOAR > Avanzada > Asignación de grupos.
  2. Haz clic en add Agregar.

  3. Completa los campos en el cuadro de diálogo Agregar asignación para asignar la identidad a los parámetros de control de acceso de la plataforma.

    1. En el campo IdP / Grupo de usuarios, ingresa una de las siguientes opciones:
      • La dirección de correo electrónico completa de tu cuenta de servicio, si la identidad se configuró con Cloud Identity.
      • La cadena principal de Workload Identity, si la identidad se configuró con la federación de identidades de personal.

    2. Configura los siguientes campos de control de acceso:

      Campo Descripción
      Grupos de permisos Selecciona los grupos de permisos para definir a qué módulos y submódulos puede acceder la identidad.
      Roles del SOC Selecciona los roles del SOC para definir el rol de la identidad (como el nivel 1).
      Entornos Selecciona los entornos o los grupos de entornos a los que puede acceder la identidad (como Todos los entornos).
      Miembros del grupo Ingresa los correos electrónicos de los usuarios necesarios, si corresponde. Presiona Intro después de agregar cada correo electrónico.
      Acciones restringidas Selecciona las acciones restringidas para limitar operaciones específicas dentro de los módulos.

  4. 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 reutilizar 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 exactitud 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.