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

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

Los datos incluidos en las respuestas de la API incluyen la misma información que si generó un informe de vulnerabilidades desde la consola del sensor de OT.

dispositivos (Recuperar información de vulnerabilidad del dispositivo)

Use esta API para solicitar los resultados de la evaluación de vulnerabilidades de cada dispositivo.

URI:/api/v1/reports/vulnerabilities/devices

GET

Solicitud

Se llama a esta API sin parámetros de solicitud.

Respuesta

Tipo: JSON

Matriz de objetos JSON que representan dispositivos evaluados y sus vulnerabilidades notificadas.

Los dispositivos que no tienen vulnerabilidades no se incluyen en la respuesta del resultado.

Campos de dispositivo

Nombre	Tipo	Que admite valores NULL / No admite valores NULL	Lista de valores
name	String	No acepta valores NULL	-
ipAddresses	Matriz JSON	No acepta valores NULL	-
securityScore	Numeric	No acepta valores NULL	-
vendor	String	Nullable
firmwareVersion	String	Nullable	-
model	String	Nullable	-
isWirelessAccessPoint	Boolean	No acepta valores NULL	True o False
operatingSystem	Objeto Operating system	Nullable	-
vulnerabilities	Objeto Vulnerabilities	No acepta valores NULL	-

Campos del sistema operativo

Nombre	Tipo	Que admite valores NULL / No admite valores NULL	Lista de valores
name	String	No acepta valores NULL	-
type	String	No acepta valores NULL	-
version	String	Nullable	-
latestVersion	String	Nullable	-

Campos de vulnerabilidades

Nombre	Tipo	Que admite valores NULL / No admite valores NULL	Lista de valores
antiViruses	Matriz JSON de cadenas	Nullable	Nombres de antivirus
plainTextPasswords	Matriz JSON	Nullable	Objetos Password
remoteAccess	Matriz JSON	Nullable	Objetos Remote access
isBackupServer	Boolean	No acepta valores NULL	True o False
openedPorts	Matriz JSON	Nullable	Objetos Opened port
isEngineeringStation	Boolean	No acepta valores NULL	True o False
isKnownScanner	Boolean	No acepta valores NULL	True o False
cves	Matriz JSON	Nullable	Objetos CVE
isUnauthorized	Boolean	No acepta valores NULL	True o False
malwareIndicationsDetected	Boolean	No acepta valores NULL	True o False
weakAuthentication	Matriz JSON de cadenas	Nullable	Aplicaciones detectadas que usan una autenticación débil

Campos de contraseña

Nombre	Tipo	Que admite valores NULL / No admite valores NULL	Lista de valores
password	String	No acepta valores NULL	-
protocolo	String	No acepta valores NULL	-
strength	String	No acepta valores NULL	Very weak, Weak, , Medium, Strong

Campos de acceso remoto

Nombre	Type	Nullable	Lista de valores
port	Numeric	No acepta valores NULL	-
transport	String	No acepta valores NULL	TCP, UDP
client	String	No acepta valores NULL	Dirección IP
clientSoftware	String	No acepta valores NULL	Nombre del protocolo remoto, como SSH, VNC, Remote desktop o Team viewer

Campos de puerto abierto

Nombre	Tipo	Que admite valores NULL / No admite valores NULL	Lista de valores
port	Numeric	No acepta valores NULL	-
transport	String	No acepta valores NULL	TCP o UDP
protocolo	String	Nullable	-
isConflictingWithFirewall	Boolean	No acepta valores NULL	True o False

Campos de CVE

Nombre	Tipo	Que admite valores NULL / No admite valores NULL	Lista de valores
id	String	No acepta valores NULL	-
score	Valor numérico, decimal	No acepta valores NULL	-
description	String	No acepta valores NULL	-

Ejemplo de respuesta

