Python SDK ir CLI

Autorius: Aether365 komanda Auditorija: Kūrėjai ir DevOps inžinieriai Apimtis: Oficialaus aether365 Python SDK ir komandinės eilutės sąsajos diegimas ir naudojimas

aether365 paketas yra oficialus Aether365 API skirtas Python SDK ir komandinės eilutės įrankis. Jis apgaubia https://api.aether365.io, pasirūpina autentifikavimu, išpakuoja atsakymo apvalkalą ir automatiškai kartoja dėl laikinų trikdžių nepavykusias užklausas. Viską, ką galite atlikti su curl, galite atlikti ir per SDK arba CLI.

SDK ir CLI naudoja API raktą (ak_live_...) ir kreipiasi į vieningą galinį tašką - užklausos automatiškai nukreipiamos į jūsų tenant'o namų regioną. Kaip veikia raktai, aprašyta skiltyje Autentifikavimas.

Diegimas

Paketas platinamas tik viduje (jo nėra PyPI). Įdiekite jį tiesiai iš repozitorijos arba lokalios kodo kopijos.

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

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

Reikalinga Python 3.12 arba naujesnė versija. Įdiegus paketą, komanda aether365 atsiranda jūsų PATH.

Konfigūracija

Tiek SDK, tiek CLI skaito tuos pačius aplinkos kintamuosius:

Kintamasis	Paskirtis	Numatytoji reikšmė
AETHER365_API_KEY	Jūsų API raktas (ak_live_...). Privalomas.	-
AETHER365_API_URL	Pakeičia bazinį URL (pavyzdžiui, dev galinį tašką).	https://api.aether365.io
AETHER365_OUTPUT	CLI išvesties formatas: table arba json.	table

export AETHER365_API_KEY="ak_live_..."

Regionas nustatomas automatiškai: API pagal raktą atpažįsta jūsų tenant'ą ir persiunčia užklausą į teisingą regioną, todėl regiono niekada nereikia nei konfigūruoti, nei perduoti.

Greitas startas: 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")

Greitas startas: 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

Ką API raktas gali ir ko negali

API rakto aprėptis apsiriboja saugiu skaitymo ir operaciniu paviršiumi. Su juo galima skaityti jūsų duomenis, paleisti bei valdyti nuskaitymus, generuoti ataskaitas ir tvarkyti atakos paviršiaus taikinius. Jis negali atlikti paskyros valdymo ar katalogo užrakinimo veiksmų - API raktų valdymo, atsiskaitymų, komandos narystės, ryšių prijungimo ar atjungimo, SSO, taisymo plano taikymo ar AI Pilot sąlyginės prieigos / break-glass įrašymo veiksmų. Visa tai lieka prieinama tik prisijungusiai sesijai valdymo skydelyje. Užklausa į neleidžiamą maršrutą grąžina 403 AUTH_INSUFFICIENT_SCOPE.

Komandų ir metodų žinynas

Kiekviena eilutė rodo tą pačią operaciją trimis būdais: grynu curl, SDK metodu ir CLI komanda.

Tenant ir paskyra

Operacija	curl	SDK	CLI
Gauti tenant'o profilį	GET /tenants/me	client.tenants.me()	aether365 tenant me
Ryšių sąrašas	GET /tenants/me/connections	client.connections.list()	aether365 tenant connections
Pranešimų nustatymai	GET /tenants/me/notifications	client.notifications.get()	aether365 tenant notifications
Suplanuoti nuskaitymai	GET /tenants/me/scheduled-scans	client.scheduled_scans.list()	aether365 tenant scheduled-scans

Nuskaitymai

Operacija	curl	SDK	CLI
Nuskaitymų sąrašas	GET /tenants/me/scans	client.scans.list()	aether365 scan list
Paleisti nuskaitymą	POST /tenants/me/scans	client.scans.create("compliance")	aether365 scan run --type compliance
Gauti nuskaitymą	GET /scans/{id}	client.scans.get(id)	aether365 scan get <id>
Skaityti rezultatus	GET /scans/{id}/results	client.scans.results(id)	aether365 scan results <id>
Atšaukti nuskaitymą	POST /scans/{id}/cancel	client.scans.cancel(id)	aether365 scan cancel <id>
Paslėpti nuskaitymą	PATCH /scans/{id}/hide	client.scans.hide(id)	aether365 scan hide <id>
Vėl rodyti nuskaitymą	PATCH /scans/{id}/unhide	client.scans.unhide(id)	aether365 scan unhide <id>
Ištrinti nuskaitymą	DELETE /scans/{id}	client.scans.delete(id)	aether365 scan delete <id>

