# Research brief: portable unprivileged Linux sandbox for untrusted build/test workloads

## Context (minimal)

A single-machine control-plane process (written in Python) orchestrates workloads that execute build and test
commands against source code it has fetched from a repository. Some of that code is untrusted: it may attempt to
exfiltrate data, tamper with the controller's own state, or attack the host. The controller must run each workload in
an operating-system-enforced sandbox.

The control plane itself is trusted and runs as an ordinary process. We do **not** want to require root, a setuid
helper, a long-running privileged daemon, or a container runtime unless the isolation genuinely cannot be achieved
otherwise. The system should work on as broad a range of **recent Linux** systems as possible (consider kernels 5.15,
5.10, 6.x; mainstream distributions; and ordinary CI containers/VMs), and it must **fail closed**: if the required
isolation mechanism is unavailable, it must refuse to execute the workload rather than run it unsandboxed.

This is a design/feasibility question, not a request to implement anything.

## What the sandbox must enforce

Each workload runs as a subprocess (and may spawn further child processes). The sandbox must provide:

1. **Identity separation** — a dedicated unprivileged identity for the workload.
2. **Filesystem confinement** — a private mount view (or an equivalent isolation boundary) in which:
   - the candidate working tree is read-write;
   - required toolchains/dependencies are read-only;
   - controller state, event storage, artefact storage, credentials, sockets, and arbitrary host paths are absent;
   - Git metadata/objects are not directly mutable (the base tree is materialised, and candidate output is imported
     through a copy-in/copy-out boundary);
   - hidden test files/paths are absent from mounts and environment variables.
3. **Network** — denied by default.
4. **Credentials** — nothing inherited except explicitly scoped short-lived credentials; secrets must not be visible
   to the workload.
5. **Resource limits** — process count, memory, CPU, file size, open descriptors, and wall-clock duration, enforced
   across the whole process tree.
6. **Syscall and device restrictions** appropriate to Linux.
7. **Observation** — reliable capture of command, exit code, stdout, stderr, and resource usage.
8. **Fail-closed degradation** — detect an unavailable mechanism and refuse execution.

## Candidate mechanisms I am aware of

- seccomp-BPF (`no_new_privs` + `PR_SET_SECCOMP`)
- POSIX resource limits (`setrlimit`)
- cgroup v2 (delegated subtree)
- unprivileged user namespaces + mount namespaces (`unshare`, bubblewrap)
- Landlock LSM
- `chroot` (requires `CAP_SYS_CHROOT`)
- DAC by running as a distinct uid
- Rootless Podman
- Docker / containerd daemon
- LXC

## Questions

1. For each candidate mechanism above, on recent Linux: minimum kernel version; whether it works **unprivileged**;
   known distribution/CI policy restrictions (for example, restrictions on unprivileged user namespaces); and which
   of the eight requirements in the previous section it can and cannot satisfy.
2. Which **combination** maximizes availability across recent Linux while still enforcing filesystem confinement,
   network denial, syscall restriction, and process-tree resource limits? Please give a recommended default and a
   priority order for capability detection.
3. Is there a widely available **unprivileged filesystem-confinement** mechanism other than Landlock and user
   namespaces? (Is Landlock actually present and enabled by default on the kernels shipped by the major distributions
   of the last ~3 years? What is a defensible minimum-kernel baseline to document?)
4. Given a process already confined by Landlock/seccomp/resource limits, is a **separate uid** materially necessary,
   or is it defence-in-depth that can be deployment-configurable (assumed only when the controller has the privilege
   to drop into it)?
5. What is the most reliable way to enforce memory/CPU/process limits for a **process tree**, unprivileged — per-child
   `setrlimit` versus a delegated cgroup v2 — and what happens in environments where cgroup delegation is unavailable
   (common in CI containers)?
6. How should this behave when the workload runs **nested** (inside Docker/CI) where user namespaces or certain
   syscalls are already blocked? Which mechanisms commonly fail there, how can that be detected, and is failing closed
   the right response?
7. Practical guidance for applying a seccomp filter from a Python controller without linking libseccomp (ctypes +
   `prctl` + raw BPF): portability across x86_64/aarch64, syscall-number differences, and the risk of breaking
   legitimate build toolchains that need a broad syscall set. Deny-list versus allow-list?
8. Known bypasses or caveats that must be mitigated (for example: file descriptors opened before confinement, `ptrace`
   of same-uid processes, `io_uring`, `/proc/self/mem`, `CLONE_*` flags, inherited capabilities), and the
   corresponding deny-list entries or detection steps.
9. A recommended **layered default policy**: which mechanisms to require, which to use opportunistically, the
   detection order, and exactly when to fail closed, with a short rationale for each choice.
10. A recommended **minimum supported baseline** (kernel versions / distribution classes) to document, and what the
    behaviour should be on systems below that baseline.

## Desired deliverable

A written recommendation covering: the default mechanism stack; the capability-detection order and fail-closed rules;
the minimum supported baseline; the residual risks and their mitigations; and an explicit statement of which
requirements (from the list above) remain only partially enforced under the recommended design. If a container runtime
(e.g. rootless Podman or a Docker daemon) is warranted despite the no-daemon preference, say so and quantify the
trade-off in portability, rootlessness, and testability.
