Microsoft Defender XDR API de búsqueda avanzada

  • Artículo

Se aplica a:

  • Microsoft Defender XDR

Advertencia

Esta API de búsqueda avanzada es una versión anterior con funcionalidades limitadas. Ya hay disponible una versión más completa de la API de búsqueda avanzada en la API de seguridad de Microsoft Graph. Consulte Búsqueda avanzada mediante la API de seguridad de Microsoft Graph

Importante

Parte de la información se refiere a productos preliminares que pueden ser modificados sustancialmente antes de su lanzamiento comercial. Microsoft no otorga garantías, expresas o implícitas, con respecto a la información que aquí se proporciona.

La búsqueda avanzada es una herramienta de búsqueda de amenazas que usa consultas especialmente construidas para examinar los últimos 30 días de datos de eventos en Microsoft Defender XDR. Puede usar consultas de búsqueda avanzadas para inspeccionar actividades inusuales, detectar posibles amenazas e incluso responder a ataques. La API de búsqueda avanzada permite consultar datos de eventos mediante programación.

Cuotas y asignación de recursos

Las condiciones siguientes se relacionan con todas las consultas.

  1. Las consultas exploran y devuelven datos de los últimos 30 días.
  2. Los resultados pueden devolver hasta 100 000 filas.
  3. Puede realizar al menos 45 llamadas por minuto por inquilino. El número de llamadas varía por inquilino en función de su tamaño.
  4. A cada inquilino se le asignan recursos de CPU, en función del tamaño del inquilino. Las consultas se bloquean si el inquilino ha alcanzado el 100 % de los recursos asignados hasta después del ciclo de 15 minutos siguiente. Para evitar consultas bloqueadas debido al consumo excesivo, siga las instrucciones de Optimización de las consultas para evitar alcanzar las cuotas de CPU.
  5. Si una sola solicitud se ejecuta durante más de tres minutos, se agota el tiempo de espera y devuelve un error.
  6. Un 429 código de respuesta HTTP indica que ha alcanzado los recursos de CPU asignados, ya sea por número de solicitudes enviadas o por tiempo de ejecución asignado. Lea el cuerpo de la respuesta para comprender el límite que ha alcanzado.

Permissions

Se requiere uno de los permisos siguientes para llamar a la API de búsqueda avanzada. Para obtener más información, incluido cómo elegir permisos, consulte Acceso a las API de protección de Microsoft Defender XDR.

Tipo de permiso Permiso Nombre para mostrar del permiso
Aplicación AdvancedHunting.Read.All Ejecución de consultas avanzadas
Delegado (cuenta profesional o educativa) AdvancedHunting.Read Ejecución de consultas avanzadas

Nota:

Al obtener un token con credenciales de usuario:

  • El usuario debe tener el rol "Ver datos".
  • El usuario debe tener acceso al dispositivo, en función de la configuración del grupo de dispositivos.

Solicitud HTTP

POST https://api.security.microsoft.com/api/advancedhunting/run

Encabezados de solicitud

Encabezado Valor
Autorización Portador {token} Nota: obligatorio
Content-Type application/json

Cuerpo de la solicitud

En el cuerpo de la solicitud, proporcione un objeto JSON con los parámetros siguientes:

Parámetro Tipo Description
Consulta Texto Consulta que se va a ejecutar. (obligatorio)

Respuesta

Si se ejecuta correctamente, este método devolverá 200 OKy un objeto QueryResponse en el cuerpo de la respuesta.

El objeto de respuesta contiene tres propiedades de nivel superior:

  1. Estadísticas: diccionario de estadísticas de rendimiento de consultas.
  2. Esquema: esquema de la respuesta, una lista de pares de Name-Type para cada columna.
  3. Resultados: una lista de eventos de búsqueda avanzada.

Ejemplo

En el ejemplo siguiente, un usuario envía la consulta siguiente y recibe un objeto de respuesta de API que contiene Stats, Schemay Results.

Consulta

{
    "Query":"DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2"
}

Objeto Response

{
    "Stats": {
        "ExecutionTime": 4.621215,
        "resource_usage": {
            "cache": {
                "memory": {
                    "hits": 773461,
                    "misses": 4481,
                    "total": 777942
                },
                "disk": {
                    "hits": 994,
                    "misses": 197,
                    "total": 1191
                }
            },
            "cpu": {
                "user": "00:00:19.0468750",
                "kernel": "00:00:00.0156250",
                "total cpu": "00:00:19.0625000"
            },
            "memory": {
                "peak_per_node": 236822432
            }
        },
        "dataset_statistics": [
            {
                "table_row_count": 2,
                "table_size": 102
            }
        ]
    },
    "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"
        }
    ]
}

Sugerencia

¿Desea obtener más información? Engage con la comunidad de seguridad de Microsoft en nuestra comunidad tecnológica: Microsoft Defender XDR Tech Community.