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

Cet article liste les API REST de gestion des vulnérabilités prises en charge pour les capteurs de monitoring OT Microsoft Defender pour IoT.

Les données incluses dans les réponses des API incluent les mêmes informations que si vous aviez généré un rapport de vulnérabilité à partir de la console de gestion locale.

appareils (Récupérer les informations sur les vulnérabilités des appareils)

Utilisez cette API pour demander les résultats de l’évaluation de vulnérabilité pour chaque appareil.

URI : /api/v1/reports/vulnerabilities/devices

GET

Requête

Cette API est appelée sans aucun paramètre de requête.

Réponse

Type : JSON

Tableau d’objets JSON qui représentent des appareils évalués et leurs vulnérabilités signalées.

Les appareils détectés qui n’ont pas de vulnérabilités ne sont pas inclus dans la réponse du résultat.

Champs de l’appareil

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null	Liste de valeurs
name	String	N'accepte pas la valeur null	-
ipAddresses	Tableau JSON	N'accepte pas la valeur null	-
securityScore	Numérique	N'accepte pas la valeur null	-
vendor	String	Nullable
firmwareVersion	String	Nullable	-
model	String	Nullable	-
isWirelessAccessPoint	Boolean	N'accepte pas la valeur null	True ou False
operatingSystem	Objet du système d’exploitation	Nullable	-
vulnerabilities	Objet de vulnérabilités	N'accepte pas la valeur null	-

Champs de système d'exploitation

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null	Liste de valeurs
name	String	N'accepte pas la valeur null	-
type	String	N'accepte pas la valeur null	-
version	String	Nullable	-
latestVersion	String	Nullable	-

Champs de vulnérabilités

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null	Liste de valeurs
antiViruses	Tableau de chaînes JSON	Nullable	Nom des antivirus
plainTextPasswords	Tableau JSON	Nullable	Objets de mot de passe
remoteAccess	Tableau JSON	Nullable	Objets d’accès distant
isBackupServer	Boolean	N'accepte pas la valeur null	True ou False
openedPorts	Tableau JSON	Nullable	Objets de port ouvert
isEngineeringStation	Boolean	N'accepte pas la valeur null	True ou False
isKnownScanner	Boolean	N'accepte pas la valeur null	True ou False
cves	Tableau JSON	Nullable	Objets CVE
isUnauthorized	Boolean	N'accepte pas la valeur null	True ou False
malwareIndicationsDetected	Boolean	N'accepte pas la valeur null	True ou False
weakAuthentication	Tableau de chaînes JSON	Nullable	Applications détectées qui utilisent une authentification faible

Champs de mot de passe

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null	Liste de valeurs
mot de passe	String	N'accepte pas la valeur null	-
protocol	String	N'accepte pas la valeur null	-
strength	String	N'accepte pas la valeur null	Very weak, Weak, Medium, Strong

Champs d'accès à distance

Nom	Type	Nullable	Liste de valeurs
port	Numérique	N'accepte pas la valeur null	-
transport	String	N'accepte pas la valeur null	TCP, UDP
client	String	N'accepte pas la valeur null	Adresse IP
clientSoftware	String	N'accepte pas la valeur null	Nom du protocole distant, comme SSH, VNC, Remote desktop ou Team viewer

Champs de port ouvert

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null	Liste de valeurs
port	Numérique	N'accepte pas la valeur null	-
transport	String	N'accepte pas la valeur null	TCP ou UDP
protocol	String	Nullable	-
isConflictingWithFirewall	Boolean	N'accepte pas la valeur null	True ou False

Champs CVE

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null	Liste de valeurs
id	String	N'accepte pas la valeur null	-
score	Valeur numérique, décimale	N'accepte pas la valeur null	-
description	String	N'accepte pas la valeur null	-

Exemple de réponse

