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

En este artículo se enumeran las API rest de administración de alertas compatibles con las consolas de administración locales de Microsoft Defender para IoT.

alertas (recuperar información de alerta)

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

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

OBTENER

Parámetros de consulta:

Nombre	Descripción	Ejemplo	Obligatorio/Opcional
de estado de	Obtenga solo alertas controladas o no controladas. Valores admitidos: - handled - unhandled Se omiten todos los demás valores.	/api/v1/alerts?state=handled	Opcional
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 solo antes en un momento dado, en milisegundos desde la hora de época y en la zona horaria UTC.	/api/v1/alerts?toTime=<epoch>	Opcional
siteId	Sitio en el que se detectó la alerta.	/api/v1/alerts?siteId=1	Opcional
zoneId	Zona en la que se detectó la alerta.	/api/v1/alerts?zoneId=1	Opcional
sensorId	Sensor en el que se detectó la alerta.	/api/v1/alerts?sensorId=1	Opcional

Nota

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

tipo: JSON

Lista de alertas con los siguientes campos:

Nombre	Tipo	Admite valores NULL/No acepta valores NULL	Lista de valores
id. de	Numérico	No acepta valores NULL	-
sensorId	Numérico	No acepta valores NULL	-
zoneId	Numérico	No acepta valores NULL	-
de tiempo	Numérico	No acepta valores NULL	Milisegundos de hora de época, en zona horaria UTC
de título de	Cuerda	No acepta valores NULL	-
de mensajes	Cuerda	No acepta valores NULL	-
de gravedad	Cuerda	No acepta valores NULL	Warning, Minor, Majoro Critical
del motor de	Cuerda	No acepta valores NULL	Protocol Violation, Policy Violation, Malware, Anomalyo Operational
sourceDevice	Numérico	Nullable	Id. de dispositivo
destinationDevice	Numérico	Nullable	Id. de dispositivo
correcciónSteps	Cuerda	Nullable	Pasos de corrección que se muestran en la alerta
additionalInformation	Objeto de información adicional	Nullable	-
controladas	Boolean, estado de la alerta	No acepta valores NULL	true o false

campos de información adicional:

Nombre	Tipo	Admite valores NULL/No acepta valores NULL	Lista de valores
descripción	Cuerda	No acepta valores NULL	-
de información	Matriz JSON	No acepta valores NULL	Cuerda

Agregado para laV2 :

Nombre	Tipo	Admite valores NULL/No acepta valores NULL	Lista de valores
sourceDeviceAddress	Cuerda	Nullable	Dirección IP o MAC
destinationDeviceAddress	Cuerda	Nullable	Dirección IP o MAC
correcciónSteps	Matriz JSON	No acepta valores NULL	Cadenas, pasos de corrección descritos en alerta
sensorName	Cuerda	No acepta valores NULL	Nombre del sensor definido por el usuario
zoneName	Cuerda	No acepta valores NULL	Nombre de la zona asociada al sensor
siteName	Cuerda	No acepta valores NULL	Nombre del sitio asociado al sensor

Para obtener más información, consulte referencia de la versión de sensor API.

Ejemplo de respuesta

[
    {
        "engine": "Operational",
        "handled": false,
        "title": "Traffic Detected on sensor Interface",
        "additionalInformation": null,
        "sourceDevice": 0,
        "zoneId": 1,
        "siteId": 1,
        "time": 1594808245000,
        "sensorId": 1,
        "message": "The sensor resumed detecting network traffic on ens224.",
        "destinationDevice": 0,
        "id": 1,
        "severity": "Warning"
    },
    {
        "engine": "Anomaly",
        "handled": false,
        "title": "Address Scan Detected",
        "additionalInformation": null,
        "sourceDevice": 4,
        "zoneId": 1,
        "siteId": 1,
        "time": 1594808260000,
        "sensorId": 1,
        "message": "Address scan detected.\nScanning address: 10.10.10.22\nScanned subnet: 10.11.0.0/16\nScanned addresses: 10.11.1.1, 10.11.20.1, 10.11.20.10, 10.11.20.100, 10.11.20.2, 10.11.20.3, 10.11.20.4, 10.11.20.5, 10.11.20.6, 10.11.20.7...\nIt is recommended to notify the security officer of the incident.",
        "destinationDevice": 0,
        "id": 2,
        "severity": "Critical"
    },
    {
        "engine": "Operational",
        "handled": false,
        "title": "Suspicion of Unresponsive MODBUS Device",
        "additionalInformation": null,
        "sourceDevice": 194,
        "zoneId": 1,
        "siteId": 1,
        "time": 1594808285000,
        "sensorId": 1,
        "message": "Outstation device 10.13.10.1 (Protocol Address 53) seems to be unresponsive to MODBUS requests.",
        "destinationDevice": 0,
        "id": 3,
        "severity": "Minor"
    }
]

