API зовнішньої поверхні атаки

Супровід: команда Aether365 Аудиторія: розробники Обсяг: endpoint'и зовнішньої поверхні атаки (EAS) - результати, цілі сканування, перевірка домену та сканування на вимогу

API зовнішньої поверхні атаки зчитує стан ваших доменів Microsoft 365 ззовні (TLS, безпека DNS та відкриті endpoint'и), керує тим, які хости скануються, і запускає сканування на вимогу. Усі endpoint'и обмежені tenant'ом за токеном bearer. Сканування на вимогу потребує платного плану.

Отримання результатів поверхні атаки

Повертає останнє сканування поверхні атаки, згруповане в розділи ssl, dns та endpoints, а також кількість відкритих проблем за критичністю та поточні цілі сканування.

GET /tenants/me/attack-surface

Приклад запиту

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

Приклад відповіді

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

Поле target кожної знахідки - це хост, до якого вона стосується; знахідки без хоста є перевірками рівня всього tenant'у. Згрупуйте за target, щоб отримати подоменний огляд.

---

Список цілей сканування

Повертає всі цілі сканування для tenant'у: автоматично виявлені домени Microsoft 365 та власні домени, які ви додали.

GET /tenants/me/attack-surface/targets

Незавершена власна ціль також повертає verificationRecord (значення DNS TXT, яке потрібно опублікувати).

---

Додавання власної цілі

Додає власний домен. Він починає зі статусу pending і не сканується, доки не буде перевірений.

POST /tenants/me/attack-surface/targets

Тіло запиту

{ "host": "contoso.com" }

Поле	Тип	Обов'язкове	Примітки
host	string	Так	Чисте доменне ім'я (без схеми, порту чи шляху)

Приклад відповіді

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

Помилки

Код	HTTP	Опис
VALIDATION_ERROR	400	host не є чистим доменним ім'ям
VALIDATION_ERROR	409	Ціль уже існує

---

Перевірка власної цілі

Підтверджує право власності на домен, шукаючи опублікований запис TXT. У разі успіху ціль стає verified і включається до наступного сканування.

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

Опублікуйте запис DNS TXT на apex домену зі значенням, поверненим як verificationRecord (наприклад, aether365-site-verification=ab12cd34...), а потім викличте цей endpoint.

Помилки

Код	HTTP	Опис
EAS_TXT_NOT_FOUND	400	Очікуваний запис TXT ще не знайдено в DNS

---

Виключення або включення цілі

Перемикає, чи сканується ціль. Автоматично виявлені цілі не можна видалити, лише виключити.

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

Тіло запиту

{ "excluded": true }

---

Видалення власної цілі

Видаляє власну (додану користувачем) ціль. Автоматично виявлені цілі повертають 400 і можуть бути лише виключені.

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

---

Запуск сканування поверхні атаки

Запускає сканування поверхні атаки на вимогу. Потребує платного плану.

POST /tenants/me/attack-surface/scan

Тіло запиту

{ "connectionId": "conn_abc123" }

Поле	Тип	Обов'язкове	Примітки
connectionId	string	Ні	Підключений tenant Microsoft для сканування; пропустіть для основного

Помилки

Код	HTTP	Опис
AUTH_FORBIDDEN	403	План не включає зовнішню поверхню атаки
TENANT_NOT_CONNECTED	400	Немає підключеного tenant'у Microsoft
SCAN_ALREADY_RUNNING	409	Сканування поверхні атаки вже виконується
SERVICE_UNAVAILABLE	503	Сканер поверхні атаки ще недоступний