Skip to content
Open
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
279 changes: 279 additions & 0 deletions docs/audits/2026-11-17-capstd-experiment.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,279 @@
// SPDX-License-Identifier: CC-BY-SA-4.0
// Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
= Containment experiment: capability handles (`cap-std`), 2026-11-17
:toc: preamble

The route plan asks for a one-day experiment before the sandbox escapes are
fixed (`docs/plans/VSH-ROUTE-PLAN-2026-11-04.adoc`, Phase 1; step B1 of the
2026-11-17 amendment): route a few commands through a directory handle from
the `cap-std` crate, and decide from the result how the shell is contained.

*Result: go.* The mechanism closes the symlink and `..` escapes for the
commands ported, with a small change and no test regressions. It does not
cover hard links, which need their own check.

== The question

Today the shell contains paths lexically: it joins the path to the root and
removes `..` components. It never asks where the path leads on disk, so a
symlink inside the root reaches outside it (holes j, k, l, m), and `cd`
moves the root itself (holes f, g).

Three ways to fix that were rated in the plan: capability handles (elegance
9 / dependability 8), a hand-written `openat2` and `O_NOFOLLOW` walk (6 / 7),
and more lexical checks (3 / 3, which is what fails today).

A capability handle is an open directory. Every path given to it is relative,
and the operating system resolves it beneath that directory (`openat2` with
`RESOLVE_BENEATH` on Linux 5.6 and later), so a path cannot name anything
outside, whatever symlinks it passes through.

== Part 1: the crate alone

A stand-alone program opened a handle on a root directory and tried each
escape (Measured, Linux 6.18, `cap-std` 4.0.3):

[cols="3,2",options="header"]
|===
| Attempt | Result

| Write through a symlink to a file outside (absolute or relative target) | Refused; the outside file is unchanged
| Create a file or directory under a symlink to an outside directory | Refused
| Rename a file into a symlink to an outside directory | Refused
| `../escaped`, `sub/../../escaped`, and opening `..` | Refused
| An absolute path | Refused (paths must be relative to the handle)
| `sub/../inside` (stays in the root) | Allowed
| Write through a symlink whose target is inside the root | Allowed
| Open for writing a hard link whose other name is outside the root | *Allowed.* The link count (2) is visible on the open file
|===

Cost of 20,000 file creations, one run each, release build: at the top of the
root, 0.93 s through the handle against 0.23 s through `std::fs`; six
directories deep, 0.18 s against 0.25 s. The two runs disagree on which is
faster, so the only safe reading is that the cost is tens of microseconds per
operation at most, which does not matter for a shell.

== Part 2: in the shell

`ShellState` gained a handle on the session root, opened once at start, and a
function that turns a typed path into a path relative to the session root (or
refuses it if it lies outside). Four commands were moved onto the handle:
`touch`, `mkdir`, `mv`, and output redirection (`>` and `>>`, both the
built-in and the external-command paths).

[cols="2,3",options="header"]
|===
| Measure | Value

| Source change | 3 files under `src/`, 101 lines added, 21 removed
| New crates in `Cargo.lock` | 11 (304 to 315): `cap-std`, `cap-primitives`, `io-lifetimes`, `io-extras`, `ambient-authority`, `fs-set-times`, `maybe-owned`, `ipnet`, `rustix-linux-procfs`, and `winx` (Windows only)
| Licences of those crates | `Apache-2.0 WITH LLVM-exception OR Apache-2.0 OR MIT`, or `MIT OR Apache-2.0`
| Debug binary size | 61.9 MB to 64.3 MB
| `cargo test --no-fail-fast` | 843 passed, 0 failed, as before the change
| Hole tests (`tests/regressions_parsed_path.rs`) | j, k and l no longer reproduce and left the open list
|===

Hole g (`cd ..; touch escaped`) also stopped reproducing for the four ported
commands. That was too narrow a test: `cd ..; rm bystander` still removed a
file outside the root, because `rm` was not ported and `cd` still moved the
root. The test for g now covers `touch`, `mkdir`, `>` and `rm`, and at this
point of the experiment g stayed on the open list.

NOTE: This part and the next describe the shell as it was when the experiment
ended. Later work on the same day changed some of it: `rm` is ported, `cd`
moves a separate working directory, and hole g is closed. <<now>> gives the
state at the end of the day.

== What it does not do

* *Hard links* (hole n). A hard link inside the root to a file outside it is
an ordinary file as far as path resolution goes. Content operations must
check the link count on the open file and refuse a count above one.
* *Commands not yet ported.* About 200 other filesystem calls in the shell
still use `std::fs` with a lexically resolved path. Containment holds only
where the handle is used. A lint that bans `std::fs` outside one module is
needed to keep it that way.
* *`cd`.* The working directory was still stored by overwriting the root.
Fixing f and g needed a session root that never moves and a separate
working directory. (Done later the same day: see <<now>>.)
* *External commands.* A program the shell runs is not confined by the
handle; it runs as the user.
* *Other platforms.* Not run on macOS or Windows. On systems without
`openat2`, `cap-std` resolves paths itself, one component at a time; that
path was not exercised here.

== Follow-up the same day: obliterate

`obliterate` (file and directory forms) and `secure_delete` now work through
the handle, and close holes c, i, m and n:

* A symbolic link is refused, wherever it points. The request named the link,
and the data belongs to its target.
* A file with more than one hard link is refused, and so is a directory that
contains one. The check is made on the open file, which is opened without
following a link, so the name cannot be swapped in between.
* A directory is walked first, without following links, and refused whole if
anything in it cannot be obliterated safely. Links inside it are removed as
links.
* `obliterate` is refused inside a transaction (ruling OD-3a).
* An audit entry is written before anything is destroyed, and its failure
stops the command. A second entry records the outcome.

Output redirection also refuses a file with more than one hard link.

One fault was found on the way: a directory handle from `open_dir` cannot be
synced (`EBADF`), so the first version destroyed the file and then reported
failure. The directory is now opened as a file for syncing. The existing
tests did not catch this; the hole test for d did, because its set-up runs
`obliterate`.

== Follow-up the same day: one open per redirection

Review found that a redirection's target was opened more than once: by the
set-up (beneath the root, with the check on hard links), and then again by
whatever wrote to it. For a built-in the second open was beneath the root,
without the check. For an external command it was an ordinary `File::create`
on the name. A name given to another file between the two opens was
followed: a hard link to a file outside the root was truncated and written,
and for an external command so was the target of a symbolic link.

A redirection's target is now opened once:

* It is opened beneath the root without truncating it. The file type and the
link count are read from the open file. Only then is it truncated.
* A file that does not exist is created exclusively. A file that another
program makes at that moment is not taken for a new one. One consequence:
a redirection to a symbolic link whose target does not exist is refused
(bash creates the target).
* The bytes saved for undo are read through the same handle, opened with
`O_NOATIME` where the system has it.
* Built-ins and external commands write through duplicates of that handle.
* The history records the file that was changed, with the links in the path
resolved, so `echo x > alias` is recorded under the file `alias` points
to. `obliterate` of that file then finds the record.

Input redirection is still opened by an ordinary path (once). Undoing an
append or the creation of a file, and redoing the creation of a file, still
go by an ordinary path.

== Follow-up the same day: redo, and a gap in the scrub

Review found that a removal which is redone lost the file. The record made by
`redo` held no content, and undo of a removal with no content wrote an empty
file, readable by its owner only, and reported success: `rm f; undo; redo;
undo` left `f` empty. A redone truncation (`echo x > f; undo; redo; undo`)
lost the content in the same way.

* `redo` of a removal now removes the file as `rm` does: beneath the root,
keeping the content and the file's permissions, owner and modification
time. `redo` of a truncation empties the file as the redirection does: one
open, the same checks, the content read from the file that is emptied.
What is kept is what the file holds at that moment, which is not always
what the first run saved.
* Undo of a removal or of a truncation whose record holds no content now
fails and writes nothing. Such a record can come from `redo` in an earlier
build.
* The audit entry of a directory obliteration that fails part of the way
counts a file as soon as its name is removed. It was counted after the
directory was synced, so a failed sync reported one file too few.

