Python SDK in CLI

Paket aether365 je uradni Python SDK in vmesnik ukazne vrstice za Aether365 API. Ovija https://api.aether365.io, poskrbi za preverjanje pristnosti, razpakira ovojnico odgovora in prehodne napake samodejno ponovi. Vse, kar lahko naredite s curl, lahko naredite tudi s SDK-jem ali CLI-jem.

SDK in CLI uporabljata API ključ (ak_live_...) in ciljata na poenoten endpoint - zahteve se samodejno usmerijo v domačo regijo vašega tenanta. Kako ključi delujejo, opisuje stran Preverjanje pristnosti.

Namestitev

Paket se distribuira interno (ni na PyPI). Namestite ga neposredno iz repozitorija ali lokalne kopije.

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

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

Zahtevan je Python 3.12 ali novejši. Namestitev paketa doda tudi ukaz aether365 v PATH.

Konfiguracija

SDK in CLI bereta iste okoljske spremenljivke:

Spremenljivka	Namen	Privzeto
AETHER365_API_KEY	Vaš API ključ (ak_live_...). Obvezno.	-
AETHER365_API_URL	Prepis osnovnega URL-ja (na primer dev endpoint).	https://api.aether365.io
AETHER365_OUTPUT	Izhodni format CLI: table ali json.	table

export AETHER365_API_KEY="ak_live_..."

Regija je samodejna: API iz ključa razbere vašega tenanta in zahtevo posreduje v pravo regijo, zato regije nikoli ne konfigurirate niti je ne podajate.

Hitri začetek: 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")

Hitri začetek: 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

Kaj API ključ sme in česa ne

API ključ je omejen na varno površino: branje plus operativna opravila. Lahko bere vaše podatke, sproža in upravlja skene, generira poročila ter upravlja cilje attack surface. Ne more izvajati dejanj za nadzor računa ali dejanj, ki bi lahko zaklenila imenik - upravljanja API ključev, obračunavanja, članstva v ekipi, priklopa in odklopa povezav, SSO, uveljavitve načrta remediacije ali zapisov AI Pilota v conditional access / break-glass. Ta dejanja ostajajo na voljo samo prijavljeni seji v nadzorni plošči. Zahteva na nedovoljeno pot vrne 403 AUTH_INSUFFICIENT_SCOPE.

Pregled ukazov in metod

Vsaka vrstica prikazuje isto operacijo na tri načine: surov curl, metoda SDK in ukaz CLI.

Tenant in račun

Operacija	curl	SDK	CLI
Profil tenanta	GET /tenants/me	client.tenants.me()	aether365 tenant me
Seznam povezav	GET /tenants/me/connections	client.connections.list()	aether365 tenant connections
Nastavitve obvestil	GET /tenants/me/notifications	client.notifications.get()	aether365 tenant notifications
Načrtovani skeni	GET /tenants/me/scheduled-scans	client.scheduled_scans.list()	aether365 tenant scheduled-scans

Skeni

Operacija	curl	SDK	CLI
Seznam skenov	GET /tenants/me/scans	client.scans.list()	aether365 scan list
Sprožitev skena	POST /tenants/me/scans	client.scans.create("compliance")	aether365 scan run --type compliance
Pridobitev skena	GET /scans/{id}	client.scans.get(id)	aether365 scan get <id>
Branje rezultatov	GET /scans/{id}/results	client.scans.results(id)	aether365 scan results <id>
Preklic skena	POST /scans/{id}/cancel	client.scans.cancel(id)	aether365 scan cancel <id>
Skritje skena	PATCH /scans/{id}/hide	client.scans.hide(id)	aether365 scan hide <id>
Razkritje skena	PATCH /scans/{id}/unhide	client.scans.unhide(id)	aether365 scan unhide <id>
Izbris skena	DELETE /scans/{id}	client.scans.delete(id)	aether365 scan delete <id>

curl za sprožitev skena:

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

Poročila

Operacija	curl	SDK	CLI
Status poročila	GET /scans/{id}/report	client.reports.status(id)	aether365 report status <id>
Generiranje poročila	POST /scans/{id}/report/generate	client.reports.generate(id)	aether365 report generate <id>
Seznam poročil	GET /tenants/me/reports	client.reports.list()	aether365 report list
Prenos poročila	GET /scans/{id}/report (presigned)	client.reports.download(id, path)	aether365 report download <id> -o out.pdf

