Referenz für die Warnungsverwaltungs-APIs für OT-Überwachungssensoren

In diesem Artikel werden die REST-APIs für die Warnungsverwaltung aufgeführt, die für OT-Überwachungssensoren von Microsoft Defender for IoT unterstützt werden.

alerts (Warnungsinformationen abrufen)

Mit dieser API können Sie eine Liste aller Warnungen anfordern, die vom Defender für IoT-Sensor erkannt wurden.

URI: /api/v1/alerts

GET

Anforderung

Abfrageparameter

Name	BESCHREIBUNG	Beispiel	Erforderlich/optional
state	Dient zum Abrufen von behandelten oder unbehandelten Warnungen. Unterstützte Werte: - handled - unhandled	/api/v1/alerts?state=handled	Optional
fromTime	Dient zum Abrufen von Warnungen ab einem bestimmten Zeitpunkt (in Millisekunden auf Basis der Epochenzeit und in der UTC-Zeitzone).	/api/v1/alerts?fromTime=<epoch>	Optional
toTime	Dient zum Abrufen von Warnungen vor einem bestimmten Zeitpunkt (in Millisekunden auf Basis der Epochenzeit und in der UTC-Zeitzone).	/api/v1/alerts?toTime=<epoch>	Optional
type	Dient zum Abrufen von Warnungen eines bestimmten Typs. Unterstützte Werte: - unexpected new devices - disconnections Alle anderen Werte werden ignoriert.	/api/v1/alerts?type=disconnections	Optional

Antwort

Typ: JSON

Eine Liste von Warnungen mit folgenden Feldern:

Name	type	Nullwerte zulassend/Keine Nullwerte zulassend	Liste der Werte
ID	Numeric	Lässt keine NULL-Werte zu	-
time	Numeric	Lässt keine NULL-Werte zu	Millisekunden ab der Epochenzeit und in UTC-Zeitzone
title	String	Lässt keine NULL-Werte zu	-
Nachricht	String	Lässt keine NULL-Werte zu	-
severity	String	Lässt keine NULL-Werte zu	Warning, Minor, Major oder Critical
engine	String	Lässt keine NULL-Werte zu	Protocol Violation, Policy Violation, Malware, Anomaly oder Operational
sourceDevice	Numeric	Nullwerte zulässig	Geräte-ID
destinationDevice	Numeric	Nullwerte zulässig	Geräte-ID
additionalInformation	Zusätzliches Informationsobjekt	Nullwerte zulässig	-

Zusätzliche Informationsfelder

Name	type	Nullwerte zulassend/Keine Nullwerte zulassend	Liste der Werte
description	String	Lässt keine NULL-Werte zu	-
information	JSON-Array	Lässt keine NULL-Werte zu	String

Für V2 hinzugefügt:

Name	type	Nullwerte zulassend/Keine Nullwerte zulassend	Liste der Werte
sourceDeviceAddress	String	Nullwerte zulässig	IP- oder MAC-Adresse
destinationDeviceAddress	String	Nullwerte zulässig	IP- oder MAC-Adresse
remediationSteps	JSON-Array	Lässt keine NULL-Werte zu	Zeichenfolgen, in der Warnung beschriebene Problembehandlungsschritte

Weitere Informationen finden Sie in der Referenz zur Sensor-API-Version.

Antwortbeispiel

[
    {
        "engine": "Policy Violation",
        "severity": "Major",
        "title": "Internet Access Detected",
        "additionalinformation": {
            "information": [
                "170.60.50.201 over port BACnet (47808)"
            ],
            "description": "External Addresses"
        },
        "sourceDevice": null,
        "destinationDevice": null,
        "time": 1509881077000,
        "message": "Device 192.168.0.13 tried to access an external IP address which is an address in the Internet and is not allowed by policy. It is recommended to notify the security officer of the incident.",
        "id": 1
    },
    {
        "engine": "Protocol Violation",
        "severity": "Major",
        "title": "Illegal MODBUS Operation (Exception Raised by Master)",
        "sourceDevice": 3,
        "destinationDevice": 4,
        "time": 1505651605000,
        "message": "A MODBUS master 192.168.110.131 attempted to initiate an illegal operation.\nThe operation is considered to be illegal since it incorporated function code \#129 which should not be used by a master.\nIt is recommended to notify the security officer of the incident.",
        "id": 2,
        "additionalInformation": null,
    }
]

