API de busca avançada do Microsoft Defender XDR

Aviso

Essa API de busca avançada é uma versão mais antiga com recursos limitados. Uma versão mais abrangente da Advanced Hunting API está disponível na Microsoft Graph Security API. Para obter mais informações, consulte Busca avançada usando Microsoft Graph API de segurança.

A API avançada de caça Microsoft Defender XDR está em transição para a API de segurança Microsoft Graph, que oferece cobertura de dados mais ampla, maior consistência e maior escalabilidade para fluxos de automação e segurança. A aposentadoria começou em janeiro de 2026. Após a aposentadoria concluída, a API avançada de caça do Microsoft Defender XDR deixa de funcionar mais. Para a linha do tempo de desativação, consulte MC1220762. Para orientações sobre migração, veja Usar a API de segurança da Microsoft Graph.

Importante

Algumas informações estão relacionadas a produtos pré-lançados que podem ser substancialmente modificados antes de seu lançamento comercial. A Microsoft não faz garantias, expressas ou implícitas, quanto às informações fornecidas aqui.

A caça avançada é uma ferramenta de caça a ameaças que utiliza consultas especialmente construídas para examinar dados de eventos no Microsoft Defender. Você pode usar consultas avançadas de busca para inspecionar atividades incomuns, detectar possíveis ameaças e até responder a ataques. A API de busca avançada permite consultar dados de eventos de forma programática.

Cotas e alocação de recursos

As condições a seguir estão relacionadas a todas as consultas.

  1. As consultas exploram e retornam dados dos últimos 30 dias.
  2. Os resultados podem retornar até 100.000 linhas.
  3. Você pode fazer pelo menos 45 chamadas por minuto por locatário. O número de chamadas varia por locatário com base em seu tamanho.
  4. Cada locatário recebe recursos de CPU com base no tamanho do locatário. As consultas serão bloqueadas se o locatário tiver atingido 100% dos recursos alocados até depois do próximo ciclo de 15 minutos. Para evitar consultas bloqueadas devido ao consumo excessivo, siga as orientações em Otimizar suas consultas para evitar o cumprimento das cotas de CPU.
  5. Se uma única solicitação for executada por mais de três minutos, ela atingirá o tempo limite e retornará um erro.
  6. Um 429 código de resposta HTTP indica que você alcançou os recursos de CPU alocados, seja pelo número de solicitações enviadas ou pelo tempo de execução alocado. Leia o corpo da resposta para entender o limite atingido.

Permissões

Uma das permissões a seguir é necessária para chamar a API de busca avançada. Para saber mais, incluindo como escolher permissões, consulte Acessar as APIs de Proteção de Microsoft Defender.

Tipo de permissão Permissão Nome de exibição da permissão
Application AdvancedHunting.Read.All Executar consultas avançadas
Delegado (conta corporativa ou de estudante) AdvancedHunting.Read Executar consultas avançadas

Observação

Ao obter um token usando credenciais de usuário:

  • O usuário precisa ter a função 'Exibir Dados'.
  • O usuário precisa ter acesso ao dispositivo, com base nas configurações do grupo de dispositivos.

solicitação HTTP

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

Cabeçalhos de solicitação

Cabeçalho Valor
Autorização Portador {token} Observação: obrigatório
Content-Type application/json

Corpo da solicitação

No corpo da solicitação, forneça um objeto JSON com os seguintes parâmetros:

Parâmetro Tipo Descrição
Consultar Texto A consulta a ser executada. (obrigatório)

Resposta

Se for bem-sucedido, esse método retornará 200 OKe um objeto QueryResponse no corpo da resposta.

O objeto de resposta contém três propriedades de nível superior:

  1. Estatísticas - Um dicionário de estatísticas de desempenho de consulta.
  2. Esquema - O esquema da resposta, uma lista de Name-Type pares para cada coluna.
  3. Resultados - Uma lista de eventos avançados de busca.

Exemplo

No exemplo a seguir, um usuário envia a consulta abaixo e recebe um objeto de resposta da API contendo Stats, Schema, e Results.

Consultar

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

Objeto de resposta

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

Dica

Você deseja aprender mais? Participe da comunidade de Segurança da Microsoft em nossa Tech Community: Tech Community do Microsoft Defender XDR.