Microsoft 365 Defender API för avancerad sökning

Viktigt

Den förbättrade Microsoft 365 Defender-portalen är nu tillgänglig. Med den här nya upplevelsen kommer Defender för Endpoint, Defender för Office 365, 365 Microsoft 365 Defender och annat till Microsoft Defender for Cloud Apps. Läs om de senaste.

Gäller för:

  • Microsoft 365 Defender

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 sökning är ett verktyg för hot efter hot som använder specialkonstruktioner för att undersöka de senaste 30 dagarnas händelsedata i Microsoft 365 Defender. Du kan använda avancerade sökfrågor för att inspektera ovanlig aktivitet, identifiera möjliga hot och även svara på attacker. Med API:t för avancerad sökning kan du programmässigt fråga händelsedata.

Kvoter och resurstilldelning

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

  1. Frågor utforskar och returnerar data från de senaste 30 dagarna.
  2. Resultatet kan returnera upp till 100 000 rader.
  3. Du kan ringa upp till 45 samtal per minut per klientorganisation.
  4. Frågor blockeras om klientorganisationen har nått 100 % till efter den kommande 15-minuterscykeln.
  5. Om en enskild begäran körs i mer än 10 minuter time out och returnerar ett fel.
  6. En HTTP-svarskod anger att du har nått en kvot, antingen genom antal begäranden som skickas 429 eller med tilldelad löpande tid. Läs svarstexten för att förstå gränsen som du har nått.

Anteckning

Alla kvoter som anges ovan (till exempel 15 samtal per min) är per klientorganisationsstorlek. Dessa kvoter är de lägsta.

Behörigheter

En av följande behörigheter krävs för att anropa det avancerade API:t för sökning. Mer information, inklusive hur du väljer behörigheter, finns i Åtkomst API:Microsoft 365 Defender 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

Anteckning

När du skaffar en token med hjälp av användarautentiseringsuppgifter:

  • Användaren måste ha AD-rollen "Visa data"
  • Användaren måste ha åtkomst till enheten, baserat på enhetens gruppinställningar.

HTTP-begäran

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

Frågerubriker

Rubrik Värde
Auktorisering Bearer {token} Obs! obligatoriskt
Content-Type application/json

Frågebrödtext

Ange följande parametrar för ett JSON-objekt i begärans brödtext:

Parameter Typ Beskrivning
Fråga Text Frågan som ska köras. Obs! obligatoriskt

Svar

Om det lyckas returnerar den här 200 OK metoden och ett QueryResponse-objekt i svarets brödtext.

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

  1. Statistik – en ordlista med frågeprestandastatistik.
  2. Schema – Schemat för svaret, en lista med Name-Type par för varje kolumn.
  3. Resultat – En lista över avancerad sökning.

Exempel

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

Fråga

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

Response-objekt

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