Migrer 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. 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 introduit 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 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 :

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 Flux de travail 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 septembre 2026. Nous vous recommandons d'effectuer votre 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 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 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. 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 mapper votre compte de service :

  1. Accédez à SOAR Settings > Advanced > Group Mapping (Paramètres SOAR > Avancé > Mappage de groupe).

  2. Cliquez sur add Add (Ajouter).

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

  4. Sélectionnez les SOC Roles (Rôles SOC) et les Environments (Environnements) appropriés.

  5. Cliquez sur Add (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 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 Google SecOps.