API de búsqueda avanzada de amenazas

  • Artículo

Se aplica a:

  • .. /microsoft-defender-endpoint.md

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 que puede consultar más tablas en la API de seguridad de Microsoft Graph. Consulte Búsqueda avanzada mediante la API de seguridad de Microsoft Graph

¿Quiere experimentar Microsoft Defender para punto de conexión? Regístrese para obtener una prueba gratuita.

Nota:

Si es cliente del Gobierno de EE. UU., use los URI que aparecen en Microsoft Defender para punto de conexión para los clientes del Gobierno de EE. UU.

Sugerencia

Para mejorar el rendimiento, puede usar el servidor más cercano a la ubicación geográfica:

  • api-us.securitycenter.microsoft.com
  • api-eu.securitycenter.microsoft.com
  • api-uk.securitycenter.microsoft.com
  • api-au.securitycenter.microsoft.com

Limitaciones

  1. Solo puede ejecutar una consulta en los datos de los últimos 30 días.

  2. Los resultados incluyen un máximo de 100 000 filas.

  3. El número de ejecuciones es limitado por inquilino:

    • Llamadas API: hasta 45 llamadas por minuto y hasta 1500 llamadas por hora.
    • Tiempo de ejecución: 10 minutos de tiempo de ejecución cada hora y 3 horas de tiempo de ejecución al día.

  4. El tiempo máximo de ejecución de una sola solicitud es de 200 segundos.

  5. 429 response representa alcanzar el límite de cuota por número de solicitudes o por CPU. Lea el cuerpo de la respuesta para comprender qué límite se alcanzó.

  6. El tamaño máximo del resultado de la consulta de una sola solicitud no puede superar los 124 MB. Si se supera, una solicitud HTTP 400 incorrecta con el mensaje "La ejecución de consultas ha superado el tamaño de resultado permitido. Optimice la consulta limitando el número de resultados e inténtelo de nuevo".

Permisos

Se requiere uno de los siguientes permisos para llamar a esta API. Para más información, incluido cómo elegir permisos, consulte Uso de api de Microsoft Defender para punto de conexión

Tipo de permiso Permiso Nombre para mostrar del permiso
Aplicación AdvancedQuery.Read.All Run advanced queries
Delegado (cuenta profesional o educativa) AdvancedQuery.Read Run advanced queries

Nota:

Al obtener un token con credenciales de usuario:

  • El usuario debe tener asignado el View Data rol en Microsoft Entra ID
  • El usuario debe tener acceso al dispositivo en función de la configuración del grupo de dispositivos (consulte Create y administrar grupos de dispositivos para obtener más información).

La creación de grupos de dispositivos se admite en El plan 1 y el plan 2 de Defender para punto de conexión.

Solicitud HTTP

POST https://api.securitycenter.microsoft.com/api/advancedqueries/run

Encabezados de solicitud

Encabezado Valor
Authorization {token} de portador. Necesario.
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. Necesario.

Respuesta

Si se ejecuta correctamente, este método devuelve 200 OK y el objeto QueryResponse en el cuerpo de la respuesta.

Ejemplo

Ejemplo de solicitud

Este es un ejemplo de la solicitud.

POST https://api.securitycenter.microsoft.com/api/advancedqueries/run

{
    "Query":"DeviceProcessEvents
|where InitiatingProcessFileName =~ 'powershell.exe'
|where ProcessCommandLine contains 'appdata'
|project Timestamp, FileName, InitiatingProcessFileName, DeviceId
|limit 2"
}

Ejemplo de respuesta

Este es un ejemplo de la respuesta:

Nota:

El objeto de respuesta que se muestra aquí puede truncarse por brevedad. Todas las propiedades se devolverán desde una llamada real.

{
    "Schema": [
        {
            "Name": "Timestamp",
            "Type": "DateTime"
        },
        {
            "Name": "FileName",
            "Type": "String"
        },
        {
            "Name": "InitiatingProcessFileName",
            "Type": "String"
        },
        {
            "Name": "DeviceId",
            "Type": "String"
        }
    ],
    "Results": [
        {
            "Timestamp": "2020-02-05T01:10:26.2648757Z",
            "FileName": "csc.exe",
            "InitiatingProcessFileName": "powershell.exe",
            "DeviceId": "10cbf9182d4e95660362f65cfa67c7731f62fdb3"
        },
        {
            "Timestamp": "2020-02-05T01:10:26.5614772Z",
            "FileName": "csc.exe",
            "InitiatingProcessFileName": "powershell.exe",
            "DeviceId": "10cbf9182d4e95660362f65cfa67c7731f62fdb3"
        }
    ]
}

Sugerencia

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