Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Migrer de l'ancienne API SIEM vers l'API Chronicle

Compatible avec :

Google SecOps SIEM

Ce document vous aide à gérer les applications qui appellent l'une des anciennes API SIEM (API Backstory et API Ingestion). Il décrit les étapes à suivre pour configurer l'accès programmatique et mettre à jour toutes les références des anciens points de terminaison de l'API SIEM vers les points de terminaison de la nouvelle API Chronicle.

Pour obtenir un aperçu rapide du processus de migration, regardez la vidéo intégrée.

La surface de l'API Chronicle présente plusieurs améliorations conçues pour simplifier votre processus de développement et s'aligner sur les normes de l'API Google Cloud afin d'améliorer la fiabilité, la sécurité et les performances, et de renforcer l'intégration à Cloud Audit Logs, Cloud Monitoring, Cloud Identity et Identity and Access Management (IAM). Elle répond également à de nombreuses limites et complexités des anciennes API.

Qu'est-ce qui change ?

Toutes les requêtes programmatiques envoyées aux anciens points de terminaison de l'API Backstory et de l'API Ingestion doivent être transférées vers la nouvelle API Chronicle. Si votre organisation utilise des intégrations personnalisées, des scripts d'automatisation ou des outils tiers qui appellent ces anciens points de terminaison, vous devez mettre à jour ces charges de travail pour qu'elles utilisent des points de terminaison et des flux d'authentification modernes avant le 20 juillet 2027. De plus, si votre organisation utilise Google Security Operations SOAR, vous devez mettre à jour vos intégrations et connecteurs SOAR (tels que l'intégration Google Chronicle) pour utiliser l'API Chronicle. Pour en savoir plus, consultez Migrer les intégrations SOAR.

Ce qui ne change pas

Les actions effectuées directement dans l'interface utilisateur (UI) de Google Security Operations invoquent déjà la nouvelle API Chronicle. Si votre organisation n'interagit avec Google SecOps que par le biais de l'UI ou si vos intégrations appellent déjà des points de terminaison de l'API Chronicle, aucune action n'est requise de votre part.

Principaux changements et améliorations

Le tableau suivant met en évidence les principales différences entre l'ancienne API SIEM et l'API Chronicle :

Zone de la fonctionnalité	Ancienne API SIEM	API Chronicle	Détails
Gestion des identifiants	Processus manuel impliquant des représentants Google	Gestion en libre-service des comptes de service, des identifiants et des autorisations IAM	La gestion en libre-service des identifiants et d'IAM simplifie l'intégration et élimine la dépendance aux demandes d'assistance manuelles.
Normes de conformité	Compatibilité limitée	Prise en charge intégrée des contrôles de résidence des données, de VPC Service Controls, d'Access Transparency, des CMEK et de FedRAMP	Des contrôles d'infrastructure intégrés modernes répondent aux normes de conformité et réglementaires du secteur.
Journalisation et audit	Flux d'audit hérités	Cloud Audit Logs intégré à votre projet Google Cloud	L'intégration directe fournit des pistes d'audit et une surveillance centralisées.
Authentification	Jeton d'API et identifiants du compte de service	OAuth 2.0 avec prise en charge des méthodes d'authentification modernes, y compris Workload Identity et les comptes de service, comme décrit dans Authentification pour Google Cloud les API et les services	Ces méthodes d'authentification modernes renforcent la sécurité et standardisent le flux d'identifiants.
Modèles de données et conception d'API	Structures propriétaires et plates	Conception orientée ressources, architecture RESTful et dénomination standardisée suivant les AIP	Cette conception moderne améliore la cohérence des données, rend l'API plus intuitive et simplifie la manipulation des objets.
Nommer les points de terminaison	Incohérent	RESTful et standardisé	La cohérence des noms rend l'API plus intuitive et plus facile à intégrer.
Écosystème	Très limitée	Intégration à MCP, Terraform, aux bibliothèques clientes et aux SDK	Compatibilité étendue avec les outils cloud modernes et les frameworks d'automatisation.
Autorisation de partenariat	Jeton de partenaire ou clé API utilisés directement dans les codes client	Délégation IAM entre projets pour les ressources locataires ; méthodes TenantService à portée partenaire	Les méthodes TenantService s'exécutent dans le projet partenaire. Toutes les autres API de locataire nécessitent une délégation IAM inter-projets accordée par le locataire dans le projet locataire.

