External Attack Surface API

Maintenu par : Aether365 Team Public : Développeurs Périmètre : Endpoints External Attack Surface (EAS) - résultats, cibles d'analyse, vérification de domaine et analyses à la demande

L'API External Attack Surface lit la posture vue de l'extérieur de vos domaines Microsoft 365 (TLS, sécurité DNS et endpoints exposés), gère les hôtes qui sont analysés et déclenche des analyses à la demande. Tous les endpoints sont limités au tenant à partir du bearer token. L'analyse à la demande nécessite un plan payant.

Obtenir les résultats de l'attack surface

Renvoie la dernière analyse d'attack surface regroupée en sections ssl, dns et endpoints, ainsi que le nombre de problèmes ouverts par sévérité et les cibles d'analyse actuelles.

GET /tenants/me/attack-surface

Exemple de requête

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

Exemple de réponse

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

Le champ target de chaque constat correspond à l'hôte auquel il s'applique ; les constats sans hôte sont des contrôles couvrant l'ensemble du tenant. Regroupez par target pour obtenir une vue par domaine.

---

Lister les cibles d'analyse

Renvoie toutes les cibles d'analyse du tenant : les domaines Microsoft 365 découverts automatiquement et les domaines personnalisés que vous avez ajoutés.

GET /tenants/me/attack-surface/targets

Une cible personnalisée en attente renvoie également un verificationRecord (la valeur DNS TXT à publier).

---

Ajouter une cible personnalisée

Ajoute un domaine personnalisé. Il démarre à l'état pending et n'est pas analysé tant qu'il n'est pas vérifié.

POST /tenants/me/attack-surface/targets

Corps de la requête

{ "host": "contoso.com" }

Champ	Type	Requis	Remarques
host	string	Oui	Un nom de domaine seul (sans schéma, port ni chemin)

Exemple de réponse

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

Erreurs

Code	HTTP	Description
VALIDATION_ERROR	400	host n'est pas un nom de domaine seul
VALIDATION_ERROR	409	La cible existe déjà

---

Vérifier une cible personnalisée

Confirme la propriété du domaine en recherchant l'enregistrement TXT publié. En cas de succès, la cible passe à l'état verified et est incluse dans la prochaine analyse.

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

Publiez un enregistrement DNS TXT sur l'apex du domaine avec la valeur renvoyée dans verificationRecord (par exemple aether365-site-verification=ab12cd34...), puis appelez cet endpoint.

Erreurs

Code	HTTP	Description
EAS_TXT_NOT_FOUND	400	L'enregistrement TXT attendu n'a pas encore été trouvé dans le DNS

---

Exclure ou inclure une cible

Active ou désactive l'analyse d'une cible. Les cibles découvertes automatiquement ne peuvent pas être supprimées, seulement exclues.

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

Corps de la requête

{ "excluded": true }

---

Supprimer une cible personnalisée

Supprime une cible personnalisée (ajoutée par l'utilisateur). Les cibles découvertes automatiquement renvoient 400 et peuvent uniquement être exclues.

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

---

Déclencher une analyse d'attack surface

Lance une analyse d'attack surface à la demande. Nécessite un plan payant.

POST /tenants/me/attack-surface/scan

Corps de la requête

{ "connectionId": "conn_abc123" }

Champ	Type	Requis	Remarques
connectionId	string	Non	Tenant Microsoft connecté à analyser ; à omettre pour le tenant principal

Erreurs

Code	HTTP	Description
AUTH_FORBIDDEN	403	Le plan n'inclut pas External Attack Surface
TENANT_NOT_CONNECTED	400	Aucun tenant Microsoft connecté
SCAN_ALREADY_RUNNING	409	Une analyse d'attack surface est déjà en cours
SERVICE_UNAVAILABLE	503	L'analyseur d'attack surface n'est pas encore disponible