Microsoft 365 API de busca avançada do DefenderMicrosoft 365 Defender Advanced hunting API

Importante

O aperfeiçoado Centro de segurança do Microsoft 365 está agora disponível.The improved Microsoft 365 security center is now available. Esta nova experiência traz o Defender para Ponto de Extremidade, Defender para Office 365, Microsoft 365 Defender e muito mais para o Centro de segurança do Microsoft 365.This new experience brings Defender for Endpoint, Defender for Office 365, Microsoft 365 Defender, and more into the Microsoft 365 security center. Conheça as novidades.Learn what's new.

Aplica-se a:Applies to:

  • Microsoft 365 DefenderMicrosoft 365 Defender

Importante

Algumas informações estão relacionadas a produtos pré-lançados que podem ser substancialmente modificados antes de seu lançamento comercial.Some information relates to prereleased product which may be substantially modified before it's commercially released. A Microsoft não faz garantias, expressas ou implícitas, quanto às informações fornecidas aqui.Microsoft makes no warranties, express or implied, with respect to the information provided here.

A busca avançada é uma ferramenta de busca de ameaças que usa consultas especialmente construídas para examinar os últimos 30 dias de dados de eventos no 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. Você pode usar consultas avançadas de busca para inspecionar atividades incomuns, detectar possíveis ameaças e até mesmo responder a ataques.You can use advanced hunting queries to inspect unusual activity, detect possible threats, and even respond to attacks. A API de busca avançada permite que você consulte programaticamente dados de eventos.The advanced hunting API allows you to programatically query event data.

Cotas e alocação de recursosQuotas and resource allocation

As condições a seguir se relacionam a todas as consultas.The following conditions relate to all queries.

  1. As consultas exploram e retornam dados dos últimos 30 dias.Queries explore and return data from the past 30 days.
  2. Os resultados podem retornar até 100.000 linhas.Results can return up to 100,000 rows.
  3. Você pode fazer até 15 chamadas por minuto por locatário.You can make up to 15 calls per minute per tenant.
  4. As consultas serão bloqueadas se o locatário tiver atingido 100% até após o próximo ciclo de 15 minutos.Queries are blocked if the tenant has reached 100% until after the next 15-minute cycle.
  5. Se uma única solicitação for executado por mais de 10 minutos, ela passará o tempo e retornará um erro.If a single request runs for more than 10 minutes, it will time out and return an error.
  6. Um código de resposta HTTP indica que você atingiu uma cota, por número de solicitações enviadas ou pelo tempo de 429 execução alocado.A 429 HTTP response code indicates that you've reached a quota, either by number of requests sent, or by allotted running time. Leia o corpo da resposta para entender o limite atingido.Read the response body to understand the limit you have reached.

Observação

Todas as cotas listadas acima (por exemplo, 15 chamadas por minuto) são por tamanho de locatário.All quotas listed above (for example 15 calls per min) are per tenant size. Essas cotas são mínimas.These quotas are the minimum.

PermissõesPermissions

Uma das seguintes permissões é necessária para chamar a API de busca avançada.One of the following permissions is required to call the advanced hunting API. Para saber mais, incluindo como escolher permissões, consulte Access the Microsoft 365 Defender Protection APIsTo learn more, including how to choose permissions, see Access the Microsoft 365 Defender Protection APIs

Tipo de permissãoPermission type PermissãoPermission Nome de exibição de permissãoPermission display name
AplicativoApplication AdvancedHunting.Read.AllAdvancedHunting.Read.All Executar consultas avançadasRun advanced queries
Delegado (conta corporativa ou de estudante)Delegated (work or school account) AdvancedHunting.ReadAdvancedHunting.Read Executar consultas avançadasRun advanced queries

Observação

Ao obter um token usando credenciais de usuário:When obtaining a token using user credentials:

  • O usuário precisa ter a função AD 'Exibir Dados'The user needs to have the 'View Data' AD role
  • O usuário precisa ter acesso ao dispositivo, com base nas configurações do grupo de dispositivos.The user needs to have access to the device, based on device group settings.

Solicitação HTTPHTTP request

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

Cabeçalhos de solicitaçãoRequest headers

CabeçalhoHeader ValorValue
AutorizaçãoAuthorization Portador {token} Observação: obrigatórioBearer {token} Note: required
Content-TypeContent-Type application/jsonapplication/json

Corpo da solicitaçãoRequest body

No corpo da solicitação, fornece um objeto JSON com os seguintes parâmetros:In the request body, supply a JSON object with the following parameters:

ParâmetroParameter TipoType DescriçãoDescription
ConsultaQuery TextoText A consulta a ser executado.The query to run. Observação: obrigatórioNote: required

RespostaResponse

Se tiver êxito, este método retornará 200 OK e um objeto QueryResponse no corpo da resposta.If successful, this method will return 200 OK, and a QueryResponse object in the response body.

O objeto response contém três propriedades de nível superior:The response object contains three top-level properties:

  1. Estatísticas - Um dicionário de estatísticas de desempenho de consulta.Stats - A dictionary of query performance statistics.
  2. Esquema - O esquema da resposta, uma lista de Name-Type pares para cada coluna.Schema - The schema of the response, a list of Name-Type pairs for each column.
  3. Resultados - Uma lista de eventos de busca avançada.Results - A list of advanced hunting events.

ExemploExample

No exemplo a seguir, um usuário envia a consulta abaixo e recebe um objeto de resposta da API contendo Stats Schema , e 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"
}

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