Informazioni di riferimento sulle API di gestione dell'inventario per i sensori di monitoraggio OT

Articolo
12/18/2023

Questo articolo elenca le API di gestione dell'inventario dei dispositivi supportate per i sensori OT di Defender per IoT.

connessioni (recuperare le informazioni di connessione del dispositivo)

Usare questa API per richiedere un elenco di tutte le connessioni al dispositivo.

URI: /api/v1/devices/connections

GET

Parametri di query

Definire uno dei parametri di query seguenti per filtrare i risultati restituiti. Se non si impostano parametri di query, vengono restituite tutte le connessioni del dispositivo.

Nome	Descrizione	Esempio	Obbligatoria / Facoltativa
discoveredBefore	Numerico. Filtra i risultati rilevati prima di un determinato momento, in cui l'ora specificata viene definita in millisecondi dall'ora Epoch e nel fuso orario UTC.	`/api/v1/devices/2/connections?discoveredBefore=<epoch>`	Facoltativo
discoveredAfter	Numerico. Filtra i risultati rilevati dopo un determinato periodo di tempo, in cui l'ora specificata viene definita in millisecondi dall'ora Epoch e nel fuso orario UTC.	`/api/v1/devices/2/connections?discoveredAfter=<epoch>`	Facoltativo
lastActiveInMinutes	Numerico. Filtra i risultati in base a un determinato intervallo di tempo durante il quale le connessioni erano attive. Definito all'indietro, in minuti, dall'ora corrente.	`/api/v1/devices/2/connections?lastActiveInMinutes=20`	Facoltativo

Tipo di risposta: JSON

Matrice di oggetti JSON che rappresentano le connessioni del dispositivo o il messaggio di errore seguente:

Message	Descrizione
Errore : errore	Operazione non riuscita

Campi risposta riuscita

Nome	Type	Nullable/Not nullable	Elenco di valori
firstDeviceId	Numerico	Non nullable	-
secondDeviceId	Numerico	Non nullable	-
lastSeen	Numerico	Non nullable	Epoch (UTC)
Scoperto	Numerico	Non nullable	Epoch (UTC)
Porte	Matrice numerica	Nullable	-
Protocolli	Matrice JSON	Nullable	Campo Protocollo

Campi del protocollo

Nome	Type	Nullable/Not nullable
name	string	Non nullable
Comandi	Matrice di stringhe	Nullable

Risposta di esempio

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

Tipo: GET

API:

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

Esempi:

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

connessioni per dispositivo (recuperare informazioni di connessione specifiche del dispositivo )

Usare questa API per richiedere un elenco di tutte le connessioni per dispositivo.

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

GET

Parametro Path

Nome	Descrizione	Esempio	Obbligatoria / Facoltativa
deviceId	Ottenere le connessioni per il dispositivo specificato.	`/api/v1/devices/<deviceId>/connections`	Richiesto

Parametri di query

Nome	Descrizione	Esempio	Obbligatoria / Facoltativa
discoveredBefore	Numerico. Filtra i risultati rilevati prima di un determinato momento, in cui l'ora specificata viene definita in millisecondi dall'ora Epoch e nel fuso orario UTC.	`/api/v1/devices/2/connections?discoveredBefore=<epoch>`	Facoltativo
discoveredAfter	Numerico. Filtra i risultati rilevati dopo un determinato periodo di tempo, in cui l'ora specificata viene definita in millisecondi dall'ora Epoch e nel fuso orario UTC.	`/api/v1/devices/2/connections?discoveredAfter=<epoch>`	Facoltativo
lastActiveInMinutes	Numerico. Filtra i risultati in base a un determinato intervallo di tempo durante il quale le connessioni erano attive. Definito all'indietro, in minuti, dall'ora corrente.	`/api/v1/devices/2/connections?lastActiveInMinutes=20`	Facoltativo

Tipo di risposta: JSON

Matrice di oggetti JSON che rappresentano le connessioni del dispositivo o il messaggio di errore seguente:

Message	Descrizione
Errore : errore	Operazione non riuscita

Campi risposta riuscita

Nome	Type	Nullable/Not nullable	Elenco di valori
firstDeviceId	Numerico	Non nullable	-
secondDeviceId	Numerico	Non nullable	-
lastSeen	Numerico	Non nullable	Epoch (UTC)
Scoperto	Numerico	Non nullable	Epoch (UTC)
Porte	Matrice numerica	Nullable	-
Protocolli	Matrice JSON	Nullable	Campo Protocollo

Campi del protocollo

