Informations de référence sur l’API de gestion des stocks pour les capteurs de monitoring OT

Article
06/01/2023

Cet article liste les API de gestion des stocks d’appareils prises en charge pour les capteurs OT Defender pour IoT.

connexions (Récupérer les informations de connexion de l’appareil)

Utilisez cette API pour demander la liste de toutes les connexions d’appareil.

URI : /api/v1/devices/connections

GET

Paramètres de requête

Définissez l’un des paramètres de requête suivants pour filtrer les résultats retournés. Si vous ne définissez pas les paramètres de requête, toutes les connexions d’appareil sont retournées.

Nom	Description	Exemple	Obligatoire/facultatif
discoveredBefore	Numérique. Filtrez les résultats détectés avant une heure donnée, avec l’heure donnée définie en millisecondes à partir de l’heure Époque et dans le fuseau horaire UTC.	`/api/v1/devices/2/connections?discoveredBefore=<epoch>`	Facultatif
discoveredAfter	Numérique. Filtrez les résultats détectés après une heure donnée, avec l’heure donnée définie en millisecondes à partir de l’heure Époque et dans le fuseau horaire UTC.	`/api/v1/devices/2/connections?discoveredAfter=<epoch>`	Facultatif
lastActiveInMinutes	Numérique. Filtrez les résultats selon une période donnée pendant laquelle les connexions étaient actives. Cette valeur est définie à rebours, en minutes, à partir de l’heure actuelle.	`/api/v1/devices/2/connections?lastActiveInMinutes=20`	Facultatif

Type de réponse : JSON

Tableau d’objets JSON qui représentent des connexions d’appareil ou message d’échec suivant :

Message	Description
Échec – erreur	L’opération a échoué

Champs de réponse de réussite

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null	Liste de valeurs
firstDeviceId	Numérique	N'accepte pas la valeur null	-
secondDeviceId	Numérique	N'accepte pas la valeur null	-
lastSeen	Numérique	N'accepte pas la valeur null	Époque (UTC)
discovered	Numérique	N'accepte pas la valeur null	Époque (UTC)
ports	Tableau de chiffres	Nullable	-
protocols	Tableau JSON	Nullable	Champ de protocole

Champs de protocole

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null
name	String	N'accepte pas la valeur null
commands	Tableau de chaînes	Nullable

Exemple de réponse

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

Type : GET

API :

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

Exemples :

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

connexions par appareil (Récupérer des informations de connexion d’appareil spécifiques)

Utilisez cette API pour demander une liste de toutes les connexions par appareil.

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

GET

Paramètre de chemin

Nom	Description	Exemple	Obligatoire/facultatif
deviceId	Obtenez les connexions de l’appareil donné.	`/api/v1/devices/<deviceId>/connections`	Obligatoire

Paramètres de requête

Nom	Description	Exemple	Obligatoire/facultatif
discoveredBefore	Numérique. Filtrez les résultats détectés avant une heure donnée, avec l’heure donnée définie en millisecondes à partir de l’heure Époque et dans le fuseau horaire UTC.	`/api/v1/devices/2/connections?discoveredBefore=<epoch>`	Facultatif
discoveredAfter	Numérique. Filtrez les résultats détectés après une heure donnée, avec l’heure donnée définie en millisecondes à partir de l’heure Époque et dans le fuseau horaire UTC.	`/api/v1/devices/2/connections?discoveredAfter=<epoch>`	Facultatif
lastActiveInMinutes	Numérique. Filtrez les résultats selon une période donnée pendant laquelle les connexions étaient actives. Cette valeur est définie à rebours, en minutes, à partir de l’heure actuelle.	`/api/v1/devices/2/connections?lastActiveInMinutes=20`	Facultatif

Type de réponse : JSON

Tableau d’objets JSON qui représentent des connexions d’appareil ou message d’échec suivant :

Message	Description
Échec – erreur	L’opération a échoué

Champs de réponse de réussite

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null	Liste de valeurs
firstDeviceId	Numérique	N'accepte pas la valeur null	-
secondDeviceId	Numérique	N'accepte pas la valeur null	-
lastSeen	Numérique	N'accepte pas la valeur null	Époque (UTC)
discovered	Numérique	N'accepte pas la valeur null	Époque (UTC)
ports	Tableau de chiffres	Nullable	-
protocols	Tableau JSON	Nullable	Champ de protocole

Champs de protocole

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null
name	String	N'accepte pas la valeur null
commands	Tableau de chaînes	Nullable

Exemple de réponse

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

Type : GET

API :

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

