MICROSOFT DEFENDER XDR API di ricerca avanzata

  • Si applica a: Microsoft Defender XDR

Avviso

Questa API di ricerca avanzata è una versione precedente con funzionalità limitate. Una versione più completa dell'API avanzata di caccia è disponibile nell'API di sicurezza Microsoft Graph. Per altre informazioni, vedere Ricerca avanzata con Microsoft Graph API di sicurezza.

L'API avanzata di caccia Microsoft Defender XDR sta passando all'API di sicurezza Microsoft Graph, che offre una copertura dati più ampia, maggiore coerenza e una scalabilità migliore per i flussi di lavoro di automazione e sicurezza. Il ritiro è iniziato nel gennaio 2026. Dopo il completamento del ritiro, l'API avanzata di caccia Microsoft Defender XDR non funziona più. Per la sequenza temporale del ritiro, vedere MC1220762. Per indicazioni sulla migrazione, vedi Usa l'API di sicurezza Microsoft Graph.

Importante

Alcune informazioni fanno riferimento alle caratteristiche del prodotto prima del rilascio, e possono essere modificate sostanzialmente prima della distribuzione al pubblico. Microsoft non fornisce alcuna garanzia, esplicita o implicita, in relazione alle informazioni contenute in questo documento.

La ricerca avanzata è uno strumento di ricerca delle minacce che usa query appositamente costruite per esaminare gli ultimi 30 giorni di dati degli eventi in Microsoft Defender. È possibile usare query di ricerca avanzate per ispezionare attività insolite, rilevare possibili minacce e persino rispondere agli attacchi. L'API di ricerca avanzata consente di eseguire query sui dati degli eventi a livello di codice.

Quote e allocazione delle risorse

Le condizioni seguenti sono correlate a tutte le query.

  1. Le query esplorano e restituiscono dati degli ultimi 30 giorni.
  2. I risultati possono restituire fino a 100.000 righe.
  3. È possibile effettuare almeno 45 chiamate al minuto per ogni tenant. Il numero di chiamate varia per tenant in base alle dimensioni.
  4. A ogni tenant vengono allocate risorse CPU, in base alle dimensioni del tenant. Le query vengono bloccate se il tenant ha raggiunto il 100% delle risorse allocate fino al successivo ciclo di 15 minuti. Per evitare query bloccate a causa di un consumo eccessivo, seguire le indicazioni in Ottimizzare le query per evitare di raggiungere le quote della CPU.
  5. Se una singola richiesta viene eseguita per più di tre minuti, il timeout e restituisce un errore.
  6. Un 429 codice di risposta HTTP indica che sono state raggiunta le risorse CPU allocate, in base al numero di richieste inviate o al tempo di esecuzione assegnato. Leggere il corpo della risposta per comprendere il limite raggiunto.

Autorizzazioni

Per chiamare l'API di ricerca avanzata, è necessaria una delle autorizzazioni seguenti. Per altre informazioni, tra cui come scegliere le autorizzazioni, vedere Accedere alle API di protezione Microsoft Defender.

Tipo di autorizzazione Autorizzazione Nome visualizzato autorizzazioni
Applicazione AdvancedHunting.Read.All Eseguire query avanzate
Delegato (account aziendale o dell'istituto di istruzione) AdvancedHunting.Read Eseguire query avanzate

Nota

Quando si ottiene un token usando le credenziali utente:

  • L'utente deve avere il ruolo "Visualizza dati".
  • L'utente deve avere accesso al dispositivo, in base alle impostazioni del gruppo di dispositivi.

Richiesta HTTP

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

Intestazioni della richiesta

Intestazione Valore
Autorizzazione Bearer {token} Nota: obbligatorio
Content-Type application/json

Corpo della richiesta

Nel corpo della richiesta specificare un oggetto JSON con i parametri seguenti:

Parametro Tipo Descrizione
Query Testo Query da eseguire. (obbligatorio)

Risposta

In caso di esito positivo, questo metodo restituirà 200 OKe un oggetto QueryResponse nel corpo della risposta.

L'oggetto risposta contiene tre proprietà di primo livello:

  1. Statistiche: dizionario di statistiche sulle prestazioni delle query.
  2. Schema: schema della risposta, un elenco di coppie di Name-Type per ogni colonna.
  3. Risultati: elenco di eventi di ricerca avanzati.

Esempio

Nell'esempio seguente un utente invia la query seguente e riceve un oggetto risposta API contenente Stats, Schemae Results.

Query

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

Oggetto Response

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

Consiglio

Per saperne di più, Visitare la community di Microsoft Security nella Tech Community: Tech Community di Microsoft Defender XDR.

  • Last updated on