External Attack Surface API

Hazırlayan: Aether365 Ekibi Hedef Kitle: Geliştiriciler Kapsam: External Attack Surface (EAS) endpoint'leri - sonuçlar, tarama hedefleri, alan adı doğrulaması ve talep üzerine taramalar

External Attack Surface API, Microsoft 365 alan adlarınızın dışarıdan görünen durumunu (TLS, DNS güvenliği ve açıktaki endpoint'ler) okur, hangi sunucuların taranacağını yönetir ve talep üzerine taramalar tetikler. Tüm endpoint'ler bearer token'dan alınan tenant kapsamıyla sınırlıdır. Talep üzerine tarama için ücretli bir plan gerekir.

Attack Surface Sonuçlarını Alma

En son attack surface taramasını ssl, dns ve endpoints bölümlerine ayrılmış olarak, ayrıca önem derecesine göre açık sorun sayılarını ve mevcut tarama hedeflerini döndürür.

GET /tenants/me/attack-surface

Örnek İstek

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

Örnek Yanıt

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

Her bulgunun target değeri, ilgili olduğu sunucudur; sunucusu olmayan bulgular tenant genelindeki kontrollerdir. Alan adı bazında bir görünüm için target değerine göre gruplayın.

---

Tarama Hedeflerini Listeleme

Tenant'a ait her tarama hedefini döndürür: otomatik keşfedilen Microsoft 365 alan adları ve eklediğiniz özel alan adları.

GET /tenants/me/attack-surface/targets

Beklemede olan bir özel hedef, ayrıca bir verificationRecord (yayımlanacak DNS TXT değeri) döndürür.

---

Özel Hedef Ekleme

Bir özel alan adı ekler. pending durumunda başlar ve doğrulanana kadar taranmaz.

POST /tenants/me/attack-surface/targets

İstek Gövdesi

{ "host": "contoso.com" }

Alan	Tür	Gerekli	Notlar
host	string	Evet	Çıplak bir alan adı (şema, port veya yol olmadan)

Örnek Yanıt

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

Hatalar

Kod	HTTP	Açıklama
VALIDATION_ERROR	400	host çıplak bir alan adı değil
VALIDATION_ERROR	409	Hedef zaten mevcut

---

Özel Hedefi Doğrulama

Yayımlanan TXT kaydını arayarak alan adı sahipliğini doğrular. Başarılı olduğunda hedef verified durumuna geçer ve bir sonraki taramaya dahil edilir.

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

Alan adının kök (apex) kaydına, verificationRecord olarak döndürülen değerle bir DNS TXT kaydı yayımlayın (örneğin aether365-site-verification=ab12cd34...), ardından bu endpoint'i çağırın.

Hatalar

Kod	HTTP	Açıklama
EAS_TXT_NOT_FOUND	400	Beklenen TXT kaydı DNS'te henüz bulunamadı

---

Hedefi Hariç Tutma veya Dahil Etme

Bir hedefin taranıp taranmayacağını değiştirir. Otomatik keşfedilen hedefler silinemez, yalnızca hariç tutulabilir.

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

İstek Gövdesi

{ "excluded": true }

---

Özel Hedefi Silme

Özel (kullanıcı tarafından eklenen) bir hedefi kaldırır. Otomatik keşfedilen hedefler 400 döndürür ve yalnızca hariç tutulabilir.

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

---

Attack Surface Taraması Tetikleme

Talep üzerine bir attack surface taraması başlatır. Ücretli bir plan gerektirir.

POST /tenants/me/attack-surface/scan

İstek Gövdesi

{ "connectionId": "conn_abc123" }

Alan	Tür	Gerekli	Notlar
connectionId	string	Hayır	Taranacak bağlı Microsoft tenant'ı; birincil için boş bırakın

Hatalar

Kod	HTTP	Açıklama
AUTH_FORBIDDEN	403	Plan External Attack Surface'i içermiyor
TENANT_NOT_CONNECTED	400	Bağlı bir Microsoft tenant'ı yok
SCAN_ALREADY_RUNNING	409	Zaten devam eden bir attack surface taraması var
SERVICE_UNAVAILABLE	503	Attack surface tarayıcısı henüz kullanılabilir değil