Espaço de nomes: microsoft.graph.security
Importante
As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.
Consulte um conjunto especificado de dados de eventos, atividades ou entidades suportados pelo Microsoft 365 Defender para procurar proativamente ameaças específicas no seu ambiente.
Este método destina-se à investigação avançada no Microsoft 365 Defender. Este método inclui uma consulta no Linguagem de Consulta Kusto (KQL). Especifica uma tabela de dados no esquema de investigação avançado e uma sequência canalizada de operadores para filtrar ou pesquisar esses dados e formatar a saída da consulta de formas específicas.
Saiba mais sobre a procura de ameaças entre dispositivos, e-mails, aplicações e identidades. Saiba mais sobre o KQL.
Para obter informações sobre como utilizar a investigação avançada no portal do Microsoft 365 Defender, consulte Proativamente investigar ameaças com investigação avançada no Microsoft 365 Defender.
Esta API está disponível nas seguintes implementações de cloud nacionais.
| Serviço global |
US Government L4 |
US Government L5 (DOD) |
China operada pela 21Vianet |
| ✅ |
✅ |
✅ |
❌ |
Permissões
Escolha a permissão ou permissões marcadas como menos privilegiadas para esta API. Utilize uma permissão ou permissões com privilégios mais elevados apenas se a sua aplicação o exigir. Para obter detalhes sobre as permissões delegadas e de aplicação, veja Tipos de permissão. Para saber mais sobre estas permissões, veja a referência de permissões.
| Tipo de permissão |
Permissões com menos privilégios |
Permissões com privilégios superiores |
| 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
| 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 estiver a utilizar carateres não ANSI na sua consulta, por exemplo, para consultar assuntos de e-mail com carateres mal formados ou sósias, utilize application/json; charset=utf-8 para o cabeçalho Tipo de Conteúdo.
Corpo da solicitação
No corpo do pedido, forneça um objeto JSON para o Query parâmetro e, opcionalmente, inclua um Timespan parâmetro.
| Parâmetro |
Tipo |
Descrição |
Exemplo |
| Consultar |
Cadeia de caracteres |
Obrigatório. A consulta de investigação no Linguagem de Consulta Kusto (KQL). Para obter mais informações, veja Referência rápida do KQL. |
|
| Período de tempo |
String |
Opcional. O intervalo de tempo durante o qual consultar dados, no formato ISO 8601. O valor predefinido é 30 dias, o que significa que, se não for especificada startTime, a consulta terá um aspeto anterior a 30 dias a partir de agora. Se for especificado um filtro de tempo na consulta e no parâmetro startTime, é aplicado o intervalo de tempo mais curto. Por exemplo, se a consulta tiver um filtro para os últimos 7 dias e startTime for 10 dias atrás, a consulta só terá um aspeto anterior em sete dias. |
|
Os exemplos seguintes mostram os formatos possíveis para o Timepsan parâmetro :
-
Data/Data: "2024-02-01T08:00:00Z/2024-02-15T08:00:00Z" - Datas de início e de fim.
-
Duration/endDate: "P30D/2024-02-15T08:00:00Z" – um período antes da data de fim.
-
Início/duração: "2024-02-01T08:00:00Z/P30D" – Data e duração de início.
-
ISO8601 duração: "P30D" - Duração a partir de agora retroceder.
-
Data/hora única: "2024-02-01T08:00:00Z" – Hora de início com a hora de fim predefinida para a hora atual.
Resposta
Se for bem-sucedida, esta ação devolve um 200 OK código de resposta e um huntingQueryResults no corpo da resposta.
Exemplos
Exemplo 1: consulta com intervalo de tempo predefinido
Solicitação
O exemplo seguinte especifica uma consulta KQL e:
- Analisa a tabela DeviceProcessEvents no esquema de investigação avançado.
- Filtra a condição de o processo de powershell.exe iniciar o evento.
- Especifica o resultado de três colunas da mesma tabela para cada linha:
Timestamp, , FileNameInitiatingProcessFileName.
- Ordena o resultado pelo
Timestamp valor.
- Limita a saída a dois registos (duas linhas).
POST https://graph.microsoft.com/beta/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.Beta.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://v4.hkg1.meaqua.org/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 $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphsecurity "github.com/microsoftgraph/msgraph-beta-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://v4.hkg1.meaqua.org/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.beta.security.microsoftgraphsecurityrunhuntingquery.RunHuntingQueryPostRequestBody runHuntingQueryPostRequestBody = new com.microsoft.graph.beta.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')
.version('beta')
.post(huntingQueryResults);
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\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.Beta.Security
$params = @{
Query = "DeviceProcessEvents | where InitiatingProcessFileName =~ "powershell.exe" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2"
}
Start-MgBetaSecurityHuntingQuery -BodyParameter $params
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.security.microsoft_graph_security_run_hunting_query.run_hunting_query_post_request_body import RunHuntingQueryPostRequestBody
# To initialize your graph_client, see https://v4.hkg1.meaqua.org/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/beta/$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 de período de tempo especificado
Solicitação
Este exemplo especifica uma consulta KQL e analisa a tabela deviceProcessEvents no esquema de investigação avançado há 60 dias.
POST https://graph.microsoft.com/beta/security/runHuntingQuery
{
"Query": "DeviceProcessEvents",
"Timespan": "P90D"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Beta.Security.MicrosoftGraphSecurityRunHuntingQuery;
var requestBody = new RunHuntingQueryPostRequestBody
{
Query = "DeviceProcessEvents",
Timespan = "P90D",
};
// To initialize your graphClient, see https://v4.hkg1.meaqua.org/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 $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphsecurity "github.com/microsoftgraph/msgraph-beta-sdk-go/security"
//other-imports
)
requestBody := graphsecurity.NewRunHuntingQueryPostRequestBody()
query := "DeviceProcessEvents"
requestBody.SetQuery(&query)
timespan := "P90D"
requestBody.SetTimespan(×pan)
// To initialize your graphClient, see https://v4.hkg1.meaqua.org/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.beta.security.microsoftgraphsecurityrunhuntingquery.RunHuntingQueryPostRequestBody runHuntingQueryPostRequestBody = new com.microsoft.graph.beta.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')
.version('beta')
.post(huntingQueryResults);
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\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.Beta.Security
$params = @{
Query = "DeviceProcessEvents"
Timespan = "P90D"
}
Start-MgBetaSecurityHuntingQuery -BodyParameter $params
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.security.microsoft_graph_security_run_hunting_query.run_hunting_query_post_request_body import RunHuntingQueryPostRequestBody
# To initialize your graph_client, see https://v4.hkg1.meaqua.org/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
Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.
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"
}
]
}