Nome	Type	Nullable/Not nullable
name	string	Non nullable
Comandi	Matrice di stringhe	Nullable

Risposta di esempio

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

Tipo: GET

API:

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

Esempi:

Con i parametri di query specificati:

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

cves (recuperare informazioni sui CVE)

Usare questa API per richiedere un elenco di tutti i CVE noti individuati nei dispositivi della rete, ordinati in base al punteggio CVE decrescente.

URI: /api/v1/devices/cves

GET

Esempio: /api/v1/devices/cves

Definire uno dei parametri di query seguenti per filtrare i risultati restituiti.

Nome	Descrizione	Esempio	Obbligatoria / Facoltativa
top	Numerico. Determinare il numero di CVE con punteggio superiore da ottenere per ogni indirizzo IP del dispositivo.	`/api/v1/devices/cves?top=50` `/api/v1/devices/<ipAddress>/cves?top=50`	Facoltativo. Valore predefinito = `100`

Tipo: JSON

Matrice JSON di oggetti CVE del dispositivo o il messaggio di errore seguente:

Message	Descrizione
Errore : errore	Operazione non riuscita

Campi risposta riuscita

Nome	Type	Nullable/Not nullable	Elenco di valori
cveId	String	Non nullable	ID canonico standard del settore per il codice CVE specificato.
ipAddress	String	Non nullable	Indirizzi IP
Punteggio	String	Non nullable	Punteggio CVE compreso tra 0,0 e 10,0
attackVector	String	Non nullable	`Network`, `Adjacent Network`, `Local` o `Physical`
description	Stringa	Non nullable	-

Risposta di esempio

