External Attack Surface API

Autorius: Aether365 komanda Auditorija: Kūrėjai Apimtis: External Attack Surface (EAS) galutiniai taškai - rezultatai, nuskaitymo taikiniai, domeno patvirtinimas ir nuskaitymai pagal poreikį

External Attack Surface API skaito jūsų Microsoft 365 domenų išorinę būklę (TLS, DNS saugumą ir atskleistus galutinius taškus), tvarko, kurie serveriai nuskaitomi, ir inicijuoja nuskaitymus pagal poreikį. Visi galutiniai taškai apriboti organizacija pagal bearer tokeną. Nuskaitymui pagal poreikį reikalingas mokamas planas.

Atakos paviršiaus rezultatų gavimas

Grąžina naujausią atakos paviršiaus nuskaitymą, suskirstytą į ssl, dns ir endpoints skiltis, taip pat atvirų problemų skaičių pagal rimtumą ir esamus nuskaitymo taikinius.

GET /tenants/me/attack-surface

Užklausos pavyzdys

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

Atsakymo pavyzdys

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

Kiekvieno radinio target yra serveris, kuriam jis taikomas; radiniai be serverio yra visai organizacijai taikomi patikrinimai. Sugrupuokite pagal target, kad gautumėte kiekvieno domeno vaizdą.

---

Nuskaitymo taikinių sąrašas

Grąžina visus organizacijos nuskaitymo taikinius: automatiškai aptiktus Microsoft 365 domenus ir jūsų pridėtus pasirinktinius domenus.

GET /tenants/me/attack-surface/targets

Laukiantis pasirinktinis taikinys taip pat grąžina verificationRecord (DNS TXT reikšmę, kurią reikia paskelbti).

---

Pasirinktinio taikinio pridėjimas

Prideda pasirinktinį domeną. Jis pradedamas pending būsenoje ir nenuskaitomas, kol nepatvirtinamas.

POST /tenants/me/attack-surface/targets

Užklausos turinys

{ "host": "contoso.com" }

Laukas	Tipas	Būtinas	Pastabos
host	string	Taip	Grynas domeno vardas (be schemos, prievado ar kelio)

Atsakymo pavyzdys

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

Klaidos

Kodas	HTTP	Aprašymas
VALIDATION_ERROR	400	host nėra grynas domeno vardas
VALIDATION_ERROR	409	Taikinys jau egzistuoja

---

Pasirinktinio taikinio patvirtinimas

Patvirtina domeno nuosavybę ieškodamas paskelbto TXT įrašo. Sėkmės atveju taikinys tampa verified ir įtraukiamas į kitą nuskaitymą.

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

Paskelbkite DNS TXT įrašą domeno viršūnėje (apex) su reikšme, grąžinta kaip verificationRecord (pavyzdžiui aether365-site-verification=ab12cd34...), tada iškvieskite šį galutinį tašką.

Klaidos

Kodas	HTTP	Aprašymas
EAS_TXT_NOT_FOUND	400	Laukiamas TXT įrašas dar nerastas DNS sistemoje

---

Taikinio išskyrimas arba įtraukimas

Perjungia, ar taikinys nuskaitomas. Automatiškai aptiktų taikinių ištrinti negalima, tik išskirti.

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

Užklausos turinys

{ "excluded": true }

---

Pasirinktinio taikinio ištrynimas

Pašalina pasirinktinį (naudotojo pridėtą) taikinį. Automatiškai aptikti taikiniai grąžina 400 ir gali būti tik išskirti.

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

---

Atakos paviršiaus nuskaitymo inicijavimas

Pradeda atakos paviršiaus nuskaitymą pagal poreikį. Reikalingas mokamas planas.

POST /tenants/me/attack-surface/scan

Užklausos turinys

{ "connectionId": "conn_abc123" }

Laukas	Tipas	Būtinas	Pastabos
connectionId	string	Ne	Prijungta Microsoft organizacija, kurią nuskaityti; praleiskite pagrindinei

Klaidos

Kodas	HTTP	Aprašymas
AUTH_FORBIDDEN	403	Planas neapima External Attack Surface
TENANT_NOT_CONNECTED	400	Nėra prijungtos Microsoft organizacijos
SCAN_ALREADY_RUNNING	409	Atakos paviršiaus nuskaitymas jau vykdomas
SERVICE_UNAVAILABLE	503	Atakos paviršiaus skaitytuvas dar neprieinamas