[WSLC] Proposal: Built-in proxy for networking by theelliotm · Pull Request #1625 · microsoft/mxc

Elliot (theelliotm) · 2026-10-30T22:04:17Z

Summary

WSLC networking today supports only all-allow (BRIDGED) or all-deny (NONE). This design adds a per-container controller container that enforces TCP CIDR and port rules, and lets egress, ingress and hostLoopback defaults be set independently. It uses the existing network fields.

README: docs/development/architecture/designs/1462-wslc-builtin-proxy/README.md
API Doc: docs/development/architecture/designs/1462-wslc-builtin-proxy/api.md
Related Issue: [WSLC] In-built proxy for networking #1462

Microsoft Reviewers: Open in CodeFlow

azure-pipelines · 2026-10-30T22:04:28Z

Azure Pipelines: There may be pipelines that require an authorized user to comment /azp run to run.

Copilot

🟡 Changes recommended

The design leaves unresolved DNS policy enforcement gaps, Windows loopback port collisions, and crash recovery that cannot reclaim networks while orphan workloads remain attached.

3 open issues

What changed in this PR

This documentation-only PR proposes a per-container WSLC networking controller for #1462, extending today’s all-or-nothing networking with TCP CIDR and port filtering through existing network fields.

Changes:

Defines proxy selection, host-loopback access, port relaying, and custom-proxy behavior.
Describes controller lifecycle, cleanup, prerequisites, staged delivery, and planned validation.
Provides Rust, .NET, and Node usage examples, compatibility notes, and open API questions.

File	Description
docs/development/architecture/designs/1462-wslc-builtin-proxy/README.md	Proposes controller architecture, networking behavior, lifecycle management, and validation.
docs/development/architecture/designs/1462-wslc-builtin-proxy/api.md	Documents SDK usage, request mapping, compatibility, and planned SDK tests.

_{Review effort: Balanced}

Copilot

🟡 Changes recommended

The design leaves HTTPS upstream TLS handling and controller proxy-variable injection for subsequent execs unresolved, risking failures for otherwise permitted HTTP(S) connections.

1 open issue

Preserve TLS identity when forwarding to HTTPS proxies · New

1 previously missed issue

In code that hasn't changed since last review

Inject retained proxy settings into every proxied exec

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

Lifecycle exec cannot remain unchanged: state_aware.rs::exec_config injects proxy variables only from the current exec request, and the daemon passes that environment to the new process. After provisioning a CIDR-filtered container, an exec without networkProxy therefore lacks the controller proxy variables, so even permitted HTTP(S) connections fail on the internal-only network. Specify controller endpoint retention and proxy-variable injection for every proxied exec, including replacement environments, and validate an exec without an explicit proxy setting.

3 resolved since last review

_{Review effort: Balanced}

Soham Das (SohamDas2021) · 2026-11-02T17:13:44Z

+- **Implementation PRs:** Not started.
+
+WSLC networking today supports only all-allow (`BRIDGED`) or all-deny (`NONE`).
+This design adds a per-container controller container that enforces TCP CIDR


Per-container controller container or a per vm controller container that enforces traffic rules per-container across all containers in the vm?

Per-container controller container. Adding networks to a live controller container isn't currently possible - it can only be done during creation.

to confirm, is the controller container a seperate wsl container we spin up? or is it another executable the we'll add to mxc? just want to make sure I understand what controller means here is all.

Soham Das (SohamDas2021) · 2026-11-02T17:15:24Z

+
+- With this feature, configs with CIDR rules, mixed defaults, egress deny plus `networkProxy`, or
+  all-deny plus port mappings automatically use a built-in controller. __Configs
+  that are valid today don't change.__


we discussed that the udp/icmp behavior will change?

UDP/ICMP behavior will only change for configs that modify themselves in such a way that traffic gets proxied. allow-all or deny-all configs remain unaffected.

The only significant change for unmodified configs is that hostLoopback will actually work now (as a result of the SDK update).

Copilot

🟡 Changes recommended

Unresolved proxy rules would break supported BRIDGED SDK callers, risk exposing inherited credentials in replacement environments, and leave mixed-default all-TCP access inconsistent.

