API за External Attack Surface

Поддържа се от: Aether365 Team Аудитория: разработчици Обхват: крайни точки за External Attack Surface (EAS) - резултати, цели за сканиране, проверка на домейни и сканирания при поискване

API за External Attack Surface чете състоянието на вашите Microsoft 365 домейни отвън навътре (TLS, сигурност на DNS и изложени крайни точки), управлява кои хостове се сканират и стартира сканирания при поискване. Всички крайни точки са ограничени до tenant според bearer токена. Сканирането при поискване изисква платен план.

Получаване на резултати от Attack Surface

Връща последното сканиране на attack surface, групирано в секциите 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 запис на апекса на домейна със стойността, върната като verificationRecord (например aether365-site-verification=ab12cd34...), след което извикайте тази крайна точка.

Грешки

Код	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}

---

Стартиране на сканиране на Attack Surface

Стартира сканиране на attack surface при поискване. Изисква платен план.

POST /tenants/me/attack-surface/scan

Тяло на заявката

{ "connectionId": "conn_abc123" }

Поле	Тип	Задължително	Бележки
connectionId	string	Не	Свързан Microsoft tenant за сканиране; пропуснете за основния

Грешки

Код	HTTP	Описание
AUTH_FORBIDDEN	403	Планът не включва External Attack Surface
TENANT_NOT_CONNECTED	400	Няма свързан Microsoft tenant
SCAN_ALREADY_RUNNING	409	Сканиране на attack surface вече е в ход
SERVICE_UNAVAILABLE	503	Скенерът за attack surface още не е наличен