API externí útočné plochy

Spravuje: Tým Aether365 Cílová skupina: Vývojáři Rozsah: Koncové body externí útočné plochy (EAS) - výsledky, cíle skenů, ověření domén a skeny na vyžádání

API externí útočné plochy čte stav vašich domén Microsoft 365 z vnějšího pohledu (TLS, zabezpečení DNS a vystavené koncové body), spravuje, které hostitele se skenují, a spouští skeny na vyžádání. Všechny koncové body jsou omezeny na tenanta podle bearer tokenu. Sken na vyžádání vyžaduje placený plán.

Získání výsledků útočné plochy

Vrací nejnovější sken útočné plochy rozdělený do sekcí ssl, dns a endpoints, dále počty otevřených problémů podle závažnosti a aktuální cíle skenů.

GET /tenants/me/attack-surface

Příklad požadavku

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

Příklad odpovědi

{
  "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 u každého nálezu je hostitel, kterého se nález týká; nálezy bez hostitele jsou kontroly platné pro celého tenanta. Seskupením podle target získáte pohled na jednotlivé domény.

---

Výpis cílů skenů

Vrací každý cíl skenu pro tenanta: automaticky zjištěné domény Microsoft 365 a vlastní domény, které jste přidali.

GET /tenants/me/attack-surface/targets

Čekající vlastní cíl vrací také verificationRecord (hodnotu DNS TXT, kterou je třeba zveřejnit).

---

Přidání vlastního cíle

Přidá vlastní doménu. Začíná ve stavu pending a nebude skenována, dokud nebude ověřena.

POST /tenants/me/attack-surface/targets

Tělo požadavku

{ "host": "contoso.com" }

Pole	Typ	Povinné	Poznámky
host	string	Ano	Holý název domény (bez schématu, portu nebo cesty)

Příklad odpovědi

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

Chyby

Kód	HTTP	Popis
VALIDATION_ERROR	400	host není holý název domény
VALIDATION_ERROR	409	Cíl již existuje

---

Ověření vlastního cíle

Potvrzuje vlastnictví domény vyhledáním zveřejněného TXT záznamu. Po úspěchu se cíl přepne do stavu verified a bude zahrnut do dalšího skenu.

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

Na apexu domény zveřejněte DNS TXT záznam s hodnotou vrácenou v poli verificationRecord (například aether365-site-verification=ab12cd34...) a poté zavolejte tento koncový bod.

Chyby

Kód	HTTP	Popis
EAS_TXT_NOT_FOUND	400	Očekávaný TXT záznam zatím nebyl v DNS nalezen

---

Vyloučení nebo zahrnutí cíle

Přepíná, zda se cíl skenuje. Automaticky zjištěné cíle nelze smazat, lze je pouze vyloučit.

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

Tělo požadavku

{ "excluded": true }

---

Smazání vlastního cíle

Odstraní vlastní (uživatelem přidaný) cíl. Automaticky zjištěné cíle vrací 400 a lze je pouze vyloučit.

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

---

Spuštění skenu útočné plochy

Spustí sken útočné plochy na vyžádání. Vyžaduje placený plán.

POST /tenants/me/attack-surface/scan

Tělo požadavku

{ "connectionId": "conn_abc123" }

Pole	Typ	Povinné	Poznámky
connectionId	string	Ne	Připojený tenant Microsoft, který se má skenovat; vynechte pro primárního

Chyby

Kód	HTTP	Popis
AUTH_FORBIDDEN	403	Tarif neobsahuje externí útočnou plochu
TENANT_NOT_CONNECTED	400	Žádný připojený tenant Microsoft
SCAN_ALREADY_RUNNING	409	Sken útočné plochy již probíhá
SERVICE_UNAVAILABLE	503	Skener útočné plochy zatím není dostupný