Threat Alerts API

Maintainer: Aether365 Team Destinatari: Sviluppatori Ambito: Segnali di rischio sull'identità e contenimento con un clic

Threat Alerts mette in evidenza i segnali di rischio sull'identità attivi di un tenant connesso - utenti a rischio, rilevamenti di rischio e avvisi di sicurezza - letti in tempo reale da Microsoft Graph. Puoi anche contenere un utente a rischio (revocare le sessioni e disabilitare l'account) in una sola chiamata.

Requisiti

Le letture di Threat Alerts richiedono l'abilitazione Threat Alerts e una connessione Microsoft 365 in modalità AI Pilot (i segnali di rischio provengono dall'app AI Pilot Graph). Il contenimento richiede inoltre l'abilitazione breach response. Senza una connessione AI Pilot, l'endpoint di lettura restituisce { "aiPilotConnected": false }.

Ottenere i segnali di minaccia

Restituisce i segnali di rischio sull'identità più recenti. Ogni sorgente viene recuperata in modo indipendente, così che una singola autorizzazione mancante o una funzionalità priva di licenza non comprometta mai l'intera risposta: quella sorgente restituisce un risultato vuoto con uno stato in sources.

GET /tenants/me/threats

Parametri di query

Parametro	Tipo	Descrizione
connectionId	string	Opzionale. Connessione AI Pilot da leggere; di default la più vecchia

Esempio di risposta

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

Valori di stato delle sorgenti

Stato	Significato
ok	Segnali restituiti con successo
needsConsent	Manca un'autorizzazione di Graph - concedi nuovamente il consent per abilitare questa sorgente
notLicensed	Il tenant non dispone della funzionalità (es. Entra ID P2 / Defender) - il consent non aiuta
error	Un errore imprevisto nel recupero di questa sorgente

---

Contenere un utente a rischio

Revoca le sessioni di accesso attive dell'utente e disabilita l'account. Si tratta di una scrittura distruttiva su Microsoft Graph tramite la connessione AI Pilot; le due scritture sono indipendenti, così che un errore parziale viene segnalato anziché annullato silenziosamente.

POST /tenants/me/threats/contain

Corpo della richiesta

Campo	Tipo	Descrizione
userId	string	L'utente Microsoft 365 (object id o UPN) da contenere
connectionId	string	Opzionale. Connessione AI Pilot tramite cui agire

Esempio di richiesta

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

Esempio di risposta

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

needsReconsent è true quando una scrittura è stata rifiutata perché il write-consent è assente o scaduto; concedi nuovamente il consent e riprova.