Python SDK un CLI

Pakotne aether365 ir oficiālais Python SDK un komandrindas rīks darbam ar Aether365 API. Tā ietin https://api.aether365.io, parūpējas par autentifikāciju, izsaiņo atbildes aploksni un automātiski atkārto pieprasījumus, kas cietuši no īslaicīgiem traucējumiem. Visu, ko var izdarīt ar curl, var izdarīt arī ar SDK vai CLI.

SDK un CLI izmanto API atslēgu (ak_live_...) un vēršas pie vienotā galapunkta - pieprasījumi automātiski tiek novirzīti uz jūsu tenant mājas reģionu. Kā atslēgas darbojas, skatiet sadaļā Autentifikācija.

Instalēšana

Pakotne tiek izplatīta iekšēji (tā nav pieejama PyPI). Instalējiet to tieši no repozitorija vai lokālas koda kopijas.

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

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

Nepieciešams Python 3.12 vai jaunāks. Līdz ar pakotnes instalēšanu komanda aether365 nonāk jūsu PATH.

Konfigurācija

Gan SDK, gan CLI lasa vienus un tos pašus vides mainīgos:

Mainīgais	Nozīme	Noklusējums
AETHER365_API_KEY	Jūsu API atslēga (ak_live_...). Obligāta.	-
AETHER365_API_URL	Pārraksta bāzes URL (piemēram, dev galapunktu).	https://api.aether365.io
AETHER365_OUTPUT	CLI izvades formāts: table vai json.	table

export AETHER365_API_KEY="ak_live_..."

Reģions ir automātisks: API pēc atslēgas nosaka jūsu tenant un pārsūta pieprasījumu uz pareizo reģionu, tāpēc reģions nekad nav jākonfigurē un nav jānorāda.

Ātrais starts: 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")

Ātrais starts: 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

Ko API atslēga var un ko nevar

API atslēgas tvērums aprobežojas ar drošu lasīšanas un operacionālo virsmu. Ar to var lasīt jūsu datus, palaist un pārvaldīt skenēšanas, ģenerēt pārskatus un pārvaldīt uzbrukuma virsmas mērķus. Tā nevar veikt konta pārvaldības vai direktorija bloķēšanas darbības - API atslēgu pārvaldību, norēķinus, komandas dalību, savienojumu pievienošanu vai atvienošanu, SSO, novēršanas plāna piemērošanu vai AI Pilot nosacītās piekļuves / break-glass rakstīšanas darbības. Tās joprojām ir pieejamas tikai pierakstītai sesijai informācijas panelī. Pieprasījums uz neatļautu maršrutu atgriež 403 AUTH_INSUFFICIENT_SCOPE.

Komandu un metožu atsauce

Katra rinda parāda vienu un to pašu operāciju trīs veidos: tīrs curl, SDK metode un CLI komanda.

Tenant un konts

Operācija	curl	SDK	CLI
Iegūt tenant profilu	GET /tenants/me	client.tenants.me()	aether365 tenant me
Savienojumu saraksts	GET /tenants/me/connections	client.connections.list()	aether365 tenant connections
Paziņojumu iestatījumi	GET /tenants/me/notifications	client.notifications.get()	aether365 tenant notifications
Ieplānotās skenēšanas	GET /tenants/me/scheduled-scans	client.scheduled_scans.list()	aether365 tenant scheduled-scans

Skenēšanas

Operācija	curl	SDK	CLI
Skenēšanu saraksts	GET /tenants/me/scans	client.scans.list()	aether365 scan list
Palaist skenēšanu	POST /tenants/me/scans	client.scans.create("compliance")	aether365 scan run --type compliance
Iegūt skenēšanu	GET /scans/{id}	client.scans.get(id)	aether365 scan get <id>
Lasīt rezultātus	GET /scans/{id}/results	client.scans.results(id)	aether365 scan results <id>
Atcelt skenēšanu	POST /scans/{id}/cancel	client.scans.cancel(id)	aether365 scan cancel <id>
Paslēpt skenēšanu	PATCH /scans/{id}/hide	client.scans.hide(id)	aether365 scan hide <id>
Atkal parādīt skenēšanu	PATCH /scans/{id}/unhide	client.scans.unhide(id)	aether365 scan unhide <id>
Dzēst skenēšanu	DELETE /scans/{id}	client.scans.delete(id)	aether365 scan delete <id>

curl piemērs skenēšanas palaišanai:

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

Pārskati

