Python SDK és CLI

Az aether365 csomag az Aether365 API hivatalos Python SDK-ja és parancssori felülete. Becsomagolja a https://api.aether365.io végpontot, kezeli a hitelesítést, kibontja a válaszborítékot, és az átmeneti hibákat automatikusan újrapróbálja. Amit curl-lel meg tudsz csinálni, azt az SDK-val vagy a CLI-vel is megteheted.

Az SDK és a CLI API-kulcsot (ak_live_...) használ, és az egységes végpontot célozza: a kérések automatikusan a tenant elsődleges régiójába kerülnek. A kulcsok működéséről a Hitelesítés oldalon olvashatsz.

Telepítés

A csomagot belsőleg terjesztjük (nincs a PyPI-on). Telepítsd közvetlenül a repository-ból vagy egy helyi checkoutból.

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

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

Python 3.12 vagy újabb szükséges. A csomag telepítése az aether365 parancsot is felteszi a PATH-ra.

Konfiguráció

Az SDK és a CLI ugyanazokat a környezeti változókat olvassa:

Változó	Cél	Alapértelmezés
AETHER365_API_KEY	Az API-kulcsod (ak_live_...). Kötelező.	-
AETHER365_API_URL	Felülírja az alap URL-t (például a dev végpontra).	https://api.aether365.io
AETHER365_OUTPUT	A CLI kimeneti formátuma: table vagy json.	table

export AETHER365_API_KEY="ak_live_..."

A régió automatikus: az API a kulcs alapján azonosítja a tenantot, és a megfelelő régióba továbbítja a kérést, így régiót soha nem kell beállítanod vagy átadnod.

Gyorsindítás: 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")

Gyorsindítás: 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

Mit tud egy API-kulcs, és mit nem

Az API-kulcs egy biztonságos, olvasásra és üzemeltetési műveletekre szűkített felületre korlátozódik. Olvashatja az adataidat, indíthat és kezelhet vizsgálatokat, generálhat riportokat, és kezelheti az attack-surface célpontokat. Nem hajthat végre fiókkezelési vagy a címtárból való kizárással járó műveleteket: API-kulcsok kezelése, számlázás, csapattagság, kapcsolatok felvétele/leválasztása, SSO, remediation terv alkalmazása, illetve az AI Pilot conditional-access/break-glass írásai. Ezek csak a dashboardon, bejelentkezett munkamenetből érhetők el. A nem engedélyezett útvonalra küldött kérés 403 AUTH_INSUFFICIENT_SCOPE hibát ad vissza.

Parancs- és metódusreferencia

Minden sor ugyanazt a műveletet mutatja három módon: nyers curl, SDK-metódus és CLI-parancs.

Tenant és fiók

Művelet	curl	SDK	CLI
Tenant profil lekérése	GET /tenants/me	client.tenants.me()	aether365 tenant me
Kapcsolatok listázása	GET /tenants/me/connections	client.connections.list()	aether365 tenant connections
Értesítési beállítások	GET /tenants/me/notifications	client.notifications.get()	aether365 tenant notifications
Ütemezett vizsgálatok	GET /tenants/me/scheduled-scans	client.scheduled_scans.list()	aether365 tenant scheduled-scans

Vizsgálatok

Művelet	curl	SDK	CLI
Vizsgálatok listázása	GET /tenants/me/scans	client.scans.list()	aether365 scan list
Vizsgálat indítása	POST /tenants/me/scans	client.scans.create("compliance")	aether365 scan run --type compliance
Vizsgálat lekérése	GET /scans/{id}	client.scans.get(id)	aether365 scan get <id>
Eredmények olvasása	GET /scans/{id}/results	client.scans.results(id)	aether365 scan results <id>
Vizsgálat megszakítása	POST /scans/{id}/cancel	client.scans.cancel(id)	aether365 scan cancel <id>
Vizsgálat elrejtése	PATCH /scans/{id}/hide	client.scans.hide(id)	aether365 scan hide <id>
Elrejtés visszavonása	PATCH /scans/{id}/unhide	client.scans.unhide(id)	aether365 scan unhide <id>
Vizsgálat törlése	DELETE /scans/{id}	client.scans.delete(id)	aether365 scan delete <id>

A vizsgálatot indító curl:

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

