Compartir a través de


Referencia de la API de administración de alertas para las consolas de administración locales

Este artículo enumera las API de REST de administración de alertas compatibles con consolas de administración locales de Microsoft Defender para IoT.

alertas (Recuperación de información de alertas)

Use esta API para recuperar todas las alertas o las alertas filtradas de una consola de administración local.

URI:/external/v1/alerts o /external/v2/alerts

GET

Parámetros de consulta:

Nombre Descripción Ejemplo Obligatorio u opcional
state Obtenga únicamente alertas controladas o no controladas. Valores admitidos:
- handled
- unhandled
Se ignorará al resto de los otros valores.
/api/v1/alerts?state=handled Opcionales
fromTime Obtenga alertas creadas a partir de un momento dado, en milisegundos desde la hora de época y en la zona horaria UTC. /api/v1/alerts?fromTime=<epoch> Opcional
toTime Obtenga alertas creadas solamente antes de un momento concreto, en milisegundos desde la hora de época y en la zona horaria UTC. /api/v1/alerts?toTime=<epoch> Opcionales
siteId el sitio en el que se detectó la alerta. /api/v1/alerts?siteId=1 Opcionales
zoneId la zona en la que se detectó la alerta. /api/v1/alerts?zoneId=1 Opcionales
sensorId el sensor en el que se detectó la alerta. /api/v1/alerts?sensorId=1 Opcionales

Nota

Es posible que no tenga el identificador de sitio y zona. En este caso, primero consulte todos los dispositivos para recuperar el id. de sitio y de zona. Para más información, consulte Referencia de API de integración para consolas de administración locales (versión preliminar pública).

UUID (Administrar alertas basadas en el UUID)

Use esta API para realizar acciones especificadas en una alerta específica detectada por Defender para IoT.

Por ejemplo, puede usar esta API para crear una regla de desvío que desvía los datos a QRadar. Para obtener más información, consulte Integración de QRadar con Microsoft Defender para IoT.

URI:/external/v1/alerts/<UUID>

PUT

Tipo: JSON

Parámetros de consulta:

Nombre Descripción Ejemplo Obligatorio u opcional
UUID Define el identificador único universal (UUID) de la alerta que desea controlar o controlar y aprender. /api/v1/alerts/7903F632-H7EJ-4N69-F40F-4B1E689G00Q0 Obligatorio

Parámetros del cuerpo

Nombre Descripción Ejemplo Obligatorio u opcional
action String handle o handleAndLearn Obligatorio

Ejemplo de solicitud

{
    "action": "handle"
}

maintenanceWindow (Crear exclusiones de alertas)

Administra las ventanas de mantenimiento, en las que no se enviarán alertas. Use esta API para definir y actualizar las horas de inicio y detención, los dispositivos o subredes que se deben excluir al desencadenar las alertas o defina y actualice los motores de Defender para IoT que deben excluirse.

Por ejemplo, durante una ventana de mantenimiento, quizá quiera detener la entrega de alertas para todas las alertas, salvo las alertas de malware en dispositivos críticos.

Las ventanas de mantenimiento que se definen con la API maintenanceWindow aparecen en la ventana Exclusiones de alertas de la consola de administración local como una regla de exclusión de solo lectura, denominada con la siguiente sintaxis: Maintenance-{token name}-{ticket ID}.

Importante

Esta API solo se admite con fines de mantenimiento y durante un tiempo limitado, y no está pensada para usarse en lugar de las reglas de exclusión de alertas. Use esta API solo para las operaciones de mantenimiento puntuales y temporales.

URI:/external/v1/maintenanceWindow

POST

Crea una nueva ventana de mantenimiento.

Parámetros del cuerpo:

Nombre Descripción Ejemplo Obligatorio u opcional
ticketId Cadena define el id. del vale de mantenimiento en los sistemas del usuario. Asegúrese de que el id. de vale no está vinculado a una ventana abierta existente. 2987345p98234 Obligatorio
ttl Entero positivo. Define el TTL (período de vida), que es la duración de la ventana de mantenimiento en minutos. Una vez completado el período de tiempo definido, la ventana de mantenimiento finaliza el sistema vuelve a comportarse de manera normal. 180 Obligatorio
engines Matriz JSON de cadenas. Define de qué motor se van a suprimir las alertas durante la ventana de mantenimiento. Valores posibles:

- ANOMALY
- MALWARE
- OPERATIONAL
- POLICY_VIOLATION
- PROTOCOL_VIOLATION
ANOMALY,OPERATIONAL Opcional
sensorIds Matriz JSON de cadenas. Define de qué sensores se van a suprimir las alertas durante la ventana de mantenimiento. Puede obtener estos identificadores de sensor desde la API de dispositivos (administrar dispositivos de sensor de OT). 1,35,63 Opcionales
subredes Matriz JSON de cadenas. Define de qué subredes se van a suprimir las alertas durante la ventana de mantenimiento. Defina cada subred en una notación CIDR. 192.168.0.0/16,138.136.80.0/14,112.138.10.0/8 Opcional

Delete

Cierra una ventana de mantenimiento existente.

Parámetros de consulta:

Nombre Descripción Ejemplo Obligatorio u opcional
ticketId define el id. del vale de mantenimiento en los sistemas del usuario. Asegúrese de que el id. de vale esté vinculado a una ventana abierta existente. 2987345p98234 Obligatorio

GET

Recupere un registro de todas las acciones abrir (POST), cerrar (DELETE) y actualizar (PUT) que se realizaron mediante esta API para controlar las ventanas de mantenimiento. T

Parámetros de consulta:

Nombre Descripción Ejemplo Obligatorio u opcional
fromDate filtra los registros de la fecha predefinida y posteriores. El formato es YYYY-MM-DD. 2022-08-10 Opcionales
toDate filtra los registros hasta la fecha predefinida. El formato es YYYY-MM-DD. 2022-08-10 Opcionales
ticketId filtra los registros relacionados con un id. de vale específico. 9a5fe99c-d914-4bda-9332-307384fe40bf Opcionales
tokenName filtra los registros relacionados con un token específico. quarterly-sanity-window Opcionales

Códigos de error:

Código Message Descripción
200 Aceptar la acción se ha completado correctamente.
204: Ningún contenido no hay ningún dato que mostrar.
400 Bad Request El formato de fecha es incorrecto.
500 Internal Server Error cualquier otro error inesperado.

PUT

Permite actualizar la duración de la ventana de mantenimiento después de iniciar el proceso de mantenimiento al cambiar el parámetro ttl. La nueva definición de duración invalida a la anterior.

Este método resulta útil cuando se quiere establecer una duración más larga que la duración configurada actualmente. Por ejemplo, si ha definido originalmente 180 minutos, han transcurrido 90 minutos y desea agregar otros 30 minutos, actualice el minuto ttl a 120 para restablecer el recuento de duración.

Parámetros de consulta:

Nombre Descripción Ejemplo Obligatorio u opcional
ticketId Cadena define el id. del vale de mantenimiento en los sistemas del usuario. 2987345p98234 Obligatorio
ttl Entero positivo. Define la duración de la ventana en minutos. 210 Obligatorio

pcap (Alerta de solicitud PCAP)

Use esta API para solicitar un archivo PCAP relacionado con una alerta.

URI:/external/v2/alerts/

GET

Parámetros de consulta:

Nombre Descripción Ejemplo Obligatorio u opcional
id Identificador de alerta de la consola de administración local /external/v2/alerts/pcap/<id> Obligatorio

Pasos siguientes

Para obtener más información, consulte la información general de referencia de API de Defender para IoT.