Skip to content

host: make the policy-file reader and the mount syntax private to the CLI (SL6.7b) #1539

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Pedro Henrique Penna (ppenna) merged 2 commits into from
Nov 12, 2026
Merged

host: make the policy-file reader and the mount syntax private to the CLI (SL6.7b) #1539

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e48c68c
tests: check the policy reader and the mount syntax through the CLI
ppenna Nov 12, 2026
484e0c7
host: make the policy-file reader and the mount syntax private to the…
ppenna Nov 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 23 additions & 38 deletions nvx-rs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,13 +115,11 @@ changes only when the module's purpose does.
| [`nvx::host::config`](#nvxhostconfig) | `VmConfig` and `CaptureConfig`: pure configuration, cold-boot kernel/OpenVMM arguments, portable length checks, and capture identity |
| [`nvx::host::restore`](#nvxhostrestore) | A caller-driven restore to Ready without I/O or a clock, and its peer-verified restore-ready listener |
| [`nvx::host::network`](#nvxhostnetwork) | The one lowering of a network posture into OpenVMM options, for the CLI and external orchestrators |
| [`nvx::host::network::policy`](#nvxhostnetworkpolicy) | Egress policy files and their compilation into OpenVMM's native rules |
| [`nvx::host::filesystem`](#nvxhostfilesystem) | The planner of the host paths that every NVX caller exports to the guest through OpenVMM's virtio-fs device |
| [`nvx::host::nvxs`](#nvxhostnvxs) | Compatibility paths for the host NVXS connection and its retained cause details |
| [`nvx::host::transport`](#nvxhosttransport) | A verified VM endpoint connection and the blocking host NVXS driver, with the existing timed transport |
| [`nvx::host::process`](#nvxhostprocess) | Verified references to OpenVMM processes, through which callers wait for them and end them |
| [`nvx::host::report`](#nvxhostreport) | OpenVMM's outcome report |
| [`nvx::host::sandbox`](#nvxhostsandbox) | The launch profile of `nvx-rs sandbox`: its live shares and option checks; its layer and bindings are private to the CLI |
| [`nvx::guest`](#nvxguest) | The programs that run in Linux guests; see [Guest binaries](#guest-binaries) |
| [`nvx::guest::mappings`](#nvxguestmappings) | `Mapping` and `MappingTable`: host mappings, and the account of a host's mapping table, for any guest init or agent |
| [`nvx::guest::nvxs`](#nvxguestnvxs) | `GuestConnection`: the guest's role of the NVXS session over a byte stream, such as the control console |
Expand Down Expand Up @@ -936,12 +934,6 @@ lowering of egress policy files, with at most 256 rules for each action.
the host, and fails with an `Unsupported` error for a malformed rule or for an
action that needs more than 256 rules.

### `nvx::host::network::policy`

Egress policy files: `compile_policy_file`, `compile_policy_bytes`, and
`compile_policy` compile one to a `CompiledEgressPolicy` of native rules; see
[Egress policy files](#egress-policy-files).

### `nvx::host::filesystem`

The planner of every NVX caller: `plan` turns an `ExportRequest`, the mapped
Expand Down Expand Up @@ -1063,31 +1055,6 @@ unreadable or malformed report, retaining the underlying error. It keeps today's
summary of the outcome category, status code and teardown steps, not free-form
fields.

### `nvx::host::sandbox`

The launch profile of `nvx-rs sandbox`, with native input validation: the
workload identity that `--workload-user` names, the live shares, and the checks
of the options. The image staging of the profile is private to the crate, for
the CLI (feature `cli`): `layer`'s `SandboxLayer`, the distro layer of a
sandbox, an EROFS layer or a GPT disk, the one layer that a sandbox takes;
`distro`'s `DistroBinding` of the layer, which explicit verification makes, and
its check from metadata alone; `scratch`'s `ScratchBinding` of a scratch image,
its identity, kind, and length, and its check from metadata alone, which claims
the image for one sandbox at a time; and the seals of `nvx::host`'s private
`seal`, which they record. See [Distro bindings](#distro-bindings) and
[Images by path](#images-by-path).

`mount`: `SandboxMount` requests of live shares of host directories and files,
their guest targets and the reserved ones, their access policies and owner, and
the checks of their host paths; and `plan_mounts`, which plans them through
`nvx::host::filesystem` for the container root.

`options`: the checks that `nvx-rs sandbox` and `nvx-rs run` apply to their
options: the attribution of `--mount-deny`, `--mount-allow`, and `--mount-write`
to shares, the systemd entrypoint check and the explicit verification of the
distro layer, the targets of `nvx-rs run` shares, and the managed exec
environment; see [Sandbox input contract](#sandbox-input-contract).

### `nvx::guest`

The programs that run in Linux guests; see [Guest binaries](#guest-binaries).
Expand Down Expand Up @@ -1342,9 +1309,11 @@ cloned, and formats none of them. `nvx-reseed` runs them.

## Egress policy files

`nvx::host::network::policy` compiles the egress policy files that
`nvx-rs run` and `nvx-rs sandbox` take with `--network-egress-policy-file`
([format](../doc/run.md#run-openvmm-directly)). It replaced the former
The crate's private `host::network::policy`, which only the CLI builds (feature
`cli`), compiles the egress policy files that `nvx-rs run` and `nvx-rs sandbox`
take with `--network-egress-policy-file`
([format](../doc/run.md#run-openvmm-directly)), and whose rules
[`egress compile`](#egress-compile-path) prints. It replaced the former
`scripts/nvx_tools/egress_policy.py` when `nvx.py` delegated to `nvx-rs`, and
compiles the policies that it compiled to the same rules, but reads policy
files as strict JSON
Expand Down Expand Up @@ -1537,6 +1506,22 @@ does, and holds the claim until its VM exits. A sandbox whose upper is in RAM,
and its binding, and neither `start` nor `run` binds or claims one.
## Sandbox input contract

The crate's private `host::sandbox` is the launch profile of `nvx-rs sandbox`,
which only the CLI uses (feature `cli`), but for the block geometry that
`nvx::host::vm` and `nvx::host::snapshot` read and the tag of the shares'
virtio-fs device, which a snapshot's key names: the workload identity that
`--workload-user` names; the live shares of `--mount`, their guest targets and
the reserved ones, their access policies and owner, and the checks of their
host paths, which it plans through `nvx::host::filesystem` for the container
root; and the checks that `nvx-rs sandbox` and `nvx-rs run` apply to their
options: the attribution of `--mount-deny`, `--mount-allow`, and `--mount-write`
to shares, the systemd entrypoint check and the explicit verification of the
distro layer, the targets of `nvx-rs run` shares, and the managed exec
environment. Its image staging, the `layer`, the `distro` and `scratch`
bindings, and the seals of the private `host::seal` that they record, is
described in [Distro bindings](#distro-bindings) and
[Images by path](#images-by-path).

The sandbox launch profile specifies its own inputs rather than emulating Python.
A UID or GID contains only ASCII decimal digits, without signs, whitespace,
underscores, or Unicode digits, and is in `1..4294967294`. A layer UUID is
Expand Down Expand Up @@ -2847,8 +2832,8 @@ own facilities replaced it:
through their links, on Linux and Windows, and those of the scratch image
and of the export planner that paths that are not valid Unicode are refused.

The sandbox specification tests, those of `nvx::host::sandbox`, specify the
documented option grammar. Properties cover canonical layer UUIDs, reserved
The sandbox specification tests, those of the private `host::sandbox`, specify
the documented option grammar. Properties cover canonical layer UUIDs, reserved
targets, policy option sequences, and paths on the host's own filesystem. They check
that a launch refuses both systemd entrypoints whatever the distro layer's
manifest lists, and that verification refuses a manifest that lists `systemd`
Expand Down
132 changes: 0 additions & 132 deletions nvx-rs/public-api/linux.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1079,16 +1079,6 @@ variant nvx::host::network::ProxyScheme::Https
method nvx::host::network::ProxyScheme::as_str
method nvx::host::network::ProxyScheme::from_name
fn nvx::host::network::openvmm_arguments
mod nvx::host::network::policy
struct nvx::host::network::policy::CompiledEgressPolicy
field nvx::host::network::policy::CompiledEgressPolicy::allow
field nvx::host::network::policy::CompiledEgressPolicy::deny
const nvx::host::network::policy::MAX_JSON_DEPTH
const nvx::host::network::policy::MAX_POLICY_FILE_SIZE
const nvx::host::network::policy::MAX_RULES_PER_ACTION
fn nvx::host::network::policy::compile_policy
fn nvx::host::network::policy::compile_policy_bytes
fn nvx::host::network::policy::compile_policy_file
mod nvx::host::nvxs
struct nvx::host::nvxs::HostConnection
method nvx::host::nvxs::HostConnection::attach
Expand Down Expand Up @@ -1267,128 +1257,6 @@ field nvx::host::runtime::RuntimeIdentity::kernel
method nvx::host::runtime::RuntimeIdentity::new
field nvx::host::runtime::RuntimeIdentity::openvmm
fn nvx::host::runtime::probe_hypervisor
mod nvx::host::sandbox
const nvx::host::sandbox::DEFAULT_ENTRYPOINT
const nvx::host::sandbox::DEFAULT_HOSTNAME
const nvx::host::sandbox::DEFAULT_WORKLOAD_IDENTITY
enum nvx::host::sandbox::MountAccess
variant nvx::host::sandbox::MountAccess::ReadOnly
variant nvx::host::sandbox::MountAccess::ReadWrite
method nvx::host::sandbox::MountAccess::as_str
enum nvx::host::sandbox::MountKind
variant nvx::host::sandbox::MountKind::Directory
variant nvx::host::sandbox::MountKind::File
method nvx::host::sandbox::MountKind::as_str
enum nvx::host::sandbox::MountOwner
variant nvx::host::sandbox::MountOwner::Caller
variant nvx::host::sandbox::MountOwner::Vmm
method nvx::host::sandbox::MountOwner::as_str
struct nvx::host::sandbox::MountPolicy
field nvx::host::sandbox::MountPolicy::allowed
field nvx::host::sandbox::MountPolicy::denied
method nvx::host::sandbox::MountPolicy::is_empty
method nvx::host::sandbox::MountPolicy::paths
field nvx::host::sandbox::MountPolicy::writable
enum nvx::host::sandbox::PolicyKind
variant nvx::host::sandbox::PolicyKind::Allowed
variant nvx::host::sandbox::PolicyKind::Denied
variant nvx::host::sandbox::PolicyKind::Writable
method nvx::host::sandbox::PolicyKind::as_str
method nvx::host::sandbox::PolicyKind::option
struct nvx::host::sandbox::SandboxMount
method nvx::host::sandbox::SandboxMount::host_path
method nvx::host::sandbox::SandboxMount::new
method nvx::host::sandbox::SandboxMount::parse
method nvx::host::sandbox::SandboxMount::validated
method nvx::host::sandbox::SandboxMount::with_kind
mod nvx::host::sandbox::mount
const nvx::host::sandbox::mount::AGGREGATE_MOUNT_TARGET
const nvx::host::sandbox::mount::MAX_MOUNT_POLICY_PATHS
const nvx::host::sandbox::mount::MAX_MOUNT_TARGET_BYTES
const nvx::host::sandbox::mount::MOUNT_TAG
enum nvx::host::sandbox::mount::MountAccess
variant nvx::host::sandbox::mount::MountAccess::ReadOnly
variant nvx::host::sandbox::mount::MountAccess::ReadWrite
method nvx::host::sandbox::mount::MountAccess::as_str
enum nvx::host::sandbox::mount::MountKind
variant nvx::host::sandbox::mount::MountKind::Directory
variant nvx::host::sandbox::mount::MountKind::File
method nvx::host::sandbox::mount::MountKind::as_str
enum nvx::host::sandbox::mount::MountOwner
variant nvx::host::sandbox::mount::MountOwner::Caller
variant nvx::host::sandbox::mount::MountOwner::Vmm
method nvx::host::sandbox::mount::MountOwner::as_str
struct nvx::host::sandbox::mount::MountPolicy
field nvx::host::sandbox::mount::MountPolicy::allowed
field nvx::host::sandbox::mount::MountPolicy::denied
method nvx::host::sandbox::mount::MountPolicy::is_empty
method nvx::host::sandbox::mount::MountPolicy::paths
field nvx::host::sandbox::mount::MountPolicy::writable
const nvx::host::sandbox::mount::POLICY_KINDS
enum nvx::host::sandbox::mount::PolicyKind
variant nvx::host::sandbox::mount::PolicyKind::Allowed
variant nvx::host::sandbox::mount::PolicyKind::Denied
variant nvx::host::sandbox::mount::PolicyKind::Writable
method nvx::host::sandbox::mount::PolicyKind::as_str
method nvx::host::sandbox::mount::PolicyKind::option
const nvx::host::sandbox::mount::RESERVED_EXACT_MOUNT_TARGETS
const nvx::host::sandbox::mount::RESERVED_MOUNT_TARGETS
struct nvx::host::sandbox::mount::SandboxMount
method nvx::host::sandbox::mount::SandboxMount::host_path
method nvx::host::sandbox::mount::SandboxMount::new
method nvx::host::sandbox::mount::SandboxMount::parse
method nvx::host::sandbox::mount::SandboxMount::validated
method nvx::host::sandbox::mount::SandboxMount::with_kind
fn nvx::host::sandbox::mount::mount_kind
fn nvx::host::sandbox::mount::parse_mount_value
fn nvx::host::sandbox::mount::plan_mounts
fn nvx::host::sandbox::mount::require_mount_owner_supported
fn nvx::host::sandbox::mount::validate_mount_host_paths
fn nvx::host::sandbox::mount::validate_mount_target
fn nvx::host::sandbox::mount::validate_mounts
mod nvx::host::sandbox::options
const nvx::host::sandbox::options::MAX_ENVIRONMENT_FILE_BYTES
const nvx::host::sandbox::options::MAX_EXEC_ENVIRONMENT
const nvx::host::sandbox::options::MAX_EXEC_ENVIRONMENT_BYTES
struct nvx::host::sandbox::options::PolicyPathOption
field nvx::host::sandbox::options::PolicyPathOption::kind
field nvx::host::sandbox::options::PolicyPathOption::path
field nvx::host::sandbox::options::PolicyPathOption::preceding_mount
const nvx::host::sandbox::options::SYSTEMD_ENTRYPOINTS
enum nvx::host::sandbox::options::SandboxOperation
variant nvx::host::sandbox::options::SandboxOperation::Deprovision
variant nvx::host::sandbox::options::SandboxOperation::Exec
variant nvx::host::sandbox::options::SandboxOperation::Provision
variant nvx::host::sandbox::options::SandboxOperation::Run
variant nvx::host::sandbox::options::SandboxOperation::Start
variant nvx::host::sandbox::options::SandboxOperation::Stop
method nvx::host::sandbox::options::SandboxOperation::as_str
struct nvx::host::sandbox::options::SandboxOptions
method nvx::host::sandbox::options::SandboxOptions::check
field nvx::host::sandbox::options::SandboxOptions::cwd
field nvx::host::sandbox::options::SandboxOptions::dry_run
field nvx::host::sandbox::options::SandboxOptions::entrypoint
field nvx::host::sandbox::options::SandboxOptions::environment
field nvx::host::sandbox::options::SandboxOptions::environment_file
field nvx::host::sandbox::options::SandboxOptions::inherit_default_environment
field nvx::host::sandbox::options::SandboxOptions::layers
field nvx::host::sandbox::options::SandboxOptions::mount_owner
field nvx::host::sandbox::options::SandboxOptions::mounts
field nvx::host::sandbox::options::SandboxOptions::net
field nvx::host::sandbox::options::SandboxOptions::network_options
field nvx::host::sandbox::options::SandboxOptions::network_profile
field nvx::host::sandbox::options::SandboxOptions::operation
field nvx::host::sandbox::options::SandboxOptions::outcome_report
field nvx::host::sandbox::options::SandboxOptions::policy_paths
field nvx::host::sandbox::options::SandboxOptions::scratch
field nvx::host::sandbox::options::SandboxOptions::upper
fn nvx::host::sandbox::options::exec_environment_from_file
fn nvx::host::sandbox::options::sandbox_mounts
fn nvx::host::sandbox::options::validate_exec_environment
fn nvx::host::sandbox::options::validate_run_share_targets
fn nvx::host::sandbox::options::validate_sandbox_entrypoint
fn nvx::host::sandbox::parse_workload_identity
fn nvx::host::sandbox::require_file
mod nvx::host::snapshot
struct nvx::host::snapshot::BlockGeometry
field nvx::host::snapshot::BlockGeometry::length
Expand Down
Loading
Loading