Migrer vers l'API Chronicle

Compatible avec :

Ce document s'adresse à vous si vous appelez l'API SOAR par programmation à l'aide d'intégrations, de scripts personnalisés ou d'actions personnalisées. Il décrit les étapes et les points à prendre en compte pour vous aider à mettre à jour les références d'API programmatiques vers les nouveaux points de terminaison de l'API SOAR dans le cadre de l'API Chronicle.

La surface de l'API Chronicle apporte plusieurs améliorations conçues pour simplifier votre processus de développement. Elle résout également les limites et les complexités présentes dans l'ancienne API.

L'ancienne API SOAR et les anciennes clés API seront disponibles jusqu'au 30 novembre 2026, après quoi elles ne fonctionneront plus.

Prérequis

Avant d'effectuer la migration de l'API SOAR, vous devez procéder comme suit :

Principales modifications et améliorations

Le tableau suivant met en évidence les principales différences entre les anciennes et les nouvelles surfaces d'API :

Zone de la fonctionnalité Ancienne API Nouvelle API Détails
Authentification Jeton d'API OAuth 2.0 La nouvelle méthode d'authentification offre une sécurité renforcée et standardise le processus.
Modèles de données Structures plates Conception orientée ressources Cette nouvelle conception améliore la cohérence des données et simplifie la manipulation des objets.
Nommage des points de terminaison Incohérent RESTful et standardisé Un nommage cohérent rend l'API plus intuitive et plus facile à intégrer.

Planning d'abandon

L'ancienne surface d'API pour SOAR devrait être complètement abandonnée le 30 novembre 2026. Nous vous recommandons d'effectuer la migration avant cette date pour éviter toute interruption de service.

Procédure de migration

Cette section décrit la procédure à suivre pour migrer vos applications vers l'API Chronicle :

Consulter la documentation

Familiarisez-vous avec la documentation complète de la nouvelle API, y compris le guide de référence de l'API Chronicle.

Mapper les points de terminaison vers la nouvelle surface d'API

Identifiez les nouveaux points de terminaison correspondants pour chacun des anciens appels d'API effectués par votre application. De même, mappez les anciens modèles de données vers les nouveaux, en tenant compte des modifications structurelles ou des nouveaux champs. Pour en savoir plus, consultez le tableau de mappage des points de terminaison de l'API.

Facultatif : Créer une intégration de préproduction

Si vous modifiez une intégration personnalisée ou un composant d'une intégration commerciale, nous vous recommandons de transférer d'abord les modifications vers une intégration de préproduction. Ce processus vous permet d'effectuer des tests sans affecter vos flux d'automatisation de production. Si vous migrez une application personnalisée qui utilise l'API SOAR, vous pouvez passer à l'étape suivante. Pour en savoir plus sur la préproduction d'intégration, consultez Tester les intégrations en mode préproduction.

Mettre à jour le point de terminaison de service et les URL

Un point de terminaison de service est l'URL de base qui spécifie l'adresse réseau d'un service d'API. Un seul service peut avoir plusieurs points de terminaison de service. Chronicle est un service régional et n'est compatible qu'avec les points de terminaison régionaux.

Tous les nouveaux points de terminaison utilisent un préfixe cohérent, ce qui rend l'adresse finale du point de terminaison prévisible. L'exemple suivant montre la nouvelle structure d'URL du point de terminaison :

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

Cette structure permet d'obtenir l'adresse finale du point de terminaison comme suit :

https://[service_endpoint]/[api_version]/projects/[project_id]/locations/[location]/instances/[instance_id]/...

Où :

  • service_endpoint : adresse de service régionale
  • api_version : version de l'API à interroger. Peut être v1alpha, v1beta, ou v1.
  • project_id : ID du projet (même projet que celui que vous avez défini pour vos autorisations IAM)
  • location : emplacement de votre projet (région), identique aux points de terminaison régionaux
  • instance_id : ID client de votre solution Google Security Operations SIEM.

Adresses régionales :

  • 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

Par exemple, pour obtenir la liste de tous les cas d'un projet aux États-Unis :

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

Mettre à jour la méthode d'authentification

