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

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

Requête

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

Réponse

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

Commande cURL

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

Requête

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

Réponse

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

Commande cURL

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

Requête

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

Réponse

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

Commande cURL

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

Requête

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

Réponse

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

Commande cURL

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

Requête

Paramètre 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
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

Réponse

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	-

Commande cURL

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.