Справочник по API управления уязвимостями для датчиков мониторинга OT

Статья
06/01/2023

В этой статье перечислены REST API управления уязвимостями, поддерживаемые для Microsoft Defender для датчиков мониторинга IoT OT.

Данные, включенные в ответы API, содержат те же сведения, что и при создании отчета об уязвимостях из локальной консоли управления.

devices (Получение сведений об уязвимости устройства)

Этот API позволяет получить результаты оценки уязвимостей для каждого устройства.

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

GET

Этот API вызывается без параметров запроса.

Тип: JSON

Массив объектов JSON, представляющих оцененные устройства и обнаруженные ими уязвимости.

Устройства, не имеющие уязвимостей, не включаются в ответ на результат.

Поля устройства

Имя	Тип	Допускающее значение NULL или не допускающее значение NULL	Список значений
name	Строка	Не допускает значения NULL	-
ipAddresses	Массив JSON	Не допускает значения NULL	-
securityScore	Числовой	Не допускает значения NULL	-
vendor	Строка	Допускает значения NULL
FirmwareVersion	Строка	Допускает значения NULL	-
model	Строка	Допускает значения NULL	-
isWirelessAccessPoint	Логическое	Не допускает значения NULL	`True` или `False`
operatingSystem	Объект операционной системы	Допускает значения NULL	-
vulnerabilities	Объект уязвимостей	Не допускает значения NULL	-

Поля операционной системы

Имя	Тип	Допускающее значение NULL или не допускающее значение NULL	Список значений
name	Строка	Не допускает значения NULL	-
type	Строка	Не допускает значения NULL	-
version	Строковый тип	Допускает значения NULL	-
latestVersion	Строка	Допускает значения NULL	-

Поля уязвимостей

Имя	Тип	Допускающее значение NULL или не допускающее значение NULL	Список значений
antiViruses	Массив строк в формате JSON	Допускает значения NULL	Имена антивирусных программ
plainTextPasswords	Массив JSON	Допускает значения NULL	Объекты password
remoteAccess	Массив JSON	Допускает значения NULL	Объекты удаленного доступа
isBackupServer	Логическое	Не допускает значения NULL	`True` или `False`
openedPorts	Массив JSON	Допускает значения NULL	Открытые объекты портов
isEngineeringStation	Логическое	Не допускает значения NULL	`True` или `False`
isKnownScanner	Логическое	Не допускает значения NULL	`True` или `False`
cves	Массив JSON	Допускает значения NULL	Объекты CVE
isUnauthorized	Логическое	Не допускает значения NULL	`True` или `False`
malwareIndicationsDetected	Логическое	Не допускает значения NULL	`True` или `False`
weakAuthentication	Массив строк в формате JSON	Допускает значения NULL	Обнаруженные приложения со слабой проверкой подлинности

Поля пароля

Имя	Тип	Допускающее значение NULL или не допускающее значение NULL	Список значений
password	Строка	Не допускает значения NULL	-
protocol	Строка	Не допускает значения NULL	-
strength	Строка	Не допускает значения NULL	`Very weak`, `Weak`, `Medium`, `Strong`

Поля удаленного доступа

Имя	Тип	Допускает значения NULL	Список значений
port	Числовой	Не допускает значения NULL	-
transport	Строка	Не допускает значения NULL	`TCP`, `UDP`
client	Строка	Не допускает значения NULL	IP-адрес
clientSoftware	Строка	Не допускает значения NULL	Имя удаленного протокола, например `SSH`, `VNC`, `Remote desktop`или `Team viewer`

Поля открытого порта

Имя	Тип	Допускающее значение NULL или не допускающее значение NULL	Список значений
port	Числовой	Не допускает значения NULL	-
transport	Строка	Не допускает значения NULL	`TCP` или `UDP`
protocol	Строка	Допускает значения NULL	-
isConflictingWithFirewall	Логическое	Не допускает значения NULL	`True` или `False`

Поля CVE

Имя	Тип	Допускающее значение NULL или не допускающее значение NULL	Список значений
идентификатор	Строка	Не допускает значения NULL	-
score	Числовое, десятичное значение	Не допускает значения NULL	-
description	Строка	Не допускает значения NULL	-

Пример ответа

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

Тип: GET

API:

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

Пример:

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

безопасность (получение уязвимостей системы безопасности)

Используйте этот API для запроса результатов общего отчета об оценке уязвимостей. Полученная оценка дает понимание текущего уровня безопасности вашей системы.

Эта оценка основывается на обобщенных сведениях о сети и системах, а не на анализе конкретных устройств.

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

GET

Этот API вызывается без параметров запроса.

Тип: json-представление одной или нескольких таблиц данных, каждая из которых имеет определенную и потенциально разную структуру.

