Python SDK ja CLI

aether365 pakett on Aether365 API ametlik Python SDK ja käsurealiides. See mähib endasse https://api.aether365.io, hoolitseb autentimise eest, pakib lahti vastuse ümbrise ja proovib mööduvaid tõrkeid automaatselt uuesti. Kõike, mida saad teha curl-iga, saad teha ka SDK või CLI kaudu.

SDK ja CLI kasutavad API võtit (ak_live_...) ja sihivad ühtset otspunkti: päringud suunatakse automaatselt sinu tenant'i koduregiooni. Kuidas võtmed töötavad, loe lehelt Autentimine.

Paigaldus

Paketti levitatakse sisemiselt (mitte PyPI kaudu). Paigalda see otse repositooriumist või kohalikust checkoutist.

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

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

Nõutav on Python 3.12 või uuem. Paketi paigaldamine lisab ka käsu aether365 sinu PATH-i.

Seadistamine

Nii SDK kui ka CLI loevad samu keskkonnamuutujaid:

Muutuja	Otstarve	Vaikimisi
AETHER365_API_KEY	Sinu API võti (ak_live_...). Kohustuslik.	-
AETHER365_API_URL	Asendab baas-URL-i (näiteks dev-otspunktiga).	https://api.aether365.io
AETHER365_OUTPUT	CLI väljundivorming: table või json.	table

export AETHER365_API_KEY="ak_live_..."

Regioon on automaatne: API tuvastab tenant'i võtme järgi ja edastab päringu õigesse regiooni, nii et regiooni ei pea kunagi seadistama ega kaasa andma.

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

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

Mida API võti saab ja mida ei saa teha

API võti on piiratud turvalise lugemis- ja tööoperatsioonide pinnaga. See saab lugeda sinu andmeid, käivitada ja hallata skannimisi, genereerida raporteid ning hallata ründepinna sihtmärke. See ei saa teha konto haldamise ega kataloogist väljalukustamise toiminguid: API võtmete haldus, arveldus, meeskonna liikmesus, ühenduste lisamine ja eemaldamine, SSO, remediation-plaani rakendamine ega AI Piloti conditional-access/break-glass kirjutused. Need jäävad kättesaadavaks ainult dashboardi sisselogitud seansile. Päring keelatud marsruudile tagastab 403 AUTH_INSUFFICIENT_SCOPE.

Käskude ja meetodite viide

Iga rida näitab sama toimingut kolmel viisil: toores curl, SDK meetod ja CLI käsk.

Tenant ja konto

Toiming	curl	SDK	CLI
Tenant'i profiili pärimine	GET /tenants/me	client.tenants.me()	aether365 tenant me
Ühenduste loend	GET /tenants/me/connections	client.connections.list()	aether365 tenant connections
Teavituseelistused	GET /tenants/me/notifications	client.notifications.get()	aether365 tenant notifications
Plaanitud skannimised	GET /tenants/me/scheduled-scans	client.scheduled_scans.list()	aether365 tenant scheduled-scans

Skannimised

Toiming	curl	SDK	CLI
Skannimiste loend	GET /tenants/me/scans	client.scans.list()	aether365 scan list
Skannimise käivitamine	POST /tenants/me/scans	client.scans.create("compliance")	aether365 scan run --type compliance
Skannimise pärimine	GET /scans/{id}	client.scans.get(id)	aether365 scan get <id>
Tulemuste lugemine	GET /scans/{id}/results	client.scans.results(id)	aether365 scan results <id>
Skannimise katkestamine	POST /scans/{id}/cancel	client.scans.cancel(id)	aether365 scan cancel <id>
Skannimise peitmine	PATCH /scans/{id}/hide	client.scans.hide(id)	aether365 scan hide <id>
Peidust välja toomine	PATCH /scans/{id}/unhide	client.scans.unhide(id)	aether365 scan unhide <id>
Skannimise kustutamine	DELETE /scans/{id}	client.scans.delete(id)	aether365 scan delete <id>

curl skannimise käivitamiseks:

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

Raportid

