Referência de API de gerenciamento de vulnerabilidades para sensores de monitoramento de OT

Este artigo apresenta as APIs REST de gerenciamento de vulnerabilidades compatíveis com os sensores de monitoramento de OT do Microsoft Defender para IoT.

Os dados incluídos nas respostas de API incluem as mesmas informações que se você tivesse gerado um relatório de vulnerabilidade do console de gerenciamento local.

devices (Recuperar informações de vulnerabilidade do dispositivo)

Use essa API para solicitar resultados de avaliações de vulnerabilidade para cada dispositivo.

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

GET

Solicitação

Essa API é chamada sem nenhum parâmetro de solicitação.

Resposta

Tipo: JSON

Matriz de objetos JSON que representam dispositivos avaliados e suas vulnerabilidades relatadas.

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

Campos do dispositivo

Nome	Type	Anulável/Não anulável	Lista de valores
name	String	Não permite valor nulo	-
ipAddresses	Matriz JSON	Não permite valor nulo	-
securityScore	Numérico	Não permite valor nulo	-
vendor	String	Nullable
firmwareVersion	String	Nullable	-
modelo	String	Nullable	-
isWirelessAccessPoint	Boolean	Não permite valor nulo	True ou False
operatingSystem	Objeto do sistema operacional	Nullable	-
vulnerabilities	Objeto das vulnerabilidades	Não permite valor nulo	-

Campos do sistema operacional

Nome	Type	Anulável/Não anulável	Lista de valores
name	String	Não permite valor nulo	-
tipo	String	Não permite valor nulo	-
version	String	Nullable	-
latestVersion	String	Nullable	-

Campos das vulnerabilidades

Nome	Type	Anulável/Não anulável	Lista de valores
antiViruses	Matriz de cadeias de caracteres JSON	Nullable	Nomes dos antivírus
plainTextPasswords	Matriz JSON	Nullable	Objetos de Senha
remoteAccess	Matriz JSON	Nullable	Objetos de Acesso remoto
isBackupServer	Boolean	Não permite valor nulo	True ou False
openedPorts	Matriz JSON	Nullable	Objetos de Porta aberta
isEngineeringStation	Boolean	Não permite valor nulo	True ou False
isKnownScanner	Boolean	Não permite valor nulo	True ou False
cves	Matriz JSON	Nullable	Objetos de CVE
isUnauthorized	Boolean	Não permite valor nulo	True ou False
malwareIndicationsDetected	Boolean	Não permite valor nulo	True ou False
weakAuthentication	Matriz de cadeias de caracteres JSON	Nullable	Aplicativos detectados que estão usando autenticação fraca

Campos de senha

Nome	Type	Anulável/Não anulável	Lista de valores
password	String	Não permite valor nulo	-
protocol	String	Não permite valor nulo	-
strength	String	Não permite valor nulo	Very weak, Weak, Medium, Strong

Campos de acesso remoto

Nome	Tipo	Nullable	Lista de valores
port	Numérico	Não permite valor nulo	-
transport	String	Não permite valor nulo	TCP, UDP
client	String	Não permite valor nulo	Endereço IP
clientSoftware	String	Não permite valor nulo	Nome do protocolo remoto, comoSSH, VNC, Remote desktop ou Team viewer

Abrir campos de porta

Nome	Type	Anulável/Não anulável	Lista de valores
port	Numérico	Não permite valor nulo	-
transport	String	Não permite valor nulo	TCP ou UDP
protocol	String	Nullable	-
isConflictingWithFirewall	Boolean	Não permite valor nulo	True ou False

Campos de CVEs

Nome	Type	Anulável/Não anulável	Lista de valores
id	String	Não permite valor nulo	-
score	Valor numérico decimal	Não permite valor nulo	-
descrição	String	Não permite valor 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
        }
    }
]

Comando de cURL

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 (Recuperar vulnerabilidades de segurança)

Use essa API para solicitar resultados do relatório de avaliação geral de vulnerabilidade. Essa avaliação fornece informações sobre o nível de segurança do seu sistema.