curl komanda nuskaitymui paleisti:

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

Ataskaitos

Operacija	curl	SDK	CLI
Ataskaitos būsena	GET /scans/{id}/report	client.reports.status(id)	aether365 report status <id>
Generuoti ataskaitą	POST /scans/{id}/report/generate	client.reports.generate(id)	aether365 report generate <id>
Ataskaitų sąrašas	GET /tenants/me/reports	client.reports.list()	aether365 report list
Atsisiųsti ataskaitą	GET /scans/{id}/report (presigned)	client.reports.download(id, path)	aether365 report download <id> -o out.pdf

Ataskaitos būsena yra viena iš ready, rendering, orgNameRequired arba locked. Ataskaitos generavimas gali sunaudoti ataskaitos kreditą (vienkartinis mokestis, kai kvota neįtraukta) - rakto savininkas su tuo sutinka pats, iškviesdamas generate.

Ataskaitų sąrašas puslapiuojamas poslinkiu: perduokite meta["nextCursor"] (sveikasis eilučių poslinkis arba None paskutiniame puslapyje) atgal kaip cursor. client.reports.iter_all() žymeklį seka už jus.

Atakos paviršius

Operacija	curl	SDK	CLI
Apžvalga	GET /tenants/me/attack-surface	client.attack_surface.summary()	aether365 eas summary
Istorija	GET /tenants/me/attack-surface/history	client.attack_surface.history()	aether365 eas history
Taikinių sąrašas	GET /tenants/me/attack-surface/targets	client.attack_surface.targets()	aether365 eas targets list
Pridėti taikinį	POST /tenants/me/attack-surface/targets	client.attack_surface.add_target(host)	aether365 eas targets add <host>
Atnaujinti taikinį	PATCH /tenants/me/attack-surface/targets/{id}	client.attack_surface.update_target(id, ...)	aether365 eas targets update <id> --label ...
Ištrinti taikinį	DELETE /tenants/me/attack-surface/targets/{id}	client.attack_surface.remove_target(id)	aether365 eas targets remove <id>
Patvirtinti taikinį	POST /tenants/me/attack-surface/targets/{id}/verify	client.attack_surface.verify_target(id)	aether365 eas targets verify <id>
Paleisti EAS nuskaitymą	POST /tenants/me/attack-surface/scan	client.attack_surface.scan()	aether365 eas scan

Saugumo būsena, taisymas ir AI Pilot

Operacija	curl	SDK	CLI
Grėsmių / rizikos vaizdas	GET /tenants/me/threats	client.threats.list()	aether365 threats
Politikų būsena	GET /tenants/me/policies	client.policies.list()	aether365 policies
Taisymo galimybės	GET /tenants/me/remediation/capabilities	client.remediation.capabilities()	aether365 remediation capabilities
Taisymo planų sąrašas	GET /tenants/me/remediation-plans	client.remediation.plans()	aether365 remediation plans
Gauti taisymo planą	GET /tenants/me/remediation-plans/{id}	client.remediation.plan(id)	aether365 remediation plan <id>
AI Pilot taisytini elementai	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 politikos	GET /tenants/me/ai-pilot/conditional-access	client.ai_pilot.conditional_access()	aether365 ai-pilot conditional-access

Taisymas API raktams yra tik skaitomas. Plano taikymas neatveriamas: plano veiksmų registro elementuose gali būti Conditional-Access / autorizavimo politikos pataisų, kurios užrakintų tenant'ą nuo jo paties katalogo (AADSTS50097), todėl taikymas lieka valdymo skydelyje, dalyvaujant operatoriui. Dėl tos pačios priežasties AI Pilot conditional-access ir break-glass taip pat prieinami tik skaitymui.

Klaidų apdorojimas ir kartojimai

Kiekviena API klaida atitinka tipizuotą išimtį - Aether365Error poklasį:

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

Klientas automatiškai kartoja 429 RATE_LIMITED ir 503 SERVICE_STARTING (dev šaltos duomenų bazės pašildymas) su eksponentiniu atidėjimu, atsižvelgdamas į Retry-After antraštę. Kvotos klaidos, tokios kaip SCAN_PLAN_LIMIT_REACHED, iškeliamos iš karto - jos nekartojamos.

CLI naudojimas CI aplinkoje

aether365 scan results <id> --fail-on-findings baigia darbą kodu 2, kai yra bent vienas nepavykęs radinys, todėl pipeline gali blokuoti pagal nuskaitymo rezultatus:

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

CLI klaidas rašo į stderr ir baigia darbą kodu 1 esant bet kokiai API klaidai bei kodu 2, kai suveikia radinių vartai.