Python SDK och CLI

Underhålls av: Aether365 Team Målgrupp: Utvecklare och DevOps-ingenjörer Omfattning: Installation och användning av det officiella aether365 Python SDK:t och kommandoradsgränssnittet

Paketet aether365 är det officiella Python SDK:t och kommandoradsgränssnittet för Aether365 API. Det kapslar in https://api.aether365.io, sköter autentiseringen, packar upp svarskuvertet och gör automatiskt om anrop som misslyckas tillfälligt. Allt du kan göra med curl kan du göra med SDK:t eller CLI:t.

SDK:t och CLI:t använder en API-nyckel (ak_live_...) och går mot den enhetliga endpointen - anrop dirigeras automatiskt till din tenants hemregion. Se Autentisering för hur nycklarna fungerar.

Installation

Paketet distribueras internt (inte via PyPI). Installera det direkt från repositoryt eller en lokal utcheckning.

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

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

Python 3.12 eller senare krävs. Installationen lägger också kommandot aether365 på din PATH.

Konfiguration

Både SDK:t och CLI:t läser samma miljövariabler:

Variabel	Syfte	Standard
AETHER365_API_KEY	Din API-nyckel (ak_live_...). Obligatorisk.	-
AETHER365_API_URL	Åsidosätter bas-URL:en (till exempel dev-endpointen).	https://api.aether365.io
AETHER365_OUTPUT	CLI:ts utdataformat: table eller json.	table

export AETHER365_API_KEY="ak_live_..."

Region sköts automatiskt: API:et slår upp din tenant utifrån nyckeln och vidarebefordrar till rätt region, så du behöver aldrig konfigurera eller ange någon region.

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

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

Vad en API-nyckel kan och inte kan göra

En API-nyckel är begränsad till en säker, läsande och operativ yta. Den kan läsa dina data, starta och hantera skanningar, generera rapporter och hantera attack surface-mål. Den kan inte utföra åtgärder som styr kontot eller kan låsa ute katalogen - hantering av API-nycklar, fakturering, teammedlemskap, on- och offboarding av anslutningar, SSO, tillämpning av en remediation-plan eller AI Pilots conditional access-/break glass-skrivningar. De är bara tillgängliga för en inloggad session i dashboarden. Ett anrop mot en otillåten route ger 403 AUTH_INSUFFICIENT_SCOPE.

Kommando- och metodreferens

Varje rad visar samma operation på tre sätt: som rå curl, som SDK-metod och som CLI-kommando.

Tenant och konto

Operation	curl	SDK	CLI
Hämta tenantprofil	GET /tenants/me	client.tenants.me()	aether365 tenant me
Lista anslutningar	GET /tenants/me/connections	client.connections.list()	aether365 tenant connections
Notisinställningar	GET /tenants/me/notifications	client.notifications.get()	aether365 tenant notifications
Schemalagda skanningar	GET /tenants/me/scheduled-scans	client.scheduled_scans.list()	aether365 tenant scheduled-scans

Skanningar

Operation	curl	SDK	CLI
Lista skanningar	GET /tenants/me/scans	client.scans.list()	aether365 scan list
Starta en skanning	POST /tenants/me/scans	client.scans.create("compliance")	aether365 scan run --type compliance
Hämta en skanning	GET /scans/{id}	client.scans.get(id)	aether365 scan get <id>
Läs resultat	GET /scans/{id}/results	client.scans.results(id)	aether365 scan results <id>
Avbryt en skanning	POST /scans/{id}/cancel	client.scans.cancel(id)	aether365 scan cancel <id>
Dölj en skanning	PATCH /scans/{id}/hide	client.scans.hide(id)	aether365 scan hide <id>
Visa en skanning igen	PATCH /scans/{id}/unhide	client.scans.unhide(id)	aether365 scan unhide <id>
Ta bort en skanning	DELETE /scans/{id}	client.scans.delete(id)	aether365 scan delete <id>

