Informazioni di riferimento sulle API di gestione delle vulnerabilità per i sensori di monitoraggio OT

Questo articolo elenca le API REST gestione delle vulnerabilità supportate per i sensori di monitoraggio OT di Microsoft Defender per IoT.

I dati inclusi nelle risposte dell'API includono le stesse informazioni di se è stato generato un report sulla vulnerabilità dalla console del sensore OT.

dispositivi (recuperare le informazioni sulla vulnerabilità del dispositivo)

Usare questa API per richiedere i risultati della valutazione della vulnerabilità per ogni dispositivo.

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

GET

Richiedi

Questa API viene chiamata senza parametri di richiesta.

Response

Tipo: JSON

Matrice di oggetti JSON che rappresentano i dispositivi valutati e le relative vulnerabilità segnalate.

I dispositivi che non hanno vulnerabilità non sono inclusi nella risposta del risultato.

Campi dispositivo

Nome	Type	Nullable/Not nullable	Elenco di valori
name	string	Non nullable	-
ipAddresses	Matrice JSON	Non nullable	-
securityScore	Numerico	Non nullable	-
venditore	String	Nullable
firmwareVersion	String	Nullable	-
model	String	Nullable	-
isWirelessAccessPoint	Booleano	Non nullable	True oppure False
operatingSystem	Oggetto sistema operativo	Nullable	-
vulnerabilità	Oggetto Vulnerabilità	Non nullable	-

Campi del sistema operativo

Nome	Type	Nullable/Not nullable	Elenco di valori
name	string	Non nullable	-
type	String	Non nullable	-
version	String	Nullable	-
latestVersion	String	Nullable	-

Campi vulnerabilità

Nome	Type	Nullable/Not nullable	Elenco di valori
antiViruses	Matrice di stringhe JSON	Nullable	Nomi antivirus
plainTextPasswords	Matrice JSON	Nullable	Oggetti Password
remoteAccess	Matrice JSON	Nullable	Oggetti di accesso remoto
isBackupServer	Booleano	Non nullable	True oppure False
openedPorts	Matrice JSON	Nullable	Oggetti porta aperti
isEngineeringStation	Booleano	Non nullable	True oppure False
isKnownScanner	Booleano	Non nullable	True oppure False
cves	Matrice JSON	Nullable	OGGETTI CVE
isUnauthorized	Booleano	Non nullable	True oppure False
malwareIndicationsDetected	Booleano	Non nullable	True oppure False
weakAuthentication	Matrice di stringhe JSON	Nullable	Applicazioni rilevate che usano l'autenticazione debole

Campi password

Nome	Type	Nullable/Not nullable	Elenco di valori
password	String	Non nullable	-
protocol	String	Non nullable	-
forza	String	Non nullable	Very weak, Weak, MediumStrong

Campi di accesso remoto

Nome	Type	Nullable	Elenco di valori
port	Numerico	Non nullable	-
trasporto	String	Non nullable	TCP, UDP
client	String	Non nullable	Indirizzo IP
clientSoftware	String	Non nullable	Nome del protocollo remoto, ad esempio SSH, VNC, Remote desktopo Team viewer

Aprire i campi porta

Nome	Type	Nullable/Not nullable	Elenco di valori
port	Numerico	Non nullable	-
trasporto	String	Non nullable	TCP oppure UDP
protocol	String	Nullable	-
isConflictingWithFirewall	Booleano	Non nullable	True oppure False

Campi CVE

Nome	Type	Nullable/Not nullable	Elenco di valori
id	String	Non nullable	-
Punteggio	Valore numerico, decimale	Non nullable	-
description	Stringa	Non nullable	-

Risposta di esempio

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

Comando cURL

Tipo: GET

API:

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

Esempio:

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

sicurezza (recuperare le vulnerabilità di sicurezza)

Usare questa API per richiedere i risultati di un report generale sulla valutazione della vulnerabilità. Questa valutazione fornisce informazioni dettagliate sul livello di sicurezza del sistema.

Questa valutazione si basa su informazioni generali sulla rete e sul sistema e non su una valutazione specifica del dispositivo.

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

GET

Richiedi

Questa API viene chiamata senza parametri di richiesta.

Response

Tipo: rappresentazione JSON di una o più tabelle di dati, ognuna con strutture specifiche e potenzialmente diverse.

