Referência da API de gestão de vulnerabilidades para sensores de monitorização de OT

Artigo
04/11/2023

Este artigo lista as APIs REST de gestão de vulnerabilidades suportadas para Microsoft Defender para sensores de monitorização OT IoT.

Os dados incluídos nas respostas da API incluem as mesmas informações que se tiver gerado um relatório de vulnerabilidade a partir da consola de gestão no local.

dispositivos (Obter informações de vulnerabilidade do dispositivo)

Utilize esta API para pedir resultados de avaliação de vulnerabilidades para cada dispositivo.

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

GET

Esta API é chamada sem quaisquer parâmetros de pedido.

Tipo: JSON

Matriz de objetos JSON que representam dispositivos avaliados e as respetivas vulnerabilidades reportadas.

Os dispositivos que não têm vulnerabilidades não estão incluídos na resposta de resultados.

Campos do dispositivo

Nome	Tipo	Nulo / Não nulo	Lista de valores
nome	String	Não nulo	-
ipAddresses	Matriz JSON	Não nulo	-
securityScore	Operador numérico	Não nulo	-
fornecedor	String	Pode ser nulo
firmwareVersion	String	Pode ser nulo	-
modelo	String	Pode ser nulo	-
isWirelessAccessPoint	Booleano	Não nulo	`True` ou `False`
operatingSystem	Objeto do sistema operativo	Pode ser nulo	-
vulnerabilidades	Objeto vulnerabilidades	Não nulo	-

Campos do sistema operativo

Nome	Tipo	Nulo / Não nulo	Lista de valores
nome	String	Não nulo	-
tipo	String	Não nulo	-
versão	String	Pode ser nulo	-
latestVersion	String	Pode ser nulo	-

Campos de vulnerabilidades

Nome	Tipo	Nulo / Não nulo	Lista de valores
antiVírus	Matriz JSON de cadeias	Pode ser nulo	Nomes de antivírus
plainTextPasswords	Matriz JSON	Pode ser nulo	Objetos de palavra-passe
remoteAccess	Matriz JSON	Pode ser nulo	Objetos de acesso remoto
isBackupServer	Booleano	Não nulo	`True` ou `False`
openedPorts	Matriz JSON	Pode ser nulo	Objetos de porta abertos
isEngineeringStation	Booleano	Não nulo	`True` ou `False`
isKnownScanner	Booleano	Não nulo	`True` ou `False`
cves	Matriz JSON	Pode ser nulo	Objetos CVE
isUnauthorized	Booleano	Não nulo	`True` ou `False`
malwareIndicationsDetected	Booleano	Não nulo	`True` ou `False`
weakAuthentication	Matriz JSON de cadeias	Pode ser nulo	Aplicações detetadas que estão a utilizar a autenticação fraca

Campos de palavra-passe

Nome	Tipo	Nulo / Não nulo	Lista de valores
palavra-passe	String	Não nulo	-
protocolo	String	Não nulo	-
força	String	Não nulo	`Very weak`, `Weak`, `Medium`, `Strong`

Campos de acesso remoto

Nome	Tipo	Pode ser nulo	Lista de valores
porta	Operador numérico	Não nulo	-
transporte	String	Não nulo	`TCP`, `UDP`
cliente	String	Não nulo	Endereço IP
clientSoftware	String	Não nulo	Nome do protocolo remoto, como `SSH`, `VNC`, `Remote desktop`ou `Team viewer`

Abrir campos de porta

Nome	Tipo	Nulo / Não nulo	Lista de valores
porta	Operador numérico	Não nulo	-
transporte	String	Não nulo	`TCP` ou `UDP`
protocolo	String	Pode ser nulo	-
isConflictingWithFirewall	Booleano	Não nulo	`True` ou `False`

Campos CVE

Nome	Tipo	Nulo / Não nulo	Lista de valores
id	String	Não nulo	-
pontuação	Valor numérico e decimal	Não nulo	-
descrição	String	Não nulo	-

Exemplo de resposta

[
    {
        "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
        }
    }
]

Tipo: GET

API:

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

Exemplo:

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

security (Obter vulnerabilidades de segurança)

Utilize esta API para pedir resultados de um relatório geral de avaliação de vulnerabilidades. Esta avaliação fornece informações sobre o nível de segurança do sistema.

Esta avaliação baseia-se em informações gerais de rede e sistema e não numa avaliação específica do dispositivo.

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

GET

Esta API é chamada sem quaisquer parâmetros de pedido.

Tipo: representação JSON de uma ou mais tabelas de dados, cada uma com estruturas específicas e potencialmente diferentes.

A resposta é apresentada numa vista de mapa, que mapeia títulos de tabelas para linhas de tabela. As linhas são representadas como uma lista de objetos com as mesmas estruturas.

campos unauthorizedDevices

