API External Attack Surface

Autor: Zespół Aether365 Odbiorcy: Deweloperzy Zakres: Endpointy External Attack Surface (EAS) - wyniki, cele skanowania, weryfikacja domeny oraz skany na żądanie

API External Attack Surface odczytuje stan Twoich domen Microsoft 365 widziany z zewnątrz (TLS, bezpieczeństwo DNS oraz odsłonięte endpointy), zarządza tym, które hosty są skanowane, i uruchamia skany na żądanie. Wszystkie endpointy są ograniczone do tenanta na podstawie tokena bearer. Skan na żądanie wymaga płatnego planu.

Pobieranie wyników Attack Surface

Zwraca najnowszy skan attack surface pogrupowany w sekcje ssl, dns i endpoints, wraz z liczbą otwartych problemów według poziomu istotności oraz bieżącymi celami skanowania.

GET /tenants/me/attack-surface

Przykładowe żądanie

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

Przykładowa odpowiedź

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

Pole target każdego wykrytego problemu wskazuje host, którego dotyczy; problemy bez hosta są kontrolami obejmującymi cały tenant. Grupuj według target, aby uzyskać widok dla poszczególnych domen.

---

Lista celów skanowania

Zwraca wszystkie cele skanowania tenanta: automatycznie wykryte domeny Microsoft 365 oraz dodane przez Ciebie domeny niestandardowe.

GET /tenants/me/attack-surface/targets

Oczekujący cel niestandardowy zwraca również verificationRecord (wartość rekordu DNS TXT do opublikowania).

---

Dodawanie celu niestandardowego

Dodaje domenę niestandardową. Otrzymuje status pending i nie jest skanowana, dopóki nie zostanie zweryfikowana.

POST /tenants/me/attack-surface/targets

Treść żądania

{ "host": "contoso.com" }

Pole	Typ	Wymagane	Uwagi
host	string	Tak	Sama nazwa domeny (bez schematu, portu ani ścieżki)

Przykładowa odpowiedź

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

Błędy

Kod	HTTP	Opis
VALIDATION_ERROR	400	host nie jest samą nazwą domeny
VALIDATION_ERROR	409	Cel już istnieje

---

Weryfikacja celu niestandardowego

Potwierdza własność domeny, sprawdzając opublikowany rekord TXT. Po pomyślnej weryfikacji cel otrzymuje status verified i zostaje uwzględniony w następnym skanie.

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

Opublikuj rekord DNS TXT w apeksie domeny z wartością zwróconą jako verificationRecord (na przykład aether365-site-verification=ab12cd34...), a następnie wywołaj ten endpoint.

Błędy

Kod	HTTP	Opis
EAS_TXT_NOT_FOUND	400	Oczekiwany rekord TXT nie został jeszcze znaleziony w DNS

---

Wykluczanie lub włączanie celu

Przełącza, czy cel jest skanowany. Automatycznie wykrytych celów nie można usunąć, można je jedynie wykluczyć.

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

Treść żądania

{ "excluded": true }

---

Usuwanie celu niestandardowego

Usuwa cel niestandardowy (dodany przez użytkownika). Automatycznie wykryte cele zwracają 400 i można je jedynie wykluczyć.

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

---

Uruchamianie skanu Attack Surface

Rozpoczyna skan attack surface na żądanie. Wymaga płatnego planu.

POST /tenants/me/attack-surface/scan

Treść żądania

{ "connectionId": "conn_abc123" }

Pole	Typ	Wymagane	Uwagi
connectionId	string	Nie	Połączony tenant Microsoft do przeskanowania; pomiń dla głównego

Błędy

Kod	HTTP	Opis
AUTH_FORBIDDEN	403	Plan nie obejmuje External Attack Surface
TENANT_NOT_CONNECTED	400	Brak połączonego tenanta Microsoft
SCAN_ALREADY_RUNNING	409	Skan attack surface jest już w trakcie realizacji
SERVICE_UNAVAILABLE	503	Skaner attack surface nie jest jeszcze dostępny