[
    {
        "name": "IED \#10",
        "ipAddresses": ["10.2.1.10"],
        "securityScore": 100,
        "vendor": "ABB Switzerland Ltd, Power Systems",
        "firmwareVersion": null,
        "model": null,
        "operatingSystem": {
            "name": "ABB Switzerland Ltd, Power Systems",
            "type": "abb",
            "version": null,
            "latestVersion": null
        },
        "vulnerabilities": {
        "antiViruses": [
        "McAfee"
        ],
        "plainTextPasswords": [
            {
                "password": "123456",
                "protocol": "HTTP",
                "strength": "Very Weak"
            }
        ],
        "remoteAccess": [
            {
                "port": 5900,
                "transport": "TCP",
                "clientSoftware": "VNC",
                "client": "10.2.1.20"
            }
        ],
        "isBackupServer": true,
        "openedPorts": [
            {
                "port": 445,
                "transport": "TCP",
                "protocol": "SMP Over IP",
                "isConflictingWithFirewall": false
            },
            {
                "port": 80,
                "transport": "TCP",
                "protocol": "HTTP",
                "isConflictingWithFirewall": false
            }
        ],
        "isEngineeringStation": false,
        "isKnownScanner": false,
        "cves": [
            {
                "id": "CVE-2015-6490",
                "score": 10,
                "description": "Frosty URL - Stack-based buffer overflow on Allen-Bradley MicroLogix 1100 devices before B FRN 15.000 and 1400 devices through B FRN 15.003 allows remote attackers to execute arbitrary code via unspecified vectors"
            },
            {
                "id": "CVE-2012-6437",
                "score": 10,
                "description": "MicroLogix 1100 and 1400 do not properly perform authentication for Ethernet firmware updates, which allows remote attackers to execute arbitrary code via a Trojan horse update image"
            },
            {
                "id": "CVE-2012-6440",
                "score": 9.3,
                "description": "MicroLogix 1100 and 1400 allows man-in-the-middle attackers to conduct replay attacks via HTTP traffic."
            }
        ],
        "isUnauthorized": false,
        "malwareIndicationsDetected": true
        }
    }
]

Commande cURL

Type : GET

API :

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

Exemple :

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

sécurité (Récupérer les vulnérabilités de sécurité)

Utilisez cette API pour demander les résultats d’un rapport d’évaluation des vulnérabilités général. Cette évaluation fournit des informations sur le niveau de sécurité de votre système.

Cette évaluation est basée sur des informations générales sur le réseau et le système, et non sur l’évaluation d’un appareil spécifique.

URI : /api/v1/reports/vulnerabilities/security

GET

Requête

Cette API est appelée sans aucun paramètre de requête.

Réponse

Type : Représentation JSON d’une ou plusieurs tables de données, chacune avec des structures spécifiques et potentiellement différentes.

La réponse s’affiche dans une vue cartographique, qui fait correspondre les titres des tables à leurs lignes. Les lignes sont représentées sous la forme d’une liste d’objets avec les mêmes structures.

Champs unauthorizedDevices

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null	Liste de valeurs
address	String	Nullable	Adresse IP ou MAC de l’appareil non autorisé
name	String	Nullable	Nom de l’appareil non autorisé
firstDetectionTime	Numérique	Nullable	Horodatage de la première détection de l’appareil, en millisecondes à partir de l’heure Époque et dans le fuseau horaire UTC
lastSeen	Numérique	Nullable	Horodatage de la dernière détection de trafic envoyé depuis ou vers l’appareil, en millisecondes à partir de l’heure Époque et dans le fuseau horaire UTC

Champs illegalTrafficByFirewallRules

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null	Liste de valeurs
server	String	Nullable	Adresse IP du serveur
client	String	Nullable	Adresse IP du client
port	Numérique	Nullable	Port du serveur
transport	String	Nullable	TCP, UDPou ICMP

Champs weakFirewallRules

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null	Liste de valeurs
sources	Tableau JSON des sources	Nullable	Tableau JSON des sources dans l’un des formats suivants : - Any - ip address (host) - from ip-to ip (RANGE) - ip address, subnet mask (NETWORK)
destinations	Tableau JSON des destinations	Nullable	Tableau JSON des objets de destination, dans l’un des formats suivants : - Any - ip address (host) - from ip-to ip (RANGE) - ip address, subnet mask (NETWORK)
ports	Tableau JSON des ports	Nullable	Tableau JSON des objets de port, dans l’un des formats suivants : - Any - port (protocol, if detected) - from port-to port (protocol, if detected)

Champs accessPoints

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null	Liste de valeurs
macAddress	String	Nullable	Adresse MAC du point d’accès
vendor	String	Nullable	Nom du fournisseur du point d’accès
ipAddress	String	Nullable	Adresse IP du point d’accès ou N/A
name	String	Nullable	Nom d’appareil du point d’accès ou N/A
wireless	String	Nullable	Indique si le point d’accès est connecté à un réseau sans fil : No, Suspected ou Yes

