Migrer des alertes héritées vers l’API alertes et incidents

L’API d’alertes de sécurité Microsoft Graph héritée disponible via le point de terminaison est déconseillée /security/alerts et sera mise hors service le 15 octobre 2026. Si votre application utilise actuellement l’API d’alertes héritée pour récupérer, surveiller ou gérer les alertes de sécurité, vous devez migrer vers la nouvelle API d’alertes et d’incidents dans Microsoft 365 Defender, disponible via le point de /security/alerts_v2 terminaison.

Cet article décrit les principales différences entre les deux API, fournit une référence de mappage de champs et décrit les étapes de migration de votre application.

Importante

  • Après le 15 octobre 2026, le point de terminaison hérité /security/alerts cessera de retourner des données. Migrez vos applications avant cette échéance pour éviter toute interruption de vos flux de travail d’opérations de sécurité.

  • La nouvelle API d’alertes et d’incidents ne remplace pas directement et de façon individuelle l’API d’alertes héritée. Il affiche les alertes qui font partie de l’écosystème Microsoft 365 Defender. Les alertes provenant de sources qui ne sont pas intégrées à Microsoft 365 Defender, telles qu’un espace de travail Microsoft Sentinel qui n’est pas connecté au portail Microsoft Defender, ou des alertes autonomes et ajustées, ne sont pas renvoyées par la nouvelle API. Passez en revue la section Différences et limitations connues avant de commencer votre migration.

Avant de commencer

Avant de commencer votre migration, effectuez les tâches suivantes :

  • Identifiez toutes les intégrations, scripts, connecteurs et processus en aval qui appellent /security/alerts.
  • Si vous utilisez Microsoft Sentinel, vérifiez si votre espace de travail est connecté au portail Microsoft Defender. Les alertes générées par Sentinel ne sont pas disponibles via l’API v2 tant que vous n’avez pas terminé cette intégration. Dans l’intervalle, utilisez l’API REST Sentinel pour récupérer les alertes Sentinel. Les alertes Sentinel autonomes ne sont pas prises en charge dans l’API v2 et l’API REST Sentinel sera mise hors service à l’avenir.
  • Passez en revue les différences et limitations connues pour identifier les sources de données supplémentaires dont vos flux de travail pourraient avoir besoin.

Pourquoi migrer ?

La nouvelle API d’alertes et d’incidents offre des améliorations significatives par rapport à l’API d’alertes héritée :

  • Corrélation automatique : les alertes provenant de plusieurs signaux (identité, point de terminaison, e-mail et cloud) sont automatiquement regroupées en incidents, ce qui donne aux analystes une vue plus large d’une attaque.
  • Preuves plus riches : les collections d’états héritées (userStates, hostStates, fileStates) sont remplacées par plus de 40 objets de preuve fortement typés, tels que userEvidence, azureResourceEvidenceaiAgentEvidence, et analyzedMessageEvidence qui sont plus faciles à utiliser par programmation.
  • Modèle centré sur l’incident : la nouvelle API introduit un objet d’incident de première classe qui représente l’histoire complète de l’attaque, ce qui permet une investigation et une réponse plus efficaces.
  • Couverture étendue des menaces : l’API unifiée inclut des sources supplémentaires telles que la protection contre la perte de données Microsoft Purview et la gestion des risques internes.
  • Contexte de menace plus riche : les alertes et les incidents incluent les techniques MITRE ATT&CK, les sources de détection et la classification des menaces.

Différences entre les API

Points de terminaison

Le tableau suivant répertorie les modifications apportées au point de terminaison.

Opération Point de terminaison hérité Nouveau point de terminaison
Répertorier les alertes GET /v1.0/security/alerts GET /v1.0/security/alerts_v2
Obtenir une alerte par ID GET /v1.0/security/alerts/{id} GET /v1.0/security/alerts_v2/{id}
Mettre à jour une alerte PATCH /v1.0/security/alerts/{id} PATCH /v1.0/security/alerts_v2/{id}
Répertorier les incidents Non disponible GET /v1.0/security/incidents
Obtenir l’incident par ID Non disponible GET /v1.0/security/incidents/{id}

Autorisations