Nome	Tipo	Anulável / Não nulo	Lista de valores
endereço	String	Pode ser nulo	Endereço IP ou MAC do dispositivo não autorizado
nome	String	Pode ser nulo	Nome do dispositivo não autorizado
firstDetectionTime	Operador numérico	Pode ser nulo	Carimbo de data/hora em que o dispositivo foi detetado pela primeira vez, em milissegundos a partir da hora da época e no fuso horário UTC
lastSeen	Operador numérico	Pode ser nulo	Carimbo de data/hora em que o tráfego foi detetado pela última vez como enviado para ou a partir do dispositivo, em milissegundos a partir da hora da época e no fuso horário UTC

campos illegalTrafficByFirewallRules

Nome	Tipo	Anulável / Não nulo	Lista de valores
servidor	String	Pode ser nulo	Endereço IP do servidor
cliente	String	Pode ser nulo	Endereço IP do cliente
porta	Operador numérico	Pode ser nulo	A porta do servidor
transporte	String	Pode ser nulo	`TCP`, `UDP`ou `ICMP`

campos weakFirewallRules

Nome	Tipo	Anulável / Não nulo	Lista de valores
origens	Matriz JSON de origens	Pode ser nulo	Matriz JSON de origens em qualquer um dos seguintes formatos: - `Any` - `ip address (host)` - `from ip-to ip (RANGE)` - `ip address, subnet mask (NETWORK)`
destinos	Matriz JSON de destinos	Pode ser nulo	Matriz JSON de objetos de destino, em qualquer um dos seguintes formatos: - `Any` - `ip address (host)` - `from ip-to ip (RANGE)` - `ip address, subnet mask (NETWORK)`
portas	Matriz JSON de portas	Pode ser nulo	Matriz JSON de objetos de porta, em qualquer um dos seguintes formatos: - `Any` - `port (protocol, if detected)` - `from port-to port (protocol, if detected)`

campos do accessPoints

Nome	Tipo	Anulável / Não nulo	Lista de valores
macAddress	String	Pode ser nulo	O endereço MAC do ponto de acesso
fornecedor	String	Pode ser nulo	O nome do fornecedor do ponto de acesso
endereço ip	String	Pode ser nulo	O endereço IP do ponto de acesso ou N/D
nome	String	Pode ser nulo	O nome do dispositivo do ponto de acesso ou N/D
sem fios	String	Pode ser nulo	Se o ponto de acesso está ligado a uma rede sem fios: `No`, `Suspected`ou `Yes`

connectionsBetweenSubnets campos

Nome	Tipo	Anulável / Não nulo	Lista de valores
servidor	String	Pode ser nulo	O endereço IP do servidor
cliente	String	Pode ser nulo	O endereço IP do cliente

campos industrialMalwareIndicators

Nome	Tipo	Anulável / Não nulo	Lista de valores
detectionTime	Operador numérico	Pode ser nulo	Carimbo de data/hora o malware foi detetado pela primeira vez, em milissegundos da hora da época e no fuso horário UTC
alertMessage	String	Pode ser nulo	A mensagem de alerta enviada
descrição	String	Pode ser nulo	Descrição da mensagem de alerta
dispositivos	Matriz JSON	Não nulo	Uma matriz JSON de cadeias que representam nomes de dispositivos

campos internetConnections

Nome	Tipo	Nulo / Não nulo	Lista de valores
internalAddress	String	Pode ser nulo	O endereço IP interno da ligação
autorizado	Booleano	Pode ser nulo	`Yes` ou `No`
externalAddresses	Matriz JSON	Não nulo	Uma matriz JSON dos endereços IP externos da ligação

Exemplo de resposta

{
    "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"
        }
    ]
}

Tipo: GET

APIs:

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

Exemplo:

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

operacional (Obter vulnerabilidades operacionais)

Utilize esta API para pedir resultados de uma avaliação geral de vulnerabilidades. Esta avaliação fornece informações sobre o estado operacional da sua rede. Baseia-se em informações gerais de rede e sistema e não numa avaliação específica do dispositivo.

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

GET

Esta API é chamada sem quaisquer parâmetros de pedido.

Tipo: representação JSON de uma ou mais tabelas de dados, cada uma com estruturas específicas e potencialmente diferentes.

A resposta é apresentada numa vista de mapa, que mapeia títulos de tabelas para linhas de tabela. As linhas são representadas como uma lista de objetos com as mesmas estruturas.

campos de resultado backupServer

Nome	Tipo	Nulo / Não nulo	Lista de valores
origem	String	Pode ser nulo	O endereço IP de origem
destino	String	Pode ser nulo	O endereço IP de destino
porta	Operador numérico	Pode ser nulo	A porta do servidor de cópia de segurança
transporte	String	Pode ser nulo	O protocolo `TCP` de transporte do servidor de cópia de segurança ou `UDP`
backupMaximalInterval	String	Pode ser nulo	O tempo de intervalo máximo entre cópias de segurança
lastSeenBackup	Operador numérico	Pode ser nulo	Carimbo de data/hora em que uma cópia de segurança foi vista pela última vez, em milissegundos da hora da época e no fuso horário UTC

