Microsoft Defender XDR Erweiterte Such-API

  • Artikel

Gilt für:

  • Microsoft Defender XDR

Warnung

Diese erweiterte Hunting-API ist eine ältere Version mit eingeschränkten Funktionen. Eine umfassendere Version der api für die erweiterte Suche ist bereits in der Microsoft Graph-Sicherheits-API verfügbar. Weitere Informationen finden Sie unter Erweiterte Suche mithilfe der Microsoft Graph-Sicherheits-API.

Wichtig

Einige Informationen beziehen sich auf Vorabversionen von Produkten, die vor der kommerziellen Veröffentlichung noch erheblich geändert werden können. Microsoft übernimmt mit diesen Informationen keinerlei Gewährleistung, sei sie ausdrücklich oder konkludent.

Die erweiterte Suche ist ein Tool zur Bedrohungssuche, das speziell konstruierte Abfragen verwendet, um die Ereignisdaten der letzten 30 Tage in Microsoft Defender XDR zu untersuchen. Sie können erweiterte Huntingabfragen verwenden, um ungewöhnliche Aktivitäten zu untersuchen, mögliche Bedrohungen zu erkennen und sogar auf Angriffe zu reagieren. Mit der API für die erweiterte Suche können Sie Ereignisdaten programmgesteuert abfragen.

Kontingente und Ressourcenzuordnung

Die folgenden Bedingungen beziehen sich auf alle Abfragen.

  1. Abfragen untersuchen und geben Daten der letzten 30 Tage zurück.
  2. Ergebnisse können bis zu 100.000 Zeilen zurückgeben.
  3. Sie können bis zu mindestens 45 Anrufe pro Minute und Mandant tätigen. Die Anzahl der Anrufe variiert je nach Mandant je nach Größe.
  4. Jedem Mandanten werden CPU-Ressourcen basierend auf der Mandantengröße zugeordnet. Abfragen werden blockiert, wenn der Mandant 100 % der zugeordneten Ressourcen bis nach dem nächsten 15-Minütigen Zyklus erreicht hat. Um blockierte Abfragen aufgrund von übermäßigem Verbrauch zu vermeiden, befolgen Sie die Anleitung unter Optimieren Ihrer Abfragen, um cpu-Kontingente zu vermeiden.
  5. Wenn eine einzelne Anforderung länger als drei Minuten ausgeführt wird, tritt ein Zeitüberschreitung auf und es wird ein Fehler zurückgegeben.
  6. Ein 429 HTTP-Antwortcode gibt an, dass Sie die zugeordneten CPU-Ressourcen erreicht haben, entweder anhand der Anzahl der gesendeten Anforderungen oder aufgrund der zugewiesenen Laufzeit. Lesen Sie den Antworttext, um den Grenzwert zu verstehen, den Sie erreicht haben.

Berechtigungen

Eine der folgenden Berechtigungen ist erforderlich, um die API für die erweiterte Suche aufzurufen. Weitere Informationen, einschließlich der Auswahl von Berechtigungen, finden Sie unter Zugreifen auf die Microsoft Defender XDR Protection-APIs.

Berechtigungstyp Berechtigung Anzeigename der Berechtigung
App AdvancedHunting.Read.All Ausführen erweiterter Abfragen
Delegiert (Geschäfts-, Schul- oder Unikonto) AdvancedHunting.Read Ausführen erweiterter Abfragen

Hinweis

Beim Abrufen eines Tokens mit Benutzeranmeldeinformationen:

  • Der Benutzer muss über die Rolle "Daten anzeigen" verfügen.
  • Der Benutzer muss basierend auf den Gerätegruppeneinstellungen Zugriff auf das Gerät haben.

HTTP-Anforderung

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

Anforderungsheader

Kopfzeile Wert
Authorization Bearer {token} Hinweis: erforderlich
Content-Type application/json

Anforderungstext

Geben Sie im Anforderungstext ein JSON-Objekt mit den folgenden Parametern an:

Parameter Typ Beschreibung
Abfrage Text Die auszuführende Abfrage. (erforderlich)

Antwort

Bei erfolgreicher Ausführung gibt die Methode , und ein QueryResponse-Objekt im Antworttext zurück200 OK.

Das Antwortobjekt enthält drei Eigenschaften der obersten Ebene:

  1. Statistiken: Ein Wörterbuch mit Abfrageleistungsstatistiken.
  2. Schema: Das Schema der Antwort, eine Liste von Name-Type Paaren für jede Spalte.
  3. Ergebnisse: Eine Liste mit erweiterten Huntingereignissen.

Beispiel

Im folgenden Beispiel sendet ein Benutzer die folgende Abfrage und empfängt ein API-Antwortobjekt, das , Schemaund ResultsenthältStats.

Abfrage

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

Antwortobjekt

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

Tipp

Möchten Sie mehr erfahren? Engage mit der Microsoft-Sicherheitscommunity in unserer Tech Community: Microsoft Defender XDR Tech Community.