External Attack Surface -API

Ylläpitäjä: Aether365-tiimi Kohderyhmä: Kehittäjät Laajuus: External Attack Surface (EAS) -päätepisteet - tulokset, skannauskohteet, verkkotunnuksen vahvistus ja pyynnöstä tehtävät skannaukset

External Attack Surface -API lukee Microsoft 365 -verkkotunnustesi ulkoa sisäänpäin nähtävän tilan (TLS, DNS-turvallisuus ja altistuneet päätepisteet), hallinnoi sitä mitkä isännät skannataan ja käynnistää pyynnöstä tehtäviä skannauksia. Kaikki päätepisteet on rajattu vuokralaiseen bearer-tokenin perusteella. Pyynnöstä tehtävä skannaus edellyttää maksullista tilausta.

Hae hyökkäyspinnan tulokset

Palauttaa uusimman hyökkäyspinnan skannauksen ryhmiteltynä ssl-, dns- ja endpoints-osioihin sekä avoimet havainnot vakavuuden mukaan ja nykyiset skannauskohteet.

GET /tenants/me/attack-surface

Esimerkkipyyntö

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

Esimerkkivastaus

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

Kunkin havainnon target on isäntä, johon se kohdistuu; ilman isäntää olevat havainnot ovat koko vuokralaista koskevia tarkistuksia. Ryhmittele target-kentän mukaan saadaksesi verkkotunnuskohtaisen näkymän.

---

Listaa skannauskohteet

Palauttaa vuokralaisen kaikki skannauskohteet: automaattisesti tunnistetut Microsoft 365 -verkkotunnukset ja lisäämäsi mukautetut verkkotunnukset.

GET /tenants/me/attack-surface/targets

Odottava mukautettu kohde palauttaa myös verificationRecord-arvon (julkaistavan DNS TXT -arvon).

---

Lisää mukautettu kohde

Lisää mukautetun verkkotunnuksen. Se alkaa tilassa pending eikä sitä skannata ennen kuin se on vahvistettu.

POST /tenants/me/attack-surface/targets

Pyynnön runko

{ "host": "contoso.com" }

Kenttä	Tyyppi	Pakollinen	Huomautukset
host	string	Kyllä	Pelkkä verkkotunnus (ei skeemaa, porttia tai polkua)

Esimerkkivastaus

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

Virheet

Koodi	HTTP	Kuvaus
VALIDATION_ERROR	400	host ei ole pelkkä verkkotunnus
VALIDATION_ERROR	409	Kohde on jo olemassa

---

Vahvista mukautettu kohde

Vahvistaa verkkotunnuksen omistajuuden hakemalla julkaistun TXT-tietueen. Onnistuessaan kohde siirtyy tilaan verified ja sisällytetään seuraavaan skannaukseen.

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

Julkaise verkkotunnuksen juuressa DNS TXT -tietue, jonka arvo on verificationRecord-kentässä palautettu (esimerkiksi aether365-site-verification=ab12cd34...), ja kutsu sitten tätä päätepistettä.

Virheet

Koodi	HTTP	Kuvaus
EAS_TXT_NOT_FOUND	400	Odotettua TXT-tietuetta ei vielä löytynyt DNS:stä

---

Sulje kohde pois tai sisällytä se

Vaihtaa, skannataanko kohde. Automaattisesti tunnistettuja kohteita ei voi poistaa, vaan ne voi vain sulkea pois.

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

Pyynnön runko

{ "excluded": true }

---

Poista mukautettu kohde

Poistaa mukautetun (käyttäjän lisäämän) kohteen. Automaattisesti tunnistetut kohteet palauttavat 400 ja ne voi vain sulkea pois.

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

---

Käynnistä hyökkäyspinnan skannaus

Käynnistää pyynnöstä tehtävän hyökkäyspinnan skannauksen. Edellyttää maksullista tilausta.

POST /tenants/me/attack-surface/scan

Pyynnön runko

{ "connectionId": "conn_abc123" }

Kenttä	Tyyppi	Pakollinen	Huomautukset
connectionId	string	Ei	Skannattava yhdistetty Microsoft-vuokralainen; jätä pois ensisijaiselle

Virheet

Koodi	HTTP	Kuvaus
AUTH_FORBIDDEN	403	Tilaus ei sisällä External Attack Surface -toimintoa
TENANT_NOT_CONNECTED	400	Ei yhdistettyä Microsoft-vuokralaista
SCAN_ALREADY_RUNNING	409	Hyökkäyspinnan skannaus on jo käynnissä
SERVICE_UNAVAILABLE	503	Hyökkäyspinnan skanneri ei ole vielä käytettävissä