External Attack Surface API

Vedligeholdt af: Aether365-teamet Målgruppe: Udviklere Omfang: External Attack Surface-endpoints (EAS) - resultater, scanmål, domæneverificering og on-demand-scanninger

External Attack Surface-API'en aflæser den udefrakommende sikkerhedsstatus for dine Microsoft 365-domæner (TLS, DNS-sikkerhed og eksponerede endpoints), styrer hvilke værter der scannes, og igangsætter on-demand-scanninger. Alle endpoints er afgrænset til den tenant, der følger af bearer-tokenet. On-demand-scanningen kræver en betalt plan.

Hent resultater for angrebsfladen

Returnerer den seneste scanning af angrebsfladen, inddelt i sektionerne ssl, dns og endpoints, plus antal åbne problemer fordelt på alvorlighed samt de aktuelle scanmål.

GET /tenants/me/attack-surface

Eksempel på forespørgsel

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

Eksempel på svar

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

Hvert funds target er den vært, det gælder for; fund uden vært er kontroller, der dækker hele tenanten. Gruppér efter target for at få et overblik pr. domæne.

---

List scanmål

Returnerer alle scanmål for tenanten: automatisk opdagede Microsoft 365-domæner og de brugerdefinerede domæner, du har tilføjet.

GET /tenants/me/attack-surface/targets

Et brugerdefineret mål, der afventer verificering, returnerer også en verificationRecord (den DNS TXT-værdi, der skal offentliggøres).

---

Tilføj et brugerdefineret mål

Tilføjer et brugerdefineret domæne. Det starter som pending og scannes ikke, før det er verificeret.

POST /tenants/me/attack-surface/targets

Forespørgselsindhold

{ "host": "contoso.com" }

Felt	Type	Påkrævet	Bemærkninger
host	string	Ja	Et rent domænenavn (uden skema, port eller sti)

Eksempel på svar

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

Fejl

Kode	HTTP	Beskrivelse
VALIDATION_ERROR	400	host er ikke et rent domænenavn
VALIDATION_ERROR	409	Målet findes allerede

---

Verificér et brugerdefineret mål

Bekræfter ejerskab af domænet ved at slå den offentliggjorte TXT-record op. Lykkes det, bliver målet verified og indgår i den næste scanning.

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

Offentliggør en DNS TXT-record på domænets apex med den værdi, der blev returneret som verificationRecord (for eksempel aether365-site-verification=ab12cd34...), og kald derefter dette endpoint.

Fejl

Kode	HTTP	Beskrivelse
EAS_TXT_NOT_FOUND	400	Den forventede TXT-record blev endnu ikke fundet i DNS

---

Udeluk eller medtag et mål

Slår til og fra, om et mål scannes. Automatisk opdagede mål kan ikke slettes, kun udelukkes.

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

Forespørgselsindhold

{ "excluded": true }

---

Slet et brugerdefineret mål

Fjerner et brugerdefineret (brugertilføjet) mål. Automatisk opdagede mål returnerer 400 og kan kun udelukkes.

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

---

Udløs en scanning af angrebsfladen

Starter en on-demand-scanning af angrebsfladen. Kræver en betalt plan.

POST /tenants/me/attack-surface/scan

Forespørgselsindhold

{ "connectionId": "conn_abc123" }

Felt	Type	Påkrævet	Bemærkninger
connectionId	string	Nej	Tilknyttet Microsoft-tenant, der skal scannes; udelad for den primære

Fejl

Kode	HTTP	Beskrivelse
AUTH_FORBIDDEN	403	Planen omfatter ikke External Attack Surface
TENANT_NOT_CONNECTED	400	Ingen tilknyttet Microsoft-tenant
SCAN_ALREADY_RUNNING	409	En scanning af angrebsfladen er allerede i gang
SERVICE_UNAVAILABLE	503	Scanneren til angrebsfladen er endnu ikke tilgængelig