API-referens för inventeringshantering för OT-övervakningssensorer

Artikel
12/18/2023

I den här artikeln visas api:er för enhetsinventeringshantering som stöds för Defender för IoT OT-sensorer.

anslutningar (Hämta information om enhetsanslutning)

Använd det här API:et för att begära en lista över alla enhetsanslutningar.

URI: /api/v1/devices/connections

GET

Frågeparametrar

Definiera någon av följande frågeparametrar för att filtrera resultatet som returneras. Om du inte anger frågeparametrar returneras alla enhetsanslutningar.

Name	Beskrivning	Exempel	Obligatoriskt/valfritt
discoveredBefore	Numeriska. Filtrera resultat som identifierades före en viss tid, där den angivna tiden definieras i millisekunder från epoktid och i UTC-tidszon.	`/api/v1/devices/2/connections?discoveredBefore=<epoch>`	Valfritt
discoveredAfter	Numeriska. Filtrera resultat som identifierades efter en viss tid, där den angivna tiden definieras i millisekunder från epoktid och i UTC-tidszon.	`/api/v1/devices/2/connections?discoveredAfter=<epoch>`	Valfritt
lastActiveInMinutes	Numeriska. Filtrera resultat efter en angiven tidsram under vilken anslutningarna var aktiva. Definieras bakåt, i minuter, från den aktuella tiden.	`/api/v1/devices/2/connections?lastActiveInMinutes=20`	Valfritt

Svarstyp: JSON

Matris med JSON-objekt som representerar enhetsanslutningar eller följande felmeddelande:

Meddelande	beskrivning
Fel – fel	Åtgärden misslyckades

Fält för lyckade svar

Namn	Type	Nullable /Not nullable	Lista över värden
firstDeviceId	Numerisk	Inte nullbar	-
secondDeviceId	Numerisk	Inte nullbar	-
lastSeen	Numerisk	Inte nullbar	Epok (UTC)
Upptäckte	Numerisk	Inte nullbar	Epok (UTC)
Portar	Talmatris	Kan ha värdet noll	-
Protokoll	JSON-matris	Kan ha värdet noll	Protokollfält

Protokollfält

Namn	Type	Nullable /Not nullable
Namn	String	Inte nullbar
Kommandon	Strängmatris	Kan ha värdet noll

Svarsexempel

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

API:er:

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

Exempel:

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

anslutningar per enhet (Hämta specifik information om enhetsanslutning )

Använd det här API:et för att begära en lista över alla anslutningar per enhet.

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

GET

Sökvägsparameter

Name	Beskrivning	Exempel	Obligatoriskt/valfritt
Deviceid	Hämta anslutningar för den angivna enheten.	`/api/v1/devices/<deviceId>/connections`	Obligatoriskt

Frågeparametrar

Name	Beskrivning	Exempel	Obligatoriskt/valfritt
discoveredBefore	Numeriska. Filtrera resultat som identifierades före en viss tid, där den angivna tiden definieras i millisekunder från epoktid och i UTC-tidszon.	`/api/v1/devices/2/connections?discoveredBefore=<epoch>`	Valfritt
discoveredAfter	Numeriska. Filtrera resultat som identifierades efter en viss tid, där den angivna tiden definieras i millisekunder från epoktid och i UTC-tidszon.	`/api/v1/devices/2/connections?discoveredAfter=<epoch>`	Valfritt
lastActiveInMinutes	Numeriska. Filtrera resultat efter en angiven tidsram under vilken anslutningarna var aktiva. Definieras bakåt, i minuter, från den aktuella tiden.	`/api/v1/devices/2/connections?lastActiveInMinutes=20`	Valfritt

Svarstyp: JSON

Matris med JSON-objekt som representerar enhetsanslutningar eller följande felmeddelande:

Meddelande	beskrivning
Fel – fel	Åtgärden misslyckades

Fält för lyckade svar

Namn	Type	Nullable /Not nullable	Lista över värden
firstDeviceId	Numerisk	Inte nullbar	-
secondDeviceId	Numerisk	Inte nullbar	-
lastSeen	Numerisk	Inte nullbar	Epok (UTC)
Upptäckte	Numerisk	Inte nullbar	Epok (UTC)
Portar	Talmatris	Kan ha värdet noll	-
Protokoll	JSON-matris	Kan ha värdet noll	Protokollfält

Protokollfält

Namn	Type	Nullable /Not nullable
Namn	String	Inte nullbar
Kommandon	Strängmatris	Kan ha värdet noll

Svarsexempel

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