[
    {
        "name": "IED \#10",
        "ipAddresses": ["10.2.1.10"],
        "securityScore": 100,
        "vendor": "ABB Switzerland Ltd, Power Systems",
        "firmwareVersion": null,
        "model": null,
        "operatingSystem": {
            "name": "ABB Switzerland Ltd, Power Systems",
            "type": "abb",
            "version": null,
            "latestVersion": null
        },
        "vulnerabilities": {
        "antiViruses": [
        "McAfee"
        ],
        "plainTextPasswords": [
            {
                "password": "123456",
                "protocol": "HTTP",
                "strength": "Very Weak"
            }
        ],
        "remoteAccess": [
            {
                "port": 5900,
                "transport": "TCP",
                "clientSoftware": "VNC",
                "client": "10.2.1.20"
            }
        ],
        "isBackupServer": true,
        "openedPorts": [
            {
                "port": 445,
                "transport": "TCP",
                "protocol": "SMP Over IP",
                "isConflictingWithFirewall": false
            },
            {
                "port": 80,
                "transport": "TCP",
                "protocol": "HTTP",
                "isConflictingWithFirewall": false
            }
        ],
        "isEngineeringStation": false,
        "isKnownScanner": false,
        "cves": [
            {
                "id": "CVE-2015-6490",
                "score": 10,
                "description": "Frosty URL - Stack-based buffer overflow on Allen-Bradley MicroLogix 1100 devices before B FRN 15.000 and 1400 devices through B FRN 15.003 allows remote attackers to execute arbitrary code via unspecified vectors"
            },
            {
                "id": "CVE-2012-6437",
                "score": 10,
                "description": "MicroLogix 1100 and 1400 do not properly perform authentication for Ethernet firmware updates, which allows remote attackers to execute arbitrary code via a Trojan horse update image"
            },
            {
                "id": "CVE-2012-6440",
                "score": 9.3,
                "description": "MicroLogix 1100 and 1400 allows man-in-the-middle attackers to conduct replay attacks via HTTP traffic."
            }
        ],
        "isUnauthorized": false,
        "malwareIndicationsDetected": true
        }
    }
]

Comando cURL

Tipo: GET

API:

curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/reports/vulnerabilities/devices

Ejemplo:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/reports/vulnerabilities/devices

seguridad (Recuperación de vulnerabilidades de seguridad)

Use esta API para solicitar los resultados de un informe de evaluación de vulnerabilidades general. Esta evaluación proporciona información sobre el nivel de seguridad del sistema.

Esta evaluación se basa en la información general del sistema y de la red, y no en la valoración de un dispositivo específico.

URI:/api/v1/reports/vulnerabilities/security

GET

Solicitud

Se llama a esta API sin parámetros de solicitud.

Respuesta

Tipo: representación JSON de una o varias tablas de datos, cada una con estructuras específicas y potencialmente diferentes.

La respuesta se muestra en una vista de mapa, que asigna títulos de tabla a filas de tabla. Las filas se representan como una lista de objetos con las mismas estructuras.

unauthorizedDevices fields

Nombre	Tipo	Que admite valores NULL / No admite valores NULL	Lista de valores
address	String	Nullable	Dirección IP o MAC del dispositivo no autorizado
name	String	Nullable	Nombre del dispositivo no autorizado
firstDetectionTime	Numeric	Nullable	Marca de tiempo en la que el dispositivo fue detectado por primera vez, en milisegundos desde la hora de época y en la zona horaria UTC
lastSeen	Numeric	Nullable	Marca de tiempo en la que el tráfico se detectó por última vez como enviado al dispositivo o desde este, en milisegundos desde la hora de época y en la zona horaria UTC

illegalTrafficByFirewallRules fields

Nombre	Tipo	Que admite valores NULL / No admite valores NULL	Lista de valores
servidor	String	Nullable	Dirección IP del servidor
client	String	Nullable	Dirección IP de cliente
port	Numeric	Nullable	Puerto del servidor
transport	String	Nullable	TCP, UDPo ICMP

weakFirewallRules fields

Nombre	Tipo	Que admite valores NULL / No admite valores NULL	Lista de valores
sources	Matriz JSON de fuentes	Nullable	Matriz JSON de orígenes en cualquiera de los siguientes formatos: - Any - ip address (host) - from ip-to ip (RANGE) - ip address, subnet mask (NETWORK)
destinations	Matriz JSON de destinos	Nullable	Matriz JSON de objetos de destino, en cualquiera de los siguientes formatos: - Any - ip address (host) - from ip-to ip (RANGE) - ip address, subnet mask (NETWORK)
ports	Matriz JSON de puertos	Nullable	Matriz JSON de objetos de puerto, en cualquiera de los siguientes formatos: - Any - port (protocol, if detected) - from port-to port (protocol, if detected)

campos accessPoints

