# Difference Between Network Proxy and Network Enforcement Modes in MXC

> Understand the key differences between MXC network proxy mode (user-space HTTP proxy) and network enforcement mode (kernel-level restrictions) for effective network control.

- Repository: [Microsoft/mxc](https://github.com/microsoft/mxc)
- Tags: deep-dive
- Published: 2026-06-07

---

**Network proxy mode runs a user-space HTTP proxy for per-host filtering, while network enforcement mode applies kernel-level restrictions via OS capabilities, firewall rules, or both.**

Microsoft's MXC (Multi-Platform eXecution Container) provides two orthogonal mechanisms for restricting container network traffic. Understanding the **difference between network proxy and network enforcement modes in MXC** is essential for deploying secure workloads, as one operates entirely in user space while the other enforces policies at the kernel level via backend-specific implementations.

## What Is Network Proxy Mode?

Network proxy mode intercepts every outbound connection through a user-space HTTP/HTTPS proxy that makes per-host allow/deny decisions. When you enable this mode with the `--proxy` flag, MXC spawns a tiny test-proxy binary that filters traffic based on the `allowedHosts` configuration list before requests reach the network stack.

This approach is implementation-agnostic and requires no elevated privileges, making it the default for **Bubblewrap** containers that lack access to firewall capabilities. The proxy implementations reside in `src/testing/linux_test_proxy/` (Linux) and `src/testing/wxc_test_proxy/` (Windows), with the main entry point defined in [`src/testing/linux_test_proxy/src/main.rs`](https://github.com/microsoft/mxc/blob/main/src/testing/linux_test_proxy/src/main.rs).

### When to Use Network Proxy

Use proxy mode when you need to restrict outbound connections to a small whitelist of external hosts (for example, `example.com`) while running the container unprivileged. It is particularly effective for scenarios requiring fine-grained host filtering without kernel-level access or administrative rights.

## What Is Network Enforcement Mode?

Network enforcement mode controls access at the kernel or OS level through three distinct strategies defined in [`src/core/wxc_common/src/models.rs`](https://github.com/microsoft/mxc/blob/main/src/core/wxc_common/src/models.rs). Unlike the user-space proxy, these mechanisms rely on system-level primitives to block traffic before it enters the network stack, configured via the JSON field `network.enforcementMode`.

### Capabilities Strategy

The **capabilities** strategy restricts network access using low-level OS capabilities. On Linux, this involves `net_raw` and `net_admin` privileges; on Windows, it leverages AppContainer network capabilities. The implementation for AppContainer resides in [`src/backends/appcontainer/common/src/network_manager.rs`](https://github.com/microsoft/mxc/blob/main/src/backends/appcontainer/common/src/network_manager.rs), which adds the necessary capability restrictions to the container process.

### Firewall Strategy

The **firewall** strategy installs container-scoped firewall rules using platform-specific mechanisms. On Linux, MXC utilizes `iptables` through [`src/backends/lxc/common/src/network_iptables.rs`](https://github.com/microsoft/mxc/blob/main/src/backends/lxc/common/src/network_iptables.rs), specifically calling functions like `apply_iptables_rules`. On Windows, it configures Windows Firewall policies. This strategy requires elevated privileges but provides robust, kernel-enforced network isolation.

### Combining Both Strategies

Setting `enforcementMode` to `"both"` applies capabilities restrictions **and** firewall rules simultaneously, creating the most restrictive environment. This defense-in-depth approach ensures that even if one mechanism fails, the other continues to block unauthorized traffic at the system level.

## How the Mechanisms Interact

The proxy and enforcement modes operate independently. When `enforcementMode` is set to `"capabilities"` or `"both"`, MXC may still launch the proxy if the `--proxy` flag is provided, resulting in layered filtering. However, when the mode is `"firewall"`, the proxy is effectively redundant because the kernel-level rules already block all disallowed traffic before it reaches the application layer.

If you request capabilities mode on a platform that cannot set those capabilities—such as non-Administrative Windows sessions—MXC falls back to proxy-only operation and emits a warning, as implemented in [`src/host/wxc_winhttp_proxy_shim/src/proxy_policy.rs`](https://github.com/microsoft/mxc/blob/main/src/host/wxc_winhttp_proxy_shim/src/proxy_policy.rs).

## Configuration Examples

### Firewall-Based Enforcement (Linux LXC)

To enforce network restrictions using kernel-level iptables rules for LXC containers:

```json
{
  "process": { "commandLine": "powershell -NoProfile -c \"Write-Host Hello\"" },
  "network": {
    "enforcementMode": "firewall"
  }
}

```

When MXC parses this JSON in [`src/core/wxc_common/src/config_parser.rs`](https://github.com/microsoft/mxc/blob/main/src/core/wxc_common/src/config_parser.rs), it sets `policy.network_enforcement_mode = NetworkEnforcementMode::Firewall`. The LXC backend then calls `apply_iptables_rules` in [`src/backends/lxc/common/src/network_iptables.rs`](https://github.com/microsoft/mxc/blob/main/src/backends/lxc/common/src/network_iptables.rs) to install container-scoped firewall rules.

### Capabilities-Only Mode (Windows AppContainer)

For AppContainer-based isolation without installing firewall rules:

```json
{
  "process": { "commandLine": "notepad.exe" },
  "network": {
    "enforcementMode": "capabilities"
  }
}

```

The AppContainer backend ([`src/backends/appcontainer/common/src/network_manager.rs`](https://github.com/microsoft/mxc/blob/main/src/backends/appcontainer/common/src/network_manager.rs)) configures the `NET_RAW` and `NET_ADMIN` capabilities. No iptables rules are created, relying solely on OS-level capability restrictions to limit network access.

### Proxy with Allowed Hosts (Bubblewrap)

To filter traffic through the user-space proxy with an explicit host whitelist:

```json
{
  "process": { "commandLine": "curl https://example.com" },
  "network": {
    "allowedHosts": ["example.com"],
    "enforcementMode": "capabilities"
  }
}

```

Launch the container with the proxy flag:

```bash
mxc run --config myconfig.json --proxy

```

The `--proxy` flag spawns the Linux test-proxy defined in [`src/testing/linux_test_proxy/src/main.rs`](https://github.com/microsoft/mxc/blob/main/src/testing/linux_test_proxy/src/main.rs). The proxy validates each outbound HTTP request against the `allowedHosts` list, blocking unauthorized destinations before they leave the container.

### Defense-in-Depth Configuration

For maximum restriction, combine firewall rules with proxy filtering:

```json
{
  "network": {
    "enforcementMode": "both",
    "allowedHosts": ["example.com"]
  }
}

```

This configuration first installs restrictive firewall rules via the backend-specific implementation (for example, [`src/backends/lxc/common/src/network_iptables.rs`](https://github.com/microsoft/mxc/blob/main/src/backends/lxc/common/src/network_iptables.rs) for LXC), then launches the proxy to permit only connections to `example.com`. This ensures redundant layers of protection.

## Summary

- **Network Proxy**: A user-space HTTP CONNECT proxy that filters traffic per-host based on the `allowedHosts` list, implemented in `src/testing/linux_test_proxy/` and `src/testing/wxc_test_proxy/`.
- **Network Enforcement**: Kernel-level restrictions configured via `network.enforcementMode` in [`src/core/wxc_common/src/models.rs`](https://github.com/microsoft/mxc/blob/main/src/core/wxc_common/src/models.rs), using `"capabilities"`, `"firewall"`, or `"both"` strategies.
- **Platform Implementation**: LXC backends use [`src/backends/lxc/common/src/network_iptables.rs`](https://github.com/microsoft/mxc/blob/main/src/backends/lxc/common/src/network_iptables.rs) for firewall rules, while AppContainer uses [`src/backends/appcontainer/common/src/network_manager.rs`](https://github.com/microsoft/mxc/blob/main/src/backends/appcontainer/common/src/network_manager.rs) for capability management.
- **Graceful Degradation**: When capabilities cannot be set (for example, on Windows without admin rights), MXC falls back to proxy-only mode with a warning via [`src/host/wxc_winhttp_proxy_shim/src/proxy_policy.rs`](https://github.com/microsoft/mxc/blob/main/src/host/wxc_winhttp_proxy_shim/src/proxy_policy.rs).

## Frequently Asked Questions

### Can I use network proxy and enforcement mode together?

Yes. When `enforcementMode` is set to `"capabilities"` or `"both"` and you specify the `--proxy` flag, MXC launches both mechanisms simultaneously. The proxy provides application-layer filtering while capabilities or firewall rules provide system-layer restrictions. However, if `enforcementMode` is `"firewall"`, the proxy becomes redundant because the kernel-level firewall already blocks disallowed traffic before the application layer.

### Which mode should I use for Bubblewrap containers?

Use **network proxy mode** for Bubblewrap containers. Because Bubblewrap lacks privileged firewall capabilities, it cannot utilize the `"firewall"` or `"both"` enforcement strategies. The proxy mode (enabled via `--proxy`) provides the only mechanism for network restriction in these environments, filtering outbound connections through the user-space proxy before they reach the network interface.

### What happens if I request capabilities mode without administrative privileges?

If you configure `enforcementMode: "capabilities"` on Windows without administrative privileges, MXC attempts to set AppContainer capabilities but falls back to proxy-only operation when the capability assignment fails. The system emits a warning through [`src/host/wxc_winhttp_proxy_shim/src/proxy_policy.rs`](https://github.com/microsoft/mxc/blob/main/src/host/wxc_winhttp_proxy_shim/src/proxy_policy.rs) and continues execution using the user-space proxy for network filtering rather than terminating with an error.

### Does network enforcement mode require elevated privileges?

The **firewall** strategy requires elevated privileges to install container-scoped rules (iptables on Linux or Windows Firewall rules). The **capabilities** strategy requires privileges only to initially set process capabilities, though these can sometimes be inherited depending on the platform configuration. The proxy mode requires no elevation, making it suitable for unprivileged container runtimes like Bubblewrap.