Ответ отображается в представлении карты, которое сопоставляет заголовки таблиц со строками таблицы. Строки представляются в виде списка объектов с одинаковыми структурами.

поля unauthorizedDevices

Имя	Тип	Допускающее значение NULL или не допускающее значение NULL	Список значений
address	Строка	Допускает значения NULL	IP- или MAC-адрес несанкционированного устройства
name	Строка	Допускает значения NULL	Имя несанкционированного устройства
firstDetectionTime	Числовой	Допускает значения NULL	Метка времени, впервые обнаруженная устройством, в миллисекундах от времени эпохи и в часовом поясе UTC
lastSeen	Числовой	Допускает значения NULL	Метка времени последнего обнаружения трафика как отправленного на устройство или с устройства в миллисекундах от времени эпохи и в часовом поясе UTC

поля illegalTrafficByFirewallRules

Имя	Тип	Допускающее значение NULL или не допускающее значение NULL	Список значений
server	Строка	Допускает значения NULL	IP-адрес сервера
client	Строка	Допускает значения NULL	IP-адрес клиента
port	Числовой	Допускает значения NULL	Порт сервера
transport	Строка	Допускает значения NULL	`TCP`, `UDP`или `ICMP`

поля weakFirewallRules

Имя	Тип	Допускающее значение NULL или не допускающее значение NULL	Список значений
sources	Массив источников JSON	Допускает значения NULL	Массив JSON источников в любом из следующих форматов: - `Any` - `ip address (host)` - `from ip-to ip (RANGE)` - `ip address, subnet mask (NETWORK)`
destinations	Массив назначений JSON	Допускает значения NULL	Массив JSON целевых объектов в любом из следующих форматов: - `Any` - `ip address (host)` - `from ip-to ip (RANGE)` - `ip address, subnet mask (NETWORK)`
ports	Массив портов JSON	Допускает значения NULL	Массив JSON объектов port в любом из следующих форматов: - `Any` - `port (protocol, if detected)` - `from port-to port (protocol, if detected)`

поля accessPoints

Имя	Тип	Допускающее значение NULL или не допускающее значение NULL	Список значений
macAddress	Строка	Допускает значения NULL	MAC-адрес точки доступа
vendor	Строка	Допускает значения NULL	Имя поставщика точки доступа
ipAddress	Строка	Допускает значения NULL	IP-адрес точки доступа или Н/Д
name	Строка	Допускает значения NULL	Имя устройства точки доступа или Н/Д
wireless	Строка	Допускает значения NULL	Подключена ли точка доступа к беспроводной сети: `No`, `Suspected`или `Yes`

Поля connectionsBetweenSubnets

Имя	Тип	Допускающее значение NULL или не допускающее значение NULL	Список значений
server	Строка	Допускает значения NULL	IP-адрес сервера
client	Строка	Допускает значения NULL	IP-адрес клиента

Поля industrialMalwareIndicators

Имя	Тип	Допускающее значение NULL или не допускающее значение NULL	Список значений
detectionTime	Числовой	Допускает значения NULL	Метка времени, впервые обнаруженная вредоносная программа, в миллисекундах от времени эпохи и в часовом поясе UTC
alertMessage	Строка	Допускает значения NULL	Отправленное оповещение
description	Строка	Допускает значения NULL	Описание сообщения оповещения
devices	Массив JSON	Не допускает значения NULL	Массив json строк, представляющих имена устройств.

Поля internetConnections

Имя	Тип	Допускающее значение NULL или не допускающее значение NULL	Список значений
internalAddress	Строка	Допускает значения NULL	Внутренний IP-адрес подключения
авторизовано	Логическое	Допускает значения NULL	`Yes` или `No`
externalAddresses	Массив JSON	Не допускает значения NULL	Массив JSON внешних IP-адресов подключения

Пример ответа

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

Тип: GET

API:

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

Пример:

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

operational (Получение операционных уязвимостей)

Этот API позволяет получить результаты общей оценки уязвимостей. Эта оценка дает информацию об операционном состоянии сети. Она основывается на обобщенных сведениях о сети и системах, а не на анализе конкретных устройств.

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

GET

Этот API вызывается без параметров запроса.

Поля результатов backupServer

Имя	Тип	Допускающее значение NULL или не допускающее значение NULL	Список значений
source	Строка	Допускает значения NULL	Исходный IP-адрес
назначение	Строка	Допускает значения NULL	Целевой IP-адрес
port	Числовой	Допускает значения NULL	Порт сервера резервного копирования
transport	Строка	Допускает значения NULL	Транспортный протокол `TCP` сервера резервного копирования или `UDP`
backupMaximalInterval	Строка	Допускает значения NULL	Максимальный интервал времени между резервными копиями
lastSeenBackup	Числовой	Допускает значения NULL	Метка времени последнего представления резервной копии в миллисекундах от времени эпохи и часового пояса в формате UTC

