Compartilhar via

API de busca avançada de ameaças

  • Artigo

Aplica-se a:

Aviso

Esta API de investigação avançada é uma versão mais antiga com capacidades limitadas. Já está disponível uma versão mais abrangente da API de investigação avançada que pode consultar mais tabelas na API de segurança do Microsoft Graph. Veja Investigação avançada com a API de segurança do Microsoft Graph

Deseja experimentar o Microsoft Defender para Ponto de Extremidade? Inscreva-se para uma avaliação gratuita.

Observação

Se for um cliente do Us Government, utilize os URIs listados no Microsoft Defender para Endpoint para clientes do Us Government.

Dica

Para um melhor desempenho, pode utilizar o servidor mais próximo da localização geográfica:

  • us.api.security.microsoft.com
  • eu.api.security.microsoft.com
  • uk.api.security.microsoft.com
  • au.api.security.microsoft.com
  • swa.api.security.microsoft.com
  • ina.api.security.microsoft.com

Limitações

  1. Só pode executar uma consulta em dados dos últimos 30 dias.

  2. Os resultados incluem um máximo de 100 000 linhas.

  3. O número de execuções é limitado por inquilino:

    • Chamadas à API: até 45 chamadas por minuto e até 1500 chamadas por hora.
    • Tempo de execução: 10 minutos de tempo de execução a cada hora e 3 horas de tempo de execução por dia.

  4. O tempo máximo de execução de um único pedido é de 200 segundos.

  5. 429 A resposta representa atingir o limite de quota por número de pedidos ou pela CPU. Leia o corpo da resposta para compreender que limite foi atingido.

  6. O tamanho máximo do resultado da consulta de um único pedido não pode exceder os 124 MB. Se for excedido, um Pedido Incorreto HTTP 400 com a mensagem "A execução da consulta excedeu o tamanho do resultado permitido. Otimize a consulta ao limitar o número de resultados e tente novamente" ocorre.

Permissões

Uma das seguintes permissões é necessária para chamar esta API. Para saber mais, incluindo como escolher permissões, consulte Utilizar as APIs do Microsoft Defender para Endpoint

Tipo de permissão Permissão Nome a apresentar da permissão
Application AdvancedQuery.Read.All Run advanced queries
Delegado (conta corporativa ou de estudante) AdvancedQuery.Read Run advanced queries

Observação

Ao obter um token com credenciais de utilizador:

  • O utilizador tem de ter a função View Data atribuída no ID do Microsoft Entra
  • O utilizador precisa de ter acesso ao dispositivo, com base nas definições do grupo de dispositivos (consulte Criar e gerir grupos de dispositivos para obter mais informações)

A criação de grupos de dispositivos é suportada no Defender para Endpoint Plano 1 e Plano 2.

Solicitação HTTP

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

Cabeçalhos de solicitação

Cabeçalho Valor
Autorização {token} de portador. Obrigatório.
Content-Type application/json

Corpo da solicitação

No corpo do pedido, forneça um objeto JSON com os seguintes parâmetros:

Parâmetro Tipo Descrição
Consultar Texto A consulta a executar. Obrigatório.

Resposta

Se for bem-sucedido, este método devolve 200 OK e o objeto QueryResponse no corpo da resposta.

Exemplo

Exemplo de solicitação

Eis um exemplo do pedido.

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

Exemplo de resposta

Veja um exemplo de resposta.

Observação

O objeto de resposta apresentado aqui pode ser truncado por questões de brevidade. Todas as propriedades serão retornadas de uma chamada 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"
        }
    ]
}

Dica

Você deseja aprender mais? Contacte a comunidade de Segurança da Microsoft na nossa Comunidade Tecnológica: Microsoft Defender para Endpoint Tech Community.