Migrer les points de terminaison SOAR vers l'API Chronicle

Compatible avec :

Ce document s'adresse à 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 l'API Chronicle.

La surface de l'API Chronicle présente plusieurs améliorations conçues pour simplifier votre processus de développement. Il aborde également les limites et les complexités de l'ancienne API.

L'ancienne API SOAR et les clés API seront disponibles jusqu'au 30 septembre 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 :

Principaux changements 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 Cette nouvelle méthode d'authentification offre une sécurité renforcée et standardise le processus.
Modèles de données Structures forfaitaires Conception orientée ressources Ce nouveau design améliore la cohérence des données et simplifie la manipulation des objets.
Nommer les points de terminaison Flux de travail RESTful et normalisé Une dénomination cohérente rend l'API plus intuitive et plus facile à intégrer.

Planning d'abandon

L'ancienne surface d'API pour SOAR devrait être entièrement abandonnée le 30 septembre 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 à 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 avec les nouveaux, en tenant compte des éventuelles 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 intermédiaire

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 mise en scène de l'intégration, consultez Tester les intégrations en mode "staging".

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 service unique peut avoir plusieurs points de terminaison de service. Chronicle est un service régional et n'accepte que les points de terminaison régionaux.

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

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

La structure de l'adresse finale du point de terminaison est la suivante :

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. 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 : votre numéro client 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

  • nous : 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 IAM pour l'authentification. Google Cloud 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 l'identité de charge de travail 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 dans 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 mapper votre compte de service :

  1. Accédez à Paramètres SOAR> Avancé> Mappage des groupes.

  2. Cliquez sur add Ajouter.

  3. Dans la boîte de dialogue Ajouter un rôle, saisissez l'adresse e-mail complète de votre compte de service ou la chaîne principale Workload Identity dans le champ Rôle IAM / Groupe IdP.

  4. Sélectionnez les rôles SOC et les environnements appropriés.

  5. 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 certains codes existants peuvent être réutilisés. 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écutez des tests : effectuez 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 de membres de la communauté et de professionnels Google SecOps.