Referens för API för sårbarhetshantering för OT-övervakningssensorer

I den här artikeln visas de hantering av säkerhetsrisker REST API:er som stöds för Övervakningssensorer för Microsoft Defender för IoT OT.

De data som ingår i API-svaren innehåller samma information som om du genererade en sårbarhetsrapport från OT-sensorkonsolen.

enheter (Hämta information om enhetens säkerhetsrisker)

Använd det här API:et för att begära resultat av sårbarhetsbedömning för varje enhet.

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

GET

Begär

Det här API:et anropas utan några parametrar för begäran.

Response

Typ: JSON

Matris med JSON-objekt som representerar utvärderade enheter och deras rapporterade sårbarheter.

Enheter som inte har några säkerhetsrisker ingår inte i resultatsvaret.

Enhetsfält

Namn	Type	Nullable /Not nullable	Lista över värden
Namn	String	Inte nullbar	-
ipAddresses	JSON-matris	Inte nullbar	-
securityScore	Numerisk	Inte nullbar	-
säljare	String	Kan ha värdet null
firmwareVersion	String	Kan ha värdet null	-
modell	String	Kan ha värdet null	-
isWirelessAccessPoint	Booleskt	Inte nullbar	True eller False
operatingSystem	Operativsystemobjekt	Kan ha värdet null	-
Sårbarheter	Sårbarhetsobjekt	Inte nullbar	-

Operativsystemfält

Namn	Type	Nullable /Not nullable	Lista över värden
Namn	String	Inte nullbar	-
typ	String	Inte nullbar	-
version	String	Kan ha värdet null	-
latestVersion	String	Kan ha värdet null	-

Sårbarhetsfält

Namn	Type	Nullable /Not nullable	Lista över värden
antiVirus	JSON-matris med strängar	Kan ha värdet null	Antivirusnamn
plainTextPasswords	JSON-matris	Kan ha värdet null	Lösenordsobjekt
remoteAccess	JSON-matris	Kan ha värdet null	Fjärråtkomstobjekt
isBackupServer	Booleskt	Inte nullbar	True eller False
openedPorts	JSON-matris	Kan ha värdet null	Öppna portobjekt
isEngineeringStation	Booleskt	Inte nullbar	True eller False
isKnownScanner	Booleskt	Inte nullbar	True eller False
cves	JSON-matris	Kan ha värdet null	CVE-objekt
är obehörig	Booleskt	Inte nullbar	True eller False
malwareIndicationsDetected	Booleskt	Inte nullbar	True eller False
weakAuthentication	JSON-matris med strängar	Kan ha värdet null	Identifierade program som använder svag autentisering

Lösenordsfält

Namn	Type	Nullable /Not nullable	Lista över värden
lösenord	String	Inte nullbar	-
protokoll	String	Inte nullbar	-
styrka	String	Inte nullbar	Very weak, Weak, , MediumStrong

Fält för fjärråtkomst

Namn	Typ	Kan ha värdet noll	Lista över värden
port	Numerisk	Inte nullbar	-
transport	String	Inte nullbar	TCP, UDP
client	String	Inte nullbar	IP-adress
clientSoftware	String	Inte nullbar	Namn på fjärrprotokollet, till exempel SSH, VNC, Remote desktopeller Team viewer

Öppna portfält

Namn	Type	Nullable /Not nullable	Lista över värden
port	Numerisk	Inte nullbar	-
transport	String	Inte nullbar	TCP eller UDP
protokoll	String	Kan ha värdet null	-
isConflictingWithFirewall	Booleskt	Inte nullbar	True eller False

CVE-fält

Namn	Type	Nullable /Not nullable	Lista över värden
id	String	Inte nullbar	-
tjog	Numeriskt decimalvärde	Inte nullbar	-
beskrivning	String	Inte nullbar	-

Svarsexempel

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

cURL-kommando

Typ: GET

API:

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

Exempel:

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

säkerhet (Hämta säkerhetsrisker)

Använd det här API:et för att begära resultat av en allmän sårbarhetsbedömningsrapport. Den här utvärderingen ger insikter om systemets säkerhetsnivå.

Den här utvärderingen baseras på allmän nätverks- och systeminformation och inte på en specifik enhetsutvärdering.

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

GET

Begär

Det här API:et anropas utan några parametrar för begäran.

Response

Typ: JSON-representation av en eller flera datatabeller, var och en med specifika och potentiellt olika strukturer.