Toiming	curl	SDK	CLI
Raporti olek	GET /scans/{id}/report	client.reports.status(id)	aether365 report status <id>
Raporti genereerimine	POST /scans/{id}/report/generate	client.reports.generate(id)	aether365 report generate <id>
Raportite loend	GET /tenants/me/reports	client.reports.list()	aether365 report list
Raporti allalaadimine	GET /scans/{id}/report (presigned)	client.reports.download(id, path)	aether365 report download <id> -o out.pdf

Raporti olek on üks järgmistest: ready, rendering, orgNameRequired või locked. Raporti genereerimine võib kulutada raportikrediidi (ühekordne tasu, kui plaan ei sisalda kvooti): võtme omanik nõustub sellega generate'i välja kutsudes.

Raportite loend on offset-põhiselt lehekülgedeks jaotatud: saada meta["nextCursor"] (täisarvuline reanihe, viimasel lehel None) tagasi cursor-ina. client.reports.iter_all() järgib kursorit sinu eest.

Ründepind

Toiming	curl	SDK	CLI
Ülevaade	GET /tenants/me/attack-surface	client.attack_surface.summary()	aether365 eas summary
Ajalugu	GET /tenants/me/attack-surface/history	client.attack_surface.history()	aether365 eas history
Sihtmärkide loend	GET /tenants/me/attack-surface/targets	client.attack_surface.targets()	aether365 eas targets list
Sihtmärgi lisamine	POST /tenants/me/attack-surface/targets	client.attack_surface.add_target(host)	aether365 eas targets add <host>
Sihtmärgi uuendamine	PATCH /tenants/me/attack-surface/targets/{id}	client.attack_surface.update_target(id, ...)	aether365 eas targets update <id> --label ...
Sihtmärgi kustutamine	DELETE /tenants/me/attack-surface/targets/{id}	client.attack_surface.remove_target(id)	aether365 eas targets remove <id>
Sihtmärgi kinnitamine	POST /tenants/me/attack-surface/targets/{id}/verify	client.attack_surface.verify_target(id)	aether365 eas targets verify <id>
EAS-skannimise käivitamine	POST /tenants/me/attack-surface/scan	client.attack_surface.scan()	aether365 eas scan

Turvaseis, remediation ja AI Pilot

Toiming	curl	SDK	CLI
Ohtude ja riskide vaade	GET /tenants/me/threats	client.threats.list()	aether365 threats
Poliitikate seis	GET /tenants/me/policies	client.policies.list()	aether365 policies
Remediation-võimekused	GET /tenants/me/remediation/capabilities	client.remediation.capabilities()	aether365 remediation capabilities
Remediation-plaanide loend	GET /tenants/me/remediation-plans	client.remediation.plans()	aether365 remediation plans
Remediation-plaani pärimine	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-poliitikad	GET /tenants/me/ai-pilot/conditional-access	client.ai_pilot.conditional_access()	aether365 ai-pilot conditional-access

Remediation on API võtmete jaoks ainult lugemiseks. Plaani rakendamist ei pakuta: plaani action-registry kirjed võivad sisaldada Conditional-Access / authorization-policy muudatusi, mis lukustaksid tenant'i tema enda kataloogist välja (AADSTS50097), seega jääb rakendamine dashboardi, kus operaator on protsessi kaasatud. AI Piloti conditional-access ja break-glass on samal põhjusel samuti ainult loetavad.

Veakäsitlus ja uuesti proovimine

Iga API viga vastab tüübitud erindile, mis on Aether365Error alamklass:

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 proovib automaatselt uuesti vigu 429 RATE_LIMITED ja 503 SERVICE_STARTING (dev-keskkonna külma andmebaasi soojenemine) eksponentsiaalse backoffiga, arvestades Retry-After päist. Kvoodivead, näiteks SCAN_PLAN_LIMIT_REACHED, tõstatatakse kohe: neid uuesti ei proovita.

CLI kasutamine CI-s

aether365 scan results <id> --fail-on-findings lõpetab väljumiskoodiga 2, kui leidub kas või üks ebaõnnestunud leid, nii et pipeline saab skannimistulemuste põhjal väravat pidada:

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

CLI kirjutab vead stderr-i ja väljub koodiga 1 iga API vea korral ning koodiga 2 leidude värava korral.