La risposta viene visualizzata in una visualizzazione mappa, che esegue il mapping dei titoli delle tabelle alle righe della tabella. Le righe sono rappresentate come un elenco di oggetti con le stesse strutture.

campi unauthorizedDevices

Nome	Type	Nullable/Not nullable	Elenco di valori
address	String	Nullable	Indirizzo IP o MAC del dispositivo non autorizzato
name	string	Nullable	Nome del dispositivo non autorizzato
firstDetectionTime	Numerico	Nullable	Timestamp rilevato per la prima volta nel dispositivo, in millisecondi dall'ora Epoch e nel fuso orario UTC
lastSeen	Numerico	Nullable	Timestamp dell'ultimo rilevamento del traffico da o verso il dispositivo, espresso in millisecondi dall'ora Epoch e nel fuso orario UTC

campi illegalTrafficByFirewallRules

Nome	Type	Nullable/Not nullable	Elenco di valori
server	String	Nullable	Indirizzo IP del server
client	String	Nullable	Indirizzo IP client
port	Numerico	Nullable	Porta del server
trasporto	String	Nullable	TCP, UDP o ICMP

campi weakFirewallRules

Nome	Type	Nullable/Not nullable	Elenco di valori
sources	Matrice JSON di origini	Nullable	Matrice JSON di origini in uno dei formati seguenti: - Any - ip address (host) - from ip-to ip (RANGE) - ip address, subnet mask (NETWORK)
Destinazioni	Matrice JSON di destinazioni	Nullable	Matrice JSON di oggetti di destinazione, in uno dei formati seguenti: - Any - ip address (host) - from ip-to ip (RANGE) - ip address, subnet mask (NETWORK)
porte	Matrice JSON di porte	Nullable	Matrice JSON di oggetti porta, in uno dei formati seguenti: - Any - port (protocol, if detected) - from port-to port (protocol, if detected)

Campi accessPoints

Nome	Type	Nullable/Not nullable	Elenco di valori
macAddress	String	Nullable	Indirizzo MAC del punto di accesso
venditore	String	Nullable	Nome fornitore del punto di accesso
ipAddress	String	Nullable	Indirizzo IP del punto di accesso o N/D
name	string	Nullable	Nome del dispositivo del punto di accesso o N/A
wireless	String	Nullable	Indica se il punto di accesso è connesso a una rete wireless: No, Suspectedo Yes

campi connectionsBetweenSubnets

Nome	Type	Nullable/Not nullable	Elenco di valori
server	String	Nullable	Indirizzo IP del server
client	String	Nullable	Indirizzo IP del client

campi industrialMalwareIndicators

Nome	Type	Nullable/Not nullable	Elenco di valori
detectionTime	Numerico	Nullable	Timestamp il malware è stato rilevato per la prima volta, in millisecondi dall'ora Epoch e nel fuso orario UTC
alertMessage	String	Nullable	Messaggio di avviso inviato
description	Stringa	Nullable	Descrizione del messaggio di avviso
Dispositivi	Matrice JSON	Non nullable	Matrice JSON di stringhe che rappresentano i nomi dei dispositivi

Campi internetConnections

Nome	Type	Nullable/Not nullable	Elenco di valori
internalAddress	String	Nullable	Indirizzo IP interno della connessione
autorizzato	Booleano	Nullable	Yes oppure No
externalAddresses	Matrice JSON	Non nullable	Matrice JSON degli indirizzi IP esterni della connessione

Risposta di esempio

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

Comando cURL

Tipo: GET

API:

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

Esempio:

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

operativo (recuperare le vulnerabilità operative)

Usare questa API per richiedere i risultati di una valutazione generale della vulnerabilità. Questa valutazione fornisce informazioni dettagliate sullo stato operativo della rete. Si basa su informazioni generali sulla rete e sul sistema e non su una valutazione specifica del dispositivo.

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

GET

Richiedi

Questa API viene chiamata senza parametri di richiesta.

Response

Tipo: rappresentazione JSON di una o più tabelle di dati, ognuna con strutture specifiche e potenzialmente diverse.

La risposta viene visualizzata in una visualizzazione mappa, che esegue il mapping dei titoli delle tabelle alle righe della tabella. Le righe sono rappresentate come un elenco di oggetti con le stesse strutture.

Campi dei risultati di backupServer

