segurança: runHuntingQuery

Namespace: microsoft.graph.security

Consulta um conjunto especificado de dados de eventos, atividades ou entidades com suporte do Microsoft 365 Defender para procurar proativamente ameaças específicas em seu ambiente.

Esse método é para busca avançada no Microsoft 365 Defender. Esse método inclui uma consulta na Linguagem de Consulta Kusto (KQL). Ele especifica uma tabela de dados no esquema de busca avançada e uma sequência canalizada de operadores para filtrar ou pesquisar esses dados e formatar a saída da consulta de maneiras específicas.

Saiba mais sobre como buscar ameaças em dispositivos, emails, aplicativos e identidades. Saiba mais sobre KQL.

Para obter informações sobre como usar a busca avançada no portal do Microsoft 365 Defender, consulte Buscar proativamente ameaças com a busca avançada no Microsoft 365 Defender.

Essa API está disponível nas seguintes implantações de nuvem nacional.

Serviço global	Governo dos EUA L4	US Government L5 (DOD)	China operada pela 21Vianet
✅	✅	✅	❌

Permissões

Escolha a(s) permissão(s) marcada(s) como menos privilegiada(s) para essa API. Use uma permissão ou permissões com privilégios mais altos somente se o aplicativo exigir. Para obter detalhes sobre permissões delegadas e de aplicativo, consulte Tipos de permissão. Para saber mais sobre essas permissões, consulte a referência de permissões.

Tipo de permissão	Permissões menos privilegiadas	Permissões com privilégios mais elevados
Delegado (conta corporativa ou de estudante)	ThreatHunting.Read.All	Indisponível.
Delegado (conta pessoal da Microsoft)	Sem suporte.	Sem suporte.
Application	ThreatHunting.Read.All	Indisponível.

Solicitação HTTP

POST /security/runHuntingQuery

Cabeçalhos de solicitação

