Naslaginformatie over voorraadbeheer-API voor OT-bewakingssensoren

Dit artikel bevat de API's voor apparaatinventarisbeheer die worden ondersteund voor Defender for IoT OT-sensoren.

verbindingen (apparaatverbindingsgegevens ophalen)

Gebruik deze API om een lijst met alle apparaatverbindingen aan te vragen.

URI: /api/v1/devices/connections

GET

Aanvragen

Queryparameters

Definieer een van de volgende queryparameters om de geretourneerde resultaten te filteren. Als u geen queryparameters instelt, worden alle apparaatverbindingen geretourneerd.

Name	Omschrijving	Voorbeeld	Vereist/optioneel
gedetecteerdBefore	Numerieke. Filter resultaten die zijn gedetecteerd vóór een bepaalde tijd, waarbij de opgegeven tijd wordt gedefinieerd in milliseconden uit epoch-tijd en in UTC-tijdzone.	/api/v1/devices/2/connections?discoveredBefore=<epoch>	Optioneel
gedetecteerdNa	Numerieke. Filter resultaten die na een bepaalde tijd zijn gedetecteerd, waarbij de opgegeven tijd wordt gedefinieerd in milliseconden uit epoch-tijd en in UTC-tijdzone.	/api/v1/devices/2/connections?discoveredAfter=<epoch>	Optioneel
lastActiveInMinutes	Numerieke. Filter resultaten op een bepaald tijdsbestek waarin verbindingen actief waren. Achterwaarts gedefinieerd, in minuten, vanaf de huidige tijd.	/api/v1/devices/2/connections?lastActiveInMinutes=20	Optioneel

Response

Antwoordtype: JSON

Matrix van JSON-objecten die apparaatverbindingen vertegenwoordigen of het volgende foutbericht:

Bericht	Beschrijving
Fout – fout	Bewerking mislukt

Antwoordvelden geslaagd

Name	Type	Nullable/Not nullable	Lijst met waarden
firstDeviceId	Numeriek	Niet nullable	-
secondDeviceId	Numeriek	Niet nullable	-
lastSeen	Numeriek	Niet nullable	Epoch (UTC)
Ontdekt	Numeriek	Niet nullable	Epoch (UTC)
Poorten	Getalmatrix	Nullable	-
Protocollen	JSON-matrix	Nullable	Protocolveld

Protocolvelden

Name	Type	Nullable/Not nullable
name	String	Niet nullable
opdrachten	Tekenreeksmatrix	Nullable

Responsvoorbeeld

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

cURL-opdracht

Type: GET

API's:

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

Voorbeelden:

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

verbindingen per apparaat (specifieke apparaatverbindingsgegevens ophalen)

Gebruik deze API om een lijst met alle verbindingen per apparaat aan te vragen.

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

GET

Aanvragen

Padparameter

Name	Omschrijving	Voorbeeld	Vereist/optioneel
deviceId	Haal verbindingen op voor het opgegeven apparaat.	/api/v1/devices/<deviceId>/connections	Vereist

Queryparameters

Name	Omschrijving	Voorbeeld	Vereist/optioneel
gedetecteerdBefore	Numerieke. Filter resultaten die zijn gedetecteerd vóór een bepaalde tijd, waarbij de opgegeven tijd wordt gedefinieerd in milliseconden uit epoch-tijd en in UTC-tijdzone.	/api/v1/devices/2/connections?discoveredBefore=<epoch>	Optioneel
gedetecteerdNa	Numerieke. Filter resultaten die na een bepaalde tijd zijn gedetecteerd, waarbij de opgegeven tijd wordt gedefinieerd in milliseconden uit epoch-tijd en in UTC-tijdzone.	/api/v1/devices/2/connections?discoveredAfter=<epoch>	Optioneel
lastActiveInMinutes	Numerieke. Filter resultaten op een bepaald tijdsbestek waarin verbindingen actief waren. Achterwaarts gedefinieerd, in minuten, vanaf de huidige tijd.	/api/v1/devices/2/connections?lastActiveInMinutes=20	Optioneel

Response

Antwoordtype: JSON

Matrix van JSON-objecten die apparaatverbindingen vertegenwoordigen of het volgende foutbericht:

Bericht	Beschrijving
Fout – fout	Bewerking mislukt

Antwoordvelden geslaagd