Riportok

Művelet	curl	SDK	CLI
Riport állapota	GET /scans/{id}/report	client.reports.status(id)	aether365 report status <id>
Riport generálása	POST /scans/{id}/report/generate	client.reports.generate(id)	aether365 report generate <id>
Riportok listázása	GET /tenants/me/reports	client.reports.list()	aether365 report list
Riport letöltése	GET /scans/{id}/report (presigned)	client.reports.download(id, path)	aether365 report download <id> -o out.pdf

A riport állapota a következők egyike: ready, rendering, orgNameRequired vagy locked. A riport generálása riportkreditet fogyaszthat (egyszeri díj, ha a csomag nem tartalmaz keretet): ebbe a kulcs tulajdonosa a generate meghívásával egyezik bele.

A riportlista offset alapon lapozott: add vissza a meta["nextCursor"] értéket (egész számú sor-offset, az utolsó oldalon None) cursor-ként. A client.reports.iter_all() magától követi a cursort.

Attack surface

Művelet	curl	SDK	CLI
Áttekintés	GET /tenants/me/attack-surface	client.attack_surface.summary()	aether365 eas summary
Előzmények	GET /tenants/me/attack-surface/history	client.attack_surface.history()	aether365 eas history
Célpontok listázása	GET /tenants/me/attack-surface/targets	client.attack_surface.targets()	aether365 eas targets list
Célpont hozzáadása	POST /tenants/me/attack-surface/targets	client.attack_surface.add_target(host)	aether365 eas targets add <host>
Célpont frissítése	PATCH /tenants/me/attack-surface/targets/{id}	client.attack_surface.update_target(id, ...)	aether365 eas targets update <id> --label ...
Célpont törlése	DELETE /tenants/me/attack-surface/targets/{id}	client.attack_surface.remove_target(id)	aether365 eas targets remove <id>
Célpont ellenőrzése	POST /tenants/me/attack-surface/targets/{id}/verify	client.attack_surface.verify_target(id)	aether365 eas targets verify <id>
EAS vizsgálat futtatása	POST /tenants/me/attack-surface/scan	client.attack_surface.scan()	aether365 eas scan

Biztonsági állapot, remediation és AI Pilot

Művelet	curl	SDK	CLI
Fenyegetés- / kockázati nézet	GET /tenants/me/threats	client.threats.list()	aether365 threats
Szabályzatállapot	GET /tenants/me/policies	client.policies.list()	aether365 policies
Remediation képességek	GET /tenants/me/remediation/capabilities	client.remediation.capabilities()	aether365 remediation capabilities
Remediation tervek listázása	GET /tenants/me/remediation-plans	client.remediation.plans()	aether365 remediation plans
Remediation terv lekérése	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 szabályzatok	GET /tenants/me/ai-pilot/conditional-access	client.ai_pilot.conditional_access()	aether365 ai-pilot conditional-access

A remediation API-kulccsal csak olvasható. A terv alkalmazása nem érhető el: egy terv action-registry elemei tartalmazhatnak olyan Conditional-Access / authorization-policy patcheket, amelyek kizárnák a tenantot a saját címtárából (AADSTS50097), ezért az alkalmazás a dashboardon marad, operátorral a folyamatban. Az AI Pilot conditional-access és break-glass ugyanezen okból szintén csak olvasható.

Hibakezelés és újrapróbálkozás

Minden API-hiba egy típusos kivételre képződik le, amely az Aether365Error leszármazottja:

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.")

A kliens automatikusan újrapróbálja a 429 RATE_LIMITED és az 503 SERVICE_STARTING (a dev hideg adatbázisának bemelegedése) hibákat exponenciális backoffal, a Retry-After fejlécet tiszteletben tartva. A kvótahibák, mint a SCAN_PLAN_LIMIT_REACHED, azonnal kivételt dobnak: ezeket nem próbálja újra.

A CLI használata CI-ban

Az aether365 scan results <id> --fail-on-findings 2-es kilépési kóddal áll le, ha akár egyetlen sikertelen találat is van, így egy pipeline a vizsgálati eredmények alapján kapuzhat:

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

A CLI a hibákat az stderr-re írja, és bármilyen API-hiba esetén 1, a találati kapunál 2 kóddal lép ki.