Skip to main content

alien_core/
sandbox_image_permissions.rs

1//! The stack side of a sandbox's image permissions: which resources a connection may name, and
2//! the startup contract deployment hands the agent.
3//!
4//! The declaration lives on [`crate::Sandbox`] and is checked on its own there. What needs the
5//! whole stack is here: a connection names another resource, and deployment resolves it to an
6//! address range from where that resource's endpoints sit.
7
8use crate::error::{ErrorData, Result};
9use crate::sandbox_egress::{sandbox_egress_network, sandbox_plans_connector, SandboxEgressVpc};
10use crate::sandbox_image::{
11    ENV_IMAGE_COMMAND, ENV_IMAGE_PERMISSIONS, ENV_IMAGE_PERMISSIONS_VERSION,
12    IMAGE_COMMAND_WITH_IMAGE_PERMISSIONS, IMAGE_PERMISSIONS_VERSION,
13};
14use crate::{
15    PrivateEndpointPlacement, ResourceRef, Sandbox, SandboxImageConnection, SandboxImageMountType,
16    Stack,
17};
18use alien_error::AlienError;
19use serde::{Deserialize, Serialize};
20use std::collections::BTreeMap;
21
22/// Where the resource a connection names has its private endpoints, or `None` when it has none
23/// a sandbox may connect to.
24///
25/// Built-in types answer through [`crate::PrivateNetworkEndpoints`]; none does yet. An
26/// extension's type answers through its descriptor.
27pub fn private_endpoint_placement(
28    stack: &Stack,
29    target: &ResourceRef,
30) -> Option<PrivateEndpointPlacement> {
31    let entry = stack.resources.get(&target.id)?;
32    if entry.config.resource_type() != target.resource_type {
33        return None;
34    }
35    stack
36        .descriptor(&target.resource_type)
37        .and_then(|descriptor| descriptor.private_network_endpoints)
38}
39
40/// Refuses connections deployment could not narrow to the private addresses of the resource they
41/// name.
42pub fn validate_connections(stack: &Stack, sandbox: &Sandbox) -> Result<()> {
43    let Some(permissions) = &sandbox.image_permissions else {
44        return Ok(());
45    };
46    if permissions.connections.is_empty() {
47        return Ok(());
48    }
49    let refuse = |connection: &SandboxImageConnection, reason: String| {
50        AlienError::new(ErrorData::SandboxLimitInvalid {
51            resource_id: sandbox.id.clone(),
52            field: "imagePermissions.connections.to".to_string(),
53            value: format!(
54                "{}:{} port {}",
55                connection.to.resource_type, connection.to.id, connection.port
56            ),
57            reason,
58        })
59    };
60    for connection in &permissions.connections {
61        // The target's addresses exist only once it does, after setup; a sandbox whose image
62        // setup builds would have to carry a range wider than the target.
63        if stack
64            .resources
65            .get(&sandbox.id)
66            .is_some_and(|entry| entry.lifecycle != crate::ResourceLifecycle::Live)
67        {
68            return Err(refuse(
69                connection,
70                "a direct connection needs a sandbox provisioned at runtime (live), which \
71                 narrows it to the addresses the target publishes once it exists"
72                    .to_string(),
73            ));
74        }
75        if private_endpoint_placement(stack, &connection.to).is_none() {
76            return Err(refuse(
77                connection,
78                "must name a resource in this stack that exposes private network endpoints"
79                    .to_string(),
80            ));
81        }
82        // The connection is a rule on the connector's security group; without a connector the
83        // sandbox reaches everything directly and the declaration would bound nothing.
84        if !sandbox_plans_connector(sandbox) {
85            return Err(refuse(
86                connection,
87                "a direct connection needs the sandbox's egress connector; declare egress \
88                 \"internet\" or \"none\""
89                    .to_string(),
90            ));
91        }
92        // The address range comes from the network setup creates. A network the customer
93        // brings has no range setup can read, and guessing one would widen the rule.
94        if let Ok(network) = sandbox_egress_network(stack) {
95            if network.vpc == SandboxEgressVpc::BroughtByCustomer {
96                return Err(refuse(
97                    connection,
98                    "direct connections are not yet available with a network the customer \
99                     brings; use a network setup creates"
100                        .to_string(),
101                ));
102            }
103        }
104    }
105    Ok(())
106}
107
108/// One mount in the agent's startup contract.
109#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
110#[serde(rename_all = "camelCase", deny_unknown_fields)]
111pub struct ContractMount {
112    /// `nfs`, `tmpfs` or `bind`.
113    #[serde(rename = "type")]
114    pub mount_type: SandboxImageMountType,
115    /// Absolute, normalized target path.
116    pub path: String,
117    /// Size in bytes; tmpfs only.
118    #[serde(default, skip_serializing_if = "Option::is_none")]
119    pub size_bytes: Option<u64>,
120    /// Source path; bind only. A declared tmpfs mount path.
121    #[serde(default, skip_serializing_if = "Option::is_none")]
122    pub from: Option<String>,
123}
124
125/// One direct connection in the agent's startup contract, already resolved to an address range.
126#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
127#[serde(rename_all = "camelCase", deny_unknown_fields)]
128pub struct ContractConnection {
129    /// Private IPv4 CIDR.
130    pub cidr: String,
131    /// TCP port, never 53.
132    pub port: u16,
133}
134
135/// The value of `ALIEN_SANDBOX_IMAGE_PERMISSIONS`: what the agent may do for the image.
136#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
137#[serde(rename_all = "camelCase", deny_unknown_fields)]
138pub struct ImagePermissionsContract {
139    pub mounts: Vec<ContractMount>,
140    pub connections: Vec<ContractConnection>,
141    #[serde(default, skip_serializing_if = "Option::is_none")]
142    pub on_pause: Option<Vec<String>>,
143    #[serde(default, skip_serializing_if = "Option::is_none")]
144    pub on_resume: Option<Vec<String>>,
145}
146
147/// The output field a connection target publishes its private IPv4 addresses in, once it exists.
148/// Deployment narrows each connection to exactly these addresses (`/32` each) and the port.
149pub const PRIVATE_IPV4_ADDRESSES_OUTPUT: &str = "privateIpv4Addresses";
150
151/// The `/32` ranges of the addresses a connection target published in its outputs
152/// ([`PRIVATE_IPV4_ADDRESSES_OUTPUT`]). Refuses a target that published none, or anything but
153/// private IPv4 addresses, rather than open a wider range.
154pub fn published_connection_addresses(
155    sandbox: &Sandbox,
156    connection: &SandboxImageConnection,
157    outputs: Option<&serde_json::Value>,
158) -> Result<Vec<String>> {
159    let refuse = |reason: String| {
160        AlienError::new(ErrorData::SandboxLimitInvalid {
161            resource_id: sandbox.id.clone(),
162            field: "imagePermissions.connections.to".to_string(),
163            value: format!("{}:{}", connection.to.id, connection.port),
164            reason,
165        })
166    };
167    let Some(published) = outputs.and_then(|outputs| outputs.get(PRIVATE_IPV4_ADDRESSES_OUTPUT))
168    else {
169        return Err(refuse(format!(
170            "'{}' has not published its private addresses ({PRIVATE_IPV4_ADDRESSES_OUTPUT}) yet",
171            connection.to.id
172        )));
173    };
174    let entries = published.as_array().ok_or_else(|| {
175        refuse(format!(
176            "'{}' published {PRIVATE_IPV4_ADDRESSES_OUTPUT} that is not a list",
177            connection.to.id
178        ))
179    })?;
180    let mut addresses = std::collections::BTreeSet::new();
181    for entry in entries {
182        let address = entry
183            .as_str()
184            .and_then(|text| text.parse::<std::net::Ipv4Addr>().ok())
185            .filter(std::net::Ipv4Addr::is_private)
186            .ok_or_else(|| {
187                refuse(format!(
188                    "'{}' published {entry} in {PRIVATE_IPV4_ADDRESSES_OUTPUT}, which is not a \
189                     private IPv4 address",
190                    connection.to.id
191                ))
192            })?;
193        addresses.insert(address);
194    }
195    if addresses.is_empty() {
196        return Err(refuse(format!(
197            "'{}' published no private addresses",
198            connection.to.id
199        )));
200    }
201    Ok(addresses
202        .into_iter()
203        .map(|address| format!("{address}/32"))
204        .collect())
205}
206
207/// The contract for `sandbox`, with each connection resolved by `addresses` to the ranges it may
208/// reach (one contract entry per range). `None` when the sandbox declares no image permissions
209/// and no lifecycle steps.
210pub fn image_permissions_contract(
211    sandbox: &Sandbox,
212    addresses: impl Fn(&SandboxImageConnection) -> Result<Vec<String>>,
213) -> Result<Option<ImagePermissionsContract>> {
214    if !sandbox.declares_image_permissions() {
215        return Ok(None);
216    }
217    let permissions = sandbox.image_permissions.clone().unwrap_or_default();
218    let mounts = permissions
219        .mounts
220        .iter()
221        .map(|mount| {
222            let size_bytes = mount
223                .size
224                .as_deref()
225                .map(|size| {
226                    crate::tmpfs_size_bytes(size).map_err(|reason| {
227                        AlienError::new(ErrorData::SandboxLimitInvalid {
228                            resource_id: sandbox.id.clone(),
229                            field: "imagePermissions.mounts.size".to_string(),
230                            value: size.to_string(),
231                            reason,
232                        })
233                    })
234                })
235                .transpose()?;
236            Ok(ContractMount {
237                mount_type: mount.mount_type,
238                path: mount.path.clone(),
239                size_bytes,
240                from: mount.from.clone(),
241            })
242        })
243        .collect::<Result<Vec<_>>>()?;
244    Ok(Some(ImagePermissionsContract {
245        mounts,
246        connections: permissions
247            .connections
248            .iter()
249            .map(|connection| {
250                Ok(addresses(connection)?
251                    .into_iter()
252                    .map(|cidr| ContractConnection {
253                        cidr,
254                        port: connection.port,
255                    })
256                    .collect::<Vec<_>>())
257            })
258            .collect::<Result<Vec<_>>>()?
259            .into_iter()
260            .flatten()
261            .collect(),
262        on_pause: sandbox.lifecycle.on_pause.clone(),
263        on_resume: sandbox.lifecycle.on_resume.clone(),
264    }))
265}
266
267/// MicroVM session hooks the agent serves, as the image declares them.
268///
269/// `Run` and `Resume` are always enabled at 30s: the agent acknowledges them. A declared
270/// `onPause` step enables `Suspend`, and a declared `onResume` step raises `Resume`'s ceiling,
271/// each to 60s so the vendor's step has room inside the hook. An image without either keeps the
272/// hooks it had, key for key.
273#[derive(Debug, Clone, Copy, PartialEq, Eq)]
274pub struct AwsMicrovmSessionHooks {
275    pub run_timeout_in_seconds: u32,
276    pub resume_timeout_in_seconds: u32,
277    /// `Some` enables the suspend hook with this ceiling; `None` leaves it out of the request.
278    pub suspend_timeout_in_seconds: Option<u32>,
279}
280
281/// Ceiling on a hook that runs a declared lifecycle step.
282pub const LIFECYCLE_STEP_HOOK_TIMEOUT_SECONDS: u32 = 60;
283/// Ceiling on a hook the agent only acknowledges.
284pub const ACKNOWLEDGED_HOOK_TIMEOUT_SECONDS: u32 = 30;
285
286pub fn aws_microvm_session_hooks(sandbox: &Sandbox) -> AwsMicrovmSessionHooks {
287    AwsMicrovmSessionHooks {
288        run_timeout_in_seconds: ACKNOWLEDGED_HOOK_TIMEOUT_SECONDS,
289        resume_timeout_in_seconds: if sandbox.lifecycle.on_resume.is_some() {
290            LIFECYCLE_STEP_HOOK_TIMEOUT_SECONDS
291        } else {
292            ACKNOWLEDGED_HOOK_TIMEOUT_SECONDS
293        },
294        suspend_timeout_in_seconds: sandbox
295            .lifecycle
296            .on_pause
297            .is_some()
298            .then_some(LIFECYCLE_STEP_HOOK_TIMEOUT_SECONDS),
299    }
300}
301
302impl Default for AwsMicrovmSessionHooks {
303    /// The hooks of an image that declares no lifecycle step.
304    fn default() -> Self {
305        Self {
306            run_timeout_in_seconds: ACKNOWLEDGED_HOOK_TIMEOUT_SECONDS,
307            resume_timeout_in_seconds: ACKNOWLEDGED_HOOK_TIMEOUT_SECONDS,
308            suspend_timeout_in_seconds: None,
309        }
310    }
311}
312
313/// The variables that make a released agent refuse to start and tell a current one which
314/// contract version it is reading. Set together with `ALIEN_SANDBOX_IMAGE_PERMISSIONS`.
315///
316/// A released agent accepts only `true` for `ALIEN_SANDBOX_IMAGE_COMMAND`, so an image whose
317/// bundle carries one fails its build's validate hook instead of running the image without the
318/// declared limits.
319pub fn image_permissions_markers() -> BTreeMap<String, String> {
320    BTreeMap::from([
321        (
322            ENV_IMAGE_COMMAND.to_string(),
323            IMAGE_COMMAND_WITH_IMAGE_PERMISSIONS.to_string(),
324        ),
325        (
326            ENV_IMAGE_PERMISSIONS_VERSION.to_string(),
327            IMAGE_PERMISSIONS_VERSION.to_string(),
328        ),
329    ])
330}
331
332/// The full environment for a sandbox, with each connection resolved by `addresses` (see
333/// [`published_connection_addresses`]). Empty when nothing is declared.
334pub fn image_permissions_environment(
335    sandbox: &Sandbox,
336    addresses: impl Fn(&SandboxImageConnection) -> Result<Vec<String>>,
337) -> Result<BTreeMap<String, String>> {
338    if sandbox.declares_image_permissions() && sandbox.image_user.is_none() {
339        return Err(AlienError::new(ErrorData::SandboxLimitInvalid {
340            resource_id: sandbox.id.clone(),
341            field: "imagePermissions".to_string(),
342            value: "image".to_string(),
343            reason: "image permissions need an image `alien build` inspected; rebuild the release"
344                .to_string(),
345        }));
346    }
347    let Some(contract) = image_permissions_contract(sandbox, addresses)? else {
348        return Ok(BTreeMap::new());
349    };
350    let mut environment = image_permissions_markers();
351    environment.insert(
352        ENV_IMAGE_PERMISSIONS.to_string(),
353        serde_json::to_string(&contract).expect("the contract serializes"),
354    );
355    Ok(environment)
356}
357
358/// Plain-language lines for the person approving setup: what the image may mount, which
359/// connections bypass the gateway, and whose responsibility isolation inside the image is.
360pub fn approval_statements(sandbox: &Sandbox) -> Vec<String> {
361    let mut statements = Vec::new();
362    let permissions = sandbox.image_permissions.clone().unwrap_or_default();
363    for mount in &permissions.mounts {
364        statements.push(match (&mount.mount_type, &mount.size, &mount.from) {
365            (SandboxImageMountType::Tmpfs, Some(size), _) => format!(
366                "The sandbox image may mount a tmpfs of {size} at {}.",
367                mount.path
368            ),
369            (SandboxImageMountType::Bind, _, Some(from)) => format!(
370                "The sandbox image may place {from} again at {}.",
371                mount.path
372            ),
373            (mount_type, _, _) => format!(
374                "The sandbox image may mount {} at {}.",
375                match mount_type {
376                    SandboxImageMountType::Nfs => "an NFS file system",
377                    SandboxImageMountType::Tmpfs => "a tmpfs",
378                    SandboxImageMountType::Bind => "a bind mount",
379                },
380                mount.path
381            ),
382        });
383    }
384    for connection in &permissions.connections {
385        statements.push(format!(
386            "The sandbox image may connect directly to {} on TCP port {}. Setup allows that port \
387             to the network's address range; the sandbox narrows it to the addresses {} \
388             publishes. This connection bypasses the egress gateway and is not in its \
389             connection log.",
390            connection.to.id, connection.port, connection.to.id
391        ));
392    }
393    if sandbox.lifecycle.on_pause.is_some() || sandbox.lifecycle.on_resume.is_some() {
394        statements.push(
395            "The sandbox image runs its own steps before a pause and after a resume.".to_string(),
396        );
397    }
398    if !statements.is_empty() {
399        statements.push(
400            "Isolation between workloads inside the sandbox image is the image vendor's \
401             responsibility."
402                .to_string(),
403        );
404    }
405    statements
406}
407
408#[cfg(test)]
409mod tests {
410    use super::*;
411    use crate::{
412        CustomResource, Network, NetworkSettings, ResourceLifecycle, ResourceType, SandboxCode,
413        SandboxEgress, SandboxImageMount, SandboxImagePermissions, SandboxLifecyclePolicy,
414    };
415
416    fn manifest(private_endpoints: bool) -> serde_json::Value {
417        let mut descriptor = serde_json::json!({
418            "lifecycles": ["live"],
419            "holdsData": true,
420            "setup": { "cloudformation": [], "terraform": [], "helm": [], "importers": [] },
421            "controllerPlatforms": ["aws"],
422            "permissionSets": [],
423            "link": { "permissionSets": [] },
424            "schemas": { "config": {}, "outputs": {} },
425            "requiresNetwork": true
426        });
427        if private_endpoints {
428            descriptor["privateNetworkEndpoints"] = "stackNetwork".into();
429        }
430        serde_json::json!({
431            "name": "acme",
432            "version": "0.1.0",
433            "digest": "sha256:00",
434            "resourceTypes": { "acme/files": descriptor }
435        })
436    }
437
438    fn files() -> CustomResource {
439        CustomResource::from_untagged("acme/files", serde_json::json!({ "id": "workspace-files" }))
440            .unwrap()
441    }
442
443    fn sandbox(egress: SandboxEgress, image_permissions: SandboxImagePermissions) -> Sandbox {
444        let mut sandbox = Sandbox::new("sandboxes".to_string())
445            .code(SandboxCode::Image {
446                image: "s3://bundles/sandboxes.zip".to_string(),
447                bundled_from: None,
448            })
449            .egress(egress)
450            .lifecycle(SandboxLifecyclePolicy {
451                on_pause: Some(vec!["/usr/local/bin/app".into(), "pause".into()]),
452                on_resume: Some(vec!["/usr/local/bin/app".into(), "resume".into()]),
453                ..Default::default()
454            })
455            .build();
456        sandbox.image_permissions = Some(image_permissions);
457        sandbox.image_user = Some(0);
458        sandbox
459    }
460
461    fn designed() -> SandboxImagePermissions {
462        SandboxImagePermissions {
463            mounts: vec![
464                SandboxImageMount {
465                    mount_type: SandboxImageMountType::Nfs,
466                    path: "/workspace".into(),
467                    size: None,
468                    from: None,
469                },
470                SandboxImageMount {
471                    mount_type: SandboxImageMountType::Tmpfs,
472                    path: "/var/lib/app/scratch".into(),
473                    size: Some("8Gi".into()),
474                    from: None,
475                },
476                SandboxImageMount {
477                    mount_type: SandboxImageMountType::Bind,
478                    path: "/workspace/tmp".into(),
479                    size: None,
480                    from: Some("/var/lib/app/scratch".into()),
481                },
482            ],
483            connections: vec![SandboxImageConnection {
484                to: ResourceRef::new(ResourceType::from("acme/files"), "workspace-files"),
485                port: 2049,
486            }],
487        }
488    }
489
490    fn stack(settings: NetworkSettings, private_endpoints: bool, sandbox: Sandbox) -> Stack {
491        stack_with(
492            settings,
493            private_endpoints,
494            sandbox,
495            ResourceLifecycle::Live,
496        )
497    }
498
499    fn stack_with(
500        settings: NetworkSettings,
501        private_endpoints: bool,
502        sandbox: Sandbox,
503        lifecycle: ResourceLifecycle,
504    ) -> Stack {
505        let mut stack = Stack::new("app".to_string())
506            .add(
507                Network::new("net".to_string()).settings(settings).build(),
508                ResourceLifecycle::Frozen,
509            )
510            .add(files(), ResourceLifecycle::Live)
511            .add(sandbox, lifecycle)
512            .build();
513        stack.extensions = vec![serde_json::from_value(manifest(private_endpoints)).unwrap()];
514        stack
515    }
516
517    fn created() -> NetworkSettings {
518        NetworkSettings::Create {
519            cidr: Some("10.0.0.0/16".into()),
520            availability_zones: 2,
521        }
522    }
523
524    #[test]
525    fn a_connection_resolves_only_to_a_resource_with_private_endpoints() {
526        let declared = sandbox(SandboxEgress::Internet, designed());
527        validate_connections(&stack(created(), true, declared.clone()), &declared).unwrap();
528
529        let error = validate_connections(&stack(created(), false, declared.clone()), &declared)
530            .unwrap_err();
531        assert!(
532            error.to_string().contains("private network endpoints"),
533            "{error}"
534        );
535
536        let mut missing = designed();
537        missing.connections[0].to.id = "elsewhere".into();
538        let declared = sandbox(SandboxEgress::Internet, missing);
539        assert!(
540            validate_connections(&stack(created(), true, declared.clone()), &declared).is_err()
541        );
542
543        let mut wrong_type = designed();
544        wrong_type.connections[0].to.resource_type = ResourceType::from("storage");
545        let declared = sandbox(SandboxEgress::Internet, wrong_type);
546        assert!(
547            validate_connections(&stack(created(), true, declared.clone()), &declared).is_err()
548        );
549    }
550
551    #[test]
552    fn a_connection_needs_a_connector_and_a_network_setup_creates() {
553        let direct = sandbox(SandboxEgress::Allow, designed());
554        let error =
555            validate_connections(&stack(created(), true, direct.clone()), &direct).unwrap_err();
556        assert!(error.to_string().contains("connector"), "{error}");
557
558        let declared = sandbox(SandboxEgress::None, designed());
559        let byo = NetworkSettings::ByoVpcAws {
560            vpc_id: "vpc-1".into(),
561            public_subnet_ids: vec![],
562            private_subnet_ids: vec!["subnet-1".into()],
563            security_group_ids: vec![],
564        };
565        let error =
566            validate_connections(&stack(byo, true, declared.clone()), &declared).unwrap_err();
567        assert!(error.to_string().contains("brings"), "{error}");
568    }
569
570    /// A sandbox whose image setup builds cannot wait for the target's addresses.
571    #[test]
572    fn a_connection_needs_a_sandbox_provisioned_at_runtime() {
573        let declared = sandbox(SandboxEgress::None, designed());
574        let frozen = stack_with(created(), true, declared.clone(), ResourceLifecycle::Frozen);
575        let error = validate_connections(&frozen, &declared).unwrap_err();
576        assert!(
577            error.to_string().contains("provisioned at runtime"),
578            "{error}"
579        );
580
581        let mut mounts_only = designed();
582        mounts_only.connections.clear();
583        let declared = sandbox(SandboxEgress::None, mounts_only);
584        let frozen = stack_with(created(), true, declared.clone(), ResourceLifecycle::Frozen);
585        validate_connections(&frozen, &declared).unwrap();
586    }
587
588    fn resolve(sandbox: &Sandbox, outputs: serde_json::Value) -> Result<BTreeMap<String, String>> {
589        image_permissions_environment(sandbox, |connection| {
590            published_connection_addresses(sandbox, connection, Some(&outputs))
591        })
592    }
593
594    /// Each connection is the target's own addresses, one `/32` each, never a wider range.
595    #[test]
596    fn a_connection_resolves_to_each_published_address() {
597        let declared = sandbox(SandboxEgress::Internet, designed());
598        let environment = resolve(
599            &declared,
600            serde_json::json!({ "privateIpv4Addresses": ["10.0.2.7", "10.0.1.5", "10.0.1.5"] }),
601        )
602        .unwrap();
603        let contract: serde_json::Value =
604            serde_json::from_str(&environment["ALIEN_SANDBOX_IMAGE_PERMISSIONS"]).unwrap();
605        assert_eq!(
606            contract["connections"],
607            serde_json::json!([
608                {"cidr": "10.0.1.5/32", "port": 2049},
609                {"cidr": "10.0.2.7/32", "port": 2049}
610            ])
611        );
612
613        for outputs in [
614            serde_json::json!({}),
615            serde_json::json!({ "privateIpv4Addresses": [] }),
616            serde_json::json!({ "privateIpv4Addresses": "10.0.1.5" }),
617            serde_json::json!({ "privateIpv4Addresses": ["10.0.0.0/16"] }),
618            serde_json::json!({ "privateIpv4Addresses": ["8.8.8.8"] }),
619            serde_json::json!({ "privateIpv4Addresses": ["fd00::1"] }),
620            serde_json::json!({ "privateIpv4Addresses": [17] }),
621        ] {
622            assert!(resolve(&declared, outputs.clone()).is_err(), "{outputs}");
623        }
624        assert!(image_permissions_environment(&declared, |connection| {
625            published_connection_addresses(&declared, connection, None)
626        })
627        .is_err());
628    }
629
630    /// The exact value the agent box parses, from the shared contract.
631    #[test]
632    fn the_environment_is_the_shared_contract() {
633        let declared = sandbox(SandboxEgress::Internet, designed());
634        let environment = resolve(
635            &declared,
636            serde_json::json!({ "privateIpv4Addresses": ["10.0.1.5"] }),
637        )
638        .unwrap();
639        assert_eq!(
640            environment["ALIEN_SANDBOX_IMAGE_COMMAND"],
641            "image-permissions-v1"
642        );
643        assert_eq!(environment["ALIEN_SANDBOX_IMAGE_PERMISSIONS_V"], "1");
644        let contract: serde_json::Value =
645            serde_json::from_str(&environment["ALIEN_SANDBOX_IMAGE_PERMISSIONS"]).unwrap();
646        assert_eq!(
647            contract,
648            serde_json::json!({
649                "mounts": [
650                    {"type": "nfs", "path": "/workspace"},
651                    {"type": "tmpfs", "path": "/var/lib/app/scratch", "sizeBytes": 8589934592u64},
652                    {"type": "bind", "from": "/var/lib/app/scratch", "path": "/workspace/tmp"}
653                ],
654                "connections": [{"cidr": "10.0.1.5/32", "port": 2049}],
655                "onPause": ["/usr/local/bin/app", "pause"],
656                "onResume": ["/usr/local/bin/app", "resume"]
657            })
658        );
659        assert_eq!(environment.len(), 3);
660    }
661
662    #[test]
663    fn nothing_declared_sets_nothing_and_connections_need_an_address_range() {
664        let mut plain = sandbox(SandboxEgress::Internet, designed());
665        plain.image_permissions = None;
666        plain.lifecycle = SandboxLifecyclePolicy::default();
667        assert!(
668            image_permissions_environment(&plain, |_| unreachable!("nothing to resolve"))
669                .unwrap()
670                .is_empty()
671        );
672        assert!(approval_statements(&plain).is_empty());
673
674        let declared = sandbox(SandboxEgress::Internet, designed());
675        assert!(resolve(&declared, serde_json::json!({})).is_err());
676
677        let mut legacy = declared.clone();
678        legacy.image_user = None;
679        assert!(resolve(
680            &legacy,
681            serde_json::json!({ "privateIpv4Addresses": ["10.0.1.5"] })
682        )
683        .is_err());
684    }
685
686    #[test]
687    fn approval_lists_mounts_connections_and_whose_isolation_it_is() {
688        let statements = approval_statements(&sandbox(SandboxEgress::Internet, designed()));
689        assert_eq!(
690            statements,
691            [
692                "The sandbox image may mount an NFS file system at /workspace.",
693                "The sandbox image may mount a tmpfs of 8Gi at /var/lib/app/scratch.",
694                "The sandbox image may place /var/lib/app/scratch again at /workspace/tmp.",
695                "The sandbox image may connect directly to workspace-files on TCP port 2049. \
696                 Setup allows that port to the network's address range; the sandbox narrows it \
697                 to the addresses workspace-files publishes. This connection bypasses the egress \
698                 gateway and is not in its connection log.",
699                "The sandbox image runs its own steps before a pause and after a resume.",
700                "Isolation between workloads inside the sandbox image is the image vendor's \
701                 responsibility.",
702            ]
703        );
704    }
705}