Készletkezelési API-referencia ot monitorozási érzékelőkhöz

Cikk
12/18/2023

Ez a cikk az IoT OT-érzékelőkhöz támogatott Defender eszközleltár-kezelési API-kat sorolja fel.

kapcsolatok (eszköz kapcsolati adatainak lekérése)

Ezzel az API-val kérheti le az összes eszközkapcsolat listáját.

URI: /api/v1/devices/connections

GET

Paraméterek lekérdezése

Adja meg az alábbi lekérdezési paraméterek bármelyikét a visszaadott eredmények szűréséhez. Ha nem állít be lekérdezési paramétereket, a rendszer minden eszközkapcsolatot visszaad.

Name	Leírás	Példa	Kötelező/ Nem kötelező
discoveredBefore	Numerikus. Szűrje azokat az eredményeket, amelyeket egy adott időpont előtt észleltek, és ahol az adott idő az időszaktól számítva ezredmásodpercben és UTC időzónában van meghatározva.	`/api/v1/devices/2/connections?discoveredBefore=<epoch>`	Választható
discoveredAfter	Numerikus. Szűrje azokat az eredményeket, amelyeket egy adott időpont után észleltek, ahol az adott idő az időtől számított ezredmásodpercben, az UTC időzónában van meghatározva.	`/api/v1/devices/2/connections?discoveredAfter=<epoch>`	Választható
lastActiveInMinutes	Numerikus. Szűrje az eredményeket egy adott időkeret szerint, amely alatt a kapcsolatok aktívak voltak. Az aktuális időponttól visszafelé, percekben definiálva.	`/api/v1/devices/2/connections?lastActiveInMinutes=20`	Választható

Válasz típusa: JSON

Az eszközkapcsolatokat jelképező JSON-objektumok tömbje vagy a következő hibaüzenet:

Üzenet	Leírás
Hiba – hiba	A művelet nem sikerült

Sikeres válaszmezők

Name	Type	Null értékű / Nem null értékű	Értékek listája
firstDeviceId	Numerikus	Nem null értékű	-
secondDeviceId	Numerikus	Nem null értékű	-
lastSeen	Numerikus	Nem null értékű	Korszak (UTC)
Felfedezett	Numerikus	Nem null értékű	Korszak (UTC)
Portok	Számtömb	Nullázható	-
Protokollok	JSON-tömb	Nullázható	Protokollmező

Protokollmezők

Name	Type	Null értékű / Nem null értékű
név	Sztring	Nem null értékű
Parancsok	Sztringtömb	Nullázható

Példa válaszra

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

Típus: GET

API-k:

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

Examples:

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

kapcsolatok eszközönként (Adott eszköz kapcsolati adatainak lekérése )

Ezzel az API-val kérheti le az eszközönkénti összes kapcsolat listáját.

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

GET

Elérési út paramétere

Name	Leírás	Példa	Kötelező/ Nem kötelező
Deviceid	Az adott eszköz kapcsolatainak lekérése.	`/api/v1/devices/<deviceId>/connections`	Szükséges

Paraméterek lekérdezése

Name	Leírás	Példa	Kötelező/ Nem kötelező
discoveredBefore	Numerikus. Szűrje azokat az eredményeket, amelyeket egy adott időpont előtt észleltek, és ahol az adott idő az időszaktól számítva ezredmásodpercben és UTC időzónában van meghatározva.	`/api/v1/devices/2/connections?discoveredBefore=<epoch>`	Választható
discoveredAfter	Numerikus. Szűrje azokat az eredményeket, amelyeket egy adott időpont után észleltek, ahol az adott idő az időtől számított ezredmásodpercben, az UTC időzónában van meghatározva.	`/api/v1/devices/2/connections?discoveredAfter=<epoch>`	Választható
lastActiveInMinutes	Numerikus. Szűrje az eredményeket egy adott időkeret szerint, amely alatt a kapcsolatok aktívak voltak. Az aktuális időponttól visszafelé, percekben definiálva.	`/api/v1/devices/2/connections?lastActiveInMinutes=20`	Választható

Válasz típusa: JSON

Az eszközkapcsolatokat jelképező JSON-objektumok tömbje vagy a következő hibaüzenet:

Üzenet	Leírás
Hiba – hiba	A művelet nem sikerült

Sikeres válaszmezők

Name	Type	Null értékű / Nem null értékű	Értékek listája
firstDeviceId	Numerikus	Nem null értékű	-
secondDeviceId	Numerikus	Nem null értékű	-
lastSeen	Numerikus	Nem null értékű	Korszak (UTC)
Felfedezett	Numerikus	Nem null értékű	Korszak (UTC)
Portok	Számtömb	Nullázható	-
Protokollok	JSON-tömb	Nullázható	Protokollmező

Protokollmezők

Name	Type	Null értékű / Nem null értékű
név	Sztring	Nem null értékű
Parancsok	Sztringtömb	Nullázható

Példa válaszra

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

