Python SDK a CLI

Balík aether365 je oficiálne Python SDK a rozhranie príkazového riadka pre Aether365 API. Obaľuje https://api.aether365.io, rieši autentifikáciu, rozbaľuje obálku odpovede a prechodné zlyhania automaticky opakuje. Všetko, čo zvládnete cez curl, zvládnete aj cez SDK alebo CLI.

SDK aj CLI používajú API kľúč (ak_live_...) a smerujú na zjednotený endpoint - požiadavky sa automaticky presmerujú do domovského regiónu vášho tenanta. Ako kľúče fungujú, opisuje stránka Autentifikácia.

Inštalácia

Balík sa distribuuje interne (nie je na PyPI). Nainštalujte ho priamo z repozitára alebo z lokálneho checkoutu.

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

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

Vyžaduje sa Python 3.12 alebo novší. Inštalácia balíka zároveň pridá príkaz aether365 do PATH.

Konfigurácia

SDK aj CLI čítajú rovnaké premenné prostredia:

Premenná	Účel	Predvolené
AETHER365_API_KEY	Váš API kľúč (ak_live_...). Povinné.	-
AETHER365_API_URL	Prepísanie základnej URL (napríklad dev endpoint).	https://api.aether365.io
AETHER365_OUTPUT	Výstupný formát CLI: table alebo json.	table

export AETHER365_API_KEY="ak_live_..."

Región je automatický: API podľa kľúča určí vášho tenanta a požiadavku odovzdá do správneho regiónu, takže región nikdy nekonfigurujete ani neposielate.

Rýchly štart: 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")

Rýchly štart: 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

Čo API kľúč môže a čo nemôže

API kľúč je obmedzený na bezpečnú plochu: čítanie plus prevádzkové operácie. Môže čítať vaše dáta, spúšťať a spravovať skeny, generovať reporty a spravovať ciele attack surface. Nemôže vykonávať akcie ovládajúce účet ani akcie, ktoré by mohli uzamknúť adresár - správu API kľúčov, fakturáciu, členstvo v tíme, pripájanie a odpájanie connectionov, SSO, aplikovanie remediačného plánu ani zápisy AI Pilota do conditional access / break-glass. Tie zostávajú dostupné len prihlásenej relácii v dashboarde. Požiadavka na nepovolenú cestu vracia 403 AUTH_INSUFFICIENT_SCOPE.

Prehľad príkazov a metód

Každý riadok ukazuje tú istú operáciu tromi spôsobmi: čistý curl, metóda SDK a príkaz CLI.

Tenant a účet

Operácia	curl	SDK	CLI
Profil tenanta	GET /tenants/me	client.tenants.me()	aether365 tenant me
Zoznam pripojení	GET /tenants/me/connections	client.connections.list()	aether365 tenant connections
Predvoľby notifikácií	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

Operácia	curl	SDK	CLI
Zoznam skenov	GET /tenants/me/scans	client.scans.list()	aether365 scan list
Spustenie skenu	POST /tenants/me/scans	client.scans.create("compliance")	aether365 scan run --type compliance
Načítanie skenu	GET /scans/{id}	client.scans.get(id)	aether365 scan get <id>
Čítanie výsledkov	GET /scans/{id}/results	client.scans.results(id)	aether365 scan results <id>
Zrušenie skenu	POST /scans/{id}/cancel	client.scans.cancel(id)	aether365 scan cancel <id>
Skrytie skenu	PATCH /scans/{id}/hide	client.scans.hide(id)	aether365 scan hide <id>
Zrušenie skrytia skenu	PATCH /scans/{id}/unhide	client.scans.unhide(id)	aether365 scan unhide <id>
Zmazanie skenu	DELETE /scans/{id}	client.scans.delete(id)	aether365 scan delete <id>

curl na spustenie 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

