Microsoft eXecution Container (MXC) Documentation

Bubblewrap (Bwrap) provides filesystem isolation through namespace enforcement with the following characteristics:

• Default-deny: If no --bind is specified, there is no access to the host filesystem. The base environment is a curated allowlist (defined by BASELINE_RO_BIND_PATHS) rather than a full bind of the host root (/).
• Subtree Mounting: Using --bind mounts the entire subtree of the target path.
• Implicit Traversal: bwrap automatically creates the parent directories of any --bind or --ro-bind destination as empty directories. This allows a path like RW /home/user/project/src to be reachable inside the namespace even if its parent directories are not explicitly bound, without exposing the host's actual parent content.
• Path Resolution: Path resolution follows a "most-specific-path-wins" rule (longest-prefix) via the filesystem_resolve.rs resolver in wxc_common.

A ContainerConfig is the complete configuration for a specific backend. It is generated via createConfigFromPolicy() and can be modified by the user before being passed to spawnSandboxFromConfig().

Key Rules:

• One backend per Config: A configuration is exclusive to one backend. For example, a Windows process config contains a processcontainer section but no lxc section. A Linux process config contains an lxc section but no processcontainer section.
• User-modifiable: Advanced users can override any field in the ContainerConfig before spawning.
• Schema-defined: Configs follow strict schemas (found in schemas/) and are mirrored by SDK TypeScript types.

All configs share common sections like filesystem, network, and ui. Backend-specific fields are scoped to their respective sections (e.g., processcontainer.ui for Windows process containment).

type ContainerConfig =
  | ProcessContainerConfig
  | LxcContainerConfig
  | MicroVmConfig;

The MXC Network Configuration is transitioning to a new GA (General Availability) schema. This schema replaces the legacy allowedHosts/blockedHosts/defaultPolicy format with a more structured approach defining egress, ingress, and proxy settings.

• Egress: Defines how traffic leaves the container. It uses a default policy (e.g., deny), an allow list containing destination CIDRs and specific protocol/port combinations, and a deny list for explicit blocks.
• Ingress: Controls incoming traffic; for example, setting hostLoopback to deny prevents the container from accessing the host's loopback interface.
• Proxy: Configures HTTP proxy settings (e.g., http key with a host/port string).

{
  "network": {
    "egress": {
      "default": "deny",
      "allow": [{ "to": [{ "cidr": "140.82.112.0/20" }], "ports": [{ "protocol": "tcp", "port": 443 }] }],
      "deny": [{ "to": [{ "cidr": "10.0.0.0/8" }] }]
    },
    "ingress": { "hostLoopback": "deny" },
    "proxy": { "http": "127.0.0.1:8080" }
  }
}

The LXC backend implements standard process.cwd and process.env fields:

Working Directory (process.cwd)

Implemented via a cd -- "$1" && exec /bin/sh -c "$2" wrapper.

• An empty string preserves the container's default CWD.
• Paths with spaces, quotes, $vars, or backticks are passed verbatim via positional arguments to avoid shell escaping issues.
• Non-existent or unpermitted paths result in a non-zero exit code (typically 1).

Environment Variables (process.env)

• Each KEY=VAL entry is passed via the --set-var=KEY=VAL flag to lxc-attach.
• Replace Semantics: If process.env is non-empty, lxc-exec uses --clear-env to prevent host environment leakage. The process.env values take precedence over the host.
• Malformed Entries: Entries without = or with an empty key (e.g., "=foo") are silently skipped.
• Baseline: Even with --clear-env, a small baseline (container, HOME, TERM, a default PATH, USER) is injected by lxc-attach.

MXC uses a default-deny outbound policy. To allow network access, you must explicitly list destinations in the configuration.

Key Rules:

• Default Deny: Unlisted destinations are unreachable. A configuration that mentions nothing grants nothing.
• Precedence: If a connection matches both an egress.allow rule and an egress.deny rule, the deny rule wins.
• Address Types: You must use IPv4/IPv6 literals or CIDRs. DNS names are rejected at validation time and cannot be used in rules.
• Default Behavior:
  • With egress.default: "deny", no matching allow means no outbound access.
  • With egress.default: "allow", no matching deny means unrestricted outbound.

Platform Enforcement:

• Windows: Uses WFP (Windows Filtering Platform) on process containers.
• Linux: Uses a network namespace and iptables on WSLc, LXC, or Bubblewrap backends.
• macOS: Uses a Seatbelt profile that restricts outbound traffic to the loopback proxy port.