Skip to main content

Security model

MSL runs Linux distributions in one lightweight virtual machine on behalf of one macOS user. This page describes the boundaries that set, what each side can reach, and the known weak spots.

What runs where​

  • msl and its service, msld, run as your macOS user, never as root. msld holds one entitlement, com.apple.security.virtualization, which Virtualization.framework needs to start a VM. The two processes msld starts to carry data, msl-portd (forwarded ports) and msl-fileviewd (~/.msl/distros), also run as your user and hold no entitlements.
  • The Linux kernel and every distribution run inside the VM. Root in a distribution is root in that distribution's namespaces, not on macOS.
  • Installing MSL needs no administrator rights, unless you choose a system prefix such as /usr/local. MSL installs no kernel extension or login item. Its LaunchAgent, ~/Library/LaunchAgents/dev.msl.msld.plist, runs nothing at login: launchd starts msld, as your user, when you first run msl.

Isolation​

The VM is the security boundary between Linux and macOS.

Distributions aren't isolated from each other by separate VMs. As in WSL 2, they share one kernel and one network namespace, and each has its own mount, PID, UTS and cgroup namespaces. Treat all your distributions as one trust zone: they share the VM's localhost, and no VM boundary separates one distribution's root from another's.

What macOS exposes to Linux​

By design, every distribution gets:

  • the macOS filesystem at /mnt/macos, with your macOS user's permissions. Any Linux user in any distribution can read and write what you can;
  • name resolution through macOS's resolver;
  • outbound network access through NAT.

MSL never runs macOS programs from Linux, and never puts macOS paths on the Linux PATH. There's no equivalent of WSL's Windows interop.

What Linux exposes to macOS​

WhatWho can reach it
The control socket, ~/Library/Application Support/msl/msld.sockYour user only (mode 0600).
Streams the VS Code extension opens into a distribution, with msl --connect through the control socketYour user only. A stream reaches a distribution as its default user, to a local TCP port or to a Unix socket under ~/.vscode-server/msl/; other Unix sockets are refused.
Forwarded ports on 127.0.0.1 and ::1Every local user on the Mac, as with WSL's localhost forwarding. Nothing is published on other interfaces. Turn forwarding off with localhostForwarding = false.
Distribution files in ~/.msl/distrosYour user only; see below.

The ~/.msl/distros file view​

Each distribution's files are served to macOS over NFSv3 through a Unix socket in MSL's folder (mode 0600), not a network port. macOS's NFS client connects from the kernel as root, so the socket's permissions alone wouldn't stop another local user from mounting it. MSL therefore checks every NFS call (in msl-fileviewd, which carries the files): only calls that carry your user ID or root's (the kernel's own) get through, and a mount is accepted only while msld itself is mounting (#1). Another local user can't mount the view, and gets an authentication error for anything in your mounts.

warning

With fileViewTransport = tcp in ~/.mslconfig, the view is served on a 127.0.0.1 port instead. The same checks apply, but any local program can connect to the port and claim any user ID. Don't use that setting on a Mac that other people log in to.

Releases​

  • The current MSL, kernel and VS Code extension releases are built by GitHub Actions and include SHA-256 checksum files. Their checksums are not PGP-signed.
  • MSL's macOS executables are signed ad hoc, not notarised. install.sh checks the MSL archive checksum and removes the macOS quarantine attribute from installed files.
  • If you'd rather not pipe install.sh into a shell, read it first: it's short. Or download the release yourself and install it with --from; see Install MSL.

Verify the MSL archive by hand​

Download the MSL archive and its .sha256 file from the latest MSL release, then run:

$ shasum -a 256 -c msl-<version>-macos-arm64.tar.gz.sha256

Supported versions​

Only the latest release gets security fixes. Update with msl --update.

Report a vulnerability​

Report vulnerabilities privately, with GitHub's Report a vulnerability button on the msl Security tab. Don't open a public issue.

Include the MSL version (msl --version), your macOS version and the steps to reproduce. You'll get an acknowledgement within 7 days. Once a fix is released, a GitHub security advisory announces it and credits you, unless you'd rather not be named.