API External Attack Surface

Maintainer: Aether365 Team Destinatari: Sviluppatori Ambito: Endpoint External Attack Surface (EAS) - risultati, target di scansione, verifica dei domini e scansioni su richiesta

L'API External Attack Surface legge la postura dall'esterno verso l'interno dei vostri domini Microsoft 365 (TLS, sicurezza DNS ed endpoint esposti), gestisce quali host vengono scansionati e avvia scansioni su richiesta. Tutti gli endpoint sono limitati al tenant ricavato dal bearer token. La scansione su richiesta richiede un piano a pagamento.

Ottenere i risultati dell'attack surface

Restituisce l'ultima scansione dell'attack surface raggruppata nelle sezioni ssl, dns ed endpoints, oltre al conteggio dei problemi aperti per gravità e i target di scansione correnti.

GET /tenants/me/attack-surface

Richiesta di esempio

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

Risposta di esempio

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

Il campo target di ogni risultato indica l'host a cui si applica; i risultati senza host sono controlli che riguardano l'intero tenant. Raggruppate per target per ottenere una vista per dominio.

---

Elencare i target di scansione

Restituisce tutti i target di scansione del tenant: i domini Microsoft 365 rilevati automaticamente e i domini personalizzati che avete aggiunto.

GET /tenants/me/attack-surface/targets

Un target personalizzato in attesa restituisce anche un verificationRecord (il valore TXT DNS da pubblicare).

---

Aggiungere un target personalizzato

Aggiunge un dominio personalizzato. Parte come pending e non viene scansionato finché non è verificato.

POST /tenants/me/attack-surface/targets

Corpo della richiesta

{ "host": "contoso.com" }

Campo	Tipo	Obbligatorio	Note
host	string	Sì	Un nome di dominio puro (senza schema, porta o percorso)

Risposta di esempio

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

Errori

Codice	HTTP	Descrizione
VALIDATION_ERROR	400	host non è un nome di dominio puro
VALIDATION_ERROR	409	Il target esiste già

---

Verificare un target personalizzato

Conferma la proprietà del dominio cercando il record TXT pubblicato. In caso di successo il target diventa verified e viene incluso nella scansione successiva.

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

Pubblicate un record TXT DNS sull'apex del dominio con il valore restituito come verificationRecord (ad esempio aether365-site-verification=ab12cd34...), poi chiamate questo endpoint.

Errori

Codice	HTTP	Descrizione
EAS_TXT_NOT_FOUND	400	Il record TXT atteso non è stato ancora trovato nel DNS

---

Escludere o includere un target

Attiva o disattiva la scansione di un target. I target rilevati automaticamente non possono essere eliminati, solo esclusi.

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

Corpo della richiesta

{ "excluded": true }

---

Eliminare un target personalizzato

Rimuove un target personalizzato (aggiunto dall'utente). I target rilevati automaticamente restituiscono 400 e possono solo essere esclusi.

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

---

Avviare una scansione dell'attack surface

Avvia una scansione dell'attack surface su richiesta. Richiede un piano a pagamento.

POST /tenants/me/attack-surface/scan

Corpo della richiesta

{ "connectionId": "conn_abc123" }

Campo	Tipo	Obbligatorio	Note
connectionId	string	No	Tenant Microsoft collegato da scansionare; omettere per il principale

Errori

Codice	HTTP	Descrizione
AUTH_FORBIDDEN	403	Il piano non include External Attack Surface
TENANT_NOT_CONNECTED	400	Nessun tenant Microsoft collegato
SCAN_ALREADY_RUNNING	409	Una scansione dell'attack surface è già in corso
SERVICE_UNAVAILABLE	503	Lo scanner dell'attack surface non è ancora disponibile