Operácia	curl	SDK	CLI
Stav reportu	GET /scans/{id}/report	client.reports.status(id)	aether365 report status <id>
Vygenerovanie reportu	POST /scans/{id}/report/generate	client.reports.generate(id)	aether365 report generate <id>
Zoznam reportov	GET /tenants/me/reports	client.reports.list()	aether365 report list
Stiahnutie reportu	GET /scans/{id}/report (presigned)	client.reports.download(id, path)	aether365 report download <id> -o out.pdf

Stav reportu je jedna z hodnôt ready, rendering, orgNameRequired alebo locked. Vygenerovanie reportu môže spotrebovať reportový kredit (jednorazový poplatok, keď plán nezahŕňa žiadny kredit) - vlastník kľúča s tým súhlasí tým, že zavolá generate.

Výpis reportov je stránkovaný offsetom: hodnotu meta["nextCursor"] (celočíselný offset riadka, alebo None na poslednej stránke) pošlite späť ako cursor. client.reports.iter_all() kurzor sleduje za vás.

Attack surface

Operácia	curl	SDK	CLI
Prehľad	GET /tenants/me/attack-surface	client.attack_surface.summary()	aether365 eas summary
História	GET /tenants/me/attack-surface/history	client.attack_surface.history()	aether365 eas history
Zoznam cieľov	GET /tenants/me/attack-surface/targets	client.attack_surface.targets()	aether365 eas targets list
Pridanie cieľa	POST /tenants/me/attack-surface/targets	client.attack_surface.add_target(host)	aether365 eas targets add <host>
Aktualizácia cieľa	PATCH /tenants/me/attack-surface/targets/{id}	client.attack_surface.update_target(id, ...)	aether365 eas targets update <id> --label ...
Zmazanie cieľa	DELETE /tenants/me/attack-surface/targets/{id}	client.attack_surface.remove_target(id)	aether365 eas targets remove <id>
Overenie cieľa	POST /tenants/me/attack-surface/targets/{id}/verify	client.attack_surface.verify_target(id)	aether365 eas targets verify <id>
Spustenie EAS skenu	POST /tenants/me/attack-surface/scan	client.attack_surface.scan()	aether365 eas scan

Bezpečnostný postoj, remediácia a AI Pilot

Operácia	curl	SDK	CLI
Pohľad na hrozby a riziká	GET /tenants/me/threats	client.threats.list()	aether365 threats
Stav politík	GET /tenants/me/policies	client.policies.list()	aether365 policies
Remediačné schopnosti	GET /tenants/me/remediation/capabilities	client.remediation.capabilities()	aether365 remediation capabilities
Zoznam remediačných plánov	GET /tenants/me/remediation-plans	client.remediation.plans()	aether365 remediation plans
Načítanie remediačného plánu	GET /tenants/me/remediation-plans/{id}	client.remediation.plan(id)	aether365 remediation plan <id>
AI Pilot: remediovateľné 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

Remediácia je pre API kľúče iba na čítanie. Aplikovanie plánu nie je sprístupnené: položky plánu z registra akcií môžu obsahovať úpravy Conditional Access / authorization policy, ktoré by tenanta zamkli mimo jeho vlastného adresára (AADSTS50097), takže apply zostáva v dashboarde s operátorom v slučke. Z rovnakého dôvodu sú conditional-access a break-glass v AI Pilote takisto len na čítanie.

Spracovanie chýb a opakovanie

Každá chyba API sa mapuje na typovanú výnimku odvodenú 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 (zahrievanie studenej databázy v dev prostredí) s exponenciálnym backoffom a rešpektuje hlavičku Retry-After. Chyby kvót ako SCAN_PLAN_LIMIT_REACHED sa vyhadzujú okamžite - neopakujú sa.

Použitie CLI v CI

aether365 scan results <id> --fail-on-findings skončí s kódom 2, keď existuje akýkoľvek neúspešný nález, takže pipeline môže výsledky skenu použiť ako bránu:

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

CLI vypisuje chyby na stderr a končí kódom 1 pri akejkoľvek chybe API a kódom 2 na bráne nálezov.