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

Статья
12/18/2023

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

подключения (получение сведений о подключении устройства)

Используйте этот API для запроса списка всех подключений к устройству.

URI: /api/v1/devices/connections

GET

Параметры запроса

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

Имя	Описание:	Пример	Обязательный или необязательный
discoveredBefore	Числовые. Результаты фильтрации, обнаруженные до заданного времени, где заданное время определяется в миллисекундах из времени эпохи и в часовом поясе UTC.	`/api/v1/devices/2/connections?discoveredBefore=<epoch>`	Необязательно
discoveredAfter	Числовые. Результаты фильтрации, обнаруженные после заданного времени, где заданное время определяется в миллисекундах из времени эпохи и в часовом поясе UTC.	`/api/v1/devices/2/connections?discoveredAfter=<epoch>`	Необязательно
lastActiveInMinutes	Числовые. Отфильтруйте результаты по заданному временному интервалу, в течение которого были активны подключения. Определяется назад в минутах с текущего времени.	`/api/v1/devices/2/connections?lastActiveInMinutes=20`	Необязательно

Тип ответа: JSON

Массив объектов JSON, представляющих подключения устройств или следующее сообщение об ошибке:

Message	Description
Сбой — ошибка	Ошибка при выполнении операции

Поля ответа успешного выполнения

Имя.	Тип	Nullable / Not nullable	Список значений
firstDeviceId	Числовое	Недопустимое значение NULL	-
secondDeviceId	Числовое	Недопустимое значение NULL	-
lastSeen	Числовое	Недопустимое значение NULL	Эпоха по стандарту UTC
discovered	Числовое	Недопустимое значение NULL	Эпоха по стандарту UTC
ports	Массив чисел	Допускает значение NULL	-
protocols	Массив JSON	Допускает значение NULL	Поле протокола

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

Имя.	Тип	Nullable / Not nullable
name	Строка	Недопустимое значение NULL
commands	Массив строк	Допускает значение NULL

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

[
    {
        "firstDeviceId": 171,
        "secondDeviceId": 22,
        "lastSeen": 1511281457933,
        "discovered": 1511872830000,
        "ports": [
            502
        ],
        "protocols": [
        {
            name: "modbus",
            commands: [
                "Read Coils"
            ]
        },
        {
            name: "ams",
            commands: [
                "AMS Write"
            ]
        },
        {
            name: "http",
            commands: [
            ]
        }
    ]
    },
    {
        "firstDeviceId": 171,
        "secondDeviceId": 23,
        "lastSeen": 1511281457933,
        "discovered": 1511872830000,
        "ports": [
            502
        ],
        "protocols": [
            {
                name: "s7comm",
                commands: [
                    "Download block",
                    "Upload"
                ]
            }
        ]
    }
]

Тип: GET

API:

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

Примеры:

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

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

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

URI: /api/v1/devices/<deviceID>/connections

GET

Параметр пути

Имя	Описание:	Пример	Обязательный или необязательный
deviceId	Получение подключений для данного устройства.	`/api/v1/devices/<deviceId>/connections`	Обязательное поле

Параметры запроса

Имя	Описание:	Пример	Обязательный или необязательный
discoveredBefore	Числовые. Результаты фильтрации, обнаруженные до заданного времени, где заданное время определяется в миллисекундах из времени эпохи и в часовом поясе UTC.	`/api/v1/devices/2/connections?discoveredBefore=<epoch>`	Необязательно
discoveredAfter	Числовые. Результаты фильтрации, обнаруженные после заданного времени, где заданное время определяется в миллисекундах из времени эпохи и в часовом поясе UTC.	`/api/v1/devices/2/connections?discoveredAfter=<epoch>`	Необязательно
lastActiveInMinutes	Числовые. Отфильтруйте результаты по заданному временному интервалу, в течение которого были активны подключения. Определяется назад в минутах с текущего времени.	`/api/v1/devices/2/connections?lastActiveInMinutes=20`	Необязательно

Тип ответа: JSON

