Referenz für die Bestandsverwaltungs-APIs für OT-Überwachungssensoren

Artikel
12/18/2023

In diesem Artikel werden die APIs für die Gerätebestandsverwaltung aufgeführt, die für OT-Sensoren von Defender for IoT unterstützt werden.

connections (Abrufen von Geräteverbindungsinformationen)

Verwenden Sie diese API, um eine Liste aller Geräteverbindungen anzufordern.

URI: /api/v1/devices/connections

GET

Abfrageparameter

Definieren Sie beliebige der folgenden Abfrageparameter, um die zurückgegebenen Ergebnisse zu filtern. Wenn Sie keine Abfrageparameter festlegen, werden alle Geräteverbindungen zurückgegeben.

Name	Beschreibung des Dataflows	Beispiel	Erforderlich/optional
discoveredBefore	Numerisch. Dient zum Filtern der Ergebnisse, die vor einem bestimmten Zeitpunkt erkannt wurden. Der Zeitpunkt wird dabei in Millisekunden auf Basis der Epochenzeit sowie in der UTC-Zeitzone angegeben.	`/api/v1/devices/2/connections?discoveredBefore=<epoch>`	Optional
discoveredAfter	Numerisch. Dient zum Filtern der Ergebnisse, die nach einem bestimmten Zeitpunkt erkannt wurden. Der Zeitpunkt wird dabei in Millisekunden auf Basis der Epochenzeit sowie in der UTC-Zeitzone angegeben.	`/api/v1/devices/2/connections?discoveredAfter=<epoch>`	Optional
lastActiveInMinutes	Numerisch. Dient zum Filtern der Ergebnisse nach einem bestimmten Zeitrahmen, in dem Verbindungen aktiv waren. Wird rückwärts in Minuten ab der aktuellen Zeit definiert.	`/api/v1/devices/2/connections?lastActiveInMinutes=20`	Optional

Antworttyp: JSON

Array von JSON-Objekten, die Geräteverbindungen darstellen, oder folgende Fehlermeldung:

`Message`	BESCHREIBUNG
Fehler: error	Fehler beim Vorgang

Antwortfelder bei Erfolg

Name	type	Nullwerte zulassend/Keine Nullwerte zulassend	Liste der Werte
firstDeviceId	Numeric	Lässt keine NULL-Werte zu	-
secondDeviceId	Numeric	Lässt keine NULL-Werte zu	-
lastSeen	Numeric	Lässt keine NULL-Werte zu	Epoche (UTC)
discovered	Numeric	Lässt keine NULL-Werte zu	Epoche (UTC)
ports	Zahlenarray	Nullwerte zulässig	-
protocols	JSON-Array	Nullwerte zulässig	Protokollfeld

Protokollfelder

Name	type	Nullwerte zulassend/Keine Nullwerte zulassend
name	String	Lässt keine NULL-Werte zu
commands	Zeichenfolgenarray	Nullwerte zulässig

Antwortbeispiel

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

APIs:

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

Beispiele:

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

connections per device (Abrufen spezifischer Geräteverbindungsinformationen)

Verwenden Sie diese API, um eine Liste aller Verbindungen pro Gerät anzufordern.

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

GET

Pfadparameter

Name	Beschreibung des Dataflows	Beispiel	Erforderlich/optional
deviceId	Dient zum Abrufen der Verbindungen für das angegebene Gerät.	`/api/v1/devices/<deviceId>/connections`	Erforderlich

Abfrageparameter

Name	Beschreibung des Dataflows	Beispiel	Erforderlich/optional
discoveredBefore	Numerisch. Dient zum Filtern der Ergebnisse, die vor einem bestimmten Zeitpunkt erkannt wurden. Der Zeitpunkt wird dabei in Millisekunden auf Basis der Epochenzeit sowie in der UTC-Zeitzone angegeben.	`/api/v1/devices/2/connections?discoveredBefore=<epoch>`	Optional
discoveredAfter	Numerisch. Dient zum Filtern der Ergebnisse, die nach einem bestimmten Zeitpunkt erkannt wurden. Der Zeitpunkt wird dabei in Millisekunden auf Basis der Epochenzeit sowie in der UTC-Zeitzone angegeben.	`/api/v1/devices/2/connections?discoveredAfter=<epoch>`	Optional
lastActiveInMinutes	Numerisch. Dient zum Filtern der Ergebnisse nach einem bestimmten Zeitrahmen, in dem Verbindungen aktiv waren. Wird rückwärts in Minuten ab der aktuellen Zeit definiert.	`/api/v1/devices/2/connections?lastActiveInMinutes=20`	Optional