Поля результатов ipNetworks

Имя	Тип	Допускающее значение NULL или не допускающее значение NULL	Список значений
addresses	Числовой	Не допускает значения NULL	Количество IP-адресов, обнаруженных в диапазоне подсети.
network	Строка	Не допускает значения NULL	Базовый IP-адрес подсети.
mask	Строка	Не допускает значения NULL	Маска подсети.

Поля результатов protocolProblems

Имя	Тип	Допускающее значение NULL или не допускающее значение NULL	Список значений
protocol	Строка	Не допускает значения NULL	Протокол, для которого было активировано оповещение о нарушении протокола.
addresses	Массив JSON IP-адресов	Не допускает значения NULL	Массив JSON IP-адресов, на которых возникло нарушение
alert	Строка	Не допускает значения NULL	Заголовок активированного оповещения
reportTime	Числовой	Не допускает значения NULL	Метка времени последнего создания отчета в миллисекундах по времени эпохи и часовом поясе UTC

Поля результатов protocolDataVolumes

Имя	Тип	Допускает значение NULL или не допускает значения NULL	Список значений
protocol	Строка	Допускает значения NULL	Протокол, обнаруженный в сети сетевым датчиком OT
volume	Строка	Допускает значения NULL	Объем пакетов протокола, захваченных сетевым датчиком OT, в МБ

поля результатов отключений

Имя	Тип	Допускает значение NULL или не допускает значения NULL	Список значений
assetAddress	Строка	Допускает значения NULL	IP-адрес отключенного ресурса
assetName	Строка	Допускает значения NULL	Имя отключенного ресурса
lastDetectionTime	Числовой	Допускает значения NULL	Метка времени последнего обнаружения отключения в миллисекундах от времени эпохи и часового пояса UTC
backToNormalTime	Числовой	Допускает значения NULL	Метка времени, возвращенная соединением, в миллисекундах от времени эпохи и часового пояса UTC

Пример ответа

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

Тип: GET

API:

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

Пример:

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

устранение рисков (получение шагов по устранению рисков)

Используйте этот API для запроса оценки устранения рисков. Эта оценка содержит рекомендуемые шаги по устранению обнаруженных уязвимостей. Она основывается на обобщенных сведениях о сети и системах, а не на анализе конкретных устройств.

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

GET

Этот API вызывается без параметров запроса.

Тип: JSON

Объект JSON, представляющий рекомендуемые шаги по устранению рисков.

Поля ответа

Имя поля	Тип	Допускает значения NULL	Список значений
уведомления	Массив строк в формате JSON	Не допускает значения NULL	Рекомендуемые действия по устранению обнаруженных уязвимостей
Смягчения	Массив JSON	Не допускает значения NULL	Объекты устранения рисков

Поля устранения рисков

Имя поля	Тип	Допускает значения NULL	Список значений
content	Строка	Не допускает значения NULL	Рекомендуемые действия по устранению обнаруженных уязвимостей
scoreImprovement	Целое число	Допускает значения NULL	Ожидаемый процент улучшения безопасности после выполнения мер по устранению рисков.
Детали	Таблица	Допускает значения NULL	Таблица с рекомендациями по устранению рисков, например, будет создана в отчете об оценке рисков . Каждая рекомендация содержит сведения о возможном влиянии на безопасность при выполнении действия и многое другое. Дополнительные сведения см. в разделе Устранение рисков.

Примечание

У вас может быть несколько шагов по устранению рисков, причем некоторые из них возвращаются в notifications поле , а другие — в mitigation поле. Элементы с scoreImprovement данными и details возвращаются только в mitigation поле . Элементы без scoreImprovement и details данные возвращаются только в notifications поле .

Пример ответа

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

Дальнейшие действия

Дополнительные сведения см. в справочнике по API Defender для Интернета вещей.

Share via

Справочник по API управления уязвимостями для датчиков мониторинга OT

devices (Получение сведений об уязвимости устройства)

GET

Поля устройства

Поля операционной системы

Поля уязвимостей

Поля пароля

Поля удаленного доступа

Поля открытого порта

Поля CVE

Пример ответа

безопасность (получение уязвимостей системы безопасности)

GET

поля unauthorizedDevices

поля illegalTrafficByFirewallRules

поля weakFirewallRules

поля accessPoints

Поля connectionsBetweenSubnets

Поля industrialMalwareIndicators

Поля internetConnections

Пример ответа

operational (Получение операционных уязвимостей)

GET

Поля результатов backupServer

Поля результатов ipNetworks

Поля результатов protocolProblems

Поля результатов protocolDataVolumes

поля результатов отключений

Пример ответа

устранение рисков (получение шагов по устранению рисков)

GET

Поля ответа

Поля устранения рисков

Пример ответа

Дальнейшие действия

Дополнительные ресурсы