Uso de la API de seguridad de Microsoft Graph
Importante
Las API de la versión /beta de Microsoft Graph están sujetas a cambios. No se admite el uso de estas API en aplicaciones de producción. Para determinar si una API está disponible en la versión 1.0, use el selector de Versión.
La API de seguridad de Microsoft Graph proporciona una interfaz y un esquema unificados para integrarse con soluciones de seguridad de Microsoft y asociados del ecosistema. Permite a los clientes simplificar las operaciones de seguridad y defenderse mejor contra el aumento de las ciberamenazas. La API de seguridad de Microsoft Graph federa las consultas a todos los proveedores de seguridad incorporados y agrega respuestas. Use la API de seguridad de Microsoft Graph para compilar aplicaciones que:
- Consolide y correlacione las alertas de seguridad de varios orígenes.
- Extraiga e investigue todos los incidentes y alertas de los servicios que forman parte o se integran con Microsoft 365 Defender.
- Desbloqueen datos contextuales para obtener información para investigaciones.
- Automatice las tareas de seguridad, los procesos empresariales, los flujos de trabajo y los informes.
- Enviar indicadores de amenazas a productos de Microsoft para detecciones personalizadas.
- Invoque acciones en en respuesta a nuevas amenazas.
- Proporcione visibilidad sobre los datos de seguridad para habilitar la administración proactiva de riesgos.
La API de seguridad de Microsoft Graph proporciona características clave como se describe en las secciones siguientes.
Acciones (versión preliminar)
Tome medidas inmediatas para defenderse frente a amenazas mediante la entidad securityAction . Cuando un analista de seguridad detecta un indicador nuevo, como un archivo, URL, dominio o dirección IP malintencionados, se puede habilitar la protección al instante en las soluciones de seguridad de Microsoft. Invoque una acción para un proveedor específico, vea todas las acciones realizadas y cancele una acción, si es necesario. Pruebe las acciones de seguridad con Microsoft Defender para punto de conexión (anteriormente ATP de Microsoft Defender) para bloquear la actividad malintencionada en los puntos de conexión de Windows mediante propiedades que se ven en alertas o identificadas durante investigaciones.
Nota: las acciones de seguridad solo admiten actualmente permisos de aplicación.
Búsqueda avanzada de amenazas
La búsqueda avanzada es una herramienta de búsqueda de amenazas basada en consulta que le permite explorar hasta 30 días de datos sin procesar. Puede inspeccionar eventos de forma proactiva en su red para localizar entidades e indicadores de amenazas. El acceso flexible a los datos permite realizar búsquedas sin restricciones de amenazas conocidas y potenciales.
Use runHuntingQuery para ejecutar una consulta de Lenguaje de consulta Kusto (KQL) en los datos almacenados en Microsoft 365 Defender. Aproveche el conjunto de resultados devuelto para enriquecer una investigación existente o descubrir amenazas no detectadas en la red.
Cuotas y asignación de recursos
Puede ejecutar una consulta en los datos de solo los últimos 30 días.
Los resultados incluyen un máximo de 100 000 filas.
El número de ejecuciones es limitado por inquilino:
- Llamadas API: hasta 45 solicitudes por minuto y hasta 1500 solicitudes por hora.
- Tiempo de ejecución: 10 minutos de tiempo de ejecución cada hora y 3 horas de tiempo de ejecución al día.
El tiempo máximo de ejecución de una sola solicitud es de 200 segundos.
Un código de respuesta HTTP 429 significa que ha alcanzado la cuota para el número de llamadas API o el tiempo de ejecución. Consulte el cuerpo de la respuesta para confirmar el límite que ha alcanzado.
El tamaño máximo del resultado de la consulta de una sola solicitud no puede superar los 124 MB. Si se supera el límite de tamaño, se produce una solicitud http 400 incorrecta con el mensaje "La ejecución de consultas ha superado el tamaño de resultado permitido. Optimice la consulta limitando el número de resultados e inténtelo de nuevo".
Detecciones personalizadas
Puede crear reglas de detección personalizadas de búsqueda avanzadas específicas de las operaciones de seguridad para permitirle supervisar proactivamente las amenazas y tomar medidas. Por ejemplo, puede crear reglas de detección personalizadas que busquen indicadores conocidos o dispositivos mal configurados. Estas desencadenan automáticamente alertas y cualquier acción de respuesta que especifique.
Cuotas
- Obtener varias reglas: 10 reglas por minuto por aplicación, 300 reglas por hora por aplicación, 600 reglas por hora por inquilino
- Obtener una sola regla: 100 reglas por minuto por aplicación, 1.500 reglas por hora por aplicación, 1.800 reglas por hora por inquilino
- Crear regla: 10 reglas por minuto por aplicación, 1.500 reglas por hora por aplicación, 1.800 reglas por hora por inquilino
- Regla de actualización: 100 reglas por minuto por aplicación, 1.500 reglas por hora por aplicación, 1.800 reglas por hora por inquilino
- Regla de eliminación: 100 reglas por minuto por aplicación, 1.500 reglas por hora por aplicación, 1.800 reglas por hora por inquilino
Alertas
Las alertas son advertencias detalladas sobre actividades sospechosas en el inquilino de un cliente que Microsoft o los proveedores de seguridad asociados han identificado y marcado como acción. Los ataques suelen emplear varias técnicas en diferentes tipos de entidades, como dispositivos, usuarios y buzones. El resultado son alertas de varios proveedores de seguridad para varias entidades del inquilino. Reunir las alertas individuales para obtener información sobre un ataque puede ser difícil y lleva mucho tiempo.
La versión beta de la API de seguridad ofrece dos tipos de alertas que agregan otras alertas de proveedores de seguridad y facilitan el análisis de ataques y la determinación de respuestas:
-
Alertas e incidentes : la última generación de alertas en la API de seguridad de Microsoft Graph. Se representan mediante el recurso de alerta y su colección, el recurso de incidente , definidos en el
microsoft.graph.securityespacio de nombres. -
Alertas heredadas : la primera generación de alertas en la API de seguridad de Microsoft Graph. Se representan mediante el recurso de alerta definido en el espacio de
microsoft.graphnombres.
Alertas e incidentes
Estos recursos de alertas extraen primero los datos de alerta de los servicios del proveedor de seguridad, que forman parte de Microsoft 365 Defender o están integrados en ellos. A continuación, consumen los datos para devolver pistas enriquecidas y valiosas sobre un ataque completado o en curso, los recursos afectados y las pruebas asociadas. Además, correlacionan automáticamente otras alertas con las mismas técnicas de ataque o con el mismo atacante en un incidente para proporcionar un contexto más amplio de un ataque. Recomiendan acciones de respuesta y corrección, lo que ofrece una capacidad de acción coherente en todos los distintos proveedores. El contenido enriquecido facilita a los analistas investigar y responder colectivamente a las amenazas.
Las alertas de los siguientes proveedores de seguridad están disponibles a través de estas alertas e incidentes enriquecidos:
- Protección de Microsoft Entra ID
- Microsoft 365 Defender
- Microsoft Defender for Cloud Apps
- Microsoft Defender para punto de conexión
- Microsoft Defender for Identity
- Microsoft Defender para Office 365
- Prevención de pérdida de datos de Microsoft Purview
Alertas heredadas
Nota:
La API de alertas heredada está en desuso y se quitará en abril de 2026. Se recomienda migrar a la nueva API de alertas e incidentes .
Los recursos de alerta heredados federan las llamadas de los proveedores de seguridad de Azure y Microsoft 365 Defender compatibles. Agregan datos de alerta comunes entre los distintos dominios para permitir que las aplicaciones unifiquen y optimicen la administración de problemas de seguridad en todas las soluciones integradas. Permiten a las aplicaciones correlacionar las alertas y el contexto para mejorar la protección y la respuesta a amenazas.
Con la funcionalidad de actualización de alertas, puede sincronizar el estado de alertas específicas en diferentes productos y servicios de seguridad que se integran con la API de seguridad de Microsoft Graph actualizando la entidad de alerta .
Las alertas de los siguientes proveedores de seguridad están disponibles a través del recurso de alerta heredado . La compatibilidad con las alertas GET, las alertas PATCH y la suscripción (a través de webhooks) se indica en la tabla siguiente.
| Proveedor de seguridad | OBTENER alerta |
REVISAR alerta |
Suscribirse a alerta |
|---|---|---|---|
| Protección de Microsoft Entra ID | ✓ |
✓ |
|
| Azure Security Center | ✓ |
✓ |
✓ |
Microsoft 365
|
✓ |
||
| Microsoft Defender for Cloud Apps (anteriormente Microsoft Cloud App Security) | ✓ |
✓ |
|
| Microsoft Defender para punto de conexión (anteriormente ATP de Microsoft Defender) ** | ✓ |
✓ |
|
| Microsoft Defender for Identity (anteriormente Protección contra amenazas avanzada de Azure) *** | ✓ |
✓ |
|
| Microsoft Sentinel (anteriormente Azure Sentinel) | ✓ |
No se admite en Microsoft Sentinel |
✓ |
Nota: Los nuevos proveedores se incorporan continuamente al ecosistema de seguridad de Microsoft Graph. Para solicitar nuevos proveedores o soporte extendido de proveedores existentes, escriba un problema en el repositorio de GitHub de seguridad de Microsoft Graph.
* Problema de archivo: el estado de las alertas se actualiza en las aplicaciones integradas de la API de seguridad de Microsoft Graph, pero no se refleja en la experiencia de administración del proveedor.
** Microsoft Defender para punto de conexión requiere roles de usuario adicionales para los que requiere la API de seguridad de Microsoft Graph. Solo los usuarios de Microsoft Defender para punto de conexión y los roles de API de seguridad de Microsoft Graph pueden tener acceso a los datos de Microsoft Defender para punto de conexión. Dado que la autenticación solo de aplicación no está limitada por esto, se recomienda usar un token de autenticación de solo aplicación.
Microsoft Defender for Identity alertas están disponibles a través de la integración de Microsoft Defender for Cloud Apps. Esto significa que obtiene alertas de Microsoft Defender for Identity solo si se ha unido a Unified SecOps y conectado Microsoft Defender for Identity a Microsoft Defender for Cloud Apps. Obtenga más información sobre cómo integrar Microsoft Defender for Identity y Microsoft Defender for Cloud Apps.
Simulación y entrenamiento de ataques
La simulación de ataques y entrenamiento forma parte de Microsoft Defender para Office 365. Este servicio permite a los usuarios de un inquilino experimentar un ataque de phishing benigno realista y aprender de él. Las experiencias de simulación y aprendizaje de ingeniería social para los usuarios finales ayudan a reducir el riesgo de que los usuarios no cumplan a través de esas técnicas de ataque. La API de simulación de ataques y aprendizaje permite a los administradores de inquilinos ver los ejercicios y aprendizajes de simulación iniciados y obtener informes sobre ideas derivadas en los comportamientos en línea de los usuarios en las simulaciones de phishing.
eDiscovery
Microsoft Purview eDiscovery (premium) ofrece un flujo de trabajo de un extremo a otro para conservar, recopilar, revisar, analizar y exportar el contenido que responde a las investigaciones internas y externas de la organización.
Consulta de registro de auditoría (versión preliminar)
Auditoría de Microsoft Purview proporciona una solución integrada para ayudar a las organizaciones a responder eficazmente a eventos de seguridad, investigaciones forenses, investigaciones internas y obligaciones de cumplimiento. Miles de operaciones de usuarios y administradores que se realizan en docenas de servicios y soluciones de Microsoft 365 se capturan, graban y retienen en el registro de auditoría unificado de su organización. Los registros de auditoría de estos eventos pueden ser objeto de búsqueda por las operaciones de seguridad, los administradores de TI, los equipos de riesgos de Insider, así como por los investigadores del cumplimiento y la legislación legal de la organización. Esta funcionalidad permite ver las actividades que se realizan en toda la organización de Microsoft 365.
Identidades
Problemas de mantenimiento
La API de problemas de estado de Microsoft Defender for Identity permite supervisar el estado de mantenimiento de los sensores y agentes en toda la infraestructura de identidad híbrida. Puede usar la API de problemas de mantenimiento para recuperar información sobre los problemas de mantenimiento actuales de los sensores, como el tipo de problema, el estado, la configuración y la gravedad. También puede usar la API para identificar y resolver cualquier problema que pueda afectar a la funcionalidad o la seguridad de los sensores y agentes.
Nota: La API de problemas de estado de Microsoft Defender for Identity solo está disponible en los planes de servicio de seguridad de Defender for Identity o Microsoft 365 E5/A5/G5/F5.
Sensores
La API de administración de sensores de Defender for Identity permite crear informes detallados de los sensores del área de trabajo, incluida la información sobre el nombre del servidor, la versión del sensor, el tipo, el estado y el estado de mantenimiento. También le permite administrar la configuración del sensor, como agregar descripciones, habilitar o deshabilitar actualizaciones retrasadas y especificar el controlador de dominio al que se conecta el sensor para consultar el id. de entra.
Incidentes
Un incidente es una colección de alertas correlacionadas y datos asociados que componen la historia de un ataque. La administración de incidentes forma parte de Microsoft 365 Defender y está disponible en el portal de Microsoft 365 Defender (https://security.microsoft.com/).
Los servicios y aplicaciones de Microsoft 365 crean alertas cuando detectan un evento o actividad sospechosos o malintencionados. Las alertas individuales proporcionan pistas valiosas sobre un ataque completado o en curso. Sin embargo, los ataques suelen emplear varias técnicas en distintos tipos de entidades, como dispositivos, usuarios y buzones de entrada. El resultado son varias alertas para varias entidades del espacio empresarial.
Dado que reunir las alertas individuales para obtener información sobre un ataque puede ser complicado y lento, Microsoft 365 Defender agrega automáticamente las alertas y su información asociada a un incidente.
La agrupación de alertas relacionadas en un incidente le ofrece una vista completa de un ataque. Por ejemplo, puede ver:
- Dónde se inició el ataque.
- Qué tácticas se usaron.
- Hasta dónde ha llegado el ataque a su cuenta empresarial.
- El ámbito del ataque, como el número de dispositivos, usuarios y buzones de entrada que se vieron afectados.
- Todos los datos asociados al ataque.
El recurso de incidentes y sus API permiten ordenar los incidentes para crear una respuesta de seguridad cibernética fundamentada. Expone una colección de incidentes, con sus alertas relacionadas, que se marcaron en la red, dentro del intervalo de tiempo especificado en la directiva de retención del entorno.
Protección de la información
Etiquetas: las etiquetas de protección de información indican cómo aplicar correctamente una etiqueta de carácter a la información. La API de la etiqueta de protección de la información describe la configuración de las etiquetas de sensibilidad que se aplican a un usuario o un espacio empresarial.
Evaluación de amenazas: la API de evaluación de amenazas de Microsoft Graph ayuda a las organizaciones a evaluar la amenaza que recibe cualquier usuario en un espacio empresarial. Esto permite a los clientes informar a Microsoft de los mensajes de correo no deseado o sospechosos, direcciones URL de suplantación de identidad y datos adjuntos malintencionados que reciben. Microsoft comprueba el ejemplo en cuestión y las directivas de la organización en juego antes de generar un resultado para que los administradores de inquilinos puedan comprender el veredicto de examen de amenazas y ajustar su directiva organizativa. También pueden usarlo para informar de correos electrónicos legítimos para evitar que se bloqueen.
Nota: se recomienda usar la API de envío de amenazas en su lugar.
Administración de registros
La mayoría de las organizaciones necesitan administrar los datos para cumplir proactivamente con las regulaciones del sector y las directivas internas, reducir el riesgo en caso de litigio o una infracción de seguridad, y permitir que sus empleados compartan de forma eficaz y ágil conocimientos que son actuales y pertinentes para ellos. Puede usar las API de administración de registros para aplicar sistemáticamente etiquetas de retención a diferentes tipos de contenido que requieren diferentes configuraciones de retención. Por ejemplo, puede configurar el inicio del período de retención desde el momento en que se creó, modificó por última vez el contenido, se etiquetó o cuando se produjo un evento para un tipo de evento determinado. Además, puede usar descriptores de plan de archivos para mejorar la capacidad de administración de estas etiquetas de retención.
Puntuación de seguridad
Puntuación de seguridad de Microsoft es una solución de análisis de seguridad que le permite ver su cartera de seguridad y conocer cómo mejorarla. Con una única puntuación, puede comprender mejor las acciones que ha realizado para reducir su riesgo en las soluciones de Microsoft. También puede comparar su puntuación con otras organizaciones y ver las tendencias de su puntuación con el paso del tiempo. Las entidades secureScore y secureScoreControlProfile le ayudan a equilibrar las necesidades de seguridad y productividad de su organización, al tiempo que habilitan la combinación adecuada de características de seguridad. También puede proyectar cuál será la puntuación después de adoptar características de seguridad.
Inteligencia sobre amenazas (versión preliminar)
Inteligencia contra amenazas de Microsoft Defender ofrece inteligencia sobre amenazas de primera clase para ayudar a proteger su organización frente a las ciberamenazas modernas. Puede usar Inteligencia sobre amenazas para identificar adversarios y sus operaciones, acelerar la detección y corrección, y mejorar sus inversiones y flujos de trabajo de seguridad.
Las API de inteligencia sobre amenazas (versión preliminar) permiten poner en funcionamiento la inteligencia que se encuentra en la interfaz de usuario. Esto incluye inteligencia finalizada en las formas de artículos y perfiles de intel, inteligencia artificial, incluidos ioCs y veredictos de reputación y, por último, datos de enriquecimiento, incluidos DNS pasivos, cookies, componentes y rastreadores.
Indicadores de inteligencia sobre amenazas (versión preliminar)
Nota:
La entidad tiIndicator está en desuso y se quitará en abril de 2026.
Los indicadores de amenazas también conocidos como indicadores de peligro (IO), representan datos sobre amenazas conocidas, como archivos malintencionados, direcciones URL, dominios y direcciones IP. Los clientes pueden generar indicadores mediante la recopilación de inteligencia de amenazas internas o adquirir indicadores de comunidades de inteligencia de amenazas, fuentes con licencia y otros orígenes. Estos indicadores se usarán en varias herramientas de seguridad para defenderse de las amenazas relacionadas.
La entidad tiIndicator permite a los clientes alimentar indicadores de amenazas a las soluciones de seguridad de Microsoft para realizar una acción de bloqueo o alerta en una actividad malintencionada, o para permitir que la actividad que se ha determinado sea irrelevante para la organización y suprimir acciones para el indicador. Para enviar un indicador, especifique la solución de seguridad de Microsoft destinada a utilizar el indicador y la acción que debe realizar para ese indicador.
Puede integrar la entidad tiIndicator en su aplicación o usar una de las siguientes plataformas de inteligencia de amenazas integradas (TIP):
- Uso compartido de inteligencia de amenazas de Palo Alto Networks MineMeld
- Plataforma de inteligencia de amenazas de código abierto de MISP disponible a través de la muestra de TI
Los indicadores de amenazas enviados a través de la API de seguridad de Microsoft Graph están disponibles hoy en día en los siguientes productos:
- Microsoft Defender para punto de conexión: permite alertar o bloquear indicadores de amenazas asociados a actividades malintencionadas. También puede permitir un indicador para ignorar el indicador de las investigaciones automatizadas. Para obtener más información sobre los tipos de indicadores compatibles y los límites de los recuentos de indicadores por inquilino, vea Administrar indicadores.
- Microsoft Sentinel: solo los clientes existentes pueden usar tiIndicator API para enviar indicadores de inteligencia sobre amenazas a Microsoft Sentinel. Para obtener las instrucciones más actualizadas y detalladas sobre cómo enviar indicadores inteligentes de amenazas a Microsoft Sentinel, consulte Conexión de la plataforma de inteligencia sobre amenazas a Microsoft Sentinel.
Envío de amenazas
La API de envío de amenazas de Microsoft Graph ayuda a las organizaciones a enviar una amenaza recibida por cualquier usuario de un inquilino. Esto permite a los clientes informar a Microsoft de los mensajes de correo no deseado o sospechosos, direcciones URL de suplantación de identidad y datos adjuntos malintencionados que reciben. Microsoft comprueba el envío en relación con las directivas de la organización en vigor y lo envía a los evaluadores humanos para su análisis. El resultado ayuda a los administradores de inquilinos a comprender el veredicto del examen de amenazas y a ajustar su directiva organizativa. Los administradores también pueden usar los resultados para informar de correos electrónicos legítimos para evitar que se bloqueen.
Nota: Se recomienda usar la API de envío de amenazas en lugar de la API de evaluación de amenazas Information Protection en desuso. La API de envío de amenazas proporciona una funcionalidad unificada de envío de amenazas de seguridad y agrega compatibilidad con resultados unificados, compatibilidad con consultas de envío de usuarios, compatibilidad con listas de permitidos y bloqueados de inquilinos, compatibilidad con revisiones de administrador y compatibilidad con el modo de solo aplicación.
protección de Email y colaboración
Microsoft Defender para Office 365 es un servicio de filtrado de correo electrónico basado en la nube que ayuda a proteger su organización frente a amenazas avanzadas a las herramientas de correo electrónico y colaboración, como suplantación de identidad (phishing), peligro de correo electrónico empresarial y ataques de malware. Puede usar las API analyzedemails y remediate de Microsoft Graph para recuperar metadatos de correo electrónico y realizar acciones de respuesta (eliminación temporal, eliminación rígida, traslado a correo no deseado, desplazamiento a la Bandeja de entrada) en los mensajes analizados.
Nota: Estas API solo están disponibles para los planes de servicio de seguridad Defender para Office 365 Plan 2 o Microsoft 365 A5/E5/F5/G5. Para obtener la lista más actualizada de los planes de servicio, consulte Microsoft Defender para Office 365 descripción del servicio.
Sensores
La API de administración de sensores de Defender for Identity permite crear informes detallados de los sensores del área de trabajo, incluida la información sobre el nombre del servidor, la versión del sensor, el tipo, el estado y el estado de mantenimiento. También permite administrar la configuración del sensor, como agregar descripciones, habilitar o deshabilitar actualizaciones retrasadas y especificar el controlador de dominio al que se conecta el sensor para consultar el identificador de entra.
Casos de uso comunes
A continuación se muestran algunas de las solicitudes más populares para trabajar con la API de seguridad de Microsoft Graph.
Puede usar webhooks de Microsoft Graph para suscribirse y recibir notificaciones sobre las actualizaciones de las entidades de la API de seguridad de Microsoft Graph.
Pasos siguientes
La API de seguridad de Microsoft Graph puede abrir nuevas formas de interactuar con diferentes soluciones de seguridad de Microsoft y asociados. Para empezar, siga estos pasos:
- Explore en profundidad alerts, tiIndicator (versión preliminar), securityAction (versión preliminar), secureScore y secureScoreControlProfiles.
- Pruebe la API en el Probador de Graph. En Consultas de ejemplo, seleccione mostrar más ejemplos y active la categoría Seguridad.
- Pruebe a suscribirse y recibir notificaciones sobre cambios en entidades.
Contenido relacionado
Code y contribuya a este ejemplo de API de seguridad de Microsoft Graph:
Explore otras opciones para conectarse con la API de seguridad de Microsoft Graph:
- Conectores de seguridad de Microsoft Graph para Logic Apps, Flow y Power Apps
- Ejemplos de bloc de notas Jupyter
Interactúe con la comunidad: