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

@@ -675,10 +675,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];
@@ -1505,6 +1504,7 @@ mod tests {
             ro_mem.to_mgr_snapshot_mem().unwrap(),
             scratch_mem,
             NextAction::Initialise(layout.get_guest_code_address() as u64),
+            layout.get_guest_code_address() as u64,
         );
 
         let (mut hshm, gshm) = mem_mgr.build().unwrap();

src/hyperlight_host/src/mem/layout.rs

@@ -562,41 +562,78 @@ impl SandboxMemoryLayout {
     /// the virtual base equals the physical load address and no conflict
     /// is possible by construction.
     ///
-    /// 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.
+    /// Determine the virtual base address of the code region.
+    ///
+    /// 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`).
+    ///
+    /// In both cases the resulting virtual range is validated against all
+    /// non-Code memory regions to prevent overlap.
     pub(crate) fn code_virt_base(
         &self,
         is_pie: bool,
         elf_base_va: u64,
         loaded_size: u64,
     ) -> Result<u64> {
-        let load_addr = self.get_guest_code_address() as u64;
-        let virt_base = if is_pie { load_addr } else { elf_base_va };
-
-        if !is_pie {
-            let code_virt_end = virt_base + loaded_size;
-            for rgn in self.get_memory_regions_::<GuestMemoryRegion>(())?.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 virt_base < rgn_end && rgn_start < code_virt_end {
-                    return Err(new_error!(
-                        "Non-PIE code mapping [{:#x}, {:#x}) conflicts with {:?} region [{:#x}, {:#x})",
-                        virt_base,
-                        code_virt_end,
-                        rgn.region_type,
-                        rgn_start,
-                        rgn_end,
-                    ));
-                }
+        let code_size_pages = loaded_size.div_ceil(PAGE_SIZE_USIZE as u64);
+        let 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"))?
+        };
+
+        // 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 = virt_base.checked_add(loaded_size).ok_or_else(|| {
+            new_error!(
+                "Code mapping overflow: base {:#x} + size {:#x}",
+                virt_base,
+                loaded_size
+            )
+        })?;
+        for rgn in self.get_memory_regions_::<GuestMemoryRegion>(())?.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 virt_base < rgn_end && rgn_start < code_virt_end {
+                return Err(new_error!(
+                    "Code mapping [{:#x}, {:#x}) conflicts with {:?} region [{:#x}, {:#x})",
+                    virt_base,
+                    code_virt_end,
+                    rgn.region_type,
+                    rgn_start,
+                    rgn_end,
+                ));
             }
         }
 
+        tracing::debug!(
+            code_virt_base = format_args!("{:#x}", virt_base),
+            elf_base_va = format_args!("{:#x}", elf_base_va),
+            is_pie,
+            "code region virtual base address"
+        );
+
         Ok(virt_base)
     }
 
@@ -723,6 +760,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/mem/mgr.rs

@@ -150,6 +150,8 @@ pub(crate) struct SandboxMemoryManager<S: SharedMemory> {
     /// restored snapshot's own generation number so the guest-visible
     /// counter tracks which snapshot the sandbox is a clone of.
     pub(crate) snapshot_count: u64,
+    /// Virtual base address of the code region in guest space
+    pub(crate) code_virt_base: u64,
 }
 
 /// Buffer for building guest page tables during snapshot creation.
@@ -276,6 +278,7 @@ where
         shared_mem: SnapshotSharedMemory<S>,
         scratch_mem: S,
         entrypoint: NextAction,
+        code_virt_base: u64,
     ) -> Self {
         Self {
             layout,
@@ -284,6 +287,7 @@ where
             entrypoint,
             abort_buffer: Vec::new(),
             snapshot_count: 0,
+            code_virt_base,
         }
     }
 
@@ -316,6 +320,7 @@ where
             entrypoint,
             self.snapshot_count,
             host_functions,
+            self.code_virt_base,
         )
     }
 }
@@ -326,7 +331,8 @@ impl SandboxMemoryManager<ExclusiveSharedMemory> {
         let shared_mem = s.memory().to_mgr_snapshot_mem()?;
         let scratch_mem = ExclusiveSharedMemory::new(s.layout().get_scratch_size())?;
         let entrypoint = s.entrypoint();
-        let mut mgr = Self::new(layout, shared_mem, scratch_mem, entrypoint);
+        let code_virt_base = s.code_virt_base();
+        let mut mgr = Self::new(layout, shared_mem, scratch_mem, entrypoint, code_virt_base);
         // Inherit the snapshot's generation number for the same
         // reason `restore_snapshot` does: the guest-visible counter
         // reflects "which snapshot is the sandbox currently a clone
@@ -360,6 +366,7 @@ impl SandboxMemoryManager<ExclusiveSharedMemory> {
             entrypoint: self.entrypoint,
             abort_buffer: self.abort_buffer,
             snapshot_count: self.snapshot_count,
+            code_virt_base: self.code_virt_base,
         };
         let guest_mgr = SandboxMemoryManager {
             shared_mem: gshm,
@@ -368,6 +375,7 @@ impl SandboxMemoryManager<ExclusiveSharedMemory> {
             entrypoint: self.entrypoint,
             abort_buffer: Vec::new(), // Guest doesn't need abort buffer
             snapshot_count: self.snapshot_count,
+            code_virt_base: self.code_virt_base,
         };
         host_mgr.update_scratch_bookkeeping()?;
         Ok((host_mgr, guest_mgr))

src/hyperlight_host/src/sandbox/initialized_multi_use.rs

@@ -1971,9 +1971,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);
 
@@ -1997,7 +2000,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);
     }
 
@@ -2007,7 +2010,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);
     }
 
@@ -2017,7 +2020,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;
@@ -2033,7 +2036,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);
     }
 
@@ -2044,7 +2047,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

@@ -456,27 +456,17 @@ impl OciSnapshotConfig {
             }
         }
 
-        // Entrypoint address must point inside the guest snapshot
-        // region `[BASE_ADDRESS, BASE_ADDRESS + snapshot_size)`. The
-        // address is a GVA, bounded by the same range because guests
-        // identity-map the snapshot region at low VAs. A guest
-        // dispatching from a non-identity-mapped VA must relax this
-        // check.
-        let snap_lo = SandboxMemoryLayout::BASE_ADDRESS as u64;
-        let snap_hi = snap_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.entrypoint_addr < snap_lo || self.entrypoint_addr >= snap_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 snapshot region [{:#x}, {:#x})",
+                "snapshot entrypoint addr {:#x} is outside the valid GVA range (0, {:#x}]",
                 self.entrypoint_addr,
-                snap_lo,
-                snap_hi
+                max_gva_entrypoint
             ));
         }
 

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

@@ -871,6 +871,12 @@ impl Snapshot {
             load_info: crate::mem::exe::LoadInfo::dummy(),
             stack_top_gva: cfg.stack_top_gva,
             sregs: Some(cfg.sregs),
+            // TODO(#1655): File-snapshot format doesn't persist code_virt_base.
+            // This is acceptable because file snapshots currently pre-date
+            // ASLR and always use identity-mapped code (VA == GPA).  If file
+            // snapshots ever need to round-trip through an ASLR sandbox, the
+            // format must be extended to include code_virt_base.
+            code_virt_base: 0,
             entrypoint,
             snapshot_generation,
             host_functions,