Tworzenie interfejsu API alertów

Artykuł
07/04/2024

Dotyczy:

Chcesz poznać usługę ochrony punktu końcowego w usłudze Microsoft Defender? Utwórz konto, aby skorzystać z bezpłatnej wersji próbnej.

Uwaga

Jeśli jesteś klientem rządowym USA, użyj identyfikatorów URI wymienionych w usłudze Microsoft Defender for Endpoint dla klientów rządowych USA.

Porada

Aby uzyskać lepszą wydajność, możesz użyć serwera bliżej lokalizacji geograficznej:

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

Opis interfejsu API

Tworzy nowy alert na początku zdarzenia.

Zdarzenie programu Microsoft Defender dla punktu końcowego jest wymagane do utworzenia alertu.
Musisz podać trzy parametry z zdarzenia w żądaniu: czas zdarzenia, identyfikator maszyny i identyfikator raportu. Zobacz przykład poniżej.
Można użyć zdarzenia znalezionego w interfejsie API zaawansowanego wyszukiwania zagrożeń lub portalu.
Jeśli na tym samym urządzeniu istnieje otwarty alert o tym samym tytule, nowy utworzony alert zostanie scalony z nim.
Automatyczne badanie uruchamia się automatycznie w przypadku alertów utworzonych za pośrednictwem interfejsu API.

Ograniczenia

Ograniczenia szybkości dla tego interfejsu API to 15 wywołań na minutę.

Uprawnienia

Do wywołania tego interfejsu API jest wymagane jedno z następujących uprawnień. Aby dowiedzieć się więcej, w tym jak wybrać uprawnienia, zobacz Korzystanie z usługi Microsoft Defender dla interfejsów API punktu końcowego.

Typ uprawnień	Uprawnienie	Nazwa wyświetlana uprawnień
Aplikacja	Alert.ReadWrite.All	"Odczytywanie i zapisywanie wszystkich alertów"
Delegowane (konto służbowe)	Alert.ReadWrite	"Odczyt i zapis alertów"

Uwaga

Podczas uzyskiwania tokenu przy użyciu poświadczeń użytkownika:

Użytkownik musi mieć co najmniej następujące uprawnienia roli: Badanie alertów. Aby uzyskać więcej informacji, zobacz Tworzenie ról i zarządzanie nimi.
Użytkownik musi mieć dostęp do urządzenia skojarzonego z alertem na podstawie ustawień grupy urządzeń. Aby uzyskać więcej informacji, zobacz Tworzenie grup urządzeń i zarządzanie nimi.

Tworzenie grupy urządzeń jest obsługiwane zarówno w usłudze Defender for Endpoint Plan 1, jak i Plan 2

Żądanie HTTP

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

Nagłówki żądań

Name (Nazwa)	Wpisać	Opis
Autoryzacja	Ciąg	Element nośny {token}. Wymagane.
Typ zawartości	Ciąg	application/json. Wymagane.

Treść żądania

W treści żądania podaj następujące wartości (wszystkie są wymagane):

Własność	Wpisać	Opis
eventTime	DateTime(UTC)	Dokładny czas zdarzenia jako ciągu, uzyskany z zaawansowanego wyszukiwania zagrożeń. Na przykład `2018-08-03T16:45:21.7115183Z`Wymagane.
reportId	Ciąg	Identyfikator reportId zdarzenia, uzyskany z zaawansowanego wyszukiwania zagrożeń. Wymagane.
machineId	Ciąg	Identyfikator urządzenia, na którym zostało zidentyfikowane zdarzenie. Wymagane.
dotkliwość	Ciąg	Ważność alertu. Wartości właściwości to: "Low", "Medium" i "High". Wymagane.
tytuł	Ciąg	Tytuł alertu. Wymagane.
opis	Ciąg	Opis alertu. Wymagane.
recommendedAction	Ciąg	Oficer ds. zabezpieczeń musi podjąć tę akcję podczas analizowania alertu. Wymagane.
kategoria	Ciąg	Kategoria alertu. Wartości właściwości to: "Ogólne", "CommandAndControl", "Collection", "CredentialAccess", "DefenseEvasion", "Discovery", "Exfiltration", "Exploit", "Execution", "InitialAccess", "LateralMovement", "Malware", "Persistence", "PrivilegeEscalation", "Ransomware", "SuspiciousActivity" Required.

Odpowiedź

W przypadku powodzenia ta metoda zwraca wartość 200 OK i nowy obiekt alertu w treści odpowiedzi. Jeśli nie znaleziono zdarzenia o określonych właściwościach (reportId, eventTime i machineId) — 404 Nie znaleziono.

Przykład

Prosić

Oto przykład żądania.

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