2 open issues

1 previously missed issue

In code that hasn't changed since last review

Reject proxied mode with default-allow egress and denied ingress

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

[P2] With egress.default: allow, denied ingress/host loopback, and networkProxy, the mode table selects Proxied, but the custom-proxy path permits only the proxy endpoint rather than all TCP. Reject this combination in proxied mode, as the linked Bubblewrap guide does, or define how all-TCP access is preserved. Keep the existing all-allow BRIDGED cooperative-proxy case unchanged and add the mixed-default combination to the validation plan.

1 resolved since last review

Preserve TLS identity when forwarding to HTTPS proxies

_{Review effort: Balanced}

Copilot

🔵 Needs a closer look

Human assessment is needed to evaluate the design’s attribution of host-loopback access to the SDK upgrade rather than MXC’s deliberate per-session enablement.

No open issues 🎉

2 resolved since last review

_{Review effort: Balanced}

Soham Das (SohamDas2021) · 2026-11-02T17:18:19Z

+
+- **Example 2: Windows loopback service plus an inbound port.** All egress
+  denied, `hostLoopback: allow`, and `wslc.portMappings`
+  `[{ "windowsPort": 18080, "containerPort": 8080, "protocol": "tcp" }]`.


please include the full schema for readability.

Elliot (theelliotm) · 2026-11-04T00:01:15Z

Tracking microsoft/WSL#42161, which adds the ability to connect/disconnect networks to running containers. Would allow one container to manage the proxy for everything.

Branden Bonaby (bbonaby) · 2026-11-05T00:13:56Z

