Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

docs(execd): trim the hosted-/tmp comments to the essentials

高然007baca87099
diff --git a/components/execd/pkg/isolation/bwrap.go b/components/execd/pkg/isolation/bwrap.go
index f563522d4..f8d6bd36c 100644
--- a/components/execd/pkg/isolation/bwrap.go
+++ b/components/execd/pkg/isolation/bwrap.go
@@ -61,9 +61,8 @@ func buildArgvWithLifecycle(
// 2. Root filesystem (read-only).
argv = append(argv, "--ro-bind", "/", "/")
- // 3. /tmp — the session-private host-backed bind when the runner
- // provisioned a backing dir, else the profile default. Skipped if an
- // overlay mounts over /tmp (its mount would override).
+ // 3. /tmp — the session-private host bind when TmpDir is set, else the
+ // profile segment. Skipped when an overlay covers /tmp.
if !OverlaysCoverPath(opts.Overlays, "/tmp") {
if opts.TmpDir != "" {
argv = append(argv, "--bind", opts.TmpDir, "/tmp")
@@ -81,13 +80,10 @@ func buildArgvWithLifecycle(
}
argv = append(argv, ovArgv...)
- // Hide upper roots to prevent cross-session access. Overlay pairs live
- // under <upper_root>/<session_id>/upper and the hosted /tmp backing dir
- // under <upper_root>/<session_id>/tmp, so Dir(Dir(child)) derives the
- // operator-configured upper root for both; dedupe keeps arbitrary
- // caller-supplied directories safe too. Without the hiding tmpfs, the
- // unconditional ro-bind of / below would expose every other session's
- // /tmp backing dir and overlay uppers inside this namespace.
+ // Hide upper roots: Dir(Dir(upper|tmpDir)) derives the operator's upper
+ // root for both overlay pairs and the /tmp backing dir. Without this,
+ // the ro-bind of / below would expose other sessions' host state
+ // in-namespace. Dedupe keeps arbitrary caller-supplied dirs safe.
hideRoots := distinctUpperRoots(opts.Overlays)
if opts.TmpDir != "" {
root := filepath.Dir(filepath.Dir(opts.TmpDir))
@@ -258,9 +254,8 @@ func validateWrapOptions(opts WrapOptions) error {
if !filepath.IsAbs(opts.TmpDir) {
return fmt.Errorf("isolation: tmp dir %q must be an absolute path", opts.TmpDir)
}
- // The hiding tmpfs derives the upper root as Dir(Dir(TmpDir)); a
- // shallower path would derive "/" and brick the namespace, the
- // same rule validateUpperDirs enforces for overlay upperdirs.
+ // The hide root is Dir(Dir(TmpDir)); shallower paths would derive
+ // "/" and brick the namespace (same rule as validateUpperDirs).
if pathDepth(opts.TmpDir) < 3 {
return fmt.Errorf(
"isolation: tmp dir %q must live under an upper root (<root>/<session>/tmp)",
@@ -286,8 +281,7 @@ func validateOverlaySpecs(overlays []OverlaySpec, extraHideRoot string) error {
// The upper-root hiding tmpfs is emitted after the overlay segments, so
// an overlay destination under a derived upper root would be silently
// shadowed — a dead mount whose writes never surface. Fail fast instead.
- // extraHideRoot is the /tmp backing dir's derived root, hidden the same
- // way for sessions without persistent overlay uppers.
+ // extraHideRoot is the /tmp backing dir's derived root, hidden likewise.
hideRoots := distinctUpperRoots(overlays)
if extraHideRoot != "" {
hideRoots = append(hideRoots, extraHideRoot)
@@ -377,10 +371,8 @@ func validateBinds(binds []BindMount) error {
if b.Dest != "" && !filepath.IsAbs(b.Dest) {
return fmt.Errorf("isolation: bind.dest %q must be an absolute path", b.Dest)
}
- // A dest of / is applied after every earlier mount (tmp segment,
- // overlays, extra writable) and shadows the whole namespace root,
- // while longest-prefix consumers (the files view) would keep
- // serving the deeper mounts. Reject instead of diverging.
+ // Dest / shadows every earlier mount in the namespace while the
+ // files view keeps serving them — reject the divergence.
if filepath.Clean(b.Dest) == "/" {
return fmt.Errorf(`isolation: bind.dest "/" would shadow the namespace root`)
}
diff --git a/components/execd/pkg/isolation/bwrap_test.go b/components/execd/pkg/isolation/bwrap_test.go
index 30e37437a..cdfd7f936 100644
--- a/components/execd/pkg/isolation/bwrap_test.go
+++ b/components/execd/pkg/isolation/bwrap_test.go
@@ -951,9 +951,8 @@ func indexOf(items []string, s string) int {
func TestBuildArgv_TmpDirHiding(t *testing.T) {
t.Run("pairless_session_hides_derived_upper_root", func(t *testing.T) {
- // A session whose /tmp is host-backed but that holds no persistent
- // overlay uppers must still hide the derived upper root: without
- // the tmpfs, the ro-bind of / exposes every session's backing dir.
+ // Pair-less sessions host /tmp without overlay uppers; the derived
+ // root must still be hidden or ro-bind / leaks other sessions' dirs.
opts := basicWrapOpts()
opts.Overlays = []OverlaySpec{{Path: "/workspace", Mode: WorkspaceRW}}
opts.TmpDir = "/var/lib/execd/isolation/abc/tmp"
diff --git a/components/execd/pkg/isolation/confined_view.go b/components/execd/pkg/isolation/confined_view.go
index bf7cc29f2..38853bdea 100644
--- a/components/execd/pkg/isolation/confined_view.go
+++ b/components/execd/pkg/isolation/confined_view.go
@@ -27,20 +27,14 @@ import (
)
// ConfinedView serves an attacker-controlled session directory (the hosted
-// private /tmp) through os.Root: every operation is resolved beneath the
-// view root, and symlinks may never escape it (absolute or root-crossing
-// link targets are rejected). Unlike BindView — whose source is an
-// operator-allowlisted trusted directory and which therefore follows
-// symlinks exactly as the namespace does — the /tmp backing dir is written
-// by the workload, so a symlink planted there (for example
-// /tmp/p -> /etc/passwd) must not turn a files-API write into a host write
-// outside the session's own subtree. Divergence note: os.Root also rejects
-// ABSOLUTE link targets that stay inside the root, where the namespace
-// would follow them; workloads' relative links behave identically in both
-// views.
+// private /tmp) through os.Root: operations stay beneath the root and
+// symlink escapes are rejected — including absolute link targets, which the
+// namespace would follow. BindView's source is operator-allowlisted and
+// trusted to mirror the namespace; this directory is written by the
+// workload, so a planted symlink (e.g. /tmp/p -> /etc/passwd) must not
+// redirect a files-API write onto the host.
//
-// The kernel-backed confinement requires openat2 (Linux 5.6+); on older
-// kernels os.OpenRoot fails and the files API surfaces that error.
+// Requires openat2 (Linux 5.6+); os.OpenRoot fails on older kernels.
//
// Compile-time check: ConfinedView satisfies vfs.FS.
var _ vfs.FS = (*ConfinedView)(nil)
@@ -58,10 +52,8 @@ func NewConfinedView(root string, uid, gid uint32) *ConfinedView {
return &ConfinedView{Root: root, Uid: uid, Gid: gid}
}
-// rel converts a namespace-or-host path into a root-relative name. The
-// router forwards absolute host paths (the OverlayView root rewrite), but
-// namespace-space paths are accepted too so direct construction behaves
-// like BindView's dual-prefix resolution.
+// rel converts a namespace-or-host path to a root-relative name; the router
+// forwards host paths after its OverlayView root rewrite.
func (c *ConfinedView) rel(path string) (string, error) {
cleaned := filepath.Clean(path)
switch {
@@ -272,10 +264,9 @@ func (c *ConfinedView) Open(path string) (*os.File, error) {
return root.Open(name)
}
-// Search walks the confined tree (symlink escape attempts surface as walk
-// errors and are skipped) and returns paths relative to the root, matching
-// BindView.Search's convention; the router rebases rewritten-route results
-// onto the namespace mount path.
+// Search walks the confined tree (escaping symlinks surface as walk errors
+// and are skipped) and returns root-relative paths; the router rebases
+// rewritten-route results onto the namespace mount path.
func (c *ConfinedView) Search(rootPath, pattern string) ([]string, error) {
base, err := c.rel(rootPath)
if err != nil {
diff --git a/components/execd/pkg/isolation/isolator.go b/components/execd/pkg/isolation/isolator.go
index a31803317..147170180 100644
--- a/components/execd/pkg/isolation/isolator.go
+++ b/components/execd/pkg/isolation/isolator.go
@@ -155,11 +155,9 @@ type WrapOptions struct {
Overlays []OverlaySpec
ExtraWritable []string
Binds []BindMount
- // TmpDir is an absolute host directory bound to the namespace /tmp,
- // replacing the profile's /tmp segment. It is the session-private /tmp
- // backing directory under the session's upper-root subtree, so the
- // files API can serve the same content run sees. Empty keeps the
- // profile default (strict: private tmpfs, balanced: shared bind).
+ // TmpDir is the session-private /tmp backing dir (absolute host path),
+ // bound to the namespace /tmp in place of the profile's segment. Empty
+ // keeps the profile default.
TmpDir string
ShareNet bool
EnvPassthrough EnvSpec
diff --git a/components/execd/pkg/isolation/merged_view_router.go b/components/execd/pkg/isolation/merged_view_router.go
index e140e10e4..65d850537 100644
--- a/components/execd/pkg/isolation/merged_view_router.go
+++ b/components/execd/pkg/isolation/merged_view_router.go
@@ -226,11 +226,8 @@ func (m *MultiMergedView) RemoveAll(path string) error {
return rt.fs.RemoveAll(p)
}
-// rejectMountRootRemoval mirrors namespace mountpoint semantics: rm cannot
-// unlink a mount point. Rewritten-root routes (caller binds, the hosted
-// /tmp) would otherwise let a files-API removal unlink the host backing
-// directory while the live mount keeps serving the unlinked inode, after
-// which a recreated directory and the namespace would silently diverge.
+// rejectMountRootRemoval mirrors mountpoint semantics: a bind-style mount
+// root (caller bind, hosted /tmp) must not be unlinked under a live mount.
// Overlay views keep their historical behavior.
func rejectMountRootRemoval(rt *overlayRoute, path string) error {
if rt.root != "" && rt.root != rt.prefix && filepath.Clean(path) == rt.prefix {
diff --git a/components/execd/pkg/isolation/upper.go b/components/execd/pkg/isolation/upper.go
index 0a7214700..7532329d5 100644
--- a/components/execd/pkg/isolation/upper.go
+++ b/components/execd/pkg/isolation/upper.go
@@ -30,9 +30,7 @@ import (
const cleanupRegistryName = ".execd-cleanup"
-// tmpDirName is the per-session directory backing the namespace /tmp bind
-// (strict profile). It lives inside the session subtree, so session
-// teardown removes it with everything else.
+// tmpDirName is the per-session directory backing the namespace /tmp bind.
const tmpDirName = "tmp"
// UpperManager manages upper directories for overlay workspaces.
@@ -162,11 +160,9 @@ func (m *UpperManager) TmpDir(sessionID string) string {
return filepath.Join(m.root, sessionID, tmpDirName)
}
-// allocateTmpDir creates the session's /tmp backing directory with real
-// /tmp semantics: world-writable + sticky, so uid-switched setpriv sessions
-// can create entries after the workload gate drops credentials (the old
-// --tmpfs /tmp was kernel-mounted world-writable too). Chmod is explicit
-// because a restrictive umask would strip the write bits from MkdirAll.
+// allocateTmpDir creates the /tmp backing dir 01777 so uid-switched
+// setpriv sessions keep the old --tmpfs write semantics; the explicit
+// Chmod survives a restrictive umask.
func allocateTmpDir(sessionDir string) error {
tmpDir := filepath.Join(sessionDir, tmpDirName)
if err := os.MkdirAll(tmpDir, 0o777); err != nil {
@@ -357,8 +353,7 @@ func (m *UpperManager) Usage() (int64, error) {
// usageLocked calculates usage without acquiring the mutex. Caller must hold m.mu.
// Missing released upper directories are tolerated as cleanup residue. A missing
// in-use upper makes the measurement invalid instead of reporting false zero.
-// Each entry's /tmp backing dir counts toward usage too, so the maxBytes
-// admission gate bounds /tmp growth like overlay uppers.
+// The /tmp backing dir counts toward usage so maxBytes bounds its growth.
func (m *UpperManager) usageLocked() (int64, error) {
var total int64
for _, e := range m.entries {
diff --git a/components/execd/pkg/runtime/bwrap_test/bwrap_tmp_files_test.go b/components/execd/pkg/runtime/bwrap_test/bwrap_tmp_files_test.go
index be30d494b..381cac575 100644
--- a/components/execd/pkg/runtime/bwrap_test/bwrap_tmp_files_test.go
+++ b/components/execd/pkg/runtime/bwrap_test/bwrap_tmp_files_test.go
@@ -177,10 +177,8 @@ func TestTmpFiles_MountOnTmpServedByFilesAPI(t *testing.T) {
assert.Equal(t, "mount-tmp\n", string(data))
}
-// TestTmpFiles_SymlinkEscapeConfined: /tmp is attacker-controlled, so a
-// symlink planted by the workload must not redirect a files-API write (or
-// read) outside the session's backing dir. The confined view rejects the
-// traversal where the trusted bind view would have followed it.
+// TestTmpFiles_SymlinkEscapeConfined: a workload-planted symlink must not
+// redirect files-API reads or writes outside the session's backing dir.
func TestTmpFiles_SymlinkEscapeConfined(t *testing.T) {
r, upperRoot := newStrictRunner(t)
id := strictSession(t, r)
@@ -211,9 +209,8 @@ func TestTmpFiles_SymlinkEscapeConfined(t *testing.T) {
assert.Equal(t, "local\n", string(data))
}
-// TestTmpFiles_MountRootRemovalRejected: deleting /tmp itself would unlink
-// the host backing dir under the live bind, so the files API rejects it
-// while child removal keeps working.
+// TestTmpFiles_MountRootRemovalRejected: removing /tmp itself would unlink
+// the backing dir under the live bind; child removal keeps working.
func TestTmpFiles_MountRootRemovalRejected(t *testing.T) {
r, _ := newStrictRunner(t)
id := strictSession(t, r)
@@ -232,9 +229,8 @@ func TestTmpFiles_MountRootRemovalRejected(t *testing.T) {
require.NoError(t, mv.Remove("/tmp/keep.txt"), "child removal must keep working")
}
-// TestTmpFiles_UIDSwitchedSessionCanWrite: the backing dir is world-writable
-// + sticky, restoring the --tmpfs /tmp semantics for setpriv sessions that
-// drop to a non-root uid.
+// TestTmpFiles_UIDSwitchedSessionCanWrite: the 01777 backing dir restores
+// the --tmpfs /tmp semantics for sessions dropping to a non-root uid.
func TestTmpFiles_UIDSwitchedSessionCanWrite(t *testing.T) {
r, _ := newStrictRunner(t)
diff --git a/components/execd/pkg/runtime/isolated_session.go b/components/execd/pkg/runtime/isolated_session.go
index 8045564f6..af19b4556 100644
--- a/components/execd/pkg/runtime/isolated_session.go
+++ b/components/execd/pkg/runtime/isolated_session.go
@@ -131,10 +131,9 @@ type isolatedSession struct {
doneCh chan struct{} // closed after process wait and lifecycle drain
lifecycleMonitorDone chan struct{} // closed after drain-failure monitor exits
upperID string // key in UpperManager, used for Release/Remove
- // tmpDir is the host directory backing the namespace /tmp bind (strict
- // profile, no overlay covering /tmp). Empty keeps the profile's /tmp
- // segment; when set, the files view serves /tmp from it. Immutable
- // after allocation.
+ // tmpDir is the host dir backing the namespace /tmp bind (strict
+ // profile); empty when /tmp is not hosted. Served by the files view.
+ // Immutable after allocation.
tmpDir string
overlays []sessionOverlay
createdAt time.Time
@@ -198,9 +197,8 @@ func (s *isolatedSession) start() error {
wrapOpts := isolation.WrapOptions{
ExtraWritable: s.opts.ExtraWritable,
Binds: s.opts.Binds,
- // Empty for balanced sessions and sessions whose overlays cover
- // /tmp: allocation only sets tmpDir for the hosted-private-/tmp
- // shape, and bwrap falls back to the profile segment on empty.
+ // Empty when /tmp is not hosted; bwrap falls back to the profile
+ // segment.
TmpDir: s.tmpDir,
ShareNet: true,
}
diff --git a/components/execd/pkg/runtime/isolated_session_binds_view_test.go b/components/execd/pkg/runtime/isolated_session_binds_view_test.go
index 148c3f388..542abdb48 100644
--- a/components/execd/pkg/runtime/isolated_session_binds_view_test.go
+++ b/components/execd/pkg/runtime/isolated_session_binds_view_test.go
@@ -591,10 +591,9 @@ func TestNewMergedView_BindOnTmpShadowsTmpBind(t *testing.T) {
}
}
-// TestNewMergedView_TmpMountRootRemovalRejected: the hosted /tmp view is a
-// bind-style mount; removing the mount root itself would unlink the host
-// backing dir while the namespace keeps the mount, so the router rejects it
-// while child removal keeps working.
+// TestNewMergedView_TmpMountRootRemovalRejected: removing the /tmp mount
+// root would unlink the host backing dir under the live mount; the router
+// rejects it while child removal keeps working.
func TestNewMergedView_TmpMountRootRemovalRejected(t *testing.T) {
base, err := filepath.EvalSymlinks(t.TempDir())
if err != nil {
diff --git a/components/execd/pkg/runtime/isolated_session_ctrl.go b/components/execd/pkg/runtime/isolated_session_ctrl.go
index 602beb99e..7c4912cd2 100644
--- a/components/execd/pkg/runtime/isolated_session_ctrl.go
+++ b/components/execd/pkg/runtime/isolated_session_ctrl.go
@@ -460,8 +460,8 @@ func sessionTmpBindHosted(session *isolatedSession) bool {
return optsTmpBindHosted(session.opts, session.overlays)
}
-// optsTmpBindHosted is the options-level form of sessionTmpBindHosted,
-// usable during create validation before the session exists.
+// optsTmpBindHosted is the options-level form of sessionTmpBindHosted for
+// create-time validation, before the session exists.
func optsTmpBindHosted(opts *IsolatedSessionOptions, overlays []sessionOverlay) bool {
switch isolation.Profile(opts.Profile) {
case isolation.ProfileStrict, "":
@@ -476,10 +476,9 @@ func optsTmpBindHosted(opts *IsolatedSessionOptions, overlays []sessionOverlay)
}
// allocateSessionUppers assigns host upper/work pairs to a session's
-// persistent overlays. Ephemeral overlays use the bwrap tmpfs upper and need
-// no allocation, but every session still gets an upper-root subtree: it
-// holds the /tmp backing directory and the durable cleanup record that makes
-// teardown crash-safe.
+// persistent overlays. Ephemeral overlays need no pairs, but every session
+// still gets an upper-root subtree: it holds the /tmp backing dir and the
+// durable cleanup record that makes teardown crash-safe.
func (r *IsolatedRunner) allocateSessionUppers(session *isolatedSession) error {
persistCount := 0
for _, ov := range session.overlays {
@@ -1081,15 +1080,11 @@ func newMergedView(s *isolatedSession) vfs.FS {
}
}
- // The strict profile's private /tmp is the session's host-backed bind
- // under its upper-root subtree; serve it so files and run share one
- // /tmp view. Appending it last is safe: no overlay shares the /tmp
- // destination (guarded at allocation), deeper overlay prefixes win by
- // length, and binds registered earlier keep the equal-prefix tie
- // against a caller bind on /tmp — mirroring bwrap's argv shadow order.
- // The view is root-confined (os.Root): /tmp is attacker-controlled, so
- // a symlink planted by the workload must not redirect a files-API write
- // outside the session's backing dir the way the trusted-bind view would.
+ // The hosted /tmp view is appended last, which is safe: no overlay
+ // shares the /tmp destination, deeper prefixes win by length, and binds
+ // registered earlier keep the equal-prefix tie — mirroring bwrap's argv
+ // shadow order. The view is root-confined (os.Root): /tmp is attacker-
+ // controlled, so planted symlinks must not redirect files-API writes.
if s.tmpDir != "" {
views = append(views, isolation.OverlayView{
Path: "/tmp",
@@ -1307,13 +1302,11 @@ func validateNormalizedCreate(opts *IsolatedSessionOptions) error {
if err := validateBindMountStack(opts.Overlays, opts.ExtraWritable, opts.Binds); err != nil {
return err
}
- // A hosted private /tmp is mounted before extra_writable binds, so an
- // extra_writable path at or under /tmp shadows it inside the namespace —
- // but extra_writable mounts are not registered as files views, so the
- // files API would still serve the backing dir. Reject the overlap.
- // validateExtraWritable has already rewritten the paths to their
- // symlink-resolved form, so /tmp's resolved prefix is matched too
- // (darwin's /tmp -> /private/tmp).
+ // A hosted /tmp is mounted before extra_writable binds, which are not
+ // files views, so an extra_writable at or under /tmp would make run and
+ // files see different directories. validateExtraWritable has already
+ // rewritten paths to symlink-resolved form, so /tmp's resolved prefix
+ // is matched too (darwin's /tmp -> /private/tmp).
if optsTmpBindHosted(opts, overlays) {
tmpPrefixes := []string{"/tmp"}
if resolved, err := filepath.EvalSymlinks("/tmp"); err == nil && resolved != "/tmp" {
diff --git a/components/execd/pkg/runtime/isolated_session_overlays_test.go b/components/execd/pkg/runtime/isolated_session_overlays_test.go
index ffa66ac72..06956786e 100644
--- a/components/execd/pkg/runtime/isolated_session_overlays_test.go
+++ b/components/execd/pkg/runtime/isolated_session_overlays_test.go
@@ -511,10 +511,8 @@ func TestNewMergedView_MultiOverlayRouting(t *testing.T) {
}
// TestCreateIsolatedSession_ExtraWritableOnTmpRejected: an extra_writable
-// path at or under /tmp shadows the hosted private /tmp inside the
-// namespace (bwrap applies extra binds after the /tmp bind) while the files
-// view would keep serving the backing dir, so create must reject the
-// overlap for hosted sessions only.
+// under /tmp shadows the hosted /tmp in the namespace while the files view
+// keeps serving the backing dir, so hosted sessions must reject the overlap.
func TestCreateIsolatedSession_ExtraWritableOnTmpRejected(t *testing.T) {
allowTmp := func(r *IsolatedRunner) {
r.allowedWritable = []string{"/tmp"}