Python SDK a CLI

Balíček aether365 je oficiální Python SDK a rozhraní příkazové řádky pro Aether365 API. Obaluje https://api.aether365.io, stará se o autentizaci, rozbaluje obálku odpovědi a přechodné chyby automaticky opakuje. Cokoli zvládnete přes curl, zvládnete i přes SDK nebo CLI.

SDK i CLI používají API klíč (ak_live_...) a míří na sjednocený endpoint - požadavky se automaticky směrují do domovského regionu vašeho tenanta. Jak klíče fungují, popisuje stránka Autentizace.

Instalace

Balíček je distribuován interně (není na PyPI). Nainstalujte jej přímo z repozitáře nebo z lokálního checkoutu.

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

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

Vyžadován je Python 3.12 nebo novější. Instalace balíčku zároveň přidá příkaz aether365 do PATH.

Konfigurace

SDK i CLI čtou stejné proměnné prostředí:

Proměnná	Účel	Výchozí
AETHER365_API_KEY	Váš API klíč (ak_live_...). Povinné.	-
AETHER365_API_URL	Přepsání základní URL (například dev endpoint).	https://api.aether365.io
AETHER365_OUTPUT	Výstupní formát CLI: table nebo json.	table

export AETHER365_API_KEY="ak_live_..."

Region je automatický: API podle klíče určí vašeho tenanta a požadavek předá do správného regionu, takže region nikdy nekonfigurujete ani nepředáváte.

Rychlý 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")

Rychlý 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

Co API klíč smí a co nesmí

API klíč je omezen na bezpečnou plochu: čtení plus provozní operace. Může číst vaše data, spouštět a spravovat skeny, generovat reporty a spravovat cíle attack surface. Nemůže provádět akce ovládající účet ani akce, které by mohly zamknout adresář - správu API klíčů, fakturaci, členství v týmu, připojování a odpojování connectionů, SSO, aplikaci remediačního plánu ani zápisy AI Pilotu do conditional access / break-glass. Ty zůstávají dostupné jen přihlášené relaci v dashboardu. Požadavek na nepovolenou cestu vrací 403 AUTH_INSUFFICIENT_SCOPE.

Přehled příkazů a metod

Každý řádek ukazuje stejnou operaci třemi způsoby: čistý curl, metoda SDK a příkaz CLI.

Tenant a účet

Operace	curl	SDK	CLI
Profil tenanta	GET /tenants/me	client.tenants.me()	aether365 tenant me
Seznam připojení	GET /tenants/me/connections	client.connections.list()	aether365 tenant connections
Předvolby notifikací	GET /tenants/me/notifications	client.notifications.get()	aether365 tenant notifications
Naplánované skeny	GET /tenants/me/scheduled-scans	client.scheduled_scans.list()	aether365 tenant scheduled-scans

Skeny

Operace	curl	SDK	CLI
Seznam skenů	GET /tenants/me/scans	client.scans.list()	aether365 scan list
Spuštění skenu	POST /tenants/me/scans	client.scans.create("compliance")	aether365 scan run --type compliance
Načtení skenu	GET /scans/{id}	client.scans.get(id)	aether365 scan get <id>
Čtení výsledků	GET /scans/{id}/results	client.scans.results(id)	aether365 scan results <id>
Zrušení skenu	POST /scans/{id}/cancel	client.scans.cancel(id)	aether365 scan cancel <id>
Skrytí skenu	PATCH /scans/{id}/hide	client.scans.hide(id)	aether365 scan hide <id>
Zrušení skrytí skenu	PATCH /scans/{id}/unhide	client.scans.unhide(id)	aether365 scan unhide <id>
Smazání skenu	DELETE /scans/{id}	client.scans.delete(id)	aether365 scan delete <id>

curl pro spuštění skenu:

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

Reporty

Operace	curl	SDK	CLI
Stav reportu	GET /scans/{id}/report	client.reports.status(id)	aether365 report status <id>
Vygenerování reportu	POST /scans/{id}/report/generate	client.reports.generate(id)	aether365 report generate <id>
Seznam reportů	GET /tenants/me/reports	client.reports.list()	aether365 report list
Stažení reportu	GET /scans/{id}/report (presigned)	client.reports.download(id, path)	aether365 report download <id> -o out.pdf

