Security model#
This page states the security guarantees of Astraeus: how people and machines prove who they are, what each may do, how organisations are kept apart, where secrets live, what Astralyx can and cannot see, and what follows if one of your machines or tokens is compromised. The control plane is a service operated by Astralyx; this page describes what it guarantees to you, not how it is built.
Principles#
- Machines connect out; nothing connects in to them. Astralyx never opens a connection to your machines: not for work, logs, metrics or a shell. Everything travels on HTTPS connections the machine opened.
- Every request is authenticated, then authorised. There is no anonymous access beyond health checks, the release version and public keys.
- Every request is confined to a workspace. Whatever you do in a cluster
— from the console,
astraor the API — is checked against your role in that workspace, and can name, list or change only that workspace's objects. - No secret values in the control plane. Credentials are references, resolved on the machine that needs them, with that machine's own authority.
- Customer data stays on its machines. Astralyx keeps metadata, states, metric series and totals. See What leaves your machines.
Parties and connections#
flowchart LR
U["You<br/>(browser, astra, API)"] -- "HTTPS: session or API token" --> CP["Astralyx control plane (SaaS)"]
M["Your machines<br/>(agent)"] -- "HTTPS, opened by the machine:<br/>the machine's own credential" --> CP| Connection | Opened by | Port |
|---|---|---|
Browser, astra and scripts to the console and its API |
You | 443 at console.astralyx.cloud |
| The machine agent to Astraeus | The machine | 443 at the Astraeus address shown in the console (on Astraeus Cloud, api.astralyx.cloud) |
Machine to the console's /releases, to install or upgrade the agent |
The machine | 443 |
Other traffic is yours to allow: what your workloads download (images, models, datasets), traffic between machines (the WireGuard mesh, multi-machine runs, drives shared over NFS) and services you publish. See Network and firewalls.
Authentication#
| Party | Proves itself with | Kept as |
|---|---|---|
| A person (password) | E-mail and password; e-mail verified; attempts limited per address and per client | Argon2id hash |
| A person (SSO) | OpenID Connect per organisation: code flow with PKCE, state and nonce; ID token checked (RS256 signature against the provider's keys, issuer, audience, expiry, nonce); a verified e-mail in an allowed domain | Link to the provider account |
| A person (Google, GitHub) | Astralyx's OAuth applications; for GitHub, only the primary, verified e-mail | Link to the provider account |
| A person, in the browser | Session cookie: HttpOnly, Secure, SameSite=Lax. Writes made with the cookie must carry the X-Astraeus-Client header, which a cross-site form cannot send |
SHA-256 of the session token |
A person, in astra and scripts |
CLI sessions (device flow, RFC 8628) and personal API tokens (ast_pat_…) |
SHA-256 |
| A machine | A single-use enrollment token to join; from then on, its own credential, issued when it joins | Hashes; never the credential itself |
| A worker of a run | A short-lived workload identity (1 hour), for services outside the cluster | Not accepted by the Astraeus API |
Sign-up, sign-in and password reset answer alike whether an address exists or not, and take as long. An account whose address was never verified is taken over by a provider's proof of that address: its password, sessions and tokens are removed, so someone who registered another person's address first keeps nothing.
A machine's credential is single-use to join and can be revoked: removing the machine revokes it at once, and Astraeus refuses it from then on.
Authorisation#
People: roles, confined to a workspace#
A request is a verb on a resource (listing runs is list jobs, requeueing a
run is create jobs/requeue). It is allowed only when your role in the
workspace grants it; everything else is denied. See
Roles and permissions.
Inside a workspace:
- paths must name objects in the workspace (
403 NAMESPACE_FORBIDDEN); - bodies may name and reference only objects in it: credentials, registry credentials, drives, run names, wake targets, data source credentials;
- listings are filtered to it;
- an endpoint selects only workers of its own workspace, whatever its labels;
- every request is written to the audit log with the user who made it.
Host access is granted, not taken#
By default a workspace's work cannot take anything from the machines it runs
on: no privileged containers, host PID or IPC, added capabilities or
runtime security options, and no host paths (403 HOST_ACCESS_FORBIDDEN).
An organisation admin grants host access per workspace: privileged, and host
path prefixes. The machine checks bind-mount sources again as they resolve on
the machine and mounts the resolved path, so a link planted inside a granted
directory cannot reach outside it.
Warning
A workspace allowed to run privileged or to mount / effectively owns
the machines it runs on, and every other workspace's work on them. Grant
host access only to workspaces you trust with the machine.
Machines act only for themselves#
A machine can register itself, receive the work placed on it, report on itself and its own workers, and answer requests addressed to it. Nothing else. Within a report, a machine speaks only for itself and for workers placed on it, may set only the states a machine can observe, and cannot revive a worker that already ended. Its metric series are labelled with the machine it authenticated as. An unused enrollment token can only register a machine.
Tenant isolation#
Astraeus Cloud is one cluster shared by many organisations. Astraeus keeps them apart itself: each machine belongs to the organisation whose enrollment token it joined with, and each workspace to its organisation, both fixed from then on. The guarantee: work runs only on machines of its own organisation, and a machine runs and hears only its organisation's work.
| Area | Guarantee |
|---|---|
| Placement | A worker is never placed on another organisation's machine. |
| Machines | Machines are never shared between organisations. A machine moves to another organisation only by removing it and enrolling it again. |
| Network | One WireGuard mesh per organisation: a machine's peers are its organisation's machines. |
| Names | A machine resolves only its organisation's DNS names. |
| What a machine receives | Endpoints, drives and data sources of its organisation's workspaces only. A drive may not name another organisation's machine. A data source is served (and receives its credentials) only on a machine its workspace's work could run on. |
| API | Machines, GPUs, a machine's work and its series are only your organisation's; another organisation's machine is not found. A request for another organisation's workspace is refused (TENANT_MISMATCH). |
| Console | Organisations and workspaces you are not a member of answer 404, not 403. |
A cluster dedicated to your organisation runs only your organisation's machines and workspaces.
Secrets never enter the control plane#
- Credentials are references. A Credential (
ExternalSecret) names a secret in your secret manager and how to authenticate; no field can hold a credential, and fields that would are refused. The credentials agent on the machine fetches the value with the machine's own authority (its cloud identity, a file on the machine), writes it under the machine's work root (directory0700, files0600), and removes it when no worker on the machine needs it. Astraeus keeps and returns references, and a status such asSynced on node X, never a value. A machine receives only the references its own workers need. - Data sources and agent tools name a Credential the same way. An agent run's model key and tool credentials are added by the machine's tool gateway; the run itself never holds them.
- Tokens are hashes. Astralyx keeps only SHA-256 hashes of sessions, API tokens and machine tokens. A copy of them authenticates no one.
- What Astralyx must use is encrypted: organisations' SSO client secrets, alert channel URLs and signing keys, and event stream URLs, tokens and keys are encrypted (AES-256-GCM).
Warning
Values you write into a run's specification (for example an environment
variable) are kept like any other field. Put secrets in Credentials,
never in a run's env. See Credentials.
What Astralyx can and cannot see#
| Astralyx can see | Astralyx cannot see |
|---|---|
| Your account, organisations, workspaces, members and roles | Credential values: they are never sent to Astralyx |
| Run specifications: image, command, resources, environment variables, labels | The data in your drives, your datasets, checkpoints and model weights |
| States and history of runs, workers, machines, drives and schedules | Your workers' logs, unless someone asks for them; they then pass through and are not kept |
| Machine inventory and metric series | Prompts and answers to Eos deployments through your edge gateway |
| Usage and the audit log | The contents of data sources: only totals |
The full account, with retention and deletion, is in What leaves your machines.
Addresses tenants give#
Organisation admins give Astralyx addresses: an identity provider, alert
webhooks, event streams. Astralyx connects to them only through a guard that
refuses non-public addresses: loopback, private (RFC 1918), link-local
(including cloud metadata at 169.254.169.254), shared address space
(100.64.0.0/10), unique-local and site-local IPv6, NAT64, 6to4, Teredo,
documentation, benchmarking, multicast and reserved ranges. The check is made
on the address actually used for the connection, so a name cannot resolve to
a public address when checked and a private one when used. Redirects are not
followed.
The tool gateway on a machine applies the same guard to the agent web tool, and also refuses the cluster's own names and the machine's own addresses.
Supply chain#
| What | How it is pinned or checked |
|---|---|
| The machine agent | Built against glibc 2.28; downloaded from the console's /releases or GitHub releases; every file checked against the release's SHA256SUMS at install and upgrade. |
| The container runtime bundled with the agent (containerd, runc, gVisor, CNI plugins, NVIDIA CDI tools) | Each pinned by version and SHA-256; anything else is refused when the release is built. |
| Built-in agent images (Anemoi) and notebook images (Hesperus) | Pinned by digest. Images you choose yourself are used as you name them. |
| Model weights from Hugging Face | Pinned to a commit. |
SHA256SUMS is served from the same address as the files it covers: it
protects against corruption, and TLS protects against tampering in transit.
Astraeus does not yet sign its images or releases.
If a machine or token is compromised#
| Compromised | The attacker can | The attacker cannot | To revoke |
|---|---|---|---|
| A machine (root on it) | Everything on that machine: its workers, their data and drives, the credentials resolved there for its workers, its machine credential. As that machine: receive its own work (its workers' specifications, its organisation's machine list and mesh keys, DNS names, endpoints), report false states and series for its own workers and hardware. | Read or change anything not placed on it; act as other machines; read other machines' credentials; act as a person; reach other organisations' machines. | Remove the machine. |
| A machine credential (stolen, without the machine) | Authenticate as that machine, with the same limits. | Anything a machine cannot do. | Remove the machine. |
| A personal API token | What its owner's roles allow, in the owner's workspaces. | Anything its owner cannot do. Read credential values (there are none in Astraeus). | Revoke the token in the console. |
Responsible disclosure#
If you find a security issue in Astraeus, write to [email protected]. Include what you found, how to reproduce it and its impact. Do not test against other customers' data or machines.