Nous avons réorganisé la structure de navigation de notre documentation pour l'aligner directement sur vos workflows opérationnels. Pour en savoir plus, consultez les notes de version et la vidéo de présentation.

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 l'API Chronicle moderne.

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

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

Qu'est-ce qui change ?

Toutes les requêtes programmatiques adressées aux anciens points de terminaison de l'API Backstory et de l'API Ingestion doivent passer à l'API Chronicle moderne. 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.

Ce qui ne change pas

Les actions effectuées directement dans l'interface utilisateur de Google SecOps appellent déjà l'API Chronicle moderne. Si votre organisation n'interagit avec Google SecOps que via l'interface utilisateur ou si vos intégrations appellent déjà des points de terminaison de l'API Chronicle, aucune action n'est requise de votre part.

Principales modifications 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 des autorisations IAM simplifie l'intégration et élimine la dépendance aux demandes d'assistance manuelles.
Normes de conformité	Compatibilité limitée	Compatibilité intégrée avec les commandes de résidence des données, VPC Service Controls, Access Transparency, CMEK et FedRAMP	Les commandes d'infrastructure intégrées modernes répondent aux normes de conformité et réglementaires du secteur.
Journalisation et audit	Anciens flux d'audit	Cloud Audit Logs intégré à votre Google Cloud projet	L'intégration directe fournit des pistes d'audit et une surveillance centralisées.
Authentification	Jeton d'API et identifiants de 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 améliorent la sécurité et standardisent le flux d'identifiants.
Modèles de données et conception d'API	Structures plates et propriétaires	Conception orientée ressource, architecture RESTful et nommage standardisé 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.
Nommage des points de terminaison	Incohérent	RESTful et standardisé	Un nommage cohérent rend l'API plus intuitive et plus facile à intégrer.
Écosystème	Très limité	Intégration avec MCP, Terraform, les bibliothèques clientes et les SDK	Large compatibilité avec les outils cloud modernes et les frameworks d'automatisation.

Planning d'abandon

L'ancienne API SIEM sera 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 (API Backstory et API Ingestion) à 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éployer sur une infrastructure SIEM moderne : assurez-vous que votre instance est déployée sur votre Google Cloud projet à l'aide de l'infrastructure SIEM moderne. Pour obtenir des instructions détaillées, consultez la présentation de la migration SIEM.
Activer l'API Chronicle : dans la Google Cloud console, accédez à votre projet et activez l'API Chronicle (chronicle.googleapis.com). Pour en savoir plus, consultez Activer une API dans votre Google Cloud projet.

Migrer vers l'API Chronicle

Migrez vos scripts et intégrations des anciennes API vers l'API Chronicle en procédant comme suit :

Auditer l'utilisation de l'API: identifiez tous les scripts et intégrations de votre environnement qui appellent d'anciens points de terminaison.
**Configurer l'authentification et l'autorisation** : configurez votre environnement pour authentifier et autoriser les requêtes adressées à l'API Chronicle.
Mapper les points de terminaison et mettre à 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.
Tester votre intégration : validez les modifications dans un environnement de préproduction avant de les déployer en production.

Auditer l'utilisation de l'API

Auditez votre environnement pour identifier les scripts ou les intégrations qui appellent backstory.googleapis.com ou malachiteingestion-pa.googleapis.com. Vous pouvez identifier ces intégrations en examinant votre code, vos scripts d'automatisation et vos outils tiers.

Configurer l'authentification et l'autorisation

Configurez votre environnement pour authentifier et autoriser les requêtes adressé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 cela évite de gérer et de stocker des clés de compte de service à longue durée de vie. Pour les scénarios d'authentification avancés (tels que 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é) : 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 Google Cloud projet, 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. Attribuez les rôles IAM requis à votre identité en fonction du niveau d'accès requis. Pour en savoir plus, consultez Gérer l'accès aux projets, aux dossiers et aux organisations. Les rôles prédéfinis incluent les éléments suivants :
Nous vous recommandons d'utiliser le principe du moindre privilège pour n'accorder que les autorisations nécessaires à vos automatisations en tirant parti des rôles IAM personnalisés ou prédéfinis.

**Remarque** : Consultez Mappage des points de terminaison de l'API SIEM pour trouver les autorisations IAM spécifiques et granulaires requises pour les points de terminaison modernes qui remplacent vos anciens appels.
Définir la variable d'environnement des identifiants : configurez votre environnement d'exécution pour qu'il utilise les identifiants avec les identifiants par défaut de l'application (ADC) 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 fédération d'identité de charge de travail. Les Google Cloud bibliothèques clientes détectent automatiquement cette variable pour authentifier les requêtes :
```
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"
```
Mettre à jour les habilitations OAuth : mettez à jour la chaîne d'habilitation si vos anciens scripts d'intégration ont explicitement demandé des habilitations OAuth pour la génération de jetons. L'ancienne habilitation n'accorde pas l'accès à la surface de l'API moderne :
- Ancienne habilitation Backstory : https://www.googleapis.com/auth/chronicle-backstory
- Habilitation Chronicle : https://www.googleapis.com/auth/chronicle (ou l'habilitation 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 vers l'API Chronicle

Identifiez les points de terminaison modernes correspondants pour chacun des appels d'ancienne API effectués par votre application. De même, mappez vos modèles de données existants vers les 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 de service

Mettez à jour 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 de l'URL du point de terminaison moderne :

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

Cette structure donne 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 Google Security Operations 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 dans la documentation sur le point de terminaison de service de l'API Chronicle Service endpoint.

Par exemple, pour répertorier 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 cas à 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 sur l'API REST Chronicle pour identifier et implémenter les modifications apportées aux noms de champs et aux structures de données de 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 Google Cloud les bibliothèques clientes

Simplifiez votre intégration pour gérer automatiquement l'authentification, l'actualisation des jetons et les détails de transport. Nous vous recommandons d'utiliser lesbibliothèques clientes officielles Google Cloud 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 une intégration de préproduction avant de la déployer en production :

Créer 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 identifiants appropriés.
- Si vous utilisez Workload Identity Federation, vérifiez que le principal d'identité externe correspond au principal lié aux rôles IAM de votre projet.
- Si vous utilisez un compte de service, vérifiez que le compte de service approprié est utilisé et qu'il n'a pas été désactivé. N'utilisez pas d'anciens comptes de service (contenant souvent bk ou malachite-cx dans leur adresse e-mail) pour les points de terminaison de l'API Chronicle moderne.
Rôles IAM : vérifiez que le compte de service ou le principal d'identité externe s'est vu attribuer les rôles IAM prédéfinis ou personnalisés requis (tels que Chronicle API Viewer ou Chronicle API Editor) dans votre Google Cloud projet. Pour obtenir des autorisations de point de terminaison granulaires, consultez Mappage des points de terminaison de l'API SIEM.

HTTP 401 Non autorisé ou UNAUTHENTICATED

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

Habilitations OAuth : vérifiez que vos scripts demandent l'habilitation moderne : https://www.googleapis.com/auth/chronicle (ou l'habilitation plus large https://www.googleapis.com/auth/cloud-platform). L'ancienne habilitation (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.

HTTP 404 Introuvable ou non-concordance régionale

Si vos appels d'API renvoient une erreur HTTP 404 Not Found ou échouent à 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 de service ou la documentation de référence officielle sur le point de terminaison de service.

Étape suivante

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