Dokumentacja interfejsu API zarządzania spisem dla czujników monitorowania OT

Artykuł
12/18/2023

W tym artykule wymieniono interfejsy API zarządzania spisem urządzeń obsługiwane dla czujników usługi Defender dla IoT OT.

połączenia (pobieranie informacji o połączeniu urządzenia)

Użyj tego interfejsu API, aby zażądać listy wszystkich połączeń urządzeń.

Identyfikator URI: /api/v1/devices/connections

GET

Parametry zapytań

Zdefiniuj dowolny z następujących parametrów zapytania, aby filtrować zwrócone wyniki. Jeśli nie ustawisz parametrów zapytania, zwracane są wszystkie połączenia urządzeń.

Nazwa/nazwisko	opis	Przykład	Wymagane/opcjonalne
discoveredBefore	Liczbowe. Przefiltruj wyniki, które zostały wykryte przed danym czasem, w którym określony czas jest zdefiniowany w milisekundach z czasu epoki i w strefie czasowej UTC.	`/api/v1/devices/2/connections?discoveredBefore=<epoch>`	Opcjonalnie
discoveredAfter	Liczbowe. Filtruj wyniki, które zostały wykryte po danym czasie, gdzie określony czas jest zdefiniowany w milisekundach z epoki i w strefie czasowej UTC.	`/api/v1/devices/2/connections?discoveredAfter=<epoch>`	Opcjonalnie
lastActiveInMinutes	Liczbowe. Filtruj wyniki według danego przedziału czasu, w którym połączenia były aktywne. Zdefiniowane wstecz(w minutach) od bieżącego czasu.	`/api/v1/devices/2/connections?lastActiveInMinutes=20`	Opcjonalnie

Typ odpowiedzi: JSON

Tablica obiektów JSON reprezentujących połączenia urządzeń lub następujący komunikat o błędzie:

Wiadomość	opis
Błąd — błąd	Operacja nie powiodła się

Pola odpowiedzi powodzenia

Nazwisko	Typ	Dopuszczana do wartości null/nie dopuszczana do wartości null	Lista wartości
firstDeviceId	Liczbowe	Nie można pustoć	-
secondDeviceId	Liczbowe	Nie można pustoć	-
lastSeen	Liczbowe	Nie można pustoć	Epoka (UTC)
Odkrył	Liczbowe	Nie można pustoć	Epoka (UTC)
Porty	Tablica liczbowa	Możliwa wartość Null	-
Protokołów	Tablica JSON	Możliwa wartość Null	Pole protokołu

Pola protokołu

Nazwisko	Typ	Dopuszczana do wartości null/nie dopuszczana do wartości null
name	String	Nie można pustoć
rozruchu kasety	Tablica ciągów	Możliwa wartość Null

Przykład odpowiedzi

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

Typ: GET

Interfejsy API:

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

Przykłady:

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

połączenia na urządzenie (pobieranie określonych informacji o połączeniu urządzenia)

Użyj tego interfejsu API, aby zażądać listy wszystkich połączeń na urządzenie.

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

GET

Parametr ścieżki

Nazwa/nazwisko	opis	Przykład	Wymagane/opcjonalne
Deviceid	Pobieranie połączeń dla danego urządzenia.	`/api/v1/devices/<deviceId>/connections`	Wymagania

Parametry zapytań

Nazwa/nazwisko	opis	Przykład	Wymagane/opcjonalne
discoveredBefore	Liczbowe. Przefiltruj wyniki, które zostały wykryte przed danym czasem, w którym określony czas jest zdefiniowany w milisekundach z czasu epoki i w strefie czasowej UTC.	`/api/v1/devices/2/connections?discoveredBefore=<epoch>`	Opcjonalnie
discoveredAfter	Liczbowe. Filtruj wyniki, które zostały wykryte po danym czasie, gdzie określony czas jest zdefiniowany w milisekundach z epoki i w strefie czasowej UTC.	`/api/v1/devices/2/connections?discoveredAfter=<epoch>`	Opcjonalnie
lastActiveInMinutes	Liczbowe. Filtruj wyniki według danego przedziału czasu, w którym połączenia były aktywne. Zdefiniowane wstecz(w minutach) od bieżącego czasu.	`/api/v1/devices/2/connections?lastActiveInMinutes=20`	Opcjonalnie