Típus: GET

API-k:

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

Examples:

Megadott lekérdezési paraméterekkel:

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

cves (Információk lekérése a CVE-ről)

Ezzel az API-val kérheti le a hálózat eszközein felderített összes ismert CVE listáját csökkenő CVE-pontszám szerint rendezve.

URI: /api/v1/devices/cves

GET

Example: /api/v1/devices/cves

Adja meg az alábbi lekérdezési paraméterek bármelyikét a visszaadott eredmények szűréséhez.

Name	Leírás	Példa	Kötelező/ Nem kötelező
Top	Numerikus. Határozza meg, hogy az egyes eszközök IP-címeihez hány legfelső pontszámú CVE legyen lekérve.	`/api/v1/devices/cves?top=50` `/api/v1/devices/<ipAddress>/cves?top=50`	Opcionális. Alapértelmezett = `100`

Típus: JSON

Eszköz CVE-objektumainak JSON-tömbje vagy a következő hibaüzenet:

Üzenet	Leírás
Hiba – hiba	A művelet nem sikerült

Sikeres válaszmezők

Name	Type	Null értékű / Nem null értékű	Értékek listája
cveId	Sztring	Nem null értékű	Egy canonical, industry-standard azonosító az adott CVE-hez.
ipAddress	Sztring	Nem null értékű	IP addresses
Pontszám	Sztring	Nem null értékű	CVE-pontszám, 0,0 és 10,0 között
attackVector	Sztring	Nem null értékű	`Network`, `Adjacent Network`, `Local`vagy `Physical`
leírás	Sztring	Nem null értékű	-

Példa válaszra

