Пространство имен: microsoft.graph.security
Важно!
API версии /beta в Microsoft Graph могут быть изменены. Использование этих API в производственных приложениях не поддерживается. Чтобы определить, доступен ли API в версии 1.0, используйте селектор версий.
Запросите указанный набор данных о событии, действии или объекте, поддерживаемый Microsoft Defender XDR, для упреждающего поиска конкретных угроз в вашей среде.
Этот метод предназначен для расширенного поиска в Microsoft Defender XDR. Этот метод включает запрос на языке запросов Kusto (KQL). Он указывает таблицу данных в схеме расширенного поиска и конвейерную последовательность операторов для фильтрации или поиска этих данных и форматирования выходных данных запроса определенными способами.
Узнайте больше об обнаружении угроз на устройствах, в сообщениях электронной почты, приложениях и удостоверениях. Подробнее о KQL.
Сведения об использовании расширенного поиска на портале Microsoft Defender см. в разделе Упреждающий поиск угроз с помощью расширенного поиска в Microsoft Defender XDR.
Этот API доступен в следующих национальных облачных развертываниях.
| Глобальное обслуживание |
Правительство США L4 |
Правительство США L5 (DOD) |
Китай, обслуживаемый 21Vianet |
| ✅ |
✅ |
✅ |
❌ |
Разрешения
Выберите разрешение или разрешения, помеченные как наименее привилегированные для этого API. Используйте более высокий уровень привилегий или разрешений, только если это требуется вашему приложению. Дополнительные сведения о делегированных разрешениях и разрешениях приложений см. в статье Типы разрешений. Дополнительные сведения об этих разрешениях см. в справочнике по разрешениям.
| Тип разрешения |
Разрешения с наименьшим объемом привилегий |
Разрешения с более высоким уровнем привилегий |
| Делегированные (рабочая или учебная учетная запись) |
ThreatHunting.Read.All |
Недоступно. |
| Делегированные (личная учетная запись Майкрософт) |
Не поддерживается. |
Не поддерживается. |
| Приложение |
ThreatHunting.Read.All |
Недоступно. |
Важно!
Вошедшему пользователю также необходима одна из следующих ролей:
HTTP-запрос
POST /security/runHuntingQuery
| Имя |
Описание |
| Авторизация |
Bearer {token}. Обязательно. Дополнительные сведения об аутентификации и авторизации. |
| Content-Type |
application/json. Обязательно. |
Примечание.
Если вы используете, например, в запросе знаки, отличные от ANSI, для определения тем сообщений электронной почты с неверно сформированными или похожими символами, используйте application/json; charset=utf-8 в качестве заголовка тип содержимого.
Текст запроса
В тексте запроса укажите объект JSON для параметра query и при необходимости добавьте timespan параметр и параметр.workspaceId
| Параметр |
Тип |
Описание |
Пример |
| Запрос |
String |
Обязательный. Запрос поиска на языке запросов Kusto (KQL). Дополнительные сведения см. в кратком справочнике по KQL. |
|
| Отрезок времени |
String |
Необязательный параметр. Интервал времени, в течение которого выполняется запрос данных в формате ISO 8601. Значение по умолчанию — 30 дней. Если и в запросе, и в параметре timespan указан временной фильтр, применяется более короткий временной интервал. |
|
| workspaceId |
GUID |
Необязательный параметр. GUID определенной целевой рабочей области Log Analytics. Если этот параметр опущен, служба использует основную рабочую область вызывающей стороны. Если рабочая область не найдена или недоступна, служба возвращается к основной рабочей области вызывающей стороны. |
00000000-0000-0000-0000-000000000001 |
В следующих примерах показаны возможные форматы этого параметра timespan :
-
Дата и дата: "2024-02-01T08:00:00Z/2024-02-15T08:00:00Z" — даты начала и окончания.
-
Duration/endDate: "P30D/2024-02-15T08:00:00Z" — период до даты окончания.
-
Начало/продолжительность: "2024-02-01T08:00:00Z/P30D" — дата начала и продолжительность.
-
ISO8601 длительность: "P30D" - Длительность с текущего момента в обратном направлении.
-
Одиночная дата и время: "2024-02-01T08:00:00Z" — время начала, время окончания по умолчанию текущее время.
Отклик
В случае успеха это действие возвращает код ответа 200 OK и huntingQueryResults в тексте ответа.
Примеры
Пример 1. Запрос с интервалом времени по умолчанию
Запрос
В следующем примере задается запрос KQL и:
- Изучает таблицу DeviceProcessEvents в схеме расширенного поиска.
- Фильтрация при условии, что процесс powershell.exe инициирует событие.
- Определяет выходные данные трех столбцов из одной таблицы для каждой строки:
Timestamp, FileName, InitiatingProcessFileName.
- Сортирует выходные данные по значению
Timestamp .
- Ограничивает выходные данные двумя записями (две строки).
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://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 $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://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.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://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)
Отклик
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"
}
]
}
Пример 2. Запрос с необязательным указанным параметром timespan
Запрос
В этом примере указывается запрос KQL и рассматривается таблица deviceProcessEvents в схеме расширенного поиска 60-дневной давности.
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://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 $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://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.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://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)
Отклик
Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.
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"
}
]
}
Пример 3. Запрос к определенной рабочей области
Запрос
В следующем примере указывается запрос KQL, который нацелен на определенную рабочую область Log Analytics, передавая необязательный параметр workspaceId .
POST https://graph.microsoft.com/beta/security/runHuntingQuery
Content-Type: application/json
{
"query": "DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2",
"timespan": "P1D",
"workspaceId": "00000000-0000-0000-0000-000000000001"
}
// 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",
Timespan = "P1D",
WorkspaceId = Guid.Parse("00000000-0000-0000-0000-000000000001"),
};
// 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 $v0.*
// Dependencies
import (
"context"
"github.com/google/uuid"
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)
timespan := "P1D"
requestBody.SetTimespan(×pan)
workspaceId := uuid.MustParse("00000000-0000-0000-0000-000000000001")
requestBody.SetWorkspaceId(&workspaceId)
// 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.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");
runHuntingQueryPostRequestBody.setTimespan("P1D");
runHuntingQueryPostRequestBody.setWorkspaceId(UUID.fromString("00000000-0000-0000-0000-000000000001"));
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',
timespan: 'P1D',
workspaceId: '00000000-0000-0000-0000-000000000001'
};
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');
$requestBody->setTimespan('P1D');
$requestBody->setWorkspaceId('00000000-0000-0000-0000-000000000001');
$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"
timespan = "P1D"
workspaceId = "00000000-0000-0000-0000-000000000001"
}
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://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",
timespan = "P1D",
workspace_id = UUID("00000000-0000-0000-0000-000000000001"),
)
result = await graph_client.security.microsoft_graph_security_run_hunting_query.post(request_body)
Отклик
Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.
HTTP/1.1 200 OK
Content-type: application/json
{
"schema": [
{
"name": "Timestamp",
"type": "DateTime"
},
{
"name": "FileName",
"type": "String"
},
{
"name": "InitiatingProcessFileName",
"type": "String"
}
],
"results": [
{
"Timestamp": "2026-03-10T06:38:35.766Z",
"FileName": "conhost.exe",
"InitiatingProcessFileName": "powershell.exe"
},
{
"Timestamp": "2026-03-10T06:38:30.516Z",
"FileName": "conhost.exe",
"InitiatingProcessFileName": "powershell.exe"
}
]
}