Migra a la API de Chronicle

Compatible con:

Este documento se aplica a ti si llamas a la API de SOAR de manera 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 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 la API antigua y la nueva:

Á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 una seguridad mejorada 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.
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.

Programa de baja

La plataforma de la API anterior para SOAR dejará 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 la API

Identifica los extremos nuevos correspondientes para cada una de las llamadas a la API antiguas que realiza tu aplicación. Del mismo modo, asigna los modelos de datos antiguos a los nuevos, teniendo en cuenta cualquier cambio estructural o campo nuevo. Para obtener más detalles, consulta la tabla de asignación de endpoints de API.

Opcional: Crea una integración de etapa de pruebas

Si estás editando 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 tus 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 detalles sobre la etapa de pruebas de integración, consulta Prueba las integraciones en el modo de etapa de pruebas.

Actualiza el extremo de servicio y las URLs

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: 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 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 la IAM de Google Cloud para la autenticación. Deberás actualizar tu aplicación o integración de respuestas 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 de destino. Para obtener instrucciones detalladas, consulta la página Autentica 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 la federación de Workload Identity para autenticarte en la API de Chronicle, debes autorizarla dentro de la plataforma para garantizar 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 de 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 de la API.

  1. Ve a Configuración > Administración de acceso > Asignación de grupos.
  2. Haz clic en Agregar 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 / User group, 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.
      • Es la cadena de la 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 de SOC para definir el rol de la identidad (como Nivel 1).
      Entornos Selecciona los entornos o 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 requeridos, 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 forma 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 la 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 nueva.

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