External Attack Surface API

Underhålls av: Aether365 Team Målgrupp: Utvecklare Omfattning: External Attack Surface (EAS)-endpoints - resultat, skanningsmål, domänverifiering och skanningar på begäran

External Attack Surface API:et läser av det utåtvända säkerhetsläget för dina Microsoft 365-domäner (TLS, DNS-säkerhet och exponerade endpoints), hanterar vilka värdar som skannas och utlöser skanningar på begäran. Alla endpoints är begränsade till tenanten utifrån bearer-token. Skanning på begäran kräver en betald plan.

Hämta resultat för attackytan

Returnerar den senaste attackytans-skanningen grupperad i sektionerna ssl, dns och endpoints, plus antal öppna problem per allvarlighet och de aktuella skanningsmålen.

GET /tenants/me/attack-surface

Exempelbegäran

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

Exempelsvar

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

Varje fynds target är den värd som det gäller; fynd utan värd är kontroller som omfattar hela tenanten. Gruppera efter target för att få en vy per domän.

---

Lista skanningsmål

Returnerar alla skanningsmål för tenanten: automatiskt upptäckta Microsoft 365-domäner och anpassade domäner som du har lagt till.

GET /tenants/me/attack-surface/targets

Ett väntande anpassat mål returnerar även en verificationRecord (det DNS TXT-värde som ska publiceras).

---

Lägg till ett anpassat mål

Lägger till en anpassad domän. Den startar som pending och skannas inte förrän den är verifierad.

POST /tenants/me/attack-surface/targets

Begärandekropp

{ "host": "contoso.com" }

Fält	Typ	Obligatoriskt	Anmärkningar
host	string	Ja	Ett rent domännamn (inget schema, port eller sökväg)

Exempelsvar

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

Fel

Kod	HTTP	Beskrivning
VALIDATION_ERROR	400	host är inte ett rent domännamn
VALIDATION_ERROR	409	Målet finns redan

---

Verifiera ett anpassat mål

Bekräftar ägarskap av domänen genom att slå upp den publicerade TXT-posten. Vid framgång blir målet verified och inkluderas i nästa skanning.

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

Publicera en DNS TXT-post på domänens apex med värdet som returnerades som verificationRecord (till exempel aether365-site-verification=ab12cd34...), och anropa sedan denna endpoint.

Fel

Kod	HTTP	Beskrivning
EAS_TXT_NOT_FOUND	400	Den förväntade TXT-posten hittades inte i DNS ännu

---

Exkludera eller inkludera ett mål

Växlar om ett mål skannas eller inte. Automatiskt upptäckta mål kan inte raderas, bara exkluderas.

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

Begärandekropp

{ "excluded": true }

---

Radera ett anpassat mål

Tar bort ett anpassat (användartillagt) mål. Automatiskt upptäckta mål returnerar 400 och kan endast exkluderas.

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

---

Utlös en attackyte-skanning

Startar en attackyte-skanning på begäran. Kräver en betald plan.

POST /tenants/me/attack-surface/scan

Begärandekropp

{ "connectionId": "conn_abc123" }

Fält	Typ	Obligatoriskt	Anmärkningar
connectionId	string	Nej	Ansluten Microsoft-tenant att skanna; utelämna för den primära

Fel

Kod	HTTP	Beskrivning
AUTH_FORBIDDEN	403	Planen inkluderar inte External Attack Surface
TENANT_NOT_CONNECTED	400	Ingen ansluten Microsoft-tenant
SCAN_ALREADY_RUNNING	409	En attackyte-skanning pågår redan
SERVICE_UNAVAILABLE	503	Attackyte-skannern är inte tillgänglig ännu