From 2d9423407b64cf5fdf1b48a63fbd7cb0274f1439 Mon Sep 17 00:00:00 2001 From: "gominimal-aw-bot[bot]" <281738952+gominimal-aw-bot[bot]@users.noreply.github.com> Date: Mon, 19 Oct 2026 02:00:18 +0000 Subject: [PATCH 1/7] fix(net): scope the host alias by the host-exposure port list The announced node row carries the frames of every box that shares the guest root namespace, so its reach through the host alias was admitted at every port: the alias opened the host's whole listener surface to a host-address box. The alias is now opened at the host exposures alone -- the inclusive port ranges the host itself exposes over the alias -- and every other port through it is the infrastructure drop for every row. A deployment widens or clears the list with MINVMD_HOST_EXPOSURE_PORTS, read once at VM start; the gate's start-up line names the list in force. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- crates/minvmd/src/net.rs | 8 +- crates/minvmd/src/net/baseline.rs | 196 ++++++++++++++++++++++++++- crates/minvmd/src/net/egress_gate.rs | 107 ++++++++++----- docs/reference/cli-minvmd.md | 2 + 4 files changed, 277 insertions(+), 36 deletions(-) diff --git a/crates/minvmd/src/net.rs b/crates/minvmd/src/net.rs index a82f48220f..3f373b8783 100644 --- a/crates/minvmd/src/net.rs +++ b/crates/minvmd/src/net.rs @@ -794,8 +794,12 @@ impl HostGvproxy { // In force, the gate decides a frame from the daemon's own address // by it, beside the boxes' rows; announced — the shipped posture — // the allow-all interim node row still does, and the gate's - // start-up line names the posture deciding. - let baseline = NodePlaneBaseline::built_in(subnet); + // start-up line names the posture deciding. The host exposures the + // alias is opened at for the node row — the same opening the host + // exposes over the alias — are read from the environment once + // here, at start, an unparseable list failing it. + let baseline = NodePlaneBaseline::built_in(subnet) + .with_host_exposure(baseline::host_exposure_ports_from_env()?); let (stop_tx, stop_rx) = tokio::sync::oneshot::channel::<()>(); let (ready_tx, ready_rx) = std::sync::mpsc::channel::>(); diff --git a/crates/minvmd/src/net/baseline.rs b/crates/minvmd/src/net/baseline.rs index c0abf15cf8..5b852806d6 100644 --- a/crates/minvmd/src/net/baseline.rs +++ b/crates/minvmd/src/net/baseline.rs @@ -33,6 +33,7 @@ //! enumeration by saying it. use boxes::core::egress::{EgressRules, Ipv4Cidr}; +use std::io; use switch::SwitchSubnet; /// A category of the node-plane baseline enumeration: one of the design's @@ -153,6 +154,81 @@ impl NodeBaselinePhase { /// the tests pin both of its arms, so the flip is one line and nothing else. pub(crate) const NODE_BASELINE_PHASE: NodeBaselinePhase = NodeBaselinePhase::Announced; +/// The host-exposure port list the baseline ships: the ranges the design +/// holds for a host's own dev-services plane (design §7.1) — the ports a +/// host's own listener surface answers on and the alias's node-row opening +/// is scoped to, the same opening the host exposes over the alias guest-side +/// (NET-062's third opening). Every other port is refused through the alias +/// for every row. +pub(crate) const DEFAULT_HOST_EXPOSURE_PORTS: [(u16, u16); 5] = [ + (3000, 3999), + (4200, 4200), + (5000, 5999), + (8000, 8999), + (9000, 9999), +]; + +/// The environment variable the daemon's host-exposure port list is read +/// from, once, at VM start — the same read-at-start shape the hostname +/// proxy port and the egress-default opt-out carry. +pub(crate) const HOST_EXPOSURE_PORTS_ENV: &str = "MINVMD_HOST_EXPOSURE_PORTS"; + +/// The host-exposure port list the daemon starts with, as the deployment +/// spelled it: absent, the built-in list; set but empty, a host alias with +/// no opening at all — the list cleared, refused at every port for every +/// row. The list is comma-separated, each term a port (`4200`) or an +/// inclusive range (`3000-3999`); a term that is neither, or a range whose +/// low end sits above its high end, fails the start, the variable naming +/// the term as it was read. +pub(crate) fn host_exposure_ports_from_env() -> io::Result> { + host_exposure_ports_from_raw(std::env::var(HOST_EXPOSURE_PORTS_ENV).ok().as_deref()) +} + +/// Parses one deployment's spelling of the host-exposure port list: every +/// term a port or an inclusive range, whitespace trimmed, an empty list a +/// cleared one — the alias's openings none — rather than the built-in's. +fn host_exposure_ports_from_raw(raw: Option<&str>) -> io::Result> { + let Some(raw) = raw else { + return Ok(DEFAULT_HOST_EXPOSURE_PORTS.to_vec()); + }; + raw.split(',') + .filter(|term| !term.trim().is_empty()) + .map(|term| { + let term = term.trim(); + match term.split_once('-') { + Some((lo, hi)) => { + let lo = lo + .trim() + .parse::() + .map_err(|_| bad_host_exposure_ports(raw, term))?; + let hi = hi + .trim() + .parse::() + .map_err(|_| bad_host_exposure_ports(raw, term))?; + if lo <= hi { + Ok((lo, hi)) + } else { + Err(bad_host_exposure_ports(raw, term)) + } + } + None => term + .parse::() + .map(|port| (port, port)) + .map_err(|_| bad_host_exposure_ports(raw, term)), + } + }) + .collect() +} + +/// The start-failing error for one unparseable term: the variable the list +/// was read from, and the list as it was read, so a mis-set environment +/// names its own correction. +fn bad_host_exposure_ports(raw: &str, term: &str) -> io::Error { + io::Error::other(format!( + "{HOST_EXPOSURE_PORTS_ENV}={raw}: `{term}` is neither a port nor a port range" + )) +} + /// The node-plane baseline set: the categories in force, each with the /// subnets it admits, and the compiled rules the host-side gate decides /// node-plane frames by. @@ -174,6 +250,13 @@ pub struct NodePlaneBaseline { /// The posture the gate decides the set under: the shipped constant, /// until the store-surface configuration flips it. phase: NodeBaselinePhase, + /// The host exposures over the alias (NET-062's third opening), as + /// inclusive port ranges: the ports the node row still reaches the + /// host alias at while the baseline is announced, the opening every + /// other port is refused through the alias for. The guest-side verdict + /// holds the same list as its own alias arm's; this is the host-side + /// gate's copy. + host_exposure: Vec<(u16, u16)>, } impl NodePlaneBaseline { @@ -251,6 +334,46 @@ impl NodePlaneBaseline { self.phase } + /// The host exposures over the alias this gate carries: the inclusive + /// port ranges the announced node row still reaches the host alias at, + /// the same list the guest-side verdict's own alias arm holds. + #[must_use] + pub(crate) fn host_exposure_ports(&self) -> &[(u16, u16)] { + &self.host_exposure + } + + /// Points the host exposures at `ports`, replacing the built-in: a host + /// widens or clears its own exposure surface, and a cleared list is an + /// alias with no opening — refused at every port for every row — not + /// an absent arm. The compiled set is untouched: the list scopes the + /// alias alone. + #[must_use] + pub fn with_host_exposure(mut self, ports: Vec<(u16, u16)>) -> Self { + self.host_exposure = ports; + self + } + + /// The host-exposure list as the daemon's start-up line spells it: one + /// `lo-hi` term per range, a bare port for a single-port term, and + /// `(none)` when the deployment cleared the list. + #[must_use] + pub(crate) fn render_host_exposure(&self) -> String { + if self.host_exposure.is_empty() { + return "(none)".to_string(); + } + self.host_exposure + .iter() + .map(|&(lo, hi)| { + if lo == hi { + lo.to_string() + } else { + format!("{lo}-{hi}") + } + }) + .collect::>() + .join(",") + } + /// The set as the daemon's start-up line spells it: one /// `category=endpoints` term per category, in the order the categories /// are carried, so the line names the set in force with each entry's @@ -314,7 +437,9 @@ impl NodePlaneBaseline { } /// Assembles the set from its parts: the categories carried, and the - /// addresses the compiled rules are keyed to. + /// addresses the compiled rules are keyed to. The host exposures start + /// at the built-in list; the deployment's spelling replaces them in + /// the run path's builder. fn from_entries(node_addr: [u8; 4], resolver: [u8; 4], entries: Vec) -> Self { Self { node_addr, @@ -322,6 +447,7 @@ impl NodePlaneBaseline { rules: Self::compile_rules(&entries, resolver, node_addr), entries, phase: NODE_BASELINE_PHASE, + host_exposure: DEFAULT_HOST_EXPOSURE_PORTS.to_vec(), } } @@ -344,7 +470,10 @@ impl NodePlaneBaseline { #[cfg(test)] mod tests { - use super::{BaselineCategory, BaselineEntry, NodePlaneBaseline}; + use super::{ + BaselineCategory, BaselineEntry, DEFAULT_HOST_EXPOSURE_PORTS, HOST_EXPOSURE_PORTS_ENV, + NodePlaneBaseline, host_exposure_ports_from_raw, + }; use boxes::core::egress::{FrameVerdict, summarize, verdict}; use std::net::Ipv4Addr; use std::str::FromStr; @@ -523,4 +652,67 @@ mod tests { FrameVerdict::Admit => panic!("a foreign source is not admitted by the set"), } } + + /// The host-exposure list the baseline ships, and the deployment's + /// spelling of its replacement: absent, the built-in ranges; set but + /// empty, a cleared list — the alias with no opening; and every term a + /// port or an inclusive range, an undecodable one a surfaced error + /// naming the variable and the value. + #[test] + fn host_exposure_ports_read_from_the_environment() { + assert_eq!( + host_exposure_ports_from_raw(None).unwrap(), + DEFAULT_HOST_EXPOSURE_PORTS.to_vec(), + "an unset variable is the built-in list of ranges" + ); + assert_eq!( + host_exposure_ports_from_raw(Some("8080")).unwrap(), + vec![(8080, 8080)], + "a bare port is a single-port range" + ); + assert_eq!( + host_exposure_ports_from_raw(Some(" 3000-3999, 4200 ")).unwrap(), + vec![(3000, 3999), (4200, 4200)], + "terms are inclusive ranges and ports, whitespace trimmed" + ); + assert!( + host_exposure_ports_from_raw(Some("")).unwrap().is_empty(), + "a set-but-empty list is a cleared one, not the built-in's" + ); + let garbage = host_exposure_ports_from_raw(Some("8080:nope")) + .expect_err("an undecodable term is a surfaced error") + .to_string(); + assert!( + garbage.contains(HOST_EXPOSURE_PORTS_ENV) && garbage.contains("8080:nope"), + "an undecodable term names the variable and the value, got: {garbage}" + ); + assert!( + host_exposure_ports_from_raw(Some("4000-3000")).is_err(), + "a reversed range is not an inclusive one" + ); + } + + /// The baseline carries the list the deployment spelled, and the + /// built-in's until a spelling replaces it: the builder replaces + /// rather than merges, and a cleared list reaches the accessor empty. + #[test] + fn baseline_carries_the_configured_host_exposures() { + let built_in = NodePlaneBaseline::built_in(SUBNET); + assert_eq!( + built_in.host_exposure_ports(), + DEFAULT_HOST_EXPOSURE_PORTS, + "the built-in enumeration carries the built-in host exposures" + ); + let re_exposed = built_in.clone().with_host_exposure(vec![(8080, 8080)]); + assert_eq!( + re_exposed.host_exposure_ports(), + &[(8080, 8080)], + "the builder replaces the built-in list within itself" + ); + let cleared = built_in.with_host_exposure(vec![]); + assert!( + cleared.host_exposure_ports().is_empty(), + "a cleared list is carried empty, not restored to the built-in's" + ); + } } diff --git a/crates/minvmd/src/net/egress_gate.rs b/crates/minvmd/src/net/egress_gate.rs index 48f1c33b20..9e65771d19 100644 --- a/crates/minvmd/src/net/egress_gate.rs +++ b/crates/minvmd/src/net/egress_gate.rs @@ -540,7 +540,11 @@ static INFRASTRUCTURE_RANGES: LazyLock = LazyLock::new(|| /// Whether `dst` lies in the infrastructure deny set as the host frame rule /// holds it ([`INFRASTRUCTURE_RULE`]): a fixed range; the host alias, which /// is default-deny at every port for a box row (design §7.1, NET-062) when -/// `refuse_host_alias` says so; the fabric plane +/// `refuse_host_alias` says so, and for the node row's frames too outside +/// the host exposures `host_exposure` carries — the inclusive port ranges a +/// host's own listener surface answers on, the alias's one opening, the +/// same list the guest-side verdict holds for its own alias arm; the fabric +/// plane /// outside `own_block`, the subnet the gate's rows live in — a frame to a /// sibling or to the daemon inside the node's own block is local reach, /// decided by the row's CIDR rules and the target's ingress, never by this @@ -564,14 +568,20 @@ static INFRASTRUCTURE_RANGES: LazyLock = LazyLock::new(|| /// of every box that shares the guest root namespace (a host-address box, /// the default network mode), and those reach the host alias as own-block /// local reach until the in-force baseline, which names the alias as its -/// registry and cache endpoint, decides the node plane instead. This -/// mirrors the shared verdict, whose own-address refusal is attached to box -/// relays only, never to the daemon relay. +/// registry and cache endpoint, decides the node plane instead. Announced, +/// that reach is scoped: the alias is opened at the host exposures alone — +/// the host's own dev-services plane — and a node-row frame to any other +/// port through the alias is this rule's drop, the same scoping the +/// box-row refusal names as default-deny. This mirrors the shared verdict, +/// whose own-address refusal is attached to box relays only, never to the +/// daemon relay. fn infrastructure_destination( dst: [u8; 4], + dst_port: u16, own_block: SwitchSubnet, allow: Option<&[Ipv4Cidr]>, refuse_host_alias: bool, + host_exposure: &[(u16, u16)], ) -> bool { let ranges = &*INFRASTRUCTURE_RANGES; if ranges.fixed.iter().any(|cidr| cidr.contains(dst)) { @@ -580,8 +590,17 @@ fn infrastructure_destination( // The host alias is default-deny (design §7.1, NET-062): a box reaches // the host only through a declared exposure, never by addressing the // alias directly, so the alias is refused under this rule at every port - // whatever the row's rules would say about it. - if refuse_host_alias && dst == own_block.host_alias().octets() { + // whatever the row's rules would say about it. The node row's frames + // — the host-address boxes the interim row carries — reach the same + // opening the host itself exposes over the alias (NET-062's third + // opening), and no other port: the exposures scope the alias for every + // row, and a frame with no readable port fails the opening closed. + let exposed = |port: u16| { + host_exposure + .iter() + .any(|&(lo, hi)| lo <= port && port <= hi) + }; + if dst == own_block.host_alias().octets() && (refuse_host_alias || !exposed(dst_port)) { return true; } let in_own_block = (u32::from_be_bytes(dst) & u32::from(own_block.netmask())) @@ -1054,6 +1073,7 @@ impl EgressGate { switch_socket = %switch_sock.display(), unregistered_sources = "dropped", undeclared_box_default = phase.as_str(), + host_exposure_ports = %baseline.render_host_exposure(), "host-side egress gate listening", ); // The node-plane baseline set the gate decides the in-VM daemon's own @@ -5386,14 +5406,20 @@ fn gate_verdict( // row, keyed to the daemon's own address, carries the host-address // boxes' frames, whose `host.min.internal` resolves to the alias, and // keeps own-block local reach to it until the in-force baseline (which - // returned above) decides the node plane. + // returned above) decides the node plane. Announced, that reach is + // scoped by the baseline's host exposures — the ports the host itself + // exposes over the alias — which the arm below reads for every row: + // the box rows' refusal stands at every port, and the node row's + // outside the exposures. let box_row = src != table.subnet().daemon_ip().octets(); if let Some(dst) = summary.destination() && infrastructure_destination( dst, + summary.destination_port(), table.subnet(), record.egress().allow_subnets(), box_row, + baseline.host_exposure_ports(), ) { return Err(GateDrop::Infrastructure { @@ -15162,15 +15188,20 @@ mod tests { ); } - /// The host alias's default-deny is a box row's alone (design §7.1, - /// NET-062). Announced, the interim node row at the daemon's address - /// carries the frames of every box sharing the guest root namespace — a - /// host-address box, the default network mode, whose `host.min.internal` - /// resolves to the alias — so a node-plane frame to the alias is - /// own-block local reach the row admits, while the same frame from a box - /// lease, even an allow-all one, is the infrastructure drop. + /// The host alias's default-deny is a box row's alone, and the node + /// row's reach through it is scoped by the host exposures (design + /// §7.1, NET-062). Announced, the interim node row at the daemon's + /// address carries the frames of every box sharing the guest root + /// namespace — a host-address box, the default network mode, whose + /// `host.min.internal` resolves to the alias — so a node-plane frame + /// to the alias is own-block local reach the row admits at the exposed + /// ports alone and the infrastructure drop at every other port, while + /// the same frames from a box lease, even an allow-all one, are the + /// infrastructure drop whatever the port. A deployment that clears the + /// exposure list closes the alias outright: the node row's frame is + /// refused at an exposed port too. #[test] - fn host_alias_refused_for_box_rows_but_not_the_announced_node_row() { + fn host_alias_refused_for_box_rows_and_scoped_by_the_exposures_for_the_node_row() { let registry = BoxRegistry::new(SUBNET); registry.register_node_namespace(7654); registry.register( @@ -15184,34 +15215,46 @@ mod tests { let summarize = boxes::core::egress::summarize; let alias = SUBNET.host_alias().octets(); - let node_frame = summarize(&ipv4_frame(SUBNET.daemon_ip().octets(), 6, alias, 18081)); - assert_eq!( + let verdict = |src: [u8; 4], port: u16, baseline: &NodePlaneBaseline| { gate_verdict( - &node_frame, + &summarize(&ipv4_frame(src, 6, alias, port)), None, &table, - &baseline, + baseline, &pins, - &ReplyTables::new() - ), + &ReplyTables::new(), + ) + }; + + // 8080 sits inside the built-in exposures (8000-8999); 18081 does + // not. + assert_eq!( + verdict(SUBNET.daemon_ip().octets(), 8080, &baseline), Ok(GateAdmit::Row), - "the announced node row keeps own-block reach to the host alias" + "the announced node row keeps own-block reach to the host alias at an exposed port" + ); + assert!( + matches!( + verdict(SUBNET.daemon_ip().octets(), 18081, &baseline), + Err(GateDrop::Infrastructure { dst, .. }) if dst == alias + ), + "the node row's frame to the host alias outside the exposures is the infrastructure drop" + ); + assert!( + matches!( + verdict(LEASE, 8080, &baseline), + Err(GateDrop::Infrastructure { dst, .. }) if dst == alias + ), + "a box row's frame to the host alias is the infrastructure drop at an exposed port" ); - let box_frame = summarize(&ipv4_frame(LEASE, 6, alias, 18081)); + let cleared = baseline.with_host_exposure(vec![]); assert!( matches!( - gate_verdict( - &box_frame, - None, - &table, - &baseline, - &pins, - &ReplyTables::new() - ), + verdict(SUBNET.daemon_ip().octets(), 8080, &cleared), Err(GateDrop::Infrastructure { dst, .. }) if dst == alias ), - "a box row's frame to the host alias is the infrastructure drop" + "a cleared exposure list refuses the node row's alias reach at every port" ); } diff --git a/docs/reference/cli-minvmd.md b/docs/reference/cli-minvmd.md index 61d101dd13..076942f7b7 100644 --- a/docs/reference/cli-minvmd.md +++ b/docs/reference/cli-minvmd.md @@ -55,6 +55,8 @@ An own-IP box that declares no `egress` section gets the deny-all egress default `minvmd` reads the variable only when it starts, and hands it to the guest at boot. Set it in the environment of the process that starts `minvmd`: `minvmd run`, or the first `min` command that starts the VM for you. Setting it for a later `min` command against a running VM changes nothing. To apply a change, stop `minvmd` (`minvmd stop`) and start it again with the new environment. +A host-address box — the default network mode — reaches the host through the switch's host alias, `host.min.internal`, and the alias is open at the host's own service ports alone: `3000-3999`, `4200`, `5000-5999`, `8000-8999`, and `9000-9999`. Every other port through the alias is refused. To open a different set, set `MINVMD_HOST_EXPOSURE_PORTS` to a comma-separated list of ports and inclusive ranges — `8080` for one port, `3000-3999,4200` for ranges — and to close the alias at every port, set it empty. An unparseable list fails the start, naming the variable and the value. The variable is read when `minvmd` starts, like the two above. + ### `status` ``` From e83f629d7614749f20c63164d55d72751b33e0c0 Mon Sep 17 00:00:00 2001 From: "gominimal-aw-bot[bot]" <281738952+gominimal-aw-bot[bot]@users.noreply.github.com> Date: Mon, 19 Oct 2026 21:54:46 -0400 Subject: [PATCH 2/7] fix(net): close host.min.internal unless host exposures are configured The design holds the host alias default-deny except explicitly configured host exposures, so an unset MINVMD_HOST_EXPOSURE_PORTS now means no exposure and the built-in port ranges are gone. The parser refuses port 0, names the bad term with the fix, gives a reversed range its own message, and fails the start on a non-Unicode value. The gate matches an exposure only for a TCP or UDP frame, so an ICMP frame (port 0) never opens the alias. Comments no longer claim the guest-side verdict holds the same list: own-address boxes stay refused at every port. The gate notes that the scoping holds only while the baseline is announced. The gate test covers range edges, UDP, ICMP and the closed default, and the CLI reference describes the closed default and the variable. --- crates/minvmd/src/net.rs | 6 +- crates/minvmd/src/net/baseline.rs | 174 ++++++++++++++------------- crates/minvmd/src/net/egress_gate.rs | 131 +++++++++++--------- docs/reference/cli-minvmd.md | 2 +- 4 files changed, 170 insertions(+), 143 deletions(-) diff --git a/crates/minvmd/src/net.rs b/crates/minvmd/src/net.rs index 3f373b8783..560f12ca82 100644 --- a/crates/minvmd/src/net.rs +++ b/crates/minvmd/src/net.rs @@ -795,9 +795,9 @@ impl HostGvproxy { // by it, beside the boxes' rows; announced — the shipped posture — // the allow-all interim node row still does, and the gate's // start-up line names the posture deciding. The host exposures the - // alias is opened at for the node row — the same opening the host - // exposes over the alias — are read from the environment once - // here, at start, an unparseable list failing it. + // alias is opened at for the node row — none unless the deployment + // names ports — are read from the daemon's environment here, on each + // spawn, an unparseable list failing it. let baseline = NodePlaneBaseline::built_in(subnet) .with_host_exposure(baseline::host_exposure_ports_from_env()?); let (stop_tx, stop_rx) = tokio::sync::oneshot::channel::<()>(); diff --git a/crates/minvmd/src/net/baseline.rs b/crates/minvmd/src/net/baseline.rs index 5b852806d6..4be93732f3 100644 --- a/crates/minvmd/src/net/baseline.rs +++ b/crates/minvmd/src/net/baseline.rs @@ -154,42 +154,44 @@ impl NodeBaselinePhase { /// the tests pin both of its arms, so the flip is one line and nothing else. pub(crate) const NODE_BASELINE_PHASE: NodeBaselinePhase = NodeBaselinePhase::Announced; -/// The host-exposure port list the baseline ships: the ranges the design -/// holds for a host's own dev-services plane (design §7.1) — the ports a -/// host's own listener surface answers on and the alias's node-row opening -/// is scoped to, the same opening the host exposes over the alias guest-side -/// (NET-062's third opening). Every other port is refused through the alias -/// for every row. -pub(crate) const DEFAULT_HOST_EXPOSURE_PORTS: [(u16, u16); 5] = [ - (3000, 3999), - (4200, 4200), - (5000, 5999), - (8000, 8999), - (9000, 9999), -]; - /// The environment variable the daemon's host-exposure port list is read -/// from, once, at VM start — the same read-at-start shape the hostname -/// proxy port and the egress-default opt-out carry. +/// from, each time the daemon starts the VM's network — from the daemon's +/// own environment, so a change takes a daemon restart, the same shape the +/// hostname proxy port and the egress-default opt-out carry. pub(crate) const HOST_EXPOSURE_PORTS_ENV: &str = "MINVMD_HOST_EXPOSURE_PORTS"; /// The host-exposure port list the daemon starts with, as the deployment -/// spelled it: absent, the built-in list; set but empty, a host alias with -/// no opening at all — the list cleared, refused at every port for every -/// row. The list is comma-separated, each term a port (`4200`) or an -/// inclusive range (`3000-3999`); a term that is neither, or a range whose -/// low end sits above its high end, fails the start, the variable naming -/// the term as it was read. +/// spelled it. The design holds the alias default-deny except explicitly +/// configured host exposures (design §7.1), so absent or empty, the list is +/// empty and the alias is refused at every port for every row. The list is +/// comma-separated, each term a port (`4200`) or an inclusive range +/// (`3000-3999`), port 0 excluded; a term that is neither, a reversed range, +/// or a value that is not Unicode fails the start, the error naming the term +/// and the fix. pub(crate) fn host_exposure_ports_from_env() -> io::Result> { - host_exposure_ports_from_raw(std::env::var(HOST_EXPOSURE_PORTS_ENV).ok().as_deref()) + match std::env::var(HOST_EXPOSURE_PORTS_ENV) { + Ok(raw) => host_exposure_ports_from_raw(Some(&raw)), + Err(std::env::VarError::NotPresent) => host_exposure_ports_from_raw(None), + Err(std::env::VarError::NotUnicode(_)) => Err(io::Error::other(format!( + "{HOST_EXPOSURE_PORTS_ENV} is not valid Unicode. {HOST_EXPOSURE_FIX}" + ))), + } } +/// The correction every parse error ends with. +const HOST_EXPOSURE_FIX: &str = "Set it to ports and ranges such as 8080,3000-3999, \ + or set it empty to close host.min.internal."; + /// Parses one deployment's spelling of the host-exposure port list: every -/// term a port or an inclusive range, whitespace trimmed, an empty list a -/// cleared one — the alias's openings none — rather than the built-in's. +/// term a port or an inclusive range from 1 to 65535, whitespace trimmed; +/// absent or empty, no exposure at all. fn host_exposure_ports_from_raw(raw: Option<&str>) -> io::Result> { let Some(raw) = raw else { - return Ok(DEFAULT_HOST_EXPOSURE_PORTS.to_vec()); + return Ok(Vec::new()); + }; + let port = |text: &str, term: &str| match text.trim().parse::() { + Ok(0) | Err(_) => Err(bad_host_exposure_term(term)), + Ok(port) => Ok(port), }; raw.split(',') .filter(|term| !term.trim().is_empty()) @@ -197,35 +199,28 @@ fn host_exposure_ports_from_raw(raw: Option<&str>) -> io::Result let term = term.trim(); match term.split_once('-') { Some((lo, hi)) => { - let lo = lo - .trim() - .parse::() - .map_err(|_| bad_host_exposure_ports(raw, term))?; - let hi = hi - .trim() - .parse::() - .map_err(|_| bad_host_exposure_ports(raw, term))?; + let (lo, hi) = (port(lo, term)?, port(hi, term)?); if lo <= hi { Ok((lo, hi)) } else { - Err(bad_host_exposure_ports(raw, term)) + Err(io::Error::other(format!( + "{HOST_EXPOSURE_PORTS_ENV}: `{term}` is a reversed range; write it \ + low-high, as `{hi}-{lo}`. {HOST_EXPOSURE_FIX}" + ))) } } - None => term - .parse::() - .map(|port| (port, port)) - .map_err(|_| bad_host_exposure_ports(raw, term)), + None => port(term, term).map(|port| (port, port)), } }) .collect() } -/// The start-failing error for one unparseable term: the variable the list -/// was read from, and the list as it was read, so a mis-set environment -/// names its own correction. -fn bad_host_exposure_ports(raw: &str, term: &str) -> io::Error { +/// The start-failing error for one unparseable term: the variable, the term +/// as it was read, and the correction. +fn bad_host_exposure_term(term: &str) -> io::Error { io::Error::other(format!( - "{HOST_EXPOSURE_PORTS_ENV}={raw}: `{term}` is neither a port nor a port range" + "{HOST_EXPOSURE_PORTS_ENV}: `{term}` is not a port from 1 to 65535 or a low-high port \ + range. {HOST_EXPOSURE_FIX}" )) } @@ -250,12 +245,13 @@ pub struct NodePlaneBaseline { /// The posture the gate decides the set under: the shipped constant, /// until the store-surface configuration flips it. phase: NodeBaselinePhase, - /// The host exposures over the alias (NET-062's third opening), as - /// inclusive port ranges: the ports the node row still reaches the - /// host alias at while the baseline is announced, the opening every - /// other port is refused through the alias for. The guest-side verdict - /// holds the same list as its own alias arm's; this is the host-side - /// gate's copy. + /// The configured host exposures over the alias, as inclusive port + /// ranges: the ports the node row still reaches the host alias at while + /// the baseline is announced, every other port refused through the + /// alias. Empty unless the deployment names ports. The host-side gate + /// alone reads it: the guest-side verdict's own alias list starts empty + /// and nothing in the run path fills it, so own-address boxes stay + /// refused at every port. host_exposure: Vec<(u16, u16)>, } @@ -336,14 +332,14 @@ impl NodePlaneBaseline { /// The host exposures over the alias this gate carries: the inclusive /// port ranges the announced node row still reaches the host alias at, - /// the same list the guest-side verdict's own alias arm holds. + /// empty unless the deployment configured ports. #[must_use] pub(crate) fn host_exposure_ports(&self) -> &[(u16, u16)] { &self.host_exposure } - /// Points the host exposures at `ports`, replacing the built-in: a host - /// widens or clears its own exposure surface, and a cleared list is an + /// Points the host exposures at `ports`, replacing the current list: a + /// host names or clears its own exposure surface, and a cleared list is an /// alias with no opening — refused at every port for every row — not /// an absent arm. The compiled set is untouched: the list scopes the /// alias alone. @@ -438,7 +434,7 @@ impl NodePlaneBaseline { /// Assembles the set from its parts: the categories carried, and the /// addresses the compiled rules are keyed to. The host exposures start - /// at the built-in list; the deployment's spelling replaces them in + /// empty, the alias closed; the deployment's spelling replaces them in /// the run path's builder. fn from_entries(node_addr: [u8; 4], resolver: [u8; 4], entries: Vec) -> Self { Self { @@ -447,7 +443,7 @@ impl NodePlaneBaseline { rules: Self::compile_rules(&entries, resolver, node_addr), entries, phase: NODE_BASELINE_PHASE, - host_exposure: DEFAULT_HOST_EXPOSURE_PORTS.to_vec(), + host_exposure: Vec::new(), } } @@ -471,8 +467,8 @@ impl NodePlaneBaseline { #[cfg(test)] mod tests { use super::{ - BaselineCategory, BaselineEntry, DEFAULT_HOST_EXPOSURE_PORTS, HOST_EXPOSURE_PORTS_ENV, - NodePlaneBaseline, host_exposure_ports_from_raw, + BaselineCategory, BaselineEntry, HOST_EXPOSURE_PORTS_ENV, NodePlaneBaseline, + host_exposure_ports_from_raw, }; use boxes::core::egress::{FrameVerdict, summarize, verdict}; use std::net::Ipv4Addr; @@ -653,17 +649,16 @@ mod tests { } } - /// The host-exposure list the baseline ships, and the deployment's - /// spelling of its replacement: absent, the built-in ranges; set but - /// empty, a cleared list — the alias with no opening; and every term a - /// port or an inclusive range, an undecodable one a surfaced error - /// naming the variable and the value. + /// The deployment's spelling of the host-exposure list: absent or + /// empty, no exposure — the alias closed; every term a port or an + /// inclusive range from 1 to 65535; an undecodable term, port 0, or a + /// reversed range a surfaced error naming the variable, the term and + /// the fix. #[test] fn host_exposure_ports_read_from_the_environment() { - assert_eq!( - host_exposure_ports_from_raw(None).unwrap(), - DEFAULT_HOST_EXPOSURE_PORTS.to_vec(), - "an unset variable is the built-in list of ranges" + assert!( + host_exposure_ports_from_raw(None).unwrap().is_empty(), + "an unset variable is no exposure: the alias stays closed" ); assert_eq!( host_exposure_ports_from_raw(Some("8080")).unwrap(), @@ -677,42 +672,57 @@ mod tests { ); assert!( host_exposure_ports_from_raw(Some("")).unwrap().is_empty(), - "a set-but-empty list is a cleared one, not the built-in's" + "a set-but-empty list is no exposure" ); let garbage = host_exposure_ports_from_raw(Some("8080:nope")) .expect_err("an undecodable term is a surfaced error") .to_string(); assert!( - garbage.contains(HOST_EXPOSURE_PORTS_ENV) && garbage.contains("8080:nope"), - "an undecodable term names the variable and the value, got: {garbage}" + garbage.contains(HOST_EXPOSURE_PORTS_ENV) + && garbage.contains("`8080:nope` is not a port") + && garbage.contains("set it empty to close host.min.internal"), + "an undecodable term names the variable, the term and the fix, got: {garbage}" ); + for zero in ["0", "0-65535"] { + let error = host_exposure_ports_from_raw(Some(zero)) + .expect_err("port 0 is refused") + .to_string(); + assert!( + error.contains(&format!("`{zero}` is not a port")), + "port 0 names the term, got: {error}" + ); + } + let reversed = host_exposure_ports_from_raw(Some("4000-3000")) + .expect_err("a reversed range is not an inclusive one") + .to_string(); assert!( - host_exposure_ports_from_raw(Some("4000-3000")).is_err(), - "a reversed range is not an inclusive one" + reversed.contains("`4000-3000` is a reversed range") + && reversed.contains("`3000-4000`") + && !reversed.contains("is not a port"), + "a reversed range gets its own message, got: {reversed}" ); } - /// The baseline carries the list the deployment spelled, and the - /// built-in's until a spelling replaces it: the builder replaces - /// rather than merges, and a cleared list reaches the accessor empty. + /// The baseline carries no exposure until the deployment's spelling + /// replaces the list: the builder replaces rather than merges, and a + /// cleared list reaches the accessor empty. #[test] fn baseline_carries_the_configured_host_exposures() { let built_in = NodePlaneBaseline::built_in(SUBNET); - assert_eq!( - built_in.host_exposure_ports(), - DEFAULT_HOST_EXPOSURE_PORTS, - "the built-in enumeration carries the built-in host exposures" + assert!( + built_in.host_exposure_ports().is_empty(), + "the built-in enumeration carries no host exposure" ); - let re_exposed = built_in.clone().with_host_exposure(vec![(8080, 8080)]); + let re_exposed = built_in.with_host_exposure(vec![(8080, 8080)]); assert_eq!( re_exposed.host_exposure_ports(), &[(8080, 8080)], - "the builder replaces the built-in list within itself" + "the builder sets the list" ); - let cleared = built_in.with_host_exposure(vec![]); + let cleared = re_exposed.with_host_exposure(vec![]); assert!( cleared.host_exposure_ports().is_empty(), - "a cleared list is carried empty, not restored to the built-in's" + "a cleared list is carried empty" ); } } diff --git a/crates/minvmd/src/net/egress_gate.rs b/crates/minvmd/src/net/egress_gate.rs index a760b7a93f..03a61134a9 100644 --- a/crates/minvmd/src/net/egress_gate.rs +++ b/crates/minvmd/src/net/egress_gate.rs @@ -541,11 +541,12 @@ static INFRASTRUCTURE_RANGES: LazyLock = LazyLock::new(|| /// holds it ([`INFRASTRUCTURE_RULE`]): a fixed range; the host alias, which /// is default-deny at every port for a box row (design §7.1, NET-062) when /// `refuse_host_alias` says so, and for the node row's frames too outside -/// the host exposures `host_exposure` carries — the inclusive port ranges a -/// host's own listener surface answers on, the alias's one opening, the -/// same list the guest-side verdict holds for its own alias arm; the fabric -/// plane -/// outside `own_block`, the subnet the gate's rows live in — a frame to a +/// the host exposures `host_exposure` carries — the inclusive port ranges +/// the deployment configured, empty unless it named ports, matched against +/// `transport_port`, the TCP or UDP destination port, `None` for any other +/// frame. Box rows stay refused at a configured exposure too: the design +/// holds an exposure as local reach under the box's egress rules, and that +/// reach is not built yet. The fabric plane outside `own_block`, the subnet the gate's rows live in — a frame to a /// sibling or to the daemon inside the node's own block is local reach, /// decided by the row's CIDR rules and the target's ingress, never by this /// rule, and the gateway inside it is the control-surface rule's; or RFC @@ -569,15 +570,14 @@ static INFRASTRUCTURE_RANGES: LazyLock = LazyLock::new(|| /// the default network mode), and those reach the host alias as own-block /// local reach until the in-force baseline, which names the alias as its /// registry and cache endpoint, decides the node plane instead. Announced, -/// that reach is scoped: the alias is opened at the host exposures alone — -/// the host's own dev-services plane — and a node-row frame to any other -/// port through the alias is this rule's drop, the same scoping the -/// box-row refusal names as default-deny. This mirrors the shared verdict, +/// that reach is scoped: the alias is opened at the configured host +/// exposures alone, and a node-row frame to any other port, or with no TCP +/// or UDP port, is this rule's drop. This mirrors the shared verdict, /// whose own-address refusal is attached to box relays only, never to the /// daemon relay. fn infrastructure_destination( dst: [u8; 4], - dst_port: u16, + transport_port: Option, own_block: SwitchSubnet, allow: Option<&[Ipv4Cidr]>, refuse_host_alias: bool, @@ -591,16 +591,15 @@ fn infrastructure_destination( // the host only through a declared exposure, never by addressing the // alias directly, so the alias is refused under this rule at every port // whatever the row's rules would say about it. The node row's frames - // — the host-address boxes the interim row carries — reach the same - // opening the host itself exposes over the alias (NET-062's third - // opening), and no other port: the exposures scope the alias for every - // row, and a frame with no readable port fails the opening closed. - let exposed = |port: u16| { + // — the host-address boxes the interim row carries — reach the alias at + // the configured host exposures alone, and only over TCP or UDP: a frame + // with no transport port (ICMP reads as port 0) fails the opening closed. + let exposed = transport_port.is_some_and(|port| { host_exposure .iter() .any(|&(lo, hi)| lo <= port && port <= hi) - }; - if dst == own_block.host_alias().octets() && (refuse_host_alias || !exposed(dst_port)) { + }); + if dst == own_block.host_alias().octets() && (refuse_host_alias || !exposed) { return true; } let in_own_block = (u32::from_be_bytes(dst) & u32::from(own_block.netmask())) @@ -5407,15 +5406,22 @@ fn gate_verdict( // boxes' frames, whose `host.min.internal` resolves to the alias, and // keeps own-block local reach to it until the in-force baseline (which // returned above) decides the node plane. Announced, that reach is - // scoped by the baseline's host exposures — the ports the host itself - // exposes over the alias — which the arm below reads for every row: - // the box rows' refusal stands at every port, and the node row's - // outside the exposures. + // scoped by the baseline's configured host exposures, which the arm + // below reads for every row: the box rows' refusal stands at every + // port, and the node row's outside the exposures. The scoping holds only + // while the baseline is announced: in force, the arm above returns first + // and the baseline's registry and cache entries admit the alias at every + // port, a gap the in-force phase still has to close. let box_row = src != table.subnet().daemon_ip().octets(); + let transport_port = matches!( + summary.protocol(), + Some(egress::IPPROTO_TCP | egress::IPPROTO_UDP) + ) + .then(|| summary.destination_port()); if let Some(dst) = summary.destination() && infrastructure_destination( dst, - summary.destination_port(), + transport_port, table.subnet(), record.egress().allow_subnets(), box_row, @@ -15189,17 +15195,18 @@ mod tests { } /// The host alias's default-deny is a box row's alone, and the node - /// row's reach through it is scoped by the host exposures (design - /// §7.1, NET-062). Announced, the interim node row at the daemon's - /// address carries the frames of every box sharing the guest root - /// namespace — a host-address box, the default network mode, whose - /// `host.min.internal` resolves to the alias — so a node-plane frame - /// to the alias is own-block local reach the row admits at the exposed - /// ports alone and the infrastructure drop at every other port, while - /// the same frames from a box lease, even an allow-all one, are the - /// infrastructure drop whatever the port. A deployment that clears the - /// exposure list closes the alias outright: the node row's frame is - /// refused at an exposed port too. + /// row's reach through it is scoped by the configured host exposures + /// (design §7.1, NET-062). Announced, the interim node row at the + /// daemon's address carries the frames of every box sharing the guest + /// root namespace — a host-address box, the default network mode, whose + /// `host.min.internal` resolves to the alias. The built-in baseline + /// carries no exposure, so the alias is closed at every port until a + /// deployment names ports; with a list, a node-plane TCP or UDP frame to + /// the alias is own-block local reach the row admits inside the list's + /// ranges, edges included, and the infrastructure drop outside them, + /// while an ICMP frame, which carries no port, is refused even by a list + /// spanning every port. The same frames from a box lease, even an + /// allow-all one, are the infrastructure drop whatever the port. #[test] fn host_alias_refused_for_box_rows_and_scoped_by_the_exposures_for_the_node_row() { let registry = BoxRegistry::new(SUBNET); @@ -15209,15 +15216,16 @@ mod tests { .with_admitted_ports([8080]), ); let table = registry.table(); - let baseline = NodePlaneBaseline::built_in(SUBNET); - assert_eq!(baseline.phase(), NodeBaselinePhase::Announced); + let built_in = NodePlaneBaseline::built_in(SUBNET); + assert_eq!(built_in.phase(), NodeBaselinePhase::Announced); let pins = dns_pins::DnsPins::new(SUBNET); let summarize = boxes::core::egress::summarize; let alias = SUBNET.host_alias().octets(); + let node = SUBNET.daemon_ip().octets(); - let verdict = |src: [u8; 4], port: u16, baseline: &NodePlaneBaseline| { + let verdict = |src: [u8; 4], proto: u8, port: u16, baseline: &NodePlaneBaseline| { gate_verdict( - &summarize(&ipv4_frame(src, 6, alias, port)), + &summarize(&ipv4_frame(src, proto, alias, port)), None, &table, baseline, @@ -15225,36 +15233,45 @@ mod tests { &ReplyTables::new(), ) }; + let refused = |result: Result| matches!(result, Err(GateDrop::Infrastructure { dst, .. }) if dst == alias); - // 8080 sits inside the built-in exposures (8000-8999); 18081 does - // not. - assert_eq!( - verdict(SUBNET.daemon_ip().octets(), 8080, &baseline), - Ok(GateAdmit::Row), - "the announced node row keeps own-block reach to the host alias at an exposed port" + assert!( + refused(verdict(node, 6, 8080, &built_in)), + "with no configured exposure the alias is closed to the node row at every port" ); + + let exposed = built_in + .clone() + .with_host_exposure(vec![(3000, 3999), (8080, 8080)]); assert!( - matches!( - verdict(SUBNET.daemon_ip().octets(), 18081, &baseline), - Err(GateDrop::Infrastructure { dst, .. }) if dst == alias - ), + refused(verdict(node, 6, 2999, &exposed)), + "the port below a range's low edge is the infrastructure drop" + ); + for port in [3000, 3999, 8080] { + assert_eq!( + verdict(node, 6, port, &exposed), + Ok(GateAdmit::Row), + "the node row reaches the host alias at exposed port {port}" + ); + } + assert!( + refused(verdict(node, 6, 18081, &exposed)), "the node row's frame to the host alias outside the exposures is the infrastructure drop" ); + assert_eq!( + verdict(node, 17, 8080, &exposed), + Ok(GateAdmit::Row), + "a UDP frame reaches the host alias at an exposed port" + ); assert!( - matches!( - verdict(LEASE, 8080, &baseline), - Err(GateDrop::Infrastructure { dst, .. }) if dst == alias - ), + refused(verdict(LEASE, 6, 8080, &exposed)), "a box row's frame to the host alias is the infrastructure drop at an exposed port" ); - let cleared = baseline.with_host_exposure(vec![]); + let every_port = built_in.with_host_exposure(vec![(0, u16::MAX)]); assert!( - matches!( - verdict(SUBNET.daemon_ip().octets(), 8080, &cleared), - Err(GateDrop::Infrastructure { dst, .. }) if dst == alias - ), - "a cleared exposure list refuses the node row's alias reach at every port" + refused(verdict(node, 1, 0, &every_port)), + "an ICMP frame carries no port and never matches an exposure" ); } diff --git a/docs/reference/cli-minvmd.md b/docs/reference/cli-minvmd.md index 076942f7b7..ff30364b05 100644 --- a/docs/reference/cli-minvmd.md +++ b/docs/reference/cli-minvmd.md @@ -55,7 +55,7 @@ An own-IP box that declares no `egress` section gets the deny-all egress default `minvmd` reads the variable only when it starts, and hands it to the guest at boot. Set it in the environment of the process that starts `minvmd`: `minvmd run`, or the first `min` command that starts the VM for you. Setting it for a later `min` command against a running VM changes nothing. To apply a change, stop `minvmd` (`minvmd stop`) and start it again with the new environment. -A host-address box — the default network mode — reaches the host through the switch's host alias, `host.min.internal`, and the alias is open at the host's own service ports alone: `3000-3999`, `4200`, `5000-5999`, `8000-8999`, and `9000-9999`. Every other port through the alias is refused. To open a different set, set `MINVMD_HOST_EXPOSURE_PORTS` to a comma-separated list of ports and inclusive ranges — `8080` for one port, `3000-3999,4200` for ranges — and to close the alias at every port, set it empty. An unparseable list fails the start, naming the variable and the value. The variable is read when `minvmd` starts, like the two above. +`minvmd` closes `host.min.internal` at every port unless `MINVMD_HOST_EXPOSURE_PORTS` lists ports. Set the variable to a comma-separated list of ports and ranges, such as `8080,3000-3999`. A box in the default host-address network mode then reaches the host at those ports and no other. The box's egress rules still apply inside an exposure. An own-address box gets a refusal at every port, whatever the list says. Leave the variable unset or empty to keep `host.min.internal` closed. Each port must lie between 1 and 65535, and each range must run from low to high. Any other value fails the start with an error that names the bad term. `minvmd` reads the variable from its own environment each time it boots the VM, so to apply a change, stop `minvmd` and start it again. ### `status` From c27b7488de0bad3e3a2b3eb209c1afa29c07a9e1 Mon Sep 17 00:00:00 2001 From: "gominimal-aw-bot[bot]" <281738952+gominimal-aw-bot[bot]@users.noreply.github.com> Date: Tue, 20 Oct 2026 12:32:30 -0400 Subject: [PATCH 3/7] test(e2e): expose the host ports the NET-003 checks reach minvmd now closes host.min.internal at every port unless MINVMD_HOST_EXPOSURE_PORTS lists ports, so the VM lanes' NET-003 check, a host-address box reaching the host-loopback listener at 18081 through the alias, timed out. Export the list as that one port on VM lanes, before the first min call autospawns the daemon, and derive PROXY_HOST_PORT from it. Add the refusal half: on VM lanes the same box gets no answer through the alias at 18089, where a second host-loopback listener answers. The own-address NET-004 drop at 18081 stays, with comments saying an own-address box is refused even at the listed port. --- scripts/session-e2e.sh | 66 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 61 insertions(+), 5 deletions(-) diff --git a/scripts/session-e2e.sh b/scripts/session-e2e.sh index 90ec31e5d9..6ab018b505 100755 --- a/scripts/session-e2e.sh +++ b/scripts/session-e2e.sh @@ -358,6 +358,20 @@ case "${1:-}" in ;; esac +# The host exposure the VM-backed daemon opens host.min.internal at. minvmd +# closes the alias at every port unless MINVMD_HOST_EXPOSURE_PORTS lists +# ports, and it reads the list from its own environment at each VM boot, so +# the export must precede the first `min` call, whose autospawn inherits it. +# The list is the one port NET-003 reaches the host's loopback at from a +# host-address box (the proxy proof's PROXY_HOST_PORT) and nothing wider: +# the same proof asserts the alias stays refused at an unlisted port, and +# own-address boxes stay refused at every port, listed or not. A native +# daemon has no alias gate and ignores the variable. +E2E_HOST_EXPOSURE_PORT=18081 +if [ -n "$E2E_VM" ]; then + export MINVMD_HOST_EXPOSURE_PORTS="$E2E_HOST_EXPOSURE_PORT" +fi + # The non-baseline package the sandbox proof adds and then runs. It must be a # real upstream package that is genuinely ABSENT from a fresh shell-stack # sandbox — the `shell` stack composes `base` (bash, coreutils, tar, gzip, …) @@ -408,6 +422,7 @@ PROXY_SEED_DIR="" # seeded by the min.internal proxy proof; removed on teardown PROXY_OWN_SEED_DIR="" # its own-address box's seed; removed on teardown PROXY_HOST_DIR="" # the host-loopback dir that proof serves; removed on teardown PROXY_HOST_SRV_PID="" # the host-loopback server it starts; killed on teardown +PROXY_UNEXPOSED_SRV_PID="" # its listener at a port outside the host exposure; killed on teardown PAR_SEED_DIR="" # seeded by the proxy-parity proof below; removed on teardown PAR_OWN_SEED_DIR="" # its own-address target box's seed; removed on teardown PAR_CALLER_SEED_DIR="" # its denied-caller box's seed; removed on teardown @@ -968,6 +983,9 @@ teardown() { if [ -n "$PROXY_HOST_SRV_PID" ]; then kill "$PROXY_HOST_SRV_PID" 2>/dev/null || true fi + if [ -n "$PROXY_UNEXPOSED_SRV_PID" ]; then + kill "$PROXY_UNEXPOSED_SRV_PID" 2>/dev/null || true + fi [ -n "$PAR_SEED_DIR" ] && rm -rf "$PAR_SEED_DIR" [ -n "$PAR_OWN_SEED_DIR" ] && rm -rf "$PAR_OWN_SEED_DIR" [ -n "$PAR_CALLER_SEED_DIR" ] && rm -rf "$PAR_CALLER_SEED_DIR" @@ -15743,7 +15761,8 @@ proof_min_internal_names_through_proxy() { PROXY_OWN_NAME="e2e-own-proxy" # the own-address box, on switch lanes PROXY_BOX_PORT=18080 # the in-box responders' listen port PROXY_OWN_EXTERNAL_PORT=18082 # ... published externally by --ingress - PROXY_HOST_PORT=18081 # the host-loopback listener (NET-003/004) + PROXY_HOST_PORT="$E2E_HOST_EXPOSURE_PORT" # the host-loopback listener (NET-003/004) + PROXY_UNEXPOSED_PORT=18089 # a host-loopback listener outside the exposure PROXY_DEAD_PORT=19090 # nothing listens: an upstream-refused 502 PROXY_CLOSED_PORT=19091 # not in the own box's ingress map: a 403 PROXY_HOST_ALIAS="100.64.255.254" # the deprecated literal (NET-004) @@ -15958,6 +15977,40 @@ proof_min_internal_names_through_proxy() { # ---- NET-003: host.min.internal from a host-address box ------------------- proxy_assert_host_by_name "$proxy_sid" "NET-003" host + # ---- the host exposure is the only opening (design §7.1) ---------------- + # A VM host's gate opens host.min.internal at the listed exposure alone + # (MINVMD_HOST_EXPOSURE_PORTS, exported at the top), so the same box, the + # same alias, at a port outside the list must not reach the host, even + # with a host-loopback listener answering there. A native host-address box + # shares the host's namespace, with no alias gate to assert. + if [ -n "$E2E_VM" ]; then + ( cd "$PROXY_HOST_DIR" && exec python3 -m http.server "$PROXY_UNEXPOSED_PORT" --bind 127.0.0.1 ) \ + >/dev/null 2>"$WORK/proxy-unexposed-srv.err" & + PROXY_UNEXPOSED_SRV_PID=$! + proxy_unexposed_up=0 + for _ in $(seq 1 40); do + if [ "$(curl -sS --max-time 5 -o /dev/null -w '%{http_code}' \ + "http://127.0.0.1:$PROXY_UNEXPOSED_PORT/marker" 2>/dev/null || true)" = "200" ]; then + proxy_unexposed_up=1 + break + fi + sleep 0.25 + done + if [ "$proxy_unexposed_up" -ne 1 ]; then + echo "::error::the unexposed host-loopback http.server never answered on 127.0.0.1:$PROXY_UNEXPOSED_PORT" + cat "$WORK/proxy-unexposed-srv.err" 2>/dev/null || true + fail + fi + if mnl session exec "$proxy_sid" \ + "curl -sS --max-time 8 http://host.min.internal:$PROXY_UNEXPOSED_PORT/marker" \ + >"$WORK/proxy-unexposed.out" 2>"$WORK/proxy-unexposed.err" \ + || grep -q -- "$PROXY_HOST_MARKER" "$WORK/proxy-unexposed.out" 2>/dev/null; then + echo "::error::the host-address box reached the host through host.min.internal at port $PROXY_UNEXPOSED_PORT, outside MINVMD_HOST_EXPOSURE_PORTS=$MINVMD_HOST_EXPOSURE_PORTS" + fail + fi + echo "host exposure: host.min.internal:$PROXY_UNEXPOSED_PORT refused from the host-address box ($(tail -n1 "$WORK/proxy-unexposed.err" 2>/dev/null)) OK" + fi + # ---- NET-001's own-address half: a VM host's lease route ----------------- # Gated like the own-IP proof: MINVMD_GVPROXY_BIN is the one signal that a # switch exists. On every lane that sets it the daemon is in a VM, so its @@ -16024,8 +16077,9 @@ proof_min_internal_names_through_proxy() { # NET-003's own-address half, narrowed to resolution: the box resolves # host.min.internal through the switch zone, to the host alias. Box→host # reach over that alias is default-deny except configured host exposures - # (design §7.1), and this box's switch has none, so the reach is not - # asserted here. TODO(host-exposure): the positive reach arm comes back + # (design §7.1), and an own-address box is refused even at the one + # exposure this run lists, so the reach is not asserted here. + # TODO(host-exposure): the positive reach arm comes back # with a configured exposure (gominimal/inbox#867). proxy_own_resolved="$(mnl session exec "$PROXY_OWN_SID" \ "getent ahostsv4 host.min.internal" 2>"$WORK/proxy-own-resolve.err" \ @@ -16039,7 +16093,9 @@ proof_min_internal_names_through_proxy() { # NET-004: the deprecated literal itself. Box→host reach over the alias # is default-deny except configured host exposures (design §7.1), and - # none is configured, so the box's own relay drops the connect — though + # an own-address box gets none — not even PROXY_HOST_PORT, the one this + # run lists for host-address boxes — so the box's own relay drops the + # connect — though # its egress rules admit every address (0.0.0.0/0 above), so the drop # is the infrastructure deny set's and not the deny-all default's: no # answer and no reset until the timeout, and the relay names the drop @@ -16061,7 +16117,7 @@ proof_min_internal_names_through_proxy() { mnl session exec "$PROXY_OWN_SID" \ "/usr/bin/socat /dev/null TCP:$PROXY_HOST_ALIAS:$PROXY_HOST_PORT,connect-timeout=10" \ >/dev/null 2>"$WORK/proxy-alias.err" && { - echo "::error::NET-004: the own-address box completed a connection to the host alias $PROXY_HOST_ALIAS:$PROXY_HOST_PORT with no host exposure configured" + echo "::error::NET-004: the own-address box completed a connection to the host alias $PROXY_HOST_ALIAS:$PROXY_HOST_PORT, which an own-address box must never reach" fail } proxy_alias_elapsed_ms=$(( $(now_ms) - proxy_alias_start_ms )) From ad1a84d51fa6a7b2f3f621806eb66611783075d9 Mon Sep 17 00:00:00 2001 From: "minimal-foundry[bot]" <327719912+minimal-foundry[bot]@users.noreply.github.com> Date: Tue, 20 Oct 2026 22:50:52 +0000 Subject: [PATCH 4/7] test(e2e): prove the exec path before the unexposed-port refusal Run the exposed-port fetch and the unexposed-port fetch in one session exec. Require the marker at the exposed port, and require curl exit 7 or 28 at the unexposed port, so a broken exec, a missing curl or a DNS failure no longer passes as a refusal. --- scripts/session-e2e.sh | 38 ++++++++++++++++++++++++++++++-------- 1 file changed, 30 insertions(+), 8 deletions(-) diff --git a/scripts/session-e2e.sh b/scripts/session-e2e.sh index 732dcaa806..4ebb48a2cb 100755 --- a/scripts/session-e2e.sh +++ b/scripts/session-e2e.sh @@ -16018,14 +16018,36 @@ proof_min_internal_names_through_proxy() { cat "$WORK/proxy-unexposed-srv.err" 2>/dev/null || true fail fi - if mnl session exec "$proxy_sid" \ - "curl -sS --max-time 8 http://host.min.internal:$PROXY_UNEXPOSED_PORT/marker" \ - >"$WORK/proxy-unexposed.out" 2>"$WORK/proxy-unexposed.err" \ - || grep -q -- "$PROXY_HOST_MARKER" "$WORK/proxy-unexposed.out" 2>/dev/null; then - echo "::error::the host-address box reached the host through host.min.internal at port $PROXY_UNEXPOSED_PORT, outside MINVMD_HOST_EXPOSURE_PORTS=$MINVMD_HOST_EXPOSURE_PORTS" - fail - fi - echo "host exposure: host.min.internal:$PROXY_UNEXPOSED_PORT refused from the host-address box ($(tail -n1 "$WORK/proxy-unexposed.err" 2>/dev/null)) OK" + # One exec runs both fetches, so a broken exec, a missing curl or a + # failed lookup shows on the exposed fetch and cannot pass as a refusal. + # The exposed port must answer with the marker. The unexposed port must + # fail as a refused connection (curl exit 7) or a timeout (exit 28). + proxy_unexposed_out="$(mnl session exec "$proxy_sid" \ + "curl -sS --max-time 8 http://host.min.internal:$PROXY_HOST_PORT/marker; echo \"exposed_rc=\$?\"; curl -sS --max-time 8 -o /dev/null http://host.min.internal:$PROXY_UNEXPOSED_PORT/marker; echo \"closed_rc=\$?\"" \ + 2>"$WORK/proxy-unexposed.err" || true)" + printf '%s\n' "$proxy_unexposed_out" >"$WORK/proxy-unexposed.out" + proxy_exposed_rc="$(sed -n 's/^.*exposed_rc=\([0-9]*\)$/\1/p' "$WORK/proxy-unexposed.out" | head -n1)" + proxy_unexposed_rc="$(sed -n 's/^closed_rc=\([0-9]*\)$/\1/p' "$WORK/proxy-unexposed.out" | tail -n1)" + if [ "$proxy_exposed_rc" != "0" ] || [[ "$proxy_unexposed_out" != *"$PROXY_HOST_MARKER"* ]]; then + echo "::error::the host-address box did not fetch the marker from host.min.internal at the exposed port $PROXY_HOST_PORT (curl exit '${proxy_exposed_rc:-none}'), so the unexposed-port check proves nothing" + echo "--- exec stdout ---"; cat "$WORK/proxy-unexposed.out" 2>/dev/null || true + echo "--- exec stderr ---"; cat "$WORK/proxy-unexposed.err" 2>/dev/null || true + fail + fi + case "$proxy_unexposed_rc" in + 7 | 28) ;; + 0) + echo "::error::the host-address box reached the host through host.min.internal at port $PROXY_UNEXPOSED_PORT, outside MINVMD_HOST_EXPOSURE_PORTS=$MINVMD_HOST_EXPOSURE_PORTS" + fail + ;; + *) + echo "::error::the fetch from host.min.internal at port $PROXY_UNEXPOSED_PORT failed with curl exit '${proxy_unexposed_rc:-none}', not a refused connection (7) or a timeout (28)" + echo "--- exec stdout ---"; cat "$WORK/proxy-unexposed.out" 2>/dev/null || true + echo "--- exec stderr ---"; cat "$WORK/proxy-unexposed.err" 2>/dev/null || true + fail + ;; + esac + echo "host exposure: host.min.internal:$PROXY_HOST_PORT reached and host.min.internal:$PROXY_UNEXPOSED_PORT refused from the host-address box (curl exit $proxy_unexposed_rc: $(tail -n1 "$WORK/proxy-unexposed.err" 2>/dev/null)) OK" fi # ---- NET-001's own-address half: a VM host's lease route ----------------- From df50c01ed5653319ee3c66001401cd39b207816a Mon Sep 17 00:00:00 2001 From: "minimal-foundry[bot]" <327719912+minimal-foundry[bot]@users.noreply.github.com> Date: Thu, 22 Oct 2026 05:24:24 +0000 Subject: [PATCH 5/7] docs(minvmd): name the issue that owns the in-force host-alias gap The comment on the host-alias arm states a residual. Name gominimal/inbox#1147 as the issue that owns it. --- crates/minvmd/src/net/egress_gate.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/crates/minvmd/src/net/egress_gate.rs b/crates/minvmd/src/net/egress_gate.rs index 6c359fbe4e..5616622fbb 100644 --- a/crates/minvmd/src/net/egress_gate.rs +++ b/crates/minvmd/src/net/egress_gate.rs @@ -5390,7 +5390,8 @@ fn gate_verdict( // port, and the node row's outside the exposures. The scoping holds only // while the baseline is announced: in force, the arm above returns first // and the baseline's registry and cache entries admit the alias at every - // port, a gap the in-force phase still has to close. + // port, a gap the in-force phase still has to close + // (gominimal/inbox#1147). let box_row = src != table.subnet().daemon_ip().octets(); let transport_port = matches!( summary.protocol(), From 3125ee4b2097c8650442eb4dc324630dabd84f6c Mon Sep 17 00:00:00 2001 From: "gominimal-aw-bot[bot]" <281738952+gominimal-aw-bot[bot]@users.noreply.github.com> Date: Thu, 22 Oct 2026 22:42:52 +0000 Subject: [PATCH 6/7] chore(worker-iterate): address CodeRabbit findings on PR #2331 Record why the non-first-fragment drop of the host-exposure port check is deliberate: the verdict path is stateless by design, and the failure direction is a drop, not an exposure (CodeRabbit, egress_gate.rs:5400). Reply-confirm the already-landed in-force gap comment (minimal-arch, egress_gate.rs:5410) and the maintainer's InForce scope ruling (CodeRabbit, egress_gate.rs:5418). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- crates/minvmd/src/net/egress_gate.rs | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/crates/minvmd/src/net/egress_gate.rs b/crates/minvmd/src/net/egress_gate.rs index 5616622fbb..3fbb7e5b54 100644 --- a/crates/minvmd/src/net/egress_gate.rs +++ b/crates/minvmd/src/net/egress_gate.rs @@ -5393,6 +5393,18 @@ fn gate_verdict( // port, a gap the in-force phase still has to close // (gominimal/inbox#1147). let box_row = src != table.subnet().daemon_ip().octets(); + // A non-first IPv4 fragment carries no readable L4 port — `summarize` + // reports destination port 0 for it — so it fails the exposure match + // and the gate drops it, never admits it: a fragmented UDP datagram to + // an exposed port dies at its later fragments. Reviewer ask + // (CodeRabbit, PR #2331) was to associate later fragments with their + // admitted first fragment, or defer the port check to reassembly. + // Declined: the verdict path is stateless and allocation-free by + // design — every input comes from the one frame being judged — and + // fragment association would add per-flow state here (or reassembly + // elsewhere) to recover a packet whose failure mode is a drop, not an + // exposure: deny-by-default keeps the safe direction. Tracked as + // follow-up work with the in-force scoping (gominimal/inbox#1147). let transport_port = matches!( summary.protocol(), Some(egress::IPPROTO_TCP | egress::IPPROTO_UDP) From cc2f86efad1aa0eb910bfbce7abdac3a007aeba2 Mon Sep 17 00:00:00 2001 From: "minimal-foundry[bot]" <327719912+minimal-foundry[bot]@users.noreply.github.com> Date: Tue, 27 Oct 2026 23:19:06 -0700 Subject: [PATCH 7/7] docs(minvmd): state the in-force alias bound and the own-address exposure gap in the gate comments --- crates/minvmd/src/net/egress_gate.rs | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/crates/minvmd/src/net/egress_gate.rs b/crates/minvmd/src/net/egress_gate.rs index 7d6bced664..f9cdf6f768 100644 --- a/crates/minvmd/src/net/egress_gate.rs +++ b/crates/minvmd/src/net/egress_gate.rs @@ -526,8 +526,9 @@ static INFRASTRUCTURE_RANGES: LazyLock = LazyLock::new(|| /// the deployment configured, empty unless it named ports, matched against /// `transport_port`, the TCP or UDP destination port, `None` for any other /// frame. Box rows stay refused at a configured exposure too: the design -/// holds an exposure as local reach under the box's egress rules, and that -/// reach is not built yet. The fabric plane outside `own_block`, the subnet the gate's rows live in — a frame to a +/// holds an exposure as local reach under the box's egress rules (§7.1), +/// and that reach is not built yet; the refusal fails closed, and +/// gominimal/inbox#1144 owns the gap. The fabric plane outside `own_block`, the subnet the gate's rows live in — a frame to a /// sibling or to the daemon inside the node's own block is local reach, /// decided by the row's CIDR rules and the target's ingress, never by this /// rule, and the gateway inside it is the control-surface rule's; or RFC @@ -5412,9 +5413,9 @@ fn gate_verdict( // below reads for every row: the box rows' refusal stands at every // port, and the node row's outside the exposures. The scoping holds only // while the baseline is announced: in force, the arm above returns first - // and the baseline's registry and cache entries admit the alias at every - // port, a gap the in-force phase still has to close - // (gominimal/inbox#1147). + // and admits the alias only at TCP on `REGISTRY_CACHE_FETCH_PORTS` (443), + // with no host exposures, a gap gominimal/inbox#1144 and + // gominimal/inbox#1147 own. let box_row = src != table.subnet().daemon_ip().octets(); // A non-first IPv4 fragment carries no readable L4 port — `summarize` // reports destination port 0 for it — so it fails the exposure match @@ -5426,8 +5427,9 @@ fn gate_verdict( // design — every input comes from the one frame being judged — and // fragment association would add per-flow state here (or reassembly // elsewhere) to recover a packet whose failure mode is a drop, not an - // exposure: deny-by-default keeps the safe direction. Tracked as - // follow-up work with the in-force scoping (gominimal/inbox#1147). + // exposure: deny-by-default keeps the safe direction. In force, the arm + // above admits no host exposure at all, so the fragment case arises only + // while the baseline is announced. let transport_port = matches!( summary.protocol(), Some(egress::IPPROTO_TCP | egress::IPPROTO_UDP)