Antworttyp: JSON

Array von JSON-Objekten, die Geräteverbindungen darstellen, oder folgende Fehlermeldung:

`Message`	BESCHREIBUNG
Fehler: error	Fehler beim Vorgang

Antwortfelder bei Erfolg

Name	type	Nullwerte zulassend/Keine Nullwerte zulassend	Liste der Werte
firstDeviceId	Numeric	Lässt keine NULL-Werte zu	-
secondDeviceId	Numeric	Lässt keine NULL-Werte zu	-
lastSeen	Numeric	Lässt keine NULL-Werte zu	Epoche (UTC)
discovered	Numeric	Lässt keine NULL-Werte zu	Epoche (UTC)
ports	Zahlenarray	Nullwerte zulässig	-
protocols	JSON-Array	Nullwerte zulässig	Protokollfeld

Protokollfelder

Name	type	Nullwerte zulassend/Keine Nullwerte zulassend
name	String	Lässt keine NULL-Werte zu
commands	Zeichenfolgenarray	Nullwerte zulässig

Antwortbeispiel

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

APIs:

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

Beispiele:

Mit angegebenen Abfrageparametern:

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

cves (Abrufen von Informationen zu CVEs)

Mit dieser API können Sie eine absteigend nach CVE-Bewertung sortierte Liste aller bekannten CVEs anfordern, die auf Geräten im Netzwerk erkannt wurden.

URI: /api/v1/devices/cves

GET

Beispiel: /api/v1/devices/cves

Definieren Sie beliebige der folgenden Abfrageparameter, um die zurückgegebenen Ergebnisse zu filtern.

Name	Beschreibung des Dataflows	Beispiel	Erforderlich/optional
top	Numerisch. Bestimmt, wie viele CVEs mit den höchsten Bewertungen für jede Geräte-IP-Adresse abgerufen werden sollen.	`/api/v1/devices/cves?top=50` `/api/v1/devices/<ipAddress>/cves?top=50`	Optional. Standardwert: `100`

Typ: JSON

JSON-Array von Geräte-CVE-Objekten oder folgende Fehlermeldung:

`Message`	BESCHREIBUNG
Fehler: error	Fehler beim Vorgang

Antwortfelder bei Erfolg

Name	type	Nullwerte zulassend/Keine Nullwerte zulassend	Liste der Werte
cveId	String	Lässt keine NULL-Werte zu	Eine kanonische ID nach Branchenstandard für die CVE-Angabe.
ipAddress	String	Lässt keine NULL-Werte zu	IP-Adressen
score	String	Lässt keine NULL-Werte zu	Eine CVE-Bewertung zwischen 0,0 und 10,0.
attackVector	String	Lässt keine NULL-Werte zu	`Network`, `Adjacent Network`, `Local` oder `Physical`
description	String	Lässt keine NULL-Werte zu	-

Antwortbeispiel