Autorisation de partenariat

Pour les workflows partenaires mutualisés, l'autorisation dans l'API Chronicle dépend de la propriété des ressources. Le projet qui héberge une ressource détermine les identifiants et les autorisations IAM dont un partenaire a besoin. Limiter les opérations de locataire aux identifiants délégués par le locataire est conforme au principe de sécurité de base selon lequel les partenaires ne doivent pas pouvoir accéder aux données du locataire, les récupérer ni les modifier sans l'autorisation explicite de ce dernier. Le tableau suivant compare l'autorisation des partenaires dans l'ancienne API Backstory et l'API Chronicle :

API	Méthodes	Champ d'application de la ressource	Autorisation
Ancienne API Backstory	`/v1/partner/customer/*` points de terminaison	Tous les codes client du partenaire	Les partenaires appellent directement ces points de terminaison avec leurs propres jetons de partenaire ou clés API.
API Chronicle : `TenantService`	`CreateTenant`, `ListTenants` et `UpdateTenant`	Instance du partenaire : `projects/{partner_project}/locations/{location}/instances/{partner_instance}/tenants/*`	Les partenaires appellent directement ces méthodes avec leurs propres comptes de service ou identifiants disposant d'autorisations `chronicle.googleapis.com/tenants.*` dans le projet partenaire.
API Chronicle : autres services, tels que `InstanceService` et `ForwarderService`	`GetInstance`, `UpdateInstance`, `GenerateForwarderFiles` et d'autres méthodes à portée locataire	Instance du locataire : `projects/{tenant_project}/locations/{location}/instances/{tenant_instance}/...`	Les identifiants de partenaire seuls ne permettent pas d'accéder aux données du locataire ni de les modifier. L'administrateur du locataire doit attribuer des rôles IAM, tels que `roles/chronicle.admin`, `roles/chronicle.viewer` ou un rôle personnalisé, au compte de service ou au principal de la fédération d'identité de charge de travail du partenaire dans le projet Google Cloud du locataire.

Planning d'abandon

L'ancienne API SIEM doit être arrêtée le 20 juillet 2027. Nous vous recommandons d'effectuer la migration avant cette date pour éviter toute interruption de service :

À partir du 26 octobre 2026, vous ne pourrez plus appeler les anciennes API (Backstory API et Ingestion API) à partir de nouvelles instances.
D'ici le 20 juillet 2027, vous devrez migrer toutes les instances existantes vers l'API Chronicle, car les anciennes API ne seront plus disponibles.

Avant de commencer

Avant de migrer vers l'API Chronicle, assurez-vous d'effectuer les opérations suivantes :

Déployez l'instance sur une infrastructure SIEM moderne : assurez-vous que l'instance est déployée sur le projet de votre partenaire MSSP ou sur le vôtre Google Cloud à l'aide de l'infrastructure SIEM moderne. Pour obtenir des instructions détaillées, consultez Présentation de la migration SIEM.
Activez l'API Chronicle : dans la console Google Cloud , accédez au projet hébergeant votre instance et activez l'API Chronicle (chronicle.googleapis.com). Pour en savoir plus, consultez Activer une API dans votre projet Google Cloud .
Identifiez les intégrations SOAR : si votre environnement connecte Google SecOps SOAR à Google Security Operations SIEM, vérifiez vos connecteurs existants. Pour en savoir plus, consultez Migrer les intégrations SOAR.

Migrer les intégrations SOAR

