Python SDK και CLI

Συντηρείται από: Aether365 Team Κοινό: Προγραμματιστές και μηχανικοί DevOps Πεδίο: Εγκατάσταση και χρήση του επίσημου Python SDK aether365 και της διεπαφής γραμμής εντολών

Το πακέτο aether365 είναι το επίσημο Python SDK και η διεπαφή γραμμής εντολών για το Aether365 API. Τυλίγει το https://api.aether365.io, αναλαμβάνει την πιστοποίηση, αποσυσκευάζει το response envelope και επαναλαμβάνει αυτόματα τα αιτήματα που αποτυγχάνουν παροδικά. Ό,τι μπορείτε να κάνετε με curl, μπορείτε να το κάνετε και με το SDK ή το CLI.

Το SDK και το CLI χρησιμοποιούν ένα API key (ak_live_...) και στοχεύουν το ενοποιημένο endpoint: τα αιτήματα δρομολογούνται αυτόματα στην κύρια περιοχή του tenant σας. Δείτε την Πιστοποίηση για το πώς λειτουργούν τα κλειδιά.

Εγκατάσταση

Το πακέτο διανέμεται εσωτερικά (όχι μέσω PyPI). Εγκαταστήστε το απευθείας από το repository ή από ένα τοπικό checkout.

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

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

Απαιτείται Python 3.12 ή νεότερη έκδοση. Η εγκατάσταση του πακέτου προσθέτει επίσης την εντολή aether365 στο PATH σας.

Ρύθμιση

Το SDK και το CLI διαβάζουν τις ίδιες μεταβλητές περιβάλλοντος:

Μεταβλητή	Σκοπός	Προεπιλογή
AETHER365_API_KEY	Το API key σας (ak_live_...). Απαιτείται.	-
AETHER365_API_URL	Παρακάμπτει το βασικό URL (για παράδειγμα το dev endpoint).	https://api.aether365.io
AETHER365_OUTPUT	Μορφή εξόδου του CLI: table ή json.	table

export AETHER365_API_KEY="ak_live_..."

Η περιοχή είναι αυτόματη: το API εντοπίζει τον tenant σας από το κλειδί και προωθεί το αίτημα στη σωστή περιοχή, οπότε δεν χρειάζεται ποτέ να ρυθμίσετε ή να περάσετε περιοχή.

Γρήγορη εκκίνηση: 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")

Γρήγορη εκκίνηση: 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 key

Ένα API key περιορίζεται σε μια ασφαλή επιφάνεια ανάγνωσης και λειτουργικών ενεργειών. Μπορεί να διαβάζει τα δεδομένα σας, να ενεργοποιεί και να διαχειρίζεται σαρώσεις, να δημιουργεί αναφορές και να διαχειρίζεται στόχους attack-surface. Δεν μπορεί να εκτελεί ενέργειες ελέγχου λογαριασμού ή ενέργειες που θα μπορούσαν να κλειδώσουν τον κατάλογο: διαχείριση API keys, χρεώσεις, μέλη ομάδας, ένταξη/αφαίρεση συνδέσεων, SSO, εφαρμογή ενός remediation plan ή τις εγγραφές conditional-access/break-glass του AI Pilot. Αυτά παραμένουν διαθέσιμα μόνο σε συνδεδεμένη συνεδρία στο dashboard. Ένα αίτημα σε μη επιτρεπόμενη διαδρομή επιστρέφει 403 AUTH_INSUFFICIENT_SCOPE.

Αναφορά εντολών και μεθόδων

Κάθε γραμμή δείχνει την ίδια λειτουργία με τρεις τρόπους: raw curl, τη μέθοδο του SDK και την εντολή του CLI.

Tenant και λογαριασμός

Λειτουργία	curl	SDK	CLI
Προφίλ tenant	GET /tenants/me	client.tenants.me()	aether365 tenant me
Λίστα συνδέσεων	GET /tenants/me/connections	client.connections.list()	aether365 tenant connections
Προτιμήσεις ειδοποιήσεων	GET /tenants/me/notifications	client.notifications.get()	aether365 tenant notifications
Προγραμματισμένες σαρώσεις	GET /tenants/me/scheduled-scans	client.scheduled_scans.list()	aether365 tenant scheduled-scans

Σαρώσεις

Λειτουργία	curl	SDK	CLI
Λίστα σαρώσεων	GET /tenants/me/scans	client.scans.list()	aether365 scan list
Ενεργοποίηση σάρωσης	POST /tenants/me/scans	client.scans.create("compliance")	aether365 scan run --type compliance
Ανάκτηση σάρωσης	GET /scans/{id}	client.scans.get(id)	aether365 scan get <id>
Ανάγνωση αποτελεσμάτων	GET /scans/{id}/results	client.scans.results(id)	aether365 scan results <id>
Ακύρωση σάρωσης	POST /scans/{id}/cancel	client.scans.cancel(id)	aether365 scan cancel <id>
Απόκρυψη σάρωσης	PATCH /scans/{id}/hide	client.scans.hide(id)	aether365 scan hide <id>
Επανεμφάνιση σάρωσης	PATCH /scans/{id}/unhide	client.scans.unhide(id)	aether365 scan unhide <id>
Διαγραφή σάρωσης	DELETE /scans/{id}	client.scans.delete(id)	aether365 scan delete <id>

