Biztonságirés-kezelési API-referencia ot monitorozási érzékelőkhöz

Ez a cikk az IoT OT monitorozási érzékelőinek Microsoft Defender által támogatott biztonságirés-kezelési REST API-kat sorolja fel.

Az API-válaszokban szereplő adatok ugyanazokat az információkat tartalmazzák, mintha biztonságirés-jelentést hozott volna létre a helyszíni felügyeleti konzolról.

eszközök (Eszköz biztonsági résének adatainak lekérése)

Ezzel az API-val biztonságirés-felmérési eredményeket kérhet az egyes eszközökhöz.

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

GET

Kérés

Ezt az API-t kérésparaméterek nélkül hívjuk meg.

Válasz

Típus: JSON

A kiértékelt eszközöket és azok jelentett biztonsági réseit képviselő JSON-objektumok tömbje.

Azok az eszközök, amelyekről kiderült, hogy nem rendelkeznek biztonsági résekkel, nem szerepelnek az eredményválaszban.

Eszközmezők

Név	Típus	Nullable /Not nullable	Értékek listája
name	Sztring	Nem lehet null értékű	-
ipAddresses	JSON-tömb	Nem lehet null értékű	-
securityScore	Numerikus	Nem lehet null értékű	-
Szállító	Sztring	Nullázható
firmwareVersion	Sztring	Nullázható	-
Modell	Sztring	Nullázható	-
isWirelessAccessPoint	Logikai	Nem lehet null értékű	True vagy False
operatingSystem	Operációsrendszer-objektum	Nullázható	-
Sebezhetőség	Biztonsági rések objektum	Nem lehet null értékű	-

Operációs rendszer mezői

Név	Típus	Nullable /Not nullable	Értékek listája
name	Sztring	Nem lehet null értékű	-
Típus	Sztring	Nem lehet null értékű	-
Változat	Sztring	Nullázható	-
latestVersion	Sztring	Nullázható	-

Biztonsági rések mezők

Név	Típus	Nullable /Not nullable	Értékek listája
Antiviruses	Sztringek JSON-tömbje	Nullázható	Víruskeresők nevei
plainTextPasswords	JSON-tömb	Nullázható	Jelszóobjektumok
Remoteaccess	JSON-tömb	Nullázható	Távelérési objektumok
isBackupServer	Logikai	Nem lehet null értékű	True vagy False
openedPorts	JSON-tömb	Nullázható	Megnyitott portobjektumok
isEngineeringStation	Logikai	Nem lehet null értékű	True vagy False
isKnownScanner	Logikai	Nem lehet null értékű	True vagy False
cves	JSON-tömb	Nullázható	CVE-objektumok
isUnauthorized	Logikai	Nem lehet null értékű	True vagy False
malwareIndicationsDetected	Logikai	Nem lehet null értékű	True vagy False
gyengehitelesítés	Sztringek JSON-tömbje	Nullázható	Gyenge hitelesítést használó észlelt alkalmazások

Jelszómezők

Név	Típus	Nullable /Not nullable	Értékek listája
alaphelyzetbe állítása	Sztring	Nem lehet null értékű	-
Protokoll	Sztring	Nem lehet null értékű	-
Erejét	Sztring	Nem lehet null értékű	Very weak, Weak, Medium, Strong

Távelérés mezői

Név	Típus	Nullázható	Értékek listája
Port	Numerikus	Nem lehet null értékű	-
Közlekedési	Sztring	Nem lehet null értékű	TCP, UDP
Ügyfél	Sztring	Nem lehet null értékű	IP-cím
clientSoftware	Sztring	Nem lehet null értékű	A távoli protokoll neve, például SSH, VNC, Remote desktopvagy Team viewer

Portmezők megnyitása

Név	Típus	Nullable /Not nullable	Értékek listája
Port	Numerikus	Nem lehet null értékű	-
Közlekedési	Sztring	Nem lehet null értékű	TCP vagy UDP
Protokoll	Sztring	Nullázható	-
isConflictingWithFirewall	Logikai	Nem lehet null értékű	True vagy False

CVE-mezők

Név	Típus	Nullable /Not nullable	Értékek listája
id	Sztring	Nem lehet null értékű	-
Pontszám	Numerikus, decimális érték	Nem lehet null értékű	-
leírás	Sztring	Nem lehet null értékű	-

Példa válaszra

