Python SDK og CLI

Vedlikeholdt av: Aether365 Team Malgruppe: Utviklere og DevOps-ingeniører Omfang: Installasjon og bruk av det offisielle aether365 Python SDK-et og kommandolinjegrensesnittet

Pakken aether365 er det offisielle Python SDK-et og kommandolinjegrensesnittet for Aether365 API-et. Den pakker inn https://api.aether365.io, håndterer autentisering, pakker ut svarkonvolutten og prøver automatisk på nytt ved forbigående feil. Alt du kan gjøre med curl, kan du gjøre med SDK-et eller CLI-et.

SDK-et og CLI-et bruker en API-nøkkel (ak_live_...) og går mot det samlede endepunktet - forespørsler rutes automatisk til tenantens hjemmeregion. Se Autentisering for hvordan nøkler fungerer.

Installasjon

Pakken distribueres internt (ikke på PyPI). Installer den direkte fra repositoryet eller en lokal utsjekk.

# 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 kreves. Installasjonen legger også kommandoen aether365 på PATH.

Konfigurasjon

Både SDK-et og CLI-et leser de samme miljøvariablene:

Variabel	Formål	Standard
AETHER365_API_KEY	Din API-nøkkel (ak_live_...). Påkrevd.	-
AETHER365_API_URL	Overstyrer basis-URL-en (for eksempel dev-endepunktet).	https://api.aether365.io
AETHER365_OUTPUT	CLI-ets utdataformat: table eller json.	table

export AETHER365_API_KEY="ak_live_..."

Region håndteres automatisk: API-et finner tenanten din ut fra nøkkelen og videresender til riktig region, så du verken konfigurerer eller oppgir en region.

Hurtigstart: 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")

Hurtigstart: 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

Hva en API-nøkkel kan og ikke kan gjøre

En API-nøkkel er begrenset til en trygg, lesende og operativ flate. Den kan lese dataene dine, starte og administrere skanninger, generere rapporter og administrere attack surface-mål. Den kan ikke utføre handlinger som styrer kontoen eller kan låse ute katalogen - administrasjon av API-nøkler, fakturering, teammedlemskap, on- og offboarding av tilkoblinger, SSO, anvendelse av en remediation-plan eller AI Pilots conditional access-/break glass-skrivinger. De er bare tilgjengelige for en pålogget økt i dashbordet. En forespørsel til en rute som ikke er tillatt, returnerer 403 AUTH_INSUFFICIENT_SCOPE.

Kommando- og metodereferanse

Hver rad viser samme operasjon på tre måter: som rå curl, som SDK-metode og som CLI-kommando.

Tenant og konto

Operasjon	curl	SDK	CLI
Hent tenantprofil	GET /tenants/me	client.tenants.me()	aether365 tenant me
List tilkoblinger	GET /tenants/me/connections	client.connections.list()	aether365 tenant connections
Varslingsinnstillinger	GET /tenants/me/notifications	client.notifications.get()	aether365 tenant notifications
Planlagte skanninger	GET /tenants/me/scheduled-scans	client.scheduled_scans.list()	aether365 tenant scheduled-scans

Skanninger

Operasjon	curl	SDK	CLI
List skanninger	GET /tenants/me/scans	client.scans.list()	aether365 scan list
Start en skanning	POST /tenants/me/scans	client.scans.create("compliance")	aether365 scan run --type compliance
Hent en skanning	GET /scans/{id}	client.scans.get(id)	aether365 scan get <id>
Les resultater	GET /scans/{id}/results	client.scans.results(id)	aether365 scan results <id>
Avbryt en skanning	POST /scans/{id}/cancel	client.scans.cancel(id)	aether365 scan cancel <id>
Skjul en skanning	PATCH /scans/{id}/hide	client.scans.hide(id)	aether365 scan hide <id>
Vis en skanning igjen	PATCH /scans/{id}/unhide	client.scans.unhide(id)	aether365 scan unhide <id>
Slett en skanning	DELETE /scans/{id}	client.scans.delete(id)	aether365 scan delete <id>

curl-kallet for å starte en skanning:

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

Operasjon	curl	SDK	CLI
Rapportstatus	GET /scans/{id}/report	client.reports.status(id)	aether365 report status <id>
Generer 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
Last ned en rapport	GET /scans/{id}/report (presigned)	client.reports.download(id, path)	aether365 report download <id> -o out.pdf

Rapportstatus er en av ready, rendering, orgNameRequired eller locked. Å generere en rapport kan bruke en rapportkreditt (et engangsbeløp når ingen kvote er inkludert) - nøkkeleieren velger dette selv ved å kalle generate.

Rapportlisten er offset-paginert: send meta["nextCursor"] (et heltalls radoffset, eller None på siste side) tilbake som cursor. client.reports.iter_all() følger cursoren for deg.

Attack surface

Operasjon	curl	SDK	CLI
Oversikt	GET /tenants/me/attack-surface	client.attack_surface.summary()	aether365 eas summary
Historikk	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
Legg til et mål	POST /tenants/me/attack-surface/targets	client.attack_surface.add_target(host)	aether365 eas targets add <host>
Oppdater et mål	PATCH /tenants/me/attack-surface/targets/{id}	client.attack_surface.update_target(id, ...)	aether365 eas targets update <id> --label ...
Slett et mål	DELETE /tenants/me/attack-surface/targets/{id}	client.attack_surface.remove_target(id)	aether365 eas targets remove <id>
Verifiser et mål	POST /tenants/me/attack-surface/targets/{id}/verify	client.attack_surface.verify_target(id)	aether365 eas targets verify <id>
Kjør en EAS-skanning	POST /tenants/me/attack-surface/scan	client.attack_surface.scan()	aether365 eas scan

Posture, remediation og AI Pilot

Operasjon	curl	SDK	CLI
Trussel-/risikovisning	GET /tenants/me/threats	client.threats.list()	aether365 threats
Policy-posture	GET /tenants/me/policies	client.policies.list()	aether365 policies
Remediation-funksjoner	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-policyer	GET /tenants/me/ai-pilot/conditional-access	client.ai_pilot.conditional_access()	aether365 ai-pilot conditional-access

Remediation er skrivebeskyttet for API-nøkler. Å anvende en plan er ikke eksponert: action registry-elementene i en plan kan inneholde conditional access-/authorization policy-patcher som ville låst en tenant ute av sin egen katalog (AADSTS50097), så anvendelsen blir værende i dashbordet med en operatør i loopen. AI Pilot conditional access og break-glass er av samme grunn også bare lesbare.

Feilhåndtering og retries

Hver API-feil mappes til en typet exception-subklasse av 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 (oppvarmingen av den kalde dev-databasen) på nytt med eksponentiell backoff og respekterer Retry-After-headeren. Kvotefeil som SCAN_PLAN_LIMIT_REACHED kastes umiddelbart - de prøves ikke på nytt.

Bruke CLI-et i CI

aether365 scan results <id> --fail-on-findings avslutter med kode 2 når minst ett feilet funn finnes, slik at en pipeline kan bruke skanneresultatene som gate:

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

CLI-et skriver feil til stderr og avslutter med 1 ved enhver API-feil og med 2 ved findings-gaten.