Threat Alerts API

Maintained by: Zespół Aether365 Audience: Programiści Scope: Sygnały ryzyka tożsamości i powstrzymanie zagrożenia jednym kliknięciem

Threat Alerts pokazuje aktywne sygnały ryzyka tożsamości połączonego najemcy: ryzykownych użytkowników, wykrycia ryzyka oraz alerty bezpieczeństwa, odczytywane na żywo z Microsoft Graph. Możesz też powstrzymać ryzykownego użytkownika (unieważnić sesje i wyłączyć konto) jednym wywołaniem.

Wymagania

Odczyty Threat Alerts wymagają uprawnienia Threat Alerts oraz połączenia Microsoft 365 w trybie AI Pilot (sygnały ryzyka pochodzą z aplikacji Graph AI Pilot). Powstrzymanie zagrożenia dodatkowo wymaga uprawnienia breach response. Bez połączenia AI Pilot punkt końcowy odczytu zwraca { "aiPilotConnected": false }.

Pobierz sygnały zagrożeń

Zwraca najnowsze sygnały ryzyka tożsamości. Każde źródło jest pobierane niezależnie, więc pojedyncze brakujące uprawnienie lub nielicencjonowana funkcja nigdy nie pogrąża całej odpowiedzi: takie źródło zwraca pusty wynik wraz ze statusem w polu sources.

GET /tenants/me/threats

Parametry zapytania

Parametr	Typ	Opis
connectionId	string	Opcjonalny. Połączenie AI Pilot do odczytu; domyślnie najstarsze

Przykładowa odpowiedź

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

Wartości statusu źródła

Status	Znaczenie
ok	Sygnały zwrócone pomyślnie
needsConsent	Brakuje uprawnienia Graph - przyznaj zgodę ponownie, aby włączyć to źródło
notLicensed	Najemca nie ma tej funkcji (np. Entra ID P2 / Defender) - zgoda nie pomoże
error	Nieoczekiwany błąd podczas pobierania tego źródła

---

Powstrzymaj ryzykownego użytkownika

Unieważnia aktywne sesje logowania użytkownika i wyłącza konto. To destrukcyjny zapis Microsoft Graph przez połączenie AI Pilot; oba zapisy są niezależne, więc częściowe niepowodzenie jest zgłaszane, a nie po cichu wycofywane.

POST /tenants/me/threats/contain

Treść żądania

Pole	Typ	Opis
userId	string	Użytkownik Microsoft 365 (object id lub UPN) do powstrzymania
connectionId	string	Opcjonalny. Połączenie AI Pilot, przez które działać

Przykładowe żądanie

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

Przykładowa odpowiedź

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

needsReconsent ma wartość true, gdy zapis został odrzucony, ponieważ brakuje zgody na zapis lub wygasła; przyznaj zgodę ponownie i spróbuj jeszcze raz.