Microsoft 365 Defender zaawansowany interfejs API wyszukiwania zagrożeń

Uwaga

Chcesz skorzystać z usługi Microsoft 365 Defender? Dowiedz się więcej o tym, jak można oceniać i pilotować Microsoft 365 Defender.

Dotyczy:

  • Microsoft 365 Defender

Uwaga

Wypróbuj nasze nowe interfejsy API przy użyciu interfejsu API zabezpieczeń programu MS Graph. Dowiedz się więcej na stronie: Korzystanie z interfejsu API zabezpieczeń programu Microsoft Graph — Microsoft Graph w wersji beta | Microsoft Learn.

Ważna

Niektóre informacje odnoszą się do wstępnie wydanego produktu, który może zostać znacząco zmodyfikowany przed jego komercyjną premierą. Firma Microsoft nie udziela żadnych gwarancji, wyraźnych ani dorozumianych, w odniesieniu do podanych tutaj informacji.

Zaawansowane wyszukiwanie zagrożeń to narzędzie do wyszukiwania zagrożeń, które używa specjalnie skonstruowanych zapytań do badania danych zdarzeń z ostatnich 30 dni w Microsoft 365 Defender. Zaawansowane zapytania dotyczące wyszukiwania zagrożeń umożliwiają inspekcję nietypowych działań, wykrywanie możliwych zagrożeń, a nawet reagowanie na ataki. Zaawansowany interfejs API wyszukiwania zagrożeń umożliwia programowe wykonywanie zapytań dotyczących danych zdarzeń.

Przydziały i alokacja zasobów

Poniższe warunki odnoszą się do wszystkich zapytań.

  1. Zapytania eksplorują i zwracają dane z ostatnich 30 dni.
  2. Wyniki mogą zwracać do 100 000 wierszy.
  3. Możesz wykonywać maksymalnie 45 wywołań na minutę na dzierżawę.
  4. Zapytania są blokowane, jeśli dzierżawa osiągnęła 100% aż do następnego 15-minutowego cyklu.
  5. Jeśli pojedyncze żądanie jest uruchamiane dłużej niż 10 minut, upłynął limit czasu i zwróci błąd.
  6. Kod 429 odpowiedzi HTTP wskazuje, że osiągnięto limit przydziału, liczbę wysłanych żądań lub przydzielony czas wykonywania. Przeczytaj treść odpowiedzi, aby zrozumieć osiągnięty limit.

Uwaga

Wszystkie limity przydziału wymienione powyżej (na przykład 15 wywołań na minutę) są szerokie dla dzierżawy. Te limity przydziału są minimalne.

Uprawnienia

Do wywołania zaawansowanego interfejsu API wyszukiwania zagrożeń jest wymagane jedno z następujących uprawnień. Aby dowiedzieć się więcej, w tym jak wybrać uprawnienia, zobacz Uzyskiwanie dostępu do interfejsów API Microsoft 365 Defender Protection.

Typ uprawnień Uprawnienia Nazwa wyświetlana uprawnień
Aplikacja AdvancedHunting.Read.All Uruchamianie zaawansowanych zapytań
Delegowane (konto służbowe) AdvancedHunting.Read Uruchamianie zaawansowanych zapytań

Uwaga

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

  • Użytkownik musi mieć rolę "Wyświetl dane".
  • Użytkownik musi mieć dostęp do urządzenia na podstawie ustawień grupy urządzeń.

Żądanie HTTP

POST https://api.security.microsoft.com/api/advancedhunting/run

Nagłówki żądań

Nagłówek Value
Autoryzacji Nośnik {token} Uwaga: wymagane
Typ zawartości application/json

Treść żądania

W treści żądania podaj obiekt JSON z następującymi parametrami:

Parametr Wpisać Opis
Kwerendy Tekst Zapytanie do uruchomienia. (wymagane)

Odpowiedzi

Jeśli to się powiedzie, ta metoda zwróci 200 OKobiekt , i QueryResponse w treści odpowiedzi.

Obiekt odpowiedzi zawiera trzy właściwości najwyższego poziomu:

  1. Statystyki — słownik statystyk wydajności zapytań.
  2. Schemat — schemat odpowiedzi, lista par Name-Type dla każdej kolumny.
  3. Wyniki — lista zaawansowanych zdarzeń wyszukiwania zagrożeń.

Przykład

W poniższym przykładzie użytkownik wysyła poniższe zapytanie i odbiera obiekt odpowiedzi interfejsu API zawierający Stats, Schemai Results.

Kwerendy

{
    "Query":"DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2"
}

Obiekt odpowiedzi

{
    "Stats": {
        "ExecutionTime": 4.621215,
        "resource_usage": {
            "cache": {
                "memory": {
                    "hits": 773461,
                    "misses": 4481,
                    "total": 777942
                },
                "disk": {
                    "hits": 994,
                    "misses": 197,
                    "total": 1191
                }
            },
            "cpu": {
                "user": "00:00:19.0468750",
                "kernel": "00:00:00.0156250",
                "total cpu": "00:00:19.0625000"
            },
            "memory": {
                "peak_per_node": 236822432
            }
        },
        "dataset_statistics": [
            {
                "table_row_count": 2,
                "table_size": 102
            }
        ]
    },
    "Schema": [
        {
            "Name": "Timestamp",
            "Type": "DateTime"
        },
        {
            "Name": "FileName",
            "Type": "String"
        },
        {
            "Name": "InitiatingProcessFileName",
            "Type": "String"
        }
    ],
    "Results": [
        {
            "Timestamp": "2020-08-30T06:38:35.7664356Z",
            "FileName": "conhost.exe",
            "InitiatingProcessFileName": "powershell.exe"
        },
        {
            "Timestamp": "2020-08-30T06:38:30.5163363Z",
            "FileName": "conhost.exe",
            "InitiatingProcessFileName": "powershell.exe"
        }
    ]
}