Typ odpowiedzi: JSON

Tablica obiektów JSON reprezentujących połączenia urządzeń lub następujący komunikat o błędzie:

Wiadomość	opis
Błąd — błąd	Operacja nie powiodła się

Pola odpowiedzi powodzenia

Nazwisko	Typ	Dopuszczana do wartości null/nie dopuszczana do wartości null	Lista wartości
firstDeviceId	Liczbowe	Nie można pustoć	-
secondDeviceId	Liczbowe	Nie można pustoć	-
lastSeen	Liczbowe	Nie można pustoć	Epoka (UTC)
Odkrył	Liczbowe	Nie można pustoć	Epoka (UTC)
Porty	Tablica liczbowa	Możliwa wartość Null	-
Protokołów	Tablica JSON	Możliwa wartość Null	Pole protokołu

Pola protokołu

Nazwisko	Typ	Dopuszczana do wartości null/nie dopuszczana do wartości null
name	String	Nie można pustoć
rozruchu kasety	Tablica ciągów	Możliwa wartość Null

Przykład odpowiedzi

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

Typ: GET

Interfejsy API:

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

Przykłady:

Z podanymi parametrami zapytania:

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

cves (Pobieranie informacji o CVEs)

Użyj tego interfejsu API, aby zażądać listy wszystkich znanych CVE odnalezionych na urządzeniach w sieci posortowanych według malejącego wyniku CVE.

Identyfikator URI: /api/v1/devices/cves

GET

Przykład: /api/v1/devices/cves

Zdefiniuj dowolny z następujących parametrów zapytania, aby filtrować zwrócone wyniki.

Nazwa/nazwisko	opis	Przykład	Wymagane/opcjonalne
Do góry	Liczbowe. Ustal, ile najlepiej ocenianych cves uzyskać dla każdego adresu IP urządzenia.	`/api/v1/devices/cves?top=50` `/api/v1/devices/<ipAddress>/cves?top=50`	Opcjonalny. Wartość domyślna = `100`

Typ: JSON

Tablica JSON obiektów CVE urządzenia lub następujący komunikat o błędzie:

Wiadomość	opis
Błąd — błąd	Operacja nie powiodła się

Pola odpowiedzi powodzenia

Nazwisko	Typ	Dopuszczana do wartości null/nie dopuszczana do wartości null	Lista wartości
cveId	String	Nie można pustoć	Kanoniczny identyfikator standardu branżowego dla danej cve.
Ipaddress	String	Nie można pustoć	Adresy IP
Ocena	String	Nie można pustoć	Wynik CVE z zakresu od 0,0 do 10,0
attackVector	String	Nie można pustoć	`Network`, `Adjacent Network`, lub `LocalPhysical`
opis	String	Nie można pustoć	-

Przykład odpowiedzi

[
    {

        "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.\""
    }
]

Typ: GET

Interfejsy API:

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

Przykłady:

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

cves per IP address (Pobieranie określonych informacji na CVEs)

Użyj tego interfejsu API, aby zażądać listy wszystkich znanych CVE odnalezionych na urządzeniach w sieci dla określonego adresu IP.

Identyfikator URI: /api/v1/devices/cves

GET

Przykład: /api/v1/devices/cves

Parametr ścieżki

Nazwa/nazwisko	opis	Przykład	Wymagane/opcjonalne
Ipaddress	Pobierz cves dla danego adresu IP.	`/api/v1/devices/<ipAddress>/cves`	Wymagania

Zdefiniuj następujący parametr zapytania, aby filtrować zwrócone wyniki.

Nazwa/nazwisko	opis	Przykład	Wymagane/opcjonalne
Do góry	Liczbowe. Ustal, ile najlepiej ocenianych cves uzyskać dla każdego adresu IP urządzenia.	`/api/v1/devices/cves?top=50` `/api/v1/devices/<ipAddress>/cves?top=50`	Opcjonalny. Wartość domyślna = `100`