API:er:

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

Exempel:

Med angivna frågeparametrar:

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

cves (Hämta information om CVE:er)

Använd det här API:et för att begära en lista över alla kända CVE:er som identifierats på enheter i nätverket, sorterade efter fallande CVE-poäng.

URI: /api/v1/devices/cves

GET

Exempel: /api/v1/devices/cves

Definiera någon av följande frågeparametrar för att filtrera resultatet som returneras.

Name	Beskrivning	Exempel	Obligatoriskt/valfritt
Topp	Numeriska. Avgör hur många toppbesatta CVE:er som ska hämtas för varje enhets IP-adress.	`/api/v1/devices/cves?top=50` `/api/v1/devices/<ipAddress>/cves?top=50`	Valfritt. Standard = `100`

Typ: JSON

JSON-matris med enhetens CVE-objekt eller följande felmeddelande:

Meddelande	beskrivning
Fel – fel	Åtgärden misslyckades

Fält för lyckade svar

Namn	Type	Nullable /Not nullable	Lista över värden
cveId	String	Inte nullbar	Ett kanoniskt branschstandard-ID för det angivna CVE:t.
Ip	String	Inte nullbar	IP-adresser
Poäng	String	Inte nullbar	En CVE-poäng, mellan 0,0 - 10,0
attackVector	String	Inte nullbar	`Network`, `Adjacent Network`, `Local`, eller `Physical`
Beskrivning	String	Inte nullbar	-

Svarsexempel