One gap in the scrub of obliterated content was found while this was
checked, and is not closed. The scrub finds the records of a file by path:
the path as recorded, and where that path leads now. Content that was saved
while the file had another name is not found:

* `echo secret > a; echo x > a; mv a b; obliterate b` leaves `secret` in the
saved history, under the name `a`;
* so does content saved through a symbolic link that has been removed
since, in a history written before redirections recorded the file they
changed.

It is listed as hole (p) in `impl/rust-cli/tests/regressions_parsed_path.rs`.
That test fails if the hole closes and the list is not updated. Closing it
needs a decision on how a record identifies its file: by the names the
history gives the file over time, by the device and inode read when the
content is saved, or both. The decision is open.

== Follow-up the same day: what a failed command leaves behind

Review found four more faults, and checking them found others of the same
kind.

* *A `>` target was emptied before the command was known to start.* Each
target was emptied as it was set up. If a later redirection of the same
command was then refused (`echo hi > out 2> dangling`), `out` was already
empty and the record of what it had held was dropped. The same happened
when the command itself failed after the set-up: a built-in that returned
an error, a command that was not found, a command that was interrupted,
and every background command. In each case the file was emptied and
nothing was recorded, so undo could not restore it. Now no target is
emptied until every redirection is set up, and what the set-up changed is
recorded whatever becomes of the command. One function does the set-up,
runs the command and makes the record, so a caller cannot leave the record
out.
* *The shell did not start in its session root.* Started with `-r` from
another directory, the process stayed in that directory until the first
`cd`. Built-ins worked in the session root, but the commands the shell
started, and `$PWD`, used the other directory, outside the root. The shell
now enters the session root when it starts.
* *Undo wrote to whatever had the recorded name.* Undo of `rm` wrote over a
file that another program had made under the name since. Undo of a
truncation opened the name with truncation, unchecked, so a name that had
become a hard link to a file outside the root was emptied and written.
Undo of `rm` now creates the file only if nothing has the name. Undo of a
truncation opens the existing file without truncating it and makes the
checks a redirection makes (a regular file with no other name) before it
writes. It no longer creates a file that has been removed since.
* *`obliterate` used what it had read before the confirmation.* The length
and the link count were read when the file was opened, before the wait
for the answer. Bytes that another program appended during the wait were
not overwritten, and a hard link made during the wait was not seen. The
link count is now read again after the answer, before anything is
recorded. The length is read where the overwrite starts, and a file that
is longer after the overwrite than the length overwritten is an error:
the name is left in place.

Not changed: a file that an earlier redirection created stays, empty, when a
later one is refused (as in bash), and it is not recorded. The checks are
made on the open file, but another program can still change the file
between a check and the write that follows it; the gap is short, not
closed.

[[now]]
== Where this stands at the end of the day

Through the handle on the session root: `touch`, `mkdir`, `mv`, `rm`,
`obliterate`, output redirection (the set-up, and the writes of built-ins
and of commands), redo of a removal and of a truncation, and undo of a
removal and of a truncation.

Still by an ordinary path: `cp`, `rmdir`, `ln -s`, `chmod`, `chown`, input
redirection, `ls`, the test built-in, undo and redo of the other operations,
and rollback of them.

The session root is fixed. `cd` moves a separate working directory, within
the root, and the process starts in the root. History paths are relative to
the session root.

Holes open in `impl/rust-cli/tests/regressions_parsed_path.rs`: b, o and p.
Holes a, c to n are closed.

== Decision and next steps

Capability handles are adopted for containment (route plan step B2). The
steps decided at the end of the experiment, with their state at the end of
the day:

. Port the remaining commands, `rm` first. `rm` and `obliterate` are done;
the commands listed in <<now>> are not.
. Give the shell a fixed session root and a separate working directory;
record history paths relative to the session root. Done.
. Refuse content operations on files with more than one hard link, and
refuse `obliterate` on a symlink. Done for `>`, `>>`, `obliterate`, redo
and undo of a truncation.
. Add the lint, so that a new `std::fs` call outside the filesystem module
fails the build. Not done.

The same handle answers the question of where the shell's own state lives: a
second handle on a state directory outside the session root, which no
root-relative path can reach.
Loading
Loading