Avanceret jagt på trusler-API

  • Artikel

Gælder for:

Advarsel

Denne avancerede jagt-API er en ældre version med begrænsede funktioner. Der findes allerede en mere omfattende version af api'en til avanceret jagt, der kan forespørge flere tabeller i Microsoft Graph-sikkerheds-API'en. Se Avanceret jagt ved hjælp af Microsoft Graph Security API

Vil du opleve Microsoft Defender for Endpoint? Tilmeld dig en gratis prøveversion.

Bemærk!

Hvis du er us government-kunde, skal du bruge de URI'er, der er angivet i Microsoft Defender for Endpoint for us Government-kunder.

Tip

For at opnå en bedre ydeevne kan du bruge serveren tættere på din geografiske placering:

  • 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

Begrænsninger

  1. Du kan kun køre en forespørgsel på data fra de seneste 30 dage.

  2. Resultaterne omfatter højst 100.000 rækker.

  3. Antallet af udførelser er begrænset pr. lejer:

    • API-kald: Op til 45 opkald pr. minut og op til 1.500 opkald pr. time.
    • Udførelsestid: 10 minutters kørselstid hver time og 3 timers kørsel om dagen.

  4. Den maksimale udførelsestid for en enkelt anmodning er 200 sekunder.

  5. 429 response repræsenterer at nå kvotegrænsen enten efter antal anmodninger eller efter CPU. Læs brødteksten i svaret for at forstå, hvilken grænse der blev nået.

  6. Den maksimale størrelse på forespørgselsresultatet for en enkelt anmodning må ikke overstige 124 MB. Hvis den overskrides, har en forkert HTTP 400-anmodning med meddelelsen "Udførelse af forespørgsel overskredet den tilladte resultatstørrelse. Optimer din forespørgsel ved at begrænse antallet af resultater, og prøv igen" opstår.

Tilladelser

En af følgende tilladelser er påkrævet for at kalde denne API. Du kan få mere at vide, herunder hvordan du vælger tilladelser, under Brug Microsoft Defender for Endpoint API'er

Tilladelsestype Tilladelse Vist navn for tilladelse
Program AdvancedQuery.Read.All Run advanced queries
Uddelegeret (arbejds- eller skolekonto) AdvancedQuery.Read Run advanced queries

Bemærk!

Når du henter et token ved hjælp af brugerlegitimationsoplysninger:

  • Brugeren skal have tildelt rollen View Data i Microsoft Entra ID
  • Brugeren skal have adgang til enheden baseret på indstillinger for enhedsgrupper (se Create og administrer enhedsgrupper for at få flere oplysninger)

Oprettelse af enhedsgruppe understøttes i Defender for Endpoint Plan 1 og Plan 2.

HTTP-anmodning

POST https://api.securitycenter.microsoft.com/api/advancedqueries/run

Anmodningsheadere

Sidehoved Værdi
Tilladelse Ihændehaver {token}. Påkrævet.
Indholdstype program/json

Brødtekst i anmodning

Angiv følgende parametre for et JSON-objekt i anmodningens brødtekst:

Parameter Type Beskrivelse
Forespørgsel Tekst Den forespørgsel, der skal køres. Påkrævet.

Svar

Hvis det lykkes, returnerer denne metode objektet 200 OK og QueryResponse i svarbrødteksten.

Eksempel

Eksempel på anmodning

Her er et eksempel på anmodningen.

POST https://api.securitycenter.microsoft.com/api/advancedqueries/run

{
    "Query":"DeviceProcessEvents
|where InitiatingProcessFileName =~ 'powershell.exe'
|where ProcessCommandLine contains 'appdata'
|project Timestamp, FileName, InitiatingProcessFileName, DeviceId
|limit 2"
}

Svareksempel

Her er et eksempel på svaret.

Bemærk!

Det svarobjekt, der vises her, kan afkortes af hensyn til en korthed. Alle egenskaberne returneres fra et faktisk opkald.

{
    "Schema": [
        {
            "Name": "Timestamp",
            "Type": "DateTime"
        },
        {
            "Name": "FileName",
            "Type": "String"
        },
        {
            "Name": "InitiatingProcessFileName",
            "Type": "String"
        },
        {
            "Name": "DeviceId",
            "Type": "String"
        }
    ],
    "Results": [
        {
            "Timestamp": "2020-02-05T01:10:26.2648757Z",
            "FileName": "csc.exe",
            "InitiatingProcessFileName": "powershell.exe",
            "DeviceId": "10cbf9182d4e95660362f65cfa67c7731f62fdb3"
        },
        {
            "Timestamp": "2020-02-05T01:10:26.5614772Z",
            "FileName": "csc.exe",
            "InitiatingProcessFileName": "powershell.exe",
            "DeviceId": "10cbf9182d4e95660362f65cfa67c7731f62fdb3"
        }
    ]
}

Tip

Vil du vide mere? Engage med Microsoft Security-community'et i vores tech-community: Microsoft Defender for Endpoint Tech Community.