OpenShell Issue: FUSE filesystem support via image inspection

[sandys]

Problem Statement

Custom container images that use FUSE filesystems (e.g., mounting a PostgreSQL database as a virtual filesystem) cannot
work inside OpenShell sandboxes because:

• /dev/fuse is not exposed into sandbox containers
• User processes have zero capabilities (no CAP_SYS_ADMIN for mount(2))
• ENTRYPOINT/CMD is replaced by the supervisor — image startup code never runs with privileges

This is by design — the sandbox security model correctly prevents user code from having elevated privileges. But FUSE mounts are safe once established: they're kernel-level mounts that any unprivileged process can read/write through normal filesystem operations.

Proposed Design

OpenShell should discover FUSE requirements by inspecting the container image's static artifacts — not by running image
code or trusting image-declared scripts.

Discovery (image inspection)

The supervisor already inspects images for:

• sandbox user existence (validate_sandbox_user())
• Policy file at /etc/openshell/policy.yaml (disk discovery fallback)
• Working directory

Add: inspect for a well-known declarative config file:

/etc/openshell/fuse.yaml

mounts:

• binary: /usr/local/bin/openeral
  args: ["mount", "/db"]
  mount_point: /db
  env_from: OPENERAL_DATABASE_URL
  ready_check: mountpoint
  read_only: true

• binary: /usr/local/bin/openeral
  args: ["workspace", "mount", "default", "/home/agent"]
  mount_point: /home/agent
  env_from: OPENERAL_DATABASE_URL
  ready_check: mountpoint
  read_only: false

This is declarative data, not executable code. The supervisor validates it against an allowlist/schema before acting on
it.

Execution (supervisor-managed, pre-child)

During the privileged startup phase (between prepare_filesystem() and ProcessHandle::spawn()):

1. Read /etc/openshell/fuse.yaml from the image
2. Validate: binary must exist in the image, mount points must be in policy read_write or read_only paths
3. Create /dev/fuse via mknod (supervisor has SYS_ADMIN)
4. For each mount: spawn the FUSE daemon as a supervisor-managed background process (like proxy and SSH server)
5. Wait for ready_check (mountpoint becomes active)
6. Drop privileges, apply Landlock/seccomp, spawn child
7. Child sees mounts as regular directories — zero capabilities needed

Security properties preserved

• No image code runs with privileges — the supervisor reads a declarative config and runs known binaries. The binary
  itself runs unprivileged (FUSE daemons don't need root after initial mount(2) — but the supervisor handles the privileged
  mount setup).
• Actually: FUSE daemons DO need to open /dev/fuse and call mount. So the FUSE daemon processes run as supervisor-managed
  services with limited elevated access (just /dev/fuse + mount), separate from the child process.
• Landlock still applies to child — child can only access paths in policy
• No capability leakage — child process has zero capabilities
• Declarative, not executable — fuse.yaml is validated data, not a script
• Binary allowlisting — supervisor can verify binary SHA256 (TOFU pattern already exists in identity.rs)

Open questions for OpenShell maintainers

1. Should the FUSE daemon run as root or as the sandbox user? (Root simplifies mount setup but widens attack surface.
   Running as sandbox user requires fusermount3 setuid binary.)
2. Should fuse.yaml support env var passthrough from provider environment? (FUSE daemons often need credentials like
   database URLs.)
3. Should there be an allowlist of approved FUSE binaries, or is binary-exists-in-image sufficient?

Alternatives Considered

