Referencia de la API de administración de alertas para sensores de supervisión de OT

Artículo
06/01/2023

En este artículo se enumeran las API de REST de administración de alertas compatibles con los sensores de supervisión de OT de Microsoft Defender para IoT.

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

Use esta API para solicitar una lista de todas las alertas que ha detectado el sensor de Defender para IoT.

URI:/api/v1/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`	`/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>`	Opcionales
toTime	Obtenga alertas creadas únicamente antes de un momento dado, en milisegundos desde la hora de época y en la zona horaria UTC.	`/api/v1/alerts?toTime=<epoch>`	Opcionales
type	Obtenga alertas de un tipo específico únicamente. Valores admitidos: - `unexpected new devices` - `disconnections` Se ignorará al resto de los otros valores.	`/api/v1/alerts?type=disconnections`	Opcionales

Tipo: JSON

Lista de alertas con los siguientes campos:

Nombre	Tipo	Que admite valores NULL / No admite valores NULL	Lista de valores
Id	Numeric	No acepta valores NULL	-
time	Numeric	No acepta valores NULL	Milisegundos desde la hora de época, en zona horaria UTC
title	String	No acepta valores NULL	-
message	String	No acepta valores NULL	-
severity	String	No acepta valores NULL	`Warning`, `Minor`, `Major` o `Critical`
engine	String	No acepta valores NULL	`Protocol Violation`, `Policy Violation`, `Malware`, `Anomaly` o `Operational`
sourceDevice	Numeric	Nullable	Id. de dispositivo
destinationDevice	Numeric	Nullable	Id. de dispositivo
additionalInformation	Objeto Additional information	Nullable	-

Campos de información adicional

Nombre	Tipo	Que admite valores NULL / No admite valores NULL	Lista de valores
description	String	No acepta valores NULL	-
information	Matriz JSON	No acepta valores NULL	String

Se agregó para V2:

Nombre	Tipo	Que admite valores NULL / No admite valores NULL	Lista de valores
sourceDeviceAddress	String	Nullable	Dirección IP o MAC
destinationDeviceAddress	String	Nullable	Dirección IP o MAC
remediationSteps	Matriz JSON	No acepta valores NULL	Cadenas, pasos para la corrección descritos en la alerta

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

Ejemplo de respuesta

[
    {
        "engine": "Policy Violation",
        "severity": "Major",
        "title": "Internet Access Detected",
        "additionalinformation": {
            "information": [
                "170.60.50.201 over port BACnet (47808)"
            ],
            "description": "External Addresses"
        },
        "sourceDevice": null,
        "destinationDevice": null,
        "time": 1509881077000,
        "message": "Device 192.168.0.13 tried to access an external IP address which is an address in the Internet and is not allowed by policy. It is recommended to notify the security officer of the incident.",
        "id": 1
    },
    {
        "engine": "Protocol Violation",
        "severity": "Major",
        "title": "Illegal MODBUS Operation (Exception Raised by Master)",
        "sourceDevice": 3,
        "destinationDevice": 4,
        "time": 1505651605000,
        "message": "A MODBUS master 192.168.110.131 attempted to initiate an illegal operation.\nThe operation is considered to be illegal since it incorporated function code \#129 which should not be used by a master.\nIt is recommended to notify the security officer of the incident.",
        "id": 2,
        "additionalInformation": null,
    }
]

Tipo: GET

API:

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/api/v1/alerts?state=<STATE>&fromTime=<FROM_TIME>&toTime=<TO_TIME>&type=<TYPE>'

Ejemplo:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/api/v1/alerts?state=unhandled&fromTime=1594550986000&toTime=1594550986001&type=disconnections'

eventos (Recuperación de los eventos de escala de tiempo)

Use esta API para solicitar una lista de los eventos informados a la escala de tiempo del evento.

Nota

La ejecución de la API idéntica dentro de la misma hora, con los mismos valores de parámetro, devuelve un valor almacenado en caché. Si ejecuta esta API dos veces en una hora, se recomienda modificar los parámetros de consulta para obtener una respuesta actualizada.

URI:/api/v1/events

GET

Parámetros de consulta

Nombre	Descripción	Ejemplo	Obligatorio u opcional
minutesTimeFrame	Filtre los resultados según un período de tiempo determinado durante el cual se notificaron los eventos. Se define hacia atrás desde la hora actual. Máximo = `4320` (3 días). Cualquier valor mayor se trata como 4320, sin ningún error	`/api/v1/events?minutesTimeFrame=20`	Opcional
type	Filtre solo los resultados de un tipo específico. Se omite cualquier valor distinto de los tipos admitidos. Para obtener más información, consulte Evento `type` y `title`referencia.	`/api/v1/events?type=DEVICE_CONNECTION_CREATED` `/api/v1/events?type=REMOTE_ACCESS&minutesTimeFrame`	Opcionales

Tipo: JSON

Matriz de objetos JSON que representan los últimos 100 eventos, ordenados por marca de tiempo de evento, con el evento más reciente primero.

Entre los campos de evento se incluyen:

Nombre	Tipo	Que admite valores NULL / No admite valores NULL	Lista de valores
timestamp	Numeric	No acepta valores NULL	Milisegundos desde la hora de época, en zona horaria UTC
type	String	No acepta valores NULL	Uno de los tipos admitidos
title	String	No acepta valores NULL	Uno de los títulos admitidos
severity	String	No acepta valores NULL	`INFO`, `NOTICE`o `ALERT`
owner	String	Nullable	Cadena Si el evento se creó manualmente, este campo incluirá el nombre del usuario que creó el evento.
content	String	No acepta valores NULL	Cadena que describe el evento.

Ejemplo de respuesta

[
    {
        "severity": "INFO",
        "title": "Back to Normal",
        "timestamp": 1504097077000,
        "content": "Device 10.2.1.15 was found responsive, after being suspected as disconnected",
        "owner": null,
        "type": "BACK_TO_NORMAL"
    },
    {
        "severity": "ALERT",
        "title": "Alert Detected",
        "timestamp": 1504096909000,
        "content": "Device 10.2.1.15 is suspected to be disconnected (unresponsive).",
        "owner": null,
        "type": "ALERT_REPORTED"
    },
    {
        "severity": "ALERT",
        "title": "Alert Detected",
        "timestamp": 1504094446000,
        "content": "A DNP3 Master 10.2.1.14 attempted to initiate a request which is not allowed by policy.\nThe policy indicates the allowed function codes, address ranges, point indexes and time intervals.\nIt is recommended to notify the security officer of the incident.",
        "owner": null,
        "type": "ALERT_REPORTED"
    },
    {
        "severity": "NOTICE",
        "title": "PLC Program Update",
        "timestamp": 1504094344000,
        "content": "Program update detected, sent from 10.2.1.25 to 10.2.1.14",
        "owner": null,
        "type": "PROGRAM_DEVICE"
    }
]

Tipo: GET

API:

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/api/v1/events?minutesTimeFrame=<TIME_FRAEM>&type=<TYPE>'

Ejemplo:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/api/v1/events?minutesTimeFrame=20&type=DEVICE_CONNECTION_CREATED'`

