MICROSOFT 365 DEFENDER API di ricerca avanzata

  • Articolo
  • 3 minuti per la lettura

Nota

Vuoi provare Microsoft 365 Defender? Altre informazioni su come valutare e pilotare Microsoft 365 Defender.

Si applica a:

  • Microsoft 365 Defender

Nota

Provare le nuove API usando l'API di sicurezza di MS Graph. Per altre informazioni, vedere: Usare l'API di sicurezza di Microsoft Graph - Microsoft Graph | Microsoft Learn.

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 365 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 fino a 45 chiamate al minuto per ogni tenant.
  4. Le query vengono bloccate se il tenant ha raggiunto il 100% dopo il ciclo di 15 minuti successivo.
  5. Se una singola richiesta viene eseguita per più di 10 minuti, il timeout verrà generato e verrà restituito un errore.
  6. Un 429 codice di risposta HTTP indica che è stata raggiunta una quota, in base al numero di richieste inviate o al tempo di esecuzione assegnato. Leggere il corpo della risposta per comprendere il limite raggiunto.

Nota

Tutte le quote elencate in precedenza (ad esempio 15 chiamate al minuto) sono a livello di tenant. Queste quote sono il minimo.

Autorizzazioni

Per chiamare l'API di ricerca avanzata, è necessaria una delle autorizzazioni seguenti. Per altre informazioni, incluso come scegliere le autorizzazioni, vedere Accedere alle API di protezione Microsoft 365 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"
        }
    ]
}