Api-referentie voor beveiligingsproblemen voor OT-bewakingssensoren

Dit artikel bevat de REST API's voor beveiligingsproblemen die worden ondersteund voor Microsoft Defender for IoT OT-bewakingssensoren.

De gegevens die zijn opgenomen in de API-antwoorden bevatten dezelfde informatie als wanneer u een rapport over beveiligingsproblemen hebt gegenereerd vanuit de OT-sensorconsole.

apparaten (informatie over beveiligingsproblemen van apparaten ophalen)

Gebruik deze API om resultaten van evaluatie van beveiligingsproblemen aan te vragen voor elk apparaat.

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

GET

Aanvragen

Deze API wordt aangeroepen zonder aanvraagparameters.

Response

Type: JSON

Matrix van JSON-objecten die geëvalueerde apparaten en hun gerapporteerde beveiligingsproblemen vertegenwoordigen.

Apparaten die geen beveiligingsproblemen hebben, worden niet opgenomen in het resultaatantwoord.

Apparaatvelden

Name	Type	Nullable/Not nullable	Lijst met waarden
name	String	Niet nullable	-
ipAddresses	JSON-matrix	Niet nullable	-
securityScore	Numeriek	Niet nullable	-
verkoper	String	Null-waarde toegestaan
firmwareVersion	String	Null-waarde toegestaan	-
model	String	Null-waarde toegestaan	-
isWirelessAccessPoint	Booleaanse waarde	Niet nullable	True of False
operatingSystem	Besturingssysteemobject	Null-waarde toegestaan	-
Kwetsbaarheden	Beveiligingsproblemen-object	Niet nullable	-

Velden van het besturingssysteem

Name	Type	Nullable/Not nullable	Lijst met waarden
name	String	Niet nullable	-
type	String	Niet nullable	-
version	String	Null-waarde toegestaan	-
latestVersion	String	Null-waarde toegestaan	-

Velden voor beveiligingsproblemen

Name	Type	Nullable/Not nullable	Lijst met waarden
antiVirussen	JSON-matrix met tekenreeksen	Null-waarde toegestaan	Antivirusnamen
plainTextPasswords	JSON-matrix	Null-waarde toegestaan	Wachtwoordobjecten
remoteAccess	JSON-matrix	Null-waarde toegestaan	Externe toegangsobjecten
isBackupServer	Booleaanse waarde	Niet nullable	True of False
openedPorts	JSON-matrix	Null-waarde toegestaan	Geopende poortobjecten
isEngineeringStation	Booleaanse waarde	Niet nullable	True of False
isKnownScanner	Booleaanse waarde	Niet nullable	True of False
cves	JSON-matrix	Null-waarde toegestaan	CVE-objecten
isUnauthorized	Booleaanse waarde	Niet nullable	True of False
malwareIndicationsDetected	Booleaanse waarde	Niet nullable	True of False
zwakke verificatie	JSON-matrix met tekenreeksen	Null-waarde toegestaan	Gedetecteerde toepassingen die gebruikmaken van zwakke verificatie

Wachtwoordvelden

Name	Type	Nullable/Not nullable	Lijst met waarden
password	String	Niet nullable	-
protocol	String	Niet nullable	-
kracht	String	Niet nullable	Very weak, , , WeakMediumStrong

Velden voor externe toegang

Name	Type	Nullable	Lijst met waarden
port	Numeriek	Niet nullable	-
vervoer	String	Niet nullable	TCP, UDP
client	String	Niet nullable	IP-adres
clientSoftware	String	Niet nullable	Naam van het externe protocol, zoals SSH, VNC, of Remote desktopTeam viewer

Poortvelden openen

Name	Type	Nullable/Not nullable	Lijst met waarden
port	Numeriek	Niet nullable	-
vervoer	String	Niet nullable	TCP of UDP
protocol	String	Null-waarde toegestaan	-
isConflictingWithFirewall	Booleaanse waarde	Niet nullable	True of False

CVE-velden

Name	Type	Nullable/Not nullable	Lijst met waarden
id	String	Niet nullable	-
partituur	Numerieke, decimale waarde	Niet nullable	-
beschrijving	String	Niet nullable	-

Responsvoorbeeld

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

Type: GET

API:

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

Voorbeeld:

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

beveiliging (beveiligingsproblemen ophalen)

Gebruik deze API om resultaten op te vragen van een algemeen rapport over evaluatie van beveiligingsproblemen. Deze evaluatie biedt inzicht in het beveiligingsniveau van uw systeem.

Deze evaluatie is gebaseerd op algemene netwerk- en systeeminformatie en niet op een specifieke apparaatevaluatie.

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

GET

Aanvragen

Deze API wordt aangeroepen zonder aanvraagparameters.

Response

Type: JSON-weergave van een of meer gegevenstabellen, elk met specifieke en mogelijk verschillende structuren.

