Migración de alertas heredadas a la API de alertas e incidentes

La API de alertas de seguridad de Microsoft Graph heredada disponible a través del punto de conexión está en desuso y se retirará el /security/alerts15 de octubre de 2026. Si la aplicación usa actualmente la API de alertas heredada para recuperar, supervisar o administrar alertas de seguridad, debe migrar a la nueva API de alertas e incidentes en Microsoft 365 Defender, disponible a través del punto de /security/alerts_v2 conexión.

En este artículo se describen las diferencias clave entre las dos API, se proporciona una referencia de asignación de campos y se describen los pasos para migrar la aplicación.

Importante

  • Después del 15 de octubre de 2026, el punto de conexión heredado /security/alerts dejará de devolver datos. Migre sus aplicaciones antes de esta fecha límite para evitar interrupciones en los flujos de trabajo de operaciones de seguridad.

  • La nueva API de alertas e incidentes no es un reemplazo directo e individual de la API de alertas heredada. Muestra alertas que forman parte del ecosistema de Microsoft 365 Defender. La nueva API no devuelve las alertas de orígenes que no están integrados con Microsoft 365 Defender, como un área de trabajo de Microsoft Sentinel que no está conectada al portal de Microsoft Defender o alertas independientes y ajustadas. Revise la sección de diferencias y limitaciones conocidas antes de comenzar la migración.

Antes de empezar

Antes de iniciar la migración, complete las siguientes tareas:

  • Identifique todas las integraciones, scripts, conectores y procesos intermedios que llaman a /security/alerts.
  • Si usa Microsoft Sentinel, compruebe si su área de trabajo está conectada al portal de Microsoft Defender. Las alertas generadas por Sentinel no están disponibles a través de la API v2 hasta que complete esa incorporación. Mientras tanto, use la API REST de Sentinel para recuperar alertas de Sentinel. Las alertas de Sentinel independientes no son compatibles con la API v2, y la API REST de Sentinel se retirará en el futuro.
  • Revisa las diferencias y limitaciones conocidas para identificar cualquier origen de datos complementario que puedan requerir tus flujos de trabajo.

¿Por qué migrar?

La nueva API de alertas e incidentes ofrece mejoras significativas respecto a la API de alertas heredada:

  • Correlación automática: las alertas de múltiples señales (identidad, punto final, correo electrónico y nube) se agrupan automáticamente en incidentes, lo que brinda a los analistas una visión más amplia de un ataque.
  • Evidencia más rica: Las colecciones de estados heredados (userStates, hostStates, fileStates) se reemplazan por más de 40 objetos de evidencia fuertemente tipados, como userEvidence, azureResourceEvidence, aiAgentEvidence, y analyzedMessageEvidence que son más fáciles de trabajar mediante programación.
  • Modelo centrado en incidentes: la nueva API introduce un objeto de incidente de primera clase que representa la historia completa del ataque, lo que permite una investigación y respuesta más efectivas.
  • Cobertura ampliada de amenazas: la API unificada incluye orígenes adicionales, como la Prevención de pérdida de datos de Microsoft Purview y la Administración de riesgos internos.
  • Contexto de amenaza más enriquecido: las alertas y los incidentes incluyen técnicas MITRE ATT&CK, orígenes de detección y clasificación de amenazas.

Diferencias de API

Puntos de conexión

En la tabla siguiente se enumeran los cambios en el punto de conexión.

Operación Punto de conexión heredado Nuevo punto de conexión
Lista de alertas GET /v1.0/security/alerts GET /v1.0/security/alerts_v2
Obtener alerta por id. GET /v1.0/security/alerts/{id} GET /v1.0/security/alerts_v2/{id}
Actualizar alerta PATCH /v1.0/security/alerts/{id} PATCH /v1.0/security/alerts_v2/{id}
Lista de Incidentes No disponible GET /v1.0/security/incidents
Obtener incidente por id. No disponible GET /v1.0/security/incidents/{id}

Permissions

El registro de la aplicación debe actualizarse con los nuevos ámbitos de permisos de Microsoft Graph.

Escenario Permiso heredado Nuevo permiso
Leer alertas SecurityEvents.Read.All SecurityAlert.Read.All
Alertas de lectura y escritura SecurityEvents.ReadWrite.All SecurityAlert.ReadWrite.All
Leer incidentes API no disponible SecurityIncident.Read.All
Incidentes de lectura y escritura API no disponible SecurityIncident.ReadWrite.All

Después de agregar los nuevos permisos al registro de la aplicación, un administrador debe otorgar el consentimiento para que la aplicación pueda usarlos en producción.

Para obtener más información acerca de estos permisos, consulte Referencia de permisos de Microsoft Graph.

Asignación de campos

En la tabla siguiente se asignan los campos de las alertas heredadas v1 a sus equivalentes de alertas v2 . Esta asignación solo cubre los campos que existen en v1 y tienen una contraparte directa o aproximada en v2. La nueva API incluye muchos campos adicionales que proporcionan un contexto más enriquecido sobre alertas e incidentes.

