Python SDK og CLI

Pakken aether365 er det officielle Python SDK og kommandolinjeværktøj til Aether365 API'et. Den indkapsler https://api.aether365.io, håndterer godkendelse, pakker svar-envelopen ud og prøver automatisk igen ved midlertidige fejl. Alt hvad du kan med curl, kan du også med SDK'et eller CLI'et.

SDK'et og CLI'et bruger en API-nøgle (ak_live_...) og går mod det samlede endpoint - forespørgsler dirigeres automatisk til din tenants hjemmeregion. Se Godkendelse for hvordan nøgler fungerer.

Installation

Pakken distribueres internt (ikke via PyPI). Installer den direkte fra repositoryet eller et lokalt checkout.

# From a local checkout of the monorepo
pip install ./packages/cli

# Or with Poetry, from a path
poetry add ./packages/cli

Python 3.12 eller nyere er påkrævet. Installationen lægger også kommandoen aether365 på din PATH.

Konfiguration

Både SDK'et og CLI'et læser de samme miljøvariabler:

Variabel	Formål	Standard
AETHER365_API_KEY	Din API-nøgle (ak_live_...). Påkrævet.	-
AETHER365_API_URL	Tilsidesætter basis-URL'en (for eksempel dev-endpointet).	https://api.aether365.io
AETHER365_OUTPUT	CLI'ets outputformat: table eller json.	table

export AETHER365_API_KEY="ak_live_..."

Region klares automatisk: API'et finder din tenant ud fra nøglen og videresender til den rigtige region, så du hverken konfigurerer eller angiver en region.

Hurtig start: SDK

from aether365 import Aether365Client

with Aether365Client() as client:          # reads AETHER365_API_KEY
    tenant = client.tenants.me()
    print(tenant["name"])

    # Trigger a scan and wait for it to finish
    scan = client.scans.create("compliance")
    for snapshot in client.scans.wait(scan["id"]):
        print(snapshot["status"])

    # Read the findings
    findings = client.scans.results(scan["id"], result="Failed")
    print(f"{len(findings)} failed checks")

Hurtig start: CLI

# Show the authenticated tenant
aether365 tenant me

# Trigger a scan and follow progress until it finishes
aether365 scan run --type compliance --watch

# List scans as JSON
aether365 --output json scan list

# Fail a CI job when a scan has failed findings (exit code 2)
aether365 scan results <SCAN_ID> --fail-on-findings

Hvad en API-nøgle kan og ikke kan

En API-nøgle er begrænset til en sikker, læsende og operationel flade. Den kan læse dine data, starte og administrere scanninger, generere rapporter og administrere attack surface-mål. Den kan ikke udføre handlinger, der styrer kontoen eller kan låse directoryet ude - administration af API-nøgler, fakturering, teammedlemskab, on- og offboarding af forbindelser, SSO, anvendelse af en remediation-plan eller AI Pilots conditional access-/break glass-skrivninger. De er kun tilgængelige for en session, der er logget ind i dashboardet. En forespørgsel til en ikke-tilladt route returnerer 403 AUTH_INSUFFICIENT_SCOPE.

Kommando- og metodereference

Hver række viser den samme operation på tre måder: som rå curl, som SDK-metode og som CLI-kommando.

Tenant og konto

Operation	curl	SDK	CLI
Hent tenantprofil	GET /tenants/me	client.tenants.me()	aether365 tenant me
List forbindelser	GET /tenants/me/connections	client.connections.list()	aether365 tenant connections
Notifikationsindstillinger	GET /tenants/me/notifications	client.notifications.get()	aether365 tenant notifications
Planlagte scanninger	GET /tenants/me/scheduled-scans	client.scheduled_scans.list()	aether365 tenant scheduled-scans

Scanninger

Operation	curl	SDK	CLI
List scanninger	GET /tenants/me/scans	client.scans.list()	aether365 scan list
Start en scanning	POST /tenants/me/scans	client.scans.create("compliance")	aether365 scan run --type compliance
Hent en scanning	GET /scans/{id}	client.scans.get(id)	aether365 scan get <id>
Læs resultater	GET /scans/{id}/results	client.scans.results(id)	aether365 scan results <id>
Annuller en scanning	POST /scans/{id}/cancel	client.scans.cancel(id)	aether365 scan cancel <id>
Skjul en scanning	PATCH /scans/{id}/hide	client.scans.hide(id)	aether365 scan hide <id>
Vis en scanning igen	PATCH /scans/{id}/unhide	client.scans.unhide(id)	aether365 scan unhide <id>
Slet en scanning	DELETE /scans/{id}	client.scans.delete(id)	aether365 scan delete <id>

curl-kaldet til at starte en scanning:

curl -X POST https://api.aether365.io/tenants/me/scans \
  -H "Authorization: Bearer $AETHER365_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scanType": "compliance"}'