Evento `type` y referencia `title`

En esta sección se enumeran los valores admitidos como valores de tipo y título de evento para la API de eventos.

Tipo de evento	Título del evento
DEVICE_CREATE	Dispositivo detectado
DEVICE_UPDATE	Dispositivo actualizado
ALERT_REPORTED	Alerta detectada
ALERT_UPDATED	Alerta actualizada
SCAN	Examen del dispositivo detectado
PROGRAM_DEVICE	Programación PLC
MMS_PROGRAM_DEVICE	Actualización del programa PLC
SCL_UPLOADED	SCL cargada
EXCLUSION_RULE_CREATED	Regla de exclusión creada
EXCLUSION_RULE_REMOVED	Regla de exclusión eliminada
EXCLUSION_RULE_UPDATED	Regla de exclusión actualizada
DEVICE_CONNECTION_CREATED	Conexión de dispositivo detectada
USER_LOGIN	Intento de inicio de sesión de usuario
FILE_TRANSFER	Transferencia de archivos detectada
CUSTOM_EVENT	Evento definido por el usuario
REMOTE_ACCESS	Conexión de acceso remoto establecida
BACK_TO_NORMAL	Volver al estado normal
MMS_MEMORY_BLOCK_OPERATION	Operación de bloque de memoria MMS
MMS_PROGRAM_OPERATION	Operación del programa MMS
HTTP_BASIC_AUTHENTICATION	Autenticación HTTP Basic
SIEMENS_S_7_MEMORY_BLOCK_OPERATION	Operación de bloque de memoria Siemens S7
SIEMENS_S_7_AUTHENTICATION	Autenticación de Siemens S7
REPORT_CREATED	Informe creado
SNMP_TRAP	Captura SNMP detectada
DATABASE_ACTION	Manipulación de la estructura de la base de datos
PLC_MODULE_CHANGE	Cambio de módulo PLC
FIRMWARE_UPDATE	Actualización de firmware
PLC_START	Inicio de PLC
SRTP_PLC_RESET	Restablecimiento de PLC
SRTP_PLC_COPY_FIRMWARE	Actualización de firmware
SRTP_LOGIN_PROGRAMMING	Conjunto de modo de programación PLC
SRTP_PLC_CHANGE_PASSWORD	Cambio de contraseña de PLC
OPC_DATA_ACCESS_GROUP_MANAGEMENT_OPERATION	Operación de administración de grupos de acceso a datos de OPC
OPC_DATA_ACCESS_ITEM_MANAGEMENT_OPERATION	Operación de administración de elementos de acceso a datos de OPC
OPC_DATA_ACCESS_IO_SUBSCRIPTION_MANAGEMENT_OPERATION	Operación de administración de suscripciones de E/S de acceso a datos de OPC
OPC_AE_EVENT_SUBSCRIPTION	Suscripción a eventos de OPC AE
OPC_AE_EVENT_CONDITION_MANAGEMENT_OPERATION	Operación de administración de condiciones de eventos de OPC AE
OPC_AE_EVENT	Evento OPC AE
SRTP_CHANGE_PRIVILEGE	Cambio del nivel de acceso de PLC
SRTP_CHANGE_LEVEL_FAILED	Error en el nivel de acceso de cambio de PLC
SUITELINK_INIT_CONNECTION	Sesión de Wonderware inicializada
USER_OPERATION	Operación de usuario
DIP_UPLOADED	Paquete de inteligencia de datos cargado
FTP_AUTHENTICATION_FAILURE	Error de autenticación FTP
PROFINET_DPC_VALUE_SET	Operación SET de Profinet
S7PLUS_PLC_MODE_CHANGE	Cambio del modo PLC
S7_PLC_MODE_CHANGE	Cambio del modo PLC
DELETE_DEVICE	Dispositivo eliminado
S7PLUS_PROGRAMMING	Programación PLC
FIRMWARE_CHANGED	Cambio de firmware de PLC
DELTAV_PROGRAMMING	Script de instalación de DeltaV
USER_DEFINED_RULE_CREATED	Regla definida por el usuario creada
USER_DEFINED_RULE_EDITED	Regla definida por el usuario editada
USER_DEFINED_RULE_DELETED	Regla definida por el usuario eliminada
USER_DEFINED_RULE_OPERATION	Operación de regla definida por el usuario
REMOTE_PROCESS_EXECUTION	Ejecución remota de procesos
DEVICE_UNIFICATION	Dispositivo actualizado
NOTIFICATION	La notificación se resolvió manualmente
ENIP_CONTROLLER_PROGRAM_DELETE	Eliminación del programa controlador
ENIP_CONTROLLER_PROGRAM_RESET	Restablecimiento del programa de controlador
ENIP_CONTROLLER_GENERIC_RESET	Restablecimiento del controlador
ENIP_CONTROLLER_GENERIC_STOP	Detención del controlador
ENIP_CONTROLLER_GENERIC_START	Inicio del controlador
TELNET_AUTHENTICATION_FAILURE	Error de autenticación de Telnet
CONFIGURATION_OF_CLEARTEXT_PASSWORD	Configuración de la contraseña
CLEARTEXT_AUTHENTICATION	Autenticación de texto no cifrado
PROGRAM_UPLOAD_DEVICE	Carga de programas PLC
CONFIGURATION_CHANGE	Escritura de configuración de PLC
CONFIGURATION_READ	Lectura de configuración de PLC
SYSLOG_MSG	Mensaje de Syslog
INTERNET_ACCESS	Acceso a Internet
CAMP_MEMORY_WRITE_OPERATION	Operación común de escritura de memoria del protocolo de mensajes ASCII
MUTED_ALERT	Evento detectado y silenciado
DHCP_UPDATE	Actualización de direcciones
DIP_FAILURE	Error de instalación del paquete de inteligencia de datos
DELETE_DEVICE_SCHEDULE	Dispositivos inactivos programados para su eliminación
PLC_OPERATING_MODE_CHANGED	Se detectó un cambio en el modo de funcionamiento de PLC
HARDWARE_UPDATE_BY_IDENTIFIER	Actualización de direcciones

Pasos siguientes

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

Compartir a través de

Referencia de la API de administración de alertas para sensores de supervisión de OT

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

GET

Parámetros de consulta

Campos de información adicional

Ejemplo de respuesta

eventos (Recuperación de los eventos de escala de tiempo)

GET

Parámetros de consulta

Ejemplo de respuesta

Evento `type` y referencia `title`

Pasos siguientes

Comentarios

Recursos adicionales

Compartir a través de

Referencia de la API de administración de alertas para sensores de supervisión de OT

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

GET

Parámetros de consulta

eventos (Recuperación de los eventos de escala de tiempo)

GET

Parámetros de consulta

Evento type y referencia title

Pasos siguientes

Comentarios

Recursos adicionales

Evento `type` y referencia `title`