External Attack Surface API

Vedlikeholdt av: Aether365 Team Malgruppe: Utviklere Omfang: External Attack Surface (EAS)-endepunkter - resultater, skannemål, domeneverifisering og skanninger ved behov

External Attack Surface-APIet leser utenfra-og-inn-stillingen til Microsoft 365-domenene dine (TLS, DNS-sikkerhet og eksponerte endepunkter), administrerer hvilke verter som skannes, og utløser skanninger ved behov. Alle endepunktene er begrenset til leietakeren basert på bearer-tokenet. Skanning ved behov krever en betalt plan.

Hent angrepsflate-resultater

Returnerer den siste angrepsflate-skanningen gruppert i seksjonene ssl, dns og endpoints, pluss antall åpne saker etter alvorlighetsgrad og de gjeldende skannemålene.

GET /tenants/me/attack-surface

Eksempelforespørsel

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

Eksempelrespons

{
  "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 funns target er verten det gjelder for; funn uten vert er sjekker som gjelder hele leietakeren. Grupper etter target for å få en oversikt per domene.

---

List skannemål

Returnerer alle skannemål for leietakeren: automatisk oppdagede Microsoft 365-domener og egendefinerte domener du har lagt til.

GET /tenants/me/attack-surface/targets

Et ventende egendefinert mål returnerer også en verificationRecord (DNS TXT-verdien som skal publiseres).

---

Legg til et egendefinert mål

Legger til et egendefinert domene. Det starter som pending og skannes ikke før det er verifisert.

POST /tenants/me/attack-surface/targets

Forespørselsbrødtekst

{ "host": "contoso.com" }

Felt	Type	Påkrevd	Merknader
host	string	Ja	Et rent domenenavn (uten skjema, port eller sti)

Eksempelrespons

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

Feil

Kode	HTTP	Beskrivelse
VALIDATION_ERROR	400	host er ikke et rent domenenavn
VALIDATION_ERROR	409	Målet finnes allerede

---

Verifiser et egendefinert mål

Bekrefter domeneeierskap ved å slå opp den publiserte TXT-posten. Ved suksess blir målet verified og inkluderes i neste skanning.

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

Publiser en DNS TXT-post på domeneroten med verdien som returneres som verificationRecord (for eksempel aether365-site-verification=ab12cd34...), og kall deretter dette endepunktet.

Feil

Kode	HTTP	Beskrivelse
EAS_TXT_NOT_FOUND	400	Den forventede TXT-posten ble ikke funnet i DNS ennå

---

Ekskluder eller inkluder et mål

Veksler om et mål skannes. Automatisk oppdagede mål kan ikke slettes, bare ekskluderes.

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

Forespørselsbrødtekst

{ "excluded": true }

---

Slett et egendefinert mål

Fjerner et egendefinert mål (lagt til av bruker). Automatisk oppdagede mål returnerer 400 og kan bare ekskluderes.

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

---

Utløs en angrepsflate-skanning

Starter en angrepsflate-skanning ved behov. Krever en betalt plan.

POST /tenants/me/attack-surface/scan

Forespørselsbrødtekst

{ "connectionId": "conn_abc123" }

Felt	Type	Påkrevd	Merknader
connectionId	string	Nei	Tilkoblet Microsoft-leietaker som skal skannes; utelat for den primære

Feil

Kode	HTTP	Beskrivelse
AUTH_FORBIDDEN	403	Planen inkluderer ikke External Attack Surface
TENANT_NOT_CONNECTED	400	Ingen tilkoblet Microsoft-leietaker
SCAN_ALREADY_RUNNING	409	En angrepsflate-skanning pågår allerede
SERVICE_UNAVAILABLE	503	Angrepsflate-skanneren er ikke tilgjengelig ennå