Svaret visas i en kartvy som mappar tabellrubriker till tabellrader. Rader representeras som en lista över objekt med samma strukturer.

unauthorizedDevices-fält

Namn	Type	Nullable /Not nullable	Lista över värden
adress	String	Kan ha värdet null	IP- eller MAC-adressen för den obehöriga enheten
Namn	String	Kan ha värdet null	Namnet på den obehöriga enheten
firstDetectionTime	Numerisk	Kan ha värdet null	Tidsstämpel som enheten först identifierades, i millisekunder från epoktid och i UTC-tidszon
lastSeen	Numerisk	Kan ha värdet null	Tidsstämpel som trafiken senast identifierades som skickad till eller från enheten, i millisekunder från epoktid och i UTC-tidszon

illegalTrafficByFirewallRules fält

Namn	Type	Nullable /Not nullable	Lista över värden
server	String	Kan ha värdet null	Serverns IP-adress
client	String	Kan ha värdet null	Klientens IP-adress
port	Numerisk	Kan ha värdet null	Serverporten
transport	String	Kan ha värdet null	TCP, UDP eller ICMP

weakFirewallRules-fält

Namn	Type	Nullable /Not nullable	Lista över värden
Källor	JSON-matris med källor	Kan ha värdet null	JSON-matris med källor i något av följande format: - Any - ip address (host) - from ip-to ip (RANGE) - ip address, subnet mask (NETWORK)
resmål	JSON-matris med mål	Kan ha värdet null	JSON-matris med målobjekt i något av följande format: - Any - ip address (host) - from ip-to ip (RANGE) - ip address, subnet mask (NETWORK)
portar	JSON-matris med portar	Kan ha värdet null	JSON-matris med portobjekt i något av följande format: - Any - port (protocol, if detected) - from port-to port (protocol, if detected)

accessPoints-fält

Namn	Type	Nullable /Not nullable	Lista över värden
macAddress	String	Kan ha värdet null	Åtkomstpunktens MAC-adress
säljare	String	Kan ha värdet null	Åtkomstpunktens leverantörsnamn
ipAddress	String	Kan ha värdet null	Åtkomstpunktens IP-adress eller N/A
Namn	String	Kan ha värdet null	Åtkomstpunktens enhetsnamn eller N/A
trådlös	String	Kan ha värdet null	Om åtkomstpunkten är ansluten till ett trådlöst nätverk: No, Suspectedeller Yes

connectionsBetweenSubnets-fält

Namn	Type	Nullable /Not nullable	Lista över värden
server	String	Kan ha värdet null	Serverns IP-adress
client	String	Kan ha värdet null	Klientens IP-adress

industrialMalwareIndicators fält

Namn	Type	Nullable /Not nullable	Lista över värden
detectionTime	Numerisk	Kan ha värdet null	Tidsstämpeln för skadlig kod upptäcktes först, i millisekunder från epoktid och i UTC-tidszon
alertMessage	String	Kan ha värdet null	Aviseringsmeddelandet som skickades
beskrivning	String	Kan ha värdet null	Beskrivning av aviseringsmeddelandet
Enheter	JSON-matris	Inte nullbar	En JSON-matris med strängar som representerar enhetsnamn

internetConnections-fält

Namn	Type	Nullable /Not nullable	Lista över värden
internalAddress	String	Kan ha värdet null	Anslutningens interna IP-adress
befogad	Booleskt	Kan ha värdet null	Yes eller No
externalAddresses	JSON-matris	Inte nullbar	En JSON-matris med anslutningens externa IP-adresser

Svarsexempel

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

cURL-kommando

Typ: GET

API:er:

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

Exempel:

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

drift (Hämta sårbarheter i drift)

Använd det här API:et för att begära resultat av en allmän sårbarhetsbedömning. Den här utvärderingen ger insikt i nätverkets driftstatus. Den baseras på allmän nätverks- och systeminformation och inte på en specifik enhetsutvärdering.

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

GET

Begär

Det här API:et anropas utan några parametrar för begäran.

Response

Typ: JSON-representation av en eller flera datatabeller, var och en med specifika och potentiellt olika strukturer.

Svaret visas i en kartvy som mappar tabellrubriker till tabellrader. Rader representeras som en lista över objekt med samma strukturer.

backupServer-resultatfält