Nome	Descrição
Autorização	{token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.
Content-Type	application/json. Obrigatório.

Observação

Se você estiver usando caracteres não ANSI em sua consulta, por exemplo, para consultar assuntos de email com caracteres malformados ou semelhantes, use application/json; charset=utf-8 para o cabeçalho Content-Type.

Corpo da solicitação

No corpo da solicitação, forneça um objeto JSON com a Query propriedade e, opcionalmente, inclua as Timespan propriedades and workspaceId .

Parâmetro	Tipo	Descrição	Exemplo
Consultar	Cadeia de caracteres	Obrigatório. A consulta de busca na Linguagem de Consulta Kusto (KQL). Para obter mais informações, consulte a referência rápida de KQL.
Intervalo de tempo	String	Opcional. O intervalo de tempo sobre o qual consultar dados, no formato ISO 8601. O valor padrão é de 30 dias, ou seja, se nenhum startTime for especificado, a consulta retrocederá daqui a 30 dias. Se um filtro de tempo for especificado na consulta e no parâmetro startTime, o intervalo de tempo mais curto será aplicado. Por exemplo, se a consulta tiver um filtro para os últimos sete dias e o startTime for de 10 dias atrás, a consulta olhará apenas para trás sete dias.
workspaceId	Guid	Opcional. O GUID de um workspace específico do Log Analytics a ser direcionado. Se omitido, o serviço usará o espaço de trabalho principal do chamador. Se o espaço de trabalho não for encontrado ou não estiver acessível, o serviço retornará ao espaço de trabalho principal do chamador.	`00000000-0000-0000-0000-000000000001`

Os exemplos a seguir mostram os formatos possíveis para o Timespan parâmetro:

Data/Data: "2024-02-01T08:00:00Z/2024-02-15T08:00:00Z" – Datas de início e término.
Duration/endDate: "P30D/2024-02-15T08:00:00Z" - Um período antes da data de término.
Início/duração: "2024-02-01T08:00:00Z/P30D" - Data de início e duração.
ISO8601 duração: "P30D" - Duração de agora para trás.
Data/hora única: "2024-02-01T08:00:00Z" - Hora de início com hora de término padronizada para a hora atual.

Resposta

Se for bem-sucedida, essa ação retornará um código de 200 OK resposta e um huntingQueryResults no corpo da resposta.

Exemplos

Exemplo 1: Consulta com intervalo de tempo padrão

Solicitação

O exemplo a seguir especifica uma consulta KQL e faz o seguinte:

Examina a tabela DeviceProcessEvents no esquema de busca avançada.
Filtros com a condição de que o processo powershell.exe inicie o evento.
Especifica a saída de três colunas da mesma tabela para cada linha: Timestamp, FileName, InitiatingProcessFileName.
Classifica a saída pelo Timestamp valor.
Limita a saída a dois registros (duas linhas).

POST https://graph.microsoft.com/v1.0/security/runHuntingQuery

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


// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Security.MicrosoftGraphSecurityRunHuntingQuery;

var requestBody = new RunHuntingQueryPostRequestBody
{
	Query = "DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2",
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Security.MicrosoftGraphSecurityRunHuntingQuery.PostAsync(requestBody);



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphsecurity "github.com/microsoftgraph/msgraph-sdk-go/security"
	  //other-imports
)

requestBody := graphsecurity.NewRunHuntingQueryPostRequestBody()
query := "DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2"
requestBody.SetQuery(&query) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
microsoftGraphSecurityRunHuntingQuery, err := graphClient.Security().MicrosoftGraphSecurityRunHuntingQuery().Post(context.Background(), requestBody, nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

com.microsoft.graph.security.microsoftgraphsecurityrunhuntingquery.RunHuntingQueryPostRequestBody runHuntingQueryPostRequestBody = new com.microsoft.graph.security.microsoftgraphsecurityrunhuntingquery.RunHuntingQueryPostRequestBody();
runHuntingQueryPostRequestBody.setQuery("DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2");
var result = graphClient.security().microsoftGraphSecurityRunHuntingQuery().post(runHuntingQueryPostRequestBody);


const options = {
	authProvider,
};

const client = Client.init(options);

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

await client.api('/security/runHuntingQuery')
	.post(huntingQueryResults);


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Security\MicrosoftGraphSecurityRunHuntingQuery\RunHuntingQueryPostRequestBody;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new RunHuntingQueryPostRequestBody();
$requestBody->setQuery('DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2');

$result = $graphServiceClient->security()->microsoftGraphSecurityRunHuntingQuery()->post($requestBody)->wait();


Import-Module Microsoft.Graph.Security

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

Start-MgSecurityHuntingQuery -BodyParameter $params


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.security.microsoft_graph_security_run_hunting_query.run_hunting_query_post_request_body import RunHuntingQueryPostRequestBody
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = RunHuntingQueryPostRequestBody(
	query = "DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2",
)

result = await graph_client.security.microsoft_graph_security_run_hunting_query.post(request_body)

Resposta

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.security.huntingQueryResults",
    "schema": [
        {
            "name": "Timestamp",
            "type": "DateTime"
        },
        {
            "name": "FileName",
            "type": "String"
        },
        {
            "name": "InitiatingProcessFileName",
            "type": "String"
        }
    ],
    "results": [
        {
            "Timestamp": "2024-03-26T09:39:50.7688641Z",
            "FileName": "cmd.exe",
            "InitiatingProcessFileName": "powershell.exe"
        },
        {
            "Timestamp": "2024-03-26T09:39:49.4353788Z",
            "FileName": "cmd.exe",
            "InitiatingProcessFileName": "powershell.exe"
        }
    ]
}

Exemplo 2: Consulta com opcional o parâmetro timespan especificado

Solicitação

Este exemplo especifica uma consulta KQL e examina a tabela deviceProcessEvents no esquema de busca avançada 60 dias atrás.

POST https://graph.microsoft.com/v1.0/security/runHuntingQuery

{
    "Query": "DeviceProcessEvents",
    "Timespan": "P90D"
}


// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Security.MicrosoftGraphSecurityRunHuntingQuery;

var requestBody = new RunHuntingQueryPostRequestBody
{
	Query = "DeviceProcessEvents",
	Timespan = "P90D",
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Security.MicrosoftGraphSecurityRunHuntingQuery.PostAsync(requestBody);



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphsecurity "github.com/microsoftgraph/msgraph-sdk-go/security"
	  //other-imports
)

requestBody := graphsecurity.NewRunHuntingQueryPostRequestBody()
query := "DeviceProcessEvents"
requestBody.SetQuery(&query) 
timespan := "P90D"
requestBody.SetTimespan(&timespan) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
microsoftGraphSecurityRunHuntingQuery, err := graphClient.Security().MicrosoftGraphSecurityRunHuntingQuery().Post(context.Background(), requestBody, nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

com.microsoft.graph.security.microsoftgraphsecurityrunhuntingquery.RunHuntingQueryPostRequestBody runHuntingQueryPostRequestBody = new com.microsoft.graph.security.microsoftgraphsecurityrunhuntingquery.RunHuntingQueryPostRequestBody();
runHuntingQueryPostRequestBody.setQuery("DeviceProcessEvents");
runHuntingQueryPostRequestBody.setTimespan("P90D");
var result = graphClient.security().microsoftGraphSecurityRunHuntingQuery().post(runHuntingQueryPostRequestBody);


const options = {
	authProvider,
};

const client = Client.init(options);

const huntingQueryResults = {
    Query: 'DeviceProcessEvents',
    Timespan: 'P90D'
};

await client.api('/security/runHuntingQuery')
	.post(huntingQueryResults);


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Security\MicrosoftGraphSecurityRunHuntingQuery\RunHuntingQueryPostRequestBody;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new RunHuntingQueryPostRequestBody();
$requestBody->setQuery('DeviceProcessEvents');
$requestBody->setTimespan('P90D');

$result = $graphServiceClient->security()->microsoftGraphSecurityRunHuntingQuery()->post($requestBody)->wait();


Import-Module Microsoft.Graph.Security

$params = @{
	Query = "DeviceProcessEvents"
	Timespan = "P90D"
}

Start-MgSecurityHuntingQuery -BodyParameter $params


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.security.microsoft_graph_security_run_hunting_query.run_hunting_query_post_request_body import RunHuntingQueryPostRequestBody
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = RunHuntingQueryPostRequestBody(
	query = "DeviceProcessEvents",
	timespan = "P90D",
)

result = await graph_client.security.microsoft_graph_security_run_hunting_query.post(request_body)

Resposta

HTTP/1.1 200 OK
Content-type: application/json

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

Comentários

Esta página foi útil?

Last updated on 2026-08-20

segurança: runHuntingQuery

Permissões

Solicitação HTTP

Cabeçalhos de solicitação

Corpo da solicitação

Resposta

Exemplos

Exemplo 1: Consulta com intervalo de tempo padrão

Solicitação

Resposta

Exemplo 2: Consulta com opcional o parâmetro timespan especificado

Solicitação

Resposta

Comentários

Recursos adicionais