External Attack Surface API

Karbantartja: Aether365 Team Célközönség: fejlesztők Hatókör: External Attack Surface (EAS) végpontok - eredmények, vizsgálati célpontok, domain-ellenőrzés és igény szerinti vizsgálatok

Az External Attack Surface API a Microsoft 365 domainjeid kívülről befelé mutató helyzetét olvassa be (TLS, DNS-biztonság és kitett végpontok), kezeli, hogy mely hostok kerülnek vizsgálatra, és igény szerinti vizsgálatokat indít. Minden végpont a bearer tokenből származó bérlőre korlátozódik. Az igény szerinti vizsgálathoz fizetős csomag szükséges.

Attack Surface eredmények lekérdezése

A legutóbbi attack surface vizsgálatot adja vissza, ssl, dns és endpoints szakaszokra csoportosítva, valamint a nyitott problémák súlyosság szerinti darabszámait és az aktuális vizsgálati célpontokat.

GET /tenants/me/attack-surface

Példa kérés

curl https://api.aether365.io/tenants/me/attack-surface \
  -H "Authorization: Bearer <token>"

Példa válasz

{
  "success": true,
  "data": {
    "latestScan": {
      "id": "scan_abc123",
      "status": "completed",
      "completedAt": "2026-06-29T08:00:00Z",
      "passCount": 18,
      "failCount": 6
    },
    "severityCounts": { "Critical": 1, "High": 2, "Medium": 3, "Low": 0 },
    "sections": {
      "ssl": [
        {
          "testId": "EAS.TLS.001",
          "title": "Certificate is valid and not expiring soon",
          "result": "Passed",
          "severity": "High",
          "target": "contoso.com",
          "helpUrl": "https://docs.aether365.io/checks/...",
          "remediation": "..."
        }
      ],
      "dns": [],
      "endpoints": []
    },
    "targets": [
      {
        "id": "tgt_abc123",
        "host": "contoso.com",
        "source": "user",
        "excluded": false,
        "verificationStatus": "verified",
        "verifiedAt": "2026-06-28T12:00:00Z",
        "createdAt": "2026-06-28T11:00:00Z"
      }
    ]
  }
}

Minden észlelés target mezője az a host, amelyre vonatkozik; a host nélküli észlelések bérlőszintű ellenőrzések. Csoportosíts target szerint a domainenkénti nézethez.

---

Vizsgálati célpontok listázása

A bérlő összes vizsgálati célpontját visszaadja: az automatikusan felfedezett Microsoft 365 domaineket és az általad hozzáadott egyedi domaineket.

GET /tenants/me/attack-surface/targets

Egy függőben lévő egyedi célpont egy verificationRecord értéket is visszaad (a közzéteendő DNS TXT értéket).

---

Egyedi célpont hozzáadása

Egyedi domaint ad hozzá. pending állapotban indul, és nem kerül vizsgálatra, amíg nincs ellenőrizve.

POST /tenants/me/attack-surface/targets

Kéréstörzs

{ "host": "contoso.com" }

Mező	Típus	Kötelező	Megjegyzések
host	string	Igen	Csupasz domainnév (séma, port vagy útvonal nélkül)

Példa válasz

{
  "success": true,
  "data": {
    "id": "tgt_new123",
    "host": "contoso.com",
    "source": "user",
    "excluded": false,
    "verificationStatus": "pending",
    "verificationRecord": "aether365-site-verification=ab12cd34..."
  }
}

Hibák

Kód	HTTP	Leírás
VALIDATION_ERROR	400	A host nem csupasz domainnév
VALIDATION_ERROR	409	A célpont már létezik

---

Egyedi célpont ellenőrzése

A domain tulajdonjogát erősíti meg a közzétett TXT rekord lekérdezésével. Sikeres esetben a célpont verified állapotúvá válik, és bekerül a következő vizsgálatba.

POST /tenants/me/attack-surface/targets/{targetId}/verify

Tegyél közzé egy DNS TXT rekordot a domain apex szintjén a verificationRecord értékeként visszaadott értékkel (például aether365-site-verification=ab12cd34...), majd hívd meg ezt a végpontot.

Hibák

Kód	HTTP	Leírás
EAS_TXT_NOT_FOUND	400	A várt TXT rekord még nem található a DNS-ben

---

Célpont kizárása vagy felvétele

Be- vagy kikapcsolja, hogy egy célpont vizsgálatra kerüljön-e. Az automatikusan felfedezett célpontokat nem lehet törölni, csak kizárni.

PATCH /tenants/me/attack-surface/targets/{targetId}

Kéréstörzs

{ "excluded": true }

---

Egyedi célpont törlése

Eltávolít egy egyedi (felhasználó által hozzáadott) célpontot. Az automatikusan felfedezett célpontok 400 hibát adnak, és csak kizárni lehet őket.

DELETE /tenants/me/attack-surface/targets/{targetId}

---

Attack Surface vizsgálat indítása

Igény szerinti attack surface vizsgálatot indít. Fizetős csomag szükséges hozzá.

POST /tenants/me/attack-surface/scan

Kéréstörzs

{ "connectionId": "conn_abc123" }

Mező	Típus	Kötelező	Megjegyzések
connectionId	string	Nem	A vizsgálandó csatlakoztatott Microsoft bérlő; hagyd el az elsődlegeshez

Hibák

Kód	HTTP	Leírás
AUTH_FORBIDDEN	403	A csomag nem tartalmazza az External Attack Surface-t
TENANT_NOT_CONNECTED	400	Nincs csatlakoztatott Microsoft bérlő
SCAN_ALREADY_RUNNING	409	Már folyamatban van egy attack surface vizsgálat
SERVICE_UNAVAILABLE	503	Az attack surface szkenner még nem érhető el