Referenční informace k rozhraní API pro správu ohrožení zabezpečení pro senzory monitorování OT

Tento článek uvádí správa ohrožení zabezpečení rozhraní REST API podporovaná pro monitorovací senzory Microsoft Defenderu pro IoT OT.

Data zahrnutá v odpovědích rozhraní API obsahují stejné informace, jako kdybyste vygenerovali sestavu ohrožení zabezpečení z konzoly senzoru OT.

zařízení (načtení informací o ohrožení zabezpečení zařízení)

Toto rozhraní API slouží k vyžádání výsledků posouzení ohrožení zabezpečení pro každé zařízení.

Identifikátor URI: /api/v1/reports/vulnerabilities/devices

GET

Požádat

Toto rozhraní API se volá bez parametrů požadavku.

Response

Typ: JSON

Pole objektů JSON, které představují vyhodnocená zařízení a jejich nahlášená ohrožení zabezpečení

Zařízení, u kterých se zjistí, že v odpovědi na výsledek nejsou zahrnutá žádná ohrožení zabezpečení.

Pole zařízení

Name	Type	Nullable / Not nullable	Seznam hodnot
Jméno	String	Nelze použít hodnotu null.	-
ipAddresses	Pole JSON	Nelze použít hodnotu null.	-
securityScore	Číslo	Nelze použít hodnotu null.	-
prodejce	String	Vynulovatelné
firmwareVersion	String	Vynulovatelné	-
model	String	Vynulovatelné	-
isWirelessAccessPoint	Logická hodnota	Nelze použít hodnotu null.	True nebo False
operatingSystem	Objekt operačního systému	Vynulovatelné	-
slabá místa	Objekt Ohrožení zabezpečení	Nelze použít hodnotu null.	-

Pole operačního systému

Name	Type	Nullable / Not nullable	Seznam hodnot
Jméno	String	Nelze použít hodnotu null.	-
type	String	Nelze použít hodnotu null.	-
version	String	Vynulovatelné	-
latestVersion	String	Vynulovatelné	-

Pole Ohrožení zabezpečení

Name	Type	Nullable / Not nullable	Seznam hodnot
antiViry	Pole JSON řetězců	Vynulovatelné	Názvy antivirových programů
plainTextPasswords	Pole JSON	Vynulovatelné	Objekty hesel
remoteAccess	Pole JSON	Vynulovatelné	Objekty vzdáleného přístupu
isBackupServer	Logická hodnota	Nelze použít hodnotu null.	True nebo False
openedPorts	Pole JSON	Vynulovatelné	Otevřené objekty portů
isEngineeringStation	Logická hodnota	Nelze použít hodnotu null.	True nebo False
isKnownScanner	Logická hodnota	Nelze použít hodnotu null.	True nebo False
cves	Pole JSON	Vynulovatelné	CVE – objekty
isUnauthorized	Logická hodnota	Nelze použít hodnotu null.	True nebo False
malwareIndicationsDetected	Logická hodnota	Nelze použít hodnotu null.	True nebo False
weakAuthentication	Pole JSON řetězců	Vynulovatelné	Zjistily se aplikace, které používají slabé ověřování.

Pole hesel

Name	Type	Nullable / Not nullable	Seznam hodnot
heslo	String	Nelze použít hodnotu null.	-
protokol	String	Nelze použít hodnotu null.	-
síla	String	Nelze použít hodnotu null.	Very weak, Weak, , MediumStrong

Pole vzdáleného přístupu

Name	Type	S možnou hodnotou Null	Seznam hodnot
port	Číslo	Nelze použít hodnotu null.	-
přeprava	String	Nelze použít hodnotu null.	TCP, UDP
klient	String	Nelze použít hodnotu null.	IP adresa
clientSoftware	String	Nelze použít hodnotu null.	Název vzdáleného protokolu, například SSH, VNC, Remote desktopnebo Team viewer

Otevření polí portů

Name	Type	Nullable / Not nullable	Seznam hodnot
port	Číslo	Nelze použít hodnotu null.	-
přeprava	String	Nelze použít hodnotu null.	TCP nebo UDP
protokol	String	Vynulovatelné	-
isConflictingWithFirewall	Logická hodnota	Nelze použít hodnotu null.	True nebo False

Pole CVE

Name	Type	Nullable / Not nullable	Seznam hodnot
id	String	Nelze použít hodnotu null.	-
partitura	Číselná, desetinná hodnota	Nelze použít hodnotu null.	-
popis	String	Nelze použít hodnotu null.	-

Příklad odpovědi