comando cURL

tipo: GET

de API de :

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<>IP_ADDRESS>/external/v1/alerts?state=&zoneId=&fromTime=&toTime=&siteId=&sensor='

ejemplo:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/external/v1/alerts?state=unhandled&zoneId=1&fromTime=0&toTime=1594551777000&siteId=1&sensor=1'

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 reenvío que reenvía los datos a QRadar. Para obtener más información, consulte Integrar Qradar con Microsoft Defender para IoT.

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

PONER

tipo: JSON

Parámetros de consulta:

Nombre	Descripción	Ejemplo	Obligatorio/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 Body

Nombre	Descripción	Ejemplo	Obligatorio/Opcional
de acción	Cuerda	handle o handleAndLearn	Obligatorio

ejemplo de solicitud de

{
    "action": "handle"
}

tipo: JSON

Matriz de objetos JSON que representan dispositivos.

Campos de respuesta:

Nombre	Tipo	Obligatorio/Opcional	Descripción
contenido o de error	Cuerda	Obligatorio	Si la solicitud se realiza correctamente, aparece la propiedad content. De lo contrario, aparece la propiedad error.

posibles valores de contenido:

Código de estado	Mensaje	Descripción
200	La solicitud de actualización de alertas finalizó correctamente.	La solicitud de actualización finalizó correctamente. Sin comentarios.
200	La alerta ya se controló (identificador).	La alerta ya se controló cuando se recibió una solicitud de identificador para la alerta. La alerta permanece controlada.
200	La alerta ya se ha controlado y aprendido (handleAndLearn).	La alerta ya se ha controlado y aprendido cuando se recibió una solicitud para handleAndLearn. La alerta permanece en el estado de handledAndLearn.
200	La alerta ya se controló (controló). Controlar y aprender (handleAndLearn) se realizó en la alerta.	La alerta ya se controló cuando se recibió una solicitud para handleAndLearn. La alerta se convierte en handleAndLearn.
200	La alerta ya se ha controlado y aprendido (handleAndLearn). Solicitud de identificador ignorada.	La alerta ya se handleAndLearn cuando se recibió una solicitud para controlar la alerta. La alerta permanece handleAndLearn.
500	Acción no válida.	La acción que se envió no es una acción válida para realizar en la alerta.
500	Error inesperado.	Error inesperado. Para resolver el problema, póngase en contacto con el soporte técnico.
500	No se pudo ejecutar la solicitud porque no se encontró ninguna alerta para este UUID.	No se encontró el UUID de alerta especificado en el sistema.

Ejemplo de respuesta: Correcto

{
    "content": "Alert update request finished successfully"
}

Ejemplo de respuesta: Incorrecto

{
    "error": "Invalid action"
}

comando cURL

Tipo: PUT

API:

curl -k -X PUT -d '{"action": "<ACTION>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/external/v1/alerts/<UUID>

ejemplo:

curl -k -X PUT -d '{"action": "handle"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/alerts/1-1594550943000

maintenanceWindow (Crear exclusiones de alertas)

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

Por ejemplo, durante una ventana de mantenimiento, es posible que desee detener la entrega de alertas de todas las alertas, excepto las alertas de malware en dispositivos críticos.

Las ventanas de mantenimiento que definen con la API de 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 período de tiempo limitado, y no está pensada para usarse en lugar de reglas de exclusión de alertas. Use esta API solo para operaciones de mantenimiento temporal únicas.

URI: /external/v1/maintenanceWindow

EXPONER

Crea una nueva ventana de mantenimiento.

parámetros Body:

Nombre	Descripción	Ejemplo	Obligatorio/Opcional
ticketId	Cuerda. Define el identificador de vale de mantenimiento en los sistemas del usuario. Asegúrese de que el identificador 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 del período de mantenimiento, en minutos. Una vez completado el período de tiempo definido, la ventana de mantenimiento finaliza y el sistema se comporta normalmente de nuevo.	180	Obligatorio
motores de	Matriz JSON de cadenas. Define qué motor 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 qué sensores suprimir las alertas durante la ventana de mantenimiento. Puede obtener estos identificadores de sensor desde los dispositivos de (administrar dispositivos de sensor de OT) API.	1,35,63	Opcional
subredes	Matriz JSON de cadenas. Define las subredes de las que se suprimirán 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