cURL-Befehl

Typ: GET

API:

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/api/v1/alerts?state=<STATE>&fromTime=<FROM_TIME>&toTime=<TO_TIME>&type=<TYPE>'

Beispiel:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/api/v1/alerts?state=unhandled&fromTime=1594550986000&toTime=1594550986001&type=disconnections'

events (Abrufen von Zeitachsenereignissen)

Mit dieser API können Sie eine Liste der Ereignisse anfordern, die an die Ereigniszeitachse gemeldet wurden.

Hinweis

Wenn Sie die gleiche API innerhalb der gleichen Stunde mit genau den gleichen Parameterwerten ausführen, wird ein zwischengespeicherter Wert zurückgegeben. Wenn Sie diese API zweimal innerhalb einer Stunde ausführen, empfiehlt es sich, die Abfrageparameter zu ändern, um eine aktualisierte Antwort zu erhalten.

URI: /api/v1/events

GET

Anforderung

Abfrageparameter

Name	BESCHREIBUNG	Beispiel	Erforderlich/optional
minutesTimeFrame	Dient zum Filtern der Ergebnisse nach einem bestimmten Zeitrahmen, in dem Ereignisse gemeldet wurden. Wird rückwärts ab der aktuellen Zeit definiert. Höchstwert: 4320 (drei Tage). Höhere Werte werden als 4.320 behandelt (ohne Fehler).	/api/v1/events?minutesTimeFrame=20	Optional
type	Dient zum Filtern der Ergebnisse nach einem bestimmten Typ. Werte, bei denen es sich nicht um unterstützte Typen handelt, werden ignoriert. Weitere Informationen finden Sie in der Referenz zu type und title von Ereignissen.	/api/v1/events?type=DEVICE_CONNECTION_CREATED /api/v1/events?type=REMOTE_ACCESS&minutesTimeFrame	Optional

Antwort

Typ: JSON

Array von JSON-Objekten, die die 100 neuesten Ereignisse darstellen (sortiert nach Ereigniszeitstempel und beginnend mit dem neuesten Ereignis).

Ereignisfelder umfassen Folgendes:

Name	type	Nullwerte zulassend/Keine Nullwerte zulassend	Liste der Werte
timestamp	Numeric	Lässt keine NULL-Werte zu	Millisekunden ab der Epochenzeit und in UTC-Zeitzone
type	String	Lässt keine NULL-Werte zu	Einer der unterstützten Typen.
title	String	Lässt keine NULL-Werte zu	Einer der unterstützten Titel.
severity	String	Lässt keine NULL-Werte zu	INFO, NOTICEoder ALERT
owner	String	Nullwerte zulässig	Eine Zeichenfolge. Wenn das Ereignis manuell erstellt wurde, enthält dieses Feld den Namen des Benutzers, der das Ereignis erstellt hat.
content	String	Lässt keine NULL-Werte zu	Zeichenfolge zur Beschreibung des Ereignisses.

Antwortbeispiel

