Python SDK ve CLI

Hazırlayan: Aether365 Ekibi Hedef Kitle: Geliştiriciler ve DevOps mühendisleri Kapsam: Resmi aether365 Python SDK'sının ve komut satırı arayüzünün kurulumu ve kullanımı

aether365 paketi, Aether365 API'si için resmi Python SDK ve komut satırı arayüzüdür. https://api.aether365.io adresini sarmalar, kimlik doğrulamayı halleder, response envelope'unu açar ve geçici hataları otomatik olarak yeniden dener. curl ile yapabildiğiniz her şeyi SDK veya CLI ile de yapabilirsiniz.

SDK ve CLI, API anahtarı (ak_live_...) kullanır ve birleşik endpoint'i hedefler: istekler tenant'ınızın ana bölgesine otomatik yönlendirilir. Anahtarların nasıl çalıştığını Kimlik Doğrulama sayfasında bulabilirsiniz.

Kurulum

Paket dahili olarak dağıtılır (PyPI'da yer almaz). Doğrudan repository'den veya yerel bir checkout'tan kurun.

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

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

Python 3.12 veya daha yenisi gereklidir. Paketi kurduğunuzda aether365 komutu da PATH'inize eklenir.

Yapılandırma

SDK ve CLI aynı ortam değişkenlerini okur:

Değişken	Amaç	Varsayılan
AETHER365_API_KEY	API anahtarınız (ak_live_...). Zorunlu.	-
AETHER365_API_URL	Temel URL'yi geçersiz kılar (örneğin dev endpoint'i için).	https://api.aether365.io
AETHER365_OUTPUT	CLI çıktı formatı: table veya json.	table

export AETHER365_API_KEY="ak_live_..."

Bölge otomatiktir: API, tenant'ınızı anahtardan çözümler ve isteği doğru bölgeye iletir; bölge yapılandırmanız veya parametre olarak geçmeniz hiçbir zaman gerekmez.

Hızlı Başlangıç: 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")

Hızlı Başlangıç: 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

API anahtarı neleri yapabilir, neleri yapamaz

API anahtarı güvenli, okuma artı operasyonel bir yüzeyle sınırlıdır. Verilerinizi okuyabilir, tarama tetikleyip yönetebilir, rapor oluşturabilir ve attack-surface hedeflerini yönetebilir. Hesap kontrolüne veya dizinden kilitlenmeye yol açabilecek işlemleri ise yapamaz: API anahtarı yönetimi, faturalama, ekip üyeliği, bağlantı ekleme/kaldırma, SSO, bir remediation planının uygulanması veya AI Pilot conditional-access/break-glass yazma işlemleri. Bunlar yalnızca dashboard'da oturum açmış bir session üzerinden kullanılabilir. İzin verilmeyen bir route'a yapılan istek 403 AUTH_INSUFFICIENT_SCOPE döner.

Komut ve metot referansı

Her satır aynı işlemi üç şekilde gösterir: ham curl, SDK metodu ve CLI komutu.

Tenant ve hesap

İşlem	curl	SDK	CLI
Tenant profilini getir	GET /tenants/me	client.tenants.me()	aether365 tenant me
Bağlantıları listele	GET /tenants/me/connections	client.connections.list()	aether365 tenant connections
Bildirim tercihleri	GET /tenants/me/notifications	client.notifications.get()	aether365 tenant notifications
Zamanlanmış taramalar	GET /tenants/me/scheduled-scans	client.scheduled_scans.list()	aether365 tenant scheduled-scans

Taramalar

İşlem	curl	SDK	CLI
Taramaları listele	GET /tenants/me/scans	client.scans.list()	aether365 scan list
Tarama tetikle	POST /tenants/me/scans	client.scans.create("compliance")	aether365 scan run --type compliance
Tarama getir	GET /scans/{id}	client.scans.get(id)	aether365 scan get <id>
Sonuçları oku	GET /scans/{id}/results	client.scans.results(id)	aether365 scan results <id>
Taramayı iptal et	POST /scans/{id}/cancel	client.scans.cancel(id)	aether365 scan cancel <id>
Taramayı gizle	PATCH /scans/{id}/hide	client.scans.hide(id)	aether365 scan hide <id>
Gizlemeyi kaldır	PATCH /scans/{id}/unhide	client.scans.unhide(id)	aether365 scan unhide <id>
Taramayı sil	DELETE /scans/{id}	client.scans.delete(id)	aether365 scan delete <id>