Código de estado	Mensaje	Descripción
201 (creado)	-	La acción se completó correctamente.
400 (solicitud incorrecta)	No TicketId	Faltaba una solicitud de API ticketId valor.
400 (solicitud incorrecta)	TTL no válido	La solicitud de API incluía un valor TTL no positivo o no numérico.
400 (solicitud incorrecta)	No se pudo analizar la solicitud.	Problema al analizar el cuerpo, como parámetros incorrectos o valores no válidos.
400 (solicitud incorrecta)	Ya existe una ventana de mantenimiento con los mismos parámetros.	Aparece cuando ya existe una ventana de mantenimiento existente con los mismos detalles.
404 (no encontrado)	Identificador de sensor desconocido	Uno de los sensores enumerados en la solicitud no existe.
409 (conflicto)	El identificador de vale ya tiene una ventana abierta.	El identificador de vale está vinculado a otra ventana de mantenimiento abierta.
500 (error interno del servidor)	-	Cualquier otro error inesperado.

comando cURL

tipo: POST

de API de :

curl -k -X POST -d '{"ticketId": "<TICKET_ID>",ttl": <TIME_TO_LIVE>,"engines": [<ENGINE1, ENGINE2...ENGINEn>],"sensorIds": [<SENSOR_ID1, SENSOR_ID2...SENSOR_IDn>],"subnets": [<SUBNET1, SUBNET2....SUBNETn>]}' -H "Authorization: <AUTH_TOKEN>" https://<IP address>/external/v1/maintenanceWindow

ejemplo:

curl -k -X POST -d '{"ticketId": "a5fe99c-d914-4bda-9332-307384fe40bf","ttl": "20","engines": ["ANOMALY"],"sensorIds": ["5","3"],"subnets": ["10.0.0.0/16"]}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/maintenanceWindow

BORRAR

Cierra una ventana de mantenimiento existente.

Parámetros de consulta:

Nombre	Descripción	Ejemplo	Obligatorio/Opcional
ticketId	Define el identificador de vale de mantenimiento en los sistemas del usuario. Asegúrese de que el identificador de vale esté vinculado a una ventana abierta existente.	2987345p98234	Obligatorio

códigos de error:

Código	Mensaje	Descripción
de 200 (correcto)	-	La acción se completó correctamente.
400 (solicitud incorrecta)	No TicketId	Falta el parámetro ticketId de la solicitud.
404 (no encontrado):	No se encontró la ventana de mantenimiento.	El identificador de vale no está vinculado a una ventana de mantenimiento abierta.
500 (error interno del servidor)	-	Cualquier otro error inesperado.

comando cURL

tipo: DELETE

de API de :

curl -k -X DELETE -d '{"ticketId": "<TICKET_ID>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP address>/external/v1/maintenanceWindow

ejemplo:

curl -k -X DELETE -d '{"ticketId": "a5fe99c-d914-4bda-9332-307384fe40bf"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/maintenanceWindow

OBTENER

Recupere un registro de todos los abiertos (POST), cierre (DELETE) y actualice (PUT) que se realizaron con esta API para controlar las ventanas de mantenimiento. T

Parámetros de consulta:

Nombre	Descripción	Ejemplo	Obligatorio/Opcional
fromDate	Filtra los registros de la fecha predefinida y versiones posteriores. El formato es YYYY-MM-DD.	2022-08-10	Opcional
toDate	Filtra los registros hasta la fecha predefinida. El formato es YYYY-MM-DD.	2022-08-10	Opcional
ticketId	Filtra los registros relacionados con un identificador de vale específico.	9a5fe99c-d914-4bda-9332-307384fe40bf	Opcional
tokenName	Filtra los registros relacionados con un nombre de token específico.	ventana trimestral	Opcional

códigos de error:

Código	Mensaje	Descripción
200	De acuerdo	La acción se completó correctamente.
204:	Sin contenido	No hay datos que mostrar.
400	Solicitud incorrecta	El formato de fecha es incorrecto.
500	Error interno del servidor	Cualquier otro error inesperado.

tipo: JSON

Matriz de objetos JSON que representan operaciones de ventana de mantenimiento.

estructura de respuesta:

Nombre	Tipo	Admite valores NULL/No acepta valores NULL	Lista de valores
de identificador de	Entero largo	No acepta valores NULL	Un identificador interno para el registro actual
dateTime	Cuerda	No acepta valores NULL	Hora en que se produjo la actividad, por ejemplo: 2022-04-23T18:25:43.511Z
ticketId	Cuerda	No acepta valores NULL	Identificador de la ventana de mantenimiento. Por ejemplo: 9a5fe99c-d914-4bda-9332-307384fe40bf
tokenName	Cuerda	No acepta valores NULL	Nombre del token de la ventana de mantenimiento. Por ejemplo: quarterly-sanity-window
motores de	Matriz de cadenas	Nullable	Motores en los que se aplica la ventana de mantenimiento, tal como se proporciona durante la creación de la ventana de mantenimiento: Protocol Violation, Policy Violation, Malware, Anomalyo Operational
sensorIds	Matriz de cadenas	Nullable	Los sensores en los que se aplica la ventana de mantenimiento, tal como se proporciona durante la creación de la ventana de mantenimiento.
subredes	Matriz de cadenas	Nullable	Subredes en las que se aplica la ventana de mantenimiento, tal como se proporciona durante la creación de la ventana de mantenimiento.
ttl	Numérico	Nullable	Período de vida (TTL) de la ventana de mantenimiento, tal como se proporciona durante la creación o actualización de la ventana de mantenimiento.
operationType	Cuerda	No acepta valores NULL	Uno de los siguientes valores: OPEN, UPDATEy CLOSE

comando cURL

tipo: GET

de API de :

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/external/v1/maintenanceWindow?fromDate=&toDate=&ticketId=&tokenName='

ejemplo:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/external/v1/maintenanceWindow?fromDate=2020-01-01&toDate=2020-07-14&ticketId=a5fe99c-d914-4bda-9332-307384fe40bf&tokenName=a'

PONER

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

Este método es útil cuando desea 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 ttl a 120 minuto para restablecer el recuento de duración.

Parámetros de consulta:

Nombre	Descripción	Ejemplo	Obligatorio/Opcional
ticketId	Cuerda. Define el identificador de vale de mantenimiento en los sistemas del usuario.	2987345p98234	Obligatorio
ttl	Entero positivo. Define la duración de la ventana en minutos.	210	Obligatorio

códigos de error:

Código	Mensaje	Descripción
de 200 (correcto)	-	La acción se completó correctamente.
400 (solicitud incorrecta)	No TicketId	Falta un valor de ticketId la solicitud.
400 (solicitud incorrecta)	TTL no válido	El TTL definido no es numérico o no es un entero positivo.
400 (solicitud incorrecta)	No se pudo analizar la solicitud	Falta un valor de parámetro ttl solicitud.
404 (no encontrado)	Ventana de mantenimiento no encontrada	El identificador de vale no está vinculado a una ventana de mantenimiento abierta.
500 (error interno del servidor)	-	Cualquier otro error inesperado.

comando cURL

Tipo: PUT

de API de :

curl -k -X PUT -d '{"ticketId": "<TICKET_ID>",ttl": "<TIME_TO_LIVE>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP address>/external/v1/maintenanceWindow

ejemplo:

curl -k -X PUT -d '{"ticketId": "a5fe99c-d914-4bda-9332-307384fe40bf","ttl": "20"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/maintenanceWindow

pcap (Solicitud de alerta PCAP)

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

URI: /external/v2/alerts/

OBTENER

Parámetros de consulta:

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

tipo: JSON

Cadena de mensaje con los detalles del estado de la operación:

Código de estado	Mensaje	Descripción
de 200 (correcto)	-	Objeto JSON con datos sobre el archivo PCAP solicitado. Para obtener más información, vea Campos de datos.
500 (error interno del servidor)	No se encontró la alerta	El identificador de alerta proporcionado no se encontró en la consola de administración local.
500 (error interno del servidor)	Error al obtener el token para el identificador de xsense <number>	Error al obtener el token del sensor para el identificador de sensor especificado.
500 (error interno del servidor)	-	Cualquier otro error inesperado.

Campos de datos

Nombre	Tipo	Admite valores NULL/No acepta valores NULL	Lista de valores
de identificador de	Numérico	No acepta valores NULL	Identificador de alerta de la consola de administración local
xsenseId	Numérico	No acepta valores NULL	El identificador del sensor
xsenseAlertId	Numérico	No acepta valores NULL	Identificador de alerta de la consola del sensor
downloadUrl	Cuerda	No acepta valores NULL	Dirección URL usada para descargar el archivo PCAP
de token de	Cuerda	No acepta valores NULL	Token del sensor, que se va a usar al descargar el archivo PCAP

Ejemplo de respuesta: Correcto

{
  "downloadUrl": "https://10.1.0.2/api/v2/alerts/pcap/1",
  "xsenseId": 1,
  "token": "d2791f58-2a88-34fd-ae5c-2651fe30a63c",
  "id": 1,
  "xsenseAlertId": 1
}

Ejemplo de respuesta: Error

{
  "error": "alert not found"
}

comando cURL

tipo: GET

API de

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/external/v2/alerts/pcap/<ID>'

* ejemplo:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://10.1.0.1/external/v2/alerts/pcap/1'

Pasos siguientes

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