[
    {
        "severity": "INFO",
        "title": "Back to Normal",
        "timestamp": 1504097077000,
        "content": "Device 10.2.1.15 was found responsive, after being suspected as disconnected",
        "owner": null,
        "type": "BACK_TO_NORMAL"
    },
    {
        "severity": "ALERT",
        "title": "Alert Detected",
        "timestamp": 1504096909000,
        "content": "Device 10.2.1.15 is suspected to be disconnected (unresponsive).",
        "owner": null,
        "type": "ALERT_REPORTED"
    },
    {
        "severity": "ALERT",
        "title": "Alert Detected",
        "timestamp": 1504094446000,
        "content": "A DNP3 Master 10.2.1.14 attempted to initiate a request which is not allowed by policy.\nThe policy indicates the allowed function codes, address ranges, point indexes and time intervals.\nIt is recommended to notify the security officer of the incident.",
        "owner": null,
        "type": "ALERT_REPORTED"
    },
    {
        "severity": "NOTICE",
        "title": "PLC Program Update",
        "timestamp": 1504094344000,
        "content": "Program update detected, sent from 10.2.1.25 to 10.2.1.14",
        "owner": null,
        "type": "PROGRAM_DEVICE"
    }
]

cURL-Befehl

Typ: GET

API:

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/api/v1/events?minutesTimeFrame=<TIME_FRAEM>&type=<TYPE>'

Beispiel:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/api/v1/events?minutesTimeFrame=20&type=DEVICE_CONNECTION_CREATED'`

Referenz zu type und title von Ereignissen

In diesem Abschnitt werden die Werte aufgelistet, die als Ereignistyp (type) und Ereignistitel (title) für die Ereignis-API unterstützt werden.

