API de búsqueda avanzada de Microsoft 365 DefenderMicrosoft 365 Defender Advanced hunting API

Importante

El Centro de seguridad de Microsoft 365 mejorado está ahora disponible.The improved Microsoft 365 security center is now available. Esta nueva experiencia incluye Defender para punto de conexión, Defender para Office 365, Microsoft 365 Defender y más en el Centro de seguridad de Microsoft 365.This new experience brings Defender for Endpoint, Defender for Office 365, Microsoft 365 Defender, and more into the Microsoft 365 security center. Ver las novedades.Learn what's new.

Se aplica a:Applies to:

  • Microsoft 365 DefenderMicrosoft 365 Defender

Importante

Parte de la información se refiere a productos preliminares que pueden ser modificados sustancialmente antes de su lanzamiento comercial.Some information relates to prereleased product which may be substantially modified before it's commercially released. Microsoft no otorga garantías, expresas o implícitas, con respecto a la información que aquí se proporciona.Microsoft makes no warranties, express or implied, with respect to the information provided here.

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 365 Defender.Advanced hunting is a threat-hunting tool that uses specially constructed queries to examine the past 30 days of event data in Microsoft 365 Defender. Puedes usar consultas avanzadas de búsqueda para inspeccionar actividad inusual, detectar posibles amenazas e incluso responder a ataques.You can use advanced hunting queries to inspect unusual activity, detect possible threats, and even respond to attacks. La API de búsqueda avanzada le permite consultar programáticamente los datos de eventos.The advanced hunting API allows you to programatically query event data.

Cuotas y asignación de recursosQuotas and resource allocation

Las siguientes condiciones se relacionan con todas las consultas.The following conditions relate to all queries.

  1. Las consultas exploran y devuelven datos de los últimos 30 días.Queries explore and return data from the past 30 days.
  2. Los resultados pueden devolver hasta 100 000 filas.Results can return up to 100,000 rows.
  3. Puede realizar hasta 15 llamadas por minuto por inquilino.You can make up to 15 calls per minute per tenant.
  4. Tiene 10 minutos de tiempo de ejecución por hora por inquilino.You have 10 minutes of running time per hour per tenant.
  5. Tiene cuatro horas totales de tiempo de ejecución al día por inquilino.You have four total hours of running time per day per tenant.
  6. Si una sola solicitud se ejecuta durante más de 10 minutos, agotará el tiempo de espera y devolverá un error.If a single request runs for more than 10 minutes, it will time out and return an error.
  7. Un código de respuesta HTTP indica que ha alcanzado una cuota, ya sea por número de solicitudes enviadas o por tiempo 429 de ejecución asignado.A 429 HTTP response code indicates that you've reached a quota, either by number of requests sent, or by allotted running time. Lea el cuerpo de la respuesta para comprender el límite que ha alcanzado.Read the response body to understand the limit you have reached.

Nota

Todas las cuotas enumeradas anteriormente (por ejemplo, 15 llamadas por minuto) son por tamaño de espacio empresarial.All quotas listed above (for example 15 calls per min) are per tenant size. Estas cuotas son las mínimas.These quotas are the minimum.

PermisosPermissions

Uno de los siguientes permisos es necesario para llamar a la API de búsqueda avanzada.One of the following permissions is required to call the advanced hunting API. Para obtener más información, incluido cómo elegir permisos, vea Access the Microsoft 365 Defender Protection APITo learn more, including how to choose permissions, see Access the Microsoft 365 Defender Protection APIs

Tipo de permisoPermission type PermisoPermission Nombre para mostrar de permisosPermission display name
AplicaciónApplication AdvancedHunting.Read.AllAdvancedHunting.Read.All Ejecutar consultas avanzadasRun advanced queries
Delegado (cuenta profesional o educativa)Delegated (work or school account) AdvancedHunting.ReadAdvancedHunting.Read Ejecutar consultas avanzadasRun advanced queries

Nota

Al obtener un token con credenciales de usuario:When obtaining a token using user credentials:

  • El usuario debe tener el rol de AD "Ver datos"The user needs to have the 'View Data' AD role
  • El usuario debe tener acceso al dispositivo en función de la configuración del grupo de dispositivos.The user needs to have access to the device, based on device group settings.

Solicitud HTTPHTTP request

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

Encabezados de solicitudRequest headers

EncabezadoHeader ValorValue
AuthorizationAuthorization Portador {token} Nota: obligatorioBearer {token} Note: required
Content-TypeContent-Type application/jsonapplication/json

Cuerpo de la solicitudRequest body

En el cuerpo de la solicitud, proporcione un objeto JSON con los siguientes parámetros:In the request body, supply a JSON object with the following parameters:

ParámetroParameter TipoType DescripciónDescription
ConsultaQuery TextoText Consulta que se debe ejecutar.The query to run. Nota: obligatorioNote: required

RespuestaResponse

Si se ejecuta correctamente, este método devolverá 200 OK y un objeto QueryResponse en el cuerpo de la respuesta.If successful, this method will return 200 OK, and a QueryResponse object in the response body.

El objeto response contiene tres propiedades de nivel superior:The response object contains three top-level properties:

  1. Estadísticas: diccionario de estadísticas de rendimiento de consulta.Stats - A dictionary of query performance statistics.
  2. Esquema: el esquema de la respuesta, una lista de Name-Type pares de cada columna.Schema - The schema of the response, a list of Name-Type pairs for each column.
  3. Resultados: una lista de eventos de búsqueda avanzados.Results - A list of advanced hunting events.

EjemploExample

En el siguiente ejemplo, un usuario envía la consulta siguiente y recibe un objeto de respuesta api que contiene Stats , Schema y Results .In the following example, a user sends the query below and receives an API response object containing Stats, Schema, and Results.

ConsultaQuery

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

Response (objeto)Response object

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