Status poročila je ena od vrednosti ready, rendering, orgNameRequired ali locked. Generiranje poročila lahko porabi kredit za poročila (enkratno plačilo, kadar paket ne vključuje kvote) - lastnik ključa v to privoli s klicem generate.

Seznam poročil je ostranjen z odmikom: vrednost meta["nextCursor"] (celoštevilski odmik vrstice ali None na zadnji strani) vrnite kot cursor. client.reports.iter_all() kazalcu sledi namesto vas.

Attack surface

Operacija	curl	SDK	CLI
Pregled	GET /tenants/me/attack-surface	client.attack_surface.summary()	aether365 eas summary
Zgodovina	GET /tenants/me/attack-surface/history	client.attack_surface.history()	aether365 eas history
Seznam ciljev	GET /tenants/me/attack-surface/targets	client.attack_surface.targets()	aether365 eas targets list
Dodajanje cilja	POST /tenants/me/attack-surface/targets	client.attack_surface.add_target(host)	aether365 eas targets add <host>
Posodobitev cilja	PATCH /tenants/me/attack-surface/targets/{id}	client.attack_surface.update_target(id, ...)	aether365 eas targets update <id> --label ...
Izbris cilja	DELETE /tenants/me/attack-surface/targets/{id}	client.attack_surface.remove_target(id)	aether365 eas targets remove <id>
Preverjanje cilja	POST /tenants/me/attack-surface/targets/{id}/verify	client.attack_surface.verify_target(id)	aether365 eas targets verify <id>
Zagon EAS skena	POST /tenants/me/attack-surface/scan	client.attack_surface.scan()	aether365 eas scan

Varnostna drža, remediacija in AI Pilot

Operacija	curl	SDK	CLI
Pogled groženj in tveganj	GET /tenants/me/threats	client.threats.list()	aether365 threats
Stanje politik	GET /tenants/me/policies	client.policies.list()	aether365 policies
Zmožnosti remediacije	GET /tenants/me/remediation/capabilities	client.remediation.capabilities()	aether365 remediation capabilities
Seznam načrtov remediacije	GET /tenants/me/remediation-plans	client.remediation.plans()	aether365 remediation plans
Pridobitev načrta remediacije	GET /tenants/me/remediation-plans/{id}	client.remediation.plan(id)	aether365 remediation plan <id>
AI Pilot: primerno za remediacijo	GET /tenants/me/ai-pilot/remediable	client.ai_pilot.remediable()	aether365 ai-pilot remediable
AI Pilot: računi break-glass	GET /tenants/me/ai-pilot/break-glass	client.ai_pilot.break_glass()	aether365 ai-pilot break-glass
AI Pilot: politike CA	GET /tenants/me/ai-pilot/conditional-access	client.ai_pilot.conditional_access()	aether365 ai-pilot conditional-access

Remediacija je za API ključe samo za branje. Uveljavitev načrta ni izpostavljena: postavke načrta iz registra dejanj lahko vključujejo popravke Conditional Access / authorization policy, ki bi tenantu zaklenili dostop do lastnega imenika (AADSTS50097), zato apply ostaja v nadzorni plošči z operaterjem v zanki. Iz istega razloga sta tudi conditional-access in break-glass v AI Pilotu izpostavljena samo za branje.

Obravnava napak in ponovni poskusi

Vsaka napaka API-ja se preslika v tipizirano izjemo, izpeljano iz 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.")

Odjemalec samodejno ponovi 429 RATE_LIMITED in 503 SERVICE_STARTING (ogrevanje hladne baze v dev okolju) z eksponentnim backoffom in pri tem upošteva glavo Retry-After. Napake kvot, kot je SCAN_PLAN_LIMIT_REACHED, se sprožijo takoj - ne ponavljajo se.

Uporaba CLI v CI

aether365 scan results <id> --fail-on-findings se konča s kodo 2, kadar obstaja katera koli neuspešna ugotovitev, zato lahko pipeline rezultate skena uporabi kot vrata:

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

CLI napake izpisuje na stderr in se konča s kodo 1 ob kateri koli napaki API-ja ter s kodo 2 na vratih za ugotovitve.