Stav reportu je jedna z hodnot ready, rendering, orgNameRequired nebo locked. Vygenerování reportu může spotřebovat reportový kredit (jednorázový poplatek, když tarif nezahrnuje žádnou kvótu) - vlastník klíče s tím souhlasí tím, že zavolá generate.

Výpis reportů je stránkován offsetem: hodnotu meta["nextCursor"] (celočíselný offset řádku, nebo None na poslední stránce) předejte zpět jako cursor. client.reports.iter_all() kurzor sleduje za vás.

Attack surface

Operace	curl	SDK	CLI
Přehled	GET /tenants/me/attack-surface	client.attack_surface.summary()	aether365 eas summary
Historie	GET /tenants/me/attack-surface/history	client.attack_surface.history()	aether365 eas history
Seznam cílů	GET /tenants/me/attack-surface/targets	client.attack_surface.targets()	aether365 eas targets list
Přidání cíle	POST /tenants/me/attack-surface/targets	client.attack_surface.add_target(host)	aether365 eas targets add <host>
Aktualizace cíle	PATCH /tenants/me/attack-surface/targets/{id}	client.attack_surface.update_target(id, ...)	aether365 eas targets update <id> --label ...
Smazání cíle	DELETE /tenants/me/attack-surface/targets/{id}	client.attack_surface.remove_target(id)	aether365 eas targets remove <id>
Ověření cíle	POST /tenants/me/attack-surface/targets/{id}/verify	client.attack_surface.verify_target(id)	aether365 eas targets verify <id>
Spuštění EAS skenu	POST /tenants/me/attack-surface/scan	client.attack_surface.scan()	aether365 eas scan

Bezpečnostní postoj, remediace a AI Pilot

Operace	curl	SDK	CLI
Pohled na hrozby a rizika	GET /tenants/me/threats	client.threats.list()	aether365 threats
Stav politik	GET /tenants/me/policies	client.policies.list()	aether365 policies
Remediační schopnosti	GET /tenants/me/remediation/capabilities	client.remediation.capabilities()	aether365 remediation capabilities
Seznam remediačních plánů	GET /tenants/me/remediation-plans	client.remediation.plans()	aether365 remediation plans
Načtení remediačního plánu	GET /tenants/me/remediation-plans/{id}	client.remediation.plan(id)	aether365 remediation plan <id>
AI Pilot: remediovatelné položky	GET /tenants/me/ai-pilot/remediable	client.ai_pilot.remediable()	aether365 ai-pilot remediable
AI Pilot: break-glass účty	GET /tenants/me/ai-pilot/break-glass	client.ai_pilot.break_glass()	aether365 ai-pilot break-glass
AI Pilot: CA politiky	GET /tenants/me/ai-pilot/conditional-access	client.ai_pilot.conditional_access()	aether365 ai-pilot conditional-access

Remediace je pro API klíče pouze pro čtení. Aplikace plánu není zpřístupněna: položky plánu z registru akcí mohou obsahovat úpravy Conditional Access / authorization policy, které by tenanta zamkly mimo jeho vlastní adresář (AADSTS50097), takže apply zůstává v dashboardu s operátorem ve smyčce. Ze stejného důvodu jsou conditional-access a break-glass v AI Pilotu rovněž jen pro čtení.

Zpracování chyb a opakování

Každá chyba API se mapuje na typovanou výjimku odvozenou od 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.")

Klient automaticky opakuje 429 RATE_LIMITED a 503 SERVICE_STARTING (zahřívání studené databáze v dev prostředí) s exponenciálním backoffem a respektuje hlavičku Retry-After. Chyby kvót, jako SCAN_PLAN_LIMIT_REACHED, jsou vyhozeny okamžitě - neopakují se.

Použití CLI v CI

aether365 scan results <id> --fail-on-findings skončí s kódem 2, pokud existuje jakýkoli neúspěšný nález, takže pipeline může výsledky skenu použít jako bránu:

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

CLI vypisuje chyby na stderr a končí kódem 1 při jakékoli chybě API a kódem 2 na bráně nálezů.