La nouvelle API utilise Google Cloud IAM pour l'authentification. Vous devez mettre à jour votre application ou votre intégration de réponse pour implémenter ce nouveau flux d'authentification. Assurez-vous que l'utilisateur qui exécute le script dispose des autorisations appropriées pour les points de terminaison auxquels il tente d'accéder. Pour implémenter ce nouveau flux, vous devez mettre à jour vos intégrations ou applications de réponse. Assurez-vous que l'utilisateur qui exécute le script dispose des autorisations nécessaires pour les points de terminaison ciblés. Pour obtenir des instructions détaillées, consultez la page S'authentifier auprès de l'API Chronicle.

Mapper le compte de service ou l'identité de charge de travail aux paramètres SOAR

Si vous utilisez un compte de service ou une fédération d'identité de charge de travail pour vous authentifier auprès de l'API Chronicle, vous devez l'autoriser sur la plate-forme pour vous assurer qu'elle peut communiquer avec Google SecOps. Ce mappage est nécessaire pour fournir au compte de service ou à l'identité de charge de travail l'accès nécessaire aux rôles et environnements SOC.

Pour accorder un accès au compte de service ou un accès à la fédération d'identité de charge de travail à Google SecOps, vous devez mapper l'identité aux paramètres de contrôle des accès de la plate-forme. Ce mappage est une étape obligatoire pour fournir à l'identité l'accès nécessaire aux rôles SOC et aux environnements requis pour effectuer des tâches automatisées ou des opérations d'API.

  1. Accédez à Paramètres SOAR > Avancé > Mappage de groupes.
  2. Cliquez sur add Ajouter.

  3. Remplissez les champs de la boîte de dialogue Ajouter un mappage pour mapper l'identité aux paramètres de contrôle des accès de la plate-forme.

    1. Dans le champ IdP / Groupe d'utilisateurs, saisissez l'une des valeurs suivantes :
      • L'adresse e-mail complète de votre compte de service, si l'identité a été configurée à l'aide de Cloud Identity.
      • La chaîne principale de Workload Identity, si l'identité a été configurée à l'aide de la fédération d'identité de personnel.

    2. Configurez les champs de contrôle des accès suivants :

      Champ Description
      Groupes d'autorisations Sélectionnez les groupes d'autorisations pour définir les modules et sous-modules auxquels l'identité peut accéder.
      Rôles SOC Sélectionnez les rôles SOC pour définir le rôle de l'identité (par exemple, niveau 1).
      Environnements Sélectionnez les environnements ou les groupes d'environnements auxquels l'identité peut accéder (par exemple, Tous les environnements).
      Membres du groupe Saisissez les adresses e-mail des utilisateurs requis, le cas échéant. Appuyez sur Entrée après avoir ajouté chaque adresse e-mail.
      Actions limitées Sélectionnez les actions limitées pour restreindre des opérations spécifiques dans les modules.

  4. Cliquez sur Ajouter.

Pour en savoir plus sur le mappage des utilisateurs et des comptes de service, consultez Mapper les utilisateurs de la plate-forme à l'aide d'une identité tierce ou Mapper les utilisateurs de la plate-forme à l'aide de Cloud Identity.

Mettre à jour la logique de l'API

Analysez les nouveaux modèles de données et les nouvelles structures de points de terminaison fournis dans la documentation de référence de l'API. Toutes les méthodes n'ont pas changé de manière significative, et une partie du code existant peut être réutilisée. L'objectif principal est de consulter la nouvelle documentation de référence et, pour chaque cas d'utilisation spécifique, d'identifier et d'implémenter les modifications nécessaires apportées aux noms de champs et aux structures de données dans la logique de votre application.

Tester votre intégration

Testez votre application mise à jour dans une intégration de préproduction avant de la déployer en production :

  1. Créez un plan de test : définissez des cas de test qui couvrent toutes les fonctionnalités migrées.
  2. Exécutez des tests : exécutez des tests automatisés et manuels pour confirmer l'exactitude et la validité.
  3. Surveillez les performances : évaluez les performances de votre application avec la nouvelle API.

Vous avez encore besoin d'aide ? Obtenez des réponses auprès des membres de la communauté et des professionnels de Google SecOps.