Массив объектов JSON, представляющих подключения устройств или следующее сообщение об ошибке:

Message	Description
Сбой — ошибка	Ошибка при выполнении операции

Поля ответа успешного выполнения

Имя.	Тип	Nullable / Not nullable	Список значений
firstDeviceId	Числовое	Недопустимое значение NULL	-
secondDeviceId	Числовое	Недопустимое значение NULL	-
lastSeen	Числовое	Недопустимое значение NULL	Эпоха по стандарту UTC
discovered	Числовое	Недопустимое значение NULL	Эпоха по стандарту UTC
ports	Массив чисел	Допускает значение NULL	-
protocols	Массив JSON	Допускает значение NULL	Поле протокола

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

Имя.	Тип	Nullable / Not nullable
name	Строка	Недопустимое значение NULL
commands	Массив строк	Допускает значение NULL

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

[
    {
        "firstDeviceId": 171,
        "secondDeviceId": 22,
        "lastSeen": 1511281457933,
        "discovered": 1511872830000,
        "ports": [
            502
        ],
        "protocols": [
        {
            name: "modbus",
            commands: [
                "Read Coils"
            ]
        },
        {
            name: "ams",
            commands: [
                "AMS Write"
            ]
        },
        {
            name: "http",
            commands: [
            ]
        }
    ]
    },
    {
        "firstDeviceId": 171,
        "secondDeviceId": 23,
        "lastSeen": 1511281457933,
        "discovered": 1511872830000,
        "ports": [
            502
        ],
        "protocols": [
            {
                name: "s7comm",
                commands: [
                    "Download block",
                    "Upload"
                ]
            }
        ]
    }
]

Тип: GET

API:

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/api/v1/devices/<deviceId>/connections?lastActiveInMinutes=&discoveredBefore=&discoveredAfter=

Примеры:

С заданными параметрами запроса:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/api/v1/devices/2/connections?lastActiveInMinutes=20&discoveredBefore=1594550986000&discoveredAfter=1594550986000

cves (получение сведений о CVEs)

Используйте этот API для запроса списка всех известных cvEs, обнаруженных на устройствах в сети, отсортированных по убыванию оценки CVE.

URI: /api/v1/devices/cves

GET

Пример: /api/v1/devices/cves

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

Имя	Описание:	Пример	Обязательный или необязательный
top	Числовые. Определите, сколько наиболее оцененных CVEs для каждого IP-адреса устройства.	`/api/v1/devices/cves?top=50` `/api/v1/devices/<ipAddress>/cves?top=50`	Необязательно. По умолчанию = `100`

Тип: JSON

Массив JSON объектов CVE устройства или следующее сообщение об ошибке:

Message	Description
Сбой — ошибка	Ошибка при выполнении операции

Поля ответа успешного выполнения

Имя.	Тип	Nullable / Not nullable	Список значений
cveId	Строка	Недопустимое значение NULL	Канонический стандартный идентификатор для заданного CVE.
ipAddress	Строка	Недопустимое значение NULL	IP-адреса
score	Строка	Недопустимое значение NULL	Оценка CVE в диапазоне от 0,0 до 10,0
attackVector	Строка	Недопустимое значение NULL	`Network`, `Adjacent Network`, `Local` или `Physical`
описание	Строка	Недопустимое значение NULL	-

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

[
    {

        "cveId": "CVE-2007-0099",
        "score": "9.3",
        "ipAddress": "10.35.1.51",
        "attackVector": "NETWORK",
        "description": "Race condition in the msxml3 module in Microsoft XML Core
        Services 3.0, as used in Internet Explorer 6 and other
        applications, allows remote attackers to execute arbitrary
        code or cause a denial of service (application crash) via many
        nested tags in an XML document in an IFRAME, when synchronous
        document rendering is frequently disrupted with asynchronous
        events, as demonstrated using a JavaScript timer, which can
        trigger NULL pointer dereferences or memory corruption, aka
        \"MSXML Memory Corruption Vulnerability.\""
    },
    {
        "cveId": "CVE-2009-1547",
        "score": "9.3",
        "ipAddress": "10.35.1.51",
        "attackVector": "NETWORK",
        "description": "Unspecified vulnerability in Microsoft Internet Explorer 5.01
        SP4, 6, 6 SP1, and 7 allows remote attackers to execute
        arbitrary code via a crafted data stream header that triggers
        memory corruption, aka \"Data Stream Header Corruption
        Vulnerability.\""
    }
]

