Skip to main content

alien_core/
sandbox_image.rs

1//! What a sandbox image must carry for the agent to serve, and the Dockerfile text carrying it.
2//!
3//! Two kinds of image exist and neither is built the way the other is. AWS renders one per
4//! deployment onto a customer-supplied base image; GCP builds static images in CI. Nothing at build
5//! time reads the other side, and a value that disagrees is invisible until a session fails: an
6//! agent listening on a port no caller dials, or an exec into a uid the image never created.
7//!
8//! So the values live here once and both kinds render the block that carries them from this
9//! module. The same holds for the default sandbox base both kinds start from: its toolchain is
10//! listed here once, and a probe reads that list rather than restating it. The Dockerfiles and the
11//! tool list are committed as generated text because CI builds them with `docker build` and probes
12//! them from a shell, neither of which can call a Rust function.
13
14/// Path the agent binary is installed at inside every sandbox image.
15///
16/// An image that installs one path and entrypoints another exits before it serves, and the
17/// session times out on connect.
18pub const AGENT_PATH: &str = "/usr/local/bin/alien-sandbox-agent";
19
20/// Port the agent serves unless the platform pins another.
21///
22/// Defined once because two independent copies are a runtime-only failure: the image build places
23/// the agent on one port and the client dials the other, and nothing catches it until a sandbox
24/// hangs. AWS scopes its endpoint token to an explicit port set, so this cannot be discovered.
25pub const AGENT_PORT: u16 = 8971;
26
27/// Header carrying a preview capability. Never `Authorization`: the caller's own bearer token
28/// belongs to the code inside the sandbox and reaches it untouched.
29pub const PREVIEW_CAPABILITY_HEADER: &str = "x-alien-preview-capability";
30
31/// Header naming the sandbox port a preview request is for.
32pub const PREVIEW_PORT_HEADER: &str = "x-alien-preview-port";
33
34/// Header a caller puts its own bearer in when the backend's edge consumes `Authorization` for
35/// its own credential (GCP). The agent, after the capability verifies, re-emits it as
36/// `Authorization` towards `127.0.0.1` only.
37pub const CALLER_AUTHORIZATION_HEADER: &str = "x-alien-caller-authorization";
38
39/// Environment variable naming the header a backend's callers use for their own bearer
40/// (`authorization` when unset). Set on backends whose edge replaces `Authorization`.
41pub const ENV_CALLER_AUTHORIZATION_HEADER: &str = "ALIEN_SANDBOX_CALLER_AUTHORIZATION_HEADER";
42
43/// Longest a preview capability lives, in seconds. A grant never outlives the session either.
44pub const PREVIEW_CAPABILITY_MAX_SECONDS: i64 = 15 * 60;
45
46/// Set by the Kubernetes backend only: the pod mounts the agent binary and `/opt/alien`
47/// read-only itself, so the agent verifies that instead of building a private mount namespace
48/// (a pod's default seccomp profile blocks `unshare`). The agent refuses to start if the mounts
49/// are not there, so setting it elsewhere cannot turn protection off.
50pub const ENV_PROTECTED_MOUNTS: &str = "ALIEN_SANDBOX_PROTECTED_MOUNTS";
51
52/// Comma-separated `host:port` addresses of the Kubernetes API server (its Service ClusterIP and
53/// the real endpoint IPs) that the startup gate must see dropped. The Operator sets it on every
54/// Kubernetes sandbox pod, because service links are off and the pod has no
55/// `KUBERNETES_SERVICE_HOST` to learn the address from.
56pub const ENV_MUST_DROP_KUBE_API: &str = "ALIEN_SANDBOX_MUST_DROP_KUBE_API";
57/// A public `host:port` the startup gate must also see dropped. The Operator sets it only where
58/// the declared egress forbids direct public traffic (`none`, and `internet`, which goes through
59/// the gateway). It is unset when the policy allows that address, so an `allow` pod is not
60/// refused for reaching it.
61pub const ENV_MUST_DROP_PUBLIC: &str = "ALIEN_SANDBOX_MUST_DROP_PUBLIC";
62/// The public address the Operator asks the gate to probe.
63pub const MUST_DROP_PUBLIC_PROBE: &str = "1.1.1.1:443";
64/// The agent's first argument that stages the protected files (the Kubernetes init container).
65pub const STAGE_PROTECTED_FILES_ARGUMENT: &str = "--stage-protected-files";
66/// The agent's first argument that prints its uid and gid and exits, touching nothing else.
67pub const AGENT_IDENTITY_ARGUMENT: &str = "identity";
68/// File name the staging step also writes at the top of the staging directory. Agents built before
69/// the directory mount were staged that way and an Operator of that release mounts it over the
70/// image's agent path; keeping it lets that Operator run an image built with this agent.
71pub const STAGED_AGENT_NAME: &str = "agent";
72/// Name of the directory inside the staging volume that the pod mounts read-only at `/opt/alien`.
73pub const STAGED_METADATA_NAME: &str = "opt";
74/// The agent's file name inside that directory. A pod mounts directories only, never the single
75/// file: runtimes that run the pod in a VM share a directory mount into the guest as a mount
76/// point but do not list a single-file bind mount, so the agent could not prove the file
77/// read-only there. The container starts the agent from [`STAGED_AGENT_PATH`].
78pub const STAGED_AGENT_FILE: &str = "alien-sandbox-agent";
79/// Where the staged agent runs from on Kubernetes (inside the read-only `/opt/alien` mount).
80pub const STAGED_AGENT_PATH: &str = "/opt/alien/alien-sandbox-agent";
81
82/// Turns on the image's own command under the root boot contract. Released agents accept only
83/// `true` and refuse to start on anything else.
84pub const ENV_IMAGE_COMMAND: &str = "ALIEN_SANDBOX_IMAGE_COMMAND";
85/// The [`ENV_IMAGE_COMMAND`] value deployment sets when the sandbox declares image permissions
86/// or lifecycle steps. A released agent refuses it and so fails the image build's validate hook;
87/// a current one reads it as `true` plus a requirement to enforce [`ENV_IMAGE_PERMISSIONS`].
88pub const IMAGE_COMMAND_WITH_IMAGE_PERMISSIONS: &str = "image-permissions-v1";
89/// JSON [`crate::sandbox_image_permissions::ImagePermissionsContract`]: the mounts the agent
90/// performs for the image, the connections it exempts from the gateway, and the lifecycle steps.
91pub const ENV_IMAGE_PERMISSIONS: &str = "ALIEN_SANDBOX_IMAGE_PERMISSIONS";
92/// Version of the [`ENV_IMAGE_PERMISSIONS`] contract.
93pub const ENV_IMAGE_PERMISSIONS_VERSION: &str = "ALIEN_SANDBOX_IMAGE_PERMISSIONS_V";
94/// The only [`ENV_IMAGE_PERMISSIONS_VERSION`] value.
95pub const IMAGE_PERMISSIONS_VERSION: &str = "1";
96
97/// Mode of the agent binary, owned by `0:0` so the exec uid cannot rewrite its supervisor.
98pub const AGENT_MODE: u32 = 0o755;
99
100/// Name of the exec identity's passwd and group entries.
101pub const EXEC_USER: &str = "sandbox";
102
103/// Mode of the session root, which the exec uid owns.
104pub const SESSION_ROOT_MODE: u32 = 0o700;
105
106/// `RUST_LOG` for a GCP image, which the agent needs set before it logs anything.
107pub const GCP_AGENT_LOG_FILTER: &str = "info";
108
109/// Linux capabilities a root image process keeps: Docker's default set without `NET_RAW`.
110///
111/// `(name, number)` pairs, one list for both sides of the contract. The agent keeps exactly
112/// this set for the image's command and a Kubernetes pod grants exactly this set to the agent
113/// (`drop: [ALL]`, then these), so the agent can start the command with what it is entitled to
114/// and nothing more. Never `NET_ADMIN`, `SYS_ADMIN` or `NET_RAW`.
115pub const IMAGE_ROOT_CAPABILITY_SET: &[(&str, u8)] = &[
116    ("CHOWN", 0),
117    ("DAC_OVERRIDE", 1),
118    ("FOWNER", 3),
119    ("FSETID", 4),
120    ("KILL", 5),
121    ("SETGID", 6),
122    ("SETUID", 7),
123    ("SETPCAP", 8),
124    ("NET_BIND_SERVICE", 10),
125    ("SYS_CHROOT", 18),
126    ("MKNOD", 27),
127    ("AUDIT_WRITE", 29),
128    ("SETFCAP", 31),
129];
130
131/// [`IMAGE_ROOT_CAPABILITY_SET`] as the 32-bit `CapEff` mask the agent applies.
132pub const IMAGE_ROOT_CAPABILITY_MASK: u32 = {
133    let mut mask = 0u32;
134    let mut index = 0;
135    while index < IMAGE_ROOT_CAPABILITY_SET.len() {
136        mask |= 1 << IMAGE_ROOT_CAPABILITY_SET[index].1;
137        index += 1;
138    }
139    mask
140};
141
142/// How an image ends, and the isolation that ending permits.
143///
144/// One value rather than two, because `ALIEN_SANDBOX_ISOLATION` and the trailing `USER` describe
145/// the same decision from opposite sides: an image that asks for `uid-split` under a non-root
146/// `USER` has no privilege left to drop with, and every exec in it fails.
147#[derive(Debug, Clone, Copy, PartialEq, Eq)]
148pub enum Isolation {
149    /// The agent starts as root and drops to the exec uid before every spawn, so a command can
150    /// never rewrite its own supervisor. The image declares no `USER`.
151    UidSplit,
152    /// The agent starts as the exec uid and supervises commands under it, which is all a runtime
153    /// that refuses a root image can offer. The image ends `USER <uid>:<uid>`.
154    Platform,
155}
156
157impl Isolation {
158    /// The `ALIEN_SANDBOX_ISOLATION` value the agent parses.
159    pub fn env_value(self) -> &'static str {
160        match self {
161            Self::UidSplit => "uid-split",
162            Self::Platform => "platform",
163        }
164    }
165}
166
167/// How the agent decides a caller may be served.
168#[derive(Debug, Clone, Copy, PartialEq, Eq)]
169pub enum Authorization {
170    /// The connection is the proof. The agent serves an uncapabilitied request only from a socket
171    /// peer it cannot trace back to the exec uid, which keeps the supervised command out.
172    Transport,
173    /// The caller presents a signed token, which is what a network anything can reach requires.
174    Capability,
175    /// A per-boot credential is read through the cloud's authenticated native file API.
176    NativeFile,
177}
178
179impl Authorization {
180    /// The `ALIEN_SANDBOX_AUTHORIZATION` value the agent parses.
181    pub fn env_value(self) -> &'static str {
182        match self {
183            Self::Transport => "transport",
184            Self::Capability => "capability",
185            Self::NativeFile => "native-file",
186        }
187    }
188}
189
190/// The values an image must carry for the agent to run in it.
191#[derive(Debug, Clone, Copy, PartialEq, Eq)]
192pub struct SandboxImage {
193    /// Uid the supervised command runs as, resolved from a non-root base USER or the default.
194    pub exec_uid: u32,
195    /// Primary gid from the base USER, which may differ from its uid.
196    pub exec_gid: u32,
197    /// Writable session directory. Image-owned directories may also be writable on VM backends.
198    pub session_root: &'static str,
199    /// Port the agent serves, both its own protocol and any lifecycle hooks.
200    pub port: u16,
201    pub authorization: Authorization,
202    pub isolation: Isolation,
203}
204
205impl SandboxImage {
206    /// Gid the supervised command runs as.
207    pub fn exec_gid(&self) -> u32 {
208        self.exec_gid
209    }
210
211    /// The agent's configuration contract as `(name, value)` pairs, in the order the `ENV` block
212    /// lists them.
213    pub fn contract_env_vars(&self) -> [(&'static str, String); 6] {
214        [
215            ("ALIEN_SANDBOX_ROOT", self.session_root.to_string()),
216            ("ALIEN_SANDBOX_PORT", self.port.to_string()),
217            (
218                "ALIEN_SANDBOX_AUTHORIZATION",
219                self.authorization.env_value().to_string(),
220            ),
221            ("ALIEN_SANDBOX_EXEC_UID", self.exec_uid.to_string()),
222            ("ALIEN_SANDBOX_EXEC_GID", self.exec_gid().to_string()),
223            (
224                "ALIEN_SANDBOX_ISOLATION",
225                self.isolation.env_value().to_string(),
226            ),
227        ]
228    }
229
230    /// The `uid:gid` the image runs as, or `None` when it declares no user and starts as root.
231    /// Why the gid is explicit is in the `USER` comment [`entrypoint`] renders.
232    pub fn user(&self) -> Option<String> {
233        match self.isolation {
234            Isolation::UidSplit => None,
235            Isolation::Platform => Some(format!("{}:{}", self.exec_uid, self.exec_gid())),
236        }
237    }
238
239    /// The port the image exposes, as an OCI `ExposedPorts` key.
240    pub fn exposed_port(&self) -> String {
241        format!("{}/tcp", self.port)
242    }
243
244    /// The exec identity's `/etc/passwd` line, without a trailing newline.
245    pub fn passwd_entry(&self) -> String {
246        format!(
247            "{EXEC_USER}:x:{uid}:{gid}::{root}:/sbin/nologin",
248            uid = self.exec_uid,
249            gid = self.exec_gid(),
250            root = self.session_root,
251        )
252    }
253
254    /// The exec identity's `/etc/group` line, without a trailing newline.
255    pub fn group_entry(&self) -> String {
256        format!("{EXEC_USER}:x:{gid}:", gid = self.exec_gid())
257    }
258}
259
260/// The Lambda MicroVM image, rendered per deployment onto a customer base image.
261///
262/// The agent runs as root so it can drop to [`SandboxImage::exec_uid`] before every spawn; inside
263/// a MicroVM that is contained by hardware virtualisation, which is the tenant boundary. A
264/// shared-kernel backend must give the agent `CAP_SETUID` instead of root.
265pub const AWS_MICROVM: SandboxImage = SandboxImage {
266    exec_uid: 60000,
267    exec_gid: 60000,
268    session_root: "/sandbox",
269    port: AGENT_PORT,
270    authorization: Authorization::Transport,
271    isolation: Isolation::UidSplit,
272};
273
274/// GCP keeps a root supervisor separate from the non-root command identity.
275/// Live conformance must verify root execution and capability bounds because the
276/// provider's published custom-image requirements do not promise root support.
277/// Agent Platform serves the port the template declares; the agent keeps the shared port so a
278/// workload that binds 8080 itself does not collide with it (measured live: with the agent on
279/// 8080 a root supervisor that also binds 8080 exits at startup).
280pub const GCP_AGENT_PLATFORM: SandboxImage = SandboxImage {
281    exec_uid: 1000,
282    exec_gid: 1000,
283    session_root: "/sandbox",
284    port: AGENT_PORT,
285    authorization: Authorization::Transport,
286    isolation: Isolation::UidSplit,
287};
288
289/// Every variable a GCP Agent Platform image sets: the contract, then `RUST_LOG`.
290pub fn gcp_agent_platform_env() -> Vec<(&'static str, String)> {
291    let mut env = GCP_AGENT_PLATFORM.contract_env_vars().to_vec();
292    env.push(("RUST_LOG", GCP_AGENT_LOG_FILTER.to_string()));
293    env.push(("ALIEN_SANDBOX_IMAGE_COMMAND", "true".into()));
294    // The edge consumes `Authorization` for its own JWT, so a caller's bearer travels in a
295    // header of its own and the agent re-emits it towards the code inside.
296    env.push((
297        ENV_CALLER_AUTHORIZATION_HEADER,
298        CALLER_AUTHORIZATION_HEADER.into(),
299    ));
300    env
301}
302
303/// Azure serves the agent through a published port and an authenticated native file read.
304/// Its native exec path is never used for packaged images because it grants excess capabilities.
305pub const AZURE_SANDBOX: SandboxImage = SandboxImage {
306    exec_uid: 1000,
307    exec_gid: 1000,
308    session_root: "/sandbox",
309    port: AGENT_PORT,
310    authorization: Authorization::NativeFile,
311    isolation: Isolation::UidSplit,
312};
313
314/// A Kubernetes sandbox pod. The cluster's sandboxed runtime is the tenant boundary and refuses to
315/// start a root container here (`runAsNonRoot`), so the agent starts as the exec uid and
316/// supervises under it. Anything on the cluster network can reach the pod, so a caller presents a
317/// signed capability. The exec uid is a default: a non-root base `USER` replaces it.
318pub const KUBERNETES_SANDBOX: SandboxImage = SandboxImage {
319    exec_uid: 1000,
320    exec_gid: 1000,
321    session_root: "/sandbox",
322    port: AGENT_PORT,
323    authorization: Authorization::Capability,
324    isolation: Isolation::Platform,
325};
326
327/// The image every default sandbox builds on, by index digest so both architectures are pinned.
328///
329/// Bumped by hand, then regenerated: Renovate skips the generated Dockerfiles and does not read
330/// this file.
331pub const DEFAULT_SANDBOX_BASE_IMAGE: &str = "public.ecr.aws/docker/library/buildpack-deps:26.04@sha256:159ea382e6fb39e62480ee932113f885f7bd787cd4895fc4dc71aebb175077fd";
332
333/// The image uv and uvx are copied out of, by index digest.
334pub const DEFAULT_SANDBOX_UV_IMAGE: &str = "ghcr.io/astral-sh/uv:0.12.21@sha256:a7aed3216253ee804de3e2d8afa5073baa1a177335345d43845cd4165e43b711";
335
336/// A tool the default sandbox base ships, and the command that shows it runs.
337#[derive(Debug, Clone, Copy, PartialEq, Eq)]
338pub struct SandboxTool {
339    /// The Ubuntu archive package it comes from, or `None` for one copied out of
340    /// [`DEFAULT_SANDBOX_UV_IMAGE`].
341    pub package: Option<&'static str>,
342    /// Prints the tool's version and exits zero.
343    pub version_command: &'static str,
344}
345
346/// The toolchain of the default sandbox base, and the one list its probes read.
347///
348/// Every tool lands in `/usr/bin` or `/usr/local/bin`: a supervised command gets a fixed `PATH`
349/// and never the image's `ENV`, so a tool anywhere else is invisible to it.
350pub const DEFAULT_SANDBOX_TOOLS: &[SandboxTool] = &[
351    SandboxTool {
352        package: Some("nftables"),
353        version_command: "/usr/sbin/nft --version",
354    },
355    SandboxTool {
356        package: Some("iptables"),
357        version_command: "iptables-nft --version",
358    },
359    SandboxTool {
360        package: Some("nodejs"),
361        version_command: "node --version",
362    },
363    SandboxTool {
364        package: Some("npm"),
365        version_command: "npm --version",
366    },
367    SandboxTool {
368        package: Some("ripgrep"),
369        version_command: "rg --version",
370    },
371    SandboxTool {
372        package: Some("jq"),
373        version_command: "jq --version",
374    },
375    SandboxTool {
376        package: Some("zip"),
377        version_command: "zip -v",
378    },
379    SandboxTool {
380        package: Some("less"),
381        version_command: "less --version",
382    },
383    SandboxTool {
384        package: Some("nano"),
385        version_command: "nano --version",
386    },
387    SandboxTool {
388        package: Some("vim-tiny"),
389        version_command: "vim.tiny --version",
390    },
391    SandboxTool {
392        package: Some("htop"),
393        version_command: "htop --version",
394    },
395    SandboxTool {
396        package: None,
397        version_command: "uv --version",
398    },
399    SandboxTool {
400        package: None,
401        version_command: "uvx --version",
402    },
403];
404
405/// The `RUN` step creating the exec identity and the session root it owns.
406pub fn identity_setup(image: &SandboxImage) -> String {
407    format!(
408        r#"RUN test ! -L /etc/passwd && test ! -L /etc/group && test ! -L {root} \
409 && touch /etc/passwd /etc/group \
410 && chown 0:0 /etc/passwd /etc/group && chmod 0644 /etc/passwd /etc/group \
411 && (awk -F: '$3 == {uid} {{ found=1 }} END {{ exit !found }}' /etc/passwd || printf '{passwd}\n' >> /etc/passwd) \
412 && (awk -F: '$3 == {gid} {{ found=1 }} END {{ exit !found }}' /etc/group || printf '{group}\n' >> /etc/group) \
413 && mkdir -p {root} \
414 && chown {uid}:{gid} {root} \
415 && chmod {SESSION_ROOT_MODE:04o} {root}"#,
416        passwd = image.passwd_entry(),
417        group = image.group_entry(),
418        root = image.session_root,
419        uid = image.exec_uid,
420        gid = image.exec_gid(),
421    )
422}
423
424/// The `ENV` block carrying the agent's configuration contract.
425pub fn contract_env(image: &SandboxImage) -> String {
426    let vars: Vec<String> = image
427        .contract_env_vars()
428        .iter()
429        .map(|(name, value)| format!("{name}={value}"))
430        .collect();
431    format!("ENV {}", vars.join(" \\\n    "))
432}
433
434/// `EXPOSE`, the image's ending, and the `ENTRYPOINT`.
435pub fn entrypoint(image: &SandboxImage) -> String {
436    let ending = match image.user() {
437        None => String::new(),
438        Some(user) => format!(
439            "# Explicit gid so a runtime that does not read /etc/passwd cannot start the agent in \
440             group 0, which\n# makes the exec drop a privilege crossing whose setgroups needs a \
441             CAP_SETGID this image lacks, so\n# every exec fails.\nUSER {user}\n"
442        ),
443    };
444    format!(
445        "EXPOSE {port}\n{ending}ENTRYPOINT [\"{AGENT_PATH}\"]",
446        port = image.exposed_port()
447    )
448}
449
450/// Path of the committed minimal wolfi GCP Dockerfile, relative to the repository root.
451#[cfg(test)]
452const GCP_DOCKERFILE: &str = "docker/Dockerfile.alien-sandbox-agent";
453
454/// Path of the committed default GCP sandbox Dockerfile, relative to the repository root.
455#[cfg(test)]
456const GCP_DEFAULT_DOCKERFILE: &str = "docker/Dockerfile.alien-sandbox-gcp";
457
458/// Path of the committed default sandbox base Dockerfile, relative to the repository root.
459#[cfg(test)]
460const DEFAULT_SANDBOX_DOCKERFILE: &str = "docker/Dockerfile.alien-sandbox-default";
461
462/// Path of the committed tool list a probe of the default sandbox base reads.
463#[cfg(test)]
464const DEFAULT_SANDBOX_TOOLS_FILE: &str = "docker/sandbox-default-tools.txt";
465
466/// Set to regenerate every committed file this module renders instead of comparing against them.
467/// Named for the agent Dockerfile; every generated header prints the name, so a rename rewrites all.
468#[cfg(test)]
469const SANDBOX_FILES_UPDATE: &str = "UPDATE_SANDBOX_AGENT_DOCKERFILE";
470
471/// Renders [`DEFAULT_SANDBOX_DOCKERFILE`], the tools-only base every default sandbox builds on.
472#[cfg(test)]
473fn default_sandbox_dockerfile() -> String {
474    let packages: Vec<&str> = DEFAULT_SANDBOX_TOOLS
475        .iter()
476        .filter_map(|tool| tool.package)
477        .collect();
478    format!(
479        r#"# Generated by `cargo test -p alien-core --lib sandbox_image`. Do not edit by hand.
480# Regenerate with {SANDBOX_FILES_UPDATE}=1 in front of that command.
481#
482# Multi-arch tools-only base for the default sandbox images, with no agent. An image that runs the
483# agent adds it and its own ending on top, and a runtime with no in-guest agent runs this as is,
484# so it declares no USER, ENTRYPOINT or ENV.
485
486FROM {DEFAULT_SANDBOX_BASE_IMAGE}
487
488# No version pins: the -updates and -security pockets supersede a pinned version and the arm64
489# ports lag behind, so a pin breaks the build. The published digest is what fixes the versions.
490# ca-certificates is already in the base; naming it upgrades the trust store to the archive's
491# current one instead of the one frozen in the base digest.
492RUN apt-get update \
493 && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
494      ca-certificates {packages} \
495 && rm -rf /var/lib/apt/lists/*
496
497COPY --from={DEFAULT_SANDBOX_UV_IMAGE} /uv /uvx /usr/local/bin/
498"#,
499        packages = packages.join(" "),
500    )
501}
502
503/// Renders [`DEFAULT_SANDBOX_TOOLS_FILE`], one version command per line.
504#[cfg(test)]
505fn default_sandbox_tools_list() -> String {
506    let mut list = format!(
507        "# Generated by `cargo test -p alien-core --lib sandbox_image`. Do not edit by hand.
508# Regenerate with {SANDBOX_FILES_UPDATE}=1 in front of that command.
509#
510# One command per tool the default sandbox base ships; each prints a version and exits zero.
511"
512    );
513    for tool in DEFAULT_SANDBOX_TOOLS {
514        list.push_str(tool.version_command);
515        list.push('\n');
516    }
517    list
518}
519
520/// Where a GCP image's final stage starts.
521#[cfg(test)]
522enum GcpBase {
523    Image(&'static str),
524    /// A build-arg with no default, which whoever builds the image must pass.
525    BuildArg(&'static str),
526}
527
528/// Renders [`GCP_DOCKERFILE`], the minimal wolfi image.
529#[cfg(test)]
530fn gcp_agent_platform_dockerfile() -> String {
531    gcp_dockerfile(
532        "Multi-arch build for the alien-sandbox-agent Docker image",
533        GcpBase::Image("docker.io/chainguard/wolfi-base:latest"),
534        "# git is for the sandboxed command, not the agent, and pulls 24 transitive packages. That cost
535# lands here because this image is the sandbox, with no customer base image underneath to carry it.
536RUN apk add --no-cache git",
537    )
538}
539
540/// Renders [`GCP_DEFAULT_DOCKERFILE`], the default GCP sandbox image: the agent on the default
541/// sandbox base ([`DEFAULT_SANDBOX_DOCKERFILE`]), which whoever builds it passes by digest.
542#[cfg(test)]
543fn gcp_default_sandbox_dockerfile() -> String {
544    assert_eq!(
545        GCP_AGENT_PLATFORM.exec_uid, 1000,
546        "the userdel below exists only because Ubuntu's own user holds the exec uid"
547    );
548    gcp_dockerfile(
549        "Multi-arch build for the default GCP sandbox image: the default sandbox base plus the agent",
550        GcpBase::BuildArg("SANDBOX_DEFAULT_BASE"),
551        "# Ubuntu ships `ubuntu` at uid 1000. Appending a second entry for that uid leaves `id` and every
552# tool resolving it to `ubuntu`, so the exec user would not be `sandbox`.
553RUN userdel --remove ubuntu",
554    )
555}
556
557/// Renders a GCP Dockerfile onto `base`, with `base_setup` run as root before the agent lands.
558///
559/// Everything outside the shared block is here because it is true of the GCP images alone: the
560/// `binary-selector` stage, which exists because the release workflow builds one manifest for two
561/// architectures from binaries cross-compiled outside Docker; and `RUST_LOG`, which the agent's own
562/// `EnvFilter` needs before it will emit anything.
563#[cfg(test)]
564fn gcp_dockerfile(title: &str, base: GcpBase, base_setup: &str) -> String {
565    let image = &GCP_AGENT_PLATFORM;
566    // An ARG read by a FROM must precede the first FROM, or it is scoped to a stage and empty.
567    // BuildKit reads a parser directive only on the first lines, before any other comment.
568    let (directive, base_arg, base) = match base {
569        GcpBase::Image(reference) => (String::new(), String::new(), reference.to_string()),
570        GcpBase::BuildArg(name) => (
571            "# check=skip=InvalidDefaultArgInFrom\n".to_string(),
572            format!(
573                "# No default: the base's digest exists only once it is built, so whoever builds \
574                 this image\n# passes it. The check directive on line 1 is for this.\nARG {name}\n\n"
575            ),
576            format!("${{{name}}}"),
577        ),
578    };
579    format!(
580        r#"{directive}# Generated by `cargo test -p alien-core --lib sandbox_image`. Do not edit by hand.
581# Regenerate with {SANDBOX_FILES_UPDATE}=1 in front of that command.
582#
583# {title}
584# Run directly as the GCP Agent Platform sandbox; nothing layers on top of it
585
586{base_arg}FROM docker.io/chainguard/wolfi-base:latest AS binary-selector
587
588COPY target/aarch64-unknown-linux-musl/release/alien-sandbox-agent /tmp/alien-sandbox-agent-aarch64
589COPY target/x86_64-unknown-linux-musl/release/alien-sandbox-agent /tmp/alien-sandbox-agent-x86_64
590
591ARG TARGETARCH
592RUN case "$TARGETARCH" in \
593       amd64)  cp /tmp/alien-sandbox-agent-x86_64 /tmp/alien-sandbox-agent ;; \
594       arm64)  cp /tmp/alien-sandbox-agent-aarch64 /tmp/alien-sandbox-agent ;; \
595       *)      echo "unsupported TARGETARCH '$TARGETARCH'" >&2; exit 1 ;; \
596    esac
597
598FROM {base}
599
600{base_setup}
601
602# Root-owned and unwritable by uid {exec_uid}: the supervised command runs under that uid and must not
603# be able to rewrite its own supervisor.
604COPY --from=binary-selector --chown=0:0 --chmod={AGENT_MODE:04o} \
605     /tmp/alien-sandbox-agent {AGENT_PATH}
606
607# Numeric ids and a plain append rather than adduser, which differs across base distributions.
608# Linux runs a process under a uid with no passwd entry, but tooling inside the sandbox reads one.
609{identity}
610
611# The template carries no env, so the contract lives here, and none of it is optional. transport
612# serves an uncapabilitied request only from a socket `peer::transport_may_serve` cannot trace
613# back to the exec uid, and the agent refuses the mode where /proc/net/tcp is unreadable.
614{env}
615
616# The release build resolves tracing-subscriber once across every package it names, and five of
617# them ask for env-filter, so the agent's fmt::init() has an EnvFilter under it. Unset, that
618# filter discards the startup warning saying this image serves requests without a capability.
619ENV RUST_LOG={GCP_AGENT_LOG_FILTER} \
620    ALIEN_SANDBOX_IMAGE_COMMAND=true
621
622# The edge consumes `Authorization` for its own credential, so a preview caller's bearer arrives in
623# this header and the agent hands it to the code inside as `Authorization`.
624ENV {ENV_CALLER_AUTHORIZATION_HEADER}={CALLER_AUTHORIZATION_HEADER}
625
626# These published agent images have no application startup command. Declare that explicitly so
627# inherited base CMD values cannot become agent arguments or a second shell process.
628RUN mkdir -p /opt/alien \
629 && printf '%s\n' '{empty_image_command}' > {IMAGE_COMMAND_PATH} \
630 && chmod 0444 {IMAGE_COMMAND_PATH}
631
632{entrypoint}
633CMD []
634"#,
635        empty_image_command = serde_json::to_string(&SandboxImageCommand {
636            user: Some(String::new()),
637            working_directory: "/".into(),
638            ..Default::default()
639        })
640        .expect("static default image command must serialize"),
641        exec_uid = image.exec_uid,
642        identity = identity_setup(image),
643        env = contract_env(image),
644        entrypoint = entrypoint(image),
645    )
646}
647
648#[cfg(test)]
649mod tests {
650    use super::*;
651
652    /// A root-supervisor workload commonly binds 8080 itself; the agent must not take it.
653    #[test]
654    fn the_gcp_agent_leaves_port_8080_to_the_workload() {
655        assert_ne!(GCP_AGENT_PLATFORM.port, 8080);
656        assert_eq!(GCP_AGENT_PLATFORM.port, AGENT_PORT);
657    }
658
659    /// The published contract value (Docker's default set without `NET_RAW`); the name list the
660    /// pod grants must equal the mask the agent applies.
661    #[test]
662    fn root_capability_set_is_dockers_default_without_net_raw() {
663        assert_eq!(IMAGE_ROOT_CAPABILITY_MASK, 0xa80405fb);
664        for forbidden in ["NET_ADMIN", "SYS_ADMIN", "NET_RAW"] {
665            assert!(IMAGE_ROOT_CAPABILITY_SET
666                .iter()
667                .all(|(name, _)| *name != forbidden));
668        }
669    }
670
671    fn committed_path(relative: &str) -> std::path::PathBuf {
672        std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"))
673            .join("../..")
674            .join(relative)
675    }
676
677    /// Where two texts first part, in terms a reader can act on. `assert_eq!` on a whole
678    /// Dockerfile prints two escaped blobs and says nothing about which line moved.
679    fn first_difference(committed: &str, rendered: &str) -> String {
680        for (index, (left, right)) in committed.lines().zip(rendered.lines()).enumerate() {
681            if left != right {
682                let line = index + 1;
683                return format!("line {line}: committed {left:?}, contract renders {right:?}");
684            }
685        }
686        format!(
687            "committed has {} lines, the contract renders {}",
688            committed.lines().count(),
689            rendered.lines().count()
690        )
691    }
692
693    /// The whole file, not chosen properties. A mutation this comparison cannot see is one that
694    /// leaves the bytes alone, and there is no such mutation.
695    #[test]
696    fn the_committed_gcp_dockerfiles_are_what_the_contract_renders() {
697        for (file, rendered) in [
698            (GCP_DOCKERFILE, gcp_agent_platform_dockerfile()),
699            (GCP_DEFAULT_DOCKERFILE, gcp_default_sandbox_dockerfile()),
700            (DEFAULT_SANDBOX_DOCKERFILE, default_sandbox_dockerfile()),
701            (DEFAULT_SANDBOX_TOOLS_FILE, default_sandbox_tools_list()),
702        ] {
703            let path = committed_path(file);
704
705            if std::env::var_os(SANDBOX_FILES_UPDATE).is_some() {
706                std::fs::write(&path, &rendered)
707                    .unwrap_or_else(|error| panic!("{} must be writable: {error}", path.display()));
708                continue;
709            }
710
711            let committed = std::fs::read_to_string(&path)
712                .unwrap_or_else(|error| panic!("{} must be readable: {error}", path.display()));
713            assert!(
714                committed == rendered,
715                "{file} has drifted from the contract it is rendered from.\n\
716                 {}\n\
717                 Regenerate it: {SANDBOX_FILES_UPDATE}=1 cargo test -p alien-core --lib sandbox_image",
718                first_difference(&committed, &rendered)
719            );
720        }
721    }
722
723    /// An image built without a Dockerfile carries what the CI images carry, so the env the
724    /// accessor hands out is read back from the committed file rather than restated.
725    #[test]
726    fn the_gcp_env_accessor_is_every_env_the_committed_dockerfile_sets() {
727        let committed = std::fs::read_to_string(committed_path(GCP_DEFAULT_DOCKERFILE)).unwrap();
728        let mut set = Vec::new();
729        let mut in_env = false;
730        for line in committed.lines() {
731            let line = line.trim();
732            let rest = match line.strip_prefix("ENV ") {
733                Some(rest) => rest,
734                None if in_env => line,
735                None => continue,
736            };
737            in_env = rest.ends_with('\\');
738            for pair in rest.trim_end_matches('\\').split_whitespace() {
739                let (name, value) = pair.split_once('=').expect("ENV name=value");
740                set.push((name.to_string(), value.to_string()));
741            }
742        }
743        let accessor: Vec<(String, String)> = gcp_agent_platform_env()
744            .into_iter()
745            .map(|(name, value)| (name.to_string(), value))
746            .collect();
747        assert_eq!(accessor, set);
748    }
749
750    /// Every consumer derives these, so nothing else compares them against a number. The
751    /// setup emitters tell the agent which uid to drop to; if that stops matching the uid the
752    /// image creates, the sandbox starts and every exec fails.
753    #[test]
754    fn the_two_images_carry_the_identities_their_stacks_were_built_against() {
755        assert_eq!(AWS_MICROVM.port, 8971);
756        assert_eq!(AWS_MICROVM.exec_uid, 60000);
757        assert_eq!(AWS_MICROVM.session_root, "/sandbox");
758        assert_eq!(GCP_AGENT_PLATFORM.port, 8971);
759        assert_eq!(GCP_AGENT_PLATFORM.exec_uid, 1000);
760        assert_eq!(GCP_AGENT_PLATFORM.session_root, "/sandbox");
761        for image in [&AWS_MICROVM, &GCP_AGENT_PLATFORM] {
762            assert_ne!(image.exec_uid, 0, "the exec uid must never be root");
763        }
764    }
765
766    /// The ending an image declares and the isolation it claims come off one value, so they
767    /// cannot disagree. The AWS half is rendered at run time and reaches no committed file, which
768    /// is why the whole-file comparison above covers only the GCP side of it.
769    #[test]
770    fn the_ending_an_image_declares_follows_its_isolation() {
771        assert!(!entrypoint(&AWS_MICROVM).contains("USER "));
772        assert!(contract_env(&AWS_MICROVM).contains("ALIEN_SANDBOX_ISOLATION=uid-split"));
773        assert_eq!(GCP_AGENT_PLATFORM.isolation, Isolation::UidSplit);
774        assert!(contract_env(&GCP_AGENT_PLATFORM).contains("ALIEN_SANDBOX_ISOLATION=uid-split"));
775    }
776}
777
778/// Root-owned metadata copied from the base image at bundle creation, never from an exec caller.
779#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize)]
780#[serde(rename_all = "camelCase", deny_unknown_fields)]
781pub struct SandboxImageCommand {
782    /// Original OCI USER, including an empty string for Docker's root default.
783    /// Absent only in released metadata whose boot command used the exec identity.
784    #[serde(default, skip_serializing_if = "Option::is_none")]
785    pub user: Option<String>,
786    /// OCI Entrypoint followed by Cmd; empty means there is no image command.
787    pub command: Vec<String>,
788    /// Image environment only, before runtime authorization and provider variables are added.
789    pub env: std::collections::BTreeMap<String, String>,
790    /// OCI WorkingDir, or / if the image does not declare one.
791    pub working_directory: String,
792}
793
794/// Installed outside the command-writable session directory.
795pub const IMAGE_COMMAND_PATH: &str = "/opt/alien/image-command.json";
796
797/// Per-boot agent credential read only through an authenticated native file API.
798pub const NATIVE_TOKEN_PATH: &str = "/opt/alien/native-token";