Microsoft 365 API di ricerca avanzata defenderMicrosoft 365 Defender Advanced hunting API

Importante

Il nuovo Centro sicurezza Microsoft 365 è ora disponibile.The improved Microsoft 365 security center is now available. Questa nuova esperienza consente di accedere a Defender per endpoint, Defender per Office 365, Microsoft 365 Defender e altre soluzioni nel Centro sicurezza Microsoft 365.This new experience brings Defender for Endpoint, Defender for Office 365, Microsoft 365 Defender, and more into the Microsoft 365 security center. Informazioni sulle novità.Learn what's new.

Si applica a:Applies to:

  • Microsoft 365 DefenderMicrosoft 365 Defender

Importante

Alcune informazioni fanno riferimento alle caratteristiche del prodotto prima del rilascio, e possono essere modificate sostanzialmente prima della distribuzione al pubblico.Some information relates to prereleased product which may be substantially modified before it's commercially released. Microsoft non fornisce alcuna garanzia, esplicita o implicita, in relazione alle informazioni contenute in questo documento.Microsoft makes no warranties, express or implied, with respect to the information provided here.

La ricerca avanzata è uno strumento di ricerca delle minacce che usa query appositamente costruite per esaminare i dati degli ultimi 30 giorni dell'evento in Microsoft 365 Defender.Advanced hunting is a threat-hunting tool that uses specially constructed queries to examine the past 30 days of event data in Microsoft 365 Defender. È possibile utilizzare query di ricerca avanzate per esaminare attività insolite, rilevare possibili minacce e persino rispondere agli attacchi.You can use advanced hunting queries to inspect unusual activity, detect possible threats, and even respond to attacks. L'API di ricerca avanzata consente di eseguire query a livello di programmazione sui dati degli eventi.The advanced hunting API allows you to programatically query event data.

Quote e allocazione delle risorseQuotas and resource allocation

Le condizioni seguenti sono correlate a tutte le query.The following conditions relate to all queries.

  1. Le query esplorano e restituiscono dati degli ultimi 30 giorni.Queries explore and return data from the past 30 days.
  2. I risultati possono restituire fino a 100.000 righe.Results can return up to 100,000 rows.
  3. È possibile effettuare fino a 15 chiamate al minuto per tenant.You can make up to 15 calls per minute per tenant.
  4. Le query vengono bloccate se il tenant ha raggiunto il 100% fino al successivo ciclo di 15 minuti.Queries are blocked if the tenant has reached 100% until after the next 15-minute cycle.
  5. Se una singola richiesta viene eseguita per più di 10 minuti, si verifica il timeout e viene restituito un errore.If a single request runs for more than 10 minutes, it will time out and return an error.
  6. Un codice di risposta HTTP indica che hai raggiunto una quota, in base al numero di richieste inviate o al tempo 429 di esecuzione assegnato.A 429 HTTP response code indicates that you've reached a quota, either by number of requests sent, or by allotted running time. Leggere il corpo della risposta per comprendere il limite raggiunto.Read the response body to understand the limit you have reached.

Nota

Tutte le quote elencate sopra (ad esempio 15 chiamate al min) sono per dimensione del tenant.All quotas listed above (for example 15 calls per min) are per tenant size. Queste quote sono minime.These quotas are the minimum.

AutorizzazioniPermissions

Una delle autorizzazioni seguenti è necessaria per chiamare l'API di ricerca avanzata.One of the following permissions is required to call the advanced hunting API. Per altre informazioni, inclusa la scelta delle autorizzazioni, vedi Accedere alle API Microsoft 365 Defender ProtectionTo learn more, including how to choose permissions, see Access the Microsoft 365 Defender Protection APIs

Tipo di autorizzazionePermission type AutorizzazionePermission Nome visualizzato autorizzazionePermission display name
ApplicazioneApplication AdvancedHunting.Read.AllAdvancedHunting.Read.All Eseguire query avanzateRun advanced queries
Delegato (account aziendale o dell'istituto di istruzione)Delegated (work or school account) AdvancedHunting.ReadAdvancedHunting.Read Eseguire query avanzateRun advanced queries

Nota

Quando si ottiene un token utilizzando le credenziali utente:When obtaining a token using user credentials:

  • L'utente deve disporre del ruolo AD "Visualizza dati"The user needs to have the 'View Data' AD role
  • L'utente deve avere accesso al dispositivo, in base alle impostazioni del gruppo di dispositivi.The user needs to have access to the device, based on device group settings.

Richiesta HTTPHTTP request

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

Intestazioni di richiestaRequest headers

IntestazioneHeader ValoreValue
AutorizzazioneAuthorization Bearer {token} Nota: obbligatoriaBearer {token} Note: required
Content-TypeContent-Type application/jsonapplication/json

Corpo della richiestaRequest body

Nel corpo della richiesta, fornire un oggetto JSON con i parametri seguenti:In the request body, supply a JSON object with the following parameters:

ParametroParameter TipoType DescrizioneDescription
QueryQuery TestoText Query da eseguire.The query to run. Nota: obbligatorioNote: required

RispostaResponse

Se ha esito positivo, questo metodo restituirà 200 OK e un oggetto QueryResponse nel corpo della risposta.If successful, this method will return 200 OK, and a QueryResponse object in the response body.

L'oggetto response contiene tre proprietà di primo livello:The response object contains three top-level properties:

  1. Statistiche: dizionario di statistiche sulle prestazioni delle query.Stats - A dictionary of query performance statistics.
  2. Schema : schema della risposta, un elenco di coppie Name-Type per ogni colonna.Schema - The schema of the response, a list of Name-Type pairs for each column.
  3. Risultati : elenco di eventi di ricerca avanzati.Results - A list of advanced hunting events.

EsempioExample

Nell'esempio seguente, un utente invia la query seguente e riceve un oggetto risposta API contenente Stats Schema , e Results .In the following example, a user sends the query below and receives an API response object containing Stats, Schema, and Results.

QueryQuery

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

Oggetto ResponseResponse object

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