Essa avaliação é baseada em informações gerais de rede e de sistema e não na avaliação de um dispositivo específico.

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

GET

Solicitação

Essa API é chamada sem nenhum parâmetro de solicitação.

Resposta

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

A resposta é exibida em um modo de exibição de mapa, que mapeia títulos de tabela para linhas de tabela. As linhas são representadas como uma lista de objetos com as mesmas estruturas.

Campos unauthorizedDevices

Nome	Type	Anulável/Não anulável	Lista de valores
address	String	Nullable	Endereço IP ou MAC do dispositivo não autorizado
name	String	Nullable	Nome do dispositivo não autorizado
firstDetectionTime	Numérico	Nullable	Carimbo de data/hora em que o dispositivo foi detectado pela primeira vez, em milissegundos da Hora da época no fuso horário UTC
lastSeen	Numérico	Nullable	Carimbo de data/hora em que o tráfego foi detectado pela última vez como enviado para ou do dispositivo, em milissegundos da Hora da época e no fuso horário UTC

illegalTrafficByFirewallRules fields

Nome	Type	Anulável/Não anulável	Lista de valores
server	String	Nullable	Endereço IP do servidor
client	String	Nullable	Endereço IP do cliente
port	Numérico	Nullable	A porta do servidor
transport	String	Nullable	TCP, UDP ou ICMP

Campos weakFirewallRules

Nome	Type	Anulável/Não anulável	Lista de valores
sources	Matriz JSON de fontes	Nullable	Matriz JSON de fontes em qualquer um dos seguintes 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, em qualquer um dos seguintes formatos: - Any - ip address (host) - from ip-to ip (RANGE) - ip address, subnet mask (NETWORK)
ports	Matriz JSON de portas	Nullable	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 accessPoints

Nome	Type	Anulável/Não anulável	Lista de valores
macAddress	String	Nullable	O endereço MAC do ponto de acesso
vendor	String	Nullable	O nome do fornecedor do ponto de acesso
ipAddress	String	Nullable	O endereço IP do ponto de acesso ou N/A
name	String	Nullable	O nome do dispositivo do ponto de acesso ou N/A
wireless	String	Nullable	Se o ponto de acesso está conectado a uma rede sem fio: No, Suspected ou Yes

Campos connectionsBetweenSubnets

Nome	Type	Anulável/Não anulável	Lista de valores
server	String	Nullable	O endereço IP do servidor
client	String	Nullable	O endereço IP do cliente

Campos industrialMalwareIndicators

Nome	Type	Anulável/Não anulável	Lista de valores
detectionTime	Numérico	Nullable	Carimbo de data/hora em que o malware foi detectado pela primeira vez, em milissegundos da Hora da época no fuso horário UTC
alertMessage	String	Nullable	A mensagem de alerta enviada
descrição	String	Nullable	A descrição da mensagem de alerta
devices	Matriz JSON	Não permite valor nulo	Uma matriz JSON de cadeias de caracteres que representam nomes de dispositivo

Campos internetConnections

Nome	Type	Anulável/Não anulável	Lista de valores
internalAddress	String	Nullable	O endereço IP interno da conexão
autorizado	Boolean	Nullable	Yes ou No
externalAddresses	Matriz JSON	Não permite valor nulo	Uma matriz JSON dos endereços IP externos da conexã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"
        }
    ]
}

Comando de cURL

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

operational (Recuperar vulnerabilidades operacionais)

Use essa API para solicitar resultados de uma avaliação geral de vulnerabilidade. Essa avaliação fornece informações sobre o status operacional da sua rede. É baseada em informações gerais de rede e de sistema e não na avaliação de um dispositivo específico.

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

GET

Solicitação

Essa API é chamada sem nenhum parâmetro de solicitação.

Resposta

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

A resposta é exibida em um modo de exibição de mapa, que mapeia títulos de tabela para linhas de tabela. As linhas são representadas como uma lista de objetos com as mesmas estruturas.

Campos de resultado do backupServer