Το 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"}'

Αναφορές

Λειτουργία	curl	SDK	CLI
Κατάσταση αναφοράς	GET /scans/{id}/report	client.reports.status(id)	aether365 report status <id>
Δημιουργία αναφοράς	POST /scans/{id}/report/generate	client.reports.generate(id)	aether365 report generate <id>
Λίστα αναφορών	GET /tenants/me/reports	client.reports.list()	aether365 report list
Λήψη αναφοράς	GET /scans/{id}/report (presigned)	client.reports.download(id, path)	aether365 report download <id> -o out.pdf

Η κατάσταση της αναφοράς είναι μία από τις ready, rendering, orgNameRequired ή locked. Η δημιουργία αναφοράς μπορεί να καταναλώσει ένα report credit (εφάπαξ χρέωση όταν δεν περιλαμβάνεται allowance): ο κάτοχος του κλειδιού συναινεί σε αυτό καλώντας το generate.

Η λίστα αναφορών σελιδοποιείται με offset: περάστε το meta["nextCursor"] (ακέραιο row offset, ή None στην τελευταία σελίδα) πίσω ως cursor. Η client.reports.iter_all() ακολουθεί το cursor για εσάς.

Attack surface

Λειτουργία	curl	SDK	CLI
Επισκόπηση	GET /tenants/me/attack-surface	client.attack_surface.summary()	aether365 eas summary
Ιστορικό	GET /tenants/me/attack-surface/history	client.attack_surface.history()	aether365 eas history
Λίστα στόχων	GET /tenants/me/attack-surface/targets	client.attack_surface.targets()	aether365 eas targets list
Προσθήκη στόχου	POST /tenants/me/attack-surface/targets	client.attack_surface.add_target(host)	aether365 eas targets add <host>
Ενημέρωση στόχου	PATCH /tenants/me/attack-surface/targets/{id}	client.attack_surface.update_target(id, ...)	aether365 eas targets update <id> --label ...
Διαγραφή στόχου	DELETE /tenants/me/attack-surface/targets/{id}	client.attack_surface.remove_target(id)	aether365 eas targets remove <id>
Επαλήθευση στόχου	POST /tenants/me/attack-surface/targets/{id}/verify	client.attack_surface.verify_target(id)	aether365 eas targets verify <id>
Εκτέλεση σάρωσης EAS	POST /tenants/me/attack-surface/scan	client.attack_surface.scan()	aether365 eas scan

Στάση ασφαλείας, remediation και AI Pilot

Λειτουργία	curl	SDK	CLI
Προβολή απειλών / κινδύνου	GET /tenants/me/threats	client.threats.list()	aether365 threats
Στάση πολιτικών	GET /tenants/me/policies	client.policies.list()	aether365 policies
Δυνατότητες remediation	GET /tenants/me/remediation/capabilities	client.remediation.capabilities()	aether365 remediation capabilities
Λίστα remediation plans	GET /tenants/me/remediation-plans	client.remediation.plans()	aether365 remediation plans
Ανάκτηση 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 policies	GET /tenants/me/ai-pilot/conditional-access	client.ai_pilot.conditional_access()	aether365 ai-pilot conditional-access

Το remediation είναι μόνο για ανάγνωση για τα API keys. Η εφαρμογή ενός plan δεν εκτίθεται: τα action-registry στοιχεία ενός plan μπορεί να περιλαμβάνουν patches Conditional-Access / authorization-policy που θα κλείδωναν έναν tenant έξω από τον ίδιο του τον κατάλογο (AADSTS50097), οπότε η εφαρμογή παραμένει στο dashboard με έναν χειριστή στη διαδικασία. Τα AI Pilot conditional-access και break-glass εκτίθενται επίσης μόνο για ανάγνωση για τον ίδιο λόγο.

Χειρισμός σφαλμάτων και επαναλήψεις

Κάθε σφάλμα του API αντιστοιχίζεται σε μια τυποποιημένη εξαίρεση, υποκλάση του 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.")

Ο client επαναλαμβάνει αυτόματα τα 429 RATE_LIMITED και 503 SERVICE_STARTING (η προθέρμανση της κρύας βάσης δεδομένων στο dev) με exponential backoff, σεβόμενος το header Retry-After. Σφάλματα ορίων όπως το SCAN_PLAN_LIMIT_REACHED εγείρονται αμέσως: δεν επαναλαμβάνονται.

Χρήση του CLI σε CI

Η εντολή aether365 scan results <id> --fail-on-findings τερματίζει με κωδικό εξόδου 2 όταν υπάρχει έστω και ένα αποτυχημένο εύρημα, ώστε ένα pipeline να μπορεί να μπλοκάρει με βάση τα αποτελέσματα της σάρωσης:

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

Το CLI γράφει τα σφάλματα στο stderr και τερματίζει με 1 σε οποιοδήποτε σφάλμα του API και με 2 στην πύλη ευρημάτων.