Compartir a través de

security: runHuntingQuery

  • Artículo

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 365 Defender para buscar de forma proactiva amenazas específicas en su entorno.

Este método es para la búsqueda avanzada en Microsoft 365 Defender. 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 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 Query parámetro y, opcionalmente, incluya un Timespan parámetro.

Parámetro Tipo Description Ejemplo
Consulta Cadena Obligatorio. La consulta de búsqueda en el lenguaje de consulta Kusto (KQL). Para obtener más información, vea Referencia rápida de KQL.
Timespan Cadena Opcional. Intervalo de tiempo durante el cual se consultan los datos, en formato ISO 8601. El valor predeterminado es de 30 días, lo que significa que si no se especifica startTime, la consulta espera 30 días a partir de ahora. Si se especifica un filtro de tiempo tanto en la consulta como en el parámetro startTime, se aplica el intervalo de tiempo más corto. Por ejemplo, si la consulta tiene un filtro para los últimos 7 días y startTime es hace 10 días, la consulta solo mira siete días atrás.

En los ejemplos siguientes se muestran los formatos posibles para el Timepsan parámetro :

  • Fecha/Fecha: "2024-02-01T08:00:00Z/2024-02-15T08:00:00Z" - Fechas de inicio y finalización.
  • Duration/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 de ahora hacia atrás.
  • Fecha y hora únicas: "2024-02-01T08:00:00Z": hora de inicio con la hora de finalización predeterminada en la hora actual.

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

Ejemplo 1: Consulta con intervalo de tiempo predeterminado

Solicitud

En el ejemplo siguiente se especifica una consulta KQL y:

  • 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 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"
}

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 el parámetro de intervalo de tiempo especificado opcionalmente

Solicitud

En este ejemplo se especifica una consulta 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"
}

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