Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
133 changes: 79 additions & 54 deletions docs/backends/wslc/wsl-container-getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -523,8 +523,8 @@ no separate `--setup-wslc` step is required.

| Type | Exact policy | WSLC behavior |
|---|---|---|
| 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. |
| 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. |
| Bridged | Egress and ingress defaults `allow`, without egress rules. Container lifecycle operations also require the host-loopback default `allow`. | 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. In create-and-run execution with `hostLoopback: "allow"`, it reaches Windows `127.0.0.1` at `host.wslc.internal`; otherwise it can't. Nothing else is filtered. |
| Isolated | All three defaults omitted or `deny`, without egress allow rules, port mappings, or `runtimeConfig.networkProxy` | No networking. The container only has its own loopback interface. It can't reach anything outside itself, and nothing can reach it. |
| Built-in proxy | Any other combination, create-and-run execution | Egress filtered by the [built-in proxy](#built-in-proxy) |
| Built-in proxy | Any other combination, container lifecycle operations | Rejected |

Expand Down Expand Up @@ -554,7 +554,8 @@ as follows:
- It joins only the internal network.
- `NET_RAW` is dropped, so the workload can't send raw frames to the proxy container.
- `HTTP_PROXY`/`HTTPS_PROXY` (and the lower-case forms) point at
`http://10.231.1.254:3128`, `NO_PROXY` is empty
`http://10.231.1.254:3128`, or at the [custom proxy](#custom-proxy);
`NO_PROXY` is empty, or `host.wslc.internal` with [host loopback](#host-loopback)
- `/etc/resolv.conf` is a read-only mount of a host temporary file naming
`10.231.1.254`.
- Node is told to use the proxy: `NODE_USE_ENV_PROXY` is `1` (can be overwritten with `env`)
Expand Down Expand Up @@ -583,8 +584,7 @@ as follows:
- Rejected with the proxy: `allow` entries for any protocol except `tcp`
(including entries without `ports`, which cover every protocol; use
`"ports": [{ "protocol": "tcp" }]` for every TCP port), IPv6
CIDRs, targets inside `10.231.0.0/16`, `hostLoopback: "allow"`, and
`runtimeConfig.networkProxy`. `deny` entries
CIDRs, and targets inside `10.231.0.0/16`. `deny` entries
for `udp` or `icmp` have no effect, because only TCP leaves through the
proxy, and log a warning.

Expand All @@ -600,6 +600,56 @@ as follows:
- Denied requests and refused lookups appear in the run log as
`[WSLC][gateway]` lines.

#### Host loopback

With `network.ingress.hostLoopback: "allow"`, the workload reaches TCP
services on Windows `127.0.0.1` at `host.wslc.internal`, on any port.

- `host.wslc.internal` resolves to `10.231.1.3`, which the proxy container
relays to Windows. Requests through the proxy reach it too. Egress rules
don't apply to it.

- Only Windows `127.0.0.1` is reachable, not other `127.0.0.0/8` addresses or `::1`.

- The proxy container is granted `NET_ADMIN` to add the relay address. If the
`AllowWSLContainerPrivileged` policy forbids it, the run is rejected.

- With `hostLoopback: "deny"`, the proxy refuses lookups and requests for
`host.wslc.internal`.

- Not available with container lifecycle operations. For bridged networking,
see [Network configuration](#network-configuration).

#### Custom proxy

With `runtimeConfig.networkProxy`, `network.egress.default: "deny"`, and no
egress rules, the built-in proxy relays the workload to your proxy and
nothing else. Your proxy decides where traffic goes.

- The workload reaches your proxy at `10.231.1.254`, on your proxy's port.

- A hostname URL is passed to the workload unchanged. MXC resolves the
hostname on Windows when the run starts, and the built-in proxy answers
lookups for it with `10.231.1.254`. This is how to use an `https://` proxy:
its certificate still matches the name.

- An IP address is replaced with `10.231.1.254` in the workload's proxy
variables. For example, `http://192.0.2.10:8080` becomes
`http://10.231.1.254:8080/`. Credentials are kept.

- A proxy on Windows loopback must use `http://127.0.0.1` or
`http://localhost`. The built-in proxy relays to it through
`host.wslc.internal`; the workload still can't reach `host.wslc.internal`
unless [host loopback](#host-loopback) is allowed.

- DNS lookups are forwarded. [Port mappings](#port-mappings) work as usual.

- Rejected: egress rules, `network.egress.default: "allow"` without bridged
networking, `https://` with an IP address or `localhost`, IPv6 addresses,
addresses inside `10.231.0.0/16`, port 53, hostnames with no IPv4 address on
Windows or that resolve to loopback, and other loopback addresses
(`127.0.0.2`, `0.0.0.0`).

#### Cleanup

- After the workload exits, times out, or is killed, MXC deletes both
Expand Down Expand Up @@ -628,54 +678,42 @@ as follows:

### External network proxy (cooperative, unprivileged)

WSLC supports a **cooperative HTTP/HTTPS proxy**: setting `runtimeConfig.networkProxy`
routes a container's egress through a proxy you provide. WSLC cannot apply an
`iptables` drop-floor β€” the container has no `CAP_NET_ADMIN` and MXC has no
VM-level enforcement hook β€” so
enforcement is *cooperative*, applied by handing the workload proxy environment
variables that well-behaved clients honor.

**How it works**

1. When `runtimeConfig.networkProxy` is set, MXC translates it into the
`HTTP_PROXY`, `HTTPS_PROXY`, `http_proxy`, and `https_proxy` environment
variables inside the container (via `WslcSetProcessSettingsEnvVariables`).
Any caller-supplied values for these keys β€” including `NO_PROXY` /
`no_proxy` β€” are **stripped** from the *initial* process environment first.
Because WSLC merges the process environment onto the image's baked-in
`ENV`, MXC also sets `NO_PROXY` / `no_proxy` to the **empty string**,
so an image-baked exemption (e.g. `ENV NO_PROXY=*`) cannot silently disable
the proxy. This sanitizes the process's *starting* environment only; see the
cooperative-model caveat below.
2. Cooperative tools (curl, wget, Python `requests`, Node `https`, etc.) honor
the env vars and their traffic flows through the proxy.

**The runtime field contains a URL string.** A WSLC container runs in its own
network namespace (a separate WSL system VM). Its own `127.0.0.1` loopback is
valid for a proxy running inside that container, as in the test fixture below;
a proxy on the host's or WSL distro's loopback is **not reachable**. An external
proxy must have an address routable from the container:
With [bridged](#network-configuration) networking, `runtimeConfig.networkProxy`
is cooperative: MXC gives the workload proxy settings, and clients that honor
them use your proxy. With any other policy, it goes through the built-in proxy
instead; see [Custom proxy](#custom-proxy).

- MXC sets `HTTP_PROXY`, `HTTPS_PROXY`, `http_proxy` and `https_proxy` to the
URL, and `NO_PROXY`/`no_proxy` to empty so an image's `ENV NO_PROXY` can't
bypass it. Caller-supplied values for these keys are dropped.

- Nothing is enforced. Clients that ignore the variables (raw sockets, some
static binaries) connect directly, and the workload can change its own
environment. To enforce the proxy, deny egress so the built-in proxy relays
to it.

- The URL must be reachable from the container. `127.0.0.1` is the
container's own loopback; reach Windows loopback at `host.wslc.internal`
with [`hostLoopback: "allow"`](#network-configuration).

- Container lifecycle operations set the proxy on `exec`, not at provision.

This create-and-run example uses a proxy on Windows `127.0.0.1:8888`:

```json
{
"version": "0.9.0-alpha",
"version": "1.0.0",
"containment": "wslc",
"process": { "commandLine": "curl -fsSL https://example.com && echo OK" },
"process": { "commandLine": "wget -qO- http://example.com && echo OK" },
"network": {
"egress": { "default": "allow" },
"ingress": { "default": "allow", "hostLoopback": "allow" }
},
"runtimeConfig": { "networkProxy": "http://proxy.example:8080" },
"runtimeConfig": { "networkProxy": "http://host.wslc.internal:8888" },
"wslc": { "image": "alpine:latest" }
}
```

The removed `network.proxy` object and its `localhost`/`builtinTestServer`
forms are rejected by schema `0.9.0-alpha`. Create-and-run proxy use requires the unrestricted
bridged posture shown above; a proxy cannot make isolated networking reach an
external listener. Execution in an existing container (`exec`) instead supplies only `runtimeConfig` and
inherits its provisioned network posture.

### Filtering for container lifecycle operations

Container lifecycle operations do not use the built-in proxy yet. A
Expand All @@ -701,19 +739,6 @@ requires explicit host-to-container forwards through `wslc.portMappings`
(create-and-run execution) or `wslc.provision.portMappings` (container lifecycle operations);
`ingress.default: "allow"` alone does not create them.

**Caveats**

- **Cooperative model, not enforcement.** Only clients that honor the proxy
env vars are routed through the proxy. Tools that bypass them (raw sockets,
custom HTTP clients, statically-linked binaries that ignore the env) are
**not** contained. WSLC cannot provide a hard network floor β€” the container
has no `CAP_NET_ADMIN` and MXC has no VM-level enforcement hook. For strict
network isolation in v0.9, use the deny/deny/deny posture instead.
- **Consumer-provided proxy.** MXC does not start a proxy for WSLC; you supply
a reachable URL via `runtimeConfig.networkProxy`. Host filtering is the
proxy's responsibility; directional rules cannot be combined to create a
firewall WSLC does not have.

### Filesystem mounts

Paths in `filesystem.readwritePaths` and `filesystem.readonlyPaths` are mounted
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -602,7 +602,6 @@ public async Task Spawn_BuiltInProxyIsRemovedAfterKill()
public static TheoryData<string, string> UnenforceableEgressCases() => new()
{
{ "external proxy", "runtimeConfig.networkProxy cannot be combined with egress filtering" },
{ "host loopback", "hostLoopback 'allow' cannot be combined with egress filtering" },
{ "UDP allow", "network.egress.allow supports only protocol 'tcp' (got 'udp')" },
{ "IPv6", "network.egress CIDR 2606:4700::/32 is IPv6" },
{ "reserved subnet", "which the built-in proxy reserves for its own networks" },
Expand All @@ -619,9 +618,6 @@ public async Task BuiltInProxyRejectsEgressItCannotEnforceBeforeStartingAContain
case "external proxy":
network.RuntimeConfig = new NetworkRuntimeConfig { NetworkProxy = "http://127.0.0.1:8888" };
break;
case "host loopback":
network.Ingress!.HostLoopback = NetworkAction.Allow;
break;
case "UDP allow":
network.Egress!.Allow = [Rule("1.1.1.1/32", NetworkProtocol.Udp, 53)];
break;
Expand Down
3 changes: 0 additions & 3 deletions sdk/node/tests/integration/wslc-e2e.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -620,12 +620,9 @@ describe('WSLC SDK E2E β€” built-in proxy', {
});

it('should reject egress rules the built-in proxy cannot enforce before starting a container', { timeout: 120_000 }, async () => {
const rules = ALLOW_CLOUDFLARE_443.egress!;
const cases: Array<[string, NetworkPolicy, Record<string, unknown>, string]> = [
['external proxy', { ...ALLOW_CLOUDFLARE_443, runtimeConfig: { networkProxy: 'http://127.0.0.1:8888' } }, {},
'runtimeConfig.networkProxy cannot be combined with egress filtering'],
['host loopback', { egress: rules, ingress: { default: 'deny', hostLoopback: 'allow' } }, {},
"hostLoopback 'allow' cannot be combined with egress filtering"],
['UDP allow', { egress: { default: 'deny', allow: [{ to: [{ cidr: '1.1.1.1/32' }], ports: [{ protocol: 'udp', port: 53 }] }] }, ingress: DENY_INGRESS }, {},
"network.egress.allow supports only protocol 'tcp' (got 'udp')"],
['IPv6', { egress: { default: 'deny', allow: [{ to: [{ cidr: '2606:4700::/32' }], ports: [{ protocol: 'tcp', port: 443 }] }] }, ingress: DENY_INGRESS }, {},
Expand Down
Loading
Loading