API externého útočného povrchu

Spravuje: Aether365 Team Cieľová skupina: vývojári Rozsah: koncové body externého útočného povrchu (EAS) - výsledky, ciele skenovania, overovanie domén a skeny na požiadanie

API externého útočného povrchu číta vonkajší pohľad na stav vašich domén Microsoft 365 (TLS, zabezpečenie DNS a vystavené koncové body), spravuje, ktoré hostiteľské servery sa skenujú, a spúšťa skeny na požiadanie. Všetky koncové body sú obmedzené na tenanta podľa bearer tokenu. Sken na požiadanie vyžaduje platený plán.

Získanie výsledkov útočného povrchu

Vráti najnovší sken útočného povrchu rozdelený do sekcií ssl, dns a endpoints, spolu s počtami otvorených problémov podľa závažnosti a aktuálnymi cieľmi skenovania.

GET /tenants/me/attack-surface

Príklad požiadavky

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

Príklad odpovede

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

Pole target každého nálezu predstavuje hostiteľský server, ktorého sa týka; nálezy bez hostiteľského servera sú kontroly platné pre celého tenanta. Zoskupením podľa target získate pohľad na jednotlivé domény.

---

Zoznam cieľov skenovania

Vráti každý cieľ skenovania tenanta: automaticky zistené domény Microsoft 365 a vlastné domény, ktoré ste pridali.

GET /tenants/me/attack-surface/targets

Čakajúci vlastný cieľ vráti aj verificationRecord (hodnotu DNS TXT, ktorú treba zverejniť).

---

Pridanie vlastného cieľa

Pridá vlastnú doménu. Začína v stave pending a neskenuje sa, kým nie je overená.

POST /tenants/me/attack-surface/targets

Telo požiadavky

{ "host": "contoso.com" }

Pole	Typ	Povinné	Poznámky
host	string	Áno	Holý názov domény (bez schémy, portu alebo cesty)

Príklad odpovede

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

Chyby

Kód	HTTP	Popis
VALIDATION_ERROR	400	host nie je holý názov domény
VALIDATION_ERROR	409	Cieľ už existuje

---

Overenie vlastného cieľa

Potvrdí vlastníctvo domény vyhľadaním zverejneného TXT záznamu. Po úspechu sa cieľ stane verified a zahrnie sa do nasledujúceho skenu.

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

Na apexe domény zverejnite DNS TXT záznam s hodnotou vrátenou ako verificationRecord (napríklad aether365-site-verification=ab12cd34...) a potom zavolajte tento koncový bod.

Chyby

Kód	HTTP	Popis
EAS_TXT_NOT_FOUND	400	Očakávaný TXT záznam sa v DNS zatiaľ nenašiel

---

Vylúčenie alebo zahrnutie cieľa

Prepína, či sa cieľ skenuje. Automaticky zistené ciele nemožno odstrániť, iba vylúčiť.

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

Telo požiadavky

{ "excluded": true }

---

Odstránenie vlastného cieľa

Odstráni vlastný cieľ pridaný používateľom. Automaticky zistené ciele vrátia 400 a možno ich iba vylúčiť.

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

---

Spustenie skenu útočného povrchu

Spustí sken útočného povrchu na požiadanie. Vyžaduje platený plán.

POST /tenants/me/attack-surface/scan

Telo požiadavky

{ "connectionId": "conn_abc123" }

Pole	Typ	Povinné	Poznámky
connectionId	string	Nie	Pripojený Microsoft tenant na skenovanie; vynechajte pre primárny

Chyby

Kód	HTTP	Popis
AUTH_FORBIDDEN	403	Plán nezahŕňa externý útočný povrch
TENANT_NOT_CONNECTED	400	Žiadny pripojený Microsoft tenant
SCAN_ALREADY_RUNNING	409	Sken útočného povrchu už prebieha
SERVICE_UNAVAILABLE	503	Skener útočného povrchu zatiaľ nie je k dispozícii