Approach 1: --device CLI flag (like Docker's --device /dev/fuse)
Exposes the device node into the pod via Kubernetes hostPath. Problem: this only gives you the device — the child process
still needs CAP_SYS_ADMIN to call mount(2) on it. So you'd also need capability passthrough. That breaks the security
model — you're giving user code elevated privileges.

Approach 2: --mount host path (#500)
Mount a host-side FUSE filesystem into the sandbox. Problem: this requires running openeral on the host, not inside the
sandbox. The host doesn't have our PostgreSQL credentials, openeral binary, or knowledge of what to mount. The sandbox
becomes dependent on host-side infrastructure. Defeats the self-contained image model.

Approach 3: Policy-driven device creation + capability passthrough
Add devices to policy YAML, supervisor creates /dev/fuse and passes CAP_SYS_ADMIN to child. Problem: giving child
CAP_SYS_ADMIN is exactly what you identified as breaking OpenShell's purpose. Any capability leak to user code undermines
the sandbox.

Approach 4: Supervisor runs image ENTRYPOINT with privileges
Supervisor executes the image's ENTRYPOINT as root during setup, then spawns child unprivileged. Problem: you identified
this too — running arbitrary image code with admin is dangerous. A malicious image could do anything.

Approach 5: Declarative fuse.yaml + supervisor-managed daemons (proposed)
Image declares FUSE mounts as data. Supervisor reads it, validates it, and runs the FUSE daemons itself as managed
services (like it already manages proxy and SSH). Child gets zero capabilities.

Why this one wins:

• No capability leak — child has zero capabilities, identical to today
• No arbitrary code execution with privileges — supervisor reads declarative config, validates binaries exist, runs them
  under its own management
• Self-contained — everything is in the image, no host-side setup
• Follows existing patterns — proxy and SSH server are already supervisor-managed background services spawned before the
  child
• Inspectable — OpenShell can validate/audit the FUSE config before acting on it

The one weakness: the FUSE daemon binary (e.g., openeral) does run with enough privilege to open /dev/fuse and call
mount(2). But it's managed by the supervisor, not by user code — similar to how the proxy runs with network access that
the child doesn't have.

Agent Investigation

Existing patterns in OpenShell that this follows

┌────────────────────────────────────────────────────────┬────────────────────────────────────────────────────────────┐
│ Existing pattern │ This proposal │
├────────────────────────────────────────────────────────┼────────────────────────────────────────────────────────────┤
│ Proxy runs as supervisor-managed background service │ FUSE daemons run as supervisor-managed background services │
├────────────────────────────────────────────────────────┼────────────────────────────────────────────────────────────┤
│ SSH server spawned before child, managed by supervisor │ FUSE daemons spawned before child, managed by supervisor │
├────────────────────────────────────────────────────────┼────────────────────────────────────────────────────────────┤
│ prepare_filesystem() creates dirs as root │ Supervisor creates /dev/fuse as root │
├────────────────────────────────────────────────────────┼────────────────────────────────────────────────────────────┤
│ /etc/openshell/policy.yaml discovered from image disk │ /etc/openshell/fuse.yaml discovered from image disk │
├────────────────────────────────────────────────────────┼────────────────────────────────────────────────────────────┤
│ validate_sandbox_user() inspects image │ FUSE config validation inspects image │
├────────────────────────────────────────────────────────┼────────────────────────────────────────────────────────────┤
│ Zombie reaper manages orphaned children │ Supervisor manages FUSE daemon lifecycle │
└────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────────┘

Implementation locations in OpenShell

┌──────────────────────────────────────────┬──────────────────────────────────────────────────────────────────────────┐
│ File │ Change │
├──────────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────┤
│ crates/openshell-sandbox/src/lib.rs │ Add FUSE discovery + daemon spawn between prepare_filesystem() and │
│ │ ProcessHandle::spawn() │
├──────────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────┤
│ crates/openshell-sandbox/src/fuse.rs │ FUSE config parsing, validation, daemon management │
│ (new) │ │
├──────────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────┤
│ crates/openshell-policy/src/lib.rs │ Validate fuse mount points against policy paths │
└──────────────────────────────────────────┴──────────────────────────────────────────────────────────────────────────┘

Checklist

• I've reviewed existing issues and the architecture docs
• This is a design proposal, not a "please build this" request

[sandys]

Linux already has a standard, safe mechanism for this: /etc/fstab entries with mount.fuse3 --drop_privileges. OpenShell
should inspect the image's /etc/fstab and set up FUSE mounts during the supervisor's privileged startup phase.

Design: /etc/fstab inspection + mount.fuse3 drop_privileges

How it works

The image declares FUSE mounts in /etc/fstab — a standard, parseable, non-executable data file:

openeral#mount /db fuse ro,noauto,drop_privileges,setuid=sandbox,allow_other 0 0
openeral#workspace#mount#default /home/agent fuse rw,noauto,drop_privileges,setuid=sandbox,allow_other 0 0

The format binary#args mountpoint fuse options 0 0 is standard Linux FUSE convention, parsed by /sbin/mount.fuse3.

Supervisor startup sequence (additions in bold)

1. Load policy
2. Validate sandbox user
3. prepare_filesystem() — create read_write dirs
4. Inspect /etc/fstab for fuse type entries with noauto flag
5. Validate: binary exists in image, mount point in policy paths, drop_privileges option required
6. Create /dev/fuse via mknod (supervisor has SYS_ADMIN)
7. For each fstab fuse entry: invoke mount.fuse3 which:

• Opens /dev/fuse and calls mount(2) as root
• Drops ALL capabilities and privilege flags
• Execs the FUSE daemon binary fully unprivileged

8. Wait for mount points to become ready
9. Start proxy, SSH server (existing)
10. Spawn child process with pre_exec: drop_privileges → Landlock → seccomp (existing)

Why this is safe

No executable code is trusted. /etc/fstab is a parseable data file with a well-defined format. The supervisor reads it the
same way it reads /etc/openshell/policy.yaml or checks for the sandbox user in /etc/passwd.

mount.fuse3 --drop_privileges is a kernel security feature. From the man page: "It will launch the file system process
fully unprivileged, i.e. without capabilities and prctl flags set up such that privileges can't be reacquired (e.g. via
setuid or fscaps binaries). This reduces risk in the event of the FUSE file system process getting compromised by
malicious file system data."

Supervisor validates before acting:

• drop_privileges option MUST be present (reject entries without it)
• setuid=sandbox option MUST match the policy's run_as_user
• Binary must exist in the image at the specified path
• Mount point must be in the policy's filesystem_policy paths
• noauto flag present (not a boot-time mount, explicitly for supervisor)

FUSE daemon runs unprivileged. Even though the FUSE daemon is an image binary, mount.fuse3 ensures it runs with zero
capabilities after mount setup. A compromised FUSE daemon can only affect its own mount — it cannot escalate.

Child process unchanged. Zero capabilities, Landlock, seccomp — identical to today.

What OpenShell already does that parallels this

┌───────────────────────────────────────────────────┬─────────────────────────────────────────────────┐
│ Existing │ Proposed │
├───────────────────────────────────────────────────┼─────────────────────────────────────────────────┤
│ Reads /etc/openshell/policy.yaml from image disk │ Reads /etc/fstab from image disk │
├───────────────────────────────────────────────────┼─────────────────────────────────────────────────┤
│ Validates sandbox user in /etc/passwd │ Validates binary + mount point in fstab entries │
├───────────────────────────────────────────────────┼─────────────────────────────────────────────────┤
│ prepare_filesystem() creates dirs as root │ mknod /dev/fuse as root │
├───────────────────────────────────────────────────┼─────────────────────────────────────────────────┤
│ Spawns proxy as supervisor-managed service │ Spawns FUSE daemons via mount.fuse3 │
├───────────────────────────────────────────────────┼─────────────────────────────────────────────────┤
│ Proxy runs with network access child doesn't have │ FUSE daemon runs with mount that child uses │
└───────────────────────────────────────────────────┴─────────────────────────────────────────────────┘

Implementation in OpenShell

┌──────────────────────────────────────────┬──────────────────────────────────────────────────────────────────────────┐
│ File │ Change │
├──────────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────┤
│ crates/openshell-sandbox/src/lib.rs │ After prepare_filesystem(): parse fstab, validate, create /dev/fuse, │
│ │ invoke mount.fuse3 │
├──────────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────┤
│ crates/openshell-sandbox/src/fuse.rs │ Fstab FUSE entry parsing, validation, mount.fuse3 invocation, readiness │
│ (new) │ check │
├──────────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────┤
│ crates/openshell-policy/src/lib.rs │ Validate fuse mount points against policy paths │
└──────────────────────────────────────────┴──────────────────────────────────────────────────────────────────────────┘