Rapporter

Operation	curl	SDK	CLI
Rapportstatus	GET /scans/{id}/report	client.reports.status(id)	aether365 report status <id>
Generér en rapport	POST /scans/{id}/report/generate	client.reports.generate(id)	aether365 report generate <id>
List rapporter	GET /tenants/me/reports	client.reports.list()	aether365 report list
Download en rapport	GET /scans/{id}/report (presigned)	client.reports.download(id, path)	aether365 report download <id> -o out.pdf

Rapportstatus er en af ready, rendering, orgNameRequired eller locked. Generering af en rapport kan bruge en rapportkredit (en engangsbetaling, når der ikke er inkluderet en kvote) - nøglens ejer vælger det selv ved at kalde generate.

Rapportlisten er offset-pagineret: send meta["nextCursor"] (et heltals-rækkeoffset, eller None på sidste side) tilbage som cursor. client.reports.iter_all() følger cursoren for dig.

Attack surface

Operation	curl	SDK	CLI
Overblik	GET /tenants/me/attack-surface	client.attack_surface.summary()	aether365 eas summary
Historik	GET /tenants/me/attack-surface/history	client.attack_surface.history()	aether365 eas history
List mål	GET /tenants/me/attack-surface/targets	client.attack_surface.targets()	aether365 eas targets list
Tilføj et mål	POST /tenants/me/attack-surface/targets	client.attack_surface.add_target(host)	aether365 eas targets add <host>
Opdater et mål	PATCH /tenants/me/attack-surface/targets/{id}	client.attack_surface.update_target(id, ...)	aether365 eas targets update <id> --label ...
Slet et mål	DELETE /tenants/me/attack-surface/targets/{id}	client.attack_surface.remove_target(id)	aether365 eas targets remove <id>
Verificér et mål	POST /tenants/me/attack-surface/targets/{id}/verify	client.attack_surface.verify_target(id)	aether365 eas targets verify <id>
Kør en EAS-scanning	POST /tenants/me/attack-surface/scan	client.attack_surface.scan()	aether365 eas scan

Posture, remediation og AI Pilot

Operation	curl	SDK	CLI
Trussels-/risikovisning	GET /tenants/me/threats	client.threats.list()	aether365 threats
Policy-posture	GET /tenants/me/policies	client.policies.list()	aether365 policies
Remediation-muligheder	GET /tenants/me/remediation/capabilities	client.remediation.capabilities()	aether365 remediation capabilities
List remediation-planer	GET /tenants/me/remediation-plans	client.remediation.plans()	aether365 remediation plans
Hent en remediation-plan	GET /tenants/me/remediation-plans/{id}	client.remediation.plan(id)	aether365 remediation plan <id>
AI Pilot remediable	GET /tenants/me/ai-pilot/remediable	client.ai_pilot.remediable()	aether365 ai-pilot remediable
AI Pilot break-glass	GET /tenants/me/ai-pilot/break-glass	client.ai_pilot.break_glass()	aether365 ai-pilot break-glass
AI Pilot CA-policies	GET /tenants/me/ai-pilot/conditional-access	client.ai_pilot.conditional_access()	aether365 ai-pilot conditional-access

Remediation er skrivebeskyttet for API-nøgler. Anvendelse af en plan er ikke eksponeret: en plans action registry-elementer kan indeholde conditional access-/authorization policy-patches, der ville låse en tenant ude af sit eget directory (AADSTS50097), så anvendelsen bliver i dashboardet med en operatør i loopet. AI Pilot conditional access og break-glass er af samme grund også kun læsbare.

Fejlhåndtering og retries

Hver API-fejl mappes til en typet exception-subklasse af Aether365Error:

from aether365 import Aether365Client
from aether365.exceptions import PermissionError_, PlanLimitError, NotFoundError

with Aether365Client() as client:
    try:
        client.scans.create("compliance")
    except PlanLimitError:
        print("Scan quota reached for this plan.")
    except PermissionError_:
        print("Route not allowed for this key, or plan lacks API access.")
    except NotFoundError:
        print("Resource not found.")

Klienten prøver automatisk 429 RATE_LIMITED og 503 SERVICE_STARTING (opvarmningen af den kolde dev-database) igen med eksponentiel backoff og respekterer Retry-After-headeren. Kvotefejl som SCAN_PLAN_LIMIT_REACHED kastes med det samme - de prøves ikke igen.

Brug af CLI'et i CI

aether365 scan results <id> --fail-on-findings afslutter med kode 2, når der er mindst ét fejlet fund, så en pipeline kan bruge scanresultaterne som gate:

aether365 scan run --type compliance --watch
aether365 scan results "$SCAN_ID" --fail-on-findings

CLI'et skriver fejl til stderr og afslutter med 1 ved enhver API-fejl og med 2 ved findings-gaten.