Freigeben über


API-Referenz zur Warnungsverwaltung für lokale Verwaltungskonsolen

In diesem Artikel werden die Warnungsverwaltungs-REST-APIs aufgeführt, die für lokale Microsoft Defender for IoT-Verwaltungskonsolen unterstützt werden.

alerts (Warnungsinformationen abrufen)

Mit dieser API können Sie alle oder gefilterte Warnungen von einer lokalen Verwaltungskonsole abrufen.

URI: /external/v1/alerts oder /external/v2/alerts

GET

Abfrageparameter:

Name BESCHREIBUNG Beispiel Erforderlich/optional
state Dient zum Abrufen von behandelten oder unbehandelten Warnungen. Unterstützte Werte:
- handled
- unhandled
Alle anderen Werte werden ignoriert.
/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
siteId Der Standort, an dem die Warnung erkannt wurde. /api/v1/alerts?siteId=1 Optional
zoneId Die Zone, in der die Warnung erkannt wurde. /api/v1/alerts?zoneId=1 Optional
sensorId Der Sensor, auf dem die Warnung erkannt wurde. /api/v1/alerts?sensorId=1 Optional

Hinweis

Die Standort- und Zonen-IDs sind Ihnen möglicherweise nicht bekannt. Fragen Sie in diesem Fall zunächst alle Geräte ab, um die Standort- und Zonen-IDs abzurufen. Weitere Informationen finden Sie unter Integrations-API-Referenz für lokale Verwaltungskonsolen (öffentliche Vorschau).

UUID (Warnungen basierend auf der UUID verwalten)

Verwenden Sie diese API, um angegebene Aktionen für eine bestimmte Warnung auszuführen, die von Defender for IoT erkannt wurde.

Sie können mit dieser API beispielsweise eine Weiterleitungsregel erstellen, die Daten an QRadar weiterleitet. Weitere Informationen finden Sie unter Integrieren von Qradar in Microsoft Defender for loT.

URI: /external/v1/alerts/<UUID>

PUT

Typ: JSON

Abfrageparameter:

Name BESCHREIBUNG Beispiel Erforderlich/optional
UUID Definiert den Universally Unique Identifier (UUID, universell eindeutiger Bezeichner) für die Warnung, die Sie behandeln oder für die Sie einen Bearbeitungs- und Lernvorgang durchführen möchten. /api/v1/alerts/7903F632-H7EJ-4N69-F40F-4B1E689G00Q0 Erforderlich

Textparameter

Name BESCHREIBUNG Beispiel Erforderlich/optional
action String Entweder handle oder handleAndLearn Erforderlich

Anforderungsbeispiel

{
    "action": "handle"
}

maintenanceWindow (Warnungsausschlüsse erstellen)

Dient zum Verwalten von Wartungsfenstern, in denen keine Warnungen gesendet werden. Definieren und aktualisieren Sie mit dieser API End- und Startzeiten, Geräte oder Subnetze, die beim Auslösen von Warnungen ausgeschlossen werden sollen, oder Defender for IoT-Engines, die nicht einbezogen werden sollen.

Während eines Wartungsfensters können Sie beispielsweise die Übermittlung aller Warnungen mit Ausnahme von Malwarewarnungen auf wichtigen Geräten unterbrechen.

Die mit der maintenanceWindow-API definierten Wartungsfenster werden im Fenster „Warnungsausschlüsse“ der lokalen Verwaltungskonsole als schreibgeschützte Ausschlussregel angezeigt und mit der folgenden Syntax benannt: Maintenance-{token name}-{ticket ID}.

Wichtig

Diese API wird nur für Wartungszwecke und nur für eine begrenzte Zeit unterstützt und sollte nicht anstelle von Warnungsausschlussregeln verwendet werden. Verwenden Sie diese API nur für einmalige, zeitlich begrenzte Wartungsvorgänge.

URI: /external/v1/maintenanceWindow

POST

Dienst zum Erstellen eines neuen Wartungsfensters.

Textparameter:

Name BESCHREIBUNG Beispiel Erforderlich/optional
ticketId Eine Zeichenfolge. Definiert die ID des Wartungstickets in den Systemen des Benutzers. Stellen Sie sicher, dass die Ticket-ID nicht mit einem vorhandenen geöffneten Wartungsfenster verknüpft ist. 2987345p98234 Erforderlich
ttl Positive ganze Zahl. Definiert die Gültigkeitsdauer (Time to Live, TTL), welche die Dauer des Wartungsfensters in Minuten angibt. Nach dem definierten Zeitraum endet das Wartungsfenster, und das System verhält sich wieder normal. 180 Erforderlich
engines JSON-Array mit Zeichenfolgen. Definiert die Engine, deren Warnungen während des Wartungsfensters unterdrückt werden sollen. Mögliche Werte:

