Repository navigation
v0.4.0-alpha.1
Pre-release
Pre-release
·
37 commits
to main
since this release
Added
- A per-command OS sandbox: each command the terminal adapter starts can run in one made for it, chosen once at startup by trying a harmless command. Seatbelt on macOS (
sandbox-exec -pwith a deny-default profile), bubblewrap on Linux (with a PID namespace and--die-with-parent), or, for a container where MELRA runs as root withCAP_SETUIDandCAP_SETGID, another account (uid). In each a command cannot read MELRA's data, the policy file, the secret files or the logins tools keep under home (~/.ssh,~/.aws,~/.config/gh,~/.npmrc,~/.netrc,~/.docker/config.json,~/.kube,~/.gnupgand more); underuidthat is the account's own permissions, which MELRA checks at startup. Under Seatbelt and bubblewrap it also writes only in the workspace and temp, makes no symbolic link unless it installs packages or the policy file names it, and reaches no network without thenetworktrait: Seatbelt opens it no socket, and with the trait only IP and DNS, while bubblewrap gives it an empty network namespace, where Unix sockets on the filesystem stay reachable. It is on in enforced mode and off in developer mode unless the policy file turns it on, and never under unsafe-local. The policy file'ssandboxkey setsuse(on,off,if-available),symlinks(commands that may make links),readable(logins to allow back) anduser(theuidsandbox's account). Each receipt from a kernel with the sandbox on names it besidemode(seatbelt,bubblewrap,uid), ornonewhereif-availablelet enforced mode start without one, and the approval console's task detail shows it; with the sandbox off a receipt has nosandboxfield. See per-command sandbox. melra doctorhas asandboxline: which sandbox works on this host, or why none does and how to fix it. It fails where the server would refuse to start, and warns where enforced mode starts on the opt-out.
Changed
- Breaking: the browser MELRA launches starts with
--webrtc-ip-handling-policy=disable_non_proxied_udp, in every mode, so a page's WebRTC no longer sends UDP; a site that needs WebRTC over UDP does not get it there. A browser attached over CDP is unchanged. - Breaking:
melra launchgives claude, and so the server claude starts, neitherMELRA_PAYLOAD_KEYnorMELRA_HTTP_TOKEN. With the payload key set only in the variable, it refuses withpayload_key_missinguntil the key is in<MELRA_HOME>/payload.key(mode0600). - In enforced mode, MELRA warns at startup, and
melra doctorwarns on a newenvironmentline, whileMELRA_PAYLOAD_KEYorMELRA_HTTP_TOKENis set in its own environment, naming the fix: the key inpayload.key(mode0600), the token left unset. Nothing is refused. - When a terminal
runfinishes, what it left in its process group now gets SIGKILL a second after SIGTERM if it is still there (POSIX), and MELRA does not exit before that second is out, a one-shotmelra runincluded. Its shutdown also stops a run still going, as it stops a background job. - On macOS, a file
read,hashorwriteis judged by the path with its links resolved and then opened following no link, so a link that appears in between fails withpath_changed. - Breaking: with the sandbox on in enforced mode, commands that ran before can now fail. In every backend they cannot read the logins under home unless
sandbox.readablelists them. Under Seatbelt and bubblewrap they also cannot write outside the workspace and temp, reach the network without thenetworktrait, or make symbolic links unless they install packages orsandbox.symlinksnames them, so agit checkoutof a repository holding links fails withEPERMuntil git is named. Under Seatbelt setuid programs such aspsandsudodo not start; under bubblewrap 32-bit binaries andio_uringfail withEPERM, and what a background job leaves running ends when its program does. - Breaking: enforced mode refuses to start where no per-command sandbox works (
sandbox_unavailable, naming why and the fix): on Windows; on Linux where neither bubblewrap (x86_64 or aarch64, with unprivileged user namespaces, which Ubuntu 24.04 restricts by default) nor asandbox.useraccount works; and on a Mac underexamples/deploy/macos/melra.sb, which macOS will not nest a profile in. It also refuses where the policy file sets"use": "off"(enforced_mode_refuses_sandbox_off)."sandbox": {"use": "if-available"}in the policy file is the recorded opt-out. - Breaking: the container pair runs MELRA as root in group
1000with onlyCAP_SETUIDandCAP_SETGID, its data and policy file in the image's root-only/var/lib/melraand/etc/melra, and each command asnode; what either creates in the workspace is group-writable. The agent runs as root with no capabilities, to reach MELRA's socket. The workspace must be writable by both. - The systemd unit allows the namespaces, mount calls and netlink sockets bubblewrap needs, and no longer sets
ProtectKernelTunables,ProtectKernelLogsorProtectHostname, under which it cannot mount a/procof its own.
Security
- File reads, hashes and
file_hashevidence open a file once and judge what was opened, so something put in its place after the check can neither hang the read nor be read unless it passes the same check (macOS and Linux; Windows opens once only). On macOS a write's temporary file is created the same way. - A process a terminal
runleft in its process group can no longer outlive the run, or MELRA's shutdown, by ignoring SIGTERM. - Page script in MELRA's own browser can no longer send data over UDP, outside the destination checks, and a browser replaying an HTTP archive sends what the archive does not serve, such as WebSockets, through those checks.
- The browser MELRA launches, the agent
melra launchstarts, and the helperserve --openandmelra consoleopen a browser with no longer inherit the payload key or the HTTP token from MELRA's environment. - The payload key file is decoded without the key ever becoming a string, and its bytes are cleared once read.
- Commands the terminal adapter runs in enforced mode, unless the policy file records the opt-out, no longer have all of MELRA's own rights: the operating system keeps them away from MELRA's records, keys and policy file and from the logins under home, and under Seatbelt or bubblewrap also from writing outside the workspace and temp, from IP networks unless their traits need it, and from making symbolic links unless they install packages or the policy file names them.