[
    {
        "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 – příkaz

Typ: GET

API:

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

Příklad:

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

zabezpečení (načtení ohrožení zabezpečení)

Toto rozhraní API slouží k vyžádání výsledků obecné sestavy posouzení ohrožení zabezpečení. Toto posouzení poskytuje přehled o úrovni zabezpečení vašeho systému.

Toto posouzení vychází z obecných informací o síti a systému, a ne na konkrétním vyhodnocení zařízení.

Identifikátor URI: /api/v1/reports/vulnerabilities/security

GET

Požádat

Toto rozhraní API se volá bez parametrů požadavku.

Response

Typ: Reprezentace JSON jedné nebo více tabulek dat, každá s konkrétními a potenciálně různými strukturami.

Odpověď se zobrazí v zobrazení mapy, které mapuje názvy tabulek na řádky tabulky. Řádky jsou reprezentovány jako seznam objektů se stejnými strukturami.

Pole unauthorizedDevices

Name	Type	Nullable / Not nullable	Seznam hodnot
adresa	String	Vynulovatelné	IP adresa nebo adresa MAC neautorizovaného zařízení
Jméno	String	Vynulovatelné	Název neoprávněného zařízení
firstDetectionTime	Číslo	Vynulovatelné	Časové razítko, které zařízení poprvé zjistilo, v milisekundách od epochy a v časovém pásmu UTC
lastSeen	Číslo	Vynulovatelné	Časové razítko, které se naposledy zjistilo jako odesílané do nebo ze zařízení, v milisekundách od epochy a v časovém pásmu UTC

pole illegalTrafficByFirewallRules

Name	Type	Nullable / Not nullable	Seznam hodnot
server	String	Vynulovatelné	IP adresa serveru
klient	String	Vynulovatelné	IP adresa klienta
port	Číslo	Vynulovatelné	Port serveru
přeprava	String	Vynulovatelné	TCP, UDP nebo ICMP

pole weakFirewallRules

Name	Type	Nullable / Not nullable	Seznam hodnot
sources	Pole JSON zdrojů	Vynulovatelné	Pole JSON zdrojů v některém z následujících formátů: - Any - ip address (host) - from ip-to ip (RANGE) - ip address, subnet mask (NETWORK)
místa určení	Pole cílů JSON	Vynulovatelné	Pole JSON cílových objektů v některém z následujících formátů: - Any - ip address (host) - from ip-to ip (RANGE) - ip address, subnet mask (NETWORK)
přístavy	Pole JSON portů	Vynulovatelné	Pole JSON objektů portů v některém z následujících formátů: - Any - port (protocol, if detected) - from port-to port (protocol, if detected)

AccessPoints fields

Name	Type	Nullable / Not nullable	Seznam hodnot
macAddress	String	Vynulovatelné	Adresa MAC přístupového bodu
prodejce	String	Vynulovatelné	Název dodavatele přístupového bodu
ipAddress	String	Vynulovatelné	IP adresa přístupového bodu nebo není k dispozici
Jméno	String	Vynulovatelné	Název zařízení přístupového bodu nebo není k dispozici
bezdrátový	String	Vynulovatelné	Zda je přístupový bod připojený k bezdrátové síti: No, Suspectednebo Yes

connectionsBetweenSubnets – pole

Name	Type	Nullable / Not nullable	Seznam hodnot
server	String	Vynulovatelné	IP adresa serveru
klient	String	Vynulovatelné	IP adresa klienta

pole industrialMalwareIndicators

Name	Type	Nullable / Not nullable	Seznam hodnot
detectionTime	Číslo	Vynulovatelné	Časové razítko, kdy byl malware poprvé zjištěn, v milisekundách od epochy a v časovém pásmu UTC
alertMessage	String	Vynulovatelné	Zpráva s upozorněním byla odeslána.
popis	String	Vynulovatelné	Popis zprávy upozornění
zařízení	Pole JSON	Nelze použít hodnotu null.	Pole JSON řetězců představujících názvy zařízení

Pole internetConnections

Name	Type	Nullable / Not nullable	Seznam hodnot
internalAddress	String	Vynulovatelné	Interní IP adresa připojení
autorizovaný	Logická hodnota	Vynulovatelné	Yes nebo No
externalAddresses	Pole JSON	Nelze použít hodnotu null.	Pole JSON externích IP adres připojení

Příklad odpovědi

{
    "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 – příkaz

Typ: GET

Rozhraní API:

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

Příklad:

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

operational (načtení provozních ohrožení zabezpečení)

Toto rozhraní API slouží k vyžádání výsledků obecného posouzení ohrožení zabezpečení. Toto posouzení poskytuje přehled o provozním stavu vaší sítě. Je založená na obecných informacích o síti a systému, a ne na konkrétním vyhodnocení zařízení.

Identifikátor URI: /api/v1/reports/vulnerabilities/operational

GET

Požádat

Toto rozhraní API se volá bez parametrů požadavku.

Response

Typ: Reprezentace JSON jedné nebo více tabulek dat, každá s konkrétními a potenciálně různými strukturami.

Odpověď se zobrazí v zobrazení mapy, které mapuje názvy tabulek na řádky tabulky. Řádky jsou reprezentovány jako seznam objektů se stejnými strukturami.

Pole výsledků backupServeru

Name	Type	Nullable / Not nullable	Seznam hodnot
source	String	Vynulovatelné	Zdrojová IP adresa
cíl	String	Vynulovatelné	Cílová IP adresa
port	Číslo	Vynulovatelné	Port záložního serveru
přeprava	String	Vynulovatelné	Přenosový protokol TCP záložního serveru nebo UDP
backupMaximalInterval	String	Vynulovatelné	Maximální doba intervalu mezi zálohami
lastSeenBackup	Číslo	Vynulovatelné	Časové razítko posledního výskytu zálohy v milisekundách od epochy a v časovém pásmu UTC

Pole výsledků ipNetworks

Name	Type	Nullable / Not nullable	Seznam hodnot
adresy	Číslo	Nelze použít hodnotu null.	Počet IP adres zjištěných v rozsahu podsítě
síť	String	Nelze použít hodnotu null.	Základní IP adresa podsítě.
maska	String	Nelze použít hodnotu null.	Maska podsítě.

Pole výsledků protokoluProblems

Name	Type	Nullable / Not nullable	Seznam hodnot
protokol	String	Nelze použít hodnotu null.	Protokol, pro který se aktivovalo upozornění na porušení protokolu
adresy	Pole JSON IP adres	Nelze použít hodnotu null.	Pole JSON IP adres, ve kterých došlo k porušení
poplach	String	Nelze použít hodnotu null.	Název aktivované výstrahy
reportTime	Číslo	Nelze použít hodnotu null.	Časové razítko, které sestava naposledy vygenerovala, v milisekundách od epochy a v časovém pásmu UTC

Pole výsledků protokoluDataVolumes

Name	Type	Nullable / Not nullable	Seznam hodnot
protokol	String	Vynulovatelné	Protokol, který byl zjištěn v síti senzorem sítě OT
hlasitost	String	Vynulovatelné	Objem paketů protokolu zachycených síťovým senzorem OT v MB

pole výsledků odpojení

Name	Type	Nullable / Not nullable	Seznam hodnot
assetAddress	String	Vynulovatelné	IP adresa odpojeného prostředku
assetName	String	Vynulovatelné	Název odpojeného prostředku
lastDetectionTime	Číslo	Vynulovatelné	Časové razítko posledního zjištění odpojení v milisekundách od epochy a v časovém pásmu UTC
backToNormalTime	Číslo	Vynulovatelné	Časové razítko, které připojení vrátilo, v milisekundách od epochy a v časovém pásmu UTC

Příklad odpovědi

{
    "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 – příkaz

Typ: GET

Rozhraní API:

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

Příklad:

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

zmírnění rizik (načtení kroků pro zmírnění rizik)

Toto rozhraní API slouží k vyžádání posouzení zmírnění rizik. Toto posouzení obsahuje doporučené kroky pro zmírnění zjištěných ohrožení zabezpečení. Je založená na obecných informacích o síti a systému, a ne na konkrétním vyhodnocení zařízení.

Identifikátor URI: /api/v1/reports/vulnerabilities/mitigation

GET

Požádat

Toto rozhraní API se volá bez parametrů požadavku.

Response

Typ: JSON

Objekt JSON, který představuje doporučené kroky pro zmírnění rizik.

Pole odpovědi

Název pole	Typ	S možnou hodnotou Null	Seznam hodnot
upozornění	Pole JSON řetězců	Nelze použít hodnotu null.	Doporučené kroky pro zmírnění rizik pro zjištěné chyby zabezpečení
zmírnění	Pole JSON	Nelze použít hodnotu null.	objekty pro zmírnění rizik

pole pro zmírnění rizik

Název pole	Typ	S možnou hodnotou Null	Seznam hodnot
obsah	String	Nelze použít hodnotu null.	Doporučené kroky pro zmírnění rizik pro zjištěné chyby zabezpečení
ScoreImprovement	Celé číslo	Vynulovatelné	Očekávané procento zlepšení zabezpečení po provedení kroků pro zmírnění rizik
podrobnosti	Table	Vynulovatelné	Tabulka s doporučeními pro zmírnění rizik, jako by se vygenerovala v sestavě posouzení rizik. Každé doporučení obsahuje podrobnosti o možném dopadu na zabezpečení, pokud se akce provede a další. Další informace najdete v tématu Zmírnění rizik.

Poznámka:

Můžete mít několik kroků pro zmírnění rizik, u některých vrácených v notifications poli a dalších vrácených v mitigation poli. Položky s daty scoreImprovement a details položky se vrátí pouze v mitigation poli. Položky bez scoreImprovement a details data se vrátí pouze v notifications poli.

Příklad odpovědi

{
    "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 – příkaz

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

Další kroky

Další informace najdete v přehledu referenčních informací k rozhraní DEFENDER for IoT API.