Champs connectionsBetweenSubnets

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null	Liste de valeurs
server	String	Nullable	Adresse IP du serveur
client	String	Nullable	Adresse IP du client

Champs industrialMalwareIndicators

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null	Liste de valeurs
detectionTime	Numérique	Nullable	Horodatage de la première détection du programme malveillant, en millisecondes à partir de l’heure Époque et dans le fuseau horaire UTC
alertMessage	String	Nullable	Message d’alerte envoyé
description	String	Nullable	Description du message d’alerte
devices	Tableau JSON	N'accepte pas la valeur null	Tableau JSON des chaînes représentant des noms d’appareil

Champs internetConnections

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null	Liste de valeurs
internalAddress	String	Nullable	Adresse IP interne de la connexion
autorisé	Boolean	Nullable	Yes ou No
externalAddresses	Tableau JSON	N'accepte pas la valeur null	Tableau JSON des adresses IP externes de la connexion

Exemple de réponse

{
    "unauthorizedDevices": [
        {
            "address": "10.2.1.14",
            "name": "PLC \#14",
            "firstDetectionTime": 1462645483000,
            "lastSeen": 1462645495000,
        }
    ],
    "redundantFirewallRules": [
        {
            "sources": "170.39.3.0/255.255.255.0",
            "destinations": "Any",
            "ports": "102"
        }
    ],
    "connectionsBetweenSubnets": [
        {
            "server": "10.2.1.22",
            "client": "170.39.2.0"
        }
    ],
    "industrialMalwareIndications": [
        {
            "detectionTime": 1462645483000,
            "alertMessage": "Suspicion of Malicious Activity (Regin)",
            "description": "Suspicious network activity was detected. Such behavior might be attributed to the Regin malware.",
            "addresses": [
                "10.2.1.4",
                "10.2.1.5"
            ]
        }
    ],
    "illegalTrafficByFirewallRules": [
        {
            "server": "10.2.1.7",
            "port": "20000",
            "client": "10.2.1.4",
            "transport": "TCP"
        },
        {
            "server": "10.2.1.8",
            "port": "20000",
            "client": "10.2.1.4",
            "transport": "TCP"
        },
        {
            "server": "10.2.1.9",
            "port": "20000",
            "client": "10.2.1.4",
            "transport": "TCP"
        }
    ],
    "internetConnections": [
        {
            "internalAddress": "10.2.1.1",
            "authorized": "Yes",
            "externalAddresses": ["10.2.1.2",”10.2.1.3”]
        }
    ],
    "accessPoints": [
        {
            "macAddress": "ec:08:6b:0f:1e:22",
            "vendor": "TP-LINK TECHNOLOGIES",
            "ipAddress": "173.194.112.22",
            "name": "Enterprise AP",
            "wireless": "Yes"
        }
    ],
    "weakFirewallRules": [
        {
            "sources": "170.39.3.0/255.255.255.0",
            "destinations": "Any",
            "ports": "102"
        }
    ]
}

Commande cURL

Type : GET

API :

curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/reports/vulnerabilities/security

Exemple :

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/reports/vulnerabilities/security

opérationnel (Récupérer les vulnérabilités opérationnelles)

Utilisez cette API pour demander les résultats de l’évaluation de vulnérabilité générale. Cette évaluation fournit un aperçu de l’état opérationnel de votre réseau. Elle est basée sur des informations générales sur le réseau et le système, et non sur l’évaluation d’un appareil spécifique.

URI : /api/v1/reports/vulnerabilities/operational

GET

Requête

Cette API est appelée sans aucun paramètre de requête.

Réponse

Type : Représentation JSON d’une ou plusieurs tables de données, chacune avec des structures spécifiques et potentiellement différentes.

La réponse s’affiche dans une vue cartographique, qui fait correspondre les titres des tables à leurs lignes. Les lignes sont représentées sous la forme d’une liste d’objets avec les mêmes structures.

Champs de résultat backupServer

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null	Liste de valeurs
source	String	Nullable	Adresse IP source
destination	String	Nullable	Adresse IP de destination
port	Numérique	Nullable	Port du serveur de sauvegarde
transport	String	Nullable	Protocole de transport TCP ou UDP du serveur de sauvegarde
backupMaximalInterval	String	Nullable	Durée maximale entre les sauvegardes
lastSeenBackup	Numérique	Nullable	Horodatage du dernier affichage d’une sauvegarde, en millisecondes à partir de l’heure Époque et dans le fuseau horaire UTC

