Skip to content

Commit e6960f7

Browse files
authored
[WSLC] Port mappings for the built-in proxy (#1799)
1 parent 8e368f0 commit e6960f7

25 files changed

Lines changed: 510 additions & 136 deletions

‎docs/backends/wslc/wsl-container-getting-started.md‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -415,6 +415,13 @@ TCP only — the WSLC SDK runtime returns `E_NOTIMPL` for UDP, so a `"udp"`
415415
protocol is rejected. Two entries claiming the same `windowsPort` are also
416416
rejected.
417417

418+
With the [built-in proxy](#built-in-proxy), including a policy that denies
419+
everything else, the mapping is set on the proxy container, which relays it to
420+
the workload's `containerPort`. Each mapping is reachable only on Windows
421+
`127.0.0.1`, regardless of `network.ingress`, and the workload sees the proxy
422+
container's address as the source. Each mapping accepts at most 512 open
423+
connections; more wait until one closes.
424+
418425
The separate `provision` operation takes the same list under
419426
`wslc.provision.portMappings`, which requires schema `1.1.0-alpha`:
420427

@@ -517,7 +524,7 @@ no separate `--setup-wslc` step is required.
517524
| Type | Exact policy | WSLC behavior |
518525
|---|---|---|
519526
| Bridged | Egress, ingress, and host-loopback defaults all `allow`, without egress rules | The container gets an address on WSLC's NAT network in the session VM. It can reach the internet, the local network, and [port mappings](#port-mappings) forward Windows ports into it. Windows host loopback isn't accessible. Nothing is filtered. |
520-
| Isolated | All three defaults omitted or `deny`, without egress allow rules | No networking. The container only has its own loopback interface. It can't reach anything outside itself, and nothing can reach it. |
527+
| Isolated | All three defaults omitted or `deny`, without egress allow rules or port mappings | No networking. The container only has its own loopback interface. It can't reach anything outside itself, and nothing can reach it. |
521528
| Built-in proxy | Any other combination, create-and-run execution | Egress filtered by the [built-in proxy](#built-in-proxy) |
522529
| Built-in proxy | Any other combination, container lifecycle operations | Rejected |
523530

@@ -576,13 +583,14 @@ as follows:
576583
- Rejected with the proxy: `allow` entries for any protocol except `tcp`
577584
(including entries without `ports`, which cover every protocol; use
578585
`"ports": [{ "protocol": "tcp" }]` for every TCP port), IPv6
579-
CIDRs, targets inside `10.231.0.0/16`, `wslc.portMappings`,
580-
`hostLoopback: "allow"`, and `runtimeConfig.networkProxy`. `deny` entries
586+
CIDRs, targets inside `10.231.0.0/16`, `hostLoopback: "allow"`, and
587+
`runtimeConfig.networkProxy`. `deny` entries
581588
for `udp` or `icmp` have no effect, because only TCP leaves through the
582589
proxy, and log a warning.
583590

584-
- Nothing can connect in to the workload, so `network.ingress.default:
585-
"allow"` has no effect and logs a warning.
591+
- The workload accepts connections only through [port mappings](#port-mappings),
592+
which listen on Windows `127.0.0.1`, not a LAN address. So
593+
`network.ingress.default: "allow"` has no effect and logs a warning.
586594

587595
- The proxy image ships as `mxc-wslc-gateway.tar` beside the MXC binaries and
588596
is imported into the image store on first use. If the tar is missing or

‎docs/development/architecture/designs/1462-wslc-builtin-proxy/README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -117,7 +117,8 @@ Built on the WSLC SDK networking support from Pierre and the WSLC team
117117
- **Limits:** each listener accepts at most 512 connections; more wait in the
118118
kernel's queue. At most 256 UDP DNS queries are in flight; more are dropped
119119
and retried by the client. Request headers are limited to 16 KB and 10s,
120-
upstream connections to 30s, idle connections to 10 minutes, and DNS
120+
upstream connections to 30s, idle connections (except port mappings) to 10
121+
minutes, and DNS
121122
forwarding to 4s. Accept errors, including running out of descriptors, are
122123
retried rather than stopping the controller. The SDK has no per-container
123124
memory or CPU limit, only per session.

‎scripts/versioning/config-validation-exemptions.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414
"tests/configs/lxc_network_retired_v08.json",
1515
"tests/configs/rejected_version_too_old.json",
1616
"tests/configs/seatbelt_capture_denials_v1_0.json",
17+
"tests/configs/wslc_network_egress_port_mapping_udp_rejected.json",
1718
"tests/configs/wslc_state_aware_exec_rejected_filesystem.json",
1819
"tests/configs/wslc_state_aware_provision_rejected_proxy.json"
1920
]

‎sdk/dotnet/Microsoft.Mxc.Sdk.Tests/V1/MxcContainerWslcE2ETests.cs‎

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -601,7 +601,6 @@ public async Task Spawn_BuiltInProxyIsRemovedAfterKill()
601601

602602
public static TheoryData<string, string> UnenforceableEgressCases() => new()
603603
{
604-
{ "port mappings", "wslc.portMappings cannot be combined with egress filtering" },
605604
{ "external proxy", "runtimeConfig.networkProxy cannot be combined with egress filtering" },
606605
{ "host loopback", "hostLoopback 'allow' cannot be combined with egress filtering" },
607606
{ "UDP allow", "network.egress.allow supports only protocol 'tcp' (got 'udp')" },
@@ -615,12 +614,8 @@ public async Task BuiltInProxyRejectsEgressItCannotEnforceBeforeStartingAContain
615614
{
616615
RequireWslc();
617616
var network = AllowCloudflare443();
618-
var containment = new Containment.Wslc();
619617
switch (name)
620618
{
621-
case "port mappings":
622-
containment.PortMappings.Add(new WslcPortMapping(39001, 80));
623-
break;
624619
case "external proxy":
625620
network.RuntimeConfig = new NetworkRuntimeConfig { NetworkProxy = "http://127.0.0.1:8888" };
626621
break;
@@ -640,7 +635,7 @@ public async Task BuiltInProxyRejectsEgressItCannotEnforceBeforeStartingAContain
640635
var request = new ContainerRequest("echo WSLC_EGRESS_RULES_SHOULD_NOT_RUN")
641636
{
642637
Network = network,
643-
Containment = containment,
638+
Containment = new Containment.Wslc(),
644639
};
645640

646641
var run = await Assert.ThrowsAsync<MxcException>(

‎sdk/node/tests/integration/wslc-e2e.test.ts‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -622,8 +622,6 @@ describe('WSLC SDK E2E — built-in proxy', {
622622
it('should reject egress rules the built-in proxy cannot enforce before starting a container', { timeout: 120_000 }, async () => {
623623
const rules = ALLOW_CLOUDFLARE_443.egress!;
624624
const cases: Array<[string, NetworkPolicy, Record<string, unknown>, string]> = [
625-
['port mappings', ALLOW_CLOUDFLARE_443, { portMappings: [{ windowsPort: 39001, containerPort: 80, protocol: 'tcp' }] },
626-
'wslc.portMappings cannot be combined with egress filtering'],
627625
['external proxy', { ...ALLOW_CLOUDFLARE_443, runtimeConfig: { networkProxy: 'http://127.0.0.1:8888' } }, {},
628626
'runtimeConfig.networkProxy cannot be combined with egress filtering'],
629627
['host loopback', { egress: rules, ingress: { default: 'deny', hostLoopback: 'allow' } }, {},
0 Bytes
Binary file not shown.
0 Bytes
Binary file not shown.

‎src/mxc-sdk/src/backends/wslc/common/container_steps.rs‎

Lines changed: 45 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -666,6 +666,35 @@ impl ProcessSettings {
666666
// ContainerSettings builder
667667
// ---------------------------------------------------------------------------
668668

669+
/// IPv4 `127.0.0.1` as a `sockaddr_in` (port, then address, in network order).
670+
/// `'static` because the SDK reads `windowsAddress` at `WslcCreateContainer`.
671+
static WINDOWS_LOOPBACK: sockaddr_storage = sockaddr_storage {
672+
ss_family: 2, // AF_INET
673+
__ss_pad1: [0, 0, 127, 0, 0, 1],
674+
__ss_align: 0,
675+
__ss_pad2: [0; 112],
676+
};
677+
678+
/// The SDK form of `mappings`, bound to Windows `127.0.0.1` only.
679+
/// The parser rejects UDP today; the branch keeps this correct if an SDK
680+
/// update enables it.
681+
pub(crate) fn sdk_port_mappings(mappings: &[PortMapping]) -> Vec<WslcContainerPortMapping> {
682+
mappings
683+
.iter()
684+
.map(|pm| WslcContainerPortMapping {
685+
windowsPort: pm.windows_port,
686+
containerPort: pm.container_port,
687+
protocol: if pm.protocol == "udp" {
688+
WslcPortProtocol::WSLC_PORT_PROTOCOL_UDP
689+
} else {
690+
WslcPortProtocol::WSLC_PORT_PROTOCOL_TCP
691+
},
692+
// The SDK only reads the address.
693+
windowsAddress: ptr::from_ref(&WINDOWS_LOOPBACK).cast_mut(),
694+
})
695+
.collect()
696+
}
697+
669698
/// A fully-populated `WslcContainerSettings` together with every heap buffer its
670699
/// pointers reference (image name, volume paths, port mappings). The init
671700
/// process is intentionally NOT set here — that is caller-specific (the one-shot
@@ -703,24 +732,10 @@ impl ContainerSettings {
703732
return Err(sdk_step_error("WslcInitContainerSettings", hr, ""));
704733
}
705734

706-
// Port mappings (host<->container). Empty list = no forwarding. The
707-
// parser rejects UDP up front today; the explicit branch is retained so
708-
// this keeps compiling if UDP is enabled after an SDK update.
735+
// Port mappings (host<->container). Empty list = no forwarding.
709736
let mut port_vec: Vec<WslcContainerPortMapping> = Vec::new();
710737
if !port_mappings.is_empty() {
711-
port_vec = port_mappings
712-
.iter()
713-
.map(|pm| WslcContainerPortMapping {
714-
windowsPort: pm.windows_port,
715-
containerPort: pm.container_port,
716-
protocol: if pm.protocol == "udp" {
717-
WslcPortProtocol::WSLC_PORT_PROTOCOL_UDP
718-
} else {
719-
WslcPortProtocol::WSLC_PORT_PROTOCOL_TCP
720-
},
721-
windowsAddress: ptr::null_mut(),
722-
})
723-
.collect();
738+
port_vec = sdk_port_mappings(port_mappings);
724739

725740
let hr = sdk.WslcSetContainerSettingsPortMappings(
726741
&mut raw,
@@ -1864,6 +1879,20 @@ mod tests {
18641879
logical_cpus: 8,
18651880
};
18661881

1882+
#[test]
1883+
fn port_mappings_bind_windows_ipv4_loopback() {
1884+
let mapping = PortMapping {
1885+
windows_port: 8080,
1886+
container_port: 80,
1887+
protocol: "tcp".to_string(),
1888+
};
1889+
let sdk = sdk_port_mappings(&[mapping]);
1890+
// SAFETY: points at the 'static WINDOWS_LOOPBACK.
1891+
let address = unsafe { &*sdk[0].windowsAddress };
1892+
assert_eq!(address.ss_family, 2);
1893+
assert_eq!(address.__ss_pad1, [0, 0, 127, 0, 0, 1]);
1894+
}
1895+
18671896
#[test]
18681897
fn a_processor_count_the_host_cannot_supply_is_refused() {
18691898
let refused = sizing_fits_host(

‎src/mxc-sdk/src/backends/wslc/common/egress_gateway.rs‎

Lines changed: 78 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ use crate::mxc_common::filesystem_security::{
2929
lock_owner_only_directory_path, set_current_user_owner, LockedDirectoryPath,
3030
};
3131
use crate::mxc_common::logger::{Logger, Mode};
32-
use crate::mxc_common::models::ScriptResponse;
32+
use crate::mxc_common::models::{PortMapping, ScriptResponse};
3333
use crate::mxc_common::proxy_env;
3434
use crate::mxc_common::string_util::CoTaskMemPWSTR;
3535
use crate::wslc_common::container_steps::{self, cstr_bytes, sdk_error, ProcessSettings};
@@ -113,12 +113,15 @@ const INTERNAL_SUBNET: Ipv4Addr = Ipv4Addr::new(10, 231, 1, 0);
113113
const SUBNET_PREFIX_LENGTH: u8 = 24;
114114
const GATEWAY_EGRESS_ADDRESS: Ipv4Addr = Ipv4Addr::new(10, 231, 0, 2);
115115
const GATEWAY_WORKLOAD_ADDRESS: Ipv4Addr = Ipv4Addr::new(10, 231, 1, 254);
116+
/// Pinned so the gateway knows where to relay port mappings.
117+
const WORKLOAD_ADDRESS: Ipv4Addr = Ipv4Addr::new(10, 231, 1, 2);
116118
const PROXY_PORT: u16 = 3128;
117119
const NODE_USE_ENV_PROXY: &str = "NODE_USE_ENV_PROXY";
118120

119121
// The SDK reads these through pointers when the container is created.
120122
static GATEWAY_EGRESS_IN_ADDR: IN_ADDR = in_addr_of(GATEWAY_EGRESS_ADDRESS);
121123
static GATEWAY_WORKLOAD_IN_ADDR: IN_ADDR = in_addr_of(GATEWAY_WORKLOAD_ADDRESS);
124+
static WORKLOAD_IN_ADDR: IN_ADDR = in_addr_of(WORKLOAD_ADDRESS);
122125

123126
const IMAGE_ID: &str = env!("MXC_WSLC_GATEWAY_IMAGE_ID");
124127
const IMAGE_TAR: &str = "mxc-wslc-gateway.tar";
@@ -153,13 +156,14 @@ impl Gateway {
153156
store_path: &str,
154157
session_name: &str,
155158
egress: &ProxiedEgress,
159+
port_mappings: &[PortMapping],
156160
logger: &mut Logger,
157161
) -> Result<Self, ScriptResponse> {
158162
let records = StoreRecords::open(store_path).map_err(host_error)?;
159163
let names = ProxyNames::for_session(session_name);
160164
refuse_unrecorded(sdk, session, &records, &names)?;
161165
records.write(&names, &names.all()).map_err(host_error)?;
162-
match Self::start_inner(sdk, session, &names, egress, logger) {
166+
match Self::start_inner(sdk, session, &names, egress, port_mappings, logger) {
163167
Ok((container, process, resolv_conf)) => Ok(Self {
164168
sdk,
165169
session,
@@ -185,6 +189,7 @@ impl Gateway {
185189
session: WslcSession,
186190
names: &ProxyNames,
187191
egress: &ProxiedEgress,
192+
port_mappings: &[PortMapping],
188193
logger: &mut Logger,
189194
) -> Result<(WslcContainerGuard, ProcessSettings, tempfile::TempPath), ScriptResponse> {
190195
create_network(sdk, session, &names.egress, EGRESS_SUBNET, false)?;
@@ -215,8 +220,25 @@ impl Gateway {
215220
if hr != S_OK {
216221
return Err(sdk_error("WslcSetContainerSettingsNetworks failed", hr, ""));
217222
}
223+
// Published ports reach only a container with a non-internal network,
224+
// so the gateway takes the workload's mappings and relays them.
225+
let mappings = container_steps::sdk_port_mappings(port_mappings);
226+
if !mappings.is_empty() {
227+
let hr = sdk.WslcSetContainerSettingsPortMappings(
228+
&mut settings,
229+
mappings.as_ptr(),
230+
mappings.len() as u32,
231+
);
232+
if hr != S_OK {
233+
return Err(sdk_error(
234+
"WslcSetContainerSettingsPortMappings failed",
235+
hr,
236+
"",
237+
));
238+
}
239+
}
218240

219-
let policy = serde_json::to_string(&render_policy(egress)).map_err(|e| {
241+
let policy = serde_json::to_string(&render_policy(egress, port_mappings)).map_err(|e| {
220242
WslcError::Host(format!("could not render the built-in proxy policy: {e}"))
221243
.into_response()
222244
})?;
@@ -294,7 +316,7 @@ impl Gateway {
294316
/// The workload's only network. The SDK reads it when the container is
295317
/// created.
296318
pub(crate) fn workload_networks(&self) -> [WslcContainerNetwork; 1] {
297-
[network(&self.names.internal, ptr::null())]
319+
[network(&self.names.internal, &WORKLOAD_IN_ADDR)]
298320
}
299321

300322
/// Delete the gateway, the workload, and their networks, then log the
@@ -352,8 +374,21 @@ pub(crate) fn workload_env(caller_env: &[String], scope: EnvScope) -> Vec<String
352374
env
353375
}
354376

355-
fn render_policy(egress: &ProxiedEgress) -> gateway::Policy {
377+
fn render_policy(egress: &ProxiedEgress, port_mappings: &[PortMapping]) -> gateway::Policy {
356378
let egress = egress.egress.clone();
379+
let mut relayed: Vec<gateway::PortMapping> = Vec::new();
380+
for mapping in port_mappings {
381+
if relayed
382+
.iter()
383+
.all(|r| r.listen_port != mapping.container_port)
384+
{
385+
relayed.push(gateway::PortMapping {
386+
listen_port: mapping.container_port,
387+
workload_address: WORKLOAD_ADDRESS,
388+
workload_port: mapping.container_port,
389+
});
390+
}
391+
}
357392
gateway::Policy {
358393
workload_address: GATEWAY_WORKLOAD_ADDRESS,
359394
egress_address: GATEWAY_EGRESS_ADDRESS,
@@ -362,7 +397,7 @@ fn render_policy(egress: &ProxiedEgress) -> gateway::Policy {
362397
egress,
363398
host_loopback: None,
364399
custom_proxy: None,
365-
port_mappings: Vec::new(),
400+
port_mappings: relayed,
366401
}
367402
}
368403

@@ -927,12 +962,46 @@ mod tests {
927962
ports: None,
928963
};
929964

930-
let policy = render_policy(&egress(gateway::Action::Deny, vec![rule]));
965+
let policy = render_policy(&egress(gateway::Action::Deny, vec![rule]), &[]);
931966
assert!(policy.forward_dns);
932967
assert_eq!(policy.workload_address, GATEWAY_WORKLOAD_ADDRESS);
933968
assert_eq!(proxy_url(), "http://10.231.1.254:3128");
934-
assert!(render_policy(&egress(gateway::Action::Allow, Vec::new())).forward_dns);
935-
assert!(!render_policy(&egress(gateway::Action::Deny, Vec::new())).forward_dns);
969+
assert!(render_policy(&egress(gateway::Action::Allow, Vec::new()), &[]).forward_dns);
970+
assert!(!render_policy(&egress(gateway::Action::Deny, Vec::new()), &[]).forward_dns);
971+
}
972+
973+
#[test]
974+
fn each_mapped_container_port_is_relayed_once_to_the_workload() {
975+
let mapping = |windows_port, container_port| PortMapping {
976+
windows_port,
977+
container_port,
978+
protocol: "tcp".to_string(),
979+
};
980+
let egress = ProxiedEgress {
981+
egress: gateway::Egress {
982+
default: gateway::Action::Deny,
983+
allow: Vec::new(),
984+
deny: Vec::new(),
985+
},
986+
warnings: Vec::new(),
987+
};
988+
let policy = render_policy(
989+
&egress,
990+
&[
991+
mapping(18080, 8080),
992+
mapping(18081, 8080),
993+
mapping(2222, 22),
994+
],
995+
);
996+
assert!(!policy.forward_dns);
997+
assert_eq!(
998+
policy.port_mappings,
999+
[8080, 22].map(|port| gateway::PortMapping {
1000+
listen_port: port,
1001+
workload_address: WORKLOAD_ADDRESS,
1002+
workload_port: port,
1003+
})
1004+
);
9361005
}
9371006

9381007
#[test]

0 commit comments

Comments
 (0)