Name	Type	Nullable/Not nullable	Lijst met waarden
firstDeviceId	Numeriek	Niet nullable	-
secondDeviceId	Numeriek	Niet nullable	-
lastSeen	Numeriek	Niet nullable	Epoch (UTC)
Ontdekt	Numeriek	Niet nullable	Epoch (UTC)
Poorten	Getalmatrix	Nullable	-
Protocollen	JSON-matrix	Nullable	Protocolveld

Protocolvelden

Name	Type	Nullable/Not nullable
name	String	Niet nullable
opdrachten	Tekenreeksmatrix	Nullable

Responsvoorbeeld

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

cURL-opdracht

Type: GET

API's:

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

Voorbeelden:

Met opgegeven queryparameters:

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

cves (informatie ophalen over CVE's)

Gebruik deze API om een lijst aan te vragen met alle bekende CVE's die zijn gedetecteerd op apparaten in het netwerk, gesorteerd op aflopende CVE-score.

URI: /api/v1/devices/cves

GET

Aanvragen

Voorbeeld: /api/v1/devices/cves

Definieer een van de volgende queryparameters om de geretourneerde resultaten te filteren.

Name	Omschrijving	Voorbeeld	Vereist/optioneel
Boven	Numerieke. Bepaal hoeveel cv's met de hoogste score moeten worden opgehaald voor elk IP-adres van het apparaat.	/api/v1/devices/cves?top=50 /api/v1/devices/<ipAddress>/cves?top=50	Optioneel. Standaard = 100

Response

Type: JSON

JSON-matrix van CVE-objecten van apparaten of het volgende foutbericht:

Bericht	Beschrijving
Fout – fout	Bewerking mislukt

Antwoordvelden geslaagd

Name	Type	Nullable/Not nullable	Lijst met waarden
cveId	String	Niet nullable	Een canonieke, industriestandaard id voor de opgegeven CVE.
ipAddress	String	Niet nullable	IP-adressen
Score	String	Niet nullable	Een CVE-score, tussen 0,0 en 10,0
attackVector	String	Niet nullable	Network, , Adjacent Networkof LocalPhysical
beschrijving	String	Niet nullable	-

Responsvoorbeeld

[
    {

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

cURL-opdracht

Type: GET

API's:

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

Voorbeelden:

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

cves per IP-adres (specifieke informatie over CVE's ophalen)

Gebruik deze API om een lijst aan te vragen met alle bekende CV's die zijn gedetecteerd op apparaten in het netwerk voor een specifiek IP-adres.

URI: /api/v1/devices/cves

GET

Aanvragen

Voorbeeld: /api/v1/devices/cves

Padparameter

Name	Omschrijving	Voorbeeld	Vereist/optioneel
ipAddress	HAAL CV's op voor het opgegeven IP-adres.	/api/v1/devices/<ipAddress>/cves	Vereist

Definieer de volgende queryparameter om de geretourneerde resultaten te filteren.

Name	Omschrijving	Voorbeeld	Vereist/optioneel
Boven	Numerieke. Bepaal hoeveel cv's met de hoogste score moeten worden opgehaald voor elk IP-adres van het apparaat.	/api/v1/devices/cves?top=50 /api/v1/devices/<ipAddress>/cves?top=50	Optioneel. Standaard = 100

Response

Type: JSON

JSON-matrix van CVE-objecten van apparaten of het volgende foutbericht:

Bericht	Beschrijving
Fout – fout	Bewerking mislukt

Antwoordvelden geslaagd

Name	Type	Nullable/Not nullable	Lijst met waarden
cveId	String	Niet nullable	Een canonieke, industriestandaard id voor de opgegeven CVE.
ipAddress	String	Niet nullable	IP-adressen
Score	String	Niet nullable	Een CVE-score, tussen 0,0 en 10,0
attackVector	String	Niet nullable	Network, , Adjacent Networkof LocalPhysical
beschrijving	String	Niet nullable	-

Responsvoorbeeld

[
    {

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

cURL-opdracht

Type: GET

API's:

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

Voorbeelden:

Met opgegeven queryparameters:

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

apparaten (apparaatgegevens ophalen)

Gebruik deze API om een lijst aan te vragen van alle apparaten die door deze sensor zijn gedetecteerd.

URI: api/v1/devices/

GET

Aanvragen

Queryparameter

Definieer de volgende queryparameter om de geretourneerde resultaten te filteren. Als u geen queryparameters instelt, worden alle apparaatverbindingen geretourneerd.

Name	Omschrijving	Voorbeeld	Vereist/optioneel
Gemachtigd	Booleaanse: - true: Filter alleen op gegevens op geautoriseerde apparaten. - false: Filter alleen op gegevens op niet-geautoriseerde apparaten.	/api/v1/devices/	Optioneel

Response

Antwoordtype: JSON

Matrix van JSON-objecten die apparaatobjecten vertegenwoordigen of het volgende foutbericht:

Bericht	Beschrijving
Fout – fout	Bewerking mislukt

Antwoordvelden geslaagd

Name	Type	Nullable/Not nullable	Lijst met waarden
id	Numerieke. Hiermee definieert u de apparaat-id.	Niet nullable	-
ipAddresses	JSON-matrix met tekenreeksen.	Nullable	-
name	Tekenreeks. Hiermee definieert u de apparaatnaam.	Niet nullable	-
Leverancier	Tekenreeks. Definieert de leverancier van het apparaat.	Nullable	-
Operatingsystem	Enum. Definieert het besturingssysteem van het apparaat.	Nullable	Zie Ondersteunde waarden voor het besturingssysteem voor meer informatie.
macAddresses	JSON-matrix met tekenreeksen.	Nullable	-
type	Tekenreeks. Hiermee definieert u het apparaattype.	Niet nullable	Kan zijn Unknown. Zie Ondersteunde typewaarden voor meer informatie.
engineeringStation	Booleaans. Hiermee definieert u of het apparaat is gedefinieerd als een technisch station of niet.	Niet nullable	- true: Apparaat is een technisch station - false: Apparaat is geen technisch station.
Gemachtigd	Booleaans. Hiermee definieert u of het apparaat is gedefinieerd als een technisch station of niet.	Niet nullable	- true: Apparaat is een technisch station - false: Apparaat is geen technisch station
Scanner	Booleaans. Hiermee definieert u of het apparaat is geautoriseerd of niet.	Niet nullable	- true: Apparaat is geautoriseerd - false: Apparaat is niet geautoriseerd
Protocollen	Object dat de protocolgegevens van het apparaat bevat.	Nullable	Zie Microsoft Defender for IoT - ondersteunde IoT-, OT-, ICS- en SCADA-protocollen voor meer informatie.
Firmware	JSON-matrix van een firmware object dat de firmware van het apparaat afdificeert.	Niet nullable	Zie ondersteunde firmwarevelden voor meer informatie.
hasDynamicAddress	Booleaans. Hiermee definieert u of het apparaat een dynamisch adres heeft of niet.	Niet nullable	- true: Het apparaat heeft een dynamisch adres - false: Het apparaat heeft geen dynamisch adres

Ondersteunde operatingSystem waarden

In deze sectie worden de ondersteunde waarden voor het antwoordveld operatingSystem weergegeven.

• 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

Ondersteunde type waarden

In deze sectie worden de ondersteunde waarden voor het antwoordveld van het type weergegeven.

• 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

Ondersteunde velden voor de protocols object- en protocolwaarden name

In deze sectie worden de ondersteunde velden voor het protocolobject in het protocols antwoordveld weergegeven.

Name	Type	Nullable/Not nullable	Lijst met waarden
id	Numerieke. Definieert de interne id van het protocol.	Niet nullable	-
name	Tekenreeks. Hiermee definieert u de apparaatnaam.	Niet nullable	Zie hieronder voor meer informatie.
ipAddresses	JSON-matrix met tekenreeksen van protocol-IP-adressen.	Niet nullable	-

De volgende waarden worden standaard ondersteund als protocolnamen :

• 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

Ondersteunde firmwarevelden

In deze sectie vindt u de ondersteunde velden voor het firmwareobject in het firmware antwoordveld.

Name	Type	Nullable/Not nullable	Lijst met waarden
Adres	Tekenreeks. Hiermee definieert u het IP-adres van de firmware.	Niet nullable	-
moduleAddress	Tekenreeks. Definieert het moduleadres van de firmware.	Niet nullable.	-
Seriële	Tekenreeks. Hiermee definieert u het serienummer van de firmware.	Nullable	-
Model	Tekenreeks. Definieert het firmwaremodel.	Nullable	-
firmwareVersion	Tekenreeks. Hiermee definieert u de firmwareversie.	Nullable	-
Additionaldata	Tekenreeks. Definieert aanvullende gegevens voor de firmware.	Nullable	-
Rack	Tekenreeks. Definieert het firmwarerek.	Nullable	-
Sleuf	Tekenreeks. Definieert de firmwaresite.	Nullable	-

cURL-opdracht

Type: GET

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

Volgende stappen

Zie het overzicht van de defender voor IoT-API voor meer informatie.