L’inscription de votre application doit être mise à jour avec de nouvelles étendues d’autorisation Microsoft Graph.

Scénario Autorisation héritée Nouvelle autorisation
Lire les alertes SecurityEvents.Read.All SecurityAlert.Read.All
Lire et écrire des alertes SecurityEvents.ReadWrite.All SecurityAlert.ReadWrite.All
Lire les incidents API non disponible SecurityIncident.Read.All
Incidents de lecture et d’écriture API non disponible SecurityIncident.ReadWrite.All

Une fois que vous avez ajouté les nouvelles autorisations à votre inscription d’application, un administrateur doit accorder votre consentement avant que l’application puisse les utiliser en production.

Pour plus d’informations sur ces autorisations, consultez la référence des autorisations Microsoft Graph.

Mappage de champs

Le tableau suivant mappe les champs d’alertes v1 hérités à leurs équivalents alertes v2 . Ce mappage ne couvre que les champs qui existent dans la v1 et ont un équivalent direct ou approximatif dans la v2. La nouvelle API inclut de nombreux champs supplémentaires qui fournissent un contexte plus riche sur les alertes et les incidents.

Champ v1 champ v2 Notes
azureTenantId tenantId Même signification, propriété renommée.
lastModifiedDateTime lastUpdateDateTime Suit l’heure de la dernière mise à jour.
closedDateTime resolvedDateTime Indique le moment où l’alerte a été résolue.
activityGroupName actorDisplayName Champ renommé pour le contexte d’acteur.
commentaires classification + détermination La V2 sépare la disposition de la détermination du type d’attaque.
fournisseurInformation.fournisseur serviceSource + productName Les métadonnées du fournisseur sont divisées en une énumération et un nom d’affichage.
sourceMaterials[] alertWebUrl + incidentWebUrl Les liens du portail pointent désormais vers l’expérience Defender unifiée.
eventDateTime firstActivityDateTime + lastActivityDateTime L’horodatage unique devient un intervalle de temps.
incidentIds[] incident Chaque alerte appartient désormais exactement à un incident.
userStates[].userPrincipalName evidence(userEvidence).userAccount.userPrincipalName Les entités utilisateur se déplacent dans des objets de preuve typés.
hostStates[].fqdn evidence(deviceEvidence).deviceDnsName Les informations de l’hôte se déplacent vers la preuve de l’appareil.
fileStates[].name / fileHash.hashValue evidence(fileEvidence).fileName / fileDetails.sha256 Les métadonnées et les hachages des fichiers se déplacent dans les preuves des fichiers.
networkConnections[].destinationUrl evidence(urlEvidence).url Les artefacts de réseau se décomposent en types de preuves distincts.
networkConnections[].destinationAddress evidence(ipEvidence).ipAddress Les adresses IP se déplacent dans la preuve IP.
confiance Pas de remplacement direct Utilisez des valeurs de verdict de niveau preuve, telles que suspect ou malveillant, au lieu d’un score numérique.

Migrer votre application

Utilisez ces étapes pour migrer de l’API d’alertes héritée vers la nouvelle API d’alertes et d’incidents.

Étape 1 : Identifier les dépendances

Avant de modifier du code, identifiez toutes les intégrations, scripts, connecteurs et processus en aval qui appellent /security/alertsactuellement .

Étape 2 : Connecter Microsoft Sentinel pour une visibilité unifiée

Si vous utilisez Microsoft Sentinel, connectez votre espace de travail au portail Microsoft Defender et confirmez que les détections pertinentes sont promues en incidents. Sans cette intégration, les alertes générées par Sentinel n’apparaissent pas dans l’API v2.

Pendant que vous vous préparez à l’intégration, utilisez l’API REST Sentinel pour récupérer les alertes Sentinel. Gardez à l’esprit que les alertes Sentinel autonomes ne sont pas prises en charge dans le nouveau modèle d’API et que l’API REST Sentinel sera supprimée à l’avenir. Hiérarchisez l’intégration du portail Defender avant l’échéance du 15 octobre 2026.

Pour plus d’informations, voir Connecter Microsoft Sentinel au portail Microsoft Defender et Transition de votre environnement Microsoft Sentinel vers le portail Defender.