Exemples :

Avec des paramètres de requête donnés :

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

cves (Récupérer des informations sur les CVE)

Utilisez cette API pour demander la liste de tous les CVE connus découverts sur les appareils du réseau, triés par score CVE dans l’ordre décroissant.

URI : /api/v1/devices/cves

GET

Exemple : /api/v1/devices/cves

Définissez l’un des paramètres de requête suivants pour filtrer les résultats retournés.

Nom	Description	Exemple	Obligatoire/facultatif
top	Numérique. Déterminez le nombre de CVE de score élevé à obtenir pour chaque adresse IP d’appareil.	`/api/v1/devices/cves?top=50` `/api/v1/devices/<ipAddress>/cves?top=50`	facultatif. Valeur par défaut = `100`

Type : JSON

Tableau JSON d’objets CVE d’appareil ou message d’échec suivant :

Message	Description
Échec – erreur	L’opération a échoué

Champs de réponse de réussite

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null	Liste de valeurs
cveId	String	N'accepte pas la valeur null	ID canonique standard pour le CVE donné.
ipAddress	String	N'accepte pas la valeur null	Adresses IP
score	String	N'accepte pas la valeur null	Score CVE compris entre 0,0 et 10,0
attackVector	String	N'accepte pas la valeur null	`Network`, `Adjacent Network`, `Local` ou `Physical`
description	String	N'accepte pas la valeur null	-

Exemple de réponse

