Adds LibcRngReseedPolicy

[ludfjig]

Adds LibcRngReseedPolicy to configure Hyperlight’s guest libc PRNG:

• Random generates a new host seed during initialization and after every snapshot restore.
• Fixed(u32) uses the supplied seed for reproducible execution.

The policy is stored in snapshots (not sandbox). Restoring a snapshot replaces the sandbox’s configured policy with the snapshot’s policy.

This applies only to rand() and random() from Hyperlight’s bundled libc and guest runtime. Snapshot config and ABI versions are bumped to v2. Existing v1 snapshots are not supported. #1674 already bumps it so breaking isn't bad if we get this is before release

[Copilot]

Pull request overview

This PR adds a new sandbox configuration knob, RngRestorePolicy, to control whether the guest libc PRNG state is preserved from a snapshot or reseeded when restoring/resuming from a snapshot. This fits into the host/guest snapshot/restore flow by using scratch bookkeeping to pass a reseed request from host to guest at restore time.

Changes:

• Add RngRestorePolicy to SandboxConfiguration and thread it into MultiUseSandbox so restore/from-snapshot can optionally request a libc PRNG reseed.
• Add a scratch bookkeeping field (SCRATCH_TOP_LIBC_RNG_SEED_OFFSET) plus guest-side logic to consume it and call srand() before dispatching guest calls.
• Add C-guest-based regression tests validating default preservation and optional reseeding behavior across from_snapshot and restore.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/tests/c_guests/c_simpleguest/main.c	Adds a NextRandom guest export (wrap + register) for testing libc RNG behavior.
src/hyperlight_host/src/sandbox/uninitialized_evolve.rs	Threads RNG restore policy into MultiUseSandbox construction.
src/hyperlight_host/src/sandbox/snapshot/file_tests.rs	Adds snapshot/restore tests for libc RNG preservation vs reseeding using the C simple guest.
src/hyperlight_host/src/sandbox/mod.rs	Re-exports RngRestorePolicy from the sandbox module.
src/hyperlight_host/src/sandbox/initialized_multi_use.rs	Implements host-side reseed requests on from_snapshot and restore, plus stores policy in the sandbox.
src/hyperlight_host/src/sandbox/config.rs	Introduces RngRestorePolicy and getters/setters on SandboxConfiguration.
src/hyperlight_host/src/mem/mgr.rs	Adds a scratch bookkeeping write helper for the libc RNG seed and clears it during bookkeeping updates.
src/hyperlight_guest/src/layout.rs	Exposes the guest virtual address of the libc RNG seed scratch slot.
src/hyperlight_guest_bin/src/lib.rs	Adds guest-side reseed logic (refresh_libc_rng) and updates initial srand seeding via a shared fold.
src/hyperlight_guest_bin/src/guest_function/call.rs	Calls refresh_libc_rng() on each internal dispatch (libc feature).
src/hyperlight_common/src/layout.rs	Defines the new scratch bookkeeping offset constant.
CHANGELOG.md	Documents the new configuration option in the unreleased changelog.

[syntactically]

However if somebody passes Refresh with an old snapshot it will be silently ignored

I haven't looked at the implementation, but from the description this concerns me a bit. It also feels to me like "whether I need access to actual randomness" is more a semantic property of the guest being run than it is a property of the sandbox, so I wonder if it would make more sense to make it a (persisted) property of the snapshot that the sandbox honours. Snapshots which don't set the rng-needed flag could leave it out of their manifest for backwards compatibility.

I also wonder whether or not there is really any benefit to the current rng initialisation that is shared between everyone. I could imagine that rather than looking at it as "do I need randomness re-initialised on snapshot restore or not", which might be somewhat opaque to users, the semantically simpler thing to consider, which is basically identical, is "do I need randomness at all or not". If we recast the API from that perspective, we could change to having a snapshot-level flag that switches between "not initialising randomness at all (/ideally also erroring if you try to use it)" and "initialising randomness on every restore".

[ludfjig]

However if somebody passes Refresh with an old snapshot it will be silently ignored

I haven't looked at the implementation, but from the description this concerns me a bit. It also feels to me like "whether I need access to actual randomness" is more a semantic property of the guest being run than it is a property of the sandbox, so I wonder if it would make more sense to make it a (persisted) property of the snapshot that the sandbox honours. Snapshots which don't set the rng-needed flag could leave it out of their manifest for backwards compatibility.

Agreed, I made it property of the snapshot now. And made it a break change which should be fine given we get this in before release

I also wonder whether or not there is really any benefit to the current rng initialisation that is shared between everyone. I could imagine that rather than looking at it as "do I need randomness re-initialised on snapshot restore or not", which might be somewhat opaque to users, the semantically simpler thing to consider, which is basically identical, is "do I need randomness at all or not". If we recast the API from that perspective, we could change to having a snapshot-level flag that switches between "not initialising randomness at all (/ideally also erroring if you try to use it)" and "initialising randomness on every restore".

This would be nice, but how does this cover same/different rng for multiple sandboxes from the same snapshot? From each guest's perspective, they both could get randomness, but it might be the same as the other sandbox's