Criar API de alerta
Aplica-se a:
- Plano 1 do Microsoft Defender para Ponto de Extremidade
- Microsoft Defender para Ponto de Extremidade
- Microsoft Defender XDR
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
Descrição da API
Cria um novo Alerta sobre o Evento.
- O Evento do Microsoft Defender para Endpoint é necessário para a criação do alerta.
- Tem de fornecer três parâmetros do Evento no pedido: Hora do Evento, ID do Computador e ID do Relatório. Veja o exemplo a seguir.
- Pode utilizar um evento encontrado na API de Investigação Avançada ou no Portal.
- Se existir um alerta aberto no mesmo Dispositivo com o mesmo Título, o novo alerta criado é intercalado com o mesmo.
- Uma investigação automática é iniciada automaticamente em alertas criados através da API.
Limitações
- As limitações de taxa para esta API são de 15 chamadas por minuto.
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 | Alert.ReadWrite.All | "Ler e escrever todos os alertas" |
| Delegado (conta corporativa ou de estudante) | Alert.ReadWrite | "Alertas de leitura e escrita" |
Observação
Ao obter um token com credenciais de utilizador:
- O utilizador tem de ter, pelo menos, a seguinte permissão de função: Investigação de alertas. Para obter mais informações, veja Criar e gerir funções.
- O utilizador tem de ter acesso ao dispositivo associado ao alerta, com base nas definições do grupo de dispositivos. Para obter mais informações, veja Criar e gerir grupos de dispositivos.
A criação do Grupo de Dispositivos é suportada no Plano 1 e Plano 2 do Defender para Endpoint
Solicitação HTTP
POST https://api.securitycenter.microsoft.com/api/alerts/CreateAlertByReference
Cabeçalhos de solicitação
| Nome | Tipo | Descrição |
|---|---|---|
| Autorização | Cadeia de caracteres | {token} de portador. Obrigatório. |
| Content-Type | Cadeia de Caracteres | application/json. Obrigatório. |
Corpo da solicitação
No corpo do pedido, forneça os seguintes valores (todos são necessários):
| Propriedade | Tipo | Descrição |
|---|---|---|
| eventTime | DateTime(UTC) | O tempo exata do evento como cadeia, conforme obtido a partir da investigação avançada. Por exemplo, 2018-08-03T16:45:21.7115183ZObrigatório. |
| reportId | Cadeia de caracteres | O reportId do evento, conforme obtido da investigação avançada. Obrigatório. |
| machineId | Cadeia de caracteres | ID do dispositivo no qual o evento foi identificado. Obrigatório. |
| severity | Cadeia de caracteres | Gravidade do alerta. Os valores das propriedades são: "Baixo", "Médio" e "Alto". Obrigatório. |
| title | Cadeia de caracteres | Título do alerta. Obrigatório. |
| description | Cadeia de caracteres | Descrição do alerta. Obrigatório. |
| recommendedAction | Cadeia de caracteres | O agente de segurança tem de efetuar esta ação ao analisar o alerta. Obrigatório. |
| category | Cadeia de caracteres | Categoria do alerta. Os valores das propriedades são: "Geral", "CommandAndControl", "Collection", "CredentialAccess", "DefenseEvasion", "Discovery", "Exfiltration", "Exploit", "Execution", "InitialAccess", "LateralMovement", "Malware", "Persistence", "PrivilegeEscalation", "Ransomware", "SuspiciousActivity" Necessário. |
Resposta
Se for bem-sucedido, este método devolve 200 OK e um novo objeto de alerta no corpo da resposta. Se o evento com as propriedades especificadas (reportId, eventTime e machineId) não tiver sido encontrado – 404 Não Encontrado.
Exemplo
Solicitação
Eis um exemplo do pedido.
POST https://api.securitycenter.microsoft.com/api/alerts/CreateAlertByReference
{
"machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
"severity": "Low",
"title": "example",
"description": "example alert",
"recommendedAction": "nothing",
"eventTime": "2018-08-03T16:45:21.7115183Z",
"reportId": "20776",
"category": "Exploit"
}
Dica
Você deseja aprender mais? Contacte a comunidade de Segurança da Microsoft na nossa Comunidade Tecnológica: Microsoft Defender para Endpoint Tech Community.