Erstellen einer Warnungs-API

API-Beschreibung

Erstellt eine neue Warnung über dem Ereignis.

• Microsoft Defender for Endpoint-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

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.

Eine der nachfolgenden Berechtigungen ist erforderlich, um diese API aufrufen zu können. Weitere Informationen zum Auswählen von Berechtigungen finden Sie unter Verwenden von Microsoft Defender for Endpoint-APIs.

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

HTTP-Anforderung

POST https://api.security.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.security.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"
}