Namn	Type	Nullable /Not nullable	Lista över värden
källa	String	Kan ha värdet null	Källans IP-adress
destination	String	Kan ha värdet null	Målets IP-adress
port	Numerisk	Kan ha värdet null	Serverporten för säkerhetskopiering
transport	String	Kan ha värdet null	Transportprotokollet TCP för säkerhetskopieringsservern eller UDP
backupMaximalInterval	String	Kan ha värdet null	Den maximala intervalltiden mellan säkerhetskopior
lastSeenBackup	Numerisk	Kan ha värdet null	Tidsstämpel som en säkerhetskopia senast sågs, i millisekunder från epoktid och i UTC-tidszon

ipNetworks-resultatfält

Namn	Type	Nullable /Not nullable	Lista över värden
Adresser	Numerisk	Inte nullbar	Antalet IP-adresser som identifierats i undernätsintervallet.
nätverk	String	Inte nullbar	Undernätets bas-IP-adress.
mask	String	Inte nullbar	Nätmasken.

protocolProblems-resultatfält

Namn	Type	Nullable /Not nullable	Lista över värden
protokoll	String	Inte nullbar	Ett protokoll för vilket en avisering om protokollöverträdelse utlöstes
Adresser	JSON-matris med IP-adresser	Inte nullbar	JSON-matris med IP-adresser där överträdelsen har sitt ursprung
alert	String	Inte nullbar	Rubriken på aviseringen som utlöstes
reportTime	Numerisk	Inte nullbar	Tidsstämpel som en rapport senast genererades, i millisekunder från epoktid och i UTC-tidszon

protocolDataVolumes-resultatfält

Namn	Type	Nullable /Not nullable	Lista över värden
protokoll	String	Kan ha värdet null	Ett protokoll som identifierades i nätverket av OT-nätverkssensorn
volym	String	Kan ha värdet null	Volymen protokollpaket som samlas in av OT-nätverkssensorn i MB

resultatfält för frånkopplingar

Namn	Type	Nullable /Not nullable	Lista över värden
assetAddress	String	Kan ha värdet null	IP-adressen för den frånkopplade tillgången
assetName	String	Kan ha värdet null	Namnet på den frånkopplade tillgången
lastDetectionTime	Numerisk	Kan ha värdet null	Tidsstämpel som frånkopplingen senast identifierades, i millisekunder från epoktid och i UTC-tidszon
backToNormalTime	Numerisk	Kan ha värdet null	Tidsstämpel som anslutningen returnerade, i millisekunder från epoktid och i UTC-tidszon

Svarsexempel

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

cURL-kommando

Typ: GET

API:er:

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

Exempel:

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

mitigation (Hämta åtgärdssteg)

Använd det här API:et för att begära en åtgärdsbedömning. Den här utvärderingen innehåller rekommenderade steg för att minimera identifierade sårbarheter. Den baseras på allmän nätverks- och systeminformation och inte på en specifik enhetsutvärdering.

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

GET

Begär

Det här API:et anropas utan några parametrar för begäran.

Response

Typ: JSON

JSON-objekt som representerar rekommenderade åtgärdssteg.

Svarsfält

Fältnamn	Type	Kan ha värdet noll	Lista över värden
Meddelanden	JSON-matris med strängar	Inte nullbar	Rekommenderade åtgärdssteg för identifierade sårbarheter
förmildrande omständighet	JSON-matris	Inte nullbar	åtgärdsobjekt

åtgärdsfält

Fältnamn	Type	Kan ha värdet noll	Lista över värden
innehåll	String	Inte nullbar	Rekommenderade åtgärdssteg för identifierade sårbarheter
scoreImprovement	Integer	Kan ha värdet null	Förväntad procentandel av säkerhetsförbättringar efter att åtgärdsåtgärder har vidtagits.
Detaljer	Register	Kan ha värdet null	En tabell som visar rekommendationer för riskreducering, till exempel skulle genereras i riskbedömningsrapporten . Varje rekommendation innehåller information om möjliga säkerhetseffekter om åtgärden utförs med mera. Mer information finns i Riskreducering.

Kommentar

Du kan ha flera åtgärdssteg, där vissa returneras i fältet notifications och andra returneras i fältet mitigation . Objekt med scoreImprovement och details data returneras endast i fältet mitigation . Objekt utan scoreImprovement och details data returneras endast i fältet notifications .

Svarsexempel

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

cURL-kommando

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

Nästa steg

Mer information finns i referensöversikten för Defender för IoT API.