Étape 3 : Mettre à jour les points de terminaison et les autorisations de l’API

Pour chaque intégration :

  1. Remplacez les appels par /security/alerts/security/alerts_v2 ou /security/incidents en fonction de votre flux de travail.
  2. Mettez à jour les autorisations d’inscription des applications et obtenez le consentement de l’administrateur.
  3. Documentez les lacunes d’authentification et corrigez-les avant la date limite de mise hors service.

Étape 4 : Mettre à jour votre modèle de données et votre logique de requête

La migration v2 nécessite plus qu’un échange de champ par champ. Prévoyez les modifications suivantes :

  • Traitez les incidents comme des objets de première classe : dans la v2, les alertes appartiennent aux incidents. Envisagez de créer votre workflow autour des incidents pour obtenir l’histoire complète de l’attaque.
  • Mettre à jour la logique d’analyse et d’enrichissement : remplacez les références à userStates, hostStates, fileStateset networkConnections par les objets de preuve typés correspondants.
  • Réécrire OData filtres : Mettez à jour les filtres de requête pour utiliser les nouveaux noms de propriété et la fonction pour le filtrage basé sur les evidence/any() preuves.

Les exemples suivants illustrent les réécritures courantes de filtres.

Filtrer par produit ou source

# Legacy
GET /v1.0/security/alerts?$filter=vendorInformation/provider eq 'Microsoft Defender ATP'

# New - alerts v2
GET /v1.0/security/alerts_v2?$filter=serviceSource eq 'microsoftDefenderForEndpoint'

Filtrer par utilisateur impliqué

# Legacy: No direct OData filter on userStates sub-properties; required client-side filtering.

# New - alerts v2
GET /v1.0/security/alerts_v2?$filter=evidence/any(e: e/microsoft.graph.security.userEvidence/userAccount/userPrincipalName eq 'alice@contoso.com')

Filtrer par périphérique impliqué

# Legacy
GET /v1.0/security/alerts?$filter=hostStates/any(h: h/fqdn eq 'pc123.contoso.com')

# New
GET /v1.0/security/alerts_v2?$filter=evidence/any(e: e/microsoft.graph.security.deviceEvidence/deviceDnsName eq 'pc123.contoso.com')

Requêtes centrées sur l’incident (nouvelle fonctionnalité)

# Get all active, high-severity incidents
GET /v1.0/security/incidents?$filter=status eq 'active' and severity eq 'high'

# Get all alerts for a specific incident
GET /v1.0/security/incidents/{incidentId}/alerts

Étape 5 : Valider la couverture et les flux de travail en aval

Avant de mettre hors service votre intégration héritée :

  1. Vérifiez que les alertes et incidents attendus sont renvoyés par la nouvelle API.
  2. Vérifiez que les workflows en aval, tels que l’automatisation, la création de rapports et l’ingestion de SIEM, fonctionnent correctement après la migration.
  3. Passez en revue les différences de couverture connues et identifiez les sources de données supplémentaires dont vous avez encore besoin.

Utilisez un outil de test d’API comme Graph Explorer pour valider vos requêtes et inspecter le nouveau modèle de données.

Différences et limitations connues

  • Couverture Microsoft Sentinel : Les alertes générées par Sentinel ne sont renvoyées par l’API v2, sauf si votre espace de travail Sentinel est connecté au portail Microsoft Defender. Dans l’intervalle, utilisez l’API REST Sentinel pour récupérer ces alertes.
  • Alertes autonomes : les alertes qui existent en dehors du modèle d’incident Microsoft 365 Defender, y compris les détections autonomes qui ne sont pas promues à un incident, ne sont pas renvoyées par l’API v2.
  • Alertes réglées : les alertes supprimées par des règles de réglage d’alerte ne sont pas renvoyées via le point de alerts_v2 terminaison.
  • Événements Exchange Online à faible signal : Certains événements Exchange Online à faible signal, tels que la création de règles de boîte aux lettres et les retards de messages, ne sont pas inclus dans alerts_v2. Récupérez-les par le biais des journaux d’audit ou d’autres sources de données pertinentes.

Contenu connexe

  • Last updated on