Microsoft Defender XDR Avancerat jakt-API

  • Artikel

Gäller för:

  • Microsoft Defender XDR

Varning

Det här avancerade jakt-API:et är en äldre version med begränsade funktioner. En mer omfattande version av api:et för avancerad jakt finns redan i Säkerhets-API:et för Microsoft Graph. Se Avancerad jakt med Microsoft Graph-säkerhets-API

Viktigt

En del information gäller förinstallerad produkt som kan ha ändrats mycket innan den släpps kommersiellt. Microsoft lämnar inga garantier, uttryckliga eller underförstådda, med avseende på den information som anges här.

Avancerad jakt är ett verktyg för hotjakt som använder särskilt konstruerade frågor för att undersöka de senaste 30 dagarnas händelsedata i Microsoft Defender XDR. Du kan använda avancerade jaktfrågor för att inspektera ovanlig aktivitet, identifiera möjliga hot och till och med svara på attacker. Med api:et för avancerad jakt kan du programmatiskt fråga efter händelsedata.

Kvoter och resursallokering

Följande villkor gäller för alla frågor.

  1. Frågor utforskar och returnerar data från de senaste 30 dagarna.
  2. Resultaten kan returnera upp till 100 000 rader.
  3. Du kan göra upp till minst 45 anrop per minut per klientorganisation. Antalet anrop varierar per klientorganisation baserat på dess storlek.
  4. Varje klientorganisation tilldelas CPU-resurser baserat på klientorganisationens storlek. Frågor blockeras om klientorganisationen har nått 100 % av de allokerade resurserna till efter nästa 15-minuterscykel. Om du vill undvika blockerade frågor på grund av överförbrukning följer du anvisningarna i Optimera dina frågor för att undvika att uppnå CPU-kvoter.
  5. Om en enskild begäran körs i mer än tre minuter överskrider den tidsgränsen och returnerar ett fel.
  6. En 429 HTTP-svarskod anger att du har nått de allokerade CPU-resurserna, antingen efter antal skickade begäranden eller efter tilldelad körningstid. Läs svarstexten för att förstå den gräns som du har nått.

Behörigheter

En av följande behörigheter krävs för att anropa API:et för avancerad jakt. Mer information, inklusive hur du väljer behörigheter, finns i Åtkomst till Microsoft Defender XDR Protection-API:er.

Behörighetstyp Behörighet Visningsnamn för behörighet
Program AdvancedHunting.Read.All Köra avancerade frågor
Delegerat (arbets- eller skolkonto) AdvancedHunting.Read Köra avancerade frågor

Obs!

När du hämtar en token med användarautentiseringsuppgifter:

  • Användaren måste ha rollen Visa data.
  • Användaren måste ha åtkomst till enheten baserat på enhetsgruppsinställningarna.

HTTP-begäran

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

Frågerubriker

Rubrik Värde
Tillstånd Ägaren {token} Obs! Krävs
Content-Type application/json

Frågebrödtext

I begärandetexten anger du ett JSON-objekt med följande parametrar:

Parameter Typ Beskrivning
Fråga Text Frågan som ska köras. (krävs)

Svar

Om det lyckas returnerar 200 OKden här metoden och ett QueryResponse-objekt i svarstexten.

Svarsobjektet innehåller tre egenskaper på den översta nivån:

  1. Statistik – en ordlista med frågeprestandastatistik.
  2. Schema – schemat för svaret, en lista över Name-Type par för varje kolumn.
  3. Resultat – En lista över avancerade jakthändelser.

Exempel

I följande exempel skickar en användare frågan nedan och tar emot ett API-svarsobjekt som innehåller Stats, Schemaoch Results.

Fråga

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

Svarsobjekt

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

Tips

Vill du veta mer? Engage med Microsofts säkerhetscommunity i vår Tech Community: Microsoft Defender XDR Tech Community.