Het antwoord wordt weergegeven in een kaartweergave, waarmee tabeltitels worden toegewezen aan tabelrijen. Rijen worden weergegeven als een lijst met objecten met dezelfde structuren.

unauthorizedDevices-velden

Name	Type	Nullable/Not nullable	Lijst met waarden
adres	String	Null-waarde toegestaan	IP- of MAC-adres van het niet-geautoriseerde apparaat
name	String	Null-waarde toegestaan	Naam van het niet-geautoriseerde apparaat
firstDetectionTime	Numeriek	Null-waarde toegestaan	Tijdstempel van het apparaat is voor het eerst gedetecteerd, in milliseconden van epoch-tijd en in UTC-tijdzone
lastSeen	Numeriek	Null-waarde toegestaan	Tijdstempel dat verkeer voor het laatst is gedetecteerd als verzonden naar of vanaf het apparaat, in milliseconden van epoch-tijd en in UTC-tijdzone

illegalTrafficByFirewallRules-velden

Name	Type	Nullable/Not nullable	Lijst met waarden
server	String	Null-waarde toegestaan	IP-adres van server
client	String	Null-waarde toegestaan	IP-adres van client
port	Numeriek	Null-waarde toegestaan	De serverpoort
vervoer	String	Null-waarde toegestaan	TCP, UDP of ICMP

zwakkeFirewallRules-velden

Name	Type	Nullable/Not nullable	Lijst met waarden
Bronnen	JSON-matrix met bronnen	Null-waarde toegestaan	JSON-matrix met bronnen in een van de volgende indelingen: - Any - ip address (host) - from ip-to ip (RANGE) - ip address, subnet mask (NETWORK)
Bestemmingen	JSON-matrix met bestemmingen	Null-waarde toegestaan	JSON-matrix met doelobjecten, in een van de volgende indelingen: - Any - ip address (host) - from ip-to ip (RANGE) - ip address, subnet mask (NETWORK)
poorten	JSON-matrix met poorten	Null-waarde toegestaan	JSON-matrix van poortobjecten, in een van de volgende indelingen: - Any - port (protocol, if detected) - from port-to port (protocol, if detected)

AccessPoints-velden

Name	Type	Nullable/Not nullable	Lijst met waarden
macAddress	String	Null-waarde toegestaan	Het MAC-adres van het toegangspunt
verkoper	String	Null-waarde toegestaan	De naam van de leverancier van het toegangspunt
ipAddress	String	Null-waarde toegestaan	Het IP-adres van het toegangspunt of N/B
name	String	Null-waarde toegestaan	De apparaatnaam van het toegangspunt of N/B
draadloos	String	Null-waarde toegestaan	Of het toegangspunt is verbonden met een draadloos netwerk: No, Suspectedof Yes

connectionsBetweenSubnets fields

Name	Type	Nullable/Not nullable	Lijst met waarden
server	String	Null-waarde toegestaan	Het IP-adres van de server
client	String	Null-waarde toegestaan	Het IP-adres van de client

velden industrialMalwareIndicators

Name	Type	Nullable/Not nullable	Lijst met waarden
detectionTime	Numeriek	Null-waarde toegestaan	Tijdstempel van de malware is voor het eerst gedetecteerd, in milliseconden van epoch-tijd en in UTC-tijdzone
alertMessage	String	Null-waarde toegestaan	Het verzonden waarschuwingsbericht
beschrijving	String	Null-waarde toegestaan	De beschrijving van het waarschuwingsbericht
apparaten	JSON-matrix	Niet nullable	Een JSON-matrix met tekenreeksen die apparaatnamen vertegenwoordigen

internetConnections (velden)

Name	Type	Nullable/Not nullable	Lijst met waarden
internalAddress	String	Null-waarde toegestaan	Het interne IP-adres van de verbinding
geautoriseerd	Booleaanse waarde	Null-waarde toegestaan	Yes of No
externalAddresses	JSON-matrix	Niet nullable	Een JSON-matrix van de externe IP-adressen van de verbinding

Responsvoorbeeld

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

Type: GET

API's:

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

Voorbeeld:

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

operationeel (operationele beveiligingsproblemen ophalen)

Gebruik deze API om resultaten van een algemene evaluatie van beveiligingsproblemen aan te vragen. Deze evaluatie biedt inzicht in de operationele status van uw netwerk. Het is gebaseerd op algemene netwerk- en systeeminformatie en niet op een specifieke apparaatevaluatie.

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

GET

Aanvragen

Deze API wordt aangeroepen zonder aanvraagparameters.

Response

Type: JSON-weergave van een of meer gegevenstabellen, elk met specifieke en mogelijk verschillende structuren.

Het antwoord wordt weergegeven in een kaartweergave, waarmee tabeltitels worden toegewezen aan tabelrijen. Rijen worden weergegeven als een lijst met objecten met dezelfde structuren.

resultaatvelden backupServer