[
    {

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

Típus: GET

API-k:

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

Examples:

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

cves/IP-cím (A cves-ekkel kapcsolatos konkrét információk lekérése)

Ezzel az API-val kérheti le a hálózat eszközein egy adott IP-címhez felderített összes ismert CVE listáját.

URI: /api/v1/devices/cves

GET

Example: /api/v1/devices/cves

Elérési út paramétere

Name	Leírás	Példa	Kötelező/ Nem kötelező
ipAddress	CvEs lekérése a megadott IP-címhez.	`/api/v1/devices/<ipAddress>/cves`	Szükséges

Adja meg a következő lekérdezési paramétert a visszaadott eredmények szűréséhez.

Name	Leírás	Példa	Kötelező/ Nem kötelező
Top	Numerikus. Határozza meg, hogy az egyes eszközök IP-címeihez hány legfelső pontszámú CVE legyen lekérve.	`/api/v1/devices/cves?top=50` `/api/v1/devices/<ipAddress>/cves?top=50`	Opcionális. Alapértelmezett = `100`

Típus: JSON

Eszköz CVE-objektumainak JSON-tömbje vagy a következő hibaüzenet:

Üzenet	Leírás
Hiba – hiba	A művelet nem sikerült

Sikeres válaszmezők

Name	Type	Null értékű / Nem null értékű	Értékek listája
cveId	Sztring	Nem null értékű	Egy canonical, industry-standard azonosító az adott CVE-hez.
ipAddress	Sztring	Nem null értékű	IP addresses
Pontszám	Sztring	Nem null értékű	CVE-pontszám, 0,0 és 10,0 között
attackVector	Sztring	Nem null értékű	`Network`, `Adjacent Network`, `Local`vagy `Physical`
leírás	Sztring	Nem null értékű	-

Példa válaszra

[
    {

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

Típus: GET

API-k:

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

Examples:

Megadott lekérdezési paraméterekkel:

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

eszközök (Eszközadatok lekérése)

Ezzel az API-val kérheti le az érzékelő által észlelt összes eszköz listáját.

URI: api/v1/devices/

GET

Query parameter

Adja meg a következő lekérdezési paramétert a visszaadott eredmények szűréséhez. Ha nem állít be lekérdezési paramétereket, a rendszer minden eszközkapcsolatot visszaad.

Name	Leírás	Példa	Kötelező/ Nem kötelező
Engedélyezett	Logikai: - `true`: Csak az engedélyezett eszközökön szűrjön adatokat. - `false`: Csak jogosulatlan eszközökön szűrjön adatokat.	`/api/v1/devices/`	Választható

Válasz típusa: JSON

Eszközobjektumokat ábrázoló JSON-objektumok tömbje vagy a következő hibaüzenet:

Üzenet	Leírás
Hiba – hiba	A művelet nem sikerült

Sikeres válaszmezők

Name	Type	Null értékű / Nem null értékű	Értékek listája
id	Numerikus. Meghatározza az eszközazonosítót.	Nem null értékű	-
ipAddresses	Sztringek JSON-tömbje.	Nullázható	-
név	Karakterlánc. Meghatározza az eszköz nevét.	Nem null értékű	-
Szállító	Karakterlánc. Meghatározza az eszköz szállítóját.	Nullázható	-
operatingSystem	Enum. Meghatározza az eszköz operációs rendszerét.	Nullázható	További információ: Támogatott operációsrendszer-értékek.
macAddresses	Sztringek JSON-tömbje.	Nullázható	-
type	Karakterlánc. Meghatározza az eszköz típusát.	Nem null értékű	`Unknown`Lehet . További információ: Támogatott típusértékek.
engineeringStation	Logikai. Meghatározza, hogy az eszköz mérnöki állomásként van-e definiálva.	Nem null értékű	- `true`: Az eszköz egy mérnöki állomás - `false`: Az eszköz nem mérnöki állomás.
Engedélyezett	Logikai. Meghatározza, hogy az eszköz mérnöki állomásként van-e definiálva.	Nem null értékű	- `true`: Az eszköz egy mérnöki állomás - `false`: Az eszköz nem mérnöki állomás
Szkenner	Logikai. Meghatározza, hogy az eszköz jogosult-e vagy sem.	Nem null értékű	- `true`: Az eszköz engedélyezve van - `false`: Az eszköz nincs engedélyezve
Protokollok	Az eszköz protokolladatait tartalmazó objektum.	Nullázható	További információ: Microsoft Defender for IoT – támogatott IoT-, OT-, ICS- és SCADA-protokollok.
Firmware	Egy objektum JSON-tömbje `firmware` , amely ellenáll az eszköz belső vezérlőprogramjának.	Nem null értékű	További információ: Támogatott belső vezérlőprogram mezők.
hasDynamicAddress	Logikai. Meghatározza, hogy az eszköz rendelkezik-e dinamikus címmel.	Nem null értékű	- `true`: Az eszköz dinamikus címmel rendelkezik - `false`: Az eszköz nem rendelkezik dinamikus címmel

`operatingSystem` Támogatott értékek

Ez a szakasz az operatingSystem válaszmező támogatott értékeit sorolja fel.

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` Támogatott értékek

Ez a szakasz a típusválasz mező támogatott értékeit sorolja fel.

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

Az objektum- és protokollértékek `name` támogatott mezői `protocols`

Ez a szakasz a protokollobjektum támogatott mezőit sorolja fel a protocols válaszmezőben.

Name	Type	Null értékű / Nem null értékű	Értékek listája
id	Numerikus. Meghatározza a protokoll belső azonosítóját.	Nem null értékű	-
név	Karakterlánc. Meghatározza az eszköz nevét.	Nem null értékű	További információkért lásd alább.
ipAddresses	Protokoll IP-címek sztringjeinek JSON-tömbje.	Nem null értékű	-

A protokollnevek a következő értékeket támogatják:

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

Támogatott belső vezérlőprogram-mezők

Ez a szakasz a belső vezérlőprogram-objektum támogatott mezőit sorolja fel a firmware válaszmezőben.

Name	Type	Null értékű / Nem null értékű	Értékek listája
Cím	Karakterlánc. Meghatározza a belső vezérlőprogram IP-címét.	Nem null értékű	-
moduleAddress	Karakterlánc. Meghatározza a belső vezérlőprogram modulcímét.	Nem null értékű.	-
Sorozat	Karakterlánc. Meghatározza a belső vezérlőprogram sorozatszámát.	Nullázható	-
Modell	Karakterlánc. Meghatározza a belső vezérlőprogram modelljét.	Nullázható	-
firmwareVersion	Karakterlánc. Meghatározza a belső vezérlőprogram verzióját.	Nullázható	-
additionalData	Karakterlánc. További adatokat határoz meg a belső vezérlőprogramhoz.	Nullázható	-
Rack	Karakterlánc. Meghatározza a belső vezérlőprogram-állványt.	Nullázható	-
Slot	Karakterlánc. Meghatározza a belső vezérlőprogram-pontot.	Nullázható	-

Típus: GET

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

További lépések

További információkért tekintse meg a Defender for IoT API referenciájának áttekintését.

Share via

Készletkezelési API-referencia ot monitorozási érzékelőkhöz

kapcsolatok (eszköz kapcsolati adatainak lekérése)

GET

Paraméterek lekérdezése

Sikeres válaszmezők

Protokollmezők

Példa válaszra

kapcsolatok eszközönként (Adott eszköz kapcsolati adatainak lekérése )

GET

Elérési út paramétere

Paraméterek lekérdezése

Sikeres válaszmezők

Protokollmezők

Példa válaszra

cves (Információk lekérése a CVE-ről)

GET

Sikeres válaszmezők

Példa válaszra

cves/IP-cím (A cves-ekkel kapcsolatos konkrét információk lekérése)

GET

Elérési út paramétere

Sikeres válaszmezők

Példa válaszra

eszközök (Eszközadatok lekérése)

GET

Query parameter

Sikeres válaszmezők

`operatingSystem` Támogatott értékek

`type` Támogatott értékek

Az objektum- és protokollértékek `name` támogatott mezői `protocols`

Támogatott belső vezérlőprogram-mezők

További lépések

További források