Creación de la API de alertas

Artículo
08/14/2024

Se aplica a:

¿Quiere experimentar Microsoft Defender para punto de conexión? Regístrese para obtener una prueba gratuita.

Nota:

Si es un cliente del Gobierno de EE. UU., use los URI que aparecen en Microsoft Defender para punto de conexión para clientes del Gobierno de EE. UU.

Sugerencia

Para mejorar el rendimiento, puede usar el servidor más cercano a la ubicación geográfica:

us.api.security.microsoft.com
eu.api.security.microsoft.com
uk.api.security.microsoft.com
au.api.security.microsoft.com
swa.api.security.microsoft.com
ina.api.security.microsoft.com

Descripción de la API

Crea una nueva alerta sobre el evento.

El evento de Microsoft Defender para punto de conexión es necesario para la creación de alertas.
Debe proporcionar tres parámetros del evento en la solicitud: Hora del evento, Id. de máquina e Id. de informe. Vea el ejemplo abajo.
Puede usar un evento que se encuentra en Advanced Hunting API o Portal.
Si existe una alerta abierta en el mismo dispositivo con el mismo título, la nueva alerta creada se combina con ella.
Una investigación automática se inicia automáticamente en las alertas creadas a través de la API.

Limitaciones

Las limitaciones de velocidad de esta API son 15 llamadas por minuto.

Permisos

Se requiere uno de los siguientes permisos para llamar a esta API. Para más información, incluido cómo elegir permisos, consulte Uso de Las API de Microsoft Defender para punto de conexión.

Tipo de permiso	Permiso	Nombre para mostrar del permiso
Aplicación	Alert.ReadWrite.All	"Leer y escribir todas las alertas"
Delegado (cuenta profesional o educativa)	Alert.ReadWrite	"Alertas de lectura y escritura"

Nota:

Al obtener un token con credenciales de usuario:

El usuario debe tener al menos el siguiente permiso de rol: Investigación de alertas. Para obtener más información, consulte Creación y administración de roles.
El usuario debe tener acceso al dispositivo asociado a la alerta, en función de la configuración del grupo de dispositivos. Para obtener más información, consulte Creación y administración de grupos de dispositivos.

La creación de grupos de dispositivos se admite en El plan 1 y el plan 2 de Defender para punto de conexión

Solicitud HTTP

POST https://api.securitycenter.microsoft.com/api/alerts/CreateAlertByReference

Encabezados de solicitud

Nombre	Tipo	Descripción
Authorization	Cadena	{token} de portador. Necesario.
Content-Type	Cadena	application/json. Necesario.

Cuerpo de la solicitud

En el cuerpo de la solicitud, proporcione los siguientes valores (todos son necesarios):

Propiedad	Tipo	Descripción
eventTime	DateTime(UTC)	Hora exacta del evento como cadena, obtenida de la búsqueda avanzada. Por ejemplo, `2018-08-03T16:45:21.7115183Z`Requerido.
reportId	Cadena	El reportId del evento, tal como se obtiene de la búsqueda avanzada. Necesario.
machineId	Cadena	Identificador del dispositivo en el que se identificó el evento. Necesario.
severity	Cadena	Gravedad de la alerta. Los valores de propiedad son: "Low", "Medium" y "High". Necesario.
title	Cadena	Título de la alerta. Necesario.
description	Cadena	Descripción de la alerta. Necesario.
recommendedAction	Cadena	El responsable de seguridad debe realizar esta acción al analizar la alerta. Necesario.
categoría	Cadena	Categoría de la alerta. Los valores de propiedad son: "General", "CommandAndControl", "Collection", "CredentialAccess", "DefenseEvasion", "Discovery", "Exfiltration", "Exploit", "Execution", "InitialAccess", "LateralMovement", "Malware", "Persistence", "PrivilegeEscalation", "Ransomware", "SuspiciousActivity" Required.

Respuesta

Si se ejecuta correctamente, este método devuelve 200 OK y un nuevo objeto de alerta en el cuerpo de la respuesta. Si no se encontró el evento con las propiedades especificadas (reportId, eventTime y machineId): 404 No encontrado.

Ejemplo

Solicitud

Este es un ejemplo de la solicitud.

POST https://api.securitycenter.microsoft.com/api/alerts/CreateAlertByReference

{
    "machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
    "severity": "Low",
    "title": "example",
    "description": "example alert",
    "recommendedAction": "nothing",
    "eventTime": "2018-08-03T16:45:21.7115183Z",
    "reportId": "20776",
    "category": "Exploit"
}