Espacio de nombres: microsoft.graph.security
Importante
Las API de la versión /beta de Microsoft Graph están sujetas a cambios. No se admite el uso de estas API en aplicaciones de producción. Para determinar si una API está disponible en la versión 1.0, use el selector de Versión.
Consulte un conjunto especificado de datos de eventos, actividades o entidades compatibles con Microsoft Defender XDR para buscar de forma proactiva amenazas específicas en su entorno.
Este método es para la búsqueda avanzada en Microsoft Defender XDR. Este método incluye una consulta en el Lenguaje de consulta Kusto (KQL). Especifica una tabla de datos en el esquema de búsqueda avanzada y una secuencia canalizada de operadores para filtrar o buscar esos datos y dar formato al resultado de la consulta de maneras específicas.
Obtenga más información sobre cómo buscar amenazas en dispositivos, correos electrónicos, aplicaciones e identidades. Obtenga más información sobre KQL.
Para obtener información sobre el uso de la búsqueda avanzada en el portal de Microsoft Defender, consulte Búsqueda proactiva de amenazas con búsqueda avanzada en Microsoft Defender XDR.
Esta API está disponible en las siguientes implementaciones en la nube nacional.
| Servicio global |
Administración pública de EE. UU. |
Gobierno de EE. UU. L5 (DOD) |
China operado por 21Vianet |
| ✅ |
✅ |
✅ |
❌ |
Permissions
Elija el permiso o los permisos marcados como con privilegios mínimos para esta API. Use uno o varios permisos con privilegios más altos solo si la aplicación lo requiere. Para obtener más información sobre los permisos delegados y de aplicación, consulte Tipos de permisos. Para obtener más información sobre estos permisos, consulte la referencia de permisos.
| Tipo de permiso |
Permisos con privilegios mínimos |
Permisos con privilegios más altos |
| Delegado (cuenta profesional o educativa) |
ThreatHunting.Read.All |
No disponible. |
| Delegado (cuenta personal de Microsoft) |
No admitida. |
No admitida. |
| Aplicación |
ThreatHunting.Read.All |
No disponible. |
Importante
El usuario que ha iniciado sesión también necesita uno de los siguientes roles:
Solicitud HTTP
POST /security/runHuntingQuery
| Nombre |
Descripción |
| Authorization |
{token} de portador. Obligatorio. Obtenga más información sobre autenticación y autorización. |
| Content-Type |
application/json. Obligatorio. |
Nota:
Si usa caracteres no ANSI en la consulta, por ejemplo, para consultar asuntos de correo electrónico con caracteres mal formados o similares, úselos application/json; charset=utf-8 para el encabezado Tipo de contenido.
Cuerpo de la solicitud
En el cuerpo de la solicitud, proporcione un objeto JSON para el query parámetro y, opcionalmente, incluya un timespan parámetro y un workspaceId parámetro.
| Parámetro |
Tipo |
Descripción |
Ejemplo |
| consulta |
Cadena |
Obligatorio. La consulta de búsqueda en el Lenguaje de consulta Kusto (KQL). Para obtener más información, consulte la referencia rápida de KQL. |
|
| intervalo de tiempo |
Cadena |
Opcional. El intervalo de tiempo durante el cual consultar datos, en formato ISO 8601. El valor predeterminado es 30 días. Si se especifica un filtro de tiempo tanto en la consulta como en el parámetro de intervalo de tiempo , se aplica el intervalo de tiempo más corto. |
|
| workspaceId |
Guid |
Opcional. El GUID de un área de trabajo de Log Analytics específica a la que se va a dirigir. Si se omite, el servicio usa el área de trabajo principal del autor de la llamada. Si no se encuentra el área de trabajo o no se puede acceder a ella, el servicio vuelve al área de trabajo principal del autor de la llamada. |
00000000-0000-0000-0000-000000000001 |
Los siguientes ejemplos muestran los formatos posibles para el timespan parámetro:
-
Fecha/Fecha: "2024-02-01T08:00:00Z/2024-02-15T08:00:00Z": fechas de inicio y finalización.
-
Duración/endDate: "P30D/2024-02-15T08:00:00Z" - Un período antes de la fecha de finalización.
-
Inicio/duración: "2024-02-01T08:00:00Z/P30D": fecha de inicio y duración.
-
ISO8601 duración: "P30D" - Duración desde ahora hacia atrás.
-
Fecha y hora única: "2024-02-01T08:00:00Z": hora de inicio con la hora de finalización predeterminada en la hora actual.
Respuesta
Si se realiza correctamente, esta acción devuelve un código de respuesta y un 200 OKhuntingQueryResults en el cuerpo de la respuesta.
Ejemplos
Ejemplo 1: Consulta con intervalo de tiempo predeterminado
Solicitud
En el ejemplo siguiente se especifica una consulta de KQL y:
- Busca en la tabla DeviceProcessEvents en el esquema de búsqueda avanzada.
- Se filtra según la condición de que el proceso de powershell.exe inicie el evento.
- Especifica la salida de tres columnas de la misma tabla para cada fila:
Timestamp, FileName, InitiatingProcessFileName.
- Ordena la salida por el
Timestamp valor.
- Limita la salida a dos registros (dos filas).
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)
Respuesta
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"
}
]
}
Ejemplo 2: Consulta con opcional el parámetro de intervalo de tiempo especificado
Solicitud
En este ejemplo se especifica una consulta de KQL y se examina la tabla deviceProcessEvents en el esquema de búsqueda avanzada hace 60 días.
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)
Respuesta
Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.
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"
}
]
}
Ejemplo 3: Consulta de un área de trabajo específica
Solicitud
En el ejemplo siguiente se especifica una consulta KQL y se dirige a un área de trabajo de Log Analytics específica pasando el parámetro opcional workId .
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)
Respuesta
Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.
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"
}
]
}