API External Attack Surface

Întreținut de: Aether365 Team Public țintă: dezvoltatori Domeniu: endpoint-uri External Attack Surface (EAS) - rezultate, ținte de scanare, verificarea domeniilor și scanări la cerere

API-ul External Attack Surface citește poziția văzută din exterior a domeniilor dvs. Microsoft 365 (TLS, securitatea DNS și endpoint-urile expuse), gestionează ce host-uri sunt scanate și declanșează scanări la cerere. Toate endpoint-urile sunt limitate la tenant pe baza token-ului bearer. Scanarea la cerere necesită un plan plătit.

Obținerea rezultatelor Attack Surface

Returnează cea mai recentă scanare attack surface grupată în secțiunile ssl, dns și endpoints, plus numărul de probleme deschise pe severitate și țintele de scanare curente.

GET /tenants/me/attack-surface

Exemplu de cerere

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

Exemplu de răspuns

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

Câmpul target al fiecărei constatări este host-ul la care se aplică; constatările fără host sunt verificări la nivel de tenant. Grupați după target pentru o vedere per domeniu.

---

Listarea țintelor de scanare

Returnează fiecare țintă de scanare a tenant-ului: domeniile Microsoft 365 descoperite automat și domeniile personalizate adăugate de dvs.

GET /tenants/me/attack-surface/targets

O țintă personalizată în așteptare returnează și un verificationRecord (valoarea DNS TXT de publicat).

---

Adăugarea unei ținte personalizate

Adaugă un domeniu personalizat. Pornește ca pending și nu este scanat până la verificare.

POST /tenants/me/attack-surface/targets

Corp cerere

{ "host": "contoso.com" }

Câmp	Tip	Obligatoriu	Note
host	string	Da	Un nume de domeniu simplu (fără schemă, port sau cale)

Exemplu de răspuns

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

Erori

Cod	HTTP	Descriere
VALIDATION_ERROR	400	host nu este un nume de domeniu simplu
VALIDATION_ERROR	409	Ținta există deja

---

Verificarea unei ținte personalizate

Confirmă proprietatea domeniului prin căutarea înregistrării TXT publicate. La succes, ținta devine verified și este inclusă în următoarea scanare.

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

Publicați o înregistrare DNS TXT pe apex-ul domeniului cu valoarea returnată în verificationRecord (de exemplu aether365-site-verification=ab12cd34...), apoi apelați acest endpoint.

Erori

Cod	HTTP	Descriere
EAS_TXT_NOT_FOUND	400	Înregistrarea TXT așteptată nu a fost încă găsită în DNS

---

Excluderea sau includerea unei ținte

Comută dacă o țintă este scanată. Țintele descoperite automat nu pot fi șterse, ci doar excluse.

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

Corp cerere

{ "excluded": true }

---

Ștergerea unei ținte personalizate

Elimină o țintă personalizată (adăugată de utilizator). Țintele descoperite automat returnează 400 și pot fi doar excluse.

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

---

Declanșarea unei scanări Attack Surface

Pornește la cerere o scanare attack surface. Necesită un plan plătit.

POST /tenants/me/attack-surface/scan

Corp cerere

{ "connectionId": "conn_abc123" }

Câmp	Tip	Obligatoriu	Note
connectionId	string	Nu	Tenant-ul Microsoft conectat de scanat; omiteți pentru cel principal

Erori

Cod	HTTP	Descriere
AUTH_FORBIDDEN	403	Planul nu include External Attack Surface
TENANT_NOT_CONNECTED	400	Niciun tenant Microsoft conectat
SCAN_ALREADY_RUNNING	409	O scanare attack surface este deja în curs
SERVICE_UNAVAILABLE	503	Scanerul attack surface nu este încă disponibil