Nombre	Tipo	Que admite valores NULL / No admite valores NULL	Lista de valores
macAddress	String	Nullable	Dirección MAC del punto de acceso
vendor	String	Nullable	Nombre del proveedor del punto de acceso
ipAddress	String	Nullable	Dirección IP del punto de acceso o N/A
name	String	Nullable	Nombre del dispositivo del punto de acceso o N/A
wireless	String	Nullable	Si el punto de acceso está conectado a una red inalámbrica: No, Suspected o Yes

connectionsBetweenSubnets fields

Nombre	Tipo	Que admite valores NULL / No admite valores NULL	Lista de valores
servidor	String	Nullable	Dirección IP del servidor
client	String	Nullable	Dirección IP del cliente

industrialMalwareIndicators fields

Nombre	Tipo	Que admite valores NULL / No admite valores NULL	Lista de valores
detectionTime	Numeric	Nullable	Marca de tiempo en la que el malware fue detectado por primera vez, en milisegundos desde la hora de época y en la zona horaria UTC
alertMessage	String	Nullable	Mensaje de alerta enviado
description	String	Nullable	Descripción del mensaje de alerta
devices	Matriz JSON	No acepta valores NULL	Matriz JSON de cadenas que representan nombres de dispositivo

internetConnections fields

Nombre	Tipo	Que admite valores NULL / No admite valores NULL	Lista de valores
internalAddress	String	Nullable	Dirección IP interna de la conexión
autorizado	Boolean	Nullable	Yes o No
externalAddresses	Matriz JSON	No acepta valores NULL	Matriz JSON de las direcciones IP externas de la conexión

Ejemplo de respuesta

{
    "unauthorizedDevices": [
        {
            "address": "10.2.1.14",
            "name": "PLC \#14",
            "firstDetectionTime": 1462645483000,
            "lastSeen": 1462645495000,
        }
    ],
    "redundantFirewallRules": [
        {
            "sources": "170.39.3.0/255.255.255.0",
            "destinations": "Any",
            "ports": "102"
        }
    ],
    "connectionsBetweenSubnets": [
        {
            "server": "10.2.1.22",
            "client": "170.39.2.0"
        }
    ],
    "industrialMalwareIndications": [
        {
            "detectionTime": 1462645483000,
            "alertMessage": "Suspicion of Malicious Activity (Regin)",
            "description": "Suspicious network activity was detected. Such behavior might be attributed to the Regin malware.",
            "addresses": [
                "10.2.1.4",
                "10.2.1.5"
            ]
        }
    ],
    "illegalTrafficByFirewallRules": [
        {
            "server": "10.2.1.7",
            "port": "20000",
            "client": "10.2.1.4",
            "transport": "TCP"
        },
        {
            "server": "10.2.1.8",
            "port": "20000",
            "client": "10.2.1.4",
            "transport": "TCP"
        },
        {
            "server": "10.2.1.9",
            "port": "20000",
            "client": "10.2.1.4",
            "transport": "TCP"
        }
    ],
    "internetConnections": [
        {
            "internalAddress": "10.2.1.1",
            "authorized": "Yes",
            "externalAddresses": ["10.2.1.2",”10.2.1.3”]
        }
    ],
    "accessPoints": [
        {
            "macAddress": "ec:08:6b:0f:1e:22",
            "vendor": "TP-LINK TECHNOLOGIES",
            "ipAddress": "173.194.112.22",
            "name": "Enterprise AP",
            "wireless": "Yes"
        }
    ],
    "weakFirewallRules": [
        {
            "sources": "170.39.3.0/255.255.255.0",
            "destinations": "Any",
            "ports": "102"
        }
    ]
}

Comando cURL

Tipo: GET

API:

curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/reports/vulnerabilities/security

Ejemplo:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/reports/vulnerabilities/security

operacional (Recuperar vulnerabilidades operativas)

Use esta API para solicitar los resultados de una evaluación de vulnerabilidades general. Esta evaluación ofrece conclusiones sobre el estado operativo de la red. Se basa en la información general del sistema y de la red, y no en la valoración de un dispositivo específico.

URI:/api/v1/reports/vulnerabilities/operational

GET

Solicitud

Se llama a esta API sin parámetros de solicitud.

Respuesta

Tipo: representación JSON de una o varias tablas de datos, cada una con estructuras específicas y potencialmente diferentes.

La respuesta se muestra en una vista de mapa, que asigna títulos de tabla a filas de tabla. Las filas se representan como una lista de objetos con las mismas estructuras.