Operācija	curl	SDK	CLI
Pārskata statuss	GET /scans/{id}/report	client.reports.status(id)	aether365 report status <id>
Ģenerēt pārskatu	POST /scans/{id}/report/generate	client.reports.generate(id)	aether365 report generate <id>
Pārskatu saraksts	GET /tenants/me/reports	client.reports.list()	aether365 report list
Lejupielādēt pārskatu	GET /scans/{id}/report (presigned)	client.reports.download(id, path)	aether365 report download <id> -o out.pdf

Pārskata statuss ir viens no ready, rendering, orgNameRequired vai locked. Pārskata ģenerēšana var patērēt pārskata kredītu (vienreizējs maksājums, ja piešķīrums nav iekļauts) - atslēgas īpašnieks tam piekrīt pats, izsaucot generate.

Pārskatu saraksts tiek lapots ar nobīdi: nododiet meta["nextCursor"] (vesels skaitlis ar rindu nobīdi vai None pēdējā lapā) atpakaļ kā cursor. client.reports.iter_all() seko kursoram jūsu vietā.

Uzbrukuma virsma

Operācija	curl	SDK	CLI
Kopsavilkums	GET /tenants/me/attack-surface	client.attack_surface.summary()	aether365 eas summary
Vēsture	GET /tenants/me/attack-surface/history	client.attack_surface.history()	aether365 eas history
Mērķu saraksts	GET /tenants/me/attack-surface/targets	client.attack_surface.targets()	aether365 eas targets list
Pievienot mērķi	POST /tenants/me/attack-surface/targets	client.attack_surface.add_target(host)	aether365 eas targets add <host>
Atjaunināt mērķi	PATCH /tenants/me/attack-surface/targets/{id}	client.attack_surface.update_target(id, ...)	aether365 eas targets update <id> --label ...
Dzēst mērķi	DELETE /tenants/me/attack-surface/targets/{id}	client.attack_surface.remove_target(id)	aether365 eas targets remove <id>
Verificēt mērķi	POST /tenants/me/attack-surface/targets/{id}/verify	client.attack_surface.verify_target(id)	aether365 eas targets verify <id>
Palaist EAS skenēšanu	POST /tenants/me/attack-surface/scan	client.attack_surface.scan()	aether365 eas scan

Drošības stāvoklis, novēršana un AI Pilot

Operācija	curl	SDK	CLI
Draudu / riska skats	GET /tenants/me/threats	client.threats.list()	aether365 threats
Politiku stāvoklis	GET /tenants/me/policies	client.policies.list()	aether365 policies
Novēršanas iespējas	GET /tenants/me/remediation/capabilities	client.remediation.capabilities()	aether365 remediation capabilities
Novēršanas plānu saraksts	GET /tenants/me/remediation-plans	client.remediation.plans()	aether365 remediation plans
Iegūt novēršanas plānu	GET /tenants/me/remediation-plans/{id}	client.remediation.plan(id)	aether365 remediation plan <id>
AI Pilot novēršamie vienumi	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 politikas	GET /tenants/me/ai-pilot/conditional-access	client.ai_pilot.conditional_access()	aether365 ai-pilot conditional-access

Novēršana ar API atslēgām ir tikai lasāma. Plāna piemērošana nav pieejama: plāna darbību reģistra vienumi var ietvert Conditional-Access / autorizācijas politikas labojumus, kas varētu bloķēt tenant piekļuvi paša direktorijam (AADSTS50097), tāpēc piemērošana paliek informācijas panelī ar operatoru procesā. Tā paša iemesla dēļ arī AI Pilot conditional-access un break-glass ir pieejami tikai lasīšanai.

Kļūdu apstrāde un atkārtojumi

Katra API kļūda atbilst tipizētam izņēmumam - Aether365Error apakšklasei:

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

Klients automātiski atkārto 429 RATE_LIMITED un 503 SERVICE_STARTING (dev aukstās datubāzes iesilšana) ar eksponenciālu atkāpi, ievērojot Retry-After galveni. Kvotu kļūdas, piemēram, SCAN_PLAN_LIMIT_REACHED, tiek izmestas uzreiz - tās netiek atkārtotas.

CLI izmantošana CI vidē

aether365 scan results <id> --fail-on-findings beidz darbu ar kodu 2, ja ir kaut viens neizdevies konstatējums, tāpēc pipeline var izmantot skenēšanas rezultātus kā vārtus:

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

CLI raksta kļūdas uz stderr un beidz darbu ar kodu 1 jebkuras API kļūdas gadījumā un ar kodu 2, ja nostrādā konstatējumu vārti.