MICROSOFT DEFENDER XDR API di ricerca avanzata

  • Articolo

Si applica a:

  • Microsoft Defender XDR

Avviso

Questa API di ricerca avanzata è una versione precedente con funzionalità limitate. Una versione più completa dell'API di ricerca avanzata è già disponibile nell'API di sicurezza di Microsoft Graph. Vedere Ricerca avanzata con l'API di sicurezza di 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.

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 XDR. È 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, inclusa la scelta delle autorizzazioni, vedere Accedere alle API di protezione Microsoft Defender XDR.

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ù, Engage con la community Microsoft Security nella community tech: Microsoft Defender XDR Tech Community.