campo v1 campo v2 Notas
azureTenantId tenantId El mismo significado, propiedad renombrada.
lastModifiedDateTime lastUpdateDateTime Realiza un seguimiento de la hora de actualización más reciente.
closedDateTime resolvedDateTime Representa cuándo se resolvió la alerta.
activityGroupName actorDisplayName Campo cuyo nombre se ha cambiado para el contexto del actor.
feedback Clasificación + determinación v2 separa la disposición de la determinación de tipo de ataque.
vendorInformation.provider serviceSource + productName Los metadatos del proveedor se dividen en una enumeración y un nombre para mostrar.
sourceMaterials[] alertWebUrl + incidentWebUrl Los vínculos del portal ahora apuntan a la experiencia unificada de Defender.
eventDateTime firstActivityDateTime + lastActivityDateTime Una sola marca de tiempo se convierte en un intervalo de tiempo.
incidentIds[] identificador de incidente Cada alerta ahora pertenece exactamente a un incidente.
userStates[].userPrincipalName evidence(userEvidence).userAccount.userPrincipalName Las entidades de usuario se mueven a objetos de evidencia con tipo.
hostStates[].fqdn evidence(deviceEvidence).deviceDnsName La información del host pasa a la evidencia del dispositivo.
fileStates[].name / fileHash.hashValue evidence(fileEvidence).fileName / fileDetails.sha256 Los metadatos y hashes de archivo se mueven a la evidencia de archivo.
networkConnections[].destinationUrl evidence(urlEvidence).url Los artefactos de red se descomponen en tipos de evidencia independientes.
networkConnections[].destinationAddress evidence(ipEvidence).ipAddress Las direcciones IP se mueven a la evidencia IP.
confianza Sin reemplazo directo Utilice valores de veredicto a nivel de evidencia, como sospechoso o malicioso, en lugar de una puntuación numérica.

Migrar la aplicación

Siga estos pasos para migrar de la API de alertas heredada a la nueva API de alertas e incidentes.

Paso 1: Identificar dependencias

Antes de cambiar cualquier código, identifique todas las integraciones, scripts, conectores y procesos descendentes que actualmente llaman a /security/alerts.

Paso 2: Conectar a Microsoft Sentinel para obtener visibilidad unificada

Si usa Microsoft Sentinel, conecte su área de trabajo al portal de Microsoft Defender y confirme que las detecciones relevantes se promueven a incidentes. Sin esta integración, las alertas generadas por Sentinel no aparecen en la API v2.

Mientras se prepara para la incorporación, use la API REST de Sentinel para recuperar alertas de Sentinel. Tenga en cuenta que las alertas de Sentinel independientes no son compatibles con el nuevo modelo de API y que la API REST de Sentinel se retirará en el futuro. Priorice la incorporación del portal de Defender antes de la fecha límite del 15 de octubre de 2026.

Para obtener más información, consulte Conexión de Microsoft Sentinel al portal de Microsoft Defender y Transición del entorno de Microsoft Sentinel al portal de Defender.

Paso 3: Actualizar los puntos de conexión y los permisos de la API

Para cada integración:

  1. Reemplace las llamadas a /security/alerts con /security/alerts_v2 o /security/incidents según corresponda para su flujo de trabajo.
  2. Actualice los permisos de registro de la aplicación y obtenga el consentimiento del administrador.
  3. Documente las brechas de autenticación y resuélvalas antes de la fecha límite de retirada.

Paso 4: Actualizar el modelo de datos y la lógica de consulta

La migración v2 requiere más que un intercambio de campo por campo. Prevea los siguientes cambios:

  • Trate los incidentes como objetos de primera clase: En v2, las alertas pertenecen a incidentes. Considere la posibilidad de crear su flujo de trabajo en torno a los incidentes para obtener la historia completa del ataque.
  • Actualice la lógica de análisis y enriquecimiento: reemplace las referencias a userStates, hostStates, fileStates, y networkConnections con los objetos de evidencia con tipo correspondiente.
  • Reescribir filtros OData: actualice los filtros de consulta para usar los nuevos nombres de propiedad y la evidence/any() función para el filtrado basado en evidencia.

En los ejemplos siguientes se muestran reescrituras de filtros comunes.

Filtrar por producto o origen

# 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'

Filtrar por usuario involucrado

# 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')

Filtrar por dispositivo implicado

# 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')

Consultas centradas en incidentes (nueva funcionalidad)

# 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

Paso 5: Validar la cobertura y los flujos de trabajo descendentes

Antes de retirar la integración heredada:

  1. Confirme que la nueva API devuelve las alertas e incidentes esperados.
  2. Compruebe que los flujos de trabajo descendentes, como la automatización, los informes y la ingesta de SIEM, funcionan correctamente después de la migración.
  3. Revisa las diferencias de cobertura conocidas e identifica cualquier fuente de datos complementaria que aún necesites.

Use una herramienta de prueba de API, como Graph Explorer , para validar las consultas e inspeccionar el nuevo modelo de datos.

Limitaciones y diferencias conocidas

  • Cobertura de Microsoft Sentinel: La API v2 no devuelve las alertas generadas por Sentinel a menos que su área de trabajo de Sentinel esté conectada al portal de Microsoft Defender. Mientras tanto, use la API REST de Sentinel para recuperar estas alertas.
  • Alertas independientes: las alertas que existen fuera del modelo de incidentes de Microsoft 365 Defender, incluidas las detecciones independientes que no se promueven a un incidente, no se devuelven por la API v2.
  • Alertas optimizadas: las alertas suprimidas por las reglas de ajuste de alertas no se devuelven a través del punto de alerts_v2 conexión.
  • Eventos de Exchange Online de señal baja: algunos eventos de Exchange Online de señal baja, como la creación de reglas de buzón de correo y los retrasos en los mensajes, no se incluyen en alerts_v2. Recupérelos a través de registros de auditoría u otros orígenes de datos relevantes.

Contenido relacionado

  • Last updated on