Name	Type	Nullable/Not nullable	Lijst met waarden
bron	String	Null-waarde toegestaan	Het ip-adres van de bron
bestemming	String	Null-waarde toegestaan	Het doel-IP-adres
port	Numeriek	Null-waarde toegestaan	De poort van de back-upserver
vervoer	String	Null-waarde toegestaan	Het transportprotocol TCP van de back-upserver of UDP
backupMaximalInterval	String	Null-waarde toegestaan	De maximale intervaltijd tussen back-ups
lastSeenBackup	Numeriek	Null-waarde toegestaan	Tijdstempel dat een back-up voor het laatst is gezien, in milliseconden van epoch-tijd en in UTC-tijdzone

resultaatvelden ipNetworks

Name	Type	Nullable/Not nullable	Lijst met waarden
Adressen	Numeriek	Niet nullable	Het aantal IP-adressen dat in het subnetbereik is gedetecteerd.
netwerk	String	Niet nullable	Het basis-IP-adres van het subnet.
masker	String	Niet nullable	Het subnetmasker.

protocolProblems resultaatvelden

Name	Type	Nullable/Not nullable	Lijst met waarden
protocol	String	Niet nullable	Een protocol waarvoor een waarschuwing voor protocolschending is geactiveerd
Adressen	JSON-matrix met IP-adressen	Niet nullable	JSON-matrix met IP-adressen waarvan de schending afkomstig is
alert	String	Niet nullable	De titel van de geactiveerde waarschuwing
reportTime	Numeriek	Niet nullable	Tijdstempel dat een rapport voor het laatst is gegenereerd, in milliseconden van epoch-tijd en in UTC-tijdzone

resultaatvelden protocolDataVolumes

Name	Type	Nullable/Not nullable	Lijst met waarden
protocol	String	Null-waarde toegestaan	Een protocol dat is gedetecteerd op het netwerk door de OT-netwerksensor
volume	String	Null-waarde toegestaan	Het volume van protocolpakketten die zijn vastgelegd door de OT-netwerksensor, in MB

resultatenvelden voor verbroken verbindingen

Name	Type	Nullable/Not nullable	Lijst met waarden
assetAddress	String	Null-waarde toegestaan	Het IP-adres van de niet-verbonden asset
assetName	String	Null-waarde toegestaan	De naam van de niet-verbonden asset
lastDetectionTime	Numeriek	Null-waarde toegestaan	Tijdstempel dat de verbinding voor het laatst is gedetecteerd, in milliseconden van epoch-tijd en in UTC-tijdzone
backToNormalTime	Numeriek	Null-waarde toegestaan	Tijdstempel die de verbinding heeft geretourneerd, in milliseconden van epoch-tijd en in UTC-tijdzone

Responsvoorbeeld

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

Type: GET

API's:

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

Voorbeeld:

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

risicobeperking (risicobeperkingsstappen ophalen)

Gebruik deze API om een beperkingsevaluatie aan te vragen. Deze evaluatie biedt aanbevolen stappen voor het beperken van gedetecteerde beveiligingsproblemen. Het is gebaseerd op algemene netwerk- en systeeminformatie en niet op een specifieke apparaatevaluatie.

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

GET

Aanvragen

Deze API wordt aangeroepen zonder aanvraagparameters.

Response

Type: JSON

JSON-object dat de aanbevolen oplossingsstappen vertegenwoordigt.

Antwoordvelden

Veldnaam	Type	Nullable	Lijst met waarden
Meldingen	JSON-matrix met tekenreeksen	Niet nullable	Aanbevolen oplossingsstappen voor gedetecteerde beveiligingsproblemen
verzachting	JSON-matrix	Niet nullable	risicobeperkingsobjecten

risicobeperkingsvelden

Veldnaam	Type	Nullable	Lijst met waarden
tevreden	String	Niet nullable	Aanbevolen oplossingsstappen voor gedetecteerde beveiligingsproblemen
scoreImprovement	Geheel getal	Null-waarde toegestaan	Verwacht percentage van beveiligingsverbetering nadat er risicobeperkingsstappen zijn uitgevoerd.
bijzonderheden	Tabel	Null-waarde toegestaan	Een tabel met aanbevelingen voor risicobeperking, zoals die worden gegenereerd in het rapport Risicobeoordeling . Elke aanbeveling bevat details over mogelijke beveiligingsimpact als de actie wordt uitgevoerd en meer. Zie Risicobeperking voor meer informatie.

Notitie

Mogelijk hebt u meerdere beperkingsstappen, waarbij sommige in het notifications veld worden geretourneerd en andere in het mitigation veld worden geretourneerd. Items met scoreImprovement en details gegevens worden alleen in het mitigation veld geretourneerd. Items zonder scoreImprovement en details gegevens worden alleen in het notifications veld geretourneerd.

Responsvoorbeeld

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

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

Volgende stappen

Zie het overzicht van de defender voor IoT-API voor meer informatie.