+- **SDK differences:** one existing difference matters here. Rust and .NET
+  provision requests carry `NetworkPolicy.runtime_config` / `RuntimeConfig`;
+  Node's provision `DirectionalNetworkConfig` has none. WSLC rejects a proxy
+  at provision today. The resolution is design spec
+  [open question 1](README.md#open-questions).


question: doesn't node have it right here?

mxc/sdk/node/src/v1/types.ts

Line 222 in 27d0717

export interface NetworkPolicy extends DirectionalNetworkConfig {

Branden Bonaby (bbonaby) · 2026-11-05T00:17:10Z

+1. **Discovery capability:** should `BackendCapability` gain a value for WSLC
+   egress rules or host loopback, so callers can detect support before
+   running? Without one, unsupported hosts fail at run time with
+   `backend_unavailable`. Adding a value is non-breaking: the enum is
+   `#[non_exhaustive]` in Rust and has an `Unknown` value in .NET. Owners:
+   `@theelliotm` and SDK maintainers.


question: Any idea what you want to call it? wslcProxyAvailable? or reusng an existing name but for wslc?

I'd have to take a look at the full list, but I imagine we can re-use existing names. The built-in proxy functionality should feel plug-and-play.

Branden Bonaby (bbonaby) · 2026-11-05T00:57:40Z

+- **Proxy URL with a hostname:** the workload's proxy URL is passed through
+  unchanged. MXC resolves the name on Windows before creating the controller
+  and passes the first IPv4 answer in the controller's policy. The
+  controller's DNS answers only that name, with the controller's own address,
+  and the controller relays the proxy's port byte-for-byte to the resolved
+  IP. It never resolves the name itself. TLS to an `https://` proxy therefore
+  runs end to end and the certificate is checked against the proxy's name.


note: Not sure if you can get around this but when you start accepting host names you have to start thinking about DNS changes. e.g When we resolve the name on windows, the address can change right after. I assume we don't do any refreshing or anything like that right? Just a one time thing?

Branden Bonaby (bbonaby) · 2026-11-05T01:01:38Z

+- **Proxy URL with an IP or loopback address:** the workload can't reach
+  that address directly, so MXC replaces the URL's host with the controller's
+  address. A certificate can't match the replaced host, so these URLs must
+  use `http://`.


note: probably want to reject random ip addresses, but can it not get to localhost at all?

Branden Bonaby (bbonaby) · 2026-11-05T01:03:12Z

+7. **`egress.default: allow` plus `networkProxy` in proxied mode:** a denied
+   `ingress` or `hostLoopback` selects proxied mode, where the controller
+   forwards only to the custom proxy. `allow` and `deny` then behave the same.
+   Potential options:
+   - Reject it, like Bubblewrap. `deny` plus `networkProxy` gives the same
+     result.
+   - Accept it and document that `allow` has no effect with a custom proxy.
+
+   `BRIDGED` with everything allowed plus the cooperative proxy is unchanged
+   either way.


note: probably just reject it for now if it has no effect and then document it

Branden Bonaby (bbonaby) · 2026-11-05T01:07:32Z

+   - **Ownership record:** before creating them, MXC writes the names to a
+     file under `%LOCALAPPDATA%\mxc` and cleanup deletes only those names. A
+     lost record leaves leftovers in place but never deletes another tool's
+     resources.
+   - **Exact names:** derive every name from one MXC ID (`mxc-<id>` for the
+     workload via `WslcSetContainerSettingsName`, plus `-ctl`, `-int` and
+     `-out`), list networks with `WslcListSessionNetworks`, and delete only
+     full-pattern matches. Unlikely to collide, but not ruled out.
+   - **Default stores only:** skip cleanup when `wslc.storagePath` is set.
+   - Ask WSLC for SDK support for listing containers.


thought: we should ask them for a listing API for sure. But in the meantime, we probably can't do the owership thing since multiple apps could be using mxc at the same time. For the exact name, I suppose we could do that and add our own guid at the end? Assuming WslcSetContainerSettingsName can allow duplicates.

If the app crashes though, then I don't think we can do anything since all our internal state will be lost. Probably will need to document.

Branden Bonaby (bbonaby) · 2026-11-05T01:10:46Z

+4. **DNS and deny rules:** a deny rule covering UDP 53 is bypassed: the
+   controller's DNS lookups go through Docker's resolver (`127.0.0.11`), WSL
+   and Windows, which picks the server per name. 
+   Potential options:
+   - Query Windows' DNS servers directly, checking each IP against the rules
+     first (matches LXC). Stale after network changes; VPN DNS reachability
+     from WSLC is unverified.
+   - Turn DNS off when any deny rule covers UDP 53 (fail closed; over-blocks).
+   - Document DNS as outside egress rules.


thought: I don't think we can do anything about this until we get a general solution from the Networking team tbh. Process container has the same issue with dns bypass.

Branden Bonaby (bbonaby) · 2026-11-05T01:11:16Z

+1. **Provision `networkProxy`:** the controller is created at provision, so
+   it needs the proxy then. Today WSLC accepts the proxy only at exec
+   (`validate_provision_policy` rejects it), and the MXC request JSON
+   provision contract has no `runtimeConfig`. Rust and .NET typed provision
+   requests carry it; Node's doesn't. Potential options:
+   - Add `runtimeConfig` to the development provision contract and Node's
+     provision request.
+   - Support custom proxies only for create-and-run, and reject them for
+     lifecycle containers.


note: see comment above, I thought we already had this in place already

Branden Bonaby (bbonaby) · 2026-11-05T01:12:18Z

+3. **Controller image distribution:** a bundled tar or a registry, and how is
+   it signed? Owners: build maintainers.


thought: users should definitely bring their own imo that we use. Or it at least shouldn't be offered by us.

The main question isn't if someone should bring their own, the main question is, do we load the filtering script onto the container at runtime (e.g. using stock alpine), or do we bake it in on top of the base image and sign it?

Could be a feature request to add the option for a "custom proxy image".

when you say "filtering script" what's that? Checked the docs in this PR but I might be missing where it's talked about

The controller container will have the filtering script inside of it. The networking policy is converted into environment variables that are set on the controller container. The filtering script reads those env vars and creates network rules to follow the policy.

Branden Bonaby (bbonaby) · 2026-11-05T01:13:29Z

+2. **Host loopback on older runtimes:** Currently valid `BRIDGED` contracts running 
+   on WSL 3.0.3 will NOT get host loopback while those contracts running on 3.0.5 will. 
+   Is this acceptable?


thought: to me it is. We have a remediation field in our MxcError object that we can say "proxy support is only available on wsl 3.0.3 or higher"

Branden Bonaby (bbonaby) · 2026-11-05T22:17:50Z

+- **Implementation PRs:** Not started.
+
+WSLC networking today supports only all-allow (`BRIDGED`) or all-deny (`NONE`).
+This design adds a per-container controller container that enforces TCP CIDR


to confirm, is the controller container a seperate wsl container we spin up? or is it another executable the we'll add to mxc? just want to make sure I understand what controller means here is all.

Branden Bonaby (bbonaby) · 2026-11-05T22:31:48Z

+- **Cost:** one extra container and two networks per container, plus startup
+  time.
+
+## Open questions


note: lets see if we can update the doc to remove any answered questions before check in. I still had a question about what the controller is and whether it's a wslc concept or we're creating it ourselves.

The controller is an image we build from a Dockerfile during CI and ship with the binaries. The image will include the filtering script and the packages it needs. At build time, the hash of the image will be embedded into wxc-exec and the daemon. At runtime, MXC will only use the controller image with that hash.

Copilot

🟡 Changes recommended

Expanding Node v1’s closed BackendCapability union breaks compilation for existing consumers that rely on exhaustive mappings or switches.

1 open issue

Preserve Node v1's closed BackendCapability union · New

_{Review effort: Balanced}

Copilot

🟡 Changes recommended

Adding a member to Node V1’s closed BackendCapability union breaks source compatibility for existing callers using exhaustive switches or complete capability-keyed records.

2 open issues

_{Review effort: Balanced}

…updates.

Copilot

🔵 Needs a closer look

Human assessment is needed because crash recovery could mistake a pending reservation for confirmed ownership and force-delete another tool’s resource in shared storage.

No open issues 🎉

2 resolved since last review

_{Review effort: Balanced}

WSLC Built-in proxy feature spec

cd000f5

Elliot (theelliotm) requested a review from Soham Das (SohamDas2021) October 30, 2026 22:04

Elliot (theelliotm) self-assigned this Oct 30, 2026

Copilot AI balanced review requested due to automatic review settings October 30, 2026 22:04

Elliot (theelliotm) marked this pull request as ready for review October 30, 2026 22:04

Elliot (theelliotm) requested a review from a team October 30, 2026 22:04

Elliot (theelliotm) requested a review from a team as a code owner October 30, 2026 22:04

Copilot started reviewing on behalf of Elliot (theelliotm) October 30, 2026 22:04

View session

Copilot AI reviewed Oct 30, 2026

View reviewed changes

Comment thread docs/development/architecture/designs/1462-wslc-builtin-proxy/README.md Resolved

Comment thread docs/development/architecture/designs/1462-wslc-builtin-proxy/README.md Resolved

Comment thread docs/development/architecture/designs/1462-wslc-builtin-proxy/README.md Resolved

Branden Bonaby (bbonaby) added the Feature-Spec-In-Review Label for feature spec PRs that are currently in review label Oct 30, 2026

Elliot (theelliotm) added 2 commits October 30, 2026 17:24

address DNS deny rules question

e8b8f11

seperate relay address + ask how to identify orphaned containers

bb00f08

Copilot AI balanced review requested due to automatic review settings October 31, 2026 00:57

Copilot started reviewing on behalf of Elliot (theelliotm) October 31, 2026 00:58

View session

Copilot AI reviewed Oct 31, 2026

View reviewed changes

Comment thread docs/development/architecture/designs/1462-wslc-builtin-proxy/README.md Resolved

Soham Das (SohamDas2021) reviewed Nov 2, 2026

View reviewed changes

Copilot AI balanced review requested due to automatic review settings November 2, 2026 21:57

Address copilot's proxy concerns with TLS and exec vs. provision

cde3e68

Copilot started reviewing on behalf of Elliot (theelliotm) November 2, 2026 21:57

View session

Elliot (theelliotm) requested a review from Soham Das (SohamDas2021) November 2, 2026 21:59

Copilot AI reviewed Nov 2, 2026

View reviewed changes

Comment thread docs/development/architecture/designs/1462-wslc-builtin-proxy/README.md Resolved

Comment thread docs/development/architecture/designs/1462-wslc-builtin-proxy/README.md Resolved

Copilot AI balanced review requested due to automatic review settings November 2, 2026 22:34

address SDK concerns with non-proxied exec mode

407a3db

Copilot started reviewing on behalf of Elliot (theelliotm) November 2, 2026 22:34

View session

Copilot AI reviewed Nov 2, 2026

View reviewed changes

Soham Das (SohamDas2021) previously approved these changes Nov 3, 2026

View reviewed changes

Elliot (theelliotm) requested a review from Gudge (MGudgin) November 3, 2026 00:15

Jeff Whiteside (jsidewhite) reviewed Nov 3, 2026

View reviewed changes

Comment thread docs/development/architecture/designs/1462-wslc-builtin-proxy/api.md Resolved

Anis Mohammed Khaja Mohideen (kanismohammed) previously approved these changes Nov 4, 2026

View reviewed changes

Branden Bonaby (bbonaby) reviewed Nov 5, 2026

View reviewed changes

Elliot (theelliotm) mentioned this pull request Nov 5, 2026

[WSLC] Proxy Pt. 1: Update SDK to 3.0.5 #1679

Open

5 of 11 tasks

trevotai-amd mentioned this pull request Nov 5, 2026

How to limit a sandboxed agent to one endpoint in production? (request: packaged proxy sample) #1686

Open

Branden Bonaby (bbonaby) reviewed Nov 5, 2026

View reviewed changes

Answer all open questions

875e3ba

Elliot (theelliotm) dismissed stale reviews from Anis Mohammed Khaja Mohideen (kanismohammed) and Soham Das (SohamDas2021) via 875e3ba November 6, 2026 00:06

Elliot (theelliotm) requested review from Soham Das (SohamDas2021) and Branden Bonaby (bbonaby) and a balanced review from Copilot November 6, 2026 00:06

Copilot started reviewing on behalf of Elliot (theelliotm) November 6, 2026 00:07

View session

Copilot AI reviewed Nov 6, 2026

View reviewed changes

Comment thread docs/development/architecture/designs/1462-wslc-builtin-proxy/api.md Resolved

implementation details for embedded proxy

d164852

Copilot AI balanced review requested due to automatic review settings November 7, 2026 00:59

Copilot started reviewing on behalf of Elliot (theelliotm) November 7, 2026 00:59

View session

Copilot AI reviewed Nov 7, 2026

View reviewed changes

Comment thread docs/development/architecture/designs/1462-wslc-builtin-proxy/README.md Resolved

Elliot (theelliotm) added 2 commits November 9, 2026 13:51

clarification on how the tar is bundled, especially for Rust SDK users

59f5a7f

breaking change isn't really breaking, and has precedent in previous …

16b3d4e

…updates.

Copilot AI balanced review requested due to automatic review settings November 9, 2026 21:58

Copilot started reviewing on behalf of Elliot (theelliotm) November 9, 2026 21:58

View session

Copilot AI reviewed Nov 9, 2026

View reviewed changes

This was referenced Nov 9, 2026

[WSLC] Proxy Pt. 2: Enable session host loopback #1714

Open

[WSLC] Proxy Pt. 3: Add runtimeConfig to WSLC provision contract #1717

Open

[WSLC] Proxy Pt. 4: Apply the provision proxy to every exec #1719

Open

		3. Controller image distribution: a bundled tar or a registry, and how is
		it signed? Owners: build maintainers.

Conversation

Elliot (theelliotm) commented Oct 30, 2026 • edited by microsoft-github-policy-service Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Microsoft Reviewers: Open in CodeFlow

Uh oh!

azure-pipelines Bot commented Oct 30, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Elliot (theelliotm) Nov 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Elliot (theelliotm) Nov 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Elliot (theelliotm) commented Nov 4, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Branden Bonaby (bbonaby) Nov 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Elliot (theelliotm) commented Oct 30, 2026 •

edited by microsoft-github-policy-service Bot

Loading

Elliot (theelliotm) Nov 2, 2026 •

edited

Loading

Elliot (theelliotm) Nov 2, 2026 •

edited

Loading

Branden Bonaby (bbonaby) Nov 5, 2026 •

edited

Loading