Tarama tetiklemek için 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"}'

Raporlar

İşlem	curl	SDK	CLI
Rapor durumu	GET /scans/{id}/report	client.reports.status(id)	aether365 report status <id>
Rapor oluştur	POST /scans/{id}/report/generate	client.reports.generate(id)	aether365 report generate <id>
Raporları listele	GET /tenants/me/reports	client.reports.list()	aether365 report list
Rapor indir	GET /scans/{id}/report (presigned)	client.reports.download(id, path)	aether365 report download <id> -o out.pdf

Rapor durumu ready, rendering, orgNameRequired veya locked değerlerinden biridir. Rapor oluşturmak bir rapor kredisi tüketebilir (dahil bir ödenek olmadığında tek seferlik ücret): anahtar sahibi generate'i çağırarak buna kendisi onay vermiş olur.

Rapor listesi offset ile sayfalanır: meta["nextCursor"] değerini (tamsayı satır offset'i, son sayfada None) cursor olarak geri gönderin. client.reports.iter_all() cursor'u sizin yerinize takip eder.

Attack surface

İşlem	curl	SDK	CLI
Genel bakış	GET /tenants/me/attack-surface	client.attack_surface.summary()	aether365 eas summary
Geçmiş	GET /tenants/me/attack-surface/history	client.attack_surface.history()	aether365 eas history
Hedefleri listele	GET /tenants/me/attack-surface/targets	client.attack_surface.targets()	aether365 eas targets list
Hedef ekle	POST /tenants/me/attack-surface/targets	client.attack_surface.add_target(host)	aether365 eas targets add <host>
Hedef güncelle	PATCH /tenants/me/attack-surface/targets/{id}	client.attack_surface.update_target(id, ...)	aether365 eas targets update <id> --label ...
Hedef sil	DELETE /tenants/me/attack-surface/targets/{id}	client.attack_surface.remove_target(id)	aether365 eas targets remove <id>
Hedef doğrula	POST /tenants/me/attack-surface/targets/{id}/verify	client.attack_surface.verify_target(id)	aether365 eas targets verify <id>
EAS taraması çalıştır	POST /tenants/me/attack-surface/scan	client.attack_surface.scan()	aether365 eas scan

Güvenlik duruşu, remediation ve AI Pilot

İşlem	curl	SDK	CLI
Tehdit / risk görünümü	GET /tenants/me/threats	client.threats.list()	aether365 threats
Policy duruşu	GET /tenants/me/policies	client.policies.list()	aether365 policies
Remediation yetenekleri	GET /tenants/me/remediation/capabilities	client.remediation.capabilities()	aether365 remediation capabilities
Remediation planlarını listele	GET /tenants/me/remediation-plans	client.remediation.plans()	aether365 remediation plans
Remediation planı getir	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 policy'leri	GET /tenants/me/ai-pilot/conditional-access	client.ai_pilot.conditional_access()	aether365 ai-pilot conditional-access

Remediation, API anahtarları için salt okunurdur. Plan uygulama API'ye açılmamıştır: bir planın action-registry öğeleri, tenant'ı kendi dizininin dışında bırakabilecek Conditional-Access / authorization-policy patch'leri içerebilir (AADSTS50097); bu yüzden uygulama adımı, operatörün süreçte yer aldığı dashboard'da kalır. AI Pilot conditional-access ve break-glass da aynı nedenle yalnızca okunabilir olarak sunulur.

Hata yönetimi ve yeniden denemeler

Her API hatası, Aether365Error sınıfının alt sınıfı olan tipli bir exception'a eşlenir:

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

İstemci, 429 RATE_LIMITED ve 503 SERVICE_STARTING (dev ortamındaki soğuk veritabanı ısınması) hatalarını Retry-After header'ına uyarak exponential backoff ile otomatik olarak yeniden dener. SCAN_PLAN_LIMIT_REACHED gibi kota hataları anında fırlatılır: bunlar yeniden denenmez.

CLI'yi CI'da kullanmak

aether365 scan results <id> --fail-on-findings, başarısız herhangi bir bulgu varsa 2 çıkış koduyla sonlanır; böylece bir pipeline tarama sonuçlarına göre gate kurabilir:

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

CLI, hataları stderr'e yazar; herhangi bir API hatasında 1, bulgu gate'inde 2 koduyla çıkar.