[
    {

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

Tipo: GET

API:

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

Esempi:

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

cves per indirizzo IP (recuperare informazioni specifiche sui CVE)

Usare questa API per richiedere un elenco di tutti i CVE noti individuati nei dispositivi nella rete per un indirizzo IP specifico.

URI: /api/v1/devices/cves

GET

Esempio: /api/v1/devices/cves

Parametro Path

Nome	Descrizione	Esempio	Obbligatoria / Facoltativa
ipAddress	Ottenere CVEs per l'indirizzo IP specificato.	`/api/v1/devices/<ipAddress>/cves`	Richiesto

Definire il parametro di query seguente per filtrare i risultati restituiti.

Nome	Descrizione	Esempio	Obbligatoria / Facoltativa
top	Numerico. Determinare il numero di CVE con punteggio superiore da ottenere per ogni indirizzo IP del dispositivo.	`/api/v1/devices/cves?top=50` `/api/v1/devices/<ipAddress>/cves?top=50`	Facoltativo. Valore predefinito = `100`

Tipo: JSON

Matrice JSON di oggetti CVE del dispositivo o il messaggio di errore seguente:

Message	Descrizione
Errore : errore	Operazione non riuscita

Campi risposta riuscita

Nome	Type	Nullable/Not nullable	Elenco di valori
cveId	String	Non nullable	ID canonico standard del settore per il codice CVE specificato.
ipAddress	String	Non nullable	Indirizzi IP
Punteggio	String	Non nullable	Punteggio CVE compreso tra 0,0 e 10,0
attackVector	String	Non nullable	`Network`, `Adjacent Network`, `Local` o `Physical`
description	Stringa	Non nullable	-

Risposta di esempio

[
    {

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

Tipo: GET

API:

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

Esempi:

Con i parametri di query specificati:

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

dispositivi (recuperare le informazioni sul dispositivo)

Usare questa API per richiedere un elenco di tutti i dispositivi rilevati da questo sensore.

URI: api/v1/devices/

GET

Query parameter (Parametro di query)

Definire il parametro di query seguente per filtrare i risultati restituiti. Se non si impostano parametri di query, vengono restituite tutte le connessioni del dispositivo.

Nome	Descrizione	Esempio	Obbligatoria / Facoltativa
Autorizzato	Booleano: - `true`: filtra i dati solo nei dispositivi autorizzati. - `false`: filtra i dati solo in dispositivi non autorizzati.	`/api/v1/devices/`	Facoltativo

Tipo di risposta: JSON

Matrice di oggetti JSON che rappresentano oggetti dispositivo o il messaggio di errore seguente:

Message	Descrizione
Errore : errore	Operazione non riuscita

Campi risposta riuscita

Nome	Type	Nullable/Not nullable	Elenco di valori
id	Numerico. Definisce l'ID dispositivo.	Non nullable	-
Ipaddresses	Matrice JSON di stringhe.	Nullable	-
name	String. Definisce il nome del dispositivo.	Non nullable	-
Fornitore	String. Definisce il fornitore del dispositivo.	Nullable	-
operatingSystem	Enum. Definisce il sistema operativo del dispositivo.	Nullable	Per altre informazioni, vedere Valori di operatingSystem supportati.
macAddresses	Matrice JSON di stringhe.	Nullable	-
type	String. Definisce il tipo di dispositivo.	Non nullable	Può essere `Unknown`. Per altre informazioni, vedere Valori dei tipi supportati.
engineeringStation	Booleano. Definisce se il dispositivo è definito come stazione di progettazione o meno.	Non nullable	- `true`: il dispositivo è una stazione di progettazione - `false`: il dispositivo non è una stazione di ingegneria.
Autorizzato	Booleano. Definisce se il dispositivo è definito come stazione di progettazione o meno.	Non nullable	- `true`: il dispositivo è una stazione di progettazione - `false`: il dispositivo non è una stazione di progettazione
Scanner	Booleano. Definisce se il dispositivo è autorizzato o meno.	Non nullable	- `true`: il dispositivo è autorizzato - `false`: il dispositivo non è autorizzato
Protocolli	Oggetto che contiene i dettagli del protocollo del dispositivo.	Nullable	Per altre informazioni, vedere Microsoft Defender per IoT : protocolli IoT, OT, ICS e SCADA supportati.
Firmware	Matrice JSON di un `firmware` oggetto che sfida il firmware del dispositivo.	Non nullable	Per altre informazioni, vedere Campi firmware supportati.
hasDynamicAddress	Booleano. Definisce se il dispositivo ha o meno un indirizzo dinamico.	Non nullable	- `true`: il dispositivo ha un indirizzo dinamico - `false`: il dispositivo non ha un indirizzo dinamico

Valori supportati `operatingSystem`

Questa sezione elenca i valori supportati per il campo di risposta 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

Valori supportati `type`

Questa sezione elenca i valori supportati per il campo di risposta del tipo .

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

Campi supportati per i valori di `protocols` oggetto e protocollo `name`

Questa sezione elenca i campi supportati per l'oggetto protocolli nel campo della protocols risposta.

Nome	Type	Nullable/Not nullable	Elenco di valori
id	Numerico. Definisce l'ID interno del protocollo.	Non nullable	-
name	String. Definisce il nome del dispositivo.	Non nullable	Per altre informazioni, vedere sotto.
Ipaddresses	Matrice JSON di stringhe di indirizzi IP del protocollo.	Non nullable	-

I valori seguenti sono supportati come nomi di protocollo predefiniti:

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

Campi firmware supportati

Questa sezione elenca i campi supportati per l'oggetto firmware nel campo della firmware risposta.

Nome	Type	Nullable/Not nullable	Elenco di valori
address	String. Definisce l'indirizzo IP del firmware.	Non nullable	-
moduleAddress	String. Definisce l'indirizzo del modulo del firmware.	Non ammette i valori NULL.	-
Seriale	String. Definisce il numero di serie del firmware.	Nullable	-
model	String. Definisce il modello del firmware.	Nullable	-
firmwareVersion	String. Definisce la versione del firmware.	Nullable	-
additionalData	String. Definisce dati aggiuntivi per il firmware.	Nullable	-
armadio dati	String. Definisce il rack del firmware.	Nullable	-
Slot	String. Definisce lo slot del firmware.	Nullable	-

Tipo: GET

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

Passaggi successivi

Per altre informazioni, vedere la panoramica di riferimento sull'API Defender per IoT.

Condividi tramite

Informazioni di riferimento sulle API di gestione dell'inventario per i sensori di monitoraggio OT

connessioni (recuperare le informazioni di connessione del dispositivo)

GET

Parametri di query

Campi risposta riuscita

Campi del protocollo

Risposta di esempio

connessioni per dispositivo (recuperare informazioni di connessione specifiche del dispositivo )

GET

Parametro Path

Parametri di query

Campi risposta riuscita

Campi del protocollo

Risposta di esempio

cves (recuperare informazioni sui CVE)

GET

Campi risposta riuscita

Risposta di esempio

cves per indirizzo IP (recuperare informazioni specifiche sui CVE)

GET

Parametro Path

Campi risposta riuscita

Risposta di esempio

dispositivi (recuperare le informazioni sul dispositivo)

GET

Query parameter (Parametro di query)

Campi risposta riuscita

Valori supportati `operatingSystem`

Valori supportati `type`

Campi supportati per i valori di `protocols` oggetto e protocollo `name`

Campi firmware supportati

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive