use crate::error::{ErrorData, Result};
use crate::resource::ResourceRef;
use crate::Platform;
use alien_error::AlienError;
use serde::{Deserialize, Serialize};
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub enum SandboxImageMountType {
Nfs,
Tmpfs,
Bind,
}
impl SandboxImageMountType {
pub fn as_str(self) -> &'static str {
match self {
Self::Nfs => "nfs",
Self::Tmpfs => "tmpfs",
Self::Bind => "bind",
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct SandboxImageMount {
#[serde(rename = "type")]
pub mount_type: SandboxImageMountType,
pub path: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub size: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub from: Option<String>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct SandboxImageConnection {
pub to: ResourceRef,
pub port: u16,
}
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct SandboxImagePermissions {
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub mounts: Vec<SandboxImageMount>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub connections: Vec<SandboxImageConnection>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub enum PrivateEndpointPlacement {
StackNetwork,
}
pub trait PrivateNetworkEndpoints {
fn private_endpoint_placement(&self) -> PrivateEndpointPlacement;
}
const PROTECTED_PATHS: &[&str] = &[
"/opt/alien",
"/proc",
"/sys",
"/dev",
"/run",
"/etc",
"/usr",
"/bin",
"/sbin",
"/boot",
];
const MAX_TMPFS_BYTES: u64 = 1 << 40;
impl SandboxImagePermissions {
pub fn validate(&self, resource_id: &str) -> Result<()> {
let invalid = |field: &str, value: &str, reason: &str| {
AlienError::new(ErrorData::SandboxLimitInvalid {
resource_id: resource_id.to_string(),
field: field.to_string(),
value: value.to_string(),
reason: reason.to_string(),
})
};
if self.mounts.is_empty() && self.connections.is_empty() {
return Err(invalid(
"imagePermissions",
"{}",
"declare at least one mount or connection, or leave imagePermissions out",
));
}
let mut paths = std::collections::BTreeSet::new();
for mount in &self.mounts {
if let Err(reason) = check_mount_path(&mount.path) {
return Err(invalid(
"imagePermissions.mounts.path",
&mount.path,
&reason,
));
}
if !paths.insert(mount.path.as_str()) {
return Err(invalid(
"imagePermissions.mounts.path",
&mount.path,
"declared more than once",
));
}
let refuse = |field: &str, value: &str, reason: &str| {
Err(invalid(
&format!("imagePermissions.mounts.{field}"),
value,
reason,
))
};
match (mount.mount_type, &mount.size, &mount.from) {
(SandboxImageMountType::Tmpfs, None, _) => {
return refuse(
"size",
&mount.path,
"a tmpfs mount needs a size, such as \"8Gi\"",
)
}
(SandboxImageMountType::Tmpfs, Some(size), None) => {
tmpfs_size_bytes(size)
.map_err(|reason| invalid("imagePermissions.mounts.size", size, &reason))?;
}
(SandboxImageMountType::Nfs | SandboxImageMountType::Bind, Some(size), _) => {
return refuse("size", size, "only a tmpfs mount takes a size")
}
(SandboxImageMountType::Bind, None, None) => {
return refuse(
"from",
&mount.path,
"a bind mount needs `from`, the declared mount it places again",
)
}
(SandboxImageMountType::Bind, None, Some(from)) => {
if let Err(reason) = check_mount_path(from) {
return refuse("from", from, &reason);
}
let source = self.mounts.iter().find(|source| {
source.mount_type == SandboxImageMountType::Tmpfs && from == &source.path
});
if source.is_none() {
return refuse("from", from, "must be the path of a declared tmpfs mount");
}
let target = self.mounts.iter().any(|target| {
target.mount_type == SandboxImageMountType::Nfs
&& is_under(&mount.path, &target.path)
});
if !target {
return refuse(
"path",
&mount.path,
"a bind must be placed inside a declared nfs mount",
);
}
if is_same_or_under(&mount.path, from) {
return refuse(
"from",
from,
"a bind cannot be placed inside its own source",
);
}
}
(SandboxImageMountType::Nfs | SandboxImageMountType::Tmpfs, _, Some(from)) => {
return refuse("from", from, "only a bind mount takes `from`")
}
(SandboxImageMountType::Nfs, None, None) => {}
}
}
let mut connections = std::collections::HashSet::new();
for connection in &self.connections {
let value = format!("{}:{}", connection.to.id, connection.port);
if connection.port == 0 {
return Err(invalid(
"imagePermissions.connections.port",
&value,
"port 0 names no service",
));
}
if connection.port == 53 {
return Err(invalid(
"imagePermissions.connections.port",
&value,
"DNS always goes through the agent's resolver; port 53 cannot be a direct connection",
));
}
if !connections.insert((&connection.to, connection.port)) {
return Err(invalid(
"imagePermissions.connections",
&value,
"declared more than once",
));
}
}
Ok(())
}
}
fn check_mount_path(path: &str) -> std::result::Result<(), String> {
if !path.starts_with('/') {
return Err("must be an absolute path".into());
}
if path == "/" {
return Err("cannot mount over the root file system".into());
}
if path.len() > 1024 {
return Err("longer than 1024 bytes".into());
}
if !path
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'/' | b'-' | b'_' | b'.'))
{
return Err("may contain only letters, digits, '/', '-', '_' and '.'".into());
}
let segments: Vec<&str> = path[1..].split('/').collect();
if segments
.iter()
.any(|segment| segment.is_empty() || *segment == "." || *segment == "..")
{
return Err(
"must be normalized: no trailing '/', no '//', and no '.' or '..' segments".into(),
);
}
if segments[0].starts_with("lib") {
return Err(format!("overlaps the system path /{}", segments[0]));
}
for protected in PROTECTED_PATHS {
if is_same_or_under(path, protected) || is_same_or_under(protected, path) {
return Err(format!("overlaps the system path {protected}"));
}
}
Ok(())
}
fn is_same_or_under(path: &str, ancestor: &str) -> bool {
path == ancestor
|| path
.strip_prefix(ancestor)
.is_some_and(|rest| rest.starts_with('/'))
}
fn is_under(path: &str, ancestor: &str) -> bool {
path != ancestor && is_same_or_under(path, ancestor)
}
pub fn tmpfs_size_bytes(size: &str) -> std::result::Result<u64, String> {
let digits_end = size
.find(|c: char| !c.is_ascii_digit())
.unwrap_or(size.len());
let (number, suffix) = size.split_at(digits_end);
let unit: u64 = match suffix {
"" => 1,
"k" => 1_000,
"M" => 1_000_000,
"G" => 1_000_000_000,
"T" => 1_000_000_000_000,
"Ki" => 1 << 10,
"Mi" => 1 << 20,
"Gi" => 1 << 30,
"Ti" => 1 << 40,
_ => {
return Err(
"must be a whole number with an optional unit (k, M, G, T, Ki, Mi, Gi, Ti)".into(),
)
}
};
let number: u64 = number
.parse()
.map_err(|_| "must start with a whole number, such as \"8Gi\"".to_string())?;
let bytes = number
.checked_mul(unit)
.filter(|bytes| *bytes <= MAX_TMPFS_BYTES)
.ok_or_else(|| "must be at most 1Ti".to_string())?;
if bytes < 1 << 20 {
return Err("must be at least 1Mi".into());
}
Ok(bytes)
}
pub(crate) fn validate_lifecycle_argv(
resource_id: &str,
field: &str,
argv: &[String],
mounts: &[SandboxImageMount],
) -> Result<()> {
let invalid = |value: &str, reason: &str| {
AlienError::new(ErrorData::SandboxLimitInvalid {
resource_id: resource_id.to_string(),
field: field.to_string(),
value: value.to_string(),
reason: reason.to_string(),
})
};
let Some(program) = argv.first() else {
return Err(invalid("[]", "needs a program to run"));
};
if !program.starts_with('/') {
return Err(invalid(
program,
"the program must be an absolute path inside the image; there is no PATH lookup",
));
}
if program[1..]
.split('/')
.any(|segment| segment.is_empty() || segment == "." || segment == "..")
{
return Err(invalid(
program,
"the program path must be normalized: no trailing '/', no '//', and no '.' or '..' \
segments",
));
}
if let Some(mount) = mounts
.iter()
.find(|mount| is_same_or_under(program, &mount.path))
{
return Err(invalid(
program,
&format!(
"the program is on the declared mount {}; a lifecycle step must run from the \
image's own files",
mount.path
),
));
}
if argv
.iter()
.any(|argument| argument.contains('\0') || argument.len() > 4096)
{
return Err(invalid(
program,
"arguments may not contain NUL or exceed 4096 bytes",
));
}
if argv.len() > 64 {
return Err(invalid(program, "at most 64 arguments"));
}
Ok(())
}
pub(crate) fn require_image_permissions_platform(
capability: &str,
platform: Platform,
) -> Result<()> {
if platform == Platform::Aws {
return Ok(());
}
Err(AlienError::new(ErrorData::SandboxCapabilityUnsupported {
capability: format!("{capability} (available on AWS Lambda MicroVM sandboxes only)"),
platform: platform.to_string(),
}))
}
#[cfg(test)]
mod tests {
use super::*;
use crate::ResourceType;
fn mount(
mount_type: SandboxImageMountType,
path: &str,
size: Option<&str>,
) -> SandboxImageMount {
SandboxImageMount {
mount_type,
path: path.into(),
size: size.map(Into::into),
from: None,
}
}
fn connection(id: &str, port: u16) -> SandboxImageConnection {
SandboxImageConnection {
to: ResourceRef::new(ResourceType::from("acme-files"), id),
port,
}
}
fn permissions(
mounts: Vec<SandboxImageMount>,
connections: Vec<SandboxImageConnection>,
) -> SandboxImagePermissions {
SandboxImagePermissions {
mounts,
connections,
}
}
#[test]
fn the_designed_declaration_is_accepted() {
permissions(
vec![
mount(SandboxImageMountType::Nfs, "/workspace", None),
mount(SandboxImageMountType::Tmpfs, "/workspace/tmp", Some("8Gi")),
],
vec![connection("workspace-files", 2049)],
)
.validate("sandboxes")
.unwrap();
}
#[test]
fn system_and_unnormalized_paths_are_refused() {
for path in [
"/",
"workspace",
"/workspace/",
"/workspace//tmp",
"/workspace/./tmp",
"/workspace/../etc",
"/opt/alien",
"/opt/alien/bin",
"/opt",
"/proc",
"/proc/sys",
"/sys",
"/dev/shm",
"/run",
"/run/alien",
"/etc",
"/usr/local",
"/bin",
"/sbin",
"/lib",
"/lib64",
"/libx32/foo",
"/boot",
"/boot/efi",
"/work space",
"/work,space",
] {
let error = permissions(vec![mount(SandboxImageMountType::Nfs, path, None)], vec![])
.validate("sandboxes")
.expect_err(path);
assert!(error.to_string().contains("mounts.path"), "{path}: {error}");
}
for path in [
"/procedures",
"/opt/alienware",
"/devices",
"/running",
"/opt/data",
] {
permissions(vec![mount(SandboxImageMountType::Nfs, path, None)], vec![])
.validate("sandboxes")
.unwrap_or_else(|error| panic!("{path}: {error}"));
}
}
#[test]
fn tmpfs_needs_a_size_and_nfs_takes_none() {
assert!(permissions(
vec![mount(SandboxImageMountType::Tmpfs, "/scratch", None)],
vec![]
)
.validate("s")
.is_err());
assert!(permissions(
vec![mount(SandboxImageMountType::Nfs, "/scratch", Some("1Gi"))],
vec![]
)
.validate("s")
.is_err());
for size in ["8", "1.5Gi", "8gb", "2Ti", "", "Gi", "512Ki"] {
assert!(
permissions(
vec![mount(SandboxImageMountType::Tmpfs, "/scratch", Some(size))],
vec![]
)
.validate("s")
.is_err(),
"{size}"
);
}
assert_eq!(tmpfs_size_bytes("8Gi").unwrap(), 8_589_934_592);
assert_eq!(tmpfs_size_bytes("512Mi").unwrap(), 536_870_912);
assert_eq!(tmpfs_size_bytes("2G").unwrap(), 2_000_000_000);
}
fn bind(from: &str, path: &str) -> SandboxImageMount {
SandboxImageMount {
mount_type: SandboxImageMountType::Bind,
path: path.into(),
size: None,
from: Some(from.into()),
}
}
#[test]
fn a_bind_places_a_declared_mount_again_and_nothing_else() {
let tmpfs = || {
mount(
SandboxImageMountType::Tmpfs,
"/var/lib/app/scratch",
Some("8Gi"),
)
};
let nfs = || mount(SandboxImageMountType::Nfs, "/workspace", None);
permissions(
vec![
nfs(),
tmpfs(),
bind("/var/lib/app/scratch", "/workspace/tmp"),
],
vec![],
)
.validate("s")
.unwrap();
for (mounts, why) in [
(
vec![
nfs(),
tmpfs(),
bind("/var/lib/app/scratch/a", "/workspace/a"),
],
"source inside a tmpfs rather than the tmpfs itself (the agent takes only a \
declared mount path)",
),
(
vec![nfs(), bind("/var/lib/app/scratch", "/workspace/tmp")],
"undeclared source",
),
(vec![nfs(), bind("/etc", "/workspace/etc")], "system source"),
(
vec![tmpfs(), bind("/var/lib/app/scratch", "/data")],
"target outside any nfs mount",
),
(
vec![nfs(), tmpfs(), bind("/var/lib/app/scratch", "/workspace")],
"target is the nfs mount itself",
),
(
vec![
nfs(),
mount(SandboxImageMountType::Nfs, "/shared", None),
bind("/shared", "/workspace/shared"),
],
"nfs source",
),
(
vec![tmpfs(), bind("/var/lib/app", "/data")],
"parent of a mount",
),
(
vec![
tmpfs(),
bind("/var/lib/app/scratch", "/var/lib/app/scratch/x"),
],
"inside itself",
),
(
vec![
nfs(),
tmpfs(),
bind("/var/lib/app/scratch", "/workspace/a"),
bind("/workspace/a", "/workspace/b"),
],
"from a bind",
),
(
vec![SandboxImageMount {
mount_type: SandboxImageMountType::Bind,
path: "/x".into(),
size: None,
from: None,
}],
"no from",
),
(
vec![SandboxImageMount {
from: Some("/workspace".into()),
..nfs()
}],
"from on nfs",
),
] {
assert!(permissions(mounts, vec![]).validate("s").is_err(), "{why}");
}
}
#[test]
fn port_53_zero_and_duplicates_are_refused() {
for connections in [
vec![connection("files", 53)],
vec![connection("files", 0)],
vec![connection("files", 2049), connection("files", 2049)],
] {
assert!(permissions(vec![], connections).validate("s").is_err());
}
assert!(permissions(
vec![
mount(SandboxImageMountType::Nfs, "/a", None),
mount(SandboxImageMountType::Nfs, "/a", None)
],
vec![]
)
.validate("s")
.is_err());
assert!(permissions(vec![], vec![]).validate("s").is_err());
}
#[test]
fn unknown_fields_are_refused_so_an_older_reader_cannot_drop_them() {
for json in [
r#"{"mounts":[{"type":"nfs","path":"/w","readOnly":true}]}"#,
r#"{"mounts":[],"capabilities":["SYS_ADMIN"]}"#,
r#"{"connections":[{"to":{"type":"x","id":"y"},"port":2049,"cidr":"0.0.0.0/0"}]}"#,
r#"{"mounts":[{"type":"overlay","path":"/w"}]}"#,
] {
serde_json::from_str::<SandboxImagePermissions>(json).expect_err(json);
}
}
#[test]
fn lifecycle_argv_must_name_an_absolute_program() {
validate_lifecycle_argv(
"s",
"onPause",
&["/usr/bin/app".into(), "pause".into()],
&[],
)
.unwrap();
assert!(validate_lifecycle_argv("s", "onPause", &[], &[]).is_err());
assert!(validate_lifecycle_argv("s", "onPause", &["app".into()], &[]).is_err());
assert!(
validate_lifecycle_argv("s", "onPause", &["/a".into(), "b\0".into()], &[]).is_err()
);
}
fn declared_sandbox() -> crate::Sandbox {
let mut sandbox = crate::Sandbox::new("sandboxes".to_string())
.code(crate::SandboxCode::Image {
image: "s3://bundles/sandboxes.zip".to_string(),
bundled_from: None,
})
.egress(crate::SandboxEgress::Internet)
.lifecycle(crate::SandboxLifecyclePolicy::default())
.build();
sandbox.image_permissions = Some(permissions(
vec![mount(SandboxImageMountType::Nfs, "/workspace", None)],
vec![connection("workspace-files", 2049)],
));
sandbox
}
#[test]
fn only_aws_accepts_image_permissions_and_the_refusal_names_the_platform() {
declared_sandbox()
.validate_for_platform(Platform::Aws)
.unwrap();
for platform in [
Platform::Gcp,
Platform::Azure,
Platform::Kubernetes,
Platform::Local,
] {
let error = declared_sandbox()
.validate_for_platform(platform)
.expect_err("refused off AWS");
assert!(error.to_string().contains("imagePermissions"), "{error}");
assert!(error.to_string().contains(&platform.to_string()), "{error}");
}
let mut steps_only = declared_sandbox();
steps_only.image_permissions = None;
steps_only.lifecycle.on_resume = Some(vec!["/bin/true".into()]);
steps_only.validate_for_platform(Platform::Aws).unwrap();
let error = steps_only.validate_for_platform(Platform::Gcp).unwrap_err();
assert!(error.to_string().contains("onResume"), "{error}");
let mut pause_only = declared_sandbox();
pause_only.image_permissions = None;
pause_only.lifecycle.on_pause = Some(vec!["/bin/sync".into()]);
pause_only.validate_for_platform(Platform::Aws).unwrap();
for platform in [Platform::Azure, Platform::Kubernetes, Platform::Local] {
let error = pause_only
.validate_for_platform(platform)
.expect_err("onPause refused off AWS");
assert!(error.to_string().contains("onPause"), "{error}");
assert!(error.to_string().contains(&platform.to_string()), "{error}");
}
}
#[test]
fn lifecycle_programs_under_a_declared_mount_are_refused() {
let with_mounts = || {
let mut sandbox = declared_sandbox();
sandbox.image_permissions = Some(permissions(
vec![
mount(SandboxImageMountType::Nfs, "/workspace", None),
mount(SandboxImageMountType::Tmpfs, "/scratch", Some("64Mi")),
SandboxImageMount {
mount_type: SandboxImageMountType::Bind,
path: "/workspace/cache".into(),
size: None,
from: Some("/scratch".into()),
},
],
vec![connection("workspace-files", 2049)],
));
sandbox
};
for field in ["onPause", "onResume"] {
let set = |sandbox: &mut crate::Sandbox, program: &str| {
let argv = Some(vec![program.to_string(), "pause".to_string()]);
if field == "onPause" {
sandbox.lifecycle.on_pause = argv;
} else {
sandbox.lifecycle.on_resume = argv;
}
};
for program in ["/usr/local/bin/app", "/workspaces/app", "/scratchpad"] {
let mut sandbox = with_mounts();
set(&mut sandbox, program);
sandbox
.validate_for_platform(Platform::Aws)
.unwrap_or_else(|error| panic!("{field} {program}: {error}"));
}
for program in [
"/workspace",
"/workspace/bin/pause",
"/scratch/pause",
"/workspace/cache/pause",
"//workspace/bin/pause",
"/usr/../workspace/pause",
"/./scratch/pause",
"/usr/bin/",
] {
let mut sandbox = with_mounts();
set(&mut sandbox, program);
let error = sandbox
.validate_for_platform(Platform::Aws)
.expect_err(program);
assert!(error.to_string().contains(field), "{program}: {error}");
}
}
}
#[test]
fn image_permissions_need_guest_network_egress_and_a_root_image() {
let steps_only = || {
let mut sandbox = declared_sandbox();
sandbox.image_permissions = None;
sandbox.lifecycle.on_pause = Some(vec!["/bin/sync".into()]);
sandbox
};
for declared in [declared_sandbox, steps_only] {
for egress in [crate::SandboxEgress::Internet, crate::SandboxEgress::None] {
let mut sandbox = declared();
sandbox.egress = egress;
sandbox.validate_for_platform(Platform::Aws).unwrap();
sandbox.image_user = Some(0);
sandbox.validate_for_platform(Platform::Aws).unwrap();
}
for egress in [
crate::SandboxEgress::Allow,
crate::SandboxEgress::AllowDomains {
domains: vec!["example.com".into()],
},
] {
let mut sandbox = declared();
sandbox.egress = egress;
let error = sandbox
.validate_for_platform(Platform::Aws)
.expect_err("egress without the guest network");
assert!(error.to_string().contains("egress"), "{error}");
}
let mut sandbox = declared();
sandbox.image_user = Some(1000);
let error = sandbox
.validate_for_platform(Platform::Aws)
.expect_err("a non-root image");
assert!(error.to_string().contains("root"), "{error}");
}
}
#[test]
fn a_sandbox_without_image_permissions_serializes_as_before() {
let mut sandbox = declared_sandbox();
sandbox.image_permissions = None;
let json = serde_json::to_value(&sandbox).unwrap();
assert!(json.get("imagePermissions").is_none());
assert_eq!(json["lifecycle"], serde_json::json!({}));
let declared = serde_json::to_value(declared_sandbox()).unwrap();
assert_eq!(
declared["imagePermissions"],
serde_json::json!({
"mounts": [{"type": "nfs", "path": "/workspace"}],
"connections": [{"to": {"type": "acme-files", "id": "workspace-files"}, "port": 2049}]
})
);
let read: crate::Sandbox = serde_json::from_value(declared).unwrap();
assert_eq!(read, declared_sandbox());
}
}