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

La API heredada de alertas de seguridad de Microsoft Graph disponible a través del /security/alerts punto de conexión está en desuso y se retirará el 31 de agosto 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 31 de agosto de 2026, el punto de conexión heredado /security/alerts dejará de devolver datos. Migre las 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 uno a uno 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 optimizadas. Revise la sección de diferencias y limitaciones conocidas antes de comenzar la migración.

Antes de empezar

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

  • Identifique todas las integraciones, scripts, conectores y procesos de bajada que llaman a /security/alerts.
  • Si usa Microsoft Sentinel, compruebe si el á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. Entre tanto, use la API REST de Sentinel para recuperar Sentinel alertas. Las alertas de Sentinel independientes no se admiten en la API v2 y la API REST de Sentinel se retirará en el futuro.
  • Revise las diferencias y limitaciones conocidas para identificar los orígenes de datos complementarios que puedan requerir los flujos de trabajo.

¿Por qué migrar?

La nueva API de alertas e incidentes ofrece mejoras significativas en la API de alertas heredadas:

  • Correlación automática: las alertas de varias señales (identidad, punto de conexión, correo electrónico y nube) se agrupan automáticamente en incidentes, lo que proporciona a los analistas una visión más amplia de un ataque.
  • Evidencia más completa: las colecciones de estados heredadas (userStates, hostStates, fileStates) se reemplazan por más de 40 objetos de evidencia fuertemente tipados, como userEvidence, azureResourceEvidence, aiAgentEvidencey analyzedMessageEvidence que son más fáciles de trabajar con mediante programación.
  • Modelo centrado en incidentes: la nueva API presenta un objeto de incidente de primera clase que representa el caso de ataque completo, lo que permite una investigación y una respuesta más eficaces.
  • Cobertura de amenazas ampliada: la API unificada incluye orígenes adicionales, como Prevención de pérdida de datos de Microsoft Purview y Insider Risk Management.
  • Contexto de amenazas más completo: las alertas y los incidentes incluyen técnicas de 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 identificador 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
Obtención del incidente por identificador No disponible GET /v1.0/security/incidents/{id}

Permissions

El registro de la aplicación debe actualizarse con 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 conceder su consentimiento para que la aplicación pueda usarlos en producción.

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

Asignación de campos

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

Campo v1 Campo v2 Notas
azureTenantId tenantId El mismo significado, se ha cambiado el nombre de la propiedad.
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 Se ha cambiado el nombre del campo para el contexto de actor.
feedback clasificación y determinación v2 separa la eliminación de la determinación del 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[] incidentId 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 los 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 de IP.
confianza Sin reemplazo directo Use valores de veredicto de nivel de evidencia, como sospechosos o malintencionados, en lugar de una puntuación numérica.

Migración de la aplicación

Siga estos pasos para migrar desde 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 de bajada que actualmente llaman a /security/alerts.

Paso 2: Conectar Microsoft Sentinel para una visibilidad unificada

Si usa Microsoft Sentinel, conecte el área de trabajo al portal de Microsoft Defender y confirme que las detecciones pertinentes 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 Sentinel alertas. Tenga en cuenta que las alertas de Sentinel independientes no se admiten en 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 31 de agosto 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: Actualización de los permisos y puntos de conexión de API

Para cada integración:

  1. Reemplace las llamadas a /security/alerts con /security/alerts_v2 o /security/incidents según corresponda para el flujo de trabajo.
  2. Actualice los permisos de registro de aplicaciones y obtenga el consentimiento del administrador.
  3. Documente las brechas de autenticación y resuelvalas 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 a campo. Planee los siguientes cambios:

  • Tratar los incidentes como objetos de primera clase: en v2, las alertas pertenecen a incidentes. Considere la posibilidad de crear el flujo de trabajo en torno a incidentes para obtener la historia completa de ataques.
  • Actualice la lógica de análisis y enriquecimiento: reemplace las referencias a userStates, hostStates, fileStatesy networkConnections por los objetos de evidencia con tipo correspondientes.
  • Reescribir filtros de 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 las 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 implicado

# 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: Validación de flujos de trabajo de cobertura y de bajada

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 de nivel inferior (como la automatización, los informes y la ingesta siem) funcionan correctamente después de la migración.
  3. Revise las diferencias de cobertura conocidas e identifique los orígenes de datos complementarios que todavía necesita.

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

Diferencias y limitaciones conocidas

  • Microsoft Sentinel cobertura: la API v2 no devuelve las alertas generadas por Sentinel a menos que el área de trabajo de Sentinel esté conectada al portal de Microsoft Defender. Entre tanto, use la API REST de Sentinel para recuperar estas alertas.
  • Alertas independientes: la API v2 no devuelve las alertas que existen fuera del modelo de incidentes de Microsoft 365 Defender, incluidas las detecciones independientes no promocionadas a un incidente.
  • Alertas optimizadas: las alertas suprimidas por las reglas de optimización de alertas no se devuelven a través del alerts_v2 punto de 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 y los retrasos en los mensajes, no se incluyen en alerts_v2. Recuperarlos a través de registros de auditoría u otros orígenes de datos pertinentes.

Contenido relacionado

  • Last updated on