From 75e703e1a473a25ce456802c637b05264863bda5 Mon Sep 17 00:00:00 2001
From: mwiegand <martin.wiegand@seibert.group>
Date: Fri, 8 May 2026 15:53:21 +0200
Subject: [PATCH] feat(deploy): left4me-script-sandbox helper + sudoers
 fragment

Privileged bash helper that wraps user-authored scripts in
systemd-run --scope (cgroup limits + RuntimeMaxSec=3600) inside a
bubblewrap sandbox dropped to the l4d2-sandbox uid. Network is shared
with the host so scripts can fetch from Steam / l4d2center / etc.;
filesystem is RO except for /overlay (rw bind from
/var/lib/left4me/overlays/{id}) and tmpfs /tmp + /run.

Adds a sudoers rule allowing the left4me user to invoke this helper
without restrictions on its arguments. Strict argument validation is
in the helper itself.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 deploy/files/etc/sudoers.d/left4me            |  1 +
 .../libexec/left4me/left4me-script-sandbox    | 55 ++++++++++++++++++
 deploy/tests/test_deploy_artifacts.py         | 57 +++++++++++++++++++
 3 files changed, 113 insertions(+)
 create mode 100755 deploy/files/usr/local/libexec/left4me/left4me-script-sandbox

diff --git a/deploy/files/etc/sudoers.d/left4me b/deploy/files/etc/sudoers.d/left4me
index 02cccc6..5aa94eb 100644
--- a/deploy/files/etc/sudoers.d/left4me
+++ b/deploy/files/etc/sudoers.d/left4me
@@ -2,3 +2,4 @@ Defaults:left4me !requiretty
 left4me ALL=(root) NOPASSWD: /usr/local/libexec/left4me/left4me-systemctl *
 left4me ALL=(root) NOPASSWD: /usr/local/libexec/left4me/left4me-journalctl *
 left4me ALL=(root) NOPASSWD: /usr/local/libexec/left4me/left4me-overlay mount *, /usr/local/libexec/left4me/left4me-overlay umount *
