External Attack Surface API

Betreut von: Aether365 Team Zielgruppe: Entwickler Umfang: External Attack Surface (EAS) Endpunkte - Ergebnisse, Scan-Ziele, Domain-Verifizierung und On-Demand-Scans

Die External Attack Surface API liest die Außenansicht Ihrer Microsoft 365-Domains aus (TLS, DNS-Sicherheit und exponierte Endpunkte), verwaltet, welche Hosts gescannt werden, und löst On-Demand-Scans aus. Alle Endpunkte sind über das Bearer-Token auf den jeweiligen Tenant beschränkt. Der On-Demand-Scan setzt einen kostenpflichtigen Tarif voraus.

Attack-Surface-Ergebnisse abrufen

Gibt den neuesten Attack-Surface-Scan zurück, gruppiert in die Abschnitte ssl, dns und endpoints, dazu die Anzahl offener Probleme nach Schweregrad sowie die aktuellen Scan-Ziele.

GET /tenants/me/attack-surface

Beispielanfrage

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

Beispielantwort

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

Das target jedes Befunds ist der Host, auf den er sich bezieht; Befunde ohne Host sind tenant-weite Prüfungen. Gruppieren Sie nach target, um eine Ansicht pro Domain zu erhalten.

---

Scan-Ziele auflisten

Gibt alle Scan-Ziele des Tenants zurück: automatisch erkannte Microsoft 365-Domains und von Ihnen hinzugefügte benutzerdefinierte Domains.

GET /tenants/me/attack-surface/targets

Ein ausstehendes benutzerdefiniertes Ziel gibt zusätzlich einen verificationRecord zurück (den zu veröffentlichenden DNS-TXT-Wert).

---

Benutzerdefiniertes Ziel hinzufügen

Fügt eine benutzerdefinierte Domain hinzu. Sie beginnt im Status pending und wird erst gescannt, sobald sie verifiziert ist.

POST /tenants/me/attack-surface/targets

Anfragekörper

{ "host": "contoso.com" }

Feld	Typ	Erforderlich	Hinweise
host	string	Ja	Ein reiner Domainname (ohne Schema, Port oder Pfad)

Beispielantwort

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

Fehler

Code	HTTP	Beschreibung
VALIDATION_ERROR	400	host ist kein reiner Domainname
VALIDATION_ERROR	409	Das Ziel existiert bereits

---

Benutzerdefiniertes Ziel verifizieren

Bestätigt den Domain-Besitz durch Abruf des veröffentlichten TXT-Eintrags. Bei Erfolg wechselt das Ziel in den Status verified und wird in den nächsten Scan einbezogen.

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

Veröffentlichen Sie einen DNS-TXT-Eintrag auf dem Domain-Apex mit dem als verificationRecord zurückgegebenen Wert (zum Beispiel aether365-site-verification=ab12cd34...) und rufen Sie anschließend diesen Endpunkt auf.

Fehler

Code	HTTP	Beschreibung
EAS_TXT_NOT_FOUND	400	Der erwartete TXT-Eintrag wurde im DNS noch nicht gefunden

---

Ziel aus- oder einschließen

Schaltet um, ob ein Ziel gescannt wird. Automatisch erkannte Ziele können nicht gelöscht, sondern nur ausgeschlossen werden.

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

Anfragekörper

{ "excluded": true }

---

Benutzerdefiniertes Ziel löschen

Entfernt ein benutzerdefiniertes (selbst hinzugefügtes) Ziel. Automatisch erkannte Ziele geben 400 zurück und können nur ausgeschlossen werden.

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

---

Attack-Surface-Scan auslösen

Startet einen On-Demand-Attack-Surface-Scan. Setzt einen kostenpflichtigen Tarif voraus.

POST /tenants/me/attack-surface/scan

Anfragekörper

{ "connectionId": "conn_abc123" }

Feld	Typ	Erforderlich	Hinweise
connectionId	string	Nein	Zu scannender verbundener Microsoft-Tenant; weglassen für den primären

Fehler

Code	HTTP	Beschreibung
AUTH_FORBIDDEN	403	Der Tarif beinhaltet kein External Attack Surface
TENANT_NOT_CONNECTED	400	Kein verbundener Microsoft-Tenant
SCAN_ALREADY_RUNNING	409	Ein Attack-Surface-Scan läuft bereits
SERVICE_UNAVAILABLE	503	Der Attack-Surface-Scanner ist noch nicht verfügbar