security: runHuntingQuery
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.
Consulta un conjunto especificado de datos de eventos, actividades o entidades compatibles con Microsoft 365 Defender para buscar proactivamente amenazas específicas en su entorno.
Este es el método para la búsqueda avanzada en Microsoft 365 Defender. Este método incluye una consulta en Lenguaje de consulta Kusto (KQL). Especifica una tabla de datos en el esquema de búsqueda avanzada y una secuencia canalada de operadores para filtrar o buscar esos datos y dar formato a la salida de la consulta de maneras específicas.
Obtenga más información sobre la búsqueda de amenazas entre dispositivos, correos electrónicos, aplicaciones e identidades. Obtenga información sobre KQL.
Para obtener información sobre el uso de la búsqueda avanzada en el portal de Microsoft 365 Defender, consulte Búsqueda proactiva de amenazas con búsqueda avanzada en Microsoft 365 Defender.
Esta API está disponible en las siguientes implementaciones nacionales de nube.
Servicio global | Gobierno de EE. UU. L4 | Us Government L5 (DOD) | China operada por 21Vianet |
---|---|---|---|
✅ | ✅ | ✅ | ❌ |
Permissions
Elija el permiso o los permisos marcados como con privilegios mínimos para esta API. Use un permiso o permisos con privilegios superiores 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. |
Solicitud HTTP
POST /security/runHuntingQuery
Encabezados de solicitud
Nombre | Descripción |
---|---|
Authorization | {token} de portador. Obligatorio. Obtenga más información sobre la autenticación y la 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 con formato incorrecto o similares, use application/json; charset=utf-8
para el encabezado Content-Type.
Cuerpo de la solicitud
En el cuerpo de la solicitud, proporcione un objeto JSON para el parámetro , query
.
Parámetro | Tipo | Descripción |
---|---|---|
consulta | Cadena | Consulta de búsqueda en Lenguaje de consulta Kusto (KQL). Para obtener más información sobre la sintaxis de KQL, vea Referencia rápida de KQL. |
Respuesta
Si se ejecuta correctamente, esta acción devuelve un 200 OK
código de respuesta y un huntingQueryResults en el cuerpo de la respuesta.
Ejemplos
Solicitud
En este ejemplo se especifica una consulta KQL que hace lo siguiente:
- Examina la tabla DeviceProcessEvents en el esquema de búsqueda avanzada.
- Filtra la condición de que el proceso de powershell.exe inicie el evento.
- Especifica la salida de 3 columnas de la misma tabla para cada fila:
Timestamp
,FileName
,InitiatingProcessFileName
. - Ordena la salida por el
Timestamp
valor . - Limita la salida a 2 registros (2 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"
}
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"
}
]
}
Comentarios
https://aka.ms/ContentUserFeedback.
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea:Enviar y ver comentarios de