Champs de résultat ipNetworks

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null	Liste de valeurs
addresses	Numérique	N'accepte pas la valeur null	Nombre d’adresses IP découvertes dans la plage de sous-réseau.
network	String	N'accepte pas la valeur null	Adresse IP de base du sous-réseau.
mask	String	N'accepte pas la valeur null	Masque de sous-réseau.

Champs de résultat protocolProblems

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null	Liste de valeurs
protocol	String	N'accepte pas la valeur null	Protocole pour lequel une alerte de violation de protocole a été déclenchée
addresses	Tableau JSON des adresses IP	N'accepte pas la valeur null	Tableau JSON des adresses IP à l’origine de la violation
alert	String	N'accepte pas la valeur null	Titre de l’alerte déclenchée
reportTime	Numérique	N'accepte pas la valeur null	Horodatage de la dernière génération d’un rapport, en millisecondes à partir de l’heure Époque et dans le fuseau horaire UTC

Champs de résultat protocolDataVolumes

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null	Liste de valeurs
protocol	String	Nullable	Protocole détecté sur le réseau par le capteur réseau OT
volume	String	Nullable	Volume de paquets de protocole capturés par le capteur réseau OT, en Mo

Champs de résultat disconnections

Nom	Type	Autorise la valeur Null/N’accepte pas la valeur Null	Liste de valeurs
assetAddress	String	Nullable	Adresse IP de la ressource déconnectée
assetName	String	Nullable	Nom de la ressource déconnectée
lastDetectionTime	Numérique	Nullable	Horodatage de la dernière détection de la déconnexion, en millisecondes à partir de l’heure Époque et dans le fuseau horaire UTC
backToNormalTime	Numérique	Nullable	Horodatage retourné par la connexion, en millisecondes à partir de l’heure Époque et dans le fuseau horaire UTC

Exemple de réponse

{
    "backupServer": [
        {
            "backupMaximalInterval": "1 Hour, 29 Minutes",
            "source": "10.2.1.22",
            "destination": "170.39.2.14",
            "port": 10000,
            "transport": "TCP",
            "lastSeenBackup": 1462645483000
        }
    ],
    "ipNetworks": [
        {
            "addresses": "21",
            "network": "10.2.1.0",
            "mask": "255.255.255.0"
        },
        {
            "addresses": "3",
            "network": "170.39.2.0",
            "mask": "255.255.255.0"
        }
    ],
    "protocolProblems": [
        {
            "protocol": "DNP3",
            "addresses": [
                "10.2.1.7",
                "10.2.1.8"
            ],
            "alert": "Illegal DNP3 Operation",
            "reportTime": 1462645483000
        },
        {
            "protocol": "DNP3",
            "addresses": [
                "10.2.1.15"
            ],
            "alert": "Master Requested an Application Layer Confirmation",
            "reportTime": 1462645483000
        }
    ],
    "protocolDataVolumes": [
        {
            "protocol": "MODBUS (502)",
            "volume": "21.07 MB"
        },
        {
            "protocol": "SSH (22)",
            "volume": "0.001 MB"
        }
    ],
    "disconnections": [
        {
            "assetAddress": "10.2.1.3",
            "assetName": "PLC \#3",
            "lastDetectionTime": 1462645483000,
            "backToNormalTime": 1462645484000
        }
    ]
}

Commande cURL

Type : GET

API :

curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/reports/vulnerabilities/operational

Exemple :

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/reports/vulnerabilities/operational

atténuation (Récupérer les étapes d’atténuation)

Utilisez cette API pour demander une évaluation d’atténuation. Cette évaluation fournit les étapes recommandées pour atténuer les vulnérabilités détectées. Elle est basée sur des informations générales sur le réseau et le système, et non sur l’évaluation d’un appareil spécifique.

URI : /api/v1/reports/vulnerabilities/mitigation

GET

Requête

Cette API est appelée sans aucun paramètre de requête.

Réponse

Type : JSON

Objet JSON qui représente les étapes d’atténuation recommandées.

Champs de réponse

Nom du champ	Type	Nullable	Liste de valeurs
notifications	Tableau de chaînes JSON	N'accepte pas la valeur null	Étapes d’atténuation recommandées pour les vulnérabilités détectées
atténuation	Tableau JSON	N'accepte pas la valeur null	objets d’atténuation

champs d’atténuation