[
    {
        "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-parancs

Típus: GET

API:

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

Példa:

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

biztonság (Biztonsági rések lekérése)

Ezzel az API-val lekérheti egy általános biztonságirés-felmérési jelentés eredményeit. Ez az értékelés betekintést nyújt a rendszer biztonsági szintjébe.

Ez az értékelés az általános hálózati és rendszerinformációkon alapul, nem pedig egy adott eszközértékelésen.

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

GET

Kérés

Ezt az API-t kérésparaméterek nélkül hívjuk meg.

Válasz

Típus: Egy vagy több adattábla JSON-reprezentációja, amelyek mindegyike adott és potenciálisan eltérő struktúrával rendelkezik.

A válasz egy térképnézetben jelenik meg, amely a táblacímeket táblázatsorokra képezi le. A sorok azonos szerkezetű objektumok listájaként jelennek meg.

unauthorizedDevices mezők

Név	Típus	Nullable / Not nullable	Értékek listája
Cím	Sztring	Nullázható	A jogosulatlan eszköz IP-címe vagy MAC-címe
name	Sztring	Nullázható	A jogosulatlan eszköz neve
firstDetectionTime	Numerikus	Nullázható	Az eszköz időbélyegzőjének észlelése a korszaktól és az UTC időzónától ezredmásodpercben
lastSeen	Numerikus	Nullázható	Az eszközről vagy az eszközről küldött forgalom időbélyegzője ezredmásodpercben és UTC időzónában

illegalTrafficByFirewallRules mezők

Név	Típus	Nullable / Not nullable	Értékek listája
Szerver	Sztring	Nullázható	Kiszolgáló IP-címe
Ügyfél	Sztring	Nullázható	Ügyfél IP-címe
Port	Numerikus	Nullázható	A kiszolgálóport
Közlekedési	Sztring	Nullázható	TCP, , UDPvagy ICMP

weakFirewallRules mezők

Név	Típus	Nullable / Not nullable	Értékek listája
Források	Források JSON-tömbje	Nullázható	A források JSON-tömbje az alábbi formátumok bármelyikében: - Any - ip address (host) - from ip-to ip (RANGE) - ip address, subnet mask (NETWORK)
Célpontok	Célhelyek JSON-tömbje	Nullázható	Célobjektumok JSON-tömbje az alábbi formátumok bármelyikében: - Any - ip address (host) - from ip-to ip (RANGE) - ip address, subnet mask (NETWORK)
Portok	Portok JSON-tömbje	Nullázható	Portobjektumok JSON-tömbje az alábbi formátumok bármelyikében: - Any - port (protocol, if detected) - from port-to port (protocol, if detected)

accessPoints-mezők

Név	Típus	Nullable / Not nullable	Értékek listája
macAddress	Sztring	Nullázható	A hozzáférési pont MAC-címe
Szállító	Sztring	Nullázható	A hozzáférési pont szállítójának neve
ipAddress	Sztring	Nullázható	A hozzáférési pont IP-címe vagy a hálózati cím
name	Sztring	Nullázható	A hozzáférési pont eszközneve vagy a hálózati adapter neve
Vezeték nélküli	Sztring	Nullázható	Azt jelzi, hogy a hozzáférési pont vezeték nélküli hálózathoz csatlakozik-e: No, Suspected, vagy Yes

connectionsBetweenSubnets mezők

Név	Típus	Nullable / Not nullable	Értékek listája
Szerver	Sztring	Nullázható	A kiszolgáló IP-címe
Ügyfél	Sztring	Nullázható	Az ügyfél IP-címe

industrialMalwareIndicators mezők

Név	Típus	Nullable / Not nullable	Értékek listája
detectionTime	Numerikus	Nullázható	A kártevő első észlelésének időbélyege, ezredmásodpercben az alapidőszaktól és az UTC időzónától kezdve
alertMessage	Sztring	Nullázható	A riasztási üzenet elküldve
leírás	Sztring	Nullázható	A riasztási üzenet leírása
Eszközök	JSON-tömb	Nem lehet null értékű	Az eszközneveket jelölő sztringek JSON-tömbje

internetConnections mezők

Név	Típus	Nullable /Not nullable	Értékek listája
internalAddress	Sztring	Nullázható	A kapcsolat belső IP-címe
Engedélyezett	Logikai	Nullázható	Yes vagy No
externalAddresses	JSON-tömb	Nem lehet null értékű	A kapcsolat külső IP-címeinek JSON-tömbje

Példa válaszra

{
    "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-parancs

Típus: GET

API-k:

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

Példa:

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

operational (Működési biztonsági rések lekérése)

Ezzel az API-val általános biztonságirés-felmérés eredményeit kérheti le. Ez az értékelés betekintést nyújt a hálózat működési állapotába. Ez az általános hálózati és rendszerinformációkon alapul, nem pedig egy adott eszközértékelésen.

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

GET

Kérés

Ezt az API-t kérésparaméterek nélkül hívjuk meg.

Válasz

Típus: Egy vagy több adattábla JSON-reprezentációja, amelyek mindegyike adott és potenciálisan eltérő struktúrával rendelkezik.

A válasz egy térképnézetben jelenik meg, amely a táblacímeket táblázatsorokra képezi le. A sorok azonos szerkezetű objektumok listájaként jelennek meg.

backupServer eredménymezők

Név	Típus	Nullable /Not nullable	Értékek listája
Forrás	Sztring	Nullázható	A forrás IP-címe
Cél	Sztring	Nullázható	A cél IP-címe
Port	Numerikus	Nullázható	A biztonsági mentési kiszolgáló portja
Közlekedési	Sztring	Nullázható	A biztonsági mentési kiszolgáló átviteli protokollja TCP vagy UDP
backupMaximalInterval	Sztring	Nullázható	A biztonsági mentések közötti maximális időköz
lastSeenBackup	Numerikus	Nullázható	A biztonsági mentés utolsó megtekintése időbélyege, ezredmásodpercben az alapidőszaktól és az UTC időzónától

ipNetworks eredménymezők

Név	Típus	Nullable /Not nullable	Értékek listája
Címek	Numerikus	Nem lehet null értékű	Az alhálózati tartományban felderített IP-címek száma.
network	Sztring	Nem lehet null értékű	Az alhálózat alap IP-címe.
mask	Sztring	Nem lehet null értékű	Az alhálózati maszk.

protocolProblems eredménymezők

Név	Típus	Nullable /Not nullable	Értékek listája
Protokoll	Sztring	Nem lehet null értékű	Protokoll, amelyhez protokollmegsértési riasztást aktiváltak
Címek	IP-címek JSON-tömbje	Nem lehet null értékű	A szabálysértés forrásaként szolgáló IP-címek JSON-tömbje
Éber	Sztring	Nem lehet null értékű	A riasztás aktivált címe
reportTime	Numerikus	Nem lehet null értékű	Jelentés utolsó létrehozásának időbélyege, ezredmásodpercben az alapidőszaktól és az UTC időzónától

protocolDataVolumes eredménymezők

Név	Típus	Nullable /Not nullable	Értékek listája
Protokoll	Sztring	Nullázható	Egy protokoll, amelyet az OT hálózati érzékelő észlelt a hálózaton
Kötet	Sztring	Nullázható	Az OT hálózati érzékelő által rögzített protokollcsomagok mennyisége MB-ban

kapcsolatbontás eredménymezői

Név	Típus	Nullable /Not nullable	Értékek listája
assetAddress	Sztring	Nullázható	A leválasztott objektum IP-címe
assetName	Sztring	Nullázható	A leválasztott objektum neve
lastDetectionTime	Numerikus	Nullázható	A kapcsolat bontásának utolsó észlelésének időbélyege, ezredmásodpercben az alapidőszaktól és az UTC időzónától
backToNormalTime	Numerikus	Nullázható	A kapcsolat által visszaadott időbélyeg, ezredmásodpercben az alapidőszaktól és az UTC időzónától

Példa válaszra

{
    "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-parancs

Típus: GET

API-k:

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

Példa:

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

kockázatcsökkentés (Kockázatcsökkentési lépések lekérése)

Ezzel az API-val kockázatcsökkentési értékelést kérhet. Ez az értékelés ajánlott lépéseket biztosít az észlelt biztonsági rések elhárításához. Ez az általános hálózati és rendszerinformációkon alapul, nem pedig egy adott eszközértékelésen.

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

GET

Kérés

Ezt az API-t kérésparaméterek nélkül hívjuk meg.

Válasz

Típus: JSON

A javasolt kockázatcsökkentési lépéseket képviselő JSON-objektum.

Válaszmezők

Mező neve	Típus	Nullázható	Értékek listája
Értesítések	Sztringek JSON-tömbje	Nem lehet null értékű	Javasolt kockázatcsökkentési lépések az észlelt biztonsági rések esetén
Enyhítés	JSON-tömb	Nem lehet null értékű	kockázatcsökkentési objektumok

kockázatcsökkentési mezők

Mező neve	Típus	Nullázható	Értékek listája
Tartalom	Sztring	Nem lehet null értékű	Javasolt kockázatcsökkentési lépések az észlelt biztonsági rések esetén
scoreImprovement	Egész szám	Nullázható	A biztonsági fejlesztések várható százalékos aránya a kockázatcsökkentési lépések elvégzése után.
Részletek	Tábla	Nullázható	A kockázatcsökkentési javaslatokat felsoroló táblázat, például a kockázatértékelési jelentésben lesz létrehozva. Minden javaslat részletesen ismerteti a művelet végrehajtásakor esetleges biztonsági hatásokat és egyebeket. További információ: Kockázatcsökkentés.

Megjegyzés

Előfordulhat, hogy több kockázatcsökkentési lépése van, amelyek közül néhány a notifications mezőben, mások pedig a mitigation mezőben vannak visszaadva. A és details az adatokkal rendelkező scoreImprovement elemek csak a mezőben lesznek visszaadvamitigation. A nem és details az adatokkal nem rendelkező scoreImprovement elemek csak a notifications mezőben jelennek meg.

Példa válaszra

{
    "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-parancs

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

Következő lépések

További információ: A Defender for IoT API referencia áttekintése.