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.goindex 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.goindex 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.goindex 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.goindex 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 []OverlaySpecExtraWritable []stringBinds []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 stringShareNet boolEnvPassthrough EnvSpecdiff --git a/components/execd/pkg/isolation/merged_view_router.go b/components/execd/pkg/isolation/merged_view_router.goindex 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.goindex 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 int64for _, 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.goindex 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.goindex 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 drainlifecycleMonitorDone chan struct{} // closed after drain-failure monitor exitsupperID 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 stringoverlays []sessionOverlaycreatedAt 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.goindex 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.goindex 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 := 0for _, 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.goindex 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"}