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

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

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

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

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

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

GET

Запросить

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

Response

Тип: JSON

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

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

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

Имя.	Тип	Nullable / Not nullable	Список значений
name	Строка	Недопустимое значение NULL	-
ipAddresses	Массив JSON	Недопустимое значение NULL	-
securityScore	Числовое	Недопустимое значение NULL	-
vendor	Строка	Допускает значение NULL
встроенное ПОVersion	Строка	Допускает значение NULL	-
model	Строка	Допускает значение NULL	-
isWirelessAccessPoint	Логический	Недопустимое значение NULL	True или False
операционная система	Объект операционной системы	Допускает значение NULL	-
vulnerabilities	Объект Уязвимостей	Недопустимое значение NULL	-

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

Имя.	Тип	Nullable / Not nullable	Список значений
name	Строка	Недопустимое значение NULL	-
type	Строка	Недопустимое значение NULL	-
version	Строка	Допускает значение NULL	-
latestVersion	Строка	Допускает значение NULL	-

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

Имя.	Тип	Nullable / Not nullable	Список значений
antiViruses	Массив строк в формате JSON	Допускает значение NULL	Имена антивирусных программ
plainTextPasswords	Массив JSON	Допускает значение NULL	Объекты паролей
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	Обнаруженные приложения со слабой проверкой подлинности

Поля пароля

Имя.	Тип	Nullable / Not nullable	Список значений
пароль	Строка	Недопустимое значение NULL	-
protocol	Строка	Недопустимое значение NULL	-
strength	Строка	Недопустимое значение NULL	Very weak, , WeakMediumStrong

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

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

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

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

Поля CVE

Имя.	Тип	Nullable / Not nullable	Список значений
id	Строка	Недопустимое значение NULL	-
score	Числовое, десятичное значение	Недопустимое значение NULL	-
описание	Строка	Недопустимое значение 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
        }
    }
]

Команда cURL

Тип: 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 вызывается без параметров запроса.

Response

Тип: представление JSON одной или нескольких таблиц данных с определенными и потенциально разными структурами.

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

неавторизованные поляDevices

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

поля illegalTrafficByFirewallRules

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

поля weakFirewallRules

Имя.	Тип	Nullable / Not nullable	Список значений
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 объектов портов в любом из следующих форматов: - Any - port (protocol, if detected) - from port-to port (protocol, if detected)

Поля accessPoints

Имя.	Тип	Nullable / Not nullable	Список значений
macAddress	Строка	Допускает значение NULL	MAC-адрес точки доступа
vendor	Строка	Допускает значение NULL	Имя поставщика точки доступа
ipAddress	Строка	Допускает значение NULL	IP-адрес точки доступа или N/A
name	Строка	Допускает значение NULL	Имя устройства точки доступа или N/A
wireless	Строка	Допускает значение NULL	Подключена ли точка доступа к беспроводной сети: Noили SuspectedYes

Поля connectionsBetweenSubnets

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

поля industrialMalwareIndicator

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

Поля internetConnections

Имя.	Тип	Nullable / Not nullable	Список значений
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"
        }
    ]
}

Команда cURL

Тип: 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

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

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

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

GET

Запросить

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

Response

Тип: представление JSON одной или нескольких таблиц данных с определенными и потенциально разными структурами.

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

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

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

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

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

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

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

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

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

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

Имя.	Тип	Nullable / Not nullable	Список значений
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
        }
    ]
}

Команда cURL

Тип: 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 вызывается без параметров запроса.

Response

Тип: JSON

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

Поля ответа

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

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

Имя поля	Тип	Допускает значение NULL	Список значений
content	Строка	Недопустимое значение NULL	Рекомендуемые шаги по устранению рисков для обнаруженных уязвимостей
scoreImprovement	Целое	Допускает значение NULL	Ожидаемый процент улучшения безопасности после выполнения мер по устранению рисков.
details	Таблица	Допускает значение 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

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

Следующие шаги

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