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.
- Frågor utforskar och returnerar data från de senaste 30 dagarna.
- Resultatet kan returnera upp till 100 000 rader.
- Du kan ringa upp till 45 samtal per minut per klientorganisation.
- Frågor blockeras om klientorganisationen har nått 100 % till efter den kommande 15-minuterscykeln.
- Om en enskild begäran körs i mer än 10 minuter time out och returnerar ett fel.
- En HTTP-svarskod anger att du har nått en kvot, antingen genom antal begäranden som skickas
429eller 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:
- Statistik – en ordlista med frågeprestandastatistik.
- Schema – Schemat för svaret, en lista med Name-Type par för varje kolumn.
- 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"
}
]
}