API for Microsoft 365 Defender avansert jakt

  • Artikkel

Obs!

Vil du prøve Microsoft 365 Defender? Finn ut mer om hvordan du kan evaluere og prøve ut Microsoft 365 Defender.

Gjelder for:

  • Microsoft 365 Defender

Advarsel

Denne avanserte jakt-API-en er en eldre versjon med begrensede funksjoner. En mer omfattende versjon av API-en for avansert jakt er allerede tilgjengelig i Microsoft Graph-sikkerhets-API-en. Se Avansert jakt ved hjelp av Microsoft Graph Security API

Viktig

Noe informasjon er knyttet til forhåndsutgitt produkt som kan endres vesentlig før det utgis kommersielt. Microsoft gir ingen garantier, uttrykkelige eller underforståtte, med hensyn til informasjonen som er oppgitt her.

Avansert jakt er et trusseljaktverktøy som bruker spesialkonstruerte spørringer til å undersøke de siste 30 dagene med hendelsesdata i Microsoft 365 Defender. Du kan bruke avanserte jaktspørringer til å undersøke uvanlig aktivitet, oppdage mulige trusler og til og med svare på angrep. Med API-en for avansert jakt kan du programmatisk spørre etter hendelsesdata.

Kvoter og ressursallokering

Følgende betingelser er knyttet til alle spørringer.

  1. Spørringer utforsker og returnerer data fra de siste 30 dagene.
  2. Resultater kan returnere opptil 100 000 rader.
  3. Du kan foreta opptil minst 45 anrop per minutt per leier. Antall anrop varierer per leier basert på størrelsen.
  4. Hver leier er tildelt CPU-ressurser, basert på leierstørrelsen. Spørringer blokkeres hvis leieren har nådd 100 % av de tildelte ressursene til etter neste 15-minutters syklus. Hvis du vil unngå blokkerte spørringer på grunn av overflødig forbruk, følger du veiledningen i Optimaliser spørringene for å unngå å treffe CPU-kvoter.
  5. Hvis én enkelt forespørsel kjøres i mer enn tre minutter, blir den tidsavbrutt og returnerer en feil.
  6. En 429 HTTP-svarkode indikerer at du har nådd de tildelte CPU-ressursene, enten etter antall sendte forespørsler eller av tildelt kjøretid. Les svarteksten for å forstå grensen du har nådd.

Tillatelser

Én av følgende tillatelser er nødvendig for å kalle opp API-en for avansert jakt. Hvis du vil ha mer informasjon, inkludert hvordan du velger tillatelser, kan du se Access Microsoft 365 Defender Protection API-er.

Tillatelsestype Tillatelse Visningsnavn for tillatelse
Program AdvancedHunting.Read.All Kjør avanserte spørringer
Delegert (jobb- eller skolekonto) AdvancedHunting.Read Kjør avanserte spørringer

Obs!

Når du skaffer et token ved hjelp av brukerlegitimasjon:

  • Brukeren må ha rollen Vis data.
  • Brukeren må ha tilgang til enheten, basert på innstillingene for enhetsgruppen.

HTTP-forespørsel

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

Forespørselshoder

Topptekst Verdi
Authorization Bærer {token} Obs! obligatorisk
Innholdstype program/json

Forespørselstekst

Angi et JSON-objekt med følgende parametere i forespørselsteksten:

Parameteren Type: Beskrivelse
Spørring Tekst Spørringen som skal kjøres. (obligatorisk)

Svar

Hvis vellykket, returnerer 200 OKdenne metoden , og et QueryResponse-objekt i svarteksten.

Svarobjektet inneholder tre egenskaper på øverste nivå:

  1. Statistikk – en ordliste med statistikk for spørringsytelse.
  2. Skjema – skjemaet for svaret, en liste over Name-Type par for hver kolonne.
  3. Resultater - En liste over avanserte jakthendelser.

Eksempel

I eksemplet nedenfor sender en bruker spørringen nedenfor og mottar et API-svarobjekt som inneholder Stats, Schemaog Results.

Spørring

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

Svarobjekt

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

Vil du lære mer? Kommunmuner deg med Microsoft Security-fellesskapet i det tekniske fellesskapet vårt: Microsoft 365 Defender teknisk fellesskap.