Udostępnij za pośrednictwem

interfejs API alertów Twórca

  • Artykuł

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 Ochrona punktu końcowego w usłudze Microsoft Defender 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

Opis interfejsu API

Tworzy nowy alert na początku zdarzenia.

  • Ochrona punktu końcowego w usłudze Microsoft Defender zdarzenie 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

  1. 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 Używanie interfejsów API Ochrona punktu końcowego w usłudze Microsoft Defender.

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 Twórca i zarządzanie rolami.
  • Użytkownik musi mieć dostęp do urządzenia skojarzonego z alertem na podstawie ustawień grupy urządzeń. Aby uzyskać więcej informacji, zobacz Twórca i zarządzanie grupami urządzeń.

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
Autoryzacji 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łaściwość 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.7115183ZWymagane.
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.
Ważności 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.
Kategorii 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.

Odpowiedzi

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

Żądanie

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

Porada

Chcesz dowiedzieć się więcej? Engage ze społecznością microsoft security w naszej społeczności technicznej: Ochrona punktu końcowego w usłudze Microsoft Defender Tech Community.