API de Threat Alerts

Mantido por: Aether365 Team Público-alvo: Programadores Âmbito: Sinais de risco de identidade e contenção com um clique

O Threat Alerts apresenta os sinais de risco de identidade ativos de um tenant ligado - utilizadores em risco, deteções de risco e alertas de segurança - lidos em tempo real do Microsoft Graph. Pode também conter um utilizador em risco (revogar sessões e desativar a conta) numa única chamada.

Requisitos

As leituras do Threat Alerts requerem o direito de utilização Threat Alerts e uma ligação Microsoft 365 em modo AI Pilot (os sinais de risco vêm da aplicação Graph do AI Pilot). A contenção requer adicionalmente o direito de utilização breach response. Sem uma ligação AI Pilot, o endpoint de leitura devolve { "aiPilotConnected": false }.

Obter Sinais de Ameaça

Devolve os sinais de risco de identidade mais recentes. Cada fonte é obtida de forma independente, por isso uma única permissão em falta ou funcionalidade sem licença nunca afunda a resposta inteira: essa fonte devolve vazio com um estado em sources.

GET /tenants/me/threats

Parâmetros de Consulta

Parâmetro	Tipo	Descrição
connectionId	string	Opcional. Ligação AI Pilot a ler; por omissão, usa a mais antiga

Exemplo de Resposta

{
  "success": true,
  "data": {
    "aiPilotConnected": true,
    "msTenantId": "00000000-0000-0000-0000-000000000000",
    "riskyUsers": [{ "id": "...", "userPrincipalName": "user@contoso.com", "riskLevel": "high" }],
    "riskDetections": [],
    "securityAlerts": [],
    "sources": {
      "riskyUsers": "ok",
      "riskDetections": "ok",
      "securityAlerts": "notLicensed"
    }
  }
}

Valores de estado da fonte

Estado	Significado
ok	Sinais devolvidos com sucesso
needsConsent	Falta uma permissão do Graph - reconceda o consentimento para ativar esta fonte
notLicensed	O tenant não tem a capacidade (por exemplo, Entra ID P2 / Defender) - o consentimento não ajuda
error	Erro inesperado ao obter esta fonte

---

Conter um Utilizador em Risco

Revoga as sessões de início de sessão ativas do utilizador e desativa a conta. Esta é uma escrita destrutiva no Microsoft Graph através da ligação do AI Pilot; as duas escritas são independentes, por isso uma falha parcial é reportada em vez de revertida silenciosamente.

POST /tenants/me/threats/contain

Corpo do Pedido

Campo	Tipo	Descrição
userId	string	O utilizador Microsoft 365 (object id ou UPN) a conter
connectionId	string	Opcional. Ligação AI Pilot através da qual atuar

Exemplo de Pedido

curl -X POST https://api.aether365.io/tenants/me/threats/contain \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "userId": "user@contoso.com" }'

Exemplo de Resposta

{
  "success": true,
  "data": {
    "userId": "user@contoso.com",
    "connectionId": "conn_abc123",
    "disabled": true,
    "sessionsRevoked": true,
    "needsReconsent": false
  }
}

needsReconsent é true quando uma escrita foi rejeitada porque o write consent está em falta ou expirou; reconceda o consentimento e tente novamente.