[
    {

        "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

APIs:

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

Beispiele:

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

cves per IP address (Abrufen bestimmter Informationen zu CVEs)

Mit dieser API können Sie eine Liste aller bekannten CVEs anfordern, die auf Geräten im Netzwerk für eine bestimmte IP-Adresse erkannt werden.

URI: /api/v1/devices/cves

GET

Beispiel: /api/v1/devices/cves

Pfadparameter

Name	Beschreibung des Dataflows	Beispiel	Erforderlich/optional
ipAddress	Dient zum Abrufen von CVEs für die angegebene IP-Adresse.	`/api/v1/devices/<ipAddress>/cves`	Erforderlich

Definieren Sie den folgenden Abfrageparameter, um die zurückgegebenen Ergebnisse zu filtern:

Name	Beschreibung des Dataflows	Beispiel	Erforderlich/optional
top	Numerisch. Bestimmt, wie viele CVEs mit den höchsten Bewertungen für jede Geräte-IP-Adresse abgerufen werden sollen.	`/api/v1/devices/cves?top=50` `/api/v1/devices/<ipAddress>/cves?top=50`	Optional. Standardwert: `100`

Typ: JSON

JSON-Array von Geräte-CVE-Objekten oder folgende Fehlermeldung:

`Message`	BESCHREIBUNG
Fehler: error	Fehler beim Vorgang

Antwortfelder bei Erfolg

Name	type	Nullwerte zulassend/Keine Nullwerte zulassend	Liste der Werte
cveId	String	Lässt keine NULL-Werte zu	Eine kanonische ID nach Branchenstandard für die CVE-Angabe.
ipAddress	String	Lässt keine NULL-Werte zu	IP-Adressen
score	String	Lässt keine NULL-Werte zu	Eine CVE-Bewertung zwischen 0,0 und 10,0.
attackVector	String	Lässt keine NULL-Werte zu	`Network`, `Adjacent Network`, `Local` oder `Physical`
description	String	Lässt keine NULL-Werte zu	-

Antwortbeispiel

[
    {

        "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

APIs:

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

Beispiele:

Mit angegebenen Abfrageparametern:

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

devices (Abrufen von Geräteinformationen)

Verwenden Sie diese API, um eine Liste aller Geräte anzufordern, die von diesem Sensor erkannt wurden.

URI: api/v1/devices/

GET

Query parameter (Abfrageparameter)

Definieren Sie den folgenden Abfrageparameter, um die zurückgegebenen Ergebnisse zu filtern: Wenn Sie keine Abfrageparameter festlegen, werden alle Geräteverbindungen zurückgegeben.

Name	Beschreibung des Dataflows	Beispiel	Erforderlich/optional
authorized	Boolesch: - `true`: Filtert nur nach Daten auf autorisierten Geräten. - `false`: Filtert nur nach Daten auf nicht autorisierten Geräten.	`/api/v1/devices/`	Optional

Antworttyp: JSON

Array von JSON-Objekten, die Geräteobjekte darstellen, oder folgende Fehlermeldung:

`Message`	BESCHREIBUNG
Fehler: error	Fehler beim Vorgang

Antwortfelder bei Erfolg

Name	type	Nullwerte zulassend/Keine Nullwerte zulassend	Liste der Werte
id	Numerisch. Definiert die Geräte-ID.	Lässt keine NULL-Werte zu	-
ipAddresses	JSON-Array mit Zeichenfolgen.	Nullwerte zulässig	-
name	Eine Zeichenfolge. Definiert den Gerätenamen.	Lässt keine NULL-Werte zu	-
vendor	Eine Zeichenfolge. Definiert den Gerätehersteller.	Nullwerte zulässig	-
operatingSystem	Enumeration. Definiert das Betriebssystem des Geräts.	Nullwerte zulässig	Weitere Informationen finden Sie unter Unterstützte Werte vom Typ „operatingSystem“.
macAddresses	JSON-Array mit Zeichenfolgen.	Nullwerte zulässig	-
Typ	Eine Zeichenfolge. Definiert den Gerätetyp.	Lässt keine NULL-Werte zu	Kann `Unknown` sein. Weitere Informationen finden Sie unter Unterstützte Werte vom Typ „type“.
engineeringStation	Boolesch. Definiert, ob das Gerät als Engineeringstation definiert ist.	Lässt keine NULL-Werte zu	- `true`: Gerät ist eine Ingenieurstation - `false`: Das Gerät ist keine Engineeringstation.
authorized	Boolesch. Definiert, ob das Gerät als Engineeringstation definiert ist.	Lässt keine NULL-Werte zu	- `true`: Gerät ist eine Ingenieurstation - `false`: Das Gerät ist keine Engineeringstation.
scanner	Boolesch. Definiert, ob das Gerät autorisiert ist.	Lässt keine NULL-Werte zu	- `true`: Das Gerät ist autorisiert. - `false`: Das Gerät ist nicht autorisiert.
protocols	Objekt, das die Protokolldetails des Geräts enthält.	Nullwerte zulässig	Weitere Informationen finden Sie unter Microsoft Defender für IoT - unterstützte IoT-, OT-, ICS- und SCADA-Protokolle.
firmware	JSON-Array eines Objekts vom Typ `firmware`, das die Firmware des Geräts definiert.	Lässt keine NULL-Werte zu	Weitere Informationen finden Sie unter Unterstützte Firmwarefelder.
hasDynamicAddress	Boolesch. Definiert, ob das Gerät über eine dynamische Adresse verfügt.	Lässt keine NULL-Werte zu	- `true`: Das Gerät verfügt über eine dynamische Adresse - `false`: Das Gerät verfügt über keine dynamische Adresse.

Unterstützte Werte vom Typ `operatingSystem`

In diesem Abschnitt werden die unterstützten Werte für das Antwortfeld operatingSystem aufgeführt.

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

Unterstützte Werte vom Typ `type`

In diesem Abschnitt werden die unterstützten Werte für das Antwortfeld type aufgeführt.

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

Unterstützte Felder für das Objekt `protocols` und unterstützte Protokollwerte vom Typ `name`

In diesem Abschnitt werden die unterstützten Felder für das Objekt protocols im Antwortfeld protocols aufgelistet.

Name	type	Nullwerte zulassend/Keine Nullwerte zulassend	Liste der Werte
id	Numerisch. Definiert die interne ID des Protokolls.	Lässt keine NULL-Werte zu	-
name	Eine Zeichenfolge. Definiert den Gerätenamen.	Lässt keine NULL-Werte zu	Weitere Informationen finden Sie unten.
ipAddresses	JSON-Array mit Zeichenfolgen von Protokoll-IP-Adressen.	Lässt keine NULL-Werte zu	-

Die folgenden Werte werden standardmäßig als Protokollnamen unterstützt:

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

Unterstützte Firmwarefelder

In diesem Abschnitt werden die unterstützten Felder für das Objekt firmware im Antwortfeld firmware aufgelistet.

Name	type	Nullwerte zulassend/Keine Nullwerte zulassend	Liste der Werte
address	Eine Zeichenfolge. Definiert die Firmware-IP-Adresse.	Lässt keine NULL-Werte zu	-
moduleAddress	Eine Zeichenfolge. Definiert die Moduladresse der Firmware.	Lässt keine NULL-Werte zu.	-
serial	Eine Zeichenfolge. Definiert die Seriennummer der Firmware.	Nullwerte zulässig	-
model	Eine Zeichenfolge. Definiert das Firmwaremodell.	Nullwerte zulässig	-
firmwareVersion	Eine Zeichenfolge. Definiert die Firmwareversion.	Nullwerte zulässig	-
additionalData	Eine Zeichenfolge. Definiert zusätzliche Daten für die Firmware.	Nullwerte zulässig	-
rack	Eine Zeichenfolge. Definiert das Firmware-Rack.	Nullwerte zulässig	-
slot	Eine Zeichenfolge. Definiert den Firmware-Slot.	Nullwerte zulässig	-

Typ: GET

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

Nächste Schritte

Weitere Informationen finden Sie in der Übersicht zur API-Referenz – Defender for IoT.

Freigeben über

Referenz für die Bestandsverwaltungs-APIs für OT-Überwachungssensoren

connections (Abrufen von Geräteverbindungsinformationen)

GET

Abfrageparameter

Antwortfelder bei Erfolg

Protokollfelder

Antwortbeispiel

connections per device (Abrufen spezifischer Geräteverbindungsinformationen)

GET

Pfadparameter

Abfrageparameter

Antwortfelder bei Erfolg

Protokollfelder

Antwortbeispiel

cves (Abrufen von Informationen zu CVEs)

GET

Antwortfelder bei Erfolg

Antwortbeispiel

cves per IP address (Abrufen bestimmter Informationen zu CVEs)

GET

Pfadparameter

Antwortfelder bei Erfolg

Antwortbeispiel

devices (Abrufen von Geräteinformationen)

GET

Query parameter (Abfrageparameter)

Antwortfelder bei Erfolg

Unterstützte Werte vom Typ `operatingSystem`

Unterstützte Werte vom Typ `type`

Unterstützte Felder für das Objekt `protocols` und unterstützte Protokollwerte vom Typ `name`

Unterstützte Firmwarefelder

Nächste Schritte

Feedback

Zusätzliche Ressourcen