feat: enable ASLR for PIE guest binaries

Randomize the virtual base address for PIE guest code regions instead
of using identity mapping. This provides address space layout
randomization (ASLR) for PIE guests, making the code region virtual
address unpredictable across sandbox instantiations.

The random base is chosen from a page-aligned range within 47-bit
canonical user space [0x1000000, max - code_size). Non-PIE binaries
continue to use their declared ELF base VA.

Changes:
- layout.rs: code_virt_base() now randomizes VA for PIE guests and
  always validates against memory region conflicts
- mgr.rs: thread code_virt_base through SandboxMemoryManager
- snapshot/mod.rs: store code_virt_base in Snapshot, use it for
  relocation processing in exe_info.load()
- config.rs: relax entrypoint validation to allow non-identity-mapped
  virtual addresses (ASLR / non-PIE)
- initialized_multi_use.rs: trace_guest tests use code_virt_base
  instead of assuming GVA == GPA

Signed-off-by: cshung <3410332+cshung@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 6f20a05d-6bee-4e2e-b320-12f8d9759bbc
Signed-off-by: cshung <3410332+cshung@users.noreply.github.com>

Author: cshung

Justfile

@@ -76,6 +76,7 @@ build-and-move-rust-guests: (build-rust-guests "debug") (move-rust-guests "debug
 build-and-move-c-guests: (build-c-guests "debug") (move-c-guests "debug") (build-c-guests "release") (move-c-guests "release")
 
 # Build non-PIE variants of rust guests for testing ELF VA mapping.
+# NOTE: non-PIE guests are x86_64-only; aarch64 is not yet supported.
 # Phase 1 builds the sysroot without RUSTFLAGS (avoids RUSTFLAGS leaking
 # into the sysroot wrapper build in cargo-hyperlight).
 # Phase 2 uses plain cargo with --sysroot and non-PIE link flags.

src/hyperlight_host/src/hypervisor/hyperlight_vm/x86_64.rs

@@ -720,10 +720,9 @@ pub(super) mod debug {
                             .dbg_mem_access_fn
                             .try_lock()
                             .map_err(|_| ProcessDebugRequestError::TryLockError(file!(), line!()))?
-                            .layout
-                            .get_guest_code_address();
+                            .code_virt_base;
 
-                        Ok(DebugResponse::GetCodeSectionOffset(offset as u64))
+                        Ok(DebugResponse::GetCodeSectionOffset(offset))
                     }
                     DebugMsg::ReadAddr(addr, len) => {
                         let mut data = vec![0u8; len];

src/hyperlight_host/src/mem/layout.rs

@@ -557,15 +557,12 @@ impl SandboxMemoryLayout {
     /// guest memory regions with the Code region's `guest_virt_addr`
     /// already set to the computed virtual base.
     ///
-    /// For PIE binaries (`is_pie == true`), the code is identity-mapped so
-    /// the virtual base equals the physical load address and no conflict
-    /// is possible by construction.
+    /// For PIE binaries, a random page-aligned address is chosen within
+    /// 47-bit canonical user space (ASLR).  For non-PIE binaries, the
+    /// code appears at the ELF's declared virtual address (`elf_base_va`).
     ///
-    /// For non-PIE binaries, the code appears at the ELF's declared
-    /// virtual address (`elf_base_va`), which may differ from the physical
-    /// load address.  This method checks that the resulting virtual range
-    /// `[elf_base_va, elf_base_va + loaded_size)` does not overlap any
-    /// non-Code region.
+    /// In both cases the resulting virtual range is validated against all
+    /// non-Code memory regions to prevent overlap.
     ///
     /// Returns `(code_virt_base, regions)`.
     pub(crate) fn get_guest_regions_with_code_va(
@@ -574,35 +571,56 @@ impl SandboxMemoryLayout {
         elf_base_va: u64,
         loaded_size: u64,
     ) -> Result<(u64, Vec<MemoryRegion_<GuestMemoryRegion>>)> {
-        let load_addr = self.get_guest_code_address() as u64;
-        let code_virt_base = if is_pie { load_addr } else { elf_base_va };
+        let code_size_pages = loaded_size.div_ceil(PAGE_SIZE_USIZE as u64);
+        let code_virt_base = if !is_pie {
+            elf_base_va
+        } else {
+            // Pick a random page-aligned address within 47-bit canonical user space.
+            // Lower bound: 0x1000000 (16 MiB, above all identity-mapped layout regions)
+            // Upper bound: accounts for code region size so it doesn't overflow
+            use rand::RngExt;
+            let mut rng = rand::rng();
+            let min_page = 0x1000_u64; // 0x1000 * PAGE_SIZE = 0x1000000
+            let max_page = 0x7_FFFF_FFFF_u64
+                .checked_sub(code_size_pages)
+                .ok_or_else(|| {
+                    new_error!(
+                        "PIE code region too large ({} pages) for ASLR randomization",
+                        code_size_pages
+                    )
+                })?;
+            let page_number = rng.random_range(min_page..max_page);
+            page_number
+                .checked_mul(PAGE_SIZE_USIZE as u64)
+                .ok_or_else(|| new_error!("ASLR page number overflow"))?
+        };
 
         let mut regions = self.get_memory_regions()?;
 
-        if !is_pie {
-            let code_virt_end = code_virt_base.checked_add(loaded_size).ok_or_else(|| {
-                new_error!(
-                    "Code mapping overflow: base {:#x} + size {:#x}",
+        // Verify the code mapping does not conflict with other mappings
+        // (both non-PIE with declared VA and PIE with randomized ASLR base).
+        let code_virt_end = code_virt_base.checked_add(loaded_size).ok_or_else(|| {
+            new_error!(
+                "Code mapping overflow: base {:#x} + size {:#x}",
+                code_virt_base,
+                loaded_size
+            )
+        })?;
+        for rgn in regions.iter() {
+            if rgn.region_type == MemoryRegionType::Code {
+                continue;
+            }
+            let rgn_start = rgn.guest_region.start as u64;
+            let rgn_end = rgn_start.saturating_add(rgn.guest_region.len() as u64);
+            if code_virt_base < rgn_end && rgn_start < code_virt_end {
+                return Err(new_error!(
+                    "Code mapping [{:#x}, {:#x}) conflicts with {:?} region [{:#x}, {:#x})",
                     code_virt_base,
-                    loaded_size
-                )
-            })?;
-            for rgn in regions.iter() {
-                if rgn.region_type == MemoryRegionType::Code {
-                    continue;
-                }
-                let rgn_start = rgn.guest_region.start as u64;
-                let rgn_end = rgn_start + rgn.guest_region.len() as u64;
-                if code_virt_base < rgn_end && rgn_start < code_virt_end {
-                    return Err(new_error!(
-                        "Non-PIE code mapping [{:#x}, {:#x}) conflicts with {:?} region [{:#x}, {:#x})",
-                        code_virt_base,
-                        code_virt_end,
-                        rgn.region_type,
-                        rgn_start,
-                        rgn_end,
-                    ));
-                }
+                    code_virt_end,
+                    rgn.region_type,
+                    rgn_start,
+                    rgn_end,
+                ));
             }
         }
 
@@ -615,6 +633,13 @@ impl SandboxMemoryLayout {
             }
         }
 
+        tracing::debug!(
+            code_virt_base = format_args!("{:#x}", code_virt_base),
+            elf_base_va = format_args!("{:#x}", elf_base_va),
+            is_pie,
+            "code region virtual base address"
+        );
+
         Ok((code_virt_base, regions))
     }
 
@@ -741,6 +766,9 @@ impl SandboxMemoryLayout {
     }
 
     /// Guest address of the code section in the sandbox.
+    /// Used by WHP (Windows) and mem_profile feature; not called on
+    /// minimal Linux feature sets, hence the allow.
+    #[allow(dead_code)]
     pub(crate) fn get_guest_code_address(&self) -> usize {
         Self::BASE_ADDRESS + self.guest_code_offset()
     }

src/hyperlight_host/src/sandbox/initialized_multi_use.rs

@@ -2010,9 +2010,12 @@ mod tests {
     /// `read_guest_memory_by_gva`, then assert both views are identical.
     #[cfg(feature = "trace_guest")]
     fn assert_gva_read_matches(sbox: &mut MultiUseSandbox, gva: u64, len: usize) {
-        // Guest reads via its own page tables
+        // Guest reads via its own page tables.
+        // do_map = false: the code region is already mapped (identity-mapped
+        // or ASLR-mapped), so we must not remap it with an identity mapping
+        // that would use the GVA as a physical address.
         let expected: Vec<u8> = sbox
-            .call("ReadMappedBuffer", (gva, len as u64, true))
+            .call("ReadMappedBuffer", (gva, len as u64, false))
             .unwrap();
         assert_eq!(expected.len(), len);
 
@@ -2036,7 +2039,7 @@ mod tests {
     #[cfg(feature = "trace_guest")]
     fn read_guest_memory_by_gva_single_page() {
         let mut sbox = sandbox_for_gva_tests();
-        let code_gva = sbox.mem_mgr.layout.get_guest_code_address() as u64;
+        let code_gva = sbox.mem_mgr.code_virt_base;
         assert_gva_read_matches(&mut sbox, code_gva, 128);
     }
 
@@ -2046,7 +2049,7 @@ mod tests {
     #[cfg(feature = "trace_guest")]
     fn read_guest_memory_by_gva_full_page() {
         let mut sbox = sandbox_for_gva_tests();
-        let code_gva = sbox.mem_mgr.layout.get_guest_code_address() as u64;
+        let code_gva = sbox.mem_mgr.code_virt_base;
         assert_gva_read_matches(&mut sbox, code_gva, 4096);
     }
 
@@ -2056,7 +2059,7 @@ mod tests {
     #[cfg(feature = "trace_guest")]
     fn read_guest_memory_by_gva_unaligned_cross_page() {
         let mut sbox = sandbox_for_gva_tests();
-        let code_gva = sbox.mem_mgr.layout.get_guest_code_address() as u64;
+        let code_gva = sbox.mem_mgr.code_virt_base;
         // Start 1 byte before the second page boundary and read 4097 bytes
         // (spans 2 full page boundaries).
         let start = code_gva + 4096 - 1;
@@ -2072,7 +2075,7 @@ mod tests {
     #[cfg(feature = "trace_guest")]
     fn read_guest_memory_by_gva_two_full_pages() {
         let mut sbox = sandbox_for_gva_tests();
-        let code_gva = sbox.mem_mgr.layout.get_guest_code_address() as u64;
+        let code_gva = sbox.mem_mgr.code_virt_base;
         assert_gva_read_matches(&mut sbox, code_gva, 4096 * 2);
     }
 
@@ -2083,7 +2086,7 @@ mod tests {
     #[cfg(feature = "trace_guest")]
     fn read_guest_memory_by_gva_cross_page_boundary() {
         let mut sbox = sandbox_for_gva_tests();
-        let code_gva = sbox.mem_mgr.layout.get_guest_code_address() as u64;
+        let code_gva = sbox.mem_mgr.code_virt_base;
         // Start 100 bytes before the first page boundary, read across it.
         let start = code_gva + 4096 - 100;
         assert_gva_read_matches(&mut sbox, start, 200);

src/hyperlight_host/src/sandbox/snapshot/file/config.rs

@@ -483,53 +483,31 @@ impl OciSnapshotConfig {
             }
         }
 
-        // The saved dispatch entrypoint must be in the executable code
-        // region. Code occupies the page-rounded prefix of the snapshot.
-        let code_lo = SandboxMemoryLayout::BASE_ADDRESS as u64;
-        let code_hi = code_lo
-            .checked_add(self.layout.code_size.next_multiple_of(PAGE_SIZE) as u64)
-            .ok_or_else(|| {
-                crate::new_error!(
-                    "snapshot layout overflow: BASE_ADDRESS + code_size ({}) does not fit in u64",
-                    self.layout.code_size
-                )
-            })?;
-        if self.entrypoint_addr < code_lo || self.entrypoint_addr >= code_hi {
+        // Validate the entrypoint GVA.
+        // `entrypoint_addr` is a GVA loaded into RIP. For ASLR or non-PIE
+        // guests the code may be mapped at a non-identity VA, so we only
+        // require the address is non-zero and within the 47-bit canonical
+        // user-space range.
+        let max_gva_entrypoint = 0x7FFF_FFFF_FFFFu64; // 47-bit canonical
+        if self.entrypoint_addr == 0 || self.entrypoint_addr > max_gva_entrypoint {
             return Err(crate::new_error!(
-                "snapshot entrypoint addr {:#x} is outside the code region [{:#x}, {:#x})",
+                "snapshot entrypoint addr {:#x} is outside the valid GVA range (0, {:#x}]",
                 self.entrypoint_addr,
-                code_lo,
-                code_hi
-            ));
-        }
-        #[cfg(target_arch = "aarch64")]
-        if !self.entrypoint_addr.is_multiple_of(4) {
-            return Err(crate::new_error!(
-                "snapshot entrypoint addr {:#x} is not 4-byte aligned",
-                self.entrypoint_addr
+                max_gva_entrypoint
             ));
         }
 
         // ELF entry point GVA for `AT_ENTRY` in core dumps. 0 means
-        // unknown. Any other value must point inside the snapshot
-        // region, like `entrypoint_addr`.
-        let snapshot_hi = code_lo
-            .checked_add(self.layout.snapshot_size as u64)
-            .ok_or_else(|| {
-                crate::new_error!(
-                    "snapshot layout overflow: BASE_ADDRESS + snapshot_size ({}) does not fit in u64",
-                    self.layout.snapshot_size
-                )
-            })?;
-        if self.original_entrypoint_addr != 0
-            && (self.original_entrypoint_addr < code_lo
-                || self.original_entrypoint_addr >= snapshot_hi)
+        // unknown. Any other value must be within the 47-bit canonical
+        // user-space range (same as entrypoint_addr), since with ASLR
+        // or non-PIE the entry point may not be inside the snapshot
+        // physical region.
+        if self.original_entrypoint_addr != 0 && self.original_entrypoint_addr > max_gva_entrypoint
         {
             return Err(crate::new_error!(
-                "snapshot original entrypoint addr {:#x} is outside the snapshot region [{:#x}, {:#x})",
+                "snapshot original entrypoint addr {:#x} is outside the valid GVA range (0, {:#x}]",
                 self.original_entrypoint_addr,
-                code_lo,
-                snapshot_hi
+                max_gva_entrypoint
             ));
         }
 

src/hyperlight_host/src/sandbox/snapshot/file_tests.rs

@@ -25,7 +25,6 @@ use serde_json::Value;
 use sha2::{Digest as _, Sha256};
 
 use crate::func::Registerable;
-use crate::mem::layout::SandboxMemoryLayout;
 use crate::sandbox::snapshot::{OciDigest, OciReference, OciTag, Snapshot};
 use crate::{GuestBinary, HostFunctions, MultiUseSandbox, UninitializedSandbox};
 
@@ -2034,14 +2033,11 @@ fn original_entrypoint_addr_zero_accepted() {
 }
 
 #[test]
-fn entrypoint_addr_outside_code_rejected() {
+fn entrypoint_addr_outside_canonical_range_rejected() {
     let (_dir, path) = save_for_mutation();
     rewrite_config(&path, |cfg| {
-        let code_size = cfg["layout"]["code_size"].as_u64().unwrap();
-        let page_size = hyperlight_common::vmem::PAGE_SIZE as u64;
-        let peb_addr =
-            SandboxMemoryLayout::BASE_ADDRESS as u64 + code_size.next_multiple_of(page_size);
-        cfg["entrypoint_addr"] = Value::from(peb_addr);
+        // 0x8000_0000_0000 is just above the 47-bit canonical limit
+        cfg["entrypoint_addr"] = Value::from(0x8000_0000_0000u64);
     });
     let err = unwrap_err_snapshot(Snapshot::checked_load(
         &path,

src/hyperlight_host/src/sandbox/snapshot/mod.rs

@@ -339,7 +339,6 @@ impl Snapshot {
             guest_blob_mem_flags,
         )?;
 
-        let load_addr = layout.get_guest_code_address() as u64;
         let base_va = exe_info.base_va();
         let entrypoint_va: u64 = exe_info.entrypoint().into();
         let loaded_size = exe_info.loaded_size() as u64;
@@ -354,7 +353,7 @@ impl Snapshot {
         let mut memory = vec![0; layout.get_memory_size()?];
 
         let load_info = exe_info.load(
-            load_addr.try_into()?,
+            code_virt_base.try_into()?,
             &mut memory[layout.guest_code_offset()..],
         )?;
 
@@ -412,7 +411,15 @@ impl Snapshot {
             )
         })?;
 
-        let entrypoint_gva = code_virt_base + entrypoint_offset;
+        let entrypoint_gva = code_virt_base
+            .checked_add(entrypoint_offset)
+            .ok_or_else(|| {
+                crate::new_error!(
+                    "Entrypoint overflow: code_virt_base {:#x} + offset {:#x}",
+                    code_virt_base,
+                    entrypoint_offset
+                )
+            })?;
 
         Ok(Self {
             memory: ReadonlySharedMemory::from_bytes(&memory, layout.snapshot_size())?,
@@ -670,6 +677,12 @@ impl Snapshot {
         self.original_entrypoint
     }
 
+    /// Returns the virtual base address of the code region in guest space.
+    #[allow(dead_code)]
+    pub(crate) fn code_virt_base(&self) -> u64 {
+        self.code_virt_base
+    }
+
     /// Validate that `provided` is a superset of the host functions
     /// recorded in this snapshot: every function that was registered
     /// at snapshot time must also be present in `provided` with a