API de External Attack Surface

Mantenido por: Aether365 Team Audiencia: Desarrolladores Alcance: Endpoints de External Attack Surface (EAS) - resultados, objetivos de escaneo, verificación de dominios y escaneos bajo demanda

La API de External Attack Surface lee la postura externa de sus dominios de Microsoft 365 (TLS, seguridad DNS y endpoints expuestos), gestiona qué hosts se escanean y lanza escaneos bajo demanda. Todos los endpoints quedan limitados al tenant a partir del token bearer. El escaneo bajo demanda requiere un plan de pago.

Obtener resultados de Attack Surface

Devuelve el último escaneo de attack surface agrupado en las secciones ssl, dns y endpoints, junto con el recuento de incidencias abiertas por severidad y los objetivos de escaneo actuales.

GET /tenants/me/attack-surface

Solicitud de ejemplo

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

Respuesta de ejemplo

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

El target de cada hallazgo es el host al que se aplica; los hallazgos sin host son controles que afectan a todo el tenant. Agrupe por target para obtener una vista por dominio.

---

Listar objetivos de escaneo

Devuelve todos los objetivos de escaneo del tenant: los dominios de Microsoft 365 detectados automáticamente y los dominios personalizados que haya añadido.

GET /tenants/me/attack-surface/targets

Un objetivo personalizado pendiente también devuelve un verificationRecord (el valor del registro DNS TXT que debe publicar).

---

Añadir un objetivo personalizado

Añade un dominio personalizado. Empieza como pending y no se escanea hasta que se verifica.

POST /tenants/me/attack-surface/targets

Cuerpo de la solicitud

{ "host": "contoso.com" }

Campo	Tipo	Obligatorio	Notas
host	string	Si	Un nombre de dominio sin más (sin esquema, puerto ni ruta)

Respuesta de ejemplo

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

Errores

Código	HTTP	Descripción
VALIDATION_ERROR	400	host no es un nombre de dominio sin más
VALIDATION_ERROR	409	El objetivo ya existe

---

Verificar un objetivo personalizado

Confirma la propiedad del dominio buscando el registro TXT publicado. Si tiene éxito, el objetivo pasa a verified y se incluye en el siguiente escaneo.

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

Publique un registro DNS TXT en el apex del dominio con el valor devuelto como verificationRecord (por ejemplo aether365-site-verification=ab12cd34...) y, a continuación, llame a este endpoint.

Errores

Código	HTTP	Descripción
EAS_TXT_NOT_FOUND	400	El registro TXT esperado aún no se ha encontrado en DNS

---

Excluir o incluir un objetivo

Activa o desactiva si un objetivo se escanea. Los objetivos detectados automáticamente no se pueden eliminar, solo excluir.

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

Cuerpo de la solicitud

{ "excluded": true }

---

Eliminar un objetivo personalizado

Elimina un objetivo personalizado (añadido por el usuario). Los objetivos detectados automáticamente devuelven 400 y solo se pueden excluir.

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

---

Lanzar un escaneo de Attack Surface

Inicia un escaneo de attack surface bajo demanda. Requiere un plan de pago.

POST /tenants/me/attack-surface/scan

Cuerpo de la solicitud

{ "connectionId": "conn_abc123" }

Campo	Tipo	Obligatorio	Notas
connectionId	string	No	Tenant de Microsoft conectado que se va a escanear; omítalo para el principal

Errores

Código	HTTP	Descripción
AUTH_FORBIDDEN	403	El plan no incluye External Attack Surface
TENANT_NOT_CONNECTED	400	No hay ningún tenant de Microsoft conectado
SCAN_ALREADY_RUNNING	409	Ya hay un escaneo de attack surface en curso
SERVICE_UNAVAILABLE	503	El escáner de attack surface aún no está disponible