Partilhar via

API de investigação avançada do Microsoft Defender XDR

  • Artigo

Aplica-se a:

  • Microsoft Defender XDR

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 na API de segurança do Microsoft Graph. Veja Investigação avançada com a API de segurança do Microsoft Graph

Importante

Algumas informações estão relacionadas com o produto pré-lançado que pode ser substancialmente modificado antes de ser lançado comercialmente. A Microsoft não oferece garantias, expressas ou implícitas, em relação às informações aqui fornecidas.

A investigação avançada é uma ferramenta de investigação de ameaças que utiliza consultas especialmente construídas para examinar os últimos 30 dias de dados de eventos no Microsoft Defender XDR. Pode utilizar consultas de investigação avançadas para inspecionar atividades invulgares, detetar possíveis ameaças e até responder a ataques. A API de investigação avançada permite-lhe consultar dados de eventos através de programação.

Quotas e alocação de recursos

As seguintes condições estão relacionadas com todas as consultas.

  1. As consultas exploram e devolvem dados dos últimos 30 dias.
  2. Os resultados podem devolver até 100 000 linhas.
  3. Pode fazer, pelo menos, 45 chamadas por minuto por inquilino. O número de chamadas varia consoante o respetivo tamanho.
  4. Cada inquilino tem recursos de CPU alocados, com base no tamanho do inquilino. As consultas são bloqueadas se o inquilino tiver atingido 100% dos recursos alocados até depois do ciclo de 15 minutos seguinte. Para evitar consultas bloqueadas devido ao consumo excessivo, siga as orientações em Otimizar as consultas para evitar atingir as quotas da CPU.
  5. Se um único pedido for executado durante mais de três minutos, excede o tempo limite e devolve um erro.
  6. Um 429 código de resposta HTTP indica que atingiu os recursos de CPU alocados, quer pelo número de pedidos enviados, quer pelo tempo de execução atribuído. Leia o corpo da resposta para compreender o limite que atingiu.

Permissões

É necessária uma das seguintes permissões para chamar a API de investigação avançada. Para saber mais, incluindo como escolher permissões, veja Aceder às APIs de Proteção Microsoft Defender XDR.

Tipo de permissão Permissão Nome a apresentar da permissão
Aplicação AdvancedHunting.Read.All Executar consultas avançadas
Delegado (conta escolar ou profissional) AdvancedHunting.Read Executar consultas avançadas

Nota

Ao obter um token com credenciais de utilizador:

  • O utilizador tem de ter a função "Ver Dados".
  • O utilizador tem de ter acesso ao dispositivo, com base nas definições do grupo de dispositivos.

Pedido HTTP

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

Cabeçalhos de pedido

Cabeçalho Valor
Autorização Portador {token} Nota: necessário
Tipo de Conteúdo aplicação/json

Corpo do pedido

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

Parâmetro Tipo Descrição
Consulta Text A consulta a executar. (obrigatório)

Resposta

Se for bem-sucedido, este método devolverá 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 consultas.
  2. Esquema – o esquema da resposta, uma lista de pares Name-Type para cada coluna.
  3. Resultados – uma lista de eventos de investigação avançados.

Exemplos:

No exemplo seguinte, um utilizador envia a consulta abaixo e recebe um objeto de resposta da API que Statscontém , Schemae Results.

Consulta

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

Sugestão

Quer saber mais? Interaja com a comunidade do Microsoft Security na nossa Tech Community: Microsoft Defender XDR Tech Community.