1use crate::error::{ErrorData, Result};
11use crate::resource::{ResourceDefinition, ResourceOutputsDefinition, ResourceRef, ResourceType};
12use crate::resources::sandbox_image_permissions;
13pub use crate::resources::sandbox_image_permissions::{
14 tmpfs_size_bytes, PrivateEndpointPlacement, PrivateNetworkEndpoints, SandboxImageConnection,
15 SandboxImageMount, SandboxImageMountType, SandboxImagePermissions,
16};
17use crate::resources::ToolchainConfig;
18use crate::Platform;
19use alien_error::AlienError;
20use bon::Builder;
21use serde::{Deserialize, Serialize};
22use sha2::{Digest, Sha256};
23use std::any::Any;
24use std::fmt::Debug;
25
26#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
28#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
29#[serde(rename_all = "camelCase", tag = "type")]
30pub enum SandboxCode {
31 #[serde(rename_all = "camelCase")]
33 Image {
34 image: String,
38 #[serde(default, skip_serializing_if = "Option::is_none")]
43 #[cfg_attr(feature = "openapi", schema(ignore))]
44 bundled_from: Option<String>,
45 },
46 #[serde(rename_all = "camelCase")]
52 Source {
53 src: String,
55 toolchain: ToolchainConfig,
57 },
58}
59
60#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
66#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
67#[serde(rename_all = "camelCase", deny_unknown_fields)]
68pub struct SandboxLimits {
69 pub cpu: String,
71 pub memory: String,
73 pub disk: String,
75 #[serde(default, skip_serializing_if = "Option::is_none")]
81 pub max_processes: Option<u32>,
82}
83
84#[derive(Debug, Clone, Copy, PartialEq, Eq)]
90pub struct MicrovmTier {
91 pub baseline_memory_mib: i64,
93 pub peak_memory_mib: i64,
95 pub peak_vcpu: u32,
97 pub max_disk_mib: i64,
99}
100
101const AWS_MAX_LIFETIME_SECONDS: u32 = 28_800;
105
106const KUBERNETES_MAX_LIFETIME_SECONDS: u32 = i32::MAX as u32;
109
110const GCP_MAX_DISK_BYTES: u128 = 10 * 1024 * 1024 * 1024;
113
114const AZURE_CPU_STEP_MILLICORES: i64 = 250;
117const AZURE_MAX_CPU_MILLICORES: i64 = 16_000;
118const AZURE_MEMORY_MIB_PER_CORE: i64 = 2 * 1024;
119const AZURE_DISK_MIB_PER_CORE: i64 = 20 * 1024;
120
121const MICROVM_TIERS: &[MicrovmTier] = &[
122 MicrovmTier {
123 baseline_memory_mib: 512,
124 peak_memory_mib: 2048,
125 peak_vcpu: 1,
126 max_disk_mib: 8192,
127 },
128 MicrovmTier {
129 baseline_memory_mib: 1024,
130 peak_memory_mib: 4096,
131 peak_vcpu: 2,
132 max_disk_mib: 8192,
133 },
134 MicrovmTier {
135 baseline_memory_mib: 2048,
136 peak_memory_mib: 8192,
137 peak_vcpu: 4,
138 max_disk_mib: 8192,
139 },
140 MicrovmTier {
141 baseline_memory_mib: 4096,
142 peak_memory_mib: 16384,
143 peak_vcpu: 8,
144 max_disk_mib: 16384,
145 },
146 MicrovmTier {
147 baseline_memory_mib: 8192,
148 peak_memory_mib: 32768,
149 peak_vcpu: 16,
150 max_disk_mib: 32768,
151 },
152];
153
154pub use super::sandbox_policy::{is_public_ipv4, non_public_ipv4_ranges, EgressPolicy};
155
156#[derive(Debug, Clone, PartialEq, Eq)]
158pub enum SandboxEgress {
159 None,
160 Internet,
161 Allow,
163 AllowDomains {
165 domains: Vec<String>,
166 },
167}
168
169#[derive(Debug, Clone, Serialize, Deserialize)]
171#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
172#[serde(tag = "mode", rename_all = "camelCase", deny_unknown_fields)]
173pub enum LegacySandboxEgress {
174 Deny,
176 Allow,
179 AllowDomains { domains: Vec<String> },
182}
183
184#[derive(Serialize, Deserialize)]
185#[serde(rename_all = "camelCase")]
186enum SandboxEgressMode {
187 None,
188 Internet,
189}
190
191#[derive(Serialize, Deserialize)]
192#[serde(untagged)]
193enum SandboxEgressInput {
194 Mode(SandboxEgressMode),
195 Legacy(LegacySandboxEgress),
196}
197
198impl Serialize for SandboxEgress {
199 fn serialize<S: serde::Serializer>(
200 &self,
201 serializer: S,
202 ) -> std::result::Result<S::Ok, S::Error> {
203 match self {
204 Self::None => serializer.serialize_str("none"),
205 Self::Internet => serializer.serialize_str("internet"),
206 Self::Allow => LegacySandboxEgress::Allow.serialize(serializer),
207 Self::AllowDomains { domains } => LegacySandboxEgress::AllowDomains {
208 domains: domains.clone(),
209 }
210 .serialize(serializer),
211 }
212 }
213}
214
215impl<'de> Deserialize<'de> for SandboxEgress {
216 fn deserialize<D: serde::Deserializer<'de>>(
217 deserializer: D,
218 ) -> std::result::Result<Self, D::Error> {
219 Ok(match SandboxEgressInput::deserialize(deserializer)? {
220 SandboxEgressInput::Mode(SandboxEgressMode::None)
221 | SandboxEgressInput::Legacy(LegacySandboxEgress::Deny) => Self::None,
222 SandboxEgressInput::Mode(SandboxEgressMode::Internet) => Self::Internet,
223 SandboxEgressInput::Legacy(LegacySandboxEgress::Allow) => Self::Allow,
224 SandboxEgressInput::Legacy(LegacySandboxEgress::AllowDomains { domains }) => {
225 Self::AllowDomains { domains }
226 }
227 })
228 }
229}
230
231#[cfg(feature = "openapi")]
232impl utoipa::PartialSchema for SandboxEgress {
233 fn schema() -> utoipa::openapi::RefOr<utoipa::openapi::schema::Schema> {
234 use utoipa::openapi::schema::{ObjectBuilder, OneOfBuilder, Type};
235 OneOfBuilder::new()
236 .item(
237 ObjectBuilder::new()
238 .schema_type(Type::String)
239 .enum_values(Some(["none", "internet"])),
240 )
241 .item(LegacySandboxEgress::schema())
242 .into()
243 }
244}
245#[cfg(feature = "openapi")]
246impl utoipa::ToSchema for SandboxEgress {}
247
248impl SandboxEgress {
249 #[allow(non_upper_case_globals)]
251 #[deprecated(note = "use SandboxEgress::None")]
252 pub const Deny: Self = Self::None;
253
254 pub fn internet_access_switch(&self) -> Option<bool> {
256 match self {
257 Self::None => Some(false),
258 Self::Internet | Self::Allow => Some(true),
259 Self::AllowDomains { .. } => None,
260 }
261 }
262}
263
264pub const GCP_NO_EGRESS_ALLOWLIST: &str = "Google Cloud sandboxes have no outbound allowlist: \
270`internet` is open outbound through Google's shared addresses (no fixed egress IP) and takes no \
271per-sandbox policy; declare `none` to block all outbound traffic";
272
273pub const SANDBOX_EXPIRY_LABEL: &str = "alienExpiresAtMs";
275
276pub const SANDBOX_REQUEST_KEY_LABEL: &str = "alienRequestKey";
278
279pub const SANDBOX_REQUEST_KEY_MAX_LEN: usize = 64;
281
282pub fn is_valid_request_key(value: &str) -> bool {
285 !value.is_empty()
286 && value.len() <= SANDBOX_REQUEST_KEY_MAX_LEN
287 && value
288 .bytes()
289 .all(|b| b.is_ascii_alphanumeric() || b == b'_' || b == b'-')
290}
291
292pub fn is_valid_sandbox_expiry(value: &str) -> bool {
294 value.parse::<u64>().is_ok_and(|ms| ms > 0)
295}
296
297pub const AZURE_GATEWAY_MAX_LIFETIME_SECONDS: u32 = 24 * 60 * 60;
299
300#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
305#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
306#[serde(rename_all = "camelCase", deny_unknown_fields)]
307pub struct SandboxLifecyclePolicy {
308 #[serde(default, skip_serializing_if = "Option::is_none")]
315 pub max_lifetime_seconds: Option<u32>,
316 #[serde(alias = "idleSuspendSeconds", skip_serializing_if = "Option::is_none")]
320 pub idle_pause_seconds: Option<u32>,
321 #[serde(default, skip_serializing_if = "Option::is_none")]
326 pub on_pause: Option<Vec<String>>,
327 #[serde(default, skip_serializing_if = "Option::is_none")]
330 pub on_resume: Option<Vec<String>>,
331}
332
333pub const GCP_PREVIEW_IS_COMMAND_ACCESS: &str = "On Google Cloud, preview access equals command access; port-scoped preview sharing is not available.";
337
338#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
344#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
345#[serde(rename_all = "camelCase", deny_unknown_fields)]
346pub struct SandboxCapabilities {
347 pub files: bool,
349 pub reconnect: bool,
351 pub jobs: bool,
354 pub interactive_commands: bool,
357 pub preview: bool,
359 pub pause_resume: bool,
361 pub snapshot: bool,
363 pub domain_egress_rules: bool,
365 pub egress_deny: bool,
368 pub enforced_limits: bool,
370 pub process_limit: bool,
372 pub sandbox_lifetime: bool,
374 pub supervisor_pid_namespace: bool,
380 pub supervisor_isolation: bool,
387}
388
389impl SandboxCapabilities {
390 pub fn for_platform(platform: Platform) -> Result<Self> {
396 match platform {
397 Platform::Aws => Ok(Self {
398 files: true,
399 reconnect: true,
400 jobs: true,
401 interactive_commands: true,
404 preview: true,
405 pause_resume: true,
406 snapshot: false,
407 domain_egress_rules: false,
408 egress_deny: true,
411 enforced_limits: true,
412 process_limit: false,
414 sandbox_lifetime: true,
417 supervisor_pid_namespace: false,
422 supervisor_isolation: true,
425 }),
426 Platform::Azure => Ok(Self::azure()),
427 Platform::Gcp => Ok(Self::gcp_agent_platform()),
428 Platform::Kubernetes => Ok(Self {
429 files: true,
430 reconnect: true,
431 jobs: true,
432 interactive_commands: true,
437 preview: true,
443 pause_resume: false,
446 snapshot: false,
448 domain_egress_rules: false,
449 egress_deny: true,
450 enforced_limits: true,
451 process_limit: false,
456 sandbox_lifetime: true,
462 supervisor_pid_namespace: false,
466 supervisor_isolation: true,
472 }),
473 Platform::Local => Ok(Self {
474 files: true,
475 reconnect: true,
476 jobs: false,
478 interactive_commands: true,
481 preview: true,
482 pause_resume: false,
483 snapshot: false,
484 domain_egress_rules: false,
485 egress_deny: true,
486 enforced_limits: true,
487 process_limit: true,
489 sandbox_lifetime: false,
490 supervisor_pid_namespace: false,
493 supervisor_isolation: true,
497 }),
498 Platform::Machines | Platform::Test => {
499 Err(AlienError::new(ErrorData::SandboxPlatformUnsupported {
500 platform: platform.to_string(),
501 }))
502 }
503 }
504 }
505
506 pub fn azure() -> Self {
508 Self {
509 files: true,
510 reconnect: true,
511 jobs: true,
514 interactive_commands: true,
518 preview: true,
525 pause_resume: true,
526 snapshot: false,
530 domain_egress_rules: true,
531 egress_deny: true,
532 enforced_limits: true,
536 process_limit: false,
537 sandbox_lifetime: true,
542 supervisor_pid_namespace: false,
544 supervisor_isolation: false,
547 }
548 }
549
550 pub fn gcp_agent_platform() -> Self {
552 Self {
553 files: true,
555 reconnect: true,
559 jobs: true,
560 interactive_commands: false,
563 preview: true,
569 pause_resume: true,
575 snapshot: false,
578 domain_egress_rules: false,
580 egress_deny: true,
583 enforced_limits: true,
587 process_limit: false,
589 sandbox_lifetime: true,
591 supervisor_pid_namespace: false,
593 supervisor_isolation: false,
596 }
597 }
598
599 pub fn require(&self, capability: SandboxCapability, platform: Platform) -> Result<()> {
601 let available = match capability {
602 SandboxCapability::Files => self.files,
603 SandboxCapability::Reconnect => self.reconnect,
604 SandboxCapability::Jobs => self.jobs,
605 SandboxCapability::InteractiveCommands => self.interactive_commands,
606 SandboxCapability::Preview => self.preview,
607 SandboxCapability::PauseResume => self.pause_resume,
608 SandboxCapability::Snapshot => self.snapshot,
609 SandboxCapability::DomainEgressRules => self.domain_egress_rules,
610 SandboxCapability::EgressDeny => self.egress_deny,
611 SandboxCapability::EnforcedLimits => self.enforced_limits,
612 SandboxCapability::ProcessLimit => self.process_limit,
613 SandboxCapability::SandboxLifetime => self.sandbox_lifetime,
614 SandboxCapability::SupervisorPidNamespace => self.supervisor_pid_namespace,
615 SandboxCapability::SupervisorIsolation => self.supervisor_isolation,
616 };
617
618 if available {
619 return Ok(());
620 }
621
622 Err(AlienError::new(ErrorData::SandboxCapabilityUnsupported {
623 capability: capability.as_str().to_string(),
624 platform: platform.to_string(),
625 }))
626 }
627}
628
629#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
631#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
632#[serde(rename_all = "camelCase")]
633pub enum SandboxCapability {
634 Files,
636 Reconnect,
638 Jobs,
640 InteractiveCommands,
642 Preview,
644 PauseResume,
646 Snapshot,
648 DomainEgressRules,
650 EgressDeny,
652 EnforcedLimits,
654 ProcessLimit,
656 SandboxLifetime,
658 SupervisorPidNamespace,
660 SupervisorIsolation,
662}
663
664impl SandboxCapability {
665 pub fn as_str(&self) -> &'static str {
667 match self {
668 Self::Files => "files",
669 Self::Reconnect => "reconnect",
670 Self::Jobs => "jobs",
671 Self::InteractiveCommands => "interactiveCommands",
672 Self::Preview => "preview",
673 Self::PauseResume => "pauseResume",
674 Self::Snapshot => "snapshot",
675 Self::DomainEgressRules => "domainEgressRules",
676 Self::EgressDeny => "egressDeny",
677 Self::EnforcedLimits => "enforcedLimits",
678 Self::ProcessLimit => "processLimit",
679 Self::SandboxLifetime => "sandboxLifetime",
680 Self::SupervisorPidNamespace => "supervisorPidNamespace",
681 Self::SupervisorIsolation => "supervisorIsolation",
682 }
683 }
684}
685
686#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
688#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
689#[serde(rename_all = "camelCase", deny_unknown_fields)]
690pub struct SandboxPrivilegedSupervisor {
691 pub command_uid: u32,
693}
694
695#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Builder)]
697#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
698#[serde(rename_all = "camelCase", deny_unknown_fields)]
699#[builder(start_fn = new)]
700pub struct Sandbox {
701 #[builder(start_fn)]
704 pub id: String,
705 #[builder(field)]
708 #[serde(default, skip_serializing_if = "Vec::is_empty")]
709 #[cfg_attr(feature = "openapi", schema(ignore))]
710 pub links: Vec<ResourceRef>,
711 pub code: SandboxCode,
713 #[builder(skip)]
716 #[serde(default, skip_serializing_if = "Option::is_none")]
717 #[cfg_attr(feature = "openapi", schema(ignore))]
718 pub image_user: Option<u32>,
719 #[serde(skip_serializing_if = "Option::is_none")]
723 pub private_base_image: Option<String>,
724 #[serde(skip_serializing_if = "Option::is_none")]
730 pub limits: Option<SandboxLimits>,
731 pub egress: SandboxEgress,
733 #[serde(default, skip_serializing_if = "Option::is_none")]
735 pub default_policy: Option<EgressPolicy>,
736 #[builder(skip)]
740 #[serde(default, skip_serializing_if = "Option::is_none")]
741 pub privileged_supervisor: Option<SandboxPrivilegedSupervisor>,
742 #[serde(default, skip_serializing_if = "Option::is_none")]
746 pub image_permissions: Option<SandboxImagePermissions>,
747 #[serde(alias = "session")]
752 pub lifecycle: SandboxLifecyclePolicy,
753 #[builder(default)]
757 #[serde(default, skip_serializing_if = "Vec::is_empty")]
758 pub preview_ports: Vec<u16>,
759}
760
761pub fn restricts_network_mode(stack: &crate::Stack, targets_kubernetes: bool) -> bool {
766 !targets_kubernetes && stack_needs_named_subnets_at_setup(stack)
767}
768
769pub fn stack_needs_named_subnets_at_setup(stack: &crate::Stack) -> bool {
775 stack.resources().any(|(_, entry)| {
776 entry
777 .config
778 .downcast_ref::<Sandbox>()
779 .is_some_and(|sandbox| crate::sandbox_egress::sandbox_needs_connector(stack, sandbox))
780 })
781}
782
783impl Sandbox {
784 pub(crate) fn setup_digest_value(&self) -> serde_json::Value {
785 match &self.egress {
786 SandboxEgress::None => serde_json::json!({"mode":"deny"}),
787 value => serde_json::to_value(value).expect("egress serializes"),
788 }
789 }
790
791 pub const RESOURCE_TYPE: ResourceType = ResourceType::from_static("sandbox");
793
794 pub fn id(&self) -> &str {
796 &self.id
797 }
798
799 pub fn cloud_egress(&self) -> &SandboxEgress {
802 if self.privileged_supervisor.is_some() && self.egress != SandboxEgress::Internet {
803 &SandboxEgress::Allow
804 } else {
805 &self.egress
806 }
807 }
808
809 pub fn supervisor_environment(&self) -> std::collections::BTreeMap<String, String> {
811 let mut env = std::collections::BTreeMap::new();
812 if let Some(supervisor) = &self.privileged_supervisor {
813 env.insert(
814 "ALIEN_SANDBOX_EXPECTED_EXEC_UID".to_string(),
815 supervisor.command_uid.to_string(),
816 );
817 env.insert(
818 "ALIEN_SANDBOX_EGRESS".to_string(),
819 if self.egress == SandboxEgress::None {
821 r#"{"mode":"deny"}"#.to_string()
822 } else {
823 serde_json::to_string(&self.egress).expect("egress serializes")
824 },
825 );
826 }
827 env
828 }
829
830 pub fn resolved_limits(&self) -> SandboxLimits {
836 self.limits.clone().unwrap_or_else(default_limits)
837 }
838
839 pub fn validate_for_platform(&self, platform: Platform) -> Result<()> {
844 if let Some(policy) = &self.default_policy {
845 if self.egress != SandboxEgress::Internet {
846 return Err(AlienError::new(ErrorData::SandboxEgressInvalid {
847 target: "defaultPolicy".into(),
848 reason: "defaultPolicy requires the new internet declaration".into(),
849 }));
850 }
851 policy.validate()?;
852 if platform == Platform::Gcp {
853 return Err(AlienError::new(ErrorData::SandboxEgressInvalid {
854 target: "defaultPolicy".into(),
855 reason: GCP_NO_EGRESS_ALLOWLIST.into(),
856 }));
857 }
858 }
859 if self.image_user == Some(0) && platform == Platform::Local {
860 return Err(AlienError::new(ErrorData::SandboxCapabilityUnsupported {
861 capability: "root image USER: this backend does not yet separate bounded root boot from non-root exec; use a non-root image USER".into(),
862 platform: platform.to_string(),
863 }));
864 }
865 if self.image_user == Some(0)
869 && platform == Platform::Kubernetes
870 && !matches!(self.egress, SandboxEgress::Internet | SandboxEgress::None)
871 {
872 return Err(AlienError::new(ErrorData::SandboxCapabilityUnsupported {
873 capability: "root image USER with this egress mode: a root image on Kubernetes needs egress `internet` or `none`, because `allow` and `allowDomains` have no enforcement outside the pod".into(),
874 platform: platform.to_string(),
875 }));
876 }
877 let mut capabilities = SandboxCapabilities::for_platform(platform)?;
878 self.validate_image_permissions(platform)?;
879 if let Some(supervisor) = &self.privileged_supervisor {
880 if platform != Platform::Aws {
881 return Err(AlienError::new(ErrorData::SandboxCapabilityUnsupported {
882 capability: "privilegedSupervisor".to_string(),
883 platform: platform.to_string(),
884 }));
885 }
886 if supervisor.command_uid == 0 || supervisor.command_uid == u32::MAX {
887 return Err(AlienError::new(ErrorData::SandboxLimitInvalid {
888 resource_id: self.id.clone(),
889 field: "privilegedSupervisor.commandUid".to_string(),
890 value: supervisor.command_uid.to_string(),
891 reason: "must be a non-root Linux uid other than the invalid uid sentinel"
892 .to_string(),
893 }));
894 }
895 if let SandboxEgress::AllowDomains { domains } = &self.egress {
896 for domain in domains {
897 let hostname = domain.strip_suffix('.').unwrap_or(domain);
898 if hostname.len() > 253
899 || !hostname.split('.').all(|label| {
900 !label.is_empty()
901 && label.len() <= 63
902 && label
903 .bytes()
904 .all(|c| c.is_ascii_alphanumeric() || c == b'-')
905 && !label.starts_with('-')
906 && !label.ends_with('-')
907 })
908 {
909 return Err(AlienError::new(ErrorData::SandboxLimitInvalid {
910 resource_id: self.id.clone(), field: "egress.domains".to_string(), value: domain.clone(),
911 reason: "privileged supervisor allowlists require exact DNS hostnames; wildcards are unsupported".to_string(),
912 }));
913 }
914 }
915 }
916 capabilities.domain_egress_rules = true;
917 }
918
919 if matches!(&self.code, SandboxCode::Source { .. })
924 && !matches!(
925 platform,
926 Platform::Aws | Platform::Azure | Platform::Gcp | Platform::Kubernetes
927 )
928 {
929 return Err(AlienError::new(ErrorData::SandboxLimitInvalid {
930 resource_id: self.id.clone(),
931 field: "code".to_string(),
932 value: "source".to_string(),
933 reason: format!(
934 "no sandbox backend builds an image from source on {platform}; give \
935 code.image a prebuilt reference"
936 ),
937 }));
938 }
939
940 if self.private_base_image.is_some() && platform != Platform::Aws {
943 return Err(AlienError::new(ErrorData::SandboxCapabilityUnsupported {
944 capability: "privateBaseImage".to_string(),
945 platform: platform.to_string(),
946 }));
947 }
948
949 if platform == Platform::Azure && matches!(&self.code, SandboxCode::Image { .. }) {
952 self.azure_image()?;
953 }
954
955 if let Some(seconds) = self.lifecycle.max_lifetime_seconds {
958 capabilities.require(SandboxCapability::SandboxLifetime, platform)?;
960
961 if seconds == 0 {
962 return Err(AlienError::new(ErrorData::SandboxLimitInvalid {
963 resource_id: self.id.clone(),
964 field: "maxLifetimeSeconds".to_string(),
965 value: "0".to_string(),
966 reason: "a sandbox must be allowed to run for at least 1 second".to_string(),
967 }));
968 }
969
970 let ceiling = match platform {
975 Platform::Aws => Some((AWS_MAX_LIFETIME_SECONDS, "AWS runs a MicroVM for")),
976 Platform::Kubernetes => {
977 Some((KUBERNETES_MAX_LIFETIME_SECONDS, "Kubernetes runs a pod for"))
978 }
979 Platform::Gcp => None,
982 Platform::Azure | Platform::Local | Platform::Machines | Platform::Test => None,
985 };
986 if let Some((max, runs_for)) = ceiling {
987 if seconds > max {
988 return Err(AlienError::new(ErrorData::SandboxLimitInvalid {
989 resource_id: self.id.clone(),
990 field: "maxLifetimeSeconds".to_string(),
991 value: seconds.to_string(),
992 reason: format!("{runs_for} between 1 and {max} seconds"),
993 }));
994 }
995 }
996 }
997
998 let Some(limits) = self.limits.as_ref() else {
999 return self.validate_capabilities(&capabilities, platform);
1001 };
1002
1003 validate_quantity(&self.id, "cpu", &limits.cpu)?;
1004 validate_quantity(&self.id, "memory", &limits.memory)?;
1005 validate_quantity(&self.id, "disk", &limits.disk)?;
1006
1007 if let Some(max_processes) = limits.max_processes {
1008 if max_processes == 0 {
1009 return Err(AlienError::new(ErrorData::SandboxLimitInvalid {
1010 resource_id: self.id.clone(),
1011 field: "maxProcesses".to_string(),
1012 value: "0".to_string(),
1013 reason: "a sandbox that may run no processes cannot run code".to_string(),
1014 }));
1015 }
1016 capabilities.require(SandboxCapability::ProcessLimit, platform)?;
1017 }
1018
1019 capabilities.require(SandboxCapability::EnforcedLimits, platform)?;
1022
1023 if platform == Platform::Azure {
1024 self.azure_sandbox_limits()?;
1025 }
1026
1027 if platform == Platform::Gcp {
1028 self.gcp_sandbox_limits()?;
1029 }
1030
1031 if platform == Platform::Aws {
1032 self.microvm_tier()?;
1035 }
1036
1037 self.validate_capabilities(&capabilities, platform)
1038 }
1039
1040 pub fn declares_image_permissions(&self) -> bool {
1043 self.image_permissions.is_some()
1044 || self.lifecycle.on_pause.is_some()
1045 || self.lifecycle.on_resume.is_some()
1046 }
1047
1048 fn validate_image_permissions(&self, platform: Platform) -> Result<()> {
1052 if let Some(permissions) = &self.image_permissions {
1053 sandbox_image_permissions::require_image_permissions_platform(
1054 "imagePermissions",
1055 platform,
1056 )?;
1057 permissions.validate(&self.id)?;
1058 }
1059 for (field, argv) in [
1060 ("onPause", &self.lifecycle.on_pause),
1061 ("onResume", &self.lifecycle.on_resume),
1062 ] {
1063 if let Some(argv) = argv {
1064 sandbox_image_permissions::require_image_permissions_platform(field, platform)?;
1065 sandbox_image_permissions::validate_lifecycle_argv(
1066 &self.id,
1067 field,
1068 argv,
1069 self.image_permissions
1070 .as_ref()
1071 .map(|permissions| &permissions.mounts[..])
1072 .unwrap_or_default(),
1073 )?;
1074 }
1075 }
1076 if self.declares_image_permissions() && self.privileged_supervisor.is_some() {
1077 return Err(AlienError::new(ErrorData::SandboxLimitInvalid {
1078 resource_id: self.id.clone(),
1079 field: "imagePermissions".to_string(),
1080 value: "privilegedSupervisor".to_string(),
1081 reason: "image permissions and lifecycle steps need the root image boot, not the \
1082 released privileged supervisor"
1083 .to_string(),
1084 }));
1085 }
1086 if self.declares_image_permissions()
1089 && !matches!(self.egress, SandboxEgress::Internet | SandboxEgress::None)
1090 {
1091 return Err(AlienError::new(ErrorData::SandboxLimitInvalid {
1092 resource_id: self.id.clone(),
1093 field: "egress".to_string(),
1094 value: match self.egress {
1095 SandboxEgress::Allow => "allow",
1096 _ => "allowDomains",
1097 }
1098 .to_string(),
1099 reason: "image permissions and lifecycle steps need egress `internet` or `none`"
1100 .to_string(),
1101 }));
1102 }
1103 if self.declares_image_permissions() && self.image_user.is_some_and(|uid| uid != 0) {
1104 return Err(AlienError::new(ErrorData::SandboxLimitInvalid {
1105 resource_id: self.id.clone(),
1106 field: "imagePermissions".to_string(),
1107 value: "image USER".to_string(),
1108 reason: "image permissions and lifecycle steps need an image whose command \
1109 starts as root (USER root or no USER)"
1110 .to_string(),
1111 }));
1112 }
1113 Ok(())
1114 }
1115
1116 pub fn azure_image(&self) -> Result<AzureSandboxImage<'_>> {
1120 let SandboxCode::Image { image, .. } = &self.code else {
1121 return Err(AlienError::new(ErrorData::SandboxLimitInvalid {
1122 resource_id: self.id.clone(),
1123 field: "code".to_string(),
1124 value: "source".to_string(),
1125 reason: "the sandbox still has unbuilt source code. Run 'alien build' first"
1126 .to_string(),
1127 }));
1128 };
1129
1130 classify_azure_sandbox_image(image).ok_or_else(|| {
1131 let image = image.trim();
1132 AlienError::new(ErrorData::SandboxLimitInvalid {
1133 resource_id: self.id.clone(),
1134 field: "code.image".to_string(),
1135 value: image.to_string(),
1136 reason: if image.is_empty() {
1137 "a sandbox has to name an image".to_string()
1138 } else {
1139 "Azure creates a sandbox from a catalog name such as 'ubuntu' or from a \
1140 registry image such as 'docker.io/library/python:3.14-slim'"
1141 .to_string()
1142 },
1143 })
1144 })
1145 }
1146
1147 pub fn gcp_sandbox_limits(&self) -> Result<()> {
1150 let Some(limits) = self.limits.as_ref() else {
1151 return Ok(());
1152 };
1153 let over_cap =
1154 quantity_exceeds_bytes(&limits.disk, GCP_MAX_DISK_BYTES).ok_or_else(|| {
1155 AlienError::new(ErrorData::SandboxLimitInvalid {
1156 resource_id: self.id.clone(),
1157 field: "disk".to_string(),
1158 value: limits.disk.clone(),
1159 reason: "expected a size such as 8Gi".to_string(),
1160 })
1161 })?;
1162 if over_cap {
1163 return Err(AlienError::new(ErrorData::SandboxLimitInvalid {
1164 resource_id: self.id.clone(),
1165 field: "disk".to_string(),
1166 value: limits.disk.clone(),
1167 reason: "GCP Agent Platform caps a sandbox's ephemeral storage at 10Gi; declare \
1168 10Gi or less"
1169 .to_string(),
1170 }));
1171 }
1172 Ok(())
1173 }
1174
1175 pub fn azure_sandbox_limits(&self) -> Result<()> {
1179 let Some(limits) = self.limits.as_ref() else {
1180 return Ok(());
1183 };
1184
1185 let refused = |field: &str, value: &str, reason: &str| {
1186 AlienError::new(ErrorData::SandboxLimitInvalid {
1187 resource_id: self.id.clone(),
1188 field: field.to_string(),
1189 value: value.to_string(),
1190 reason: reason.to_string(),
1191 })
1192 };
1193
1194 let cpu_millicores = millicores(&limits.cpu)
1195 .ok_or_else(|| refused("cpu", &limits.cpu, "expected cores or millicores"))?;
1196
1197 if cpu_millicores % AZURE_CPU_STEP_MILLICORES != 0
1201 || !(AZURE_CPU_STEP_MILLICORES..=AZURE_MAX_CPU_MILLICORES).contains(&cpu_millicores)
1202 {
1203 return Err(refused(
1204 "cpu",
1205 &limits.cpu,
1206 "Azure allocates cpu in steps of 250m from 250m to 16000m",
1207 ));
1208 }
1209
1210 let memory_ceiling_mib = cpu_millicores * AZURE_MEMORY_MIB_PER_CORE / 1000;
1212 let disk_ceiling_mib = cpu_millicores * AZURE_DISK_MIB_PER_CORE / 1000;
1213
1214 let memory_mib = quantity_mib(&limits.memory)
1215 .ok_or_else(|| refused("memory", &limits.memory, "Azure sizes memory in whole MiB"))?;
1216 if memory_mib > memory_ceiling_mib {
1217 return Err(refused(
1218 "memory",
1219 &limits.memory,
1220 &format!(
1221 "Azure allows at most 2Gi of memory per core, or {memory_ceiling_mib}Mi \
1222 at the declared cpu"
1223 ),
1224 ));
1225 }
1226
1227 let disk_mib = quantity_mib(&limits.disk)
1228 .ok_or_else(|| refused("disk", &limits.disk, "Azure sizes disk in whole MiB"))?;
1229 if disk_mib > disk_ceiling_mib {
1230 return Err(refused(
1231 "disk",
1232 &limits.disk,
1233 &format!(
1234 "Azure allows at most 20Gi of disk per core, or {disk_ceiling_mib}Mi at \
1235 the declared cpu"
1236 ),
1237 ));
1238 }
1239
1240 Ok(())
1241 }
1242
1243 pub fn microvm_tier(&self) -> Result<MicrovmTier> {
1250 let Some(limits) = self.limits.as_ref() else {
1251 return Ok(MICROVM_TIERS[2]);
1255 };
1256
1257 let memory_mib = quantity_mib(&limits.memory).ok_or_else(|| {
1258 AlienError::new(ErrorData::SandboxLimitInvalid {
1259 resource_id: self.id.clone(),
1260 field: "memory".to_string(),
1261 value: limits.memory.clone(),
1262 reason: "AWS sizes a MicroVM in whole MiB".to_string(),
1263 })
1264 })?;
1265 let disk_mib = quantity_mib(&limits.disk).ok_or_else(|| {
1266 AlienError::new(ErrorData::SandboxLimitInvalid {
1267 resource_id: self.id.clone(),
1268 field: "disk".to_string(),
1269 value: limits.disk.clone(),
1270 reason: "AWS sizes a MicroVM's disk in whole MiB".to_string(),
1271 })
1272 })?;
1273 let cpu_millicores = millicores(&limits.cpu).ok_or_else(|| {
1274 AlienError::new(ErrorData::SandboxLimitInvalid {
1275 resource_id: self.id.clone(),
1276 field: "cpu".to_string(),
1277 value: limits.cpu.clone(),
1278 reason: "expected cores or millicores".to_string(),
1279 })
1280 })?;
1281
1282 let sized = |tier: &&MicrovmTier| {
1287 tier.peak_memory_mib <= memory_mib && tier.max_disk_mib <= disk_mib
1288 };
1289
1290 let tier = MICROVM_TIERS
1291 .iter()
1292 .rev()
1293 .find(sized)
1294 .copied()
1295 .ok_or_else(|| {
1296 AlienError::new(ErrorData::SandboxLimitInvalid {
1297 resource_id: self.id.clone(),
1298 field: "memory".to_string(),
1299 value: limits.memory.clone(),
1300 reason: format!(
1301 "a Lambda MicroVM bursts to four times its baseline, so the smallest \
1302 ceiling AWS can hold is 2Gi memory with 8Gi disk; '{}' memory and '{}' \
1303 disk fit no size",
1304 limits.memory, limits.disk
1305 ),
1306 })
1307 })?;
1308
1309 let required_millicores = i64::from(tier.peak_vcpu) * 1000;
1310 if cpu_millicores < required_millicores {
1311 return Err(AlienError::new(ErrorData::SandboxLimitInvalid {
1312 resource_id: self.id.clone(),
1313 field: "cpu".to_string(),
1314 value: limits.cpu.clone(),
1315 reason: format!(
1316 "AWS allocates one vCPU per 2GB, so a MicroVM sized to a '{}' memory ceiling \
1317 reaches {} vCPU; declare cpu '{}' or lower the memory ceiling",
1318 limits.memory, tier.peak_vcpu, tier.peak_vcpu
1319 ),
1320 }));
1321 }
1322
1323 Ok(tier)
1324 }
1325
1326 fn validate_capabilities(
1328 &self,
1329 capabilities: &SandboxCapabilities,
1330 platform: Platform,
1331 ) -> Result<()> {
1332 if matches!(self.egress, SandboxEgress::AllowDomains { .. }) {
1333 capabilities.require(SandboxCapability::DomainEgressRules, platform)?;
1334 }
1335
1336 if let SandboxEgress::AllowDomains { domains } = &self.egress {
1342 if domains.is_empty() {
1343 return Err(AlienError::new(ErrorData::SandboxLimitInvalid {
1344 resource_id: self.id.clone(),
1345 field: "egress.domains".to_string(),
1346 value: "[]".to_string(),
1347 reason: "an allowlist naming no domain denies everything; declare \
1348 egress: deny if that is what was meant"
1349 .to_string(),
1350 }));
1351 }
1352 }
1353
1354 if matches!(self.egress, SandboxEgress::None) {
1355 capabilities.require(SandboxCapability::EgressDeny, platform)?;
1356 }
1357
1358 if platform == Platform::Gcp
1361 && self
1362 .preview_ports
1363 .contains(&crate::sandbox_image::GCP_AGENT_PLATFORM.port)
1364 {
1365 return Err(AlienError::new(ErrorData::SandboxLimitInvalid {
1366 resource_id: self.id.clone(),
1367 field: "previewPorts".to_string(),
1368 value: crate::sandbox_image::GCP_AGENT_PLATFORM.port.to_string(),
1369 reason: "that port is the Alien agent's own on GCP Agent Platform; choose \
1370 another port for the workload"
1371 .to_string(),
1372 }));
1373 }
1374
1375 if !self.preview_ports.is_empty() {
1376 capabilities.require(SandboxCapability::Preview, platform)?;
1377 if platform == Platform::Azure
1378 && matches!(self.azure_image(), Ok(AzureSandboxImage::Catalog(_)))
1379 {
1380 return Err(AlienError::new(ErrorData::SandboxCapabilityUnsupported {
1381 capability:
1382 "preview (a catalog image runs without the Alien agent that issues \
1383 the capability; build the sandbox from source)"
1384 .to_string(),
1385 platform: platform.to_string(),
1386 }));
1387 }
1388 }
1389
1390 if self.lifecycle.idle_pause_seconds.is_some() {
1391 if platform == Platform::Gcp {
1394 return Err(AlienError::new(ErrorData::SandboxCapabilityUnsupported {
1395 capability: "idle pause policy: the GCP Agent Platform backend has no idle policy and Alien does not watch for idleness there; remove the idle policy and pause the sandbox explicitly".to_string(),
1396 platform: platform.to_string(),
1397 }));
1398 }
1399 capabilities.require(SandboxCapability::PauseResume, platform)?;
1400 }
1401
1402 if self.lifecycle.max_lifetime_seconds.is_some() {
1403 capabilities.require(SandboxCapability::SandboxLifetime, platform)?;
1404 }
1405
1406 Ok(())
1407 }
1408}
1409
1410fn default_limits() -> SandboxLimits {
1415 SandboxLimits {
1416 cpu: "1".to_string(),
1417 memory: "2Gi".to_string(),
1418 disk: "8Gi".to_string(),
1419 max_processes: None,
1420 }
1421}
1422
1423fn validate_quantity(resource_id: &str, field: &str, value: &str) -> Result<()> {
1425 let invalid = |reason: &str| {
1426 AlienError::new(ErrorData::SandboxLimitInvalid {
1427 resource_id: resource_id.to_string(),
1428 field: field.to_string(),
1429 value: value.to_string(),
1430 reason: reason.to_string(),
1431 })
1432 };
1433
1434 let digits_end = value
1435 .find(|c: char| !c.is_ascii_digit() && c != '.')
1436 .unwrap_or(value.len());
1437 let (number, suffix) = value.split_at(digits_end);
1438
1439 let parsed: f64 = number
1440 .parse()
1441 .map_err(|_| invalid("expected a number, optionally followed by a unit suffix"))?;
1442
1443 if parsed <= 0.0 {
1444 return Err(invalid("must be greater than zero"));
1445 }
1446
1447 const SUFFIXES: &[&str] = &["", "m", "k", "M", "G", "T", "Ki", "Mi", "Gi", "Ti"];
1448 if !SUFFIXES.contains(&suffix) {
1449 return Err(invalid(
1450 "unit must be one of m, k, M, G, T, Ki, Mi, Gi, Ti, or absent",
1451 ));
1452 }
1453
1454 Ok(())
1455}
1456
1457fn split_quantity(value: &str) -> Option<(f64, &str)> {
1459 let trimmed = value.trim();
1460 let digits_end = trimmed
1461 .find(|c: char| !c.is_ascii_digit() && c != '.')
1462 .unwrap_or(trimmed.len());
1463 let (number, suffix) = trimmed.split_at(digits_end);
1464 number.parse().ok().map(|number| (number, suffix))
1465}
1466
1467pub fn quantity_mib(value: &str) -> Option<i64> {
1473 let (number, suffix) = split_quantity(value)?;
1474 let bytes = match suffix {
1475 "" => number,
1476 "k" => number * 1e3,
1477 "M" => number * 1e6,
1478 "G" => number * 1e9,
1479 "T" => number * 1e12,
1480 "Ki" => number * 1024.0,
1481 "Mi" => number * 1024.0 * 1024.0,
1482 "Gi" => number * 1024.0 * 1024.0 * 1024.0,
1483 "Ti" => number * 1024.0 * 1024.0 * 1024.0 * 1024.0,
1484 _ => return None,
1486 };
1487 Some((bytes / (1024.0 * 1024.0)) as i64)
1488}
1489
1490fn quantity_exceeds_bytes(value: &str, cap_bytes: u128) -> Option<bool> {
1493 let trimmed = value.trim();
1494 let digits_end = trimmed
1495 .find(|c: char| !c.is_ascii_digit() && c != '.')
1496 .unwrap_or(trimmed.len());
1497 let (number, suffix) = trimmed.split_at(digits_end);
1498 let unit: u128 = match suffix {
1499 "" => 1,
1500 "k" => 1_000,
1501 "M" => 1_000_000,
1502 "G" => 1_000_000_000,
1503 "T" => 1_000_000_000_000,
1504 "Ki" => 1 << 10,
1505 "Mi" => 1 << 20,
1506 "Gi" => 1 << 30,
1507 "Ti" => 1 << 40,
1508 _ => return None,
1509 };
1510 let (whole, fraction) = number.split_once('.').unwrap_or((number, ""));
1511 if (whole.is_empty() && fraction.is_empty()) || fraction.contains('.') {
1512 return None;
1513 }
1514 let digits = format!("{whole}{fraction}");
1515 let scale = 10u128.checked_pow(u32::try_from(fraction.len()).ok()?)?;
1516 let mantissa: u128 = digits.parse().ok()?;
1517 Some(mantissa.checked_mul(unit)? > cap_bytes.checked_mul(scale)?)
1519}
1520
1521pub fn millicores(value: &str) -> Option<i64> {
1523 let (number, suffix) = split_quantity(value)?;
1524 match suffix {
1525 "" => Some((number * 1000.0) as i64),
1526 "m" => Some(number as i64),
1527 _ => None,
1528 }
1529}
1530
1531#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1533#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
1534#[serde(rename_all = "camelCase")]
1535pub struct SandboxOutputs {
1536 pub parent_name: String,
1538 #[serde(skip_serializing_if = "Option::is_none")]
1540 pub identifier: Option<String>,
1541 #[serde(skip_serializing_if = "Option::is_none")]
1543 pub endpoint: Option<String>,
1544}
1545
1546impl ResourceOutputsDefinition for SandboxOutputs {
1547 fn get_resource_type(&self) -> ResourceType {
1548 Sandbox::RESOURCE_TYPE
1549 }
1550
1551 fn as_any(&self) -> &dyn Any {
1552 self
1553 }
1554
1555 fn box_clone(&self) -> Box<dyn ResourceOutputsDefinition> {
1556 Box::new(self.clone())
1557 }
1558
1559 fn outputs_eq(&self, other: &dyn ResourceOutputsDefinition) -> bool {
1560 other.as_any().downcast_ref::<SandboxOutputs>() == Some(self)
1561 }
1562
1563 fn to_json_value(&self) -> serde_json::Result<serde_json::Value> {
1564 serde_json::to_value(self)
1565 }
1566}
1567
1568impl ResourceDefinition for Sandbox {
1569 fn get_resource_type(&self) -> ResourceType {
1570 Self::RESOURCE_TYPE
1571 }
1572
1573 fn id(&self) -> &str {
1574 &self.id
1575 }
1576
1577 fn replace_after_failed_create_is_safe(&self) -> bool {
1578 false
1581 }
1582
1583 fn get_dependencies(&self) -> Vec<ResourceRef> {
1586 self.image_permissions
1587 .iter()
1588 .flat_map(|permissions| &permissions.connections)
1589 .map(|connection| connection.to.clone())
1590 .collect()
1591 }
1592
1593 fn validate_update(&self, new_config: &dyn ResourceDefinition) -> Result<()> {
1594 let new_sandbox = new_config
1595 .as_any()
1596 .downcast_ref::<Sandbox>()
1597 .ok_or_else(|| {
1598 AlienError::new(ErrorData::UnexpectedResourceType {
1599 resource_id: self.id.clone(),
1600 expected: Self::RESOURCE_TYPE,
1601 actual: new_config.get_resource_type(),
1602 })
1603 })?;
1604
1605 if self.id != new_sandbox.id {
1606 return Err(AlienError::new(ErrorData::InvalidResourceUpdate {
1607 resource_id: self.id.clone(),
1608 reason: "the 'id' field is immutable".to_string(),
1609 }));
1610 }
1611
1612 Ok(())
1613 }
1614
1615 fn as_any(&self) -> &dyn Any {
1616 self
1617 }
1618
1619 fn as_any_mut(&mut self) -> &mut dyn Any {
1620 self
1621 }
1622
1623 fn box_clone(&self) -> Box<dyn ResourceDefinition> {
1624 Box::new(self.clone())
1625 }
1626
1627 fn resource_eq(&self, other: &dyn ResourceDefinition) -> bool {
1628 other.as_any().downcast_ref::<Sandbox>() == Some(self)
1629 }
1630
1631 fn to_json_value(&self) -> serde_json::Result<serde_json::Value> {
1632 serde_json::to_value(self)
1633 }
1634}
1635
1636#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1638pub enum AzureSandboxImage<'a> {
1639 Catalog(&'a str),
1641 Registry(&'a str),
1644}
1645
1646impl<'a> AzureSandboxImage<'a> {
1647 pub fn as_str(&self) -> &'a str {
1649 match self {
1650 Self::Catalog(value) | Self::Registry(value) => value,
1651 }
1652 }
1653}
1654
1655pub const AZURE_DISK_IMAGE_LABEL: &str = "alienImage";
1657
1658pub fn classify_azure_sandbox_image(image: &str) -> Option<AzureSandboxImage<'_>> {
1662 let image = image.trim();
1663 if image.is_empty() {
1664 return None;
1665 }
1666 if image
1667 .chars()
1668 .all(|c| c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '-'))
1669 {
1670 return Some(AzureSandboxImage::Catalog(image));
1671 }
1672 (image.contains(|c| matches!(c, '/' | ':' | '@')) && OCI_REFERENCE.is_match(image))
1673 .then_some(AzureSandboxImage::Registry(image))
1674}
1675
1676pub fn azure_disk_image_label(reference: &str) -> String {
1679 let digest = format!("{:x}", Sha256::digest(reference.trim().as_bytes()));
1680 digest[..32].to_string()
1681}
1682
1683static OCI_REFERENCE: std::sync::LazyLock<regex::Regex> = std::sync::LazyLock::new(|| {
1685 let domain_component = r"(?:[a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])";
1686 let domain = format!(r"{domain_component}(?:\.{domain_component})*(?::[0-9]+)?");
1687 let path_component = r"[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*";
1688 let name = format!(r"(?:{domain}/)?{path_component}(?:/{path_component})*");
1689 let tag = r"[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}";
1690 let digest = r"[A-Za-z][A-Za-z0-9]*(?:[-_+.][A-Za-z][A-Za-z0-9]*)*:[0-9a-fA-F]{32,}";
1691 regex::Regex::new(&format!(r"^{name}(?::{tag})?(?:@{digest})?$"))
1692 .expect("the OCI reference grammar compiles")
1693});
1694
1695pub const BUNDLE_REGION_TOKEN: &str = "{region}";
1700
1701#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1703pub enum BundleUri<'a> {
1704 Literal(&'a str),
1706 Regional { before: &'a str, after: &'a str },
1709}
1710
1711pub fn stable_bundle_key_prefix(key: &str) -> Option<&str> {
1715 let (above_file, _) = key.rsplit_once('/')?;
1716 let (above_version, _) = above_file.rsplit_once('/')?;
1717 Some(above_version)
1718}
1719
1720pub fn parse_bundle_uri(uri: &str) -> std::result::Result<BundleUri<'_>, String> {
1726 let path = uri
1727 .strip_prefix("s3://")
1728 .ok_or_else(|| format!("'{uri}' is not an s3:// URI"))?;
1729 let (bucket, key) = path
1730 .split_once('/')
1731 .ok_or_else(|| format!("'{uri}' names a bucket with no object key"))?;
1732
1733 if path.contains('*') || path.contains('?') {
1737 return Err(format!(
1738 "'{uri}' carries an IAM wildcard; the bundle's path is interpolated into the build \
1739 role's grant, so '*' and '?' would widen it past the bundle"
1740 ));
1741 }
1742
1743 if key.contains('{') || key.contains('}') {
1744 return Err(format!(
1745 "'{uri}' places a token in the object key; {BUNDLE_REGION_TOKEN} is accepted in the \
1746 bucket name alone"
1747 ));
1748 }
1749
1750 let Some((before, after)) = bucket.split_once(BUNDLE_REGION_TOKEN) else {
1751 if bucket.contains('{') || bucket.contains('}') {
1752 return Err(format!(
1753 "'{uri}' carries a token this build does not know; {BUNDLE_REGION_TOKEN} is the \
1754 only one"
1755 ));
1756 }
1757 return Ok(BundleUri::Literal(uri));
1758 };
1759
1760 if after.contains(BUNDLE_REGION_TOKEN) {
1761 return Err(format!("'{uri}' repeats {BUNDLE_REGION_TOKEN}"));
1762 }
1763 if before.contains('{') || before.contains('}') || after.contains('{') || after.contains('}') {
1764 return Err(format!(
1765 "'{uri}' carries a token this build does not know; {BUNDLE_REGION_TOKEN} is the only one"
1766 ));
1767 }
1768
1769 Ok(BundleUri::Regional {
1770 before: &uri[.."s3://".len() + before.len()],
1771 after: &uri["s3://".len() + before.len() + BUNDLE_REGION_TOKEN.len()..],
1772 })
1773}
1774
1775#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1777pub enum EcrImageRegion<'a> {
1778 Literal(&'a str),
1780 Deployment,
1782}
1783
1784#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1786pub struct EcrImageRepository<'a> {
1787 pub account_id: &'a str,
1788 pub region: EcrImageRegion<'a>,
1789 pub repository: &'a str,
1791}
1792
1793impl EcrImageRepository<'_> {
1794 pub fn arn(&self, partition: &str, region: &str) -> String {
1797 let region = match self.region {
1798 EcrImageRegion::Literal(region) => region,
1799 EcrImageRegion::Deployment => region,
1800 };
1801 format!(
1802 "arn:{partition}:ecr:{region}:{}:repository/{}",
1803 self.account_id, self.repository
1804 )
1805 }
1806}
1807
1808pub fn parse_ecr_image_repository(
1814 image: &str,
1815) -> std::result::Result<EcrImageRepository<'_>, String> {
1816 let refuse = |reason: &str| format!("privateBaseImage '{image}' {reason}");
1817 let (host, path) = image
1818 .split_once('/')
1819 .ok_or_else(|| refuse("names no repository"))?;
1820 let (account_id, rest) = host.split_once(".dkr.ecr.").ok_or_else(|| {
1821 refuse("is not served by a private ECR registry (<account>.dkr.ecr.<region>.amazonaws.com)")
1822 })?;
1823 let region = rest
1825 .strip_suffix(".amazonaws.com.cn")
1826 .or_else(|| rest.strip_suffix(".amazonaws.com"))
1827 .ok_or_else(|| refuse("is not served by a private ECR registry (<account>.dkr.ecr.<region>.amazonaws.com)"))?;
1828 if account_id.len() != 12 || !account_id.bytes().all(|b| b.is_ascii_digit()) {
1829 return Err(refuse("names no 12-digit account in its registry host"));
1830 }
1831 let region = if region == BUNDLE_REGION_TOKEN {
1832 EcrImageRegion::Deployment
1833 } else if !region.is_empty()
1834 && region
1835 .bytes()
1836 .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-')
1837 {
1838 EcrImageRegion::Literal(region)
1839 } else {
1840 return Err(refuse(&format!(
1841 "names no region in its registry host; give one or {BUNDLE_REGION_TOKEN}"
1842 )));
1843 };
1844
1845 let repository = match path.split_once('@') {
1846 Some((repository, _digest)) => repository,
1847 None => match path.rsplit_once('/') {
1848 Some((parent, last)) => match last.split_once(':') {
1849 Some((name, _tag)) => &path[..parent.len() + 1 + name.len()],
1850 None => path,
1851 },
1852 None => path.split_once(':').map_or(path, |(name, _tag)| name),
1853 },
1854 };
1855 let valid_segment = |segment: &str| {
1856 !segment.is_empty()
1857 && segment.bytes().all(|b| {
1858 b.is_ascii_lowercase() || b.is_ascii_digit() || matches!(b, b'.' | b'_' | b'-')
1859 })
1860 };
1861 if !repository.split('/').all(valid_segment) {
1862 return Err(refuse(
1863 "names a repository outside ECR's grammar (lowercase letters, digits, '.', '_', '-', and '/' between them)",
1864 ));
1865 }
1866 Ok(EcrImageRepository {
1867 account_id,
1868 region,
1869 repository,
1870 })
1871}
1872
1873#[cfg(test)]
1874mod tests {
1875 use super::*;
1876
1877 #[test]
1878 fn private_database_setup_accepts_the_default_network() {
1879 for lifecycle in [
1880 crate::ResourceLifecycle::Frozen,
1881 crate::ResourceLifecycle::Live,
1882 ] {
1883 let stack = crate::Stack::new("database".to_string())
1884 .add(
1885 crate::Postgres::new("metadata".to_string()).build(),
1886 lifecycle,
1887 )
1888 .build();
1889 assert!(!restricts_network_mode(&stack, false));
1890 assert!(!restricts_network_mode(&stack, true));
1891 }
1892 assert!(!restricts_network_mode(
1893 &crate::Stack::new("empty".to_string()).build(),
1894 false,
1895 ));
1896 }
1897
1898 fn repository_key(image: &str) -> String {
1901 match parse_ecr_image_repository(image) {
1902 Ok(parsed) => {
1903 let host = image.split_once('/').map_or(image, |(host, _)| host);
1904 format!("{host}/{}", parsed.repository)
1905 }
1906 Err(_) => image.to_string(),
1907 }
1908 }
1909
1910 #[test]
1911 fn a_private_base_image_names_one_repository() {
1912 let vectors: serde_json::Value = serde_json::from_str(include_str!(
1913 "../../tests/fixtures/ecr-image-repository-parity.json"
1914 ))
1915 .expect("the ECR repository vectors must be JSON");
1916 let field = |case: &serde_json::Value, name: &str| {
1917 case[name]
1918 .as_str()
1919 .unwrap_or_else(|| panic!("vector must carry {name}: {case}"))
1920 .to_string()
1921 };
1922
1923 for case in vectors["accepted"].as_array().expect("accepted vectors") {
1924 let image = field(case, "image");
1925 let region = field(case, "region");
1926 let region = if region == BUNDLE_REGION_TOKEN {
1927 EcrImageRegion::Deployment
1928 } else {
1929 EcrImageRegion::Literal(®ion)
1930 };
1931 assert_eq!(
1932 parse_ecr_image_repository(&image),
1933 Ok(EcrImageRepository {
1934 account_id: &field(case, "accountId"),
1935 region,
1936 repository: &field(case, "repository"),
1937 }),
1938 "{image}"
1939 );
1940 assert_eq!(
1941 repository_key(&image),
1942 field(case, "repositoryKey"),
1943 "{image}"
1944 );
1945 }
1946
1947 for case in vectors["refused"].as_array().expect("refused vectors") {
1948 let image = field(case, "image");
1949 assert!(
1950 parse_ecr_image_repository(&image).is_err(),
1951 "{image} must be refused"
1952 );
1953 assert_eq!(
1954 repository_key(&image),
1955 field(case, "repositoryKey"),
1956 "{image}"
1957 );
1958 }
1959 }
1960
1961 #[test]
1962 fn a_repository_arn_takes_the_deployment_region_only_where_the_host_leaves_it() {
1963 let regional =
1964 parse_ecr_image_repository("123456789012.dkr.ecr.{region}.amazonaws.com/team/base:1")
1965 .expect("parses");
1966 let pinned =
1967 parse_ecr_image_repository("123456789012.dkr.ecr.eu-west-1.amazonaws.com/team/base:1")
1968 .expect("parses");
1969 assert_eq!(
1970 regional.arn("aws-us-gov", "us-gov-west-1"),
1971 "arn:aws-us-gov:ecr:us-gov-west-1:123456789012:repository/team/base"
1972 );
1973 assert_eq!(
1974 pinned.arn("aws", "us-east-1"),
1975 "arn:aws:ecr:eu-west-1:123456789012:repository/team/base"
1976 );
1977 }
1978
1979 #[test]
1982 fn a_uri_carrying_an_iam_wildcard_is_refused() {
1983 for uri in [
1984 "s3://acme/team-*/v1/bundle.zip",
1985 "s3://acme/sandbox-bundle/f00d/bundle?.zip",
1986 "s3://acme-*/sandbox-bundle/f00d/bundle.zip",
1987 ] {
1988 let error = parse_bundle_uri(uri).expect_err("a wildcard must be refused");
1989 assert!(error.contains("IAM wildcard"), "for {uri}: {error}");
1990 }
1991
1992 parse_bundle_uri("s3://acme/sandbox-bundle/f00d/bundle.zip")
1993 .expect("an ordinary key still parses");
1994 }
1995
1996 #[test]
2000 fn a_grantable_prefix_ends_above_the_segment_that_moves() {
2001 assert_eq!(
2002 stable_bundle_key_prefix("sandbox-bundle/f00dcafe/bundle.zip"),
2003 Some("sandbox-bundle")
2004 );
2005 assert_eq!(
2006 stable_bundle_key_prefix("artifacts/team-a/sandbox/f00dcafe/bundle.zip"),
2007 Some("artifacts/team-a/sandbox"),
2008 "a deeper key narrows the prefix, it never widens to the first segment"
2009 );
2010
2011 assert_eq!(stable_bundle_key_prefix("agents/bundle.zip"), None);
2014 assert_eq!(stable_bundle_key_prefix("bundle.zip"), None);
2015 }
2016
2017 fn sandbox_with(egress: SandboxEgress, preview_ports: Vec<u16>) -> Sandbox {
2018 Sandbox::new("agent-sbx".to_string())
2019 .code(SandboxCode::Image {
2020 image: "ubuntu".to_string(),
2021 bundled_from: None,
2022 })
2023 .limits(SandboxLimits {
2024 cpu: "1".to_string(),
2025 memory: "2Gi".to_string(),
2026 disk: "10Gi".to_string(),
2027 max_processes: None,
2028 })
2029 .egress(egress)
2030 .lifecycle(SandboxLifecyclePolicy {
2031 max_lifetime_seconds: None,
2032 idle_pause_seconds: None,
2033 ..Default::default()
2034 })
2035 .preview_ports(preview_ports)
2036 .build()
2037 }
2038
2039 #[test]
2042 fn gcp_takes_internet_as_open_outbound_and_refuses_an_allowlist_policy() {
2043 sandbox_with(SandboxEgress::Internet, vec![])
2044 .validate_for_platform(Platform::Gcp)
2045 .unwrap();
2046 sandbox_with(SandboxEgress::None, vec![])
2047 .validate_for_platform(Platform::Gcp)
2048 .unwrap();
2049 for policy in [
2050 EgressPolicy::Allow {
2051 allow: vec!["api.example.com".into()],
2052 },
2053 EgressPolicy::Internet,
2054 ] {
2055 let mut declared = sandbox_with(SandboxEgress::Internet, vec![]);
2056 declared.default_policy = Some(policy);
2057 let refused = declared.validate_for_platform(Platform::Gcp).unwrap_err();
2058 assert!(
2059 refused
2060 .to_string()
2061 .contains("Google Cloud sandboxes have no outbound allowlist"),
2062 "{refused}"
2063 );
2064 }
2065 }
2066
2067 #[test]
2070 fn gcp_refuses_an_idle_pause_policy_at_plan_time_and_still_takes_a_lifetime() {
2071 let with_policy = |lifecycle: SandboxLifecyclePolicy| {
2072 Sandbox::new("sbx".to_string())
2073 .code(SandboxCode::Image {
2074 image: "ubuntu".to_string(),
2075 bundled_from: None,
2076 })
2077 .egress(SandboxEgress::None)
2078 .lifecycle(lifecycle)
2079 .build()
2080 .validate_for_platform(Platform::Gcp)
2081 };
2082 let refused = with_policy(SandboxLifecyclePolicy {
2083 max_lifetime_seconds: None,
2084 idle_pause_seconds: Some(900),
2085 ..Default::default()
2086 })
2087 .expect_err("no idle policy exists on GCP");
2088 assert_eq!(refused.code, "SANDBOX_CAPABILITY_UNSUPPORTED");
2089 assert!(refused.message.contains("idle"), "{}", refused.message);
2090 with_policy(SandboxLifecyclePolicy {
2091 max_lifetime_seconds: Some(3600),
2092 idle_pause_seconds: None,
2093 ..Default::default()
2094 })
2095 .expect("a lifetime is a TTL on GCP");
2096 }
2097
2098 #[test]
2099 fn gcp_accepts_preview_ports_but_not_the_agents_own() {
2100 sandbox_with(SandboxEgress::Deny, vec![8080, 8081, 8090])
2101 .validate_for_platform(Platform::Gcp)
2102 .expect("preview ports are served on GCP, as owner access");
2103 let error = sandbox_with(SandboxEgress::Deny, vec![8080, 8971])
2104 .validate_for_platform(Platform::Gcp)
2105 .expect_err("the agent's own port is not a workload port");
2106 assert_eq!(error.code, "SANDBOX_LIMIT_INVALID", "{error}");
2107 assert!(error.to_string().contains("8971"), "{error}");
2108 sandbox_with(SandboxEgress::Deny, vec![])
2109 .validate_for_platform(Platform::Gcp)
2110 .expect("a sandbox without preview ports is unaffected");
2111 }
2112
2113 #[test]
2114 fn a_uri_without_a_token_is_carried_whole() {
2115 assert_eq!(
2116 parse_bundle_uri("s3://acme-artifacts-us-east-2/agents/bundle.zip"),
2117 Ok(BundleUri::Literal(
2118 "s3://acme-artifacts-us-east-2/agents/bundle.zip"
2119 ))
2120 );
2121 }
2122
2123 #[test]
2126 fn a_regional_uri_splits_either_side_of_the_token() {
2127 let BundleUri::Regional { before, after } =
2128 parse_bundle_uri("s3://acme-artifacts-{region}/agents/bundle.zip")
2129 .expect("the token is accepted in the bucket")
2130 else {
2131 panic!("a bucket-position token must split");
2132 };
2133
2134 assert_eq!(before, "s3://acme-artifacts-");
2135 assert_eq!(after, "/agents/bundle.zip");
2136 assert_eq!(
2137 format!("{before}us-east-2{after}"),
2138 "s3://acme-artifacts-us-east-2/agents/bundle.zip",
2139 "the halves must rejoin to the URI the vendor meant"
2140 );
2141 }
2142
2143 #[test]
2146 fn a_token_this_build_cannot_resolve_is_refused() {
2147 for uri in [
2148 "s3://acme-artifacts-{regio}/bundle.zip",
2149 "s3://acme-artifacts/{region}/bundle.zip",
2150 "s3://acme-artifacts-{region}-{region}/bundle.zip",
2151 "s3://acme-artifacts/bundle-{version}.zip",
2152 "s3://acme}-artifacts-{region}/bundle.zip",
2153 "s3://acme{-artifacts-{region}/bundle.zip",
2154 ] {
2155 assert!(
2156 parse_bundle_uri(uri).is_err(),
2157 "'{uri}' must be refused before it can reach an image build"
2158 );
2159 }
2160 }
2161
2162 #[test]
2163 fn resource_type_is_stable() {
2164 assert_eq!(Sandbox::RESOURCE_TYPE.as_ref(), "sandbox");
2165 }
2166
2167 #[test]
2168 fn capability_sets_are_per_platform() {
2169 let gcp = SandboxCapabilities::for_platform(Platform::Gcp).expect("gcp is supported");
2170 assert!(
2171 gcp.reconnect,
2172 "generation from the container boot id makes a sandbox reachable across processes"
2173 );
2174 assert!(gcp.preview, "preview is offered as owner access");
2175 assert!(gcp.enforced_limits);
2176
2177 let azure = SandboxCapabilities::for_platform(Platform::Azure).expect("azure is supported");
2178 assert!(azure.files, "every backend moves files");
2179 assert!(gcp.files);
2180 assert!(azure.domain_egress_rules);
2183 assert!(azure.egress_deny);
2184 assert!(azure.enforced_limits);
2187 assert!(azure.pause_resume);
2188 assert!(!azure.snapshot);
2190 assert!(
2191 azure.preview,
2192 "the in-sandbox agent issues a port-scoped capability"
2193 );
2194
2195 let aws = SandboxCapabilities::for_platform(Platform::Aws).expect("aws is supported");
2196 assert!(!aws.snapshot, "AWS has no user-callable sandbox snapshot");
2197 assert!(aws.pause_resume);
2198
2199 let k8s =
2200 SandboxCapabilities::for_platform(Platform::Kubernetes).expect("k8s is supported");
2201 assert!(
2202 k8s.preview,
2203 "an in-cluster caller previews through the agent route"
2204 );
2205 }
2206
2207 #[test]
2216 fn supervisor_isolation_is_per_platform() {
2217 let value = |platform| {
2218 SandboxCapabilities::for_platform(platform)
2219 .expect("supported")
2220 .supervisor_isolation
2221 };
2222
2223 assert!(
2224 value(Platform::Aws),
2225 "root agent setuids the command to 60000"
2226 );
2227 assert!(
2228 value(Platform::Local),
2229 "the supervisor is on the host, outside the container"
2230 );
2231 assert!(
2232 value(Platform::Kubernetes),
2233 "root boot splits the command off the supervisor"
2234 );
2235 assert!(!value(Platform::Azure), "no Alien process runs the command");
2236 assert!(
2237 !value(Platform::Gcp),
2238 "no separate supervisor identity runs the command"
2239 );
2240 }
2241
2242 #[test]
2246 fn supervisor_isolation_separates_aws_from_a_subprocess_backend() {
2247 let aws = SandboxCapabilities::for_platform(Platform::Aws).expect("aws is supported");
2248 let gcp = SandboxCapabilities::for_platform(Platform::Gcp).expect("gcp is supported");
2249
2250 assert_eq!(
2251 aws.supervisor_pid_namespace, gcp.supervisor_pid_namespace,
2252 "the older axis cannot tell them apart"
2253 );
2254 assert!(
2255 aws.supervisor_isolation,
2256 "AWS setuids the command off the supervisor"
2257 );
2258 assert!(
2259 !gcp.supervisor_isolation,
2260 "the command runs under no separate supervisor identity"
2261 );
2262 }
2263
2264 #[test]
2269 fn gcp_agent_platform_row_matches_measured_backend() {
2270 let row = SandboxCapabilities::gcp_agent_platform();
2271
2272 assert!(row.files, "agent file ops move over the sandbox envelope");
2273 assert!(
2274 row.reconnect,
2275 "generation is derived from the container boot id, so a sandbox is reachable across \
2276 processes"
2277 );
2278 assert!(
2279 row.preview,
2280 "preview is owner access: the edge credential is the caller's execute right"
2281 );
2282 assert!(
2283 row.pause_resume,
2284 "pause and resume keep memory, and a resume that finds a new container is an error"
2285 );
2286 assert!(
2287 !row.snapshot,
2288 "the create path never sends a snapshot, so none is reachable through the trait"
2289 );
2290 assert!(
2291 !row.domain_egress_rules,
2292 "VPC and DNS peering is not a hostname allowlist"
2293 );
2294 assert!(
2295 row.egress_deny,
2296 "a declared deny blocks TCP, the metadata server and DNS on the default placement"
2297 );
2298 assert!(
2299 row.enforced_limits,
2300 "ceilings are enforced, by terminating the sandbox on breach"
2301 );
2302 assert!(!row.process_limit, "no process-count ceiling is observed");
2303 assert!(row.sandbox_lifetime, "ttl maps to a sandbox expireTime");
2304 assert!(!row.supervisor_pid_namespace, "no PID-namespace isolation");
2305 assert!(
2306 !row.supervisor_isolation,
2307 "the command is not run under a separate supervisor identity"
2308 );
2309
2310 let live = SandboxCapabilities::for_platform(Platform::Gcp).expect("gcp is supported");
2312 assert_eq!(
2313 live, row,
2314 "the Platform::Gcp arm is the Agent Platform capability row"
2315 );
2316 }
2317
2318 #[test]
2319 fn platforms_without_a_backend_are_an_error_not_an_empty_set() {
2320 let error = SandboxCapabilities::for_platform(Platform::Machines)
2321 .expect_err("Machines has no sandbox backend");
2322 assert_eq!(error.code, "SANDBOX_PLATFORM_UNSUPPORTED");
2323 }
2324
2325 #[test]
2326 fn unsupported_capability_names_platform_and_capability() {
2327 let capabilities = SandboxCapabilities::for_platform(Platform::Gcp).expect("supported");
2328 let error = capabilities
2329 .require(SandboxCapability::Snapshot, Platform::Gcp)
2330 .expect_err("GCP has no snapshot");
2331
2332 assert_eq!(error.code, "SANDBOX_CAPABILITY_UNSUPPORTED");
2333 let rendered = error.to_string();
2334 assert!(
2335 rendered.contains("snapshot"),
2336 "names the capability: {rendered}"
2337 );
2338 assert!(rendered.contains("gcp"), "names the platform: {rendered}");
2339 }
2340
2341 #[test]
2345 fn a_hostname_allowlist_is_refused_everywhere_it_would_be_approximated() {
2346 let sandbox = sandbox_with(
2347 SandboxEgress::AllowDomains {
2348 domains: vec!["example.com".to_string()],
2349 },
2350 vec![],
2351 );
2352
2353 for platform in [
2354 Platform::Aws,
2355 Platform::Gcp,
2356 Platform::Kubernetes,
2357 Platform::Local,
2358 ] {
2359 let error = sandbox
2360 .validate_for_platform(platform)
2361 .expect_err("only Azure expresses a hostname allowlist");
2362 assert_eq!(
2363 error.code, "SANDBOX_CAPABILITY_UNSUPPORTED",
2364 "on {platform:?}"
2365 );
2366 }
2367
2368 assert!(
2369 SandboxCapabilities::for_platform(Platform::Azure)
2370 .expect("supported")
2371 .domain_egress_rules,
2372 "Azure's egress policy matches on host pattern"
2373 );
2374 }
2375
2376 #[test]
2379 fn a_denied_egress_is_refused_where_it_would_not_be_enforced() {
2380 let sandbox = sandbox_with(SandboxEgress::None, vec![]);
2381
2382 assert!(
2385 SandboxCapabilities::for_platform(Platform::Gcp)
2386 .expect("supported")
2387 .egress_deny
2388 );
2389
2390 for platform in [Platform::Aws, Platform::Kubernetes, Platform::Local] {
2391 sandbox
2392 .validate_for_platform(platform)
2393 .expect("deny is enforced here");
2394 }
2395
2396 let egress_only = Sandbox::new("sbx".to_string())
2398 .code(SandboxCode::Image {
2399 image: "alpine".to_string(),
2400 bundled_from: None,
2401 })
2402 .egress(SandboxEgress::None)
2403 .lifecycle(SandboxLifecyclePolicy {
2404 max_lifetime_seconds: None,
2405 idle_pause_seconds: None,
2406 ..Default::default()
2407 })
2408 .build();
2409
2410 egress_only
2411 .validate_for_platform(Platform::Azure)
2412 .expect("Azure creates the sandbox under a Deny policy with full inspection");
2413 }
2414
2415 #[test]
2419 fn a_sandbox_declaring_no_ceilings_takes_the_platforms_own() {
2420 let undeclared = Sandbox::new("sbx".to_string())
2421 .code(SandboxCode::Image {
2422 image: "alpine".to_string(),
2423 bundled_from: None,
2424 })
2425 .egress(SandboxEgress::None)
2426 .lifecycle(SandboxLifecyclePolicy {
2427 max_lifetime_seconds: None,
2428 idle_pause_seconds: None,
2429 ..Default::default()
2430 })
2431 .build();
2432
2433 undeclared
2434 .validate_for_platform(Platform::Azure)
2435 .expect("a sandbox naming no ceilings takes the platform's own");
2436
2437 assert_eq!(undeclared.resolved_limits().cpu, "1");
2439 }
2440
2441 #[test]
2445 fn azure_sizes_follow_the_rule_the_data_plane_states() {
2446 let sized = |cpu: &str, memory: &str, disk: &str| {
2447 let mut sandbox = sandbox_with(SandboxEgress::None, vec![]);
2448 let limits = sandbox
2449 .limits
2450 .as_mut()
2451 .expect("the fixture declares limits");
2452 limits.cpu = cpu.to_string();
2453 limits.memory = memory.to_string();
2454 limits.disk = disk.to_string();
2455 sandbox.validate_for_platform(Platform::Azure)
2456 };
2457
2458 sized("250m", "512Mi", "5120Mi").expect("the smallest step the data plane accepts");
2459 sized("4000m", "8192Mi", "40960Mi").expect("cpu, memory and disk are all honoured");
2460 sized("16000m", "32Gi", "320Gi").expect("the top of the range");
2461
2462 let off_step = sized("333m", "512Mi", "5120Mi").expect_err("333m is not a step of 250m");
2464 assert_eq!(off_step.code, "SANDBOX_LIMIT_INVALID", "{off_step}");
2465 assert!(off_step.to_string().contains("cpu"), "{off_step}");
2466
2467 let too_big = sized("32000m", "64Gi", "640Gi").expect_err("32 cores is over the ceiling");
2468 assert_eq!(too_big.code, "SANDBOX_LIMIT_INVALID", "{too_big}");
2469
2470 sized("1000m", "2Gi", "20Gi").expect("2Gi is exactly one core's worth");
2473 let over_memory = sized("250m", "2Gi", "5120Mi").expect_err("2Gi needs a full core");
2474 assert_eq!(over_memory.code, "SANDBOX_LIMIT_INVALID", "{over_memory}");
2475 assert!(over_memory.to_string().contains("memory"), "{over_memory}");
2476
2477 let over_disk = sized("250m", "512Mi", "20Gi").expect_err("20Gi needs a full core");
2478 assert!(over_disk.to_string().contains("disk"), "{over_disk}");
2479 }
2480
2481 #[test]
2484 fn kubernetes_root_image_needs_gateway_or_no_egress() {
2485 let root = |egress| {
2486 let mut sandbox = sandbox_with(egress, vec![]);
2487 sandbox.image_user = Some(0);
2488 sandbox
2489 };
2490 for egress in [SandboxEgress::Internet, SandboxEgress::None] {
2491 root(egress)
2492 .validate_for_platform(Platform::Kubernetes)
2493 .expect("root boot is allowed with an external egress boundary");
2494 }
2495 for egress in [
2496 SandboxEgress::Allow,
2497 SandboxEgress::AllowDomains {
2498 domains: vec!["example.com".to_string()],
2499 },
2500 ] {
2501 let error = root(egress)
2502 .validate_for_platform(Platform::Kubernetes)
2503 .expect_err("a root image under unenforced egress is refused");
2504 assert_eq!(error.code, "SANDBOX_CAPABILITY_UNSUPPORTED");
2505 assert!(error.to_string().contains("root image USER"), "{error}");
2506 }
2507 root(SandboxEgress::Internet)
2508 .validate_for_platform(Platform::Local)
2509 .expect_err("Local still refuses a root image");
2510 }
2511
2512 #[test]
2513 fn preview_ports_require_the_preview_capability() {
2514 let sandbox = sandbox_with(SandboxEgress::None, vec![8080]);
2515
2516 sandbox
2517 .validate_for_platform(Platform::Aws)
2518 .expect("AWS mints a port-scoped JWE");
2519
2520 sandbox
2521 .validate_for_platform(Platform::Kubernetes)
2522 .expect("Kubernetes serves preview to in-cluster callers through the agent");
2523
2524 sandbox
2525 .validate_for_platform(Platform::Gcp)
2526 .expect("GCP serves preview to callers that already hold execute");
2527 }
2528
2529 #[test]
2531 fn azure_preview_needs_an_image_that_carries_the_agent() {
2532 let catalog = sandbox_with(SandboxEgress::None, vec![8080]);
2533 let error = catalog
2534 .validate_for_platform(Platform::Azure)
2535 .expect_err("a catalog image has no agent to issue a capability");
2536 assert_eq!(error.code, "SANDBOX_CAPABILITY_UNSUPPORTED");
2537
2538 let mut registry = sandbox_with(SandboxEgress::None, vec![8080]);
2539 registry.code = SandboxCode::Image {
2540 image: "registry.example.com/workload/sandbox:1".to_string(),
2541 bundled_from: None,
2542 };
2543 registry
2544 .validate_for_platform(Platform::Azure)
2545 .expect("a registry image is built with the agent");
2546 }
2547
2548 #[test]
2552 fn a_private_base_image_is_refused_off_aws() {
2553 let mut sandbox = sandbox_with(SandboxEgress::Allow, vec![]);
2554 sandbox.code = SandboxCode::Image {
2555 image: "s3://acme-artifacts/agents/bundle.zip".to_string(),
2556 bundled_from: None,
2557 };
2558 sandbox.private_base_image =
2559 Some("123456789012.dkr.ecr.{region}.amazonaws.com/acme:tag".to_string());
2560
2561 sandbox
2562 .validate_for_platform(Platform::Aws)
2563 .expect("AWS builds its image from a bundle, so a base image sits behind code.image");
2564
2565 for platform in [
2566 Platform::Gcp,
2567 Platform::Azure,
2568 Platform::Kubernetes,
2569 Platform::Local,
2570 ] {
2571 let error = sandbox
2572 .validate_for_platform(platform)
2573 .expect_err("a backend that builds no image must refuse a base image for one");
2574 assert_eq!(error.code, "SANDBOX_CAPABILITY_UNSUPPORTED");
2575 assert!(
2576 error.to_string().contains("privateBaseImage"),
2577 "the refusal must name the field the user declared: {error}"
2578 );
2579 }
2580 }
2581
2582 #[test]
2586 fn gcp_refuses_a_disk_above_its_cap_and_accepts_the_cap() {
2587 let with_disk = |disk: &str| {
2588 let mut sandbox = sandbox_with(SandboxEgress::Allow, vec![]);
2589 sandbox
2590 .limits
2591 .as_mut()
2592 .expect("the fixture declares limits")
2593 .disk = disk.to_string();
2594 sandbox
2595 };
2596
2597 let error = with_disk("20Gi")
2598 .validate_for_platform(Platform::Gcp)
2599 .expect_err("20Gi is above the Agent Platform cap");
2600 assert_eq!(error.code, "SANDBOX_LIMIT_INVALID");
2601 let rendered = error.to_string();
2602 assert!(rendered.contains("disk"), "names the field: {rendered}");
2603 assert!(rendered.contains("10Gi"), "names the cap: {rendered}");
2604
2605 with_disk("10Gi")
2606 .validate_for_platform(Platform::Gcp)
2607 .expect("the cap itself is allowed");
2608 with_disk("10240Mi")
2609 .validate_for_platform(Platform::Gcp)
2610 .expect("the cap in MiB is allowed");
2611 for over in ["10240.5Mi", "10241Mi", "10.0000001Gi"] {
2612 with_disk(over)
2613 .validate_for_platform(Platform::Gcp)
2614 .expect_err(&format!("{over} is above the cap and must not round down"));
2615 }
2616 with_disk("8Gi")
2617 .validate_for_platform(Platform::Gcp)
2618 .expect("the default disk is allowed");
2619 with_disk("20Gi")
2620 .validate_for_platform(Platform::Kubernetes)
2621 .expect("the cap is Agent Platform's, not every backend's");
2622 }
2623
2624 #[test]
2625 fn gcp_accepts_a_sandbox_declaring_enforced_limits() {
2626 let mut sandbox = sandbox_with(SandboxEgress::Allow, vec![]);
2627 sandbox
2628 .limits
2629 .as_mut()
2630 .expect("the fixture declares limits")
2631 .disk = "10Gi".to_string();
2632 sandbox
2633 .validate_for_platform(Platform::Gcp)
2634 .expect("Agent Platform enforces declared ceilings, by terminating on breach");
2635 }
2636
2637 #[test]
2638 fn invalid_quantities_are_rejected_with_the_offending_field() {
2639 let mut sandbox = sandbox_with(SandboxEgress::None, vec![]);
2640 sandbox
2641 .limits
2642 .as_mut()
2643 .expect("the fixture declares limits")
2644 .memory = "2Gb".to_string();
2645
2646 let error = sandbox
2647 .validate_for_platform(Platform::Aws)
2648 .expect_err("Gb is not a valid suffix");
2649 assert_eq!(error.code, "SANDBOX_LIMIT_INVALID");
2650 assert!(error.to_string().contains("memory"));
2651
2652 sandbox
2653 .limits
2654 .as_mut()
2655 .expect("the fixture declares limits")
2656 .memory = "2Gi".to_string();
2657 sandbox
2658 .limits
2659 .as_mut()
2660 .expect("the fixture declares limits")
2661 .cpu = "0".to_string();
2662 let error = sandbox
2663 .validate_for_platform(Platform::Aws)
2664 .expect_err("zero cpu is not a ceiling");
2665 assert_eq!(error.code, "SANDBOX_LIMIT_INVALID");
2666 }
2667
2668 #[test]
2669 fn zero_max_processes_is_rejected() {
2670 let mut sandbox = sandbox_with(SandboxEgress::None, vec![]);
2671 sandbox
2672 .limits
2673 .as_mut()
2674 .expect("the fixture declares limits")
2675 .max_processes = Some(0);
2676
2677 let error = sandbox
2678 .validate_for_platform(Platform::Local)
2679 .expect_err("a sandbox must be able to run at least one process");
2680 assert_eq!(error.code, "SANDBOX_LIMIT_INVALID");
2681 assert!(error.to_string().contains("maxProcesses"));
2682 }
2683
2684 #[test]
2688 fn a_process_ceiling_is_accepted_only_where_a_runtime_can_apply_it() {
2689 let mut sandbox = sandbox_with(SandboxEgress::None, vec![]);
2690 sandbox
2691 .limits
2692 .as_mut()
2693 .expect("the fixture declares limits")
2694 .max_processes = Some(256);
2695
2696 sandbox
2697 .validate_for_platform(Platform::Local)
2698 .expect("Docker takes a pids limit");
2699
2700 for platform in [Platform::Aws, Platform::Azure, Platform::Kubernetes] {
2701 let error = sandbox
2702 .validate_for_platform(platform)
2703 .expect_err("a process ceiling nothing applies must be refused");
2704 assert_eq!(error.code, "SANDBOX_CAPABILITY_UNSUPPORTED");
2705 }
2706 }
2707
2708 #[test]
2713 fn a_lifetime_aws_would_reject_is_refused_while_planning() {
2714 let with_limits = sandbox_with(SandboxEgress::None, vec![]);
2715 let mut without_limits = with_limits.clone();
2716 without_limits.limits = None;
2717
2718 for (declared, mut sandbox) in [("with", with_limits), ("without", without_limits)] {
2719 for seconds in [28_801, 30_000, 100_000] {
2720 sandbox.lifecycle.max_lifetime_seconds = Some(seconds);
2721 let error = sandbox
2722 .validate_for_platform(Platform::Aws)
2723 .expect_err("a lifetime above what AWS runs is refused");
2724 assert_eq!(
2725 error.code, "SANDBOX_LIMIT_INVALID",
2726 "{seconds}s {declared} limits"
2727 );
2728
2729 sandbox
2731 .validate_for_platform(Platform::Kubernetes)
2732 .expect("Kubernetes takes an activeDeadlineSeconds above 28,800");
2733 }
2734
2735 sandbox.lifecycle.max_lifetime_seconds = Some(28_800);
2736 sandbox
2737 .validate_for_platform(Platform::Aws)
2738 .expect("the ceiling itself is allowed");
2739 }
2740 }
2741
2742 #[test]
2746 fn a_zero_lifetime_is_refused_while_planning() {
2747 let with_limits = sandbox_with(SandboxEgress::None, vec![]);
2748 let mut without_limits = with_limits.clone();
2749 without_limits.limits = None;
2750
2751 for (declared, mut sandbox) in [("with", with_limits), ("without", without_limits)] {
2752 sandbox.lifecycle.max_lifetime_seconds = Some(0);
2753 for platform in [
2754 Platform::Aws,
2755 Platform::Kubernetes,
2756 Platform::Gcp,
2757 Platform::Azure,
2758 ] {
2759 let error = sandbox
2760 .validate_for_platform(platform)
2761 .expect_err("a zero lifetime is refused");
2762 assert_eq!(
2763 error.code, "SANDBOX_LIMIT_INVALID",
2764 "{platform} {declared} limits"
2765 );
2766 assert!(
2767 error.to_string().contains("maxLifetimeSeconds"),
2768 "{platform} {declared} limits"
2769 );
2770 }
2771
2772 for platform in [Platform::Local] {
2774 let error = sandbox
2775 .validate_for_platform(platform)
2776 .expect_err("a lifetime is refused where nothing applies it");
2777 assert_eq!(
2778 error.code, "SANDBOX_CAPABILITY_UNSUPPORTED",
2779 "{platform} {declared} limits"
2780 );
2781 }
2782
2783 sandbox.lifecycle.max_lifetime_seconds = Some(1);
2784 sandbox
2785 .validate_for_platform(Platform::Kubernetes)
2786 .expect("one second is the API server's floor");
2787 }
2788 }
2789
2790 #[test]
2794 fn a_lifetime_kubernetes_would_reject_is_refused_while_planning() {
2795 let with_limits = sandbox_with(SandboxEgress::None, vec![]);
2796 let mut without_limits = with_limits.clone();
2797 without_limits.limits = None;
2798
2799 for (declared, mut sandbox) in [("with", with_limits), ("without", without_limits)] {
2800 for seconds in [2_147_483_648, u32::MAX] {
2801 sandbox.lifecycle.max_lifetime_seconds = Some(seconds);
2802 let error = sandbox
2803 .validate_for_platform(Platform::Kubernetes)
2804 .expect_err("a lifetime above what the API server takes is refused");
2805 assert_eq!(
2806 error.code, "SANDBOX_LIMIT_INVALID",
2807 "{seconds}s {declared} limits"
2808 );
2809 assert!(
2810 error.to_string().contains("maxLifetimeSeconds"),
2811 "{seconds}s {declared} limits"
2812 );
2813 }
2814
2815 sandbox.lifecycle.max_lifetime_seconds = Some(2_147_483_647);
2816 sandbox
2817 .validate_for_platform(Platform::Kubernetes)
2818 .expect("the ceiling itself is allowed");
2819 }
2820 }
2821
2822 #[test]
2825 fn an_image_azure_cannot_pull_is_refused_while_planning() {
2826 let mut sandbox = sandbox_with(SandboxEgress::None, vec![]);
2827 sandbox.limits = None;
2830
2831 for image in ["ubuntu@sha256:abc", "", " ", "ubuntu latest", "ubuntu?x"] {
2833 sandbox.code = SandboxCode::Image {
2834 image: image.to_string(),
2835 bundled_from: None,
2836 };
2837 let error = sandbox
2838 .validate_for_platform(Platform::Azure)
2839 .expect_err("an image Azure has nowhere to put is refused");
2840 assert_eq!(error.code, "SANDBOX_LIMIT_INVALID", "image '{image}'");
2841 }
2842
2843 for image in ["ubuntu", "ubuntu-22.04", "debian_slim"] {
2844 sandbox.code = SandboxCode::Image {
2845 image: image.to_string(),
2846 bundled_from: None,
2847 };
2848 sandbox
2849 .validate_for_platform(Platform::Azure)
2850 .unwrap_or_else(|error| panic!("'{image}' is a catalog name: {error}"));
2851 }
2852
2853 for image in [
2854 "ubuntu:24.04",
2855 "ghcr.io/myorg/sandbox:latest",
2856 "docker.io/library/python:3.14-slim",
2857 "localhost:5000/team/agent@sha256:51dafde81dbdb6ebde285137a295cf18a47ca95234fe388a343719cb97305b3d",
2858 ] {
2859 sandbox.code = SandboxCode::Image {
2860 image: image.to_string(),
2861 bundled_from: None,
2862 };
2863 sandbox
2864 .validate_for_platform(Platform::Azure)
2865 .unwrap_or_else(|error| panic!("'{image}' is a registry image: {error}"));
2866 }
2867
2868 sandbox.code = SandboxCode::Image {
2870 image: " ubuntu ".to_string(),
2871 bundled_from: None,
2872 };
2873 assert_eq!(
2874 sandbox
2875 .azure_image()
2876 .expect("a padded name is still a name"),
2877 AzureSandboxImage::Catalog("ubuntu")
2878 );
2879 }
2880
2881 #[test]
2885 fn every_value_the_catalog_allowlist_accepted_is_still_a_catalog_name() {
2886 const ALPHABET: &[u8] =
2887 b"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._-";
2888
2889 let assert_catalog = |value: &str| {
2890 assert_eq!(
2891 classify_azure_sandbox_image(value),
2892 Some(AzureSandboxImage::Catalog(value.trim())),
2893 "'{value}'"
2894 );
2895 };
2896
2897 for a in ALPHABET {
2898 assert_catalog(&String::from_utf8(vec![*a]).unwrap());
2899 for b in ALPHABET {
2900 assert_catalog(&String::from_utf8(vec![*a, *b]).unwrap());
2901 for c in ALPHABET {
2902 assert_catalog(&String::from_utf8(vec![*a, *b, *c]).unwrap());
2903 }
2904 }
2905 }
2906
2907 let mut state: u64 = 0x9E37_79B9_7F4A_7C15;
2908 let mut next = || {
2909 state ^= state << 13;
2910 state ^= state >> 7;
2911 state ^= state << 17;
2912 state
2913 };
2914 for _ in 0..20_000 {
2915 let len = 4 + (next() % 60) as usize;
2916 let mut value: String = (0..len)
2917 .map(|_| ALPHABET[(next() % ALPHABET.len() as u64) as usize] as char)
2918 .collect();
2919 if next() % 4 == 0 {
2920 value = format!(" {value}\t");
2921 }
2922 assert_catalog(&value);
2923 }
2924 }
2925
2926 #[test]
2929 fn the_disk_image_label_is_stable_and_label_safe() {
2930 let label = azure_disk_image_label("docker.io/library/python:3.14-slim");
2931 assert_eq!(
2932 label,
2933 azure_disk_image_label(" docker.io/library/python:3.14-slim ")
2934 );
2935 assert_ne!(
2936 label,
2937 azure_disk_image_label("docker.io/library/python:3.13-slim")
2938 );
2939 assert_eq!(label.len(), 32);
2940 assert!(label.chars().all(|c| c.is_ascii_hexdigit()), "{label}");
2941 }
2942
2943 #[test]
2947 fn a_sandbox_deadline_is_accepted_only_where_the_platform_applies_it() {
2948 let mut sandbox = sandbox_with(SandboxEgress::None, vec![]);
2949 sandbox.lifecycle.max_lifetime_seconds = Some(3600);
2950
2951 sandbox
2952 .validate_for_platform(Platform::Kubernetes)
2953 .expect("the kubelet enforces activeDeadlineSeconds");
2954 sandbox
2955 .validate_for_platform(Platform::Aws)
2956 .expect("Lambda terminates the MicroVM at maximumDurationInSeconds");
2957
2958 sandbox.validate_for_platform(Platform::Azure).expect(
2959 "the binding stamps a deadline label and the controller's reaper deletes by it",
2960 );
2961
2962 for platform in [Platform::Local] {
2963 let error = sandbox
2964 .validate_for_platform(platform)
2965 .expect_err("a deadline nothing applies must be refused");
2966 assert_eq!(error.code, "SANDBOX_CAPABILITY_UNSUPPORTED");
2967 }
2968 }
2969
2970 #[test]
2974 fn an_aws_size_is_chosen_so_its_peak_stays_inside_the_declared_ceiling() {
2975 let sandbox = sandbox_with(SandboxEgress::None, vec![]);
2976 let tier = sandbox
2977 .microvm_tier()
2978 .expect("2Gi/1cpu/20Gi is satisfiable");
2979
2980 assert_eq!(
2981 tier.peak_memory_mib, 2048,
2982 "the peak is the declared ceiling"
2983 );
2984 assert_eq!(
2985 tier.baseline_memory_mib, 512,
2986 "which is a quarter of it as the baseline"
2987 );
2988 assert!(tier.max_disk_mib <= 20 * 1024);
2989 }
2990
2991 #[test]
2995 fn a_cpu_ceiling_below_what_the_memory_implies_is_refused_not_quietly_downsized() {
2996 let mut sandbox = sandbox_with(SandboxEgress::None, vec![]);
2997 {
2998 let limits = sandbox
2999 .limits
3000 .as_mut()
3001 .expect("the fixture declares limits");
3002 limits.cpu = "1".to_string();
3003 limits.memory = "8Gi".to_string();
3004 }
3005
3006 let error = sandbox
3007 .microvm_tier()
3008 .expect_err("1 cpu and 8Gi cannot both be ceilings on AWS");
3009 assert!(
3010 error.to_string().contains("4 vCPU"),
3011 "the refusal must say what the memory ceiling implies: {error}"
3012 );
3013
3014 sandbox
3015 .limits
3016 .as_mut()
3017 .expect("the fixture declares limits")
3018 .cpu = "4".to_string();
3019 let tier = sandbox.microvm_tier().expect("4 cpu matches 8Gi");
3020 assert_eq!(tier.peak_memory_mib, 8192);
3021 }
3022
3023 #[test]
3026 fn an_aws_ceiling_smaller_than_any_size_is_refused_rather_than_rounded() {
3027 let mut sandbox = sandbox_with(SandboxEgress::None, vec![]);
3028 sandbox
3029 .limits
3030 .as_mut()
3031 .expect("the fixture declares limits")
3032 .memory = "1Gi".to_string();
3033
3034 let error = sandbox
3035 .validate_for_platform(Platform::Aws)
3036 .expect_err("no MicroVM size peaks at or below 1Gi");
3037 assert_eq!(error.code, "SANDBOX_LIMIT_INVALID");
3038 assert!(
3039 error.to_string().contains("2Gi"),
3040 "the refusal must say what the smallest holdable ceiling is: {error}"
3041 );
3042 }
3043
3044 #[test]
3047 fn source_code_is_refused_where_no_backend_builds_it() {
3048 let sandbox = Sandbox::new("agent".to_string())
3049 .code(SandboxCode::Source {
3050 src: "./sandbox".to_string(),
3051 toolchain: ToolchainConfig::Docker {
3052 dockerfile: None,
3053 build_args: None,
3054 target: None,
3055 },
3056 })
3057 .egress(SandboxEgress::None)
3058 .lifecycle(SandboxLifecyclePolicy {
3059 max_lifetime_seconds: None,
3060 idle_pause_seconds: None,
3061 ..Default::default()
3062 })
3063 .build();
3064
3065 sandbox
3066 .validate_for_platform(Platform::Aws)
3067 .expect("an AWS sandbox base image is built by `alien build`");
3068 sandbox
3069 .validate_for_platform(Platform::Azure)
3070 .expect("an Azure sandbox base image is built by `alien build`");
3071 sandbox
3072 .validate_for_platform(Platform::Gcp)
3073 .expect("a GCP sandbox base image is built by `alien build`");
3074 sandbox
3075 .validate_for_platform(Platform::Kubernetes)
3076 .expect("a Kubernetes sandbox base image is built by `alien build`");
3077
3078 for platform in [Platform::Local] {
3079 let error = sandbox
3080 .validate_for_platform(platform)
3081 .expect_err("no backend builds a sandbox image from source here");
3082 assert_eq!(error.code, "SANDBOX_LIMIT_INVALID");
3083 assert!(
3084 error.to_string().contains("code.image"),
3085 "the refusal must say what to write instead: {error}"
3086 );
3087 assert!(
3088 error.to_string().contains(&platform.to_string()),
3089 "the refusal must name the platform that cannot build it: {error}"
3090 );
3091 }
3092 }
3093
3094 #[test]
3097 fn every_accepted_unit_converts_rather_than_falling_back() {
3098 assert_eq!(quantity_mib("2Gi"), Some(2048));
3099 assert_eq!(quantity_mib("512Mi"), Some(512));
3100 assert_eq!(quantity_mib("4G"), Some(3814));
3101 assert_eq!(quantity_mib("1Ti"), Some(1024 * 1024));
3102 assert_eq!(millicores("1"), Some(1000));
3103 assert_eq!(millicores("500m"), Some(500));
3104 }
3105
3106 #[test]
3107 fn privileged_supervisor_fixes_identity_and_requires_an_enforceable_backend() {
3108 let mut sandbox = sandbox_with(
3109 SandboxEgress::AllowDomains {
3110 domains: vec!["example.com".to_string()],
3111 },
3112 vec![],
3113 );
3114 sandbox.privileged_supervisor = Some(SandboxPrivilegedSupervisor { command_uid: 60001 });
3115 sandbox
3116 .validate_for_platform(Platform::Aws)
3117 .expect("AWS can enforce the policy in the agent");
3118 assert_eq!(sandbox.cloud_egress(), &SandboxEgress::Allow);
3119 assert_eq!(
3120 sandbox.supervisor_environment()["ALIEN_SANDBOX_EXPECTED_EXEC_UID"],
3121 "60001"
3122 );
3123 for platform in [
3124 Platform::Local,
3125 Platform::Kubernetes,
3126 Platform::Azure,
3127 Platform::Gcp,
3128 ] {
3129 let error = sandbox
3130 .validate_for_platform(platform)
3131 .expect_err("cannot grant a privilege boundary the backend lacks");
3132 assert_eq!(error.code, "SANDBOX_CAPABILITY_UNSUPPORTED");
3133 assert!(error.message.contains("privilegedSupervisor"));
3134 }
3135 for uid in [0, u32::MAX] {
3136 sandbox.privileged_supervisor.as_mut().unwrap().command_uid = uid;
3137 let error = sandbox
3138 .validate_for_platform(Platform::Aws)
3139 .expect_err("invalid uid must fail at plan time");
3140 assert_eq!(error.code, "SANDBOX_LIMIT_INVALID");
3141 }
3142 }
3143
3144 #[test]
3145 fn unknown_fields_are_rejected() {
3146 let json = r#"{
3147 "id": "sbx",
3148 "code": {"type": "image", "image": "ubuntu:24.04"},
3149 "limits": {"cpu": "1", "memory": "2Gi", "disk": "20Gi"},
3150 "egress": {"mode": "deny"},
3151 "lifecycle": {},
3152 "unexpected": true
3153 }"#;
3154
3155 serde_json::from_str::<Sandbox>(json).expect_err("deny_unknown_fields must reject");
3156 }
3157
3158 #[test]
3159 fn serialization_roundtrips() {
3160 let sandbox = sandbox_with(
3161 SandboxEgress::AllowDomains {
3162 domains: vec!["example.com".to_string()],
3163 },
3164 vec![8080, 9090],
3165 );
3166
3167 let json = serde_json::to_string(&sandbox).expect("serializes");
3168 let restored: Sandbox = serde_json::from_str(&json).expect("deserializes");
3169 assert_eq!(sandbox, restored);
3170 }
3171
3172 #[test]
3173 fn id_is_immutable_across_updates() {
3174 let original = sandbox_with(SandboxEgress::None, vec![]);
3175 let renamed = Sandbox::new("other".to_string())
3176 .code(SandboxCode::Image {
3177 image: "ubuntu".to_string(),
3178 bundled_from: None,
3179 })
3180 .limits(
3181 original
3182 .limits
3183 .clone()
3184 .expect("the fixture declares limits"),
3185 )
3186 .egress(SandboxEgress::None)
3187 .lifecycle(SandboxLifecyclePolicy {
3188 max_lifetime_seconds: None,
3189 idle_pause_seconds: None,
3190 ..Default::default()
3191 })
3192 .build();
3193
3194 original
3195 .validate_update(&original.clone())
3196 .expect("an unchanged config is a valid update");
3197 original
3198 .validate_update(&renamed)
3199 .expect_err("renaming a sandbox is not an update");
3200 }
3201
3202 #[test]
3206 fn azure_takes_an_idle_policy_and_a_lifetime_ceiling() {
3207 let with_policy = |lifecycle: SandboxLifecyclePolicy| {
3208 Sandbox::new("sbx".to_string())
3209 .code(SandboxCode::Image {
3210 image: "ubuntu".to_string(),
3211 bundled_from: None,
3212 })
3213 .egress(SandboxEgress::Allow)
3214 .lifecycle(lifecycle)
3215 .build()
3216 .validate_for_platform(Platform::Azure)
3217 };
3218
3219 with_policy(SandboxLifecyclePolicy {
3220 max_lifetime_seconds: None,
3221 idle_pause_seconds: Some(900),
3222 ..Default::default()
3223 })
3224 .expect("Azure pauses a sandbox on idle");
3225
3226 with_policy(SandboxLifecyclePolicy {
3227 max_lifetime_seconds: Some(3600),
3228 idle_pause_seconds: None,
3229 ..Default::default()
3230 })
3231 .expect("the reaper enforces a wall-clock ceiling");
3232 }
3233
3234 #[test]
3240 fn an_allowlist_with_no_domains_is_refused() {
3241 let declared = |domains: Vec<String>| {
3242 Sandbox::new("sbx".to_string())
3243 .code(SandboxCode::Image {
3244 image: "ubuntu".to_string(),
3245 bundled_from: None,
3246 })
3247 .egress(SandboxEgress::AllowDomains { domains })
3248 .lifecycle(SandboxLifecyclePolicy {
3249 max_lifetime_seconds: None,
3250 idle_pause_seconds: None,
3251 ..Default::default()
3252 })
3253 .build()
3254 .validate_for_platform(Platform::Azure)
3255 };
3256
3257 let error = declared(vec![]).expect_err("an empty allowlist must be refused");
3258 assert_eq!(error.code, "SANDBOX_LIMIT_INVALID");
3259
3260 declared(vec!["api.example.com".to_string()])
3261 .expect("a named domain is what an allowlist is for");
3262 }
3263
3264 #[test]
3267 fn internet_access_switch_maps_only_the_two_expressible_modes() {
3268 assert_eq!(SandboxEgress::Allow.internet_access_switch(), Some(true));
3269 assert_eq!(SandboxEgress::None.internet_access_switch(), Some(false));
3270 assert_eq!(
3271 SandboxEgress::AllowDomains {
3272 domains: vec!["api.example.com".to_string()]
3273 }
3274 .internet_access_switch(),
3275 None,
3276 "a host list has no boolean and must not be approximated"
3277 );
3278 }
3279
3280 #[test]
3284 fn stack_state_written_before_the_lifecycle_rename_still_reads() {
3285 let stored: crate::StackResourceState = serde_json::from_value(serde_json::json!({
3286 "type": "sandbox",
3287 "config": {
3288 "id": "sandbox",
3289 "code": {
3290 "type": "image",
3291 "image": "s3://example-bundles/analysis/v1/bundle.zip"
3292 },
3293 "type": "sandbox",
3294 "egress": { "mode": "allow" },
3295 "session": { "maxLifetimeSeconds": 28800, "idleSuspendSeconds": 600 }
3296 },
3297 "status": "running",
3298 "outputs": {
3299 "type": "sandbox",
3300 "identifier": "arn:aws:lambda:us-east-2:123456789012:microvm-image:example-sandbox",
3301 "parentName": "arn:aws:lambda:us-east-2:123456789012:microvm-image:example-sandbox"
3302 },
3303 "lifecycle": "frozen",
3304 "dependencies": [
3305 { "id": "management", "type": "remote-stack-management" },
3306 { "id": "access", "type": "resource-access" }
3307 ],
3308 "controllerPlatform": "aws"
3309 }))
3310 .expect("a stack state written before the rename must still deserialize");
3311
3312 let expected = Sandbox::new("sandbox".to_string())
3313 .code(SandboxCode::Image {
3314 image: "s3://example-bundles/analysis/v1/bundle.zip".to_string(),
3315 bundled_from: None,
3316 })
3317 .egress(SandboxEgress::Allow)
3318 .lifecycle(SandboxLifecyclePolicy {
3319 max_lifetime_seconds: Some(28_800),
3320 idle_pause_seconds: Some(600),
3321 ..Default::default()
3322 })
3323 .build();
3324 assert_eq!(stored.config.downcast_ref::<Sandbox>(), Some(&expected));
3325
3326 let rewritten = serde_json::to_value(&stored.config).expect("the sandbox serializes");
3327 assert_eq!(
3328 rewritten["lifecycle"],
3329 serde_json::json!({ "maxLifetimeSeconds": 28800, "idlePauseSeconds": 600 }),
3330 "the next write stores the current names"
3331 );
3332 assert!(rewritten.get("session").is_none());
3333 }
3334}
3335
3336#[cfg(test)]
3337mod label_format_tests {
3338 use super::*;
3339
3340 #[test]
3341 fn request_keys_are_bounded_and_safe() {
3342 for good in ["a", "A-z_9", &"x".repeat(64)] {
3343 assert!(is_valid_request_key(good), "{good}");
3344 }
3345 for bad in ["", "a b", "a/b", "a.b", "é", &"x".repeat(65)] {
3346 assert!(!is_valid_request_key(bad), "{bad}");
3347 }
3348 }
3349
3350 #[test]
3351 fn expiry_is_a_positive_integer() {
3352 assert!(is_valid_sandbox_expiry("1700000000000"));
3353 for bad in ["", "0", "-1", "1.5", "never", "+5 "] {
3354 assert!(!is_valid_sandbox_expiry(bad), "{bad}");
3355 }
3356 }
3357}