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

A caça avançada é uma ferramenta de caça a ameaças que utiliza consultas especialmente concebidas para examinar os últimos 30 dias de dados de eventos no Microsoft Defender. 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, consulte Aceder às APIs do Microsoft Defender Protection.

Pedido HTTP

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

Cabeçalhos de pedido

Corpo do pedido

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

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

Artigos relacionados

• Utilizar a API de segurança do Microsoft Graph – Microsoft Graph | Microsoft Learn

• Aceder às APIs Microsoft Defender XDR

• Saiba mais sobre os limites e o licenciamento da API

• Compreender os códigos de erro

• Descrição geral da investigação avançada