Typ: JSON

Tablica JSON obiektów CVE urządzenia lub następujący komunikat o błędzie:

Wiadomość	opis
Błąd — błąd	Operacja nie powiodła się

Pola odpowiedzi powodzenia

Nazwisko	Typ	Dopuszczana do wartości null/nie dopuszczana do wartości null	Lista wartości
cveId	String	Nie można pustoć	Kanoniczny identyfikator standardu branżowego dla danej cve.
Ipaddress	String	Nie można pustoć	Adresy IP
Ocena	String	Nie można pustoć	Wynik CVE z zakresu od 0,0 do 10,0
attackVector	String	Nie można pustoć	`Network`, `Adjacent Network`, lub `LocalPhysical`
opis	String	Nie można pustoć	-

Przykład odpowiedzi

[
    {

        "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.\""
    }
]

Typ: GET

Interfejsy API:

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

Przykłady:

Z podanymi parametrami zapytania:

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

urządzenia (pobieranie informacji o urządzeniu)

Użyj tego interfejsu API, aby zażądać listy wszystkich urządzeń wykrytych przez ten czujnik.

Identyfikator URI: api/v1/devices/

GET

Parametr zapytania

Zdefiniuj następujący parametr zapytania, aby filtrować zwrócone wyniki. Jeśli nie ustawisz parametrów zapytania, zwracane są wszystkie połączenia urządzeń.

Nazwa/nazwisko	opis	Przykład	Wymagane/opcjonalne
Autoryzowanych	Boolean: - `true`: Filtruj dane tylko na autoryzowanych urządzeniach. - `false`: filtruj tylko pod kątem danych na nieautoryzowanych urządzeniach.	`/api/v1/devices/`	Opcjonalnie

Typ odpowiedzi: JSON

Tablica obiektów JSON reprezentujących obiekty urządzenia lub następujący komunikat o błędzie:

Wiadomość	opis
Błąd — błąd	Operacja nie powiodła się

Pola odpowiedzi powodzenia

Nazwisko	Typ	Dopuszczana do wartości null/nie dopuszczana do wartości null	Lista wartości
id	Liczbowe. Definiuje identyfikator urządzenia.	Nie można pustoć	-
ipAddresses	Tablica JSON ciągów.	Możliwa wartość Null	-
name	Ciąg. Definiuje nazwę urządzenia.	Nie można pustoć	-
Dostawcy	Ciąg. Definiuje dostawcę urządzenia.	Możliwa wartość Null	-
Operatingsystem	Enum. Definiuje system operacyjny urządzenia.	Możliwa wartość Null	Aby uzyskać więcej informacji, zobacz Obsługiwane wartości operatingSystem.
macAddresses	Tablica JSON ciągów.	Możliwa wartość Null	-
type	Ciąg. Definiuje typ urządzenia.	Nie można pustoć	Może to być `Unknown`. Aby uzyskać więcej informacji, zobacz Obsługiwane wartości typów.
engineeringStation	Wartość logiczna. Określa, czy urządzenie jest definiowane jako stacja inżynieryjna, czy nie.	Nie można pustoć	- `true`: Urządzenie jest stacją inżynieryjną - `false`: Urządzenie nie jest stacją inżynieryjną.
Autoryzowanych	Wartość logiczna. Określa, czy urządzenie jest definiowane jako stacja inżynieryjna, czy nie.	Nie można pustoć	- `true`: Urządzenie jest stacją inżynieryjną - `false`: Urządzenie nie jest stacją inżynieryjną
Skaner	Wartość logiczna. Określa, czy urządzenie jest autoryzowane, czy nie.	Nie można pustoć	- `true`: Urządzenie jest autoryzowane - `false`: Urządzenie nie jest autoryzowane
Protokołów	Obiekt zawierający szczegóły protokołu urządzenia.	Możliwa wartość Null	Aby uzyskać więcej informacji, zobacz Microsoft Defender for IoT — obsługiwane protokoły IoT, OT, ICS i SCADA.
Firmware	Tablica `firmware` JSON obiektu, który przeciwstawia się oprogramowaniu układowe urządzenia.	Nie można pustoć	Aby uzyskać więcej informacji, zobacz Obsługiwane pola oprogramowania układowego.
hasDynamicAddress	Wartość logiczna. Określa, czy urządzenie ma adres dynamiczny, czy nie.	Nie można pustoć	- `true`: Urządzenie ma adres dynamiczny - `false`: Urządzenie nie ma adresu dynamicznego

