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