[
    {

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

Type : GET

API :

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

Exemples :

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

CVE par adresse IP (Récupérer des informations spécifiques sur les CVE)

Utilisez cette API pour demander la liste de tous les CVE connus découverts sur les appareils du réseau pour une adresse IP spécifique.

URI : /api/v1/devices/cves

GET

Exemple : /api/v1/devices/cves

Paramètre de chemin

Nom	Description	Exemple	Obligatoire/facultatif
ipAddress	Obtenez les CVE pour l’adresse IP donnée.	`/api/v1/devices/<ipAddress>/cves`	Obligatoire

Définissez l’un des paramètres de requête suivants pour filtrer les résultats retournés.

Nom	Description	Exemple	Obligatoire/facultatif
top	Numérique. Déterminez le nombre de CVE de score élevé à obtenir pour chaque adresse IP d’appareil.	`/api/v1/devices/cves?top=50` `/api/v1/devices/<ipAddress>/cves?top=50`	facultatif. Valeur par défaut = `100`

Type : JSON

Tableau JSON d’objets CVE d’appareil ou message d’échec suivant :

Message	Description
Échec – erreur	L’opération a échoué

Champs de réponse de réussite

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null	Liste de valeurs
cveId	String	N'accepte pas la valeur null	ID canonique standard pour le CVE donné.
ipAddress	String	N'accepte pas la valeur null	Adresses IP
score	String	N'accepte pas la valeur null	Score CVE compris entre 0,0 et 10,0
attackVector	String	N'accepte pas la valeur null	`Network`, `Adjacent Network`, `Local` ou `Physical`
description	String	N'accepte pas la valeur null	-

Exemple de réponse

[
    {

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

Type : GET

API :

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

Exemples :

Avec des paramètres de requête donnés :

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

appareils (Récupérer les informations des appareils)

Utilisez cette API pour demander la liste de tous les appareils détectés par ce capteur.

URI : api/v1/devices/

GET

Paramètre de requête.

Nom	Description	Exemple	Obligatoire/facultatif
autorisé	Booléen : - `true` : Filtrez les données sur les appareils autorisés uniquement. - `false` : Filtrez les données sur les appareils non autorisés uniquement.	`/api/v1/devices/`	Facultatif

Type de réponse : JSON

Tableau d’objets JSON qui représentent des objets d’appareil ou message d’échec suivant :

Message	Description
Échec – erreur	L’opération a échoué

Champs de réponse de réussite

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null	Liste de valeurs
id	Numérique. Définit l’ID de l’appareil.	N'accepte pas la valeur null	-
ipAddresses	Tableau JSON de chaînes.	Nullable	-
name	Chaîne. Définit le nom de l’appareil.	N'accepte pas la valeur null	-
vendor	Chaîne. Définit le fournisseur de l’appareil.	Nullable	-
operatingSystem	Énumération. Définit le système d’exploitation de l’appareil.	Nullable	Pour plus d’informations, consultez Valeurs operatingSystem prises en charge.
macAddresses	Tableau JSON de chaînes.	Nullable	-
type	Chaîne. Définit le type de l’appareil.	N'accepte pas la valeur null	Peut être `Unknown`. Pour plus d’informations, consultez Valeurs de type prises en charge.
engineeringStation	Propriété booléenne. Indique si l’appareil est défini en tant que station d’ingénierie ou non.	N'accepte pas la valeur null	- `true`: Appareil est une station d’ingénierie - `false` : L’appareil n’est pas une station d’ingénierie.
autorisé	Propriété booléenne. Indique si l’appareil est défini en tant que station d’ingénierie ou non.	N'accepte pas la valeur null	- `true`: Appareil est une station d’ingénierie - `false` : L’appareil n’est pas une station d’ingénierie.
scanner	Propriété booléenne. Définit si l’appareil est autorisé ou non.	N'accepte pas la valeur null	- `true`: l’appareil est autorisé - `false` : L’appareil n’est pas autorisé.
protocols	Objet qui contient les détails du protocole de l’appareil.	Nullable	Pour plus d’informations, consultez Microsoft Defender pour IoT - protocoles IoT, OT, ICS, et SCADA pris en charge.
microprogramme	Tableau JSON d’un objet `firmware` qui définit le microprogramme de l’appareil.	N'accepte pas la valeur null	Pour plus d’informations, consultez Champs de microprogramme pris en charge.
hasDynamicAddress	Propriété booléenne. Définit si l’appareil a une adresse dynamique ou non.	N'accepte pas la valeur null	- `true`: l’appareil a une adresse dynamique - `false` : L’appareil n’a pas d’adresse dynamique.

Valeurs `operatingSystem` prises en charge

Cette section liste les valeurs prises en charge pour le champ de réponse 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

Valeurs `type` prises en charge

Cette section liste les valeurs prises en charge pour le champ de réponse type.

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

Champs pris en charge pour l’objet `protocols` et les valeurs `name` de protocole

Cette section liste les champs pris en charge pour l’objet protocols dans le champ de réponse protocols.

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null	Liste de valeurs
id	Numérique. Définit l’ID interne du protocole.	N'accepte pas la valeur null	-
name	Chaîne. Définit le nom de l’appareil.	N'accepte pas la valeur null	Pour plus d’informations, voir plus bas.
ipAddresses	Tableau JSON des chaînes d’adresses IP de protocole.	N'accepte pas la valeur null	-

Les valeurs suivantes sont prises en charge en tant que noms de protocole prêts à l’emploi :

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

Champs de microprogramme pris en charge

Cette section liste les champs pris en charge pour l’objet firmware dans le champ de réponse firmware.

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null	Liste de valeurs
address	Chaîne. Définit l’adresse IP du microprogramme.	N'accepte pas la valeur null	-
moduleAddress	Chaîne. Définit l’adresse du module du microprogramme.	N'accepte pas la valeur NULL.	-
serial	Chaîne. Définit le numéro de série du microprogramme.	Nullable	-
model	Chaîne. Définit le modèle du microprogramme.	Nullable	-
firmwareVersion	Chaîne. Définit la version du microprogramme.	Nullable	-
additionalData	Chaîne. Définit des données supplémentaires pour le microprogramme.	Nullable	-
rack	Chaîne. Définit le rack du microprogramme.	Nullable	-
slot	Chaîne. Définit l’emplacement du microprogramme.	Nullable	-

Type : GET

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

Étapes suivantes

Pour plus d’informations, consultez Vue d’ensemble de référence de l’API Defender pour IoT.

Partager via

Informations de référence sur l’API de gestion des stocks pour les capteurs de monitoring OT

connexions (Récupérer les informations de connexion de l’appareil)

GET

Paramètres de requête

Champs de réponse de réussite

Champs de protocole

Exemple de réponse

connexions par appareil (Récupérer des informations de connexion d’appareil spécifiques)

GET

Paramètre de chemin

Paramètres de requête

Champs de réponse de réussite

Champs de protocole

Exemple de réponse

cves (Récupérer des informations sur les CVE)

GET

Champs de réponse de réussite

Exemple de réponse

CVE par adresse IP (Récupérer des informations spécifiques sur les CVE)

GET

Paramètre de chemin

Champs de réponse de réussite

Exemple de réponse

appareils (Récupérer les informations des appareils)

GET

Paramètre de requête.

Champs de réponse de réussite

Valeurs `operatingSystem` prises en charge

Valeurs `type` prises en charge

Champs pris en charge pour l’objet `protocols` et les valeurs `name` de protocole

Champs de microprogramme pris en charge

Étapes suivantes

Commentaires

Ressources supplémentaires