Тип: GET

API:

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

Примеры:

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

cves на IP-адрес (получение определенных сведений о CVEs)

Используйте этот API для запроса списка всех известных cvEs, обнаруженных на устройствах в сети для определенного IP-адреса.

URI: /api/v1/devices/cves

GET

Пример: /api/v1/devices/cves

Параметр пути

Имя	Описание:	Пример	Обязательный или необязательный
ipAddress	Получение CVEs для заданного IP-адреса.	`/api/v1/devices/<ipAddress>/cves`	Обязательное поле

Определите следующий параметр запроса, чтобы отфильтровать возвращаемые результаты.

Имя	Описание:	Пример	Обязательный или необязательный
top	Числовые. Определите, сколько наиболее оцененных CVEs для каждого IP-адреса устройства.	`/api/v1/devices/cves?top=50` `/api/v1/devices/<ipAddress>/cves?top=50`	Необязательно. По умолчанию = `100`

Тип: JSON

Массив JSON объектов CVE устройства или следующее сообщение об ошибке:

Message	Description
Сбой — ошибка	Ошибка при выполнении операции

Поля ответа успешного выполнения

Имя.	Тип	Nullable / Not nullable	Список значений
cveId	Строка	Недопустимое значение NULL	Канонический стандартный идентификатор для заданного CVE.
ipAddress	Строка	Недопустимое значение NULL	IP-адреса
score	Строка	Недопустимое значение NULL	Оценка CVE в диапазоне от 0,0 до 10,0
attackVector	Строка	Недопустимое значение NULL	`Network`, `Adjacent Network`, `Local` или `Physical`
описание	Строка	Недопустимое значение NULL	-

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

[
    {

        "cveId": "CVE-2007-0099",
        "score": "9.3",
        "ipAddress": "10.35.1.51",
        "attackVector": "NETWORK",
        "description": "Race condition in the msxml3 module in Microsoft XML Core
        Services 3.0, as used in Internet Explorer 6 and other
        applications, allows remote attackers to execute arbitrary
        code or cause a denial of service (application crash) via many
        nested tags in an XML document in an IFRAME, when synchronous
        document rendering is frequently disrupted with asynchronous
        events, as demonstrated using a JavaScript timer, which can
        trigger NULL pointer dereferences or memory corruption, aka
        \"MSXML Memory Corruption Vulnerability.\""
    },
    {
        "cveId": "CVE-2009-1547",
        "score": "9.3",
        "ipAddress": "10.35.1.51",
        "attackVector": "NETWORK",
        "description": "Unspecified vulnerability in Microsoft Internet Explorer 5.01
        SP4, 6, 6 SP1, and 7 allows remote attackers to execute
        arbitrary code via a crafted data stream header that triggers
        memory corruption, aka \"Data Stream Header Corruption
        Vulnerability.\""
    }
]

Тип: GET

API:

curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/devices/<deviceIpAddress>/cves?top=

Примеры:

С заданными параметрами запроса:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/devices/10.10.10.15/cves?top=50

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

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

URI: api/v1/devices/

GET

Параметр запроса

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

Имя	Описание:	Пример	Обязательный или необязательный
Уполномоченного	Логическое значение: - `true`: фильтрация данных только на авторизованных устройствах. - `false`: фильтрация данных только на несанкционированных устройствах.	`/api/v1/devices/`	Необязательно

Тип ответа: JSON

Массив объектов JSON, представляющих объекты устройства или следующее сообщение об ошибке:

Message	Description
Сбой — ошибка	Ошибка при выполнении операции

Поля ответа успешного выполнения

Имя.	Тип	Nullable / Not nullable	Список значений
id	Числовые. Определяет идентификатор устройства.	Недопустимое значение NULL	-
ipAddresses	Массив строк JSON.	Допускает значение NULL	-
name	Строка. Определяет имя устройства.	Недопустимое значение NULL	-
vendor	Строка. Определяет поставщика устройства.	Допускает значение NULL	-
операционная система	Перечисления. Определяет операционную систему устройства.	Допускает значение NULL	Дополнительные сведения см. в разделе "Поддерживаемые значения операционной системы".
macAddresses	Массив строк JSON.	Допускает значение NULL	-
type	Строка. Определяет тип устройства.	Недопустимое значение NULL	Может иметь значение `Unknown`. Дополнительные сведения см. в разделе "Поддерживаемые значения типов".
engineeringStation	Логическое значение. Определяет, определено ли устройство как инженерная станция или нет.	Недопустимое значение NULL	- `true`: устройство является инженерной станцией - `false`: Устройство не является инженерной станцией.
Уполномоченного	Логическое значение. Определяет, определено ли устройство как инженерная станция или нет.	Недопустимое значение NULL	- `true`: устройство является инженерной станцией - `false`: устройство не является инженерной станцией
scanner	Логическое значение. Определяет, авторизовано ли устройство.	Недопустимое значение NULL	- `true`: устройство авторизовано - `false`: устройство не авторизовано
protocols	Объект, содержащий сведения о протоколе устройства.	Допускает значение NULL	Дополнительные сведения см. в разделе Microsoft Defender для Интернета вещей: поддерживаемые протоколы Интернета вещей, OT, ICS и SCADA.
firmware	Массив `firmware` JSON объекта, который игнорирует встроенное ПО устройства.	Недопустимое значение NULL	Дополнительные сведения см. в разделе "Поддерживаемые поля встроенного ПО".
hasDynamicAddress	Логическое значение. Определяет, имеет ли устройство динамический адрес или нет.	Недопустимое значение NULL	- `true`: устройство имеет динамический адрес - `false`: устройство не имеет динамического адреса

Поддерживаемые `operatingSystem` значения

В этом разделе перечислены поддерживаемые значения для поля ответа операционной системы .

Windows 10
Windows 10 32
Windows 10 64
Windows 2000
Windows 7
Windows 7 32
Windows 7 64
Windows 8
Windows 8 32
Windows 8 64
Windows 8.1
Windows 8.1 32

Windows 8.1 64
Windows NT
Windows Server 2003
Windows Server 2003 R2
Windows Server 2008
Windows Server 2008 32
Windows Server 2008 64
Windows Server 2008 R2
Windows Server 2012
Windows Server 2012 R2
Windows Server 2016
Windows Vista

Windows Vista 32
Windows Vista 64
Windows XP
Mac OS
Mac OS X
Linux
Windows Server 2019
HP UX
Windows 11
Windows 11 32
Windows 11 64

Поддерживаемые `type` значения

В этом разделе перечислены поддерживаемые значения для поля ответа типа .

Engineering Station
PLC
Historian
HMI
Domain Controller
DB Server
Wireless Access Point
Router
Switch
Workstation
Server
IP Camera
Printer
Multicast/Broadcast
Internet
Firewall
Terminal Station
VPN Gateway
Group

IED
DCS Controller
RTU
NTP Server
Storage
Industrial Packaging System
Industrial Scale
Industrial Robot
Slot
Punch Clock
ATM
Smart TV
Game console
DVR
Door Control Panel
HVAC
Thermostat
Fire Alarm
Smart Light

Smart Switch
Fire Detector
IP Telephone
Alarm System
Alarm Siren
Smart Phone
Tablet
Wifi Pineapple
Motion Detector
Elevator
Humidity Sensor
Physical Location
Backup Server
Meter
Barcode Scanner
Uninterruptable Power Supply

Variable Frequency Drive
Robot Controller
Servo Drive
Pneumatic Device
Marquee
People Counter System
Intercom
Turnstile
I/O Adapter
Protocol Converter
KVM
Web Guiding System
Turbine
External Management
Embedded Device
Unknown

Поддерживаемые поля для значений `protocols` объектов и протоколов `name`

В этом разделе перечислены поддерживаемые поля для объекта протоколов в protocols поле ответа.

Имя.	Тип	Nullable / Not nullable	Список значений
id	Числовые. Определяет внутренний идентификатор протокола.	Недопустимое значение NULL	-
name	Строка. Определяет имя устройства.	Недопустимое значение NULL	Дополнительные сведения см. в описании параметра ниже.
ipAddresses	Массив JSON строк IP-адресов протокола.	Недопустимое значение NULL	-

Следующие значения поддерживаются как имена протоколов вне поля:

Unknown
DNP3
MODBUS
C37.118
SSH
HTTP
SYSLOG
GENERIC
ICMP
DNS
GOOSE
MMS
MALFORMED
IEC-60870
OPC UA
Siemens S7
ARP
Sampled Values
EtherNet/IP

Siemens S7 Plus
Motorola MDLC
Netbios Name Service
Netbios Datagram Service
Lightweight Access Point
CAPWAP
SNMP
DTLS
TNS
Database
SRTP
RPC
OPC
DF-1
DH-485
TDS
SMB
Suitelink
ControlNet

FTP
CDP
Profinet DCP
Profinet Real-Time
LLDP
Telnet
DeltaV
BACNet
AMS
TwinCAT
Ovation ADMD
Ovation SSRPC
Ovation DPUSTAT
Port Map
STP
Telvent OASyS Tags
Mitsubishi MELSEC
Honeywell Control Data Access

ARP
Yokogawa HIS Equalize
Emerson OpenBSI
Siemens SICAM
Omron FINS
Toshiba Computer Link
Foxboro I/A
Yokogawa VNet/IP
Emerson ROC
ABB Totalflow
Siemens Process Historian Discovery
Siemens WinCC Agent
LonTalk
Common ASCII Message
CodeSys
SAIA S-Bus
MDNS
Bently Nevada

Поддерживаемые поля встроенного ПО

В этом разделе перечислены поддерживаемые поля для объекта встроенного firmware ПО в поле ответа.

Имя.	Тип	Nullable / Not nullable	Список значений
address	Строка. Определяет IP-адрес встроенного ПО.	Недопустимое значение NULL	-
moduleAddress	Строка. Определяет адрес модуля встроенного ПО.	Не допускает значения NULL.	-
serial	Строка. Определяет серийный номер встроенного ПО.	Допускает значение NULL	-
model	Строка. Определяет модель встроенного ПО.	Допускает значение NULL	-
встроенное ПОVersion	Строка. Определяет версию встроенного ПО.	Допускает значение NULL	-
additionalData	Строка. Определяет дополнительные данные встроенного ПО.	Допускает значение NULL	-
rack	Строка. Определяет стойку встроенного ПО.	Допускает значение NULL	-
slot	Строка. Определяет слот встроенного ПО.	Допускает значение NULL	-

Тип: GET

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

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

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

Поделиться через

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

подключения (получение сведений о подключении устройства)

GET

Параметры запроса

Поля ответа успешного выполнения

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

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

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

GET

Параметр пути

Параметры запроса

Поля ответа успешного выполнения

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

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

cves (получение сведений о CVEs)

GET

Поля ответа успешного выполнения

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

cves на IP-адрес (получение определенных сведений о CVEs)

GET

Параметр пути

Поля ответа успешного выполнения

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

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

GET

Параметр запроса

Поля ответа успешного выполнения

Поддерживаемые `operatingSystem` значения

Поддерживаемые `type` значения

Поддерживаемые поля для значений `protocols` объектов и протоколов `name`

Поддерживаемые поля встроенного ПО

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

Обратная связь

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