Python SDK ja CLI

Ylläpitäjä: Aether365-tiimi Kohderyhmä: Kehittäjät ja DevOps-insinöörit Laajuus: Virallisen aether365 Python SDK:n ja komentorivityökalun asennus ja käyttö

aether365-paketti on Aether365 API:n virallinen Python SDK ja komentorivityökalu. Se kapseloi osoitteen https://api.aether365.io, hoitaa todennuksen, purkaa vastauskuoren ja yrittää ohimeneviä virheitä automaattisesti uudelleen. Kaiken minkä voit tehdä curl-komennolla, voit tehdä myös SDK:lla tai CLI:llä.

SDK ja CLI käyttävät API-avainta (ak_live_...) ja kohdistavat pyynnöt yhtenäiseen päätepisteeseen: pyynnöt reititetään automaattisesti tenantisi kotialueelle. Katso Todennus, miten avaimet toimivat.

Asennus

Pakettia jaellaan sisäisesti (ei PyPI:ssä). Asenna se suoraan repositorysta tai paikallisesta checkoutista.

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

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

Vaaditaan Python 3.12 tai uudempi. Paketin asennus lisää myös aether365-komennon PATH-polkuusi.

Konfigurointi

Sekä SDK että CLI lukevat samat ympäristömuuttujat:

Muuttuja	Tarkoitus	Oletus
AETHER365_API_KEY	API-avaimesi (ak_live_...). Pakollinen.	-
AETHER365_API_URL	Ohittaa perus-URL:n (esimerkiksi dev-päätepisteen).	https://api.aether365.io
AETHER365_OUTPUT	CLI:n tulostemuoto: table tai json.	table

export AETHER365_API_KEY="ak_live_..."

Alue on automaattinen: API tunnistaa tenantin avaimesta ja välittää pyynnön oikealle alueelle, joten aluetta ei koskaan tarvitse konfiguroida eikä välittää.

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

Pikaopas: 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ä API-avaimella voi ja ei voi tehdä

API-avain on rajattu turvalliseen luku- ja operointipintaan. Sillä voi lukea datasi, käynnistää ja hallita skannauksia, tuottaa raportteja ja hallita hyökkäyspinnan kohteita. Sillä ei voi suorittaa tilinhallintaan tai hakemistosta lukitsemiseen liittyviä toimia: API-avainten hallintaa, laskutusta, tiimin jäsenyyksiä, yhteyksien lisäystä ja poistoa, SSO:ta, remediation-suunnitelman soveltamista tai AI Pilotin conditional-access/break-glass-kirjoituksia. Ne ovat käytettävissä vain kirjautuneessa istunnossa dashboardissa. Pyyntö kiellettyyn reittiin palauttaa 403 AUTH_INSUFFICIENT_SCOPE.

Komento- ja metodiviite

Jokainen rivi näyttää saman toiminnon kolmella tavalla: raakana curl-kutsuna, SDK-metodina ja CLI-komentona.

Tenant ja tili

Toiminto	curl	SDK	CLI
Hae tenant-profiili	GET /tenants/me	client.tenants.me()	aether365 tenant me
Listaa yhteydet	GET /tenants/me/connections	client.connections.list()	aether365 tenant connections
Ilmoitusasetukset	GET /tenants/me/notifications	client.notifications.get()	aether365 tenant notifications
Ajastetut skannaukset	GET /tenants/me/scheduled-scans	client.scheduled_scans.list()	aether365 tenant scheduled-scans

Skannaukset

Toiminto	curl	SDK	CLI
Listaa skannaukset	GET /tenants/me/scans	client.scans.list()	aether365 scan list
Käynnistä skannaus	POST /tenants/me/scans	client.scans.create("compliance")	aether365 scan run --type compliance
Hae skannaus	GET /scans/{id}	client.scans.get(id)	aether365 scan get <id>
Lue tulokset	GET /scans/{id}/results	client.scans.results(id)	aether365 scan results <id>
Peruuta skannaus	POST /scans/{id}/cancel	client.scans.cancel(id)	aether365 scan cancel <id>
Piilota skannaus	PATCH /scans/{id}/hide	client.scans.hide(id)	aether365 scan hide <id>
Palauta skannaus näkyviin	PATCH /scans/{id}/unhide	client.scans.unhide(id)	aether365 scan unhide <id>
Poista skannaus	DELETE /scans/{id}	client.scans.delete(id)	aether365 scan delete <id>

Skannauksen käynnistävä 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"}'

Raportit

Toiminto	curl	SDK	CLI
Raportin tila	GET /scans/{id}/report	client.reports.status(id)	aether365 report status <id>
Luo raportti	POST /scans/{id}/report/generate	client.reports.generate(id)	aether365 report generate <id>
Listaa raportit	GET /tenants/me/reports	client.reports.list()	aether365 report list
Lataa raportti	GET /scans/{id}/report (presigned)	client.reports.download(id, path)	aether365 report download <id> -o out.pdf

Raportin tila on jokin seuraavista: ready, rendering, orgNameRequired tai locked. Raportin luonti voi kuluttaa raporttikrediitin (kertaveloitus, kun tilaukseen ei sisälly krediittikiintiötä): avaimen omistaja hyväksyy tämän kutsumalla generatea.

Raporttilistaus on offset-sivutettu: välitä meta["nextCursor"] (kokonaislukumuotoinen rivioffset, viimeisellä sivulla None) takaisin cursor-parametrina. client.reports.iter_all() seuraa kursoria puolestasi.

Hyökkäyspinta

Toiminto	curl	SDK	CLI
Yleiskuva	GET /tenants/me/attack-surface	client.attack_surface.summary()	aether365 eas summary
Historia	GET /tenants/me/attack-surface/history	client.attack_surface.history()	aether365 eas history
Listaa kohteet	GET /tenants/me/attack-surface/targets	client.attack_surface.targets()	aether365 eas targets list
Lisää kohde	POST /tenants/me/attack-surface/targets	client.attack_surface.add_target(host)	aether365 eas targets add <host>
Päivitä kohde	PATCH /tenants/me/attack-surface/targets/{id}	client.attack_surface.update_target(id, ...)	aether365 eas targets update <id> --label ...
Poista kohde	DELETE /tenants/me/attack-surface/targets/{id}	client.attack_surface.remove_target(id)	aether365 eas targets remove <id>
Vahvista kohde	POST /tenants/me/attack-surface/targets/{id}/verify	client.attack_surface.verify_target(id)	aether365 eas targets verify <id>
Aja EAS-skannaus	POST /tenants/me/attack-surface/scan	client.attack_surface.scan()	aether365 eas scan

Tietoturva-asento, remediation ja AI Pilot

Toiminto	curl	SDK	CLI
Uhka- ja riskinäkymä	GET /tenants/me/threats	client.threats.list()	aether365 threats
Käytäntöjen tila	GET /tenants/me/policies	client.policies.list()	aether365 policies
Remediation-kyvykkyydet	GET /tenants/me/remediation/capabilities	client.remediation.capabilities()	aether365 remediation capabilities
Listaa remediation-suunnitelmat	GET /tenants/me/remediation-plans	client.remediation.plans()	aether365 remediation plans
Hae remediation-suunnitelma	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-käytännöt	GET /tenants/me/ai-pilot/conditional-access	client.ai_pilot.conditional_access()	aether365 ai-pilot conditional-access

Remediation on API-avaimille vain luku. Suunnitelman soveltamista ei tarjota: suunnitelman action-registry-kohteet voivat sisältää Conditional-Access / authorization-policy-muutoksia, jotka lukitsisivat tenantin ulos omasta hakemistostaan (AADSTS50097), joten soveltaminen pysyy dashboardissa operaattorin valvonnassa. AI Pilotin conditional-access ja break-glass ovat samasta syystä niin ikään vain luettavissa.

Virheenkäsittely ja uudelleenyritykset

Jokainen API-virhe vastaa tyypitettyä poikkeusta, joka on Aether365Error-luokan aliluokka:

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

Client yrittää automaattisesti uudelleen virheet 429 RATE_LIMITED ja 503 SERVICE_STARTING (dev-ympäristön kylmän tietokannan lämpeneminen) eksponentiaalisella backoffilla ja noudattaa Retry-After-otsaketta. Kiintiövirheet, kuten SCAN_PLAN_LIMIT_REACHED, nostetaan heti: niitä ei yritetä uudelleen.

CLI:n käyttö CI:ssä

aether365 scan results <id> --fail-on-findings päättyy poistumiskoodilla 2, kun yksikin epäonnistunut löydös on olemassa, joten pipeline voi portittaa skannaustulosten perusteella:

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

CLI kirjoittaa virheet stderriin ja poistuu koodilla 1 missä tahansa API-virheessä ja koodilla 2 löydösportissa.