API de External Attack Surface

Mantido por: Aether365 Team Público-alvo: programadores Âmbito: endpoints de External Attack Surface (EAS) - resultados, alvos de análise, verificação de domínio e análises a pedido

A API de External Attack Surface lê a postura, vista de fora para dentro, dos seus domínios Microsoft 365 (TLS, segurança de DNS e endpoints expostos), gere quais os hosts que são analisados e aciona análises a pedido. Todos os endpoints estão limitados ao tenant a partir do token de portador. A análise a pedido requer um plano pago.

Obter Resultados de Attack Surface

Devolve a análise de attack surface mais recente, agrupada nas secções ssl, dns e endpoints, além das contagens de problemas em aberto por gravidade e dos alvos de análise atuais.

GET /tenants/me/attack-surface

Exemplo de Pedido

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

Exemplo de Resposta

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

O target de cada resultado é o host a que se aplica; os resultados sem host são verificações ao nível de todo o tenant. Agrupe por target para obter uma vista por domínio.

---

Listar Alvos de Análise

Devolve todos os alvos de análise do tenant: domínios Microsoft 365 descobertos automaticamente e domínios personalizados que adicionou.

GET /tenants/me/attack-surface/targets

Um alvo personalizado pendente devolve também um verificationRecord (o valor do registo DNS TXT a publicar).

---

Adicionar um Alvo Personalizado

Adiciona um domínio personalizado. Começa como pending e não é analisado até ser verificado.

POST /tenants/me/attack-surface/targets

Corpo do Pedido

{ "host": "contoso.com" }

Campo	Tipo	Obrigatório	Notas
host	string	Sim	Um nome de domínio simples (sem esquema, porta ou caminho)

Exemplo de Resposta

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

Erros

Código	HTTP	Descrição
VALIDATION_ERROR	400	host não é um nome de domínio simples
VALIDATION_ERROR	409	O alvo já existe

---

Verificar um Alvo Personalizado

Confirma a posse do domínio consultando o registo TXT publicado. Em caso de sucesso, o alvo passa a verified e é incluído na próxima análise.

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

Publique um registo DNS TXT no apex do domínio com o valor devolvido em verificationRecord (por exemplo aether365-site-verification=ab12cd34...) e, em seguida, chame este endpoint.

Erros

Código	HTTP	Descrição
EAS_TXT_NOT_FOUND	400	O registo TXT esperado ainda não foi encontrado no DNS

---

Excluir ou Incluir um Alvo

Alterna se um alvo é analisado. Os alvos descobertos automaticamente não podem ser eliminados, apenas excluídos.

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

Corpo do Pedido

{ "excluded": true }

---

Eliminar um Alvo Personalizado

Remove um alvo personalizado (adicionado pelo utilizador). Os alvos descobertos automaticamente devolvem 400 e só podem ser excluídos.

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

---

Acionar uma Análise de Attack Surface

Inicia uma análise de attack surface a pedido. Requer um plano pago.

POST /tenants/me/attack-surface/scan

Corpo do Pedido

{ "connectionId": "conn_abc123" }

Campo	Tipo	Obrigatório	Notas
connectionId	string	Não	Tenant Microsoft ligado a analisar; omita para o principal

Erros

Código	HTTP	Descrição
AUTH_FORBIDDEN	403	O plano não inclui External Attack Surface
TENANT_NOT_CONNECTED	400	Nenhum tenant Microsoft ligado
SCAN_ALREADY_RUNNING	409	Já está em curso uma análise de attack surface
SERVICE_UNAVAILABLE	503	O analisador de attack surface ainda não está disponível