Delen via


Microsoft Defender XDR Geavanceerde opsporings-API

Van toepassing op:

  • Microsoft Defender XDR

Waarschuwing

Deze geavanceerde opsporings-API is een oudere versie met beperkte mogelijkheden. Er is al een uitgebreidere versie van de geavanceerde opsporings-API beschikbaar in de Microsoft Graph-beveiligings-API. Zie Geavanceerde opsporing met microsoft Graph-beveiligings-API

Belangrijk

Sommige informatie is gerelateerd aan voorlopige productversies die mogelijk aanzienlijk gewijzigd worden voordat ze commercieel gepubliceerd worden. Microsoft geeft geen garantie, uitdrukkelijk of impliciet, met betrekking tot de informatie die hier wordt beschreven.

Geavanceerde opsporing is een hulpprogramma voor het opsporen van bedreigingen dat gebruikmaakt van speciaal samengestelde query's om de afgelopen 30 dagen aan gebeurtenisgegevens in Microsoft Defender XDR te onderzoeken. U kunt geavanceerde opsporingsquery's gebruiken om ongebruikelijke activiteiten te inspecteren, mogelijke bedreigingen te detecteren en zelfs te reageren op aanvallen. Met de geavanceerde opsporings-API kunt u programmatisch query's uitvoeren op gebeurtenisgegevens.

Quota en resourcetoewijzing

De volgende voorwaarden hebben betrekking op alle query's.

  1. Met query's worden gegevens van de afgelopen 30 dagen verkend en geretourneerd.
  2. Resultaten kunnen maximaal 100.000 rijen retourneren.
  3. U kunt maximaal 45 aanroepen per minuut per tenant uitvoeren. Het aantal aanroepen verschilt per tenant, afhankelijk van de grootte.
  4. Aan elke tenant worden CPU-resources toegewezen op basis van de tenantgrootte. Query's worden geblokkeerd als de tenant 100% van de toegewezen resources heeft bereikt tot na de volgende cyclus van 15 minuten. Als u geblokkeerde query's wilt voorkomen vanwege overmatig verbruik, volgt u de richtlijnen in Uw query's optimaliseren om te voorkomen dat CPU-quota worden bereikt.
  5. Als één aanvraag langer dan drie minuten wordt uitgevoerd, treedt er een time-out op en wordt er een fout geretourneerd.
  6. Een 429 HTTP-antwoordcode geeft aan dat u de toegewezen CPU-resources hebt bereikt, op basis van het aantal verzonden aanvragen of door de toegewezen gebruikstijd. Lees de hoofdtekst van het antwoord om de limiet te begrijpen die u hebt bereikt.

Machtigingen

Een van de volgende machtigingen is vereist om de geavanceerde opsporings-API aan te roepen. Zie Toegang tot de Microsoft Defender XDR Protection-API's voor meer informatie, waaronder het kiezen van machtigingen.

Machtigingstype Machtiging Weergavenaam van machtiging
Toepassing AdvancedHunting.Read.All Geavanceerde query's uitvoeren
Gedelegeerd (werk- of schoolaccount) AdvancedHunting.Read Geavanceerde query's uitvoeren

Opmerking

Bij het verkrijgen van een token met behulp van gebruikersreferenties:

  • De gebruiker moet de rol Gegevens weergeven hebben.
  • De gebruiker moet toegang hebben tot het apparaat op basis van de instellingen van de apparaatgroep.

HTTP-aanvraag

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

Aanvraagheaders

Header Waarde
Vergunning Bearer {token} Opmerking: vereist
Content-Type application/json

Aanvraagtekst

Geef in de aanvraagtekst een JSON-object op met de volgende parameters:

Parameter Type Omschrijving
Query Tekst De query die moet worden uitgevoerd. (vereist)

Antwoord

Als dit lukt, retourneert 200 OKdeze methode en een QueryResponse-object in de antwoordtekst.

Het antwoordobject bevat drie eigenschappen op het hoogste niveau:

  1. Statistieken: een woordenlijst met statistieken over queryprestaties.
  2. Schema: het schema van het antwoord, een lijst met Name-Type paren voor elke kolom.
  3. Resultaten: een lijst met geavanceerde opsporingsgebeurtenissen.

Voorbeeld

In het volgende voorbeeld verzendt een gebruiker de onderstaande query en ontvangt een API-antwoordobject met Stats, Schemaen Results.

Query

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

Antwoordobject

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

Tip

Wil je meer weten? Engage met de Microsoft Security-community in onze Tech Community: Microsoft Defender XDR Tech Community.