Ereignistyp	Veranstaltungstitel
DEVICE_CREATE	Gerät erkannt
DEVICE_UPDATE	Gerät aktualisiert
ALERT_REPORTED	Warnung erkannt
ALERT_UPDATED	Warnung aktualisiert
SCAN	Scangerät erkannt
PROGRAM_DEVICE	SPS-Programmierung
MMS_PROGRAM_DEVICE	SPS-Programmaktualisierung
SCL_UPLOADED	Speicherclientbibliothek hochgeladen
EXCLUSION_RULE_CREATED	Ausschlussregel erstellt
EXCLUSION_RULE_REMOVED	Ausschlussregel entfernt
EXCLUSION_RULE_UPDATED	Ausschlussregel aktualisiert
DEVICE_CONNECTION_CREATED	Geräteverbindung erkannt
USER_LOGIN	Anmeldeversuch eines Benutzers
FILE_TRANSFER	Dateiübertragung erkannt
CUSTOM_EVENT	Benutzerdefiniertes Ereignis
REMOTE_ACCESS	Remotezugriffsverbindung eingerichtet
BACK_TO_NORMAL	Zurück zum Normalzustand
MMS_MEMORY_BLOCK_OPERATION	MMS-Arbeitsspeicherblockvorgang
MMS_PROGRAM_OPERATION	MMS-Programmvorgang
HTTP_BASIC_AUTHENTICATION	HTTP-Standardauthentifizierung
SIEMENS_S_7_MEMORY_BLOCK_OPERATION	Siemens S7-Arbeitsspeicherblockvorgang
SIEMENS_S_7_AUTHENTICATION	Siemens S7-Authentifizierung
REPORT_CREATED	Bericht erstellt
SNMP_TRAP	SNMP-Trap erkannt
DATABASE_ACTION	Manipulation der Datenbankstruktur
PLC_MODULE_CHANGE	SPS-Moduländerung
FIRMWARE_UPDATE	Firmwareupdate
PLC_START	SPS-Start
SRTP_PLC_RESET	SPS-Zurücksetzung
SRTP_PLC_COPY_FIRMWARE	Firmwareupdate
SRTP_LOGIN_PROGRAMMING	SPS-Programmiermodus festgelegt
SRTP_PLC_CHANGE_PASSWORD	SPS-Kennwortänderung
OPC_DATA_ACCESS_GROUP_MANAGEMENT_OPERATION	OPC-Datenzugriff: Gruppenverwaltungsvorgang
OPC_DATA_ACCESS_ITEM_MANAGEMENT_OPERATION	OPC-Datenzugriff: Elementverwaltungsvorgang
OPC_DATA_ACCESS_IO_SUBSCRIPTION_MANAGEMENT_OPERATION	OPC-Datenzugriff: Verwaltungsvorgang für E/A-Abonnement
OPC_AE_EVENT_SUBSCRIPTION	OPC-AE-Ereignis: Abonnement
OPC_AE_EVENT_CONDITION_MANAGEMENT_OPERATION	OPC-AE-Ereignis: Bedingungsverwaltungsvorgang
OPC_AE_EVENT	OPC-AE-Ereignis
SRTP_CHANGE_PRIVILEGE	SPS: Änderung der Zugriffsebene
SRTP_CHANGE_LEVEL_FAILED	SPS: Fehler beim Ändern der Zugriffsebene
SUITELINK_INIT_CONNECTION	Wonderware-Sitzung initialisiert
USER_OPERATION	Benutzervorgang
DIP_UPLOADED	Data Intelligence-Paket hochgeladen
FTP_AUTHENTICATION_FAILURE	FTP-Authentifizierungsfehler
PROFINET_DPC_VALUE_SET	SET-Vorgang für Profinet
S7PLUS_PLC_MODE_CHANGE	SPS-Modusänderung
S7_PLC_MODE_CHANGE	SPS-Modusänderung
DELETE_DEVICE	Gerät gelöscht
S7PLUS_PROGRAMMING	SPS-Programmierung
FIRMWARE_CHANGED	SPS-Firmware geändert
DELTAV_PROGRAMMING	DeltaV-Installationsskript
USER_DEFINED_RULE_CREATED	Benutzerdefinierte Regel erstellt
USER_DEFINED_RULE_EDITED	Benutzerdefinierte Regel bearbeitet
USER_DEFINED_RULE_DELETED	Benutzerdefinierte Regel gelöscht
USER_DEFINED_RULE_OPERATION	Vorgang für benutzerdefinierte Regel
REMOTE_PROCESS_EXECUTION	Remoteprozessausführung
DEVICE_UNIFICATION	Gerät aktualisiert
NOTIFICATION	Manuell aufgelöste Benachrichtigung
ENIP_CONTROLLER_PROGRAM_DELETE	Controllerprogramm gelöscht
ENIP_CONTROLLER_PROGRAM_RESET	Controllerprogramm zurückgesetzt
ENIP_CONTROLLER_GENERIC_RESET	Controllerzurücksetzung
ENIP_CONTROLLER_GENERIC_STOP	Controllerbeendung
ENIP_CONTROLLER_GENERIC_START	Controllerstart
TELNET_AUTHENTICATION_FAILURE	Telnet-Authentifizierungsfehler
CONFIGURATION_OF_CLEARTEXT_PASSWORD	Konfiguration von Klartextkennwort
CLEARTEXT_AUTHENTICATION	Klartextauthentifizierung
PROGRAM_UPLOAD_DEVICE	SPS-Programmupload
CONFIGURATION_CHANGE	SPS-Konfiguration geschrieben
CONFIGURATION_READ	SPS-Konfiguration gelesen
SYSLOG_MSG	Syslog-Meldung
INTERNET_ACCESS	Zugriff auf das Internet
CAMP_MEMORY_WRITE_OPERATION	Arbeitsspeicherschreibvorgang für allgemeines ASCII-Nachrichtenprotokoll
MUTED_ALERT	Ereignis erkannt und stummgeschaltet
DHCP_UPDATE	Adressaktualisierung
DIP_FAILURE	Fehler beim Installieren des Data Intelligence-Pakets
DELETE_DEVICE_SCHEDULE	Inaktive Geräte mit geplanter Löschung
PLC_OPERATING_MODE_CHANGED	SPS-Betriebsmodusänderung erkannt
HARDWARE_UPDATE_BY_IDENTIFIER	Adressaktualisierung

Nächste Schritte

Weitere Informationen finden Sie in der Übersicht zur API-Referenz – Defender for IoT.