Nome	Type	Anulável/Não anulável	Lista de valores
source	String	Nullable	O endereço IP de origem
destination	String	Nullable	O endereço IP de destino
port	Numérico	Nullable	A porta do servidor de backup
transport	String	Nullable	O protocolo de transporte do servidor de backup TCP ou UDP
backupMaximalInterval	String	Nullable	O tempo de intervalo máximo entre backups
lastSeenBackup	Numérico	Nullable	Carimbo de data/hora em que um backup foi visto pela última vez, em milissegundos da Hora da época no fuso horário UTC

Campos de resultado do ipNetworks

Nome	Type	Anulável/Não anulável	Lista de valores
addresses	Numérico	Não permite valor nulo	O número de endereços IP descobertos no intervalo de sub-rede.
network	String	Não permite valor nulo	O endereço IP base da sub-rede.
mask	String	Não permite valor nulo	A máscara de sub-rede.

Campos de resultado protocolProblems

Nome	Type	Anulável/Não anulável	Lista de valores
protocol	String	Não permite valor nulo	Um protocolo para o qual um alerta de violação de protocolo foi disparado
addresses	Matriz JSON de endereços IP	Não permite valor nulo	Matriz JSON de endereços IP em que a violação se originou
alert	String	Não permite valor nulo	O título do alerta disparado
reportTime	Numérico	Não permite valor nulo	Carimbo de data/hora em que um relatório foi gerado pela última vez, em milissegundos da Hora da época no fuso horário UTC

Campos de resultado protocolDataVolumes

Nome	Type	Anulável/Não anulável	Lista de valores
protocol	String	Nullable	Um protocolo detectado na rede pelo sensor de rede OT
volume	String	Nullable	O volume de pacotes de protocolo capturados pelo sensor de rede OT, em MB

campos de resultado de desconexões

Nome	Type	Anulável/Não anulável	Lista de valores
assetAddress	String	Nullable	O endereço IP do ativo desconectado
assetName	String	Nullable	O nome do ativo desconectado
lastDetectionTime	Numérico	Nullable	Carimbo de data/hora em que a desconexão foi detectada pela última vez, em milissegundos da Hora da época e no fuso horário UTC
backToNormalTime	Numérico	Nullable	Carimbo de data/hora que a conexão retornou, 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
        }
    ]
}

Comando de cURL

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

mitigation (Recuperar etapas de mitigação)

Use essa API para solicitar uma avaliação de mitigação. Essa avaliação apresenta as etapas recomendadas para mitigar as vulnerabilidades detectadas. É baseada em informações gerais de rede e de sistema e não na avaliação de um dispositivo específico.

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

GET

Solicitação

Essa API é chamada sem nenhum parâmetro de solicitação.

Resposta

Tipo: JSON

Objeto JSON que representa as etapas de mitigação recomendadas.

Campos de resposta

Nome do campo	Tipo	Nullable	Lista de valores
notificações	Matriz de cadeias de caracteres JSON	Não permite valor nulo	Etapas de mitigação recomendadas para vulnerabilidades detectadas
mitigação	Matriz JSON	Não permite valor nulo	objetos de mitigação

campos de mitigação

Nome do campo	Tipo	Nullable	Lista de valores
content	String	Não permite valor nulo	Etapas de mitigação recomendadas para vulnerabilidades detectadas
scoreImprovement	Integer	Nullable	Percentual esperado de melhoria de segurança após as etapas de mitigação serem executadas.
details	Tabela	Nullable	Recomendações de mitigação de listagem de tabela, como seriam geradas no relatório de Avaliação de risco. Cada recomendação inclui detalhes sobre o possível impacto na segurança se a ação for executada e muito mais. Confira mais informações em Mitigação de risco.

Observação

Você pode ter várias etapas de mitigação, com algumas retornadas no campo notifications e outras retornadas no campo mitigation. Itens com os dados scoreImprovement e details são retornados somente no campo mitigation. Os itens sem os dados scoreImprovement e details são retornados somente no campo notifications.

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

Comando de cURL

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

Próximas etapas

Para obter mais informações, confira a Visão geral de referência da API do Defender para IoT.