Vytvoření rozhraní API pro upozornění

Popis rozhraní API

Vytvoří nové upozornění nad událostí.

• Microsoft Defender for Endpoint K vytvoření upozornění se vyžaduje událost.
• V požadavku musíte z události zadat tři parametry: Čas události, ID počítače a ID sestavy. Podívejte se na příklad níže.
• Můžete použít událost, kterou najdete v rozhraní API pro pokročilé proaktivní vyhledávání nebo na portálu.
• Pokud na stejném zařízení se stejným názvem existuje otevřené upozornění, nově vytvořené upozornění se s ním sloučí.
• Automatické prověřování se spustí automaticky u výstrah vytvořených prostřednictvím rozhraní API.

Omezení

Omezení rychlosti pro toto rozhraní API jsou 15 volání za minutu.

Oprávnění

Při získávání tokenu pomocí přihlašovacích údajů uživatele:

• Uživatel musí mít alespoň následující oprávnění role: Prověřování výstrah. Další informace najdete v tématu Vytváření a správa rolí.

• Uživatel musí mít přístup k zařízení přidruženému k upozornění na základě nastavení skupiny zařízení. Další informace najdete v tématu Vytváření a správa skupin zařízení.

K volání tohoto rozhraní API se vyžaduje jedno z následujících oprávnění. Další informace o tom, jak zvolit oprávnění, najdete v tématu Použití Microsoft Defender for Endpoint rozhraní API.

Typ oprávnění	Oprávnění	Zobrazovaný název oprávnění
Application	Alert.ReadWrite.All	Čtení a zápis všech výstrah
Delegovaný (pracovní nebo školní účet)	Alert.ReadWrite	Upozornění na čtení a zápis

Požadavek HTTP

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

Hlavičky požadavků

Name (Název)	Typ	Popis
Autorizace	String	Nosný {token}. Povinné.
Typ obsahu	String	application/json. Povinné.

Text požadavku

V textu požadavku zadejte následující hodnoty (všechny jsou povinné):

Vlastnost	Typ	Popis
eventTime	DateTime(UTC)	Přesný čas události jako řetězce, získaný z rozšířeného proaktivního vyhledávání. Například: 2018-08-03T16:45:21.7115183Z. Povinné.
id sestavy	String	ReportId události získané z rozšířeného proaktivního vyhledávání. Povinné.
id počítače	String	ID zařízení, na kterém byla událost identifikována. Povinné.
Závažnosti	String	Závažnost výstrahy. Hodnoty vlastností jsou: "Low", 'Medium' a 'High'. Povinné.
Název	String	Název upozornění Povinné.
description	String	Popis výstrahy Povinné.
recommendedAction	String	Při analýze výstrahy musí bezpečnostní pracovník provést tuto akci. Povinné.
Kategorie	String	Kategorie výstrahy. Hodnoty vlastností jsou: "General", "CommandAndControl", "Collection", "CredentialAccess", "DefenseEvasion", "Discovery", "Exfiltration", "Exploit", "Execution", "InitialAccess", "LateralMovement", "Malware", "Persistence", "PrivilegeEscalation", "Ransomware", "SuspiciousActivity" Povinné.

Reakce

Pokud je tato metoda úspěšná, vrátí 200 OK a nový objekt výstrahy v těle odpovědi. Pokud nebyla nalezena událost se zadanými vlastnostmi (reportId, eventTime a machineId), 404 Nenalezena.

Příklad

Požadavek

Tady je příklad požadavku.

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"
}