External Attack Surface API

Uztur: Aether365 Team Mērķauditorija: Izstrādātāji Tvērums: External Attack Surface (EAS) galapunkti - rezultāti, skenēšanas mērķi, domēna verifikācija un skenēšanas pēc pieprasījuma

External Attack Surface API nolasa jūsu Microsoft 365 domēnu ārējo (no ārpuses uz iekšu) stāvokli (TLS, DNS drošība un atklātie galapunkti), pārvalda, kuri saimniekdatori tiek skenēti, un aktivizē skenēšanas pēc pieprasījuma. Visi galapunkti ir ierobežoti ar nomnieku, balstoties uz bearer tokenu. Skenēšanai pēc pieprasījuma nepieciešams maksas plāns.

Uzbrukuma virsmas rezultātu iegūšana

Atgriež jaunāko uzbrukuma virsmas skenēšanu, kas sagrupēta ssl, dns un endpoints sadaļās, kā arī atklāto problēmu skaitu pēc smaguma un pašreizējos skenēšanas mērķus.

GET /tenants/me/attack-surface

Pieprasījuma piemērs

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

Atbildes piemērs

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

Katra konstatējuma target ir saimniekdators, uz kuru tas attiecas; konstatējumi bez saimniekdatora ir visam nomniekam piemērojamas pārbaudes. Grupējiet pēc target, lai iegūtu skatu katram domēnam.

---

Skenēšanas mērķu saraksts

Atgriež visus nomnieka skenēšanas mērķus: automātiski atklātos Microsoft 365 domēnus un pievienotos pielāgotos domēnus.

GET /tenants/me/attack-surface/targets

Gaidošs pielāgotais mērķis atgriež arī verificationRecord (DNS TXT vērtību, kas jāpublicē).

---

Pielāgota mērķa pievienošana

Pievieno pielāgotu domēnu. Tas sākas kā pending un netiek skenēts, kamēr nav verificēts.

POST /tenants/me/attack-surface/targets

Pieprasījuma pamatteksts

{ "host": "contoso.com" }

Lauks	Tips	Obligāts	Piezīmes
host	string	Jā	Tīrs domēna nosaukums (bez shēmas, porta vai ceļa)

Atbildes piemērs

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

Kļūdas

Kods	HTTP	Apraksts
VALIDATION_ERROR	400	host nav tīrs domēna nosaukums
VALIDATION_ERROR	409	Mērķis jau eksistē

---

Pielāgota mērķa verificēšana

Apstiprina domēna īpašumtiesības, meklējot publicēto TXT ierakstu. Veiksmes gadījumā mērķis kļūst verified un tiek iekļauts nākamajā skenēšanā.

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

Publicējiet DNS TXT ierakstu domēna saknē (apex) ar vērtību, kas atgriezta kā verificationRecord (piemēram, aether365-site-verification=ab12cd34...), pēc tam izsauciet šo galapunktu.

Kļūdas

Kods	HTTP	Apraksts
EAS_TXT_NOT_FOUND	400	Gaidītais TXT ieraksts vēl nav atrasts DNS

---

Mērķa izslēgšana vai iekļaušana

Pārslēdz, vai mērķis tiek skenēts. Automātiski atklātos mērķus nevar dzēst, tikai izslēgt.

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

Pieprasījuma pamatteksts

{ "excluded": true }

---

Pielāgota mērķa dzēšana

Noņem pielāgotu (lietotāja pievienotu) mērķi. Automātiski atklātie mērķi atgriež 400, un tos var tikai izslēgt.

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

---

Uzbrukuma virsmas skenēšanas aktivizēšana

Sāk uzbrukuma virsmas skenēšanu pēc pieprasījuma. Nepieciešams maksas plāns.

POST /tenants/me/attack-surface/scan

Pieprasījuma pamatteksts

{ "connectionId": "conn_abc123" }

Lauks	Tips	Obligāts	Piezīmes
connectionId	string	Nē	Savienotais Microsoft nomnieks, ko skenēt; izlaidiet primārajam

Kļūdas

Kods	HTTP	Apraksts
AUTH_FORBIDDEN	403	Plāns neietver External Attack Surface
TENANT_NOT_CONNECTED	400	Nav savienota Microsoft nomnieka
SCAN_ALREADY_RUNNING	409	Uzbrukuma virsmas skenēšana jau notiek
SERVICE_UNAVAILABLE	503	Uzbrukuma virsmas skeneris vēl nav pieejams