[
    {

        "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

API:er:

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

Exempel:

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

cves per IP-adress (Hämta specifik information om CVE:er)

Använd det här API:et för att begära en lista över alla kända CVE:er som identifierats på enheter i nätverket för en specifik IP-adress.

URI: /api/v1/devices/cves

GET

Exempel: /api/v1/devices/cves

Sökvägsparameter

Name	Beskrivning	Exempel	Obligatoriskt/valfritt
Ip	Hämta CVE:er för den angivna IP-adressen.	`/api/v1/devices/<ipAddress>/cves`	Obligatoriskt

Definiera följande frågeparameter för att filtrera resultatet som returneras.

Name	Beskrivning	Exempel	Obligatoriskt/valfritt
Topp	Numeriska. Avgör hur många toppbesatta CVE:er som ska hämtas för varje enhets IP-adress.	`/api/v1/devices/cves?top=50` `/api/v1/devices/<ipAddress>/cves?top=50`	Valfritt. Standard = `100`

Typ: JSON

JSON-matris med enhetens CVE-objekt eller följande felmeddelande:

Meddelande	beskrivning
Fel – fel	Åtgärden misslyckades

Fält för lyckade svar

Namn	Type	Nullable /Not nullable	Lista över värden
cveId	String	Inte nullbar	Ett kanoniskt branschstandard-ID för det angivna CVE:t.
Ip	String	Inte nullbar	IP-adresser
Poäng	String	Inte nullbar	En CVE-poäng, mellan 0,0 - 10,0
attackVector	String	Inte nullbar	`Network`, `Adjacent Network`, `Local`, eller `Physical`
Beskrivning	String	Inte nullbar	-

Svarsexempel

[
    {

        "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

API:er:

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

Exempel:

Med angivna frågeparametrar:

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

enheter (Hämta enhetsinformation)

Använd det här API:et för att begära en lista över alla enheter som identifierats av den här sensorn.

URI: api/v1/devices/

GET

Frågeparameter

Definiera följande frågeparameter för att filtrera resultatet som returneras. Om du inte anger frågeparametrar returneras alla enhetsanslutningar.

Name	Beskrivning	Exempel	Obligatoriskt/valfritt
Auktoriserad	Boolean: - `true`: Filtrera endast efter data på auktoriserade enheter. - `false`: Filtrera endast efter data på obehöriga enheter.	`/api/v1/devices/`	Valfritt

Svarstyp: JSON

Matris med JSON-objekt som representerar enhetsobjekt eller följande felmeddelande:

Meddelande	beskrivning
Fel – fel	Åtgärden misslyckades

Fält för lyckade svar

Namn	Type	Nullable /Not nullable	Lista över värden
id	Numeriska. Definierar enhets-ID:t.	Inte nullbar	-
ipAddresses	JSON-matris med strängar.	Kan ha värdet noll	-
Namn	Sträng. Definierar enhetsnamnet.	Inte nullbar	-
Leverantör	Sträng. Definierar enhetens leverantör.	Kan ha värdet noll	-
operatingSystem	Enum. Definierar enhetens operativsystem.	Kan ha värdet noll	Mer information finns i OperatingSystem-värden som stöds.
macAddresses	JSON-matris med strängar.	Kan ha värdet noll	-
typ	Sträng. Definierar enhetstypen.	Inte nullbar	Kan vara `Unknown`. Mer information finns i Typvärden som stöds.
engineeringStation	Boolesk. Definierar om enheten definieras som en teknisk station eller inte.	Inte nullbar	- `true`: Enheten är en teknisk station - `false`: Enheten är inte en teknisk station.
Auktoriserad	Boolesk. Definierar om enheten definieras som en teknisk station eller inte.	Inte nullbar	- `true`: Enheten är en teknisk station - `false`: Enheten är inte en teknisk station
Scanner	Boolesk. Definierar om enheten är auktoriserad eller inte.	Inte nullbar	- `true`: Enheten är auktoriserad - `false`: Enheten är inte auktoriserad
Protokoll	Objekt som innehåller enhetens protokollinformation.	Kan ha värdet noll	Mer information finns i Microsoft Defender för IoT – IoT-, OT-, ICS- och SCADA-protokoll som stöds.
Firmware	JSON-matris för ett `firmware` objekt som trotsar enhetens inbyggda programvara.	Inte nullbar	Mer information finns i Fält för inbyggd programvara som stöds.
hasDynamicAddress	Boolesk. Definierar om enheten har en dynamisk adress eller inte.	Inte nullbar	- `true`: Enheten har en dynamisk adress - `false`: Enheten har ingen dynamisk adress

Värden som stöds `operatingSystem`

I det här avsnittet visas de värden som stöds för operationsSystem-svarsfältet .

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

Värden som stöds `type`

I det här avsnittet visas de värden som stöds för typsvarsfältet.

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

Fält som stöds för objekt- `protocols` och protokollvärden `name`

I det här avsnittet visas de fält som stöds för protokollobjektet i svarsfältetprotocols.

Namn	Type	Nullable /Not nullable	Lista över värden
id	Numeriska. Definierar protokollets interna ID.	Inte nullbar	-
Namn	Sträng. Definierar enhetsnamnet.	Inte nullbar	Mer information finns i nedan.
ipAddresses	JSON-matris med strängar med protokoll-IP-adresser.	Inte nullbar	-

Följande värden stöds som protokollnamn out-of-the-box:

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

Fält för inbyggd programvara som stöds

I det här avsnittet visas de fält som stöds för objektet för inbyggd programvara i svarsfältet firmware .

Namn	Type	Nullable /Not nullable	Lista över värden
Adress	Sträng. Definierar IP-adressen för den inbyggda programvaran.	Inte nullbar	-
moduleAddress	Sträng. Definierar moduladressen för den inbyggda programvaran.	Inte nullbar.	-
Seriell	Sträng. Definierar serienumret för den inbyggda programvaran.	Kan ha värdet noll	-
Modell	Sträng. Definierar modellen för inbyggd programvara.	Kan ha värdet noll	-
firmwareVersion	Sträng. Definierar versionen av den inbyggda programvaran.	Kan ha värdet noll	-
additionalData	Sträng. Definierar ytterligare data för den inbyggda programvaran.	Kan ha värdet noll	-
Rack	Sträng. Definierar rack för inbyggd programvara.	Kan ha värdet noll	-
Slot	Sträng. Definierar den inbyggda programvarans fack.	Kan ha värdet noll	-

Typ: GET

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

Nästa steg

Mer information finns i referensöversikten för Defender för IoT API.

Dela via

API-referens för inventeringshantering för OT-övervakningssensorer

anslutningar (Hämta information om enhetsanslutning)

GET

Frågeparametrar

Fält för lyckade svar

Protokollfält

Svarsexempel

anslutningar per enhet (Hämta specifik information om enhetsanslutning )

GET

Sökvägsparameter

Frågeparametrar

Fält för lyckade svar

Protokollfält

Svarsexempel

cves (Hämta information om CVE:er)

GET

Fält för lyckade svar

Svarsexempel

cves per IP-adress (Hämta specifik information om CVE:er)

GET

Sökvägsparameter

Fält för lyckade svar

Svarsexempel

enheter (Hämta enhetsinformation)

GET

Frågeparameter

Fält för lyckade svar

Värden som stöds `operatingSystem`

Värden som stöds `type`

Fält som stöds för objekt- `protocols` och protokollvärden `name`

Fält för inbyggd programvara som stöds

Nästa steg

Feedback

Ytterligare resurser