campos de resultados backupServer

Nombre	Tipo	Que admite valores NULL / No admite valores NULL	Lista de valores
de origen	String	Nullable	La dirección IP de origen
destination	String	Nullable	La dirección IP de destino
port	Numeric	Nullable	Puerto del servidor de copia de seguridad
transport	String	Nullable	Protocolo de transporte del servidor de copia de seguridad TCP o UDP
backupMaximalInterval	String	Nullable	El tiempo máximo de intervalo entre las copias de seguridad
lastSeenBackup	Numeric	Nullable	Marca de tiempo en la que se vio por última vez una copia de seguridad, en milisegundos de la hora de época y en la zona horaria UTC

Campos de resultados de ipNetworks

Nombre	Tipo	Que admite valores NULL / No admite valores NULL	Lista de valores
addresses	Numeric	No acepta valores NULL	Número de direcciones IP detectadas en el intervalo de subredes.
network	String	No acepta valores NULL	Dirección IP base de subred.
mask	String	No acepta valores NULL	Máscara de subred.

campos de resultados protocolProblems

Nombre	Tipo	Que admite valores NULL / No admite valores NULL	Lista de valores
protocolo	String	No acepta valores NULL	Protocolo para el que se desencadenó una alerta de infracción de protocolo
addresses	Matriz JSON de direcciones IP	No acepta valores NULL	Matriz JSON de direcciones IP donde se originó la infracción
alert	String	No acepta valores NULL	El título de la alerta desencadenó
reportTime	Numeric	No acepta valores NULL	Marca de tiempo en la que se generó por última vez un informe, en milisegundos de la hora de época y en la zona horaria UTC

campos de resultado protocolDataVolumes

Nombre	Tipo	Que admite valores NULL / No admite valores NULL	Lista de valores
protocolo	String	Nullable	Protocolo detectado en la red por el sensor de red de OT
volume	String	Nullable	Volumen de paquetes de protocolo capturados por el sensor de red de OT, en MB

Campos de resultados de desconexiones

Nombre	Tipo	Que admite valores NULL / No admite valores NULL	Lista de valores
assetAddress	String	Nullable	Dirección IP del recurso desconectado
assetName	String	Nullable	Nombre del recurso desconectado
lastDetectionTime	Numeric	Nullable	Marca de tiempo en la que se detectó por última vez la desconexión, en milisegundos de la hora de época y en la zona horaria UTC
backToNormalTime	Numeric	Nullable	Marca de tiempo en la que volvió la conexión, en milisegundos de la hora de época y en la zona horaria UTC

Ejemplo de respuesta

{
    "backupServer": [
        {
            "backupMaximalInterval": "1 Hour, 29 Minutes",
            "source": "10.2.1.22",
            "destination": "170.39.2.14",
            "port": 10000,
            "transport": "TCP",
            "lastSeenBackup": 1462645483000
        }
    ],
    "ipNetworks": [
        {
            "addresses": "21",
            "network": "10.2.1.0",
            "mask": "255.255.255.0"
        },
        {
            "addresses": "3",
            "network": "170.39.2.0",
            "mask": "255.255.255.0"
        }
    ],
    "protocolProblems": [
        {
            "protocol": "DNP3",
            "addresses": [
                "10.2.1.7",
                "10.2.1.8"
            ],
            "alert": "Illegal DNP3 Operation",
            "reportTime": 1462645483000
        },
        {
            "protocol": "DNP3",
            "addresses": [
                "10.2.1.15"
            ],
            "alert": "Master Requested an Application Layer Confirmation",
            "reportTime": 1462645483000
        }
    ],
    "protocolDataVolumes": [
        {
            "protocol": "MODBUS (502)",
            "volume": "21.07 MB"
        },
        {
            "protocol": "SSH (22)",
            "volume": "0.001 MB"
        }
    ],
    "disconnections": [
        {
            "assetAddress": "10.2.1.3",
            "assetName": "PLC \#3",
            "lastDetectionTime": 1462645483000,
            "backToNormalTime": 1462645484000
        }
    ]
}

Comando cURL

Tipo: GET

API:

curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/reports/vulnerabilities/operational

Ejemplo:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/reports/vulnerabilities/operational

mitigación (recuperar pasos de mitigación)

