External Attack Surface API

Haldab: Aether365 Team Sihtrühm: arendajad Ulatus: External Attack Surface (EAS) lõpp-punktid - tulemused, skaneerimissihtmärgid, domeeni kinnitamine ja tellitavad skaneerimised

External Attack Surface API loeb teie Microsoft 365 domeenide väljastpoolt nähtavat hoiakut (TLS, DNS-i turvalisus ja avatud lõpp-punktid), haldab, milliseid hoste skaneeritakse, ja käivitab tellitavaid skaneerimisi. Kõik lõpp-punktid on bearer-tokeni põhjal halduskeskkonnaga piiratud. Tellitav skaneerimine nõuab tasulist plaani.

Rünnakupinna tulemuste kättesaamine

Tagastab viimase rünnakupinna skaneerimise, mis on jaotatud ssl, dns ja endpoints jaotisteks, koos tõsiduse järgi rühmitatud avatud probleemide arvuga ja praeguste skaneerimissihtmärkidega.

GET /tenants/me/attack-surface

Näidispäring

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

Näidisvastus

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

Iga leiu target on host, mille kohta see kehtib; ilma hostita leiud on kogu halduskeskkonda hõlmavad kontrollid. Rühmitage target järgi, et saada domeenipõhine vaade.

---

Skaneerimissihtmärkide loetelu

Tagastab kõik halduskeskkonna skaneerimissihtmärgid: automaatselt avastatud Microsoft 365 domeenid ja teie lisatud kohandatud domeenid.

GET /tenants/me/attack-surface/targets

Ootel kohandatud sihtmärk tagastab ka verificationRecord välja (avaldatav DNS TXT väärtus).

---

Kohandatud sihtmärgi lisamine

Lisab kohandatud domeeni. See algab olekus pending ja seda ei skaneerita enne kinnitamist.

POST /tenants/me/attack-surface/targets

Päringu keha

{ "host": "contoso.com" }

Väli	Tüüp	Nõutav	Märkused
host	string	Jah	Paljas domeeninimi (ilma skeemi, pordi või teeta)

Näidisvastus

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

Vead

Kood	HTTP	Kirjeldus
VALIDATION_ERROR	400	host ei ole paljas domeeninimi
VALIDATION_ERROR	409	Sihtmärk on juba olemas

---

Kohandatud sihtmärgi kinnitamine

Kinnitab domeeni omandiõiguse, otsides avaldatud TXT kirjet. Õnnestumisel muutub sihtmärk olekusse verified ja kaasatakse järgmisesse skaneerimisse.

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

Avaldage domeeni tipus (apex) DNS TXT kirje väärtusega, mis tagastati väljal verificationRecord (näiteks aether365-site-verification=ab12cd34...), seejärel kutsuge see lõpp-punkt välja.

Vead

Kood	HTTP	Kirjeldus
EAS_TXT_NOT_FOUND	400	Oodatud TXT kirjet ei leitud veel DNS-ist

---

Sihtmärgi väljaarvamine või kaasamine

Lülitab, kas sihtmärki skaneeritakse. Automaatselt avastatud sihtmärke ei saa kustutada, ainult välja arvata.

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

Päringu keha

{ "excluded": true }

---

Kohandatud sihtmärgi kustutamine

Eemaldab kohandatud (kasutaja lisatud) sihtmärgi. Automaatselt avastatud sihtmärgid tagastavad 400 ja neid saab ainult välja arvata.

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

---

Rünnakupinna skaneerimise käivitamine

Käivitab tellitava rünnakupinna skaneerimise. Nõuab tasulist plaani.

POST /tenants/me/attack-surface/scan

Päringu keha

{ "connectionId": "conn_abc123" }

Väli	Tüüp	Nõutav	Märkused
connectionId	string	Ei	Skaneeritav ühendatud Microsofti halduskeskkond; esmase puhul jätke välja

Vead

Kood	HTTP	Kirjeldus
AUTH_FORBIDDEN	403	Plaan ei sisalda External Attack Surface
TENANT_NOT_CONNECTED	400	Ühendatud Microsofti halduskeskkonda pole
SCAN_ALREADY_RUNNING	409	Rünnakupinna skaneerimine on juba käimas
SERVICE_UNAVAILABLE	503	Rünnakupinna skanner pole veel saadaval