Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion crates/openshell-driver-docker/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,6 @@ LSM decisions remain authoritative.
| `restart_policy = no` | Keeps canonical main-process exit terminal. |
| `PidsLimit` | Applies the configured sandbox PID budget. Omit `sandbox_pids_limit` to use OpenShell's default. Explicit zero is invalid. |
| Private named volumes | Separate volumes carry sandbox bootstrap keys, the runtime-initiated Unix socket, and supervisor-only credentials. The supervisor mounts bootstrap keys read-only and only the socket volume writable. |
| In-memory `/run/openshell-supervisor-ca` tmpfs | Holds only the public supervisor CA certificate and trust bundle without making all of `/run` writable. |
| CDI GPU request | Assigns the exact validated CDI devices requested by driver config or count-based selection. |

New containers dial the supervisor at `/.openshell/channel/control/supervisor/control.sock`.
Expand Down
10 changes: 3 additions & 7 deletions crates/openshell-driver-docker/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -6328,13 +6328,9 @@ fn build_container_create_body_for_image(
// Podman, Kubernetes, and VM resolvers, send names to policy DNS
// exactly as written so short names never expand to host domains.
dns_search: Some(vec![".".to_string()]),
tmpfs: Some(HashMap::from([(
openshell_sandbox_backend::SUPERVISOR_CA_RUNTIME_DIR.to_string(),
format!(
"rw,noexec,nosuid,nodev,size=1m,uid={},gid={},mode=0755",
workload_identity.uid, workload_identity.gid
),
)])),
// No writable runtime storage: provider and CA trust files are
// served from the sandbox runtime's memory.
tmpfs: None,
sysctls: Some(HashMap::from([(
"net.ipv4.ip_unprivileged_port_start".to_string(),
"0".to_string(),
Expand Down
11 changes: 2 additions & 9 deletions crates/openshell-driver-docker/src/tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -3772,17 +3772,10 @@ fn docker_supervisor_network_mode_is_an_operator_config_enum() {
}

#[test]
fn build_container_create_body_limits_writable_runtime_storage_to_supervisor_ca() {
fn build_container_create_body_mounts_no_writable_runtime_storage() {
let create_body = build_container_create_body(&test_sandbox(), &runtime_config()).unwrap();
let host_config = create_body.host_config.expect("host_config is populated");
let tmpfs = host_config.tmpfs.expect("sandbox tmpfs is populated");

assert_eq!(tmpfs.len(), 1);
assert_eq!(
tmpfs.get(openshell_sandbox_backend::SUPERVISOR_CA_RUNTIME_DIR),
Some(&"rw,noexec,nosuid,nodev,size=1m,uid=1000,gid=1000,mode=0755".to_string())
);
assert!(!tmpfs.contains_key("/run"));
assert!(host_config.tmpfs.is_none_or(|tmpfs| tmpfs.is_empty()));
}

#[test]
Expand Down
42 changes: 7 additions & 35 deletions crates/openshell-driver-podman/src/container.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1675,21 +1675,6 @@ pub fn build_isolation_specs(
workload
.mounts
.retain(|mount| !trusted_mount(&mount.destination));
workload.mounts.push(Mount {
kind: "tmpfs".into(),
source: "tmpfs".into(),
destination: openshell_sandbox_backend::SUPERVISOR_CA_RUNTIME_ROOT.into(),
options: vec![
"rw".into(),
"noexec".into(),
"nosuid".into(),
"nodev".into(),
// Libpod's OCI `mounts` API rejects tmpfs uid/gid options. The
// unprivileged runtime creates the owned material subdirectory.
"mode=0777".into(),
"size=1m".into(),
],
});
workload.volumes.push(NamedVolume {
name: channel.clone(),
dest: crate::isolation::CHANNEL_ROOT.into(),
Expand Down Expand Up @@ -2234,26 +2219,13 @@ mod tests {
.iter()
.all(|mount| !trusted_mount(&mount.destination))
);
let supervisor_ca_mount = specs
.workload
.mounts
.iter()
.find(|mount| {
mount.destination == openshell_sandbox_backend::SUPERVISOR_CA_RUNTIME_ROOT
})
.expect("workload supervisor CA mount");
assert_eq!(supervisor_ca_mount.kind, "tmpfs");
assert_eq!(supervisor_ca_mount.source, "tmpfs");
for option in ["rw", "noexec", "nosuid", "nodev", "mode=0777", "size=1m"] {
assert!(supervisor_ca_mount.options.contains(&option.to_string()));
}
assert!(
specs
.workload
.mounts
.iter()
.all(|mount| mount.destination != "/run")
);
// The CA trust files are virtual: no workload mount carries them.
assert!(specs.workload.mounts.iter().all(|mount| {
!mount
.destination
.starts_with(openshell_sandbox_backend::SUPERVISOR_CA_RUNTIME_ROOT)
&& mount.destination != "/run"
}));
assert_eq!(specs.supervisor.secrets.len(), 1);
assert_eq!(specs.supervisor.secrets[0].source, "jwt");
assert_eq!(specs.supervisor.secrets[0].uid, 1000);
Expand Down
11 changes: 5 additions & 6 deletions crates/openshell-sandbox-backend/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -42,14 +42,13 @@ pub const GPU_RESOURCE_CLAIM: &str = "openshell.gpu";
pub const ALLOW_EXTRA_SUPPLEMENTARY_GROUPS_RESOURCE_CLAIM: &str =
"openshell.identity.allow_extra_supplementary_groups";

/// Memory-backed parent used for supervisor CA material.
/// Workload path reserved for the supervisor CA material. Nothing is mounted
/// or written there: the sandbox runtime serves the files virtually, and
/// drivers keep user mounts away from it.
pub const SUPERVISOR_CA_RUNTIME_ROOT: &str = "/run/openshell-supervisor-ca";

/// Workload-visible directory for the supervisor's public HTTPS interception
/// certificate and combined trust bundle.
///
/// Keeping the material below the mount root lets runtimes that cannot assign
/// tmpfs ownership create this child as the unprivileged sandbox identity.
/// Workload-visible directory of the supervisor's public HTTPS interception
/// certificate and combined trust bundle, as named by the TLS environment.
pub const SUPERVISOR_CA_RUNTIME_DIR: &str = "/run/openshell-supervisor-ca/material";

/// Generated gRPC transport envelope for the `OpenShell` Sandbox Protocol.
Expand Down
104 changes: 71 additions & 33 deletions crates/openshell-sandbox/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,39 +42,77 @@ level or option that does not fit a non-negative C `int`, still notifies and
keeps the broker's `EPERM` and `EINVAL` results. The active qualification
probe exercises both sides.

## Provider files

Provider files appear to the workload beneath `/run/openshell/providers`.
Every workload `open`, `openat`, and `openat2` notifies the broker, which
serves a provider path by injecting a read-only descriptor for a sealed
in-memory file and continues every other open.

Each published file is an immutable revision backed by one in-memory file. The
runtime creates that file when the revision is published, not when the
workload opens it: it writes the content, seals the file against writes,
growing, shrinking, and further sealing, and keeps only a read-only descriptor
for it. Each workload open reopens that descriptor through the runtime's own
`/proc/self/fd`, so every open gets its own read-only open file description
and file offset, positioned at the start.

An update prepares every new revision before it replaces the published set in
one step, so a failed update leaves the previous set in place. A file whose
bytes did not change keeps its revision. Opens after an update see the new
revisions, descriptors opened earlier keep the bytes they opened, and a
detached file is `ENOENT` for later opens.

All opens of one revision refer to one file, which the workload owns: it can
change that file's mode or reopen a descriptor for writing. Neither reaches
the content, which the seals protect, and the runtime restores the mode if it
denies an open. The runtime holds one descriptor per published file, at most
64.

The broker classifies each open from an exact copy of the first six bytes of
its path. Six bytes identify a `/proc/` path and the start of a provider path;
only those candidates have their whole path read and decided. An open whose
first six bytes cannot be read, or match neither, continues, and unrelated
`openat2` calls do not require a copy of their `open_how`. Every continued
open remains subject to the kernel and Landlock.
## Virtual files: provider files and supervisor CA trust files

Provider files appear to the workload beneath `/run/openshell/providers`, and
the supervisor's public CA certificate and combined trust bundle at
`/run/openshell-supervisor-ca/material/ca.crt` and `ca-bundle.crt`, where the
TLS environment variables point. None of them exists on a filesystem, and no
driver mounts or Landlock grant is involved. Every workload `open`, `openat`,
and `openat2` notifies the broker, which serves a published path by injecting
a read-only descriptor for a sealed in-memory file and continues every other
open. Every path-based `stat`, `lstat`, `fstatat`, `statx`, and `access` call
notifies too; for a published path the broker writes the metadata the
injected descriptor reports into the caller's buffer, and continues every
other path.

Supported semantics are exactly: an absolute canonical path, read-only opens
(a write-capable open is `EACCES`, `O_DIRECTORY` is `ENOTDIR`, `O_PATH` and
`O_DIRECT` are `EINVAL`, `openat2` with a nonzero `mode` or `resolve` is
`EINVAL`), and the metadata calls above with the kernel's own flag sets. The
directories do not exist: `chdir`, `opendir`, a relative lookup, and an alias
through `..` are the kernel's `ENOENT`. A path beneath the provider prefix
that is not published is `ENOENT`; the CA paths continue to the kernel until
a pair is published.

Each published file is an immutable revision backed by one sealed in-memory
file (`linux::sealed_file`). The runtime writes the content, seals the file
against writes, growing, shrinking, and further sealing, and keeps only a
read-only descriptor. Each workload open reopens that descriptor through the
runtime's own `/proc/self/fd`, so every open gets its own file offset. An
update prepares every new revision before it replaces the published set in
one step; a file whose bytes did not change keeps its revision; descriptors
opened earlier keep the bytes they opened. The CA pair is published before
the spawn, replaced only as a whole, never touched by a provider update, and
cleared by a start without CA material. It is refused if either file is
empty, exceeds the 1 MiB control frame bound, or the bundle does not contain
the certificate.

The broker classifies each call from an exact copy of the first six bytes of
its path; only `/proc/` paths and candidates for the prefixes above have
their whole path read.

### Metadata writes and signal delivery

A `stat` result is delivered by writing into the workload. The broker opens
`/proc/<tid>/mem`, which binds to one address space, and only then validates
the notification: a notification stays valid only while its task lives, so a
valid one proves the pinned space belongs to the notifying task and not to a
task that reused the number (`process_vm_writev` resolves the number again on
every call and cannot give that proof). A write that fails for any reason
fails the call with `EFAULT`; a task killed meanwhile is no longer answered.
Writes through `/proc/<tid>/mem` use the kernel's `FOLL_FORCE`, which differs
from a native `stat` in one case: a result buffer in the caller's own
read-only private copy-on-write memory is written instead of failing with
`EFAULT`. The kernel refuses forced writes to shared and non-`VM_MAYWRITE`
mappings, so this reaches only memory the caller could already make writable
with `mprotect`.

For that write to be safe the workload listener is installed with
`SECCOMP_FILTER_FLAG_WAIT_KILLABLE_RECV` (Linux 5.19). A task can have only
one listener, so the flag covers every notified syscall: before the broker
receives a notification, signals interrupt the syscall as before; once
received, only a fatal signal ends the wait and a handled signal is delivered
after the broker responds. A `connect` awaiting the supervisor's network
admission decision therefore ignores handled `SIGALRM` and `SIGINT` until the
broker answers or its 30-second decision timeout fails the call; DNS relay
waits are bounded at 10 seconds. A blocking loopback `connect` is completed by
the broker with a native `connect` on a duplicate of the socket and waits for
the kernel's connect timeout, which can exceed 30 seconds. Fatal signals still
terminate the task. The runtime qualification probe writes into a dumpable child
through `/proc/<pid>/mem` and fails closed where the posture refuses it.

## Runtime boundary transport

A boundary configured with `RuntimeInitiatedTlsTcp` binds no listener. It dials
only the driver-provided supervisor addresses, which must be concrete,
Expand Down
9 changes: 5 additions & 4 deletions crates/openshell-sandbox/src/boundary_exec.rs
Original file line number Diff line number Diff line change
Expand Up @@ -220,9 +220,7 @@ impl LocalBoundaryExec {
workdir: Option<&str>,
) -> Result<Option<crate::sandbox::linux::PreparedSandbox>, BackendError> {
crate::sandbox::linux::log_sandbox_readiness(&self.policy, workdir);
let runtime_read_only =
crate::process::ca_runtime_read_only_paths(self.ca_file_paths.as_deref());
crate::process::prepare_child_sandbox(&self.policy, workdir, &runtime_read_only)
crate::process::prepare_child_sandbox(&self.policy, workdir)
.map_err(|error| BackendError::Process(error.to_string()))
}

Expand Down Expand Up @@ -817,7 +815,10 @@ mod tests {
std::thread::spawn(move || {
while let Ok(notification) = listener.receive() {
let syscall = i64::from(notification.syscall);
if syscall == libc::SYS_openat || syscall == libc::SYS_openat2 {
if syscall == libc::SYS_openat
|| syscall == libc::SYS_openat2
|| crate::linux::seccomp_notify::is_metadata_syscall(syscall)
{
let _ = listener.respond_continue(notification.id);
} else {
#[cfg(target_arch = "x86_64")]
Expand Down
Loading
Loading