- ANOMALY
- MALWARE
- OPERATIONAL
- POLICY_VIOLATION
- PROTOCOL_VIOLATION
ANOMALY,OPERATIONAL Optional
sensorIds JSON-Array mit Zeichenfolgen. Definiert die Sensoren, deren Warnungen während des Wartungsfensters unterdrückt werden sollen. Sie können die Sensor-IDs mit der API appliances (OT-Sensor-Appliances verwalten) abrufen. 1,35,63 Optional
Subnetze JSON-Array mit Zeichenfolgen. Definiert die Subnetze, deren Warnungen während des Wartungsfensters unterdrückt werden sollen. Definieren Sie jedes Subnetz in einer CIDR-Notation. 192.168.0.0/16,138.136.80.0/14,112.138.10.0/8 Optional

Delete

Schließt ein vorhandenes Wartungsfenster.

Abfrageparameter:

Name BESCHREIBUNG Beispiel Erforderlich/optional
ticketId Definiert die ID des Wartungstickets in den Systemen des Benutzers. Stellen Sie sicher, dass die Ticket-ID mit einem vorhandenen geöffneten Wartungsfenster verknüpft ist. 2987345p98234 Erforderlich

GET

Dient zum Abrufen eines Protokolls aller Aktionen zum Öffnen (POST), Schließen (DELETE) und Aktualisieren (PUT) ab, die mithilfe dieser API für die Behandlung von Wartungsfenstern ausgeführt wurden. T

Abfrageparameter:

Name Beschreibung Beispiel Erforderlich/optional
fromDate Filtert die Protokolle aufsteigend ab dem vordefinierten Datum. Das Format ist YYYY-MM-DD. 2022-08-10 Optional
toDate Filtert die Protokolle bis zum vordefinierten Datum. Das Format ist YYYY-MM-DD. 2022-08-10 Optional
ticketId Filtert die Protokolle, die mit einer bestimmten Ticket-ID verknüpft sind. 9a5fe99c-d914-4bda-9332-307384fe40bf Optional
tokenName Filtert die Protokolle, die mit einem bestimmten Tokennamen verknüpft sind. quarterly-sanity-window Optional

Fehlercodes:

Code `Message` BESCHREIBUNG
200 OK Die Aktion wurde erfolgreich abgeschlossen.
204: Kein Inhalt Es sind keine anzuzeigenden Daten vorhanden.
400 Ungültige Anforderung Das Datumsformat ist falsch.
500 Interner Serverfehler Sonstiger unerwarteter Fehler.

PUT

Ermöglicht es Ihnen, durch Ändern des ttl-Parameters die Dauer des Wartungsfensters zu aktualisieren, nachdem Sie den Wartungsvorgang gestartet haben. Die neue Definition der Dauer überschreibt die vorherige Definition.

Diese Methode ist hilfreich, wenn Sie anstelle der aktuell konfigurierten Dauer eine längere Zeitspanne festlegen möchten. Wenn Sie beispielsweise ursprünglich 180 Minuten definiert haben, 90 Minuten verstrichen sind und Sie weitere 30 Minuten hinzufügen möchten, ändern Sie den ttl-Wert in 120 Minuten, um die Dauer zurückzusetzen.

Abfrageparameter:

Name BESCHREIBUNG Beispiel Erforderlich/optional
ticketId Eine Zeichenfolge. Definiert die ID des Wartungstickets in den Systemen des Benutzers. 2987345p98234 Erforderlich
ttl Positive ganze Zahl. Definiert die Dauer des Fensters in Minuten. 210 Erforderlich

pcap (Warnungs-PCAP anfordern)

Verwenden Sie diese API, um eine PCAP-Datei im Zusammenhang mit einer Warnung anzufordern.

URI: /external/v2/alerts/

GET

Abfrageparameter:

Name BESCHREIBUNG Beispiel Erforderlich/optional
id Warnungs-ID der lokalen Verwaltungskonsole /external/v2/alerts/pcap/<id> Erforderlich

Nächste Schritte

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