External Attack Surface API

Onderhouden door: Aether365 Team Doelgroep: Ontwikkelaars Scope: External Attack Surface (EAS) endpoints - resultaten, scandoelen, domeinverificatie en scans op aanvraag

De External Attack Surface API leest de outside-in status van uw Microsoft 365-domeinen (TLS, DNS-beveiliging en blootgestelde endpoints), beheert welke hosts gescand worden en start scans op aanvraag. Alle endpoints zijn gekoppeld aan de tenant op basis van het bearer-token. De scan op aanvraag vereist een betaald abonnement.

Attack Surface-resultaten ophalen

Retourneert de laatste attack surface-scan, gegroepeerd in de secties ssl, dns en endpoints, plus het aantal openstaande issues per ernst en de huidige scandoelen.

GET /tenants/me/attack-surface

Voorbeeldverzoek

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

Voorbeeldresponse

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

De target van elke bevinding is de host waarop deze van toepassing is; bevindingen zonder host zijn tenantbrede controles. Groepeer op target voor een weergave per domein.

---

Scandoelen weergeven

Retourneert elk scandoel voor de tenant: automatisch ontdekte Microsoft 365-domeinen en aangepaste domeinen die u hebt toegevoegd.

GET /tenants/me/attack-surface/targets

Een aangepast doel met de status pending retourneert ook een verificationRecord (de DNS TXT-waarde die u moet publiceren).

---

Een aangepast doel toevoegen

Voegt een aangepast domein toe. Het start als pending en wordt pas gescand nadat het is geverifieerd.

POST /tenants/me/attack-surface/targets

Verzoekbody

{ "host": "contoso.com" }

Veld	Type	Vereist	Opmerkingen
host	string	Ja	Een kale domeinnaam (zonder schema, poort of pad)

Voorbeeldresponse

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

Fouten

Code	HTTP	Beschrijving
VALIDATION_ERROR	400	host is geen kale domeinnaam
VALIDATION_ERROR	409	Het doel bestaat al

---

Een aangepast doel verifiëren

Bevestigt het eigendom van het domein door het gepubliceerde TXT-record op te zoeken. Bij succes krijgt het doel de status verified en wordt het meegenomen in de volgende scan.

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

Publiceer een DNS TXT-record op de apex van het domein met de waarde die als verificationRecord werd geretourneerd (bijvoorbeeld aether365-site-verification=ab12cd34...) en roep daarna dit endpoint aan.

Fouten

Code	HTTP	Beschrijving
EAS_TXT_NOT_FOUND	400	Het verwachte TXT-record is nog niet gevonden in DNS

---

Een doel uitsluiten of opnemen

Schakelt in of uit of een doel wordt gescand. Automatisch ontdekte doelen kunnen niet worden verwijderd, alleen uitgesloten.

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

Verzoekbody

{ "excluded": true }

---

Een aangepast doel verwijderen

Verwijdert een aangepast (door de gebruiker toegevoegd) doel. Automatisch ontdekte doelen retourneren 400 en kunnen alleen worden uitgesloten.

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

---

Een Attack Surface-scan starten

Start een attack surface-scan op aanvraag. Vereist een betaald abonnement.

POST /tenants/me/attack-surface/scan

Verzoekbody

{ "connectionId": "conn_abc123" }

Veld	Type	Vereist	Opmerkingen
connectionId	string	Nee	Verbonden Microsoft-tenant om te scannen; laat weg voor de primaire

Fouten

Code	HTTP	Beschrijving
AUTH_FORBIDDEN	403	Abonnement bevat geen External Attack Surface
TENANT_NOT_CONNECTED	400	Geen verbonden Microsoft-tenant
SCAN_ALREADY_RUNNING	409	Er loopt al een attack surface-scan
SERVICE_UNAVAILABLE	503	De attack surface-scanner is nog niet beschikbaar