Microsoft Defender XDR API de búsqueda avanzada

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. 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.

Solicitud HTTP

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

Encabezados de solicitud

Cuerpo de la solicitud

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

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

Artículos relacionados

• Uso de API Microsoft Graph Security: Microsoft Graph | Microsoft Learn

• Acceso a las API de Microsoft Defender XDR

• Más información sobre los límites de API y las licencias

• Descripción de los códigos de error

• Información general sobre la búsqueda avanzada de amenazas