Difference Between Network Proxy and Network Enforcement Modes in MXC

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.

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. 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, 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, 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.

Configuration Examples

Firewall-Based Enforcement (Linux LXC)

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

{
  "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, 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 to install container-scoped firewall rules.

Capabilities-Only Mode (Windows AppContainer)

For AppContainer-based isolation without installing firewall rules:

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

The AppContainer backend (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:

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

Launch the container with the proxy flag:

mxc run --config myconfig.json --proxy

The --proxy flag spawns the Linux test-proxy defined in 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:

{
  "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 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, using "capabilities", "firewall", or "both" strategies.
• Platform Implementation: LXC backends use src/backends/lxc/common/src/network_iptables.rs for firewall rules, while AppContainer uses 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.

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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}