[Pedro Henrique Penna (ppenna)]

Fixes #1001.

doc/run.md and doc/usage.md said that a sandbox policy that "lets nothing through" attaches no network device. nvx::host::network::openvmm_arguments attaches none exactly when a policy has no proxy, denies egress by default without allow rules, and denies ingress and host-loopback access, whatever its deny rules. This names that condition by its options in both documents, as the issue's first option asks, and keeps the behavior.

Based on dev at fbeb563bb. One documentation commit; no code, test, or behavior changes.

Problem and root cause

The documents described the condition by its effect, then listed --network-egress deny without allow rules, ingress denied, and --host-loopback deny. openvmm_arguments tests the policy's options instead (nvx-rs/src/host/network/arguments.rs: no proxy, egress == Deny, allow.rules.is_empty(), ingress == Deny, host_loopback == Deny), so both parts of the description were too broad:

• A policy can let nothing through and still attach a device. On the CLI, --network-egress deny --host-loopback deny with --network-egress-allow 192.0.2.1 and --network-egress-deny 192.0.2.0/24, whose deny rule covers the allow rule, renders --net and both rules. Through the Rust API, a NetworkPolicy whose allow rule excepts its whole destination lowers to no OpenVMM rule but attaches a device, as the issue reports.
• A proxy-only policy has every option that the documents listed, yet attaches a device for its proxy.

The documents also did not say which allow rules count. The CLI compiles a --network-egress-policy-file to native rules before it builds the policy, as nvx-rs/README.md describes, so a file whose allow rules all except their whole destinations leaves no allow rule and attaches no device, while the same rule in a typed policy of the Rust API counts.

Change

Commit	Files	Change
018ea1a34 doc	doc/run.md, doc/usage.md	Names the condition by its options in the Sandbox networking section of doc/run.md, in its note on what changed since earlier releases, and in the --net row of the sandbox options in doc/usage.md: --network-egress deny and --host-loopback deny, without allow rules, --network-ingress allow, or --network-proxy, whatever the deny rules. Says that a policy file's allow rules are those that it compiles to, that any other policy attaches a device even if it lets nothing through, with an example, and that the typed policy of the Rust API counts every allow rule.

Why documentation rather than a behavior change

The issue offers two fixes: name the condition by its options, or also attach no device for a policy whose allow rules lower to no OpenVMM rule, "which also changes the template key of such a policy". This takes the first, the conservative one:

• It changes no behavior and no template key.
• The open template stack, nvx-rs: give each network policy a template of its own, and start network clones #958 and the pull requests above it, derives template keys from this lowering, and nvx-rs: give each network policy a template of its own, and start network clones #958 defines the device of a closed policy (attached_arguments) as the one that the same policy gets with one more allow rule that lowers to no OpenVMM rule. nvx-rs: per-clone network policies on deny-all templates #978, later in that stack, keeps openvmm_arguments's condition unchanged, so the documented condition stays accurate when the stack lands.
• The CLI never reaches the second option's case: its rules are native, and a policy file's are compiled before the policy is built.

The behavior change can still follow as its own issue once the template stack has landed, if maintainers want it.

Validation

• Base: dev at fbeb563bb29adf085184227fde46deed29def40f. Head: 018ea1a34dc54cfeb323ee81a63dd806b1665efc, signed.

• Reproduced on dev at the base, on Windows, before changing anything, with scratch tests that are not committed:

  • A unit test of openvmm_arguments for 10.0.0.2/24: no arguments for a deny-all policy, with or without a deny rule; --net and the portable profile for an allow rule whose except covers its whole cidr, with no --network-egress-allow rendered; for an allow rule that a deny rule covers; for a proxy-only policy; and for a deny-all policy with host-loopback access Outbound, the CLI's default without --host-loopback.
  • Three nvx-rs sandbox run --dry-run cases in the harness of nvx-rs/tests/cli/dry_run.rs: --network-egress deny --host-loopback deny alone renders no network option; adding --network-egress-allow 192.0.2.1 --network-egress-deny 192.0.2.0/24 renders --net and both rules; and a --network-egress-policy-file whose allow rule excepts its whole destination renders no network option.
  • nvx-rs egress compile of that policy file prints {"allow": [], "deny": []}.

• At the head, on Windows: python scripts\check_markdown_links.py; python -m compileall -q scripts; and python -m unittest scripts/test_nvx_tools.py scripts/test_markdown_links.py scripts/test_performance.py with NVX_RS set to a release nvx-rs built at the base (732 tests, OK, 34 skipped). They include test_usage_documents_every_option_of_nvx_rs, which checks that the sandbox section of doc/usage.md names exactly the options of nvx-rs sandbox --help.

• Hosts: none, since the change is documentation only and changes no runtime behavior.

  Host profile	Backend	Host type	Result
  none	n/a	n/a	Not applicable: no runtime behavior changes

• CI: run 40892621875, attempt 1, passed on head 018ea1a34: Required status check and the 7 other checks that ran succeeded, and the other 29 were skipped, since every path is documentation and the change selects no suite; see Change classification. Nothing is pending.

Follow-ups

• The runtime adapter's README, tests/runtime-adapter/README.md (its Networks section, the NIC rule of its create command, its test inventory, and the network checks of its VM scenarios), uses the same shorthand, as do the rustdoc of SandboxNetwork::openvmm_arguments in nvx-rs/src/host/sandbox/plan.rs and some comments in nvx-rs/src/host/template/, nvx-rs/src/host/sandbox/plan/tests.rs, and tests/runtime-adapter/. They are left alone here: the rustdoc defers to that of openvmm_arguments, which states the exact condition; the comments describe the deny-all policies of their tests, for which the shorthand holds; and ten open pull requests (nvx-rs: serve shorter images, and restore clones in RAM without a scratch file #925, nvx-rs: serve clones of each processor count from one template #926, nvx-rs: export one directory to a template's clone, and map it before its start #955, nvx-rs: give each network policy a template of its own, and start network clones #958, nvx-rs: set a clone's hostname and machine ID for every execution #959, nvx-rs: mount a clone's export and set its network settings #960, runtime-adapter: refresh, list, inspect, and remove template generations #962, runtime-adapter: start and run from a template, and run the stage's scenarios as one suite #963, nvx-rs: per-clone network policies on deny-all templates #978, nvx-rs: aggregate exports for clones #992) edit that README.
• openvmm_arguments returns no arguments for a policy that attaches no device before it parses that policy's deny rules, so through the Rust API it accepts a malformed deny rule there, such as EgressRule::to("not-a-cidr") (Ok([])), although its rustdoc says that it fails for an invalid rule. The CLI is not affected, since it parses each rule with EgressRule::parse_native before it builds the policy.

[Copilot]

🟢 Approval recommended

No active review issues were identified for this documentation-only clarification of when NVX omits a network device.

No open issues 🎉

What changed in this PR

This documentation-only PR addresses #1001 by stating the exact network-policy conditions under which NVX attaches no network device. Runtime behavior and template keys remain unchanged.

Changes:

• Replaces “lets nothing through” with the specific options that omit a network device.
• Clarifies how compiled policy-file allow rules differ from typed Rust API rules.
• Adds an example of a policy that blocks all traffic but still attaches a device.

File	Description
doc/​usage.md	Clarifies device-attachment conditions in the sandbox --net reference.
doc/​run.md	Explains the precise conditions, rule-counting differences, and an example; updates the historical behavior note.

_{Review effort: Balanced}