Si votre organisation connecte Google SecOps SOAR à Google SecOps SIEM, vous devez migrer vos intégrations et connecteurs SOAR (tels que l'intégration Google Chronicle) pour utiliser l'API Chronicle.

Pour obtenir des instructions détaillées sur la mise à niveau de l'intégration et des connecteurs Google Chronicle afin d'utiliser l'API Chronicle, y compris pour trouver la racine de l'API Chronicle de votre environnement et configurer les identifiants d'authentification, consultez Migrer de l'API Backstory vers l'API Chronicle.

Migrer vers l'API Chronicle

Pour migrer vos scripts et intégrations personnalisés des anciennes API vers l'API Chronicle, procédez comme suit :

Auditer l'utilisation de l'API : identifiez tous les scripts et intégrations personnalisés de votre environnement qui appellent des points de terminaison anciens.
Configurer l'authentification et l'autorisation : configurez votre environnement pour authentifier et autoriser les requêtes envoyées à l'API Chronicle.
Mappez les points de terminaison et mettez à jour les URL : remplacez les anciens points de terminaison par leurs équivalents régionaux modernes.
Mettre à jour la logique de l'API : ajustez vos charges utiles de requête et la gestion des réponses pour qu'elles correspondent aux modèles de données de l'API moderne.
Testez votre intégration : validez les modifications dans un environnement de préproduction avant de les déployer en production.

Auditer l'utilisation des API

Auditez votre environnement pour identifier les scripts ou intégrations personnalisés qui appellent backstory.googleapis.com ou malachiteingestion-pa.googleapis.com. Vous pouvez identifier ces intégrations en examinant votre codebase, vos scripts d'automatisation et vos outils tiers. Si votre organisation utilise également Google SecOps SOAR, consultez Migrer les intégrations SOAR.

Configurer l'authentification et l'autorisation

Configurez votre environnement pour authentifier et autoriser les requêtes envoyées à l'API Chronicle :

Choisir une méthode d'authentification : choisissez comment vos charges de travail s'authentifient auprès de l'API Chronicle à l'aide de l'une des méthodes listées. Nous vous recommandons d'utiliser la fédération d'identité de charge de travail pour une meilleure sécurité, car elle évite la gestion et le stockage des clés de compte de service de longue durée. Pour les scénarios d'authentification avancés (comme l'emprunt d'identité d'un compte de service), consultez S'authentifier auprès de l'API Chronicle.
- Fédération d'identité de charge de travail (recommandée) : configurez la fédération d'identité de charge de travail pour permettre aux charges de travail exécutées en dehors de Google Cloud de s'authentifier à l'aide d'identités externes.
- Comptes de service : si vous devez utiliser des comptes de service, créez-en un dans votre projet Google Cloud , puis générez et téléchargez une clé privée au format JSON. Conservez cette clé en lieu sûr.
Accorder des autorisations IAM : accordez les autorisations IAM requises à l'identité (compte de service ou principal d'identité externe) utilisée pour l'authentification. Consultez le mapping des points de terminaison de l'API SIEM pour trouver les autorisations IAM spécifiques requises pour les points de terminaison modernes qui remplacent vos anciens appels.
- Rôle personnalisé (recommandé) : créez un rôle IAM personnalisé avec les autorisations requises, puis accordez ce rôle personnalisé au compte de service ou au principal d'identité externe.
- Rôle prédéfini : attribuez un rôle prédéfini Google SecOps au compte de service ou au compte principal d'identité externe. Cela accordera probablement plus d'accès que nécessaire pour une automatisation spécifique.
- Délégation de partenaire multitenant : si vous êtes un MSSP ou un partenaire qui gère des ressources de locataire en dehors de TenantService (comme GetInstance, UpdateInstance ou GenerateForwarderFiles), l'administrateur du locataire doit accorder explicitement à votre compte de service ou à votre principal de fédération des identités de charge de travail les rôles IAM requis dans le projet Google Cloud du locataire.
Définissez la variable d'environnement des identifiants : configurez votre environnement d'exécution pour utiliser les identifiants avec les identifiants par défaut de l'application (ADC, Application Default Credentials) en définissant la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS. Cette variable doit pointer vers le fichier JSON de clé de compte de service téléchargé ou vers le fichier de configuration des identifiants de la fédération d'identité de charge de travail. Les bibliothèques clientesGoogle Cloud détectent automatiquement cette variable pour authentifier les requêtes :
```
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"
```
Mettez à jour les niveaux d'accès OAuth : mettez à jour la chaîne de champ d'application si vos anciens scripts d'intégration demandaient explicitement des niveaux d'accès OAuth pour la génération de jetons. L'ancien champ d'application n'accorde pas l'accès à la surface de l'API moderne :
- Ancien champ "Backstory" : https://www.googleapis.com/auth/chronicle-backstory
- Champ d'application Chronicle : https://www.googleapis.com/auth/chronicle (ou le champ d'application plus large https://www.googleapis.com/auth/cloud-platform).

Mapper les points de terminaison et mettre à jour les URL

Familiarisez-vous avec la surface de l'API Chronicle, mappez vos anciens appels et mettez à jour les points de terminaison de service dans votre application.

Consulter la documentation de référence

Familiarisez-vous avec la documentation complète de l'API Chronicle.

Mapper les points de terminaison à l'API Chronicle

Identifiez les points de terminaison modernes correspondants pour chacun des anciens appels d'API effectués par votre application. De même, mappez vos modèles de données existants aux structures modernes, en tenant compte des modifications de schéma ou des champs supplémentaires. Pour en savoir plus sur tous les points de terminaison SIEM, consultez Mappage des points de terminaison de l'API SIEM. Si votre workflow interagit également avec des points de terminaison SOAR, consultez le tableau de mappage des points de terminaison de l'API SOAR.

Mettre à jour le point de terminaison du service

Modifiez l'URL de base de vos appels d'API pour qu'elle pointe vers le point de terminaison de service régional approprié. L'API Chronicle est un service régional. Vous devez donc appeler le point de terminaison de service régional qui correspond à l'emplacement de votre instance Google SecOps.

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

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

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

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 : ID client Google SecOps SIEM.

Adresses régionales :

africa-south1 : https://africa-south1-chronicle.googleapis.com ou https://chronicle.africa-south1.rep.googleapis.com
asia-northeast1 : https://asia-northeast1-chronicle.googleapis.com ou https://chronicle.asia-northeast1.rep.googleapis.com
asia-south1 : https://asia-south1-chronicle.googleapis.com ou https://chronicle.asia-south1.rep.googleapis.com
asia-southeast1 : https://asia-southeast1-chronicle.googleapis.com ou https://chronicle.asia-southeast1.rep.googleapis.com
asia-southeast2 : https://asia-southeast2-chronicle.googleapis.com ou https://chronicle.asia-southeast2.rep.googleapis.com
australia-southeast1 : https://australia-southeast1-chronicle.googleapis.com ou https://chronicle.australia-southeast1.rep.googleapis.com
europe-west12 : https://europe-west12-chronicle.googleapis.com ou https://chronicle.europe-west12.rep.googleapis.com
europe-west2 : https://europe-west2-chronicle.googleapis.com ou https://chronicle.europe-west2.rep.googleapis.com
europe-west3 : https://europe-west3-chronicle.googleapis.com ou https://chronicle.europe-west3.rep.googleapis.com
europe-west6 : https://europe-west6-chronicle.googleapis.com ou https://chronicle.europe-west6.rep.googleapis.com
europe-west9 : https://europe-west9-chronicle.googleapis.com ou https://chronicle.europe-west9.rep.googleapis.com
me-central1 : https://me-central1-chronicle.googleapis.com ou https://chronicle.me-central1.rep.googleapis.com
me-central2 : https://me-central2-chronicle.googleapis.com ou https://chronicle.me-central2.rep.googleapis.com
me-west1 : https://me-west1-chronicle.googleapis.com ou https://chronicle.me-west1.rep.googleapis.com
northamerica-northeast2 : https://northamerica-northeast2-chronicle.googleapis.com ou https://chronicle.northamerica-northeast2.rep.googleapis.com
southamerica-east1 : https://southamerica-east1-chronicle.googleapis.com ou https://chronicle.southamerica-east1.rep.googleapis.com
États-Unis (us) : https://us-chronicle.googleapis.com ou https://chronicle.us.rep.googleapis.com
Europe (eu) : https://eu-chronicle.googleapis.com ou https://chronicle.eu.rep.googleapis.com

Pour obtenir la liste complète de tous les points de terminaison compatibles, consultez la documentation de référence officielle sur les points de terminaison de service de l'API Chronicle.

Par exemple, pour lister toutes les règles de détection d'une instance dans l'emplacement us, envoyez la requête suivante :

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

De même, pour interroger des ressources SOAR telles que des requêtes à l'aide de l'alias de point de terminaison régional (rep), envoyez la requête suivante :

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 logique de l'API

Consultez la documentation de référence de l'API REST Chronicle pour identifier et implémenter les modifications apportées aux noms de champs et aux structures de données dans votre application. Bien que certains anciens points de terminaison puissent rester similaires, vous devez mettre à jour vos intégrations pour qu'elles correspondent aux derniers modèles de données et structures de points de terminaison.

Utiliser des bibliothèques clientes Google Cloud

Simplifiez votre intégration pour gérer automatiquement l'authentification, l'actualisation des jetons et les informations de transport. Nous vous recommandons d'utiliser les bibliothèques clientes Google Cloud officielles pour ce faire. L'API Chronicle est compatible avec huit langages de programmation, dont Python, Go, Java, Node.js et C#. Pour en savoir plus sur l'installation et l'utilisation, consultez Bibliothèques clientes et SDK.

Tester votre intégration

Testez votre application mise à jour dans un environnement de préproduction avant de la déployer en production :

Créez un plan de test : définissez des scénarios de test qui couvrent toutes les fonctionnalités migrées.
Exécuter des tests : exécutez des tests automatisés et manuels pour confirmer l'exactitude et la validité.
Surveiller les performances : évaluez les performances de votre application avec l'API moderne.

Résoudre les problèmes

Cette section explique comment résoudre les erreurs courantes que vous pouvez rencontrer lors de la migration.

HTTP 403 (interdit) ou PERMISSION_DENIED

Si vos appels d'API renvoient une erreur HTTP 403 Forbidden ou PERMISSION_DENIED, vérifiez les points suivants :

Méthode d'authentification et principal : assurez-vous d'utiliser les bons identifiants.
- Si vous utilisez la fédération d'identité de charge de travail, vérifiez que le compte principal d'identité externe correspond au compte principal associé aux rôles IAM de votre projet.
- Si vous utilisez un compte de service, vérifiez que le bon compte est utilisé et qu'il n'a pas été désactivé. N'utilisez pas d'anciens comptes de service (qui contiennent souvent bk ou malachite-cx dans leur adresse e-mail) pour les points de terminaison des API Chronicle modernes.
Rôles IAM : vérifiez que le compte de service ou le principal d'identité externe dispose des rôles IAM prédéfinis ou personnalisés requis (tels que Chronicle API Viewer ou Chronicle API Editor) dans votre projet Google Cloud . Pour obtenir des autorisations précises sur les points de terminaison, consultez Mappage des points de terminaison de l'API SIEM.

HTTP 401 Non autorisé ou ABSENCE D'AUTHENTIFICATION

Si vos appels d'API échouent avec HTTP 401 Unauthorized ou UNAUTHENTICATED, vérifiez les points suivants :

Champs d'application OAuth : vérifiez que vos scripts personnalisés demandent le champ d'application moderne https://www.googleapis.com/auth/chronicle (ou le champ d'application plus large https://www.googleapis.com/auth/cloud-platform). L'ancien champ d'application (https://www.googleapis.com/auth/chronicle-backstory) n'accorde pas l'accès à l'API Chronicle moderne.
Variable d'environnement : vérifiez que la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS est définie et qu'elle pointe vers le fichier de clé JSON ou le fichier de configuration de la fédération d'identité de charge de travail approprié dans votre environnement d'exécution.

Erreur HTTP 404 (Introuvable) ou incohérences régionales

Si vos appels d'API renvoient un code HTTP 404 Not Found ou ne parviennent pas à se connecter, vérifiez vos points de terminaison régionaux :

Point de terminaison régional : l'API Chronicle est un service régional. Vérifiez que vous appelez le point de terminaison qui correspond à la région de votre instance Google SecOps (par exemple, https://europe-west3-chronicle.googleapis.com pour une instance à Francfort). L'envoi de requêtes à une autre région entraînera des erreurs. Pour obtenir la liste complète des adresses régionales, consultez Mettre à jour le point de terminaison du service ou la documentation de référence sur les points de terminaison du service.

Étapes suivantes

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