campos de resultados ipNetworks

Nome	Tipo	Nulo / Não nulo	Lista de valores
endereços	Operador numérico	Não nulo	O número de endereços IP detetados no intervalo de sub-rede.
network	String	Não nulo	O endereço IP base da sub-rede.
mask	String	Não nulo	A máscara de sub-rede.

campos de resultado protocolProblems

Nome	Tipo	Nulo / Não nulo	Lista de valores
protocolo	String	Não nulo	Um protocolo para o qual foi acionado um alerta de violação de protocolo
endereços	Matriz JSON de endereços IP	Não nulo	Matriz JSON de endereços IP onde a violação teve origem
alerta	String	Não nulo	O título do alerta acionado
reportTime	Operador numérico	Não nulo	Carimbo de data/hora em que um relatório foi gerado pela última vez, em milissegundos da hora da época e no fuso horário UTC

campos de resultado protocolDataVolumes

Nome	Tipo	Nulo / Não nulo	Lista de valores
protocolo	String	Pode ser nulo	Um protocolo que foi detetado na rede pelo sensor de rede OT
volume	String	Pode ser nulo	O volume de pacotes de protocolo capturados pelo sensor de rede OT, em MB

campos de resultados de desligamentos

Nome	Tipo	Nulo / Não nulo	Lista de valores
assetAddress	String	Pode ser nulo	O endereço IP do recurso desligado
assetName	String	Pode ser nulo	O nome do recurso desligado
lastDetectionTime	Operador numérico	Pode ser nulo	Carimbo de data/hora em que a desconexão foi detetada pela última vez, em milissegundos da hora da época e no fuso horário UTC
backToNormalTime	Operador numérico	Pode ser nulo	Carimbo de data/hora que a ligação devolveu, em milissegundos da hora da época e no fuso horário UTC

Exemplo de resposta

{
    "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
        }
    ]
}

Tipo: GET

APIs:

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

Exemplo:

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

mitigação (Obter passos de mitigação)

Utilize esta API para pedir uma avaliação de mitigação. Esta avaliação fornece os passos recomendados para mitigar vulnerabilidades detetadas. Baseia-se em informações gerais de rede e sistema e não numa avaliação específica do dispositivo.

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

GET

Esta API é chamada sem quaisquer parâmetros de pedido.

Tipo: JSON

Objeto JSON que representa os passos de mitigação recomendados.

Campos de resposta

Nome do campo	Tipo	Pode ser nulo	Lista de valores
notificações	Matriz JSON de cadeias	Não nulo	Passos de mitigação recomendados para vulnerabilidades detetadas
mitigação	Matriz JSON	Não nulo	objetos de mitigação

campos de mitigação

Nome do campo	Tipo	Pode ser nulo	Lista de valores
conteúdo	String	Não nulo	Passos de mitigação recomendados para vulnerabilidades detetadas
scoreImprovement	Número inteiro	Pode ser nulo	Percentagem esperada de melhoria de segurança após a tomada dos passos de mitigação.
detalhes	Tabela	Pode ser nulo	Uma tabela com recomendações de mitigação, como, por exemplo, seria gerada no relatório Avaliação de riscos . Cada recomendação inclui detalhes sobre um possível impacto de segurança se a ação for executada e muito mais. Para obter mais informações, veja Mitigação de riscos.

Nota

Poderá ter vários passos de mitigação, com alguns devolvidos no notifications campo e outros devolvidos no mitigation campo. Os itens com scoreImprovement e details os dados são devolvidos apenas no mitigation campo. Os itens sem scoreImprovement e details os dados são devolvidos apenas no notifications campo.

Exemplo de resposta

{
    "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
    }]
}

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

Passos seguintes

Para obter mais informações, veja Descrição geral da referência da API do Defender para IoT.

Partilhar via

Referência da API de gestão de vulnerabilidades para sensores de monitorização de OT

dispositivos (Obter informações de vulnerabilidade do dispositivo)

GET

Campos do dispositivo

Campos do sistema operativo

Campos de vulnerabilidades

Campos de palavra-passe

Campos de acesso remoto

Abrir campos de porta

Campos CVE

Exemplo de resposta

security (Obter vulnerabilidades de segurança)

GET

campos unauthorizedDevices

campos illegalTrafficByFirewallRules

campos weakFirewallRules

campos do accessPoints

connectionsBetweenSubnets campos

campos industrialMalwareIndicators

campos internetConnections

Exemplo de resposta

operacional (Obter vulnerabilidades operacionais)

GET

campos de resultado backupServer

campos de resultados ipNetworks

campos de resultado protocolProblems

campos de resultado protocolDataVolumes

campos de resultados de desligamentos

Exemplo de resposta

mitigação (Obter passos de mitigação)

GET

Campos de resposta

campos de mitigação

Exemplo de resposta

Passos seguintes

Comentários

Recursos adicionais