Obsługiwane `operatingSystem` wartości

W tej sekcji wymieniono obsługiwane wartości dla pola odpowiedzi 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

Obsługiwane `type` wartości

W tej sekcji wymieniono obsługiwane wartości dla pola odpowiedzi typu .

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

Obsługiwane pola dla `protocols` wartości obiektu i protokołu `name`

W tej sekcji wymieniono obsługiwane pola dla obiektu protokołów w protocols polu odpowiedzi.

Nazwisko	Typ	Dopuszczana do wartości null/nie dopuszczana do wartości null	Lista wartości
id	Liczbowe. Definiuje wewnętrzny identyfikator protokołu.	Nie można pustoć	-
name	Ciąg. Definiuje nazwę urządzenia.	Nie można pustoć	Aby uzyskać więcej informacji, zobacz poniżej.
ipAddresses	Tablica JSON ciągów adresów IP protokołu.	Nie można pustoć	-

Następujące wartości są obsługiwane jako gotowe nazwy protokołów :

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

Obsługiwane pola oprogramowania układowego

W tej sekcji wymieniono obsługiwane pola dla obiektu oprogramowania układowego w firmware polu odpowiedzi.

Nazwisko	Typ	Dopuszczana do wartości null/nie dopuszczana do wartości null	Lista wartości
Adres	Ciąg. Definiuje adres IP oprogramowania układowego.	Nie można pustoć	-
moduleAddress	Ciąg. Definiuje adres modułu oprogramowania układowego.	Nie można pustą wartość null.	-
Seryjny	Ciąg. Definiuje numer seryjny oprogramowania układowego.	Możliwa wartość Null	-
Modelu	Ciąg. Definiuje model oprogramowania układowego.	Możliwa wartość Null	-
firmwareVersion	Ciąg. Definiuje wersję oprogramowania układowego.	Możliwa wartość Null	-
additionalData	Ciąg. Definiuje dodatkowe dane dla oprogramowania układowego.	Możliwa wartość Null	-
Rack	Ciąg. Definiuje stojak oprogramowania układowego.	Możliwa wartość Null	-
Gniazdo	Ciąg. Definiuje gniazdo oprogramowania układowego.	Możliwa wartość Null	-

Typ: GET

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

Następne kroki

Aby uzyskać więcej informacji, zobacz Omówienie interfejsu API usługi Defender for IoT.

Udostępnij za pośrednictwem

Dokumentacja interfejsu API zarządzania spisem dla czujników monitorowania OT

połączenia (pobieranie informacji o połączeniu urządzenia)

GET

Parametry zapytań

Pola odpowiedzi powodzenia

Pola protokołu

Przykład odpowiedzi

połączenia na urządzenie (pobieranie określonych informacji o połączeniu urządzenia)

GET

Parametr ścieżki

Parametry zapytań

Pola odpowiedzi powodzenia

Pola protokołu

Przykład odpowiedzi

cves (Pobieranie informacji o CVEs)

GET

Pola odpowiedzi powodzenia

Przykład odpowiedzi

cves per IP address (Pobieranie określonych informacji na CVEs)

GET

Parametr ścieżki

Pola odpowiedzi powodzenia

Przykład odpowiedzi

urządzenia (pobieranie informacji o urządzeniu)

GET

Parametr zapytania

Pola odpowiedzi powodzenia

Obsługiwane `operatingSystem` wartości

Obsługiwane `type` wartości

Obsługiwane pola dla `protocols` wartości obiektu i protokołu `name`

Obsługiwane pola oprogramowania układowego

Następne kroki

Opinia

Dodatkowe zasoby