Microsoft 365 Defender avançada procura da API

Nota

Quer experimentar o Microsoft 365 Defender? Saiba mais sobre como pode avaliar e pilotar a Microsoft 365 Defender.

Aplica-se a:

  • Microsoft 365 Defender

Importante

Algumas informações referem-se a produtos pré-lançados que podem ser modificados substancialmente antes do seu lançamento comercial. A Microsoft não oferece garantias, expressas ou implícitas, relativamente às informações aqui fornecidas.

A procura avançada é uma ferramenta de procura de ameaças que utiliza consultas especialmente construídas para examinar os dados dos últimos 30 dias de eventos no Microsoft 365 Defender. Pode utilizar consultas de pesquisa avançadas para inspecionar atividade invulgar, detetar possíveis ameaças e até responder a ataques. A API de procura avançada permite-lhe fazer consultas por programação a dados de eventos.

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 até 45 chamadas por minuto por inquilino.
  4. As consultas são bloqueadas se o inquilino tiver atingido 100% até ao próximo ciclo de 15 minutos.
  5. Se um único pedido for executado durante mais de 10 minutos, irá ficar sem tempo e devolverá um erro.
  6. Um 429 código de resposta HTTP indica que atingiu uma quota, seja pelo número de pedidos enviados ou pelo tempo de execução atribuída. Leia o corpo da resposta para compreender o limite que atingiu.

Nota

Todas as quotas listadas acima (por exemplo, 15 chamadas por minuto) são de largura de inquilino. Estas quotas são o mínimo.

Permissões

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

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 escolar) 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" do AD
  • O utilizador precisa de ter acesso ao dispositivo, com base nas definições de grupo do dispositivo.

Pedido HTTP

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

Pedir cabeçalhos

Cabeçalho Valor
Autorização Bearer {token} Nota: obrigatório:
Tipo de Conteúdo application/json

Pedir corpo

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

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

Resposta

Se for bem-sucedido, este método irá 200 OKdevolver e um objeto QueryResponse no corpo da resposta.

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

  1. Estatística – um dicionário de estatísticas de desempenho de consultas.
  2. Esquema - o esquema da resposta, uma lista de Name-Type de cada coluna.
  3. Resultados – uma lista de eventos de procura avançados.

Exemplos:

No exemplo seguinte, um utilizador envia a consulta abaixo e recebe um objeto de resposta API que contém Stats, 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"
        }
    ]
}