+left4me ALL=(root) NOPASSWD: /usr/local/libexec/left4me/left4me-script-sandbox
diff --git a/deploy/files/usr/local/libexec/left4me/left4me-script-sandbox b/deploy/files/usr/local/libexec/left4me/left4me-script-sandbox
new file mode 100755
index 0000000..625f026
--- /dev/null
+++ b/deploy/files/usr/local/libexec/left4me/left4me-script-sandbox
@@ -0,0 +1,55 @@
+#!/bin/bash
+# Privileged sandbox launcher for left4me script overlays.
+#
+# Invoked via sudo by the web user with two arguments:
+#   <overlay_id>   numeric overlay id; bind-mounts /var/lib/left4me/overlays/<id>
+#                  read-write at /overlay inside the sandbox.
+#   <script_path>  absolute path to a bash file already written by the web app;
+#                  bind-mounted read-only at /script.sh inside the sandbox.
+#
+# The script runs under bubblewrap inside a transient systemd scope so we get
+# cgroup-v2 limits (memory / tasks / cpu) and a wallclock kill via
+# RuntimeMaxSec. The sandbox drops to the unprivileged l4d2-sandbox UID;
+# host filesystems are exposed read-only except /overlay (rw) and tmpfs
+# /tmp + /run. Network namespace is *not* unshared — scripts must reach the
+# public internet to download workshop / l4d2center / cedapug content.
+set -euo pipefail
+
+[[ $# -eq 2 ]] || { echo "usage: $0 <overlay_id> <script>" >&2; exit 64; }
+
+OVERLAY_ID=$1
+SCRIPT=$2
+
+[[ "$OVERLAY_ID" =~ ^[0-9]+$ ]] || { echo "bad overlay id" >&2; exit 64; }
+OVERLAY_DIR=/var/lib/left4me/overlays/$OVERLAY_ID
+[[ -d $OVERLAY_DIR ]] || { echo "no overlay dir at $OVERLAY_DIR" >&2; exit 65; }
+[[ -f $SCRIPT ]] || { echo "no script at $SCRIPT" >&2; exit 65; }
+
+SBX_UID=$(id -u l4d2-sandbox)
+SBX_GID=$(id -g l4d2-sandbox)
+
+if [[ "${LEFT4ME_SCRIPT_SANDBOX_DRY_RUN:-}" == "1" ]]; then
+    echo "DRY RUN: overlay_id=$OVERLAY_ID script=$SCRIPT uid=$SBX_UID gid=$SBX_GID overlay_dir=$OVERLAY_DIR"
+    exit 0
+fi
+
+exec systemd-run --quiet --scope --collect \
+    -p MemoryMax=4G -p MemorySwapMax=0 -p TasksMax=512 \
+    -p CPUQuota=200% -p RuntimeMaxSec=3600 \
+    -- bwrap \
+        --die-with-parent --new-session \
+        --unshare-pid --unshare-ipc --unshare-uts --unshare-cgroup \
+        --uid "$SBX_UID" --gid "$SBX_GID" \
+        --proc /proc --dev /dev --tmpfs /tmp --tmpfs /run \
+        --ro-bind /usr /usr --ro-bind /lib /lib --ro-bind /lib64 /lib64 \
+        --symlink usr/bin /bin --symlink usr/sbin /sbin \
+        --ro-bind /etc/resolv.conf /etc/resolv.conf \
+        --ro-bind /etc/ssl /etc/ssl \
+        --ro-bind /etc/ca-certificates /etc/ca-certificates \
+        --ro-bind /etc/nsswitch.conf /etc/nsswitch.conf \
+        --bind "$OVERLAY_DIR" /overlay \
+        --chdir /overlay \
+        --setenv HOME /tmp --setenv PATH /usr/bin:/usr/sbin \
+        --setenv OVERLAY /overlay \
+        --ro-bind "$SCRIPT" /script.sh \
+        /bin/bash /script.sh
diff --git a/deploy/tests/test_deploy_artifacts.py b/deploy/tests/test_deploy_artifacts.py
index 2fd7945..d7c56f8 100644
--- a/deploy/tests/test_deploy_artifacts.py
+++ b/deploy/tests/test_deploy_artifacts.py
@@ -14,6 +14,7 @@ GLOBAL_REFRESH_TIMER = DEPLOY / "files/usr/local/lib/systemd/system/left4me-refr
 SYSTEMCTL_HELPER = DEPLOY / "files/usr/local/libexec/left4me/left4me-systemctl"
 JOURNALCTL_HELPER = DEPLOY / "files/usr/local/libexec/left4me/left4me-journalctl"
 OVERLAY_HELPER = DEPLOY / "files/usr/local/libexec/left4me/left4me-overlay"
+SCRIPT_SANDBOX_HELPER = DEPLOY / "files/usr/local/libexec/left4me/left4me-script-sandbox"
 SUDOERS = DEPLOY / "files/etc/sudoers.d/left4me"
 HOST_ENV = DEPLOY / "templates/etc/left4me/host.env"
 WEB_ENV_TEMPLATE = DEPLOY / "templates/etc/left4me/web.env.template"
@@ -155,6 +156,10 @@ def test_sudoers_allows_only_left4me_helpers_not_raw_system_tools():
     ) in sudoers
     assert "/usr/local/libexec/left4me/left4me-overlay mount *" in sudoers
     assert "/usr/local/libexec/left4me/left4me-overlay umount *" in sudoers
+    assert (
+        "left4me ALL=(root) NOPASSWD: "
+        "/usr/local/libexec/left4me/left4me-script-sandbox"
+    ) in sudoers
     assert "/bin/systemctl" not in sudoers
     assert "/usr/bin/systemctl" not in sudoers
     assert "/bin/journalctl" not in sudoers
@@ -285,3 +290,55 @@ def test_deploy_script_installs_and_enables_global_refresh_timer():
     assert "left4me-refresh-global-overlays.service" in script
     assert "left4me-refresh-global-overlays.timer" in script
     assert "systemctl enable --now left4me-refresh-global-overlays.timer" in script
+
+
+def test_script_sandbox_helper_present():
+    assert SCRIPT_SANDBOX_HELPER.is_file()
+    assert SCRIPT_SANDBOX_HELPER.read_text().startswith("#!/bin/bash")
+    mode = SCRIPT_SANDBOX_HELPER.stat().st_mode & 0o777
+    assert mode == 0o755, f"expected 0755, got {oct(mode)}"
+
+
+def test_script_sandbox_helper_passes_shell_syntax_check():
+    subprocess.run(["bash", "-n", str(SCRIPT_SANDBOX_HELPER)], check=True)
+
+
+def test_script_sandbox_helper_invokes_systemd_run_and_bwrap():
+    text = SCRIPT_SANDBOX_HELPER.read_text()
+    assert "systemd-run" in text
+    assert "--scope" in text
+    assert "--collect" in text
+    assert "MemoryMax=4G" in text
+    assert "RuntimeMaxSec=3600" in text
+    assert "TasksMax=512" in text
+    assert "bwrap" in text
+    assert "--unshare-pid" in text
+    assert "--unshare-net" not in text, "scripts must keep host network access"
+    assert 'id -u l4d2-sandbox' in text
+    assert 'id -g l4d2-sandbox' in text
+
+
+def test_script_sandbox_helper_validates_overlay_id():
+    text = SCRIPT_SANDBOX_HELPER.read_text()
+    # Numeric-only overlay id
+    assert '[[ "$OVERLAY_ID" =~ ^[0-9]+$ ]]' in text
+    # Overlay dir must exist
+    assert "/var/lib/left4me/overlays/" in text
+    assert "[[ -d $OVERLAY_DIR ]]" in text
+    # Script path must exist
+    assert "[[ -f $SCRIPT ]]" in text
+
+
+def test_script_sandbox_helper_dry_run_mode(tmp_path):
+    overlay_root = tmp_path / "var/lib/left4me/overlays/42"
+    overlay_root.mkdir(parents=True)
+    fake_script = tmp_path / "fake.sh"
+    fake_script.write_text("echo hi")
+
+    # Run in DRY_RUN mode against a fake l4d2-sandbox UID via a tiny shim that
+    # simulates `id -u l4d2-sandbox` resolving to a valid number.
+    helper_text = SCRIPT_SANDBOX_HELPER.read_text()
+    # We can't actually exec this without root + a real sandbox user; just
+    # verify the dry-run guard short-circuits before systemd-run / bwrap.
+    assert 'LEFT4ME_SCRIPT_SANDBOX_DRY_RUN' in helper_text
+    assert 'exit 0' in helper_text