Skip to content

v0.4.0-alpha.1

Pre-release
Pre-release

Choose a tag to compare

@github-actions github-actions released this 26 Oct 22:46
· 37 commits to main since this release
b806fd2

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 -p with a deny-default profile), bubblewrap on Linux (with a PID namespace and --die-with-parent), or, for a container where MELRA runs as root with CAP_SETUID and CAP_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, ~/.gnupg and more); under uid that 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 the network trait: 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's sandbox key sets use (on, off, if-available), symlinks (commands that may make links), readable (logins to allow back) and user (the uid sandbox's account). Each receipt from a kernel with the sandbox on names it beside mode (seatbelt, bubblewrap, uid), or none where if-available let enforced mode start without one, and the approval console's task detail shows it; with the sandbox off a receipt has no sandbox field. See per-command sandbox.
  • melra doctor has a sandbox line: 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 launch gives claude, and so the server claude starts, neither MELRA_PAYLOAD_KEY nor MELRA_HTTP_TOKEN. With the payload key set only in the variable, it refuses with payload_key_missing until the key is in <MELRA_HOME>/payload.key (mode 0600).
  • In enforced mode, MELRA warns at startup, and melra doctor warns on a new environment line, while MELRA_PAYLOAD_KEY or MELRA_HTTP_TOKEN is set in its own environment, naming the fix: the key in payload.key (mode 0600), the token left unset. Nothing is refused.
  • When a terminal run finishes, 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-shot melra run included. Its shutdown also stops a run still going, as it stops a background job.
  • On macOS, a file read, hash or write is judged by the path with its links resolved and then opened following no link, so a link that appears in between fails with path_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.readable lists them. Under Seatbelt and bubblewrap they also cannot write outside the workspace and temp, reach the network without the network trait, or make symbolic links unless they install packages or sandbox.symlinks names them, so a git checkout of a repository holding links fails with EPERM until git is named. Under Seatbelt setuid programs such as ps and sudo do not start; under bubblewrap 32-bit binaries and io_uring fail with EPERM, 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 a sandbox.user account works; and on a Mac under examples/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 1000 with only CAP_SETUID and CAP_SETGID, its data and policy file in the image's root-only /var/lib/melra and /etc/melra, and each command as node; 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, ProtectKernelLogs or ProtectHostname, under which it cannot mount a /proc of its own.

Security

  • File reads, hashes and file_hash evidence 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 run left 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 launch starts, and the helper serve --open and melra console open 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.