Nom du champ	Type	Nullable	Liste de valeurs
content	String	N'accepte pas la valeur null	Étapes d’atténuation recommandées pour les vulnérabilités détectées
scoreImprovement	Integer	Nullable	Pourcentage attendu d’amélioration de la sécurité une fois les mesures d’atténuation prises.
details	Table de charge de travail	Nullable	Table listant les recommandations d’atténuation, comme celles générées dans le rapport d’évaluation des risques. Chaque recommandation inclut des détails sur l’impact possible sur la sécurité si l’action est effectuée, etc. Pour plus d’informations, consultez Atténuation des risques.

Notes

Vous pouvez avoir plusieurs étapes d’atténuation, certaines retournées dans le champ notifications et d’autres retournées dans le champ mitigation. Les éléments avec des données scoreImprovement et details sont retournés uniquement dans le champ mitigation. Les éléments sans données scoreImprovement et details sont retournés uniquement dans le champ notifications.

Exemple de réponse

{
    "notifications": ["Firewall policy import", "Marking \"important devices\"", "Further device information import"],
    "mitigation": [{
        "content": "Install an Antivirus solution to increase protection of the workstations",
        "details": null,
        "scoreImprovement": 10
    }, {
        "content": "Investigate all malware indicators (Contact your incident response team or support.microsoft.com). When assured the problem is solved, acknowledge the alert",
        "details": {
            "name": "",
            "description": {
                "name": "",
                "important": false,
                "warning": false
            },
            "headers": ["Detection Time", "Alert Message", "Description", "Devices"],
            "rows": [
                ["03/10/2022 07:10:24", "Address Scan Detected", "Address scan detected.\nScanning address: 10.10.10.22\nScanned subnet: 10.11.0.0/16\nScanned addresses: 10.11.1.1, 10.11.20.1, 10.11.20.10, 10.11.20.100, 10.11.20.2, 10.11.20.3, 10.11.20.4, 10.11.20.5, 10.11.20.6, 10.11.20.7...\nIt is recommended to notify the security officer of the incident.", ""],
            ]
        },
        "scoreImprovement": 8
    }, {
        "content": "Install a backup server in the network",
        "details": null,
        "scoreImprovement": 5
    }, {
        "content": "Install latest security updates (Devices: 2)",
        "details": {
            "name": "",
            "description": {
                "name": "",
                "important": false,
                "warning": false
            },
            "headers": ["Name", "Address"],
            "rows": [
                ["10.13.10.5", "10.13.10.5"],
                ["192.168.1.127", "192.168.1.127"]
            ]
        },
        "scoreImprovement": 2
    }, {
        "content": "Increase password complexity for authentication (Devices: 53)",
        "details": {
            "name": "",
            "description": {
                "name": "",
                "important": false,
                "warning": false
            },
            "headers": ["Name", "Address"],
            "rows": [
                ["10.10.10.13", "10.10.10.13"],
                ["10.10.10.14", "10.10.10.14"],
                ["10.10.10.15", "10.10.10.15"],
                ["10.13.10.3", "10.13.10.3"],
                ["10.13.10.40", "10.13.10.40"],
                ["10.13.10.5", "10.13.10.5"],
                ["10.13.11.2", "10.13.11.2"],
                ["10.13.11.3", "10.13.11.3"],
                ["192.168.1.100", "192.168.1.100"],
                ["192.168.1.242", "192.168.1.242"]
            ]
        },
        "scoreImprovement": 2
    }, {
        "content": "Investigate and acknowledge all unacknowledge alerts",
        "details": {
            "name": "",
            "description": {
                "name": "",
                "important": false,
                "warning": false
            },
            "headers": ["Detection Time", "Alert Message", "Description"],
            "rows": [
                ["03/10/2022 07:10:24", "Address Scan Detected", "Address scan detected.\nScanning address: 10.10.10.22\nScanned subnet: 10.11.0.0/16\nScanned addresses: 10.11.1.1, 10.11.20.1, 10.11.20.10, 10.11.20.100, 10.11.20.2, 10.11.20.3, 10.11.20.4, 10.11.20.5, 10.11.20.6, 10.11.20.7...\nIt is recommended to notify the security officer of the incident."],
                ["03/10/2022 07:44:52", "No Traffic Detected on Sensor Interface", "The sensor stopped detecting network traffic on local_listener."]
            ]
        },
        "scoreImprovement": 1
    }]
}

Commande cURL

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" "https://<IP address>/api/v1/reports/vulnerabilities/mitigation"

Étapes suivantes

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