Utilice esta API para solicitar una evaluación de mitigación. Esta evaluación proporciona pasos recomendados para mitigar las vulnerabilidades detectadas. Se basa en la información general del sistema y de la red, y no en la valoración de un dispositivo específico.

URI:/api/v1/reports/vulnerabilities/mitigation

GET

Solicitud

Se llama a esta API sin parámetros de solicitud.

Respuesta

Tipo: JSON

Objeto JSON que representa los pasos de mitigación recomendados.

Campos de respuesta

Nombre del campo	Tipo	Nullable	Lista de valores
notifications	Matriz JSON de cadenas	No acepta valores NULL	Pasos de mitigación recomendados para las vulnerabilidades detectadas
Mitigación	Matriz JSON	No acepta valores NULL	objetos de mitigación

campos de mitigación

Nombre del campo	Tipo	Nullable	Lista de valores
content	String	No acepta valores NULL	Pasos de mitigación recomendados para las vulnerabilidades detectadas
scoreImprovement	Entero	Nullable	Porcentaje esperado de mejora de la seguridad después de realizar los pasos de mitigación.
details	Tabla	Nullable	Una tabla que enumera las recomendaciones de mitigación, como se generaría en el informe evaluación de riesgos. Cada recomendación incluye detalles sobre el posible impacto en la seguridad si se realiza la acción y mucho más. Para más información, consulte Mitigación de riesgos.

Nota

Es posible que tenga varios pasos de mitigación, con algunos devueltos en el campo notifications y otros devueltos en el campo mitigation. Los elementos con datos scoreImprovement y details solo se devuelven en el campo mitigation. Los elementos sin datos scoreImprovement y details solo se devuelven en el campo notifications.

Ejemplo de respuesta

{
    "notifications": ["Firewall policy import", "Marking \"important devices\"", "Further device information import"],
    "mitigation": [{
        "content": "Install an Antivirus solution to increase protection of the workstations",
        "details": null,
        "scoreImprovement": 10
    }, {
        "content": "Investigate all malware indicators (Contact your incident response team or support.microsoft.com). When assured the problem is solved, acknowledge the alert",
        "details": {
            "name": "",
            "description": {
                "name": "",
                "important": false,
                "warning": false
            },
            "headers": ["Detection Time", "Alert Message", "Description", "Devices"],
            "rows": [
                ["03/10/2022 07:10:24", "Address Scan Detected", "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.", ""],
            ]
        },
        "scoreImprovement": 8
    }, {
        "content": "Install a backup server in the network",
        "details": null,
        "scoreImprovement": 5
    }, {
        "content": "Install latest security updates (Devices: 2)",
        "details": {
            "name": "",
            "description": {
                "name": "",
                "important": false,
                "warning": false
            },
            "headers": ["Name", "Address"],
            "rows": [
                ["10.13.10.5", "10.13.10.5"],
                ["192.168.1.127", "192.168.1.127"]
            ]
        },
        "scoreImprovement": 2
    }, {
        "content": "Increase password complexity for authentication (Devices: 53)",
        "details": {
            "name": "",
            "description": {
                "name": "",
                "important": false,
                "warning": false
            },
            "headers": ["Name", "Address"],
            "rows": [
                ["10.10.10.13", "10.10.10.13"],
                ["10.10.10.14", "10.10.10.14"],
                ["10.10.10.15", "10.10.10.15"],
                ["10.13.10.3", "10.13.10.3"],
                ["10.13.10.40", "10.13.10.40"],
                ["10.13.10.5", "10.13.10.5"],
                ["10.13.11.2", "10.13.11.2"],
                ["10.13.11.3", "10.13.11.3"],
                ["192.168.1.100", "192.168.1.100"],
                ["192.168.1.242", "192.168.1.242"]
            ]
        },
        "scoreImprovement": 2
    }, {
        "content": "Investigate and acknowledge all unacknowledge alerts",
        "details": {
            "name": "",
            "description": {
                "name": "",
                "important": false,
                "warning": false
            },
            "headers": ["Detection Time", "Alert Message", "Description"],
            "rows": [
                ["03/10/2022 07:10:24", "Address Scan Detected", "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."],
                ["03/10/2022 07:44:52", "No Traffic Detected on Sensor Interface", "The sensor stopped detecting network traffic on local_listener."]
            ]
        },
        "scoreImprovement": 1
    }]
}

Comando cURL

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" "https://<IP address>/api/v1/reports/vulnerabilities/mitigation"

Pasos siguientes

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