Erstellen einer Warnungs-API

Artikel
07/04/2024

Gilt für:

Möchten Sie Microsoft Defender für Endpunkt ausprobieren? Registrieren Sie sich für eine kostenlose Testversion.

Hinweis

Wenn Sie ein US Government-Kunde sind, verwenden Sie die URIs, die unter Microsoft Defender für Endpunkt für US Government-Kunden aufgeführt sind.

Tipp

Um die Leistung zu verbessern, können Sie den Server näher an Ihrem geografischen Standort verwenden:

us.api.security.microsoft.com
eu.api.security.microsoft.com
uk.api.security.microsoft.com
au.api.security.microsoft.com
swa.api.security.microsoft.com
ina.api.security.microsoft.com

API-Beschreibung

Erstellt eine neue Warnung über dem Ereignis.

Das Microsoft Defender für Endpunkt-Ereignis ist für die Warnungserstellung erforderlich.
Sie müssen drei Parameter aus dem Ereignis in der Anforderung angeben: Ereigniszeit, Computer-ID und Berichts-ID. Siehe Beispiel unten.
Sie können ein Ereignis verwenden, das in der API für die erweiterte Suche oder im Portal zu finden ist.
Wenn auf demselben Gerät mit demselben Titel eine offene Warnung vorhanden ist, wird die neu erstellte Warnung mit dieser zusammengeführt.
Bei Warnungen, die über die API erstellt wurden, wird automatisch eine automatische Untersuchung gestartet.

Begrenzungen

Die Ratenbeschränkungen für diese API sind 15 Aufrufe pro Minute.

Berechtigungen

Eine der nachfolgenden Berechtigungen ist erforderlich, um diese API aufrufen zu können. Weitere Informationen, einschließlich der Auswahl von Berechtigungen, finden Sie unter Verwenden von Microsoft Defender für Endpunkt-APIs.

Berechtigungstyp	Berechtigung	Anzeigename der Berechtigung
App	Alert.ReadWrite.All	"Alle Warnungen lesen und schreiben"
Delegiert (Geschäfts-, Schul- oder Unikonto)	Alert.ReadWrite	Warnungen zum Lesen und Schreiben

Hinweis

Beim Abrufen eines Tokens mit Benutzeranmeldeinformationen:

Der Benutzer muss mindestens über die folgende Rollenberechtigung verfügen: Untersuchung von Warnungen. Weitere Informationen finden Sie unter Erstellen und Verwalten von Rollen.
Der Benutzer muss basierend auf den Gerätegruppeneinstellungen Zugriff auf das der Warnung zugeordnete Gerät haben. Weitere Informationen finden Sie unter Erstellen und Verwalten von Gerätegruppen.

Die Erstellung von Gerätegruppen wird sowohl in Defender für Endpunkt Plan 1 als auch in Plan 2 unterstützt.

HTTP-Anforderung

POST https://api.securitycenter.microsoft.com/api/alerts/CreateAlertByReference

Anforderungsheader

Name	Typ	Beschreibung
Authorization	Zeichenfolge	Bearer {token}. Erforderlich.
Content-Type	Zeichenfolge	application/json. Erforderlich.

Anforderungstext

Geben Sie im Anforderungstext die folgenden Werte an (alle sind erforderlich):

Eigenschaft	Typ	Beschreibung
eventTime	DateTime(UTC)	Die genaue Zeit des Ereignisses als Zeichenfolge, die von der erweiterten Suche abgerufen wird. Beispiel: `2018-08-03T16:45:21.7115183Z`Erforderlich.
reportId	Zeichenfolge	Die reportId des Ereignisses, wie sie von der erweiterten Suche abgerufen wird. Erforderlich.
machineId	Zeichenfolge	ID des Geräts, auf dem das Ereignis identifiziert wurde. Erforderlich.
Schweregrad	Zeichenfolge	Der Schweregrad der Warnung. Die Eigenschaftswerte sind: "Low", "Medium" und "High". Erforderlich.
title	String	Titel für die Warnung. Erforderlich.
description	Zeichenfolge	Beschreibung der Warnung. Erforderlich.
recommendedAction	Zeichenfolge	Der Sicherheitsbeauftragte muss diese Aktion ausführen, wenn die Warnung analysiert wird. Erforderlich.
category	String	Die Kategorie der Warnung. Die Eigenschaftswerte sind: "General", "CommandAndControl", "Collection", "CredentialAccess", "DefenseEvasion", "Discovery", "Exfiltration", "Exploit", "Execution", "InitialAccess", "LateralMovement", "Malware", "Persistence", "PrivilegeEscalation", "Ransomware", "SuspiciousActivity" erforderlich.

Antwort

Bei erfolgreicher Ausführung gibt die Methode 200 OK und ein neues Warnungsobjekt im Antworttext zurück. Wenn das Ereignis mit den angegebenen Eigenschaften (reportId, eventTime und machineId) nicht gefunden wurde– 404 Nicht gefunden.

Beispiel

Anforderung

Hier sehen Sie ein Beispiel für die Anforderung.

POST https://api.securitycenter.microsoft.com/api/alerts/CreateAlertByReference

{
    "machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
    "severity": "Low",
    "title": "example",
    "description": "example alert",
    "recommendedAction": "nothing",
    "eventTime": "2018-08-03T16:45:21.7115183Z",
    "reportId": "20776",
    "category": "Exploit"
}