Nome	Type	Nullable/Not nullable	Elenco di valori
source	String	Nullable	Indirizzo IP di origine
destinazione	String	Nullable	Indirizzo IP di destinazione
port	Numerico	Nullable	Porta del server di backup
trasporto	String	Nullable	Protocollo di trasporto TCP del server di backup o UDP
backupMaximalInterval	String	Nullable	Intervallo massimo tra i backup
lastSeenBackup	Numerico	Nullable	Timestamp dell'ultima visualizzazione di un backup, espresso in millisecondi dall'ora Epoch e nel fuso orario UTC

Campi dei risultati di ipNetworks

Nome	Type	Nullable/Not nullable	Elenco di valori
indirizzi	Numerico	Non nullable	Numero di indirizzi IP individuati nell'intervallo di subnet.
network	String	Non nullable	Indirizzo IP di base della subnet.
maschera	String	Non nullable	Subnet mask.

campi dei risultati protocolProblems

Nome	Type	Nullable/Not nullable	Elenco di valori
protocol	String	Non nullable	Protocollo per il quale è stato attivato un avviso di violazione del protocollo
indirizzi	Matrice JSON di indirizzi IP	Non nullable	Matrice JSON di indirizzi IP in cui ha avuto origine la violazione
vigile	String	Non nullable	Titolo dell'avviso attivato
reportTime	Numerico	Non nullable	Timestamp generato per l'ultimo report, espresso in millisecondi dall'ora Epoch e nel fuso orario UTC

campi dei risultati protocolDataVolumes

Nome	Type	Nullable/Not nullable	Elenco di valori
protocol	String	Nullable	Protocollo rilevato sulla rete dal sensore di rete OT
volume	String	Nullable	Volume di pacchetti di protocollo acquisiti dal sensore di rete OT, in MB

campi dei risultati delle disconnessioni

Nome	Type	Nullable/Not nullable	Elenco di valori
assetAddress	String	Nullable	Indirizzo IP dell'asset disconnesso
assetName	String	Nullable	Nome dell'asset disconnesso
lastDetectionTime	Numerico	Nullable	Timestamp dell'ultimo rilevamento della disconnessione, espresso in millisecondi dall'ora Epoch e nel fuso orario UTC
backToNormalTime	Numerico	Nullable	Timestamp restituito dalla connessione, espresso in millisecondi dall'ora Epoch e nel fuso orario UTC

Risposta di esempio

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

Comando cURL

Tipo: GET

API:

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

Esempio:

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

mitigazione (recuperare i passaggi di mitigazione)

Usare questa API per richiedere una valutazione della mitigazione. Questa valutazione fornisce i passaggi consigliati per la mitigazione delle vulnerabilità rilevate. Si basa su informazioni generali sulla rete e sul sistema e non su una valutazione specifica del dispositivo.

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

GET

Richiedi

Questa API viene chiamata senza parametri di richiesta.

Response

Tipo: JSON

Oggetto JSON che rappresenta i passaggi di mitigazione consigliati.

Campi di risposta

Nome campo	Type	Nullable	Elenco di valori
Notifiche	Matrice di stringhe JSON	Non nullable	Procedura di mitigazione consigliata per le vulnerabilità rilevate
mitigazione	Matrice JSON	Non nullable	oggetti di mitigazione

campi di mitigazione

Nome campo	Type	Nullable	Elenco di valori
content	String	Non nullable	Procedura di mitigazione consigliata per le vulnerabilità rilevate
scoreImprovement	Intero	Nullable	Percentuale prevista di miglioramento della sicurezza dopo l'applicazione dei passaggi di mitigazione.
details	Tabella	Nullable	Una tabella che elenca le raccomandazioni di mitigazione, ad esempio, viene generata nel report valutazione dei rischi. Ogni raccomandazione include informazioni dettagliate sul possibile impatto sulla sicurezza se l'azione viene eseguita e altro ancora. Per altre informazioni, vedere Mitigazione dei rischi.

Nota

Potrebbero essere presenti più passaggi di mitigazione, con alcuni restituiti nel notifications campo e altri restituiti nel mitigation campo. Gli elementi con scoreImprovement e details vengono restituiti solo nel mitigation campo . Gli elementi senza scoreImprovement e details i dati vengono restituiti solo nel notifications campo .

Risposta di esempio

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

Comando cURL

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

Passaggi successivi

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