curl-anropet för att starta en skanning:

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

Rapporter

Operation	curl	SDK	CLI
Rapportstatus	GET /scans/{id}/report	client.reports.status(id)	aether365 report status <id>
Generera en rapport	POST /scans/{id}/report/generate	client.reports.generate(id)	aether365 report generate <id>
Lista rapporter	GET /tenants/me/reports	client.reports.list()	aether365 report list
Ladda ner en rapport	GET /scans/{id}/report (presigned)	client.reports.download(id, path)	aether365 report download <id> -o out.pdf

Rapportstatus är en av ready, rendering, orgNameRequired eller locked. Att generera en rapport kan förbruka en rapportkredit (en engångskostnad när ingen kvot ingår) - nyckelns ägare väljer detta själv genom att anropa generate.

Rapportlistan är offset-paginerad: skicka tillbaka meta["nextCursor"] (ett heltalsoffset för rader, eller None på sista sidan) som cursor. client.reports.iter_all() följer cursorn åt dig.

Attack surface

Operation	curl	SDK	CLI
Översikt	GET /tenants/me/attack-surface	client.attack_surface.summary()	aether365 eas summary
Historik	GET /tenants/me/attack-surface/history	client.attack_surface.history()	aether365 eas history
Lista mål	GET /tenants/me/attack-surface/targets	client.attack_surface.targets()	aether365 eas targets list
Lägg till ett mål	POST /tenants/me/attack-surface/targets	client.attack_surface.add_target(host)	aether365 eas targets add <host>
Uppdatera ett mål	PATCH /tenants/me/attack-surface/targets/{id}	client.attack_surface.update_target(id, ...)	aether365 eas targets update <id> --label ...
Ta bort ett mål	DELETE /tenants/me/attack-surface/targets/{id}	client.attack_surface.remove_target(id)	aether365 eas targets remove <id>
Verifiera ett mål	POST /tenants/me/attack-surface/targets/{id}/verify	client.attack_surface.verify_target(id)	aether365 eas targets verify <id>
Kör en EAS-skanning	POST /tenants/me/attack-surface/scan	client.attack_surface.scan()	aether365 eas scan

Posture, remediation och AI Pilot

Operation	curl	SDK	CLI
Hot-/riskvy	GET /tenants/me/threats	client.threats.list()	aether365 threats
Policy-posture	GET /tenants/me/policies	client.policies.list()	aether365 policies
Remediation-funktioner	GET /tenants/me/remediation/capabilities	client.remediation.capabilities()	aether365 remediation capabilities
Lista remediation-planer	GET /tenants/me/remediation-plans	client.remediation.plans()	aether365 remediation plans
Hämta en remediation-plan	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-policyer	GET /tenants/me/ai-pilot/conditional-access	client.ai_pilot.conditional_access()	aether365 ai-pilot conditional-access

Remediation är skrivskyddad för API-nycklar. Att tillämpa en plan exponeras inte: en plans action registry-poster kan innehålla conditional access-/authorization policy-patchar som skulle låsa ute en tenant från dess egen katalog (AADSTS50097), så tillämpningen stannar i dashboarden med en operatör i loopen. AI Pilots conditional access och break-glass är av samma skäl också bara läsbara.

Felhantering och omförsök

Varje API-fel mappas till en typad exception-subklass av Aether365Error:

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

Klienten gör automatiskt om 429 RATE_LIMITED och 503 SERVICE_STARTING (uppvärmningen av den kalla dev-databasen) med exponentiell backoff och respekterar Retry-After-headern. Kvotfel som SCAN_PLAN_LIMIT_REACHED kastas direkt - de görs inte om.

Använda CLI:t i CI

aether365 scan results <id> --fail-on-findings avslutar med kod 2 när minst ett underkänt fynd finns, så att en pipeline kan låta skanningsresultaten avgöra om den går vidare:

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

CLI:t skriver fel till stderr och avslutar med 1 vid alla API-fel och med 2 vid findings-grinden.