Freigeben über

Create-Warnungs-API

  • Artikel

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 bitte die URIs, die in Microsoft Defender for Endpoint 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

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

  1. 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 Microsoft Defender for Endpoint 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 Create 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 Create 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 String 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.7115183ZErforderlich.
reportId String Die reportId des Ereignisses, wie sie von der erweiterten Suche abgerufen wird. Erforderlich.
machineId String ID des Geräts, auf dem das Ereignis identifiziert wurde. Erforderlich.
Schweregrad String Der Schweregrad der Warnung. Die Eigenschaftswerte sind: "Low", "Medium" und "High". Erforderlich.
title String Titel für die Warnung. Erforderlich.
description String Beschreibung der Warnung. Erforderlich.
recommendedAction String 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"
}

Tipp

Möchten Sie mehr erfahren? Engage mit der Microsoft-Sicherheitscommunity in unserer Tech Community: Microsoft Defender for Endpoint Tech Community.