Migrer vers l'API Chronicle

Compatible avec :

Ce document s'applique à vous si vous appelez l'API SOAR de manière programmatique à l'aide d'intégrations, de scripts personnalisés ou d'actions personnalisées. Ce document 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 introduit plusieurs améliorations conçues pour simplifier votre processus de développement. Elle résout également les limites et les complexités de l'ancienne API.

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

Prérequis

Avant d'effectuer la migration de l'API SOAR, vous devez :

Principaux changements et améliorations

Le tableau suivant met en évidence les principales différences entre l'ancienne et la nouvelle surface 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é La cohérence des noms 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 31 mars 2027. Nous vous recommandons d'effectuer la migration avant cette date pour éviter toute interruption de service.

Procédure de migration

Cette section décrit les étapes à 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 aux nouveaux, en tenant compte des modifications structurelles ou des nouveaux champs. Pour en savoir plus, consultez Table de mappage des points de terminaison d'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 déployer d'abord les modifications dans une intégration de préproduction. Ce processus vous permet d'effectuer des tests sans affecter vos flux d'automatisation en 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 des intégrations, consultez Tester des intégrations en mode préproduction.

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

Un point de terminaison de service est l'URL de base qui spécifie l'adresse réseau d'un service d'API. Un même 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 suivante :

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

Où :

  • service_endpoint : adresse de service régional
  • api_version : version de l'API à interroger. Il peut s'agir de v1alpha, v1beta ou v1.
  • project_id : ID de votre projet (le même 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 SIEM Google Security Operations.

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 toutes les demandes 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 devrez 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 Workload Identity aux paramètres SOAR

Si vous utilisez un compte de service ou la 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'il 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 l'accès à un compte de service ou l'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 > Gestion des accès > Mappage de groupes.
  2. Cliquez sur add Ajouter.

  3. Complétez 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 / User group (IdP/Groupe d'utilisateurs), saisissez l'une des valeurs suivantes :
      • Adresse e-mail complète de votre compte de service, si l'identité a été configurée à l'aide de Cloud Identity.
      • Chaîne du compte principal 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 dans le 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 restreintes pour limiter 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 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 d'examiner 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 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 scénarios de test qui couvrent toutes les fonctionnalités migrées.
  2. Exécuter des tests : exécutez des tests automatisés et manuels pour confirmer l'exactitude et la validité.
  3. Surveiller les performances : évaluez les performances de votre application avec la nouvelle API.

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