Skip to content

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

fix(execd): harden the hosted session /tmp after review

高然8d81b8f5a17e
diff --git a/components/execd/pkg/isolation/bwrap.go b/components/execd/pkg/isolation/bwrap.go
index 611716fee..f563522d4 100644
--- a/components/execd/pkg/isolation/bwrap.go
+++ b/components/execd/pkg/isolation/bwrap.go
@@ -81,11 +81,28 @@ func buildArgvWithLifecycle(
}
argv = append(argv, ovArgv...)
- // Hide upper roots to prevent cross-session access. Every pair lives
- // under <upper_root>/<session_id>/, so a session's pairs share one
- // upper root in practice; dedupe keeps arbitrary caller-supplied
- // directories safe too.
- for _, upperRoot := range distinctUpperRoots(opts.Overlays) {
+ // 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.
+ hideRoots := distinctUpperRoots(opts.Overlays)
+ if opts.TmpDir != "" {
+ root := filepath.Dir(filepath.Dir(opts.TmpDir))
+ known := false
+ for _, r := range hideRoots {
+ if r == root {
+ known = true
+ break
+ }
+ }
+ if !known {
+ hideRoots = append(hideRoots, root)
+ }
+ }
+ for _, upperRoot := range hideRoots {
argv = append(argv, "--tmpfs", upperRoot)
}
@@ -221,7 +238,11 @@ func validateWrapOptions(opts WrapOptions) error {
if len(opts.Overlays) == 0 {
return errors.New("isolation: at least one overlay is required")
}
- if err := validateOverlaySpecs(opts.Overlays); err != nil {
+ var tmpRoot string
+ if opts.TmpDir != "" {
+ tmpRoot = filepath.Dir(filepath.Dir(opts.TmpDir))
+ }
+ if err := validateOverlaySpecs(opts.Overlays, tmpRoot); err != nil {
return err
}
if !opts.Profile.Valid() {
@@ -233,13 +254,24 @@ func validateWrapOptions(opts WrapOptions) error {
if opts.UidMode != "" && !opts.UidMode.Valid() {
return fmt.Errorf("isolation: unknown uid mode %q", opts.UidMode)
}
- if opts.TmpDir != "" && !filepath.IsAbs(opts.TmpDir) {
- return fmt.Errorf("isolation: tmp dir %q must be an absolute path", opts.TmpDir)
+ if opts.TmpDir != "" {
+ 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.
+ if pathDepth(opts.TmpDir) < 3 {
+ return fmt.Errorf(
+ "isolation: tmp dir %q must live under an upper root (<root>/<session>/tmp)",
+ opts.TmpDir,
+ )
+ }
}
return validateBinds(opts.Binds)
}
-func validateOverlaySpecs(overlays []OverlaySpec) error {
+func validateOverlaySpecs(overlays []OverlaySpec, extraHideRoot string) error {
seen := make(map[string]struct{}, len(overlays))
for i := range overlays {
if err := validateOverlaySpec(&overlays[i]); err != nil {
@@ -254,7 +286,13 @@ func validateOverlaySpecs(overlays []OverlaySpec) 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.
- for _, upperRoot := range distinctUpperRoots(overlays) {
+ // extraHideRoot is the /tmp backing dir's derived root, hidden the same
+ // way for sessions without persistent overlay uppers.
+ hideRoots := distinctUpperRoots(overlays)
+ if extraHideRoot != "" {
+ hideRoots = append(hideRoots, extraHideRoot)
+ }
+ for _, upperRoot := range hideRoots {
for i := range overlays {
p := filepath.Clean(overlays[i].Path)
if p == upperRoot || strings.HasPrefix(p, upperRoot+"/") {
@@ -339,6 +377,13 @@ 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.
+ if filepath.Clean(b.Dest) == "/" {
+ return fmt.Errorf(`isolation: bind.dest "/" would shadow the namespace root`)
+ }
}
return nil
}
diff --git a/components/execd/pkg/isolation/bwrap_test.go b/components/execd/pkg/isolation/bwrap_test.go
index 542968e4d..30e37437a 100644
--- a/components/execd/pkg/isolation/bwrap_test.go
+++ b/components/execd/pkg/isolation/bwrap_test.go
@@ -948,3 +948,57 @@ func indexOf(items []string, s string) int {
}
return -1
}
+
+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.
+ opts := basicWrapOpts()
+ opts.Overlays = []OverlaySpec{{Path: "/workspace", Mode: WorkspaceRW}}
+ opts.TmpDir = "/var/lib/execd/isolation/abc/tmp"
+ argv, err := buildArgv(opts, "")
+ if err != nil {
+ t.Fatalf("unexpected error: %v", err)
+ }
+ s := strings.Join(argv, " ")
+ if !strings.Contains(s, "--tmpfs /var/lib/execd/isolation") {
+ t.Errorf("missing upper-root hiding tmpfs for the /tmp backing dir:\n %s", s)
+ }
+ })
+
+ t.Run("overlay_derived_and_tmp_derived_roots_dedupe", func(t *testing.T) {
+ opts := basicWrapOpts()
+ opts.Overlays = []OverlaySpec{{
+ Path: "/workspace",
+ Mode: WorkspaceOverlay,
+ UpperDir: "/var/lib/execd/isolation/abc/upper",
+ }}
+ opts.TmpDir = "/var/lib/execd/isolation/abc/tmp"
+ argv, err := buildArgv(opts, "")
+ if err != nil {
+ t.Fatalf("unexpected error: %v", err)
+ }
+ if got := strings.Count(strings.Join(argv, " "), "--tmpfs /var/lib/execd/isolation"); got != 1 {
+ t.Errorf("hiding tmpfs count = %d, want 1 (deduped)", got)
+ }
+ })
+
+ t.Run("shallow_tmp_dir_rejected", func(t *testing.T) {
+ opts := basicWrapOpts()
+ opts.TmpDir = "/x/tmp"
+ _, err := buildArgv(opts, "")
+ if err == nil || !strings.Contains(err.Error(), "upper root") {
+ t.Fatalf("error = %v, want shallow upper-root rejection", err)
+ }
+ })
+}
+
+func TestBuildArgv_BindDestRootRejected(t *testing.T) {
+ opts := basicWrapOpts()
+ opts.Binds = []BindMount{{Source: "/data", Dest: "/"}}
+ _, err := buildArgv(opts, "")
+ if err == nil || !strings.Contains(err.Error(), "shadow the namespace root") {
+ t.Fatalf("error = %v, want namespace-root shadow rejection", err)
+ }
+}
diff --git a/components/execd/pkg/isolation/confined_view.go b/components/execd/pkg/isolation/confined_view.go
new file mode 100644
index 000000000..bf7cc29f2
--- /dev/null
+++ b/components/execd/pkg/isolation/confined_view.go
@@ -0,0 +1,319 @@
+// Copyright 2026 The OpenSandbox Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package isolation
+
+import (
+ "fmt"
+ "io"
+ "io/fs"
+ "os"
+ "path/filepath"
+ "sort"
+ "strings"
+
+ "github.com/alibaba/opensandbox/execd/pkg/vfs"
+)
+
+// 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.
+//
+// The kernel-backed confinement requires openat2 (Linux 5.6+); on older
+// kernels os.OpenRoot fails and the files API surfaces that error.
+//
+// Compile-time check: ConfinedView satisfies vfs.FS.
+var _ vfs.FS = (*ConfinedView)(nil)
+
+// ConfinedView is a root-confined vfs.FS over one host directory.
+type ConfinedView struct {
+ Root string
+ // Uid/Gid own newly created files, mirroring the BindView chown so
+ // in-namespace identities can access what the files API creates.
+ Uid, Gid uint32
+}
+
+// NewConfinedView creates a confined view over root.
+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.
+func (c *ConfinedView) rel(path string) (string, error) {
+ cleaned := filepath.Clean(path)
+ switch {
+ case cleaned == c.Root || cleaned == "/tmp":
+ return ".", nil
+ case strings.HasPrefix(cleaned, c.Root+"/"):
+ return strings.TrimPrefix(cleaned, c.Root+"/"), nil
+ case strings.HasPrefix(cleaned, "/tmp/"):
+ return strings.TrimPrefix(cleaned, "/tmp/"), nil
+ }
+ return "", fmt.Errorf("path %q is outside the confined view root %q", path, c.Root)
+}
+
+func (c *ConfinedView) openRoot() (*os.Root, error) {
+ return os.OpenRoot(c.Root)
+}
+
+// chownNew moves ownership of a created entry to the session identity.
+func (c *ConfinedView) chownNew(root *os.Root, name string) error {
+ return root.Chown(name, int(c.Uid), int(c.Gid))
+}
+
+func (c *ConfinedView) Stat(path string) (os.FileInfo, error) {
+ name, err := c.rel(path)
+ if err != nil {
+ return nil, err
+ }
+ root, err := c.openRoot()
+ if err != nil {
+ return nil, err
+ }
+ defer root.Close()
+ return root.Stat(name)
+}
+
+func (c *ConfinedView) ReadFile(path string) ([]byte, error) {
+ name, err := c.rel(path)
+ if err != nil {
+ return nil, err
+ }
+ root, err := c.openRoot()
+ if err != nil {
+ return nil, err
+ }
+ defer root.Close()
+ return root.ReadFile(name)
+}
+
+func (c *ConfinedView) WriteFile(path string, data []byte, perm os.FileMode) error {
+ name, err := c.rel(path)
+ if err != nil {
+ return err
+ }
+ root, err := c.openRoot()
+ if err != nil {
+ return err
+ }
+ defer root.Close()
+ if dir := filepath.Dir(name); dir != "." {
+ if err := root.MkdirAll(dir, 0o755); err != nil {
+ return err
+ }
+ }
+ if err := root.WriteFile(name, data, perm); err != nil {
+ return err
+ }
+ return c.chownNew(root, name)
+}
+
+func (c *ConfinedView) WriteFileReader(path string, r io.Reader, perm os.FileMode) (int64, error) {
+ name, err := c.rel(path)
+ if err != nil {
+ return 0, err
+ }
+ root, err := c.openRoot()
+ if err != nil {
+ return 0, err
+ }
+ defer root.Close()
+ if dir := filepath.Dir(name); dir != "." {
+ if err := root.MkdirAll(dir, 0o755); err != nil {
+ return 0, err
+ }
+ }
+ f, err := root.OpenFile(name, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, perm)
+ if err != nil {
+ return 0, err
+ }
+ defer f.Close()
+ n, err := io.Copy(f, r)
+ if err != nil {
+ return n, err
+ }
+ return n, c.chownNew(root, name)
+}
+
+func (c *ConfinedView) Remove(path string) error {
+ name, err := c.rel(path)
+ if err != nil {
+ return err
+ }
+ if name == "." {
+ return fmt.Errorf("cannot remove the confined view root %q", c.Root)
+ }
+ root, err := c.openRoot()
+ if err != nil {
+ return err
+ }
+ defer root.Close()
+ return root.Remove(name)
+}
+
+func (c *ConfinedView) RemoveAll(path string) error {
+ name, err := c.rel(path)
+ if err != nil {
+ return err
+ }
+ if name == "." {
+ return fmt.Errorf("cannot remove the confined view root %q", c.Root)
+ }
+ root, err := c.openRoot()
+ if err != nil {
+ return err
+ }
+ defer root.Close()
+ return root.RemoveAll(name)
+}
+
+func (c *ConfinedView) MkdirAll(path string, perm os.FileMode) error {
+ name, err := c.rel(path)
+ if err != nil {
+ return err
+ }
+ root, err := c.openRoot()
+ if err != nil {
+ return err
+ }
+ defer root.Close()
+ if err := root.MkdirAll(name, perm); err != nil {
+ return err
+ }
+ return c.chownNew(root, name)
+}
+
+func (c *ConfinedView) Rename(oldPath, newPath string) error {
+ oldName, err := c.rel(oldPath)
+ if err != nil {
+ return err
+ }
+ newName, err := c.rel(newPath)
+ if err != nil {
+ return err
+ }
+ root, err := c.openRoot()
+ if err != nil {
+ return err
+ }
+ defer root.Close()
+ if dir := filepath.Dir(newName); dir != "." {
+ if err := root.MkdirAll(dir, 0o755); err != nil {
+ return err
+ }
+ }
+ return root.Rename(oldName, newName)
+}
+
+func (c *ConfinedView) Chmod(path string, mode os.FileMode) error {
+ name, err := c.rel(path)
+ if err != nil {
+ return err
+ }
+ root, err := c.openRoot()
+ if err != nil {
+ return err
+ }
+ defer root.Close()
+ return root.Chmod(name, mode)
+}
+
+func (c *ConfinedView) ReadDir(path string) ([]os.DirEntry, error) {
+ name, err := c.rel(path)
+ if err != nil {
+ return nil, err
+ }
+ root, err := c.openRoot()
+ if err != nil {
+ return nil, err
+ }
+ defer root.Close()
+ f, err := root.Open(name)
+ if err != nil {
+ return nil, err
+ }
+ defer f.Close()
+ return f.ReadDir(-1)
+}
+
+func (c *ConfinedView) Open(path string) (*os.File, error) {
+ name, err := c.rel(path)
+ if err != nil {
+ return nil, err
+ }
+ root, err := c.openRoot()
+ if err != nil {
+ return nil, err
+ }
+ defer root.Close()
+ 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.
+func (c *ConfinedView) Search(rootPath, pattern string) ([]string, error) {
+ base, err := c.rel(rootPath)
+ if err != nil {
+ return nil, err
+ }
+ root, err := c.openRoot()
+ if err != nil {
+ return nil, err
+ }
+ defer root.Close()
+
+ fsys := root.FS()
+ var results []string
+ _ = fs.WalkDir(fsys, base, func(p string, d fs.DirEntry, err error) error {
+ if err != nil {
+ return nil //nolint:nilerr // skip unreadable or escaping entries
+ }
+ if d.IsDir() {
+ return nil
+ }
+ if matched, _ := filepath.Match(pattern, filepath.Base(p)); matched {
+ results = append(results, p)
+ }
+ return nil
+ })
+ sort.Strings(results)
+ return results, nil
+}
+
+func (c *ConfinedView) ReplaceContent(path, old, newStr string) error {
+ data, err := c.ReadFile(path)
+ if err != nil {
+ return err
+ }
+ content := strings.ReplaceAll(string(data), old, newStr)
+ info, err := c.Stat(path)
+ if err != nil {
+ return err
+ }
+ return c.WriteFile(path, []byte(content), info.Mode().Perm())
+}
diff --git a/components/execd/pkg/isolation/confined_view_test.go b/components/execd/pkg/isolation/confined_view_test.go
new file mode 100644
index 000000000..fd6d7c519
--- /dev/null
+++ b/components/execd/pkg/isolation/confined_view_test.go
@@ -0,0 +1,186 @@
+// Copyright 2026 The OpenSandbox Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package isolation
+
+import (
+ "os"
+ "path/filepath"
+ "syscall"
+ "testing"
+)
+
+func newConfinedView(t *testing.T) (*ConfinedView, string) {
+ t.Helper()
+ root, err := filepath.EvalSymlinks(t.TempDir())
+ if err != nil {
+ t.Fatal(err)
+ }
+ // Mirror the production view builder: it passes the session identity
+ // (or execd's own), which chown always permits.
+ return NewConfinedView(root, uint32(os.Getuid()), uint32(os.Getgid())), root
+}
+
+func TestConfinedView_BasicRoundTrip(t *testing.T) {
+ view, root := newConfinedView(t)
+
+ if err := view.WriteFile("/tmp/note.txt", []byte("hello"), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ if got, err := os.ReadFile(filepath.Join(root, "note.txt")); err != nil || string(got) != "hello" {
+ t.Fatalf("host file = %q, %v", got, err)
+ }
+ data, err := view.ReadFile("/tmp/note.txt")
+ if err != nil || string(data) != "hello" {
+ t.Fatalf("ReadFile = %q, %v", data, err)
+ }
+ if _, err := view.Stat("/tmp/note.txt"); err != nil {
+ t.Fatalf("Stat = %v", err)
+ }
+
+ if err := view.MkdirAll("/tmp/sub/deep", 0o755); err != nil {
+ t.Fatal(err)
+ }
+ if err := view.WriteFile("/tmp/sub/deep/a.log", []byte("A"), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ entries, err := view.ReadDir("/tmp")
+ if err != nil {
+ t.Fatal(err)
+ }
+ names := make(map[string]bool, len(entries))
+ for _, e := range entries {
+ names[e.Name()] = true
+ }
+ if !names["note.txt"] || !names["sub"] {
+ t.Fatalf("ReadDir missing entries: %v", names)
+ }
+
+ results, err := view.Search("/tmp", "**.log")
+ if err != nil || len(results) != 1 || results[0] != "sub/deep/a.log" {
+ t.Fatalf("Search = %v, %v; want [sub/deep/a.log]", results, err)
+ }
+
+ if err := view.ReplaceContent("/tmp/note.txt", "hello", "world"); err != nil {
+ t.Fatal(err)
+ }
+ if got, _ := os.ReadFile(filepath.Join(root, "note.txt")); string(got) != "world" {
+ t.Fatalf("ReplaceContent left %q", got)
+ }
+
+ if err := view.Rename("/tmp/note.txt", "/tmp/sub/renamed.txt"); err != nil {
+ t.Fatal(err)
+ }
+ if _, err := os.Stat(filepath.Join(root, "sub", "renamed.txt")); err != nil {
+ t.Fatalf("rename target missing: %v", err)
+ }
+
+ if err := view.Remove("/tmp/sub/renamed.txt"); err != nil {
+ t.Fatal(err)
+ }
+ if _, err := os.Stat(filepath.Join(root, "sub", "renamed.txt")); !os.IsNotExist(err) {
+ t.Fatalf("removed file still present: %v", err)
+ }
+}
+
+func TestConfinedView_RejectsSymlinkEscape(t *testing.T) {
+ view, root := newConfinedView(t)
+ outside := filepath.Join(filepath.Dir(root), "confined-outside.txt")
+ if err := os.WriteFile(outside, []byte("host"), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ t.Cleanup(func() { _ = os.Remove(outside) })
+
+ if err := os.Symlink(outside, filepath.Join(root, "abs")); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.MkdirAll(filepath.Join(root, "dir"), 0o755); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.Symlink("../../"+filepath.Base(filepath.Dir(root))+"/"+filepath.Base(outside), filepath.Join(root, "dir", "rel")); err != nil {
+ t.Fatal(err)
+ }
+
+ for _, p := range []string{"/tmp/abs", "/tmp/dir/rel"} {
+ if _, err := view.ReadFile(p); err == nil {
+ t.Errorf("ReadFile %s through escaping symlink = nil error, want rejection", p)
+ }
+ if _, err := view.Stat(p); err == nil {
+ t.Errorf("Stat %s through escaping symlink = nil error, want rejection", p)
+ }
+ if err := view.WriteFile(p, []byte("evil"), 0o644); err == nil {
+ t.Errorf("WriteFile %s through escaping symlink = nil error, want rejection", p)
+ }
+ }
+
+ // The outside file must be untouched.
+ got, err := os.ReadFile(outside)
+ if err != nil || string(got) != "host" {
+ t.Fatalf("outside file = %q, %v; escape must not write through", got, err)
+ }
+}
+
+func TestConfinedView_FollowsInRootSymlink(t *testing.T) {
+ view, root := newConfinedView(t)
+ if err := os.WriteFile(filepath.Join(root, "target.txt"), []byte("in-root"), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ // Relative in-root targets match what workloads create; os.Root rejects
+ // absolute link targets outright (see the ConfinedView doc comment).
+ if err := os.Symlink("target.txt", filepath.Join(root, "link.txt")); err != nil {
+ t.Fatal(err)
+ }
+ data, err := view.ReadFile("/tmp/link.txt")
+ if err != nil || string(data) != "in-root" {
+ t.Fatalf("in-root symlink ReadFile = %q, %v", data, err)
+ }
+}
+
+func TestConfinedView_ChownsCreatedFiles(t *testing.T) {
+ if os.Geteuid() != 0 {
+ t.Skip("chown assertion requires root")
+ }
+ root, err := filepath.EvalSymlinks(t.TempDir())
+ if err != nil {
+ t.Fatal(err)
+ }
+ view := NewConfinedView(root, 0, 0)
+ if err := view.WriteFile("/tmp/owned.txt", []byte("x"), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ info, err := os.Stat(filepath.Join(root, "owned.txt"))
+ if err != nil {
+ t.Fatal(err)
+ }
+ stat, ok := info.Sys().(*syscall.Stat_t)
+ if !ok {
+ t.Skip("stat_t unavailable on this platform")
+ }
+ if stat.Uid != 0 {
+ t.Fatalf("file uid = %d, want 0", stat.Uid)
+ }
+}
+
+func TestConfinedView_RejectsRootRemoval(t *testing.T) {
+ view, _ := newConfinedView(t)
+ if err := view.Remove("/tmp"); err == nil {
+ t.Error("Remove of the view root must be rejected")
+ }
+ if err := view.RemoveAll("/tmp"); err == nil {
+ t.Error("RemoveAll of the view root must be rejected")
+ }
+ if _, err := view.Stat("/tmp"); err != nil {
+ t.Fatalf("root must survive removal attempts: %v", err)
+ }
+}
diff --git a/components/execd/pkg/isolation/merged_view_router.go b/components/execd/pkg/isolation/merged_view_router.go
index 0fb13c001..e140e10e4 100644
--- a/components/execd/pkg/isolation/merged_view_router.go
+++ b/components/execd/pkg/isolation/merged_view_router.go
@@ -209,6 +209,9 @@ func (m *MultiMergedView) Remove(path string) error {
if err != nil {
return err
}
+ if err := rejectMountRootRemoval(rt, path); err != nil {
+ return err
+ }
return rt.fs.Remove(p)
}
@@ -217,9 +220,25 @@ func (m *MultiMergedView) RemoveAll(path string) error {
if err != nil {
return err
}
+ if err := rejectMountRootRemoval(rt, path); err != nil {
+ return err
+ }
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.
+// 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 {
+ return fmt.Errorf("cannot remove mount root %q", rt.prefix)
+ }
+ return nil
+}
+
func (m *MultiMergedView) MkdirAll(path string, perm os.FileMode) error {
rt, p, err := m.route(path)
if err != nil {
diff --git a/components/execd/pkg/isolation/upper.go b/components/execd/pkg/isolation/upper.go
index 19cec78a3..0a7214700 100644
--- a/components/execd/pkg/isolation/upper.go
+++ b/components/execd/pkg/isolation/upper.go
@@ -162,6 +162,22 @@ 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.
+func allocateTmpDir(sessionDir string) error {
+ tmpDir := filepath.Join(sessionDir, tmpDirName)
+ if err := os.MkdirAll(tmpDir, 0o777); err != nil {
+ return fmt.Errorf("upper: mkdir %s: %w", tmpDir, err)
+ }
+ if err := os.Chmod(tmpDir, 0o777|os.ModeSticky); err != nil {
+ return fmt.Errorf("upper: chmod %s: %w", tmpDir, err)
+ }
+ return nil
+}
+
// AllocateSessionDir creates a session directory without overlay pairs, for
// sessions whose mounts need no host uppers. The directory still carries a
// durable cleanup record and holds the session's /tmp backing directory, so
@@ -187,11 +203,14 @@ func (m *UpperManager) AllocateSessionDir() (sessionID string, err error) {
return "", err
}
sessionDir := filepath.Join(m.root, id)
- if err := os.MkdirAll(filepath.Join(sessionDir, tmpDirName), 0o755); err != nil {
+ if err := allocateTmpDir(sessionDir); err != nil {
if rollbackErr := m.rollbackAllocationLocked(id, sessionDir, nil); rollbackErr != nil {
- return "", errors.Join(err, rollbackErr)
+ return "", errors.Join(
+ fmt.Errorf("upper: allocate session dir %s: %w", sessionDir, err),
+ rollbackErr,
+ )
}
- return "", fmt.Errorf("upper: mkdir session dir %s: %w", sessionDir, err)
+ return "", fmt.Errorf("upper: allocate session dir %s: %w", sessionDir, err)
}
m.entries[id] = &UpperEntry{InUse: true, dir: sessionDir}
return id, nil
@@ -234,8 +253,8 @@ func (m *UpperManager) AllocateN(n int) (sessionID string, pairs []UpperDirPair,
}
return "", nil, cause
}
- if err := os.MkdirAll(filepath.Join(sessionDir, tmpDirName), 0o755); err != nil {
- return failAllocation(fmt.Errorf("upper: mkdir %s: %w", filepath.Join(sessionDir, tmpDirName), err))
+ if err := allocateTmpDir(sessionDir); err != nil {
+ return failAllocation(err)
}
for i := range n {
upperName, workName := "upper", "work"
@@ -338,6 +357,8 @@ 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.
func (m *UpperManager) usageLocked() (int64, error) {
var total int64
for _, e := range m.entries {
@@ -351,6 +372,16 @@ func (m *UpperManager) usageLocked() (int64, error) {
}
total += size
}
+ if dir := e.sessionDir(); dir != "" {
+ size, err := dirSize(filepath.Join(dir, tmpDirName))
+ if err != nil {
+ if errors.Is(err, fs.ErrNotExist) && !e.InUse {
+ continue
+ }
+ return 0, err
+ }
+ total += size
+ }
}
return total, nil
}
diff --git a/components/execd/pkg/isolation/upper_test.go b/components/execd/pkg/isolation/upper_test.go
index dd9beded6..56c0cd4b2 100644
--- a/components/execd/pkg/isolation/upper_test.go
+++ b/components/execd/pkg/isolation/upper_test.go
@@ -795,3 +795,59 @@ func TestAllocateN_CreatesTmpDir(t *testing.T) {
}
}
}
+
+func TestAllocateTmpDirWorldWritableSticky(t *testing.T) {
+ mgr := newTestUpperManager(t)
+
+ for _, tc := range []struct {
+ name string
+ alloc func() (string, error)
+ }{
+ {"allocate_session_dir", func() (string, error) { return mgr.AllocateSessionDir() }},
+ {"allocate_n", func() (string, error) {
+ id, _, err := mgr.AllocateN(1)
+ return id, err
+ }},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ id, err := tc.alloc()
+ if err != nil {
+ t.Fatal(err)
+ }
+ info, err := os.Stat(mgr.TmpDir(id))
+ if err != nil {
+ t.Fatal(err)
+ }
+ if perm := info.Mode().Perm(); perm != 0o777 {
+ t.Fatalf("tmp dir perm = %#o, want 777", perm)
+ }
+ if info.Mode()&os.ModeSticky == 0 {
+ t.Fatal("tmp dir must be sticky")
+ }
+ })
+ }
+}
+
+func TestUsageCountsTmpDir(t *testing.T) {
+ mgr := newTestUpperManager(t)
+
+ id, err := mgr.AllocateSessionDir()
+ if err != nil {
+ t.Fatal(err)
+ }
+ before, err := mgr.Usage()
+ if err != nil {
+ t.Fatal(err)
+ }
+ payload := filepath.Join(mgr.TmpDir(id), "payload.bin")
+ if err := os.WriteFile(payload, make([]byte, 1024), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ after, err := mgr.Usage()
+ if err != nil {
+ t.Fatal(err)
+ }
+ if after-before < 1024 {
+ t.Fatalf("usage grew by %d bytes, want >= 1024 (tmp dir must count)", after-before)
+ }
+}
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 6ca4ef5ae..be30d494b 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
@@ -176,3 +176,84 @@ func TestTmpFiles_MountOnTmpServedByFilesAPI(t *testing.T) {
require.NoError(t, err, "files API must serve a mount covering /tmp")
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.
+func TestTmpFiles_SymlinkEscapeConfined(t *testing.T) {
+ r, upperRoot := newStrictRunner(t)
+ id := strictSession(t, r)
+ backing := tmpBackingDir(t, upperRoot)
+
+ outside := filepath.Join(filepath.Dir(backing), "escape-canary.txt")
+ require.NoError(t, os.WriteFile(outside, []byte("host-secret"), 0o644))
+ t.Cleanup(func() { _ = os.Remove(outside) })
+
+ runInSession(t, r, id, "ln -s "+outside+" /tmp/escape", nil)
+
+ mv, err := r.GetMergedView(id)
+ require.NoError(t, err)
+
+ if _, err := mv.ReadFile("/tmp/escape"); err == nil {
+ t.Fatal("ReadFile through the escaping symlink must be rejected")
+ }
+ require.Error(t, mv.WriteFile("/tmp/escape", []byte("evil"), 0o644),
+ "WriteFile through the escaping symlink must be rejected")
+ got, err := os.ReadFile(outside)
+ require.NoError(t, err)
+ assert.Equal(t, "host-secret", string(got), "the host file must be untouched")
+
+ // In-root symlinks keep working, matching the namespace.
+ runInSession(t, r, id, "echo local > /tmp/target.txt && ln -s target.txt /tmp/link", nil)
+ data, err := mv.ReadFile("/tmp/link.txt")
+ require.NoError(t, err)
+ 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.
+func TestTmpFiles_MountRootRemovalRejected(t *testing.T) {
+ r, _ := newStrictRunner(t)
+ id := strictSession(t, r)
+
+ runInSession(t, r, id, "echo keep > /tmp/keep.txt", nil)
+
+ mv, err := r.GetMergedView(id)
+ require.NoError(t, err)
+ require.Error(t, mv.RemoveAll("/tmp"), "RemoveAll /tmp must be rejected")
+ require.Error(t, mv.Remove("/tmp"), "Remove /tmp must be rejected")
+
+ data, err := mv.ReadFile("/tmp/keep.txt")
+ require.NoError(t, err, "the backing dir must survive removal attempts")
+ assert.Equal(t, "keep\n", string(data))
+
+ 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.
+func TestTmpFiles_UIDSwitchedSessionCanWrite(t *testing.T) {
+ r, _ := newStrictRunner(t)
+
+ uid := uint32(1000)
+ gid := uint32(1000)
+ id, err := r.CreateIsolatedSession(&runtime.IsolatedSessionOptions{
+ WorkspacePath: t.TempDir(),
+ WorkspaceMode: "rw",
+ Uid: &uid,
+ Gid: &gid,
+ })
+ require.NoError(t, err)
+ t.Cleanup(func() { _ = r.DeleteIsolatedSession(id) })
+
+ runInSession(t, r, id, "id -u && echo uid-data > /tmp/uid.txt", nil)
+
+ mv, err := r.GetMergedView(id)
+ require.NoError(t, err)
+ data, err := mv.ReadFile("/tmp/uid.txt")
+ require.NoError(t, err, "the uid-switched session must be able to write /tmp")
+ assert.Equal(t, "uid-data\n", string(data))
+}
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 8988d39e5..148c3f388 100644
--- a/components/execd/pkg/runtime/isolated_session_binds_view_test.go
+++ b/components/execd/pkg/runtime/isolated_session_binds_view_test.go
@@ -590,3 +590,45 @@ func TestNewMergedView_BindOnTmpShadowsTmpBind(t *testing.T) {
t.Fatalf("ReadFile /tmp/marker.txt = %q, %v; want the caller bind to shadow the session /tmp bind", data, err)
}
}
+
+// 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.
+func TestNewMergedView_TmpMountRootRemovalRejected(t *testing.T) {
+ base, err := filepath.EvalSymlinks(t.TempDir())
+ if err != nil {
+ t.Fatal(err)
+ }
+ wsLower := filepath.Join(base, "ws")
+ tmpHost := filepath.Join(base, "session-dir", "tmp")
+ for _, dir := range []string{wsLower, tmpHost} {
+ if err := os.MkdirAll(dir, 0o755); err != nil {
+ t.Fatal(err)
+ }
+ }
+ if err := os.WriteFile(filepath.Join(tmpHost, "f.txt"), []byte("x"), 0o644); err != nil {
+ t.Fatal(err)
+ }
+
+ s := newBindsViewSession(t,
+ []IsolatedOverlayOptions{{Path: wsLower, Mode: "rw"}},
+ nil,
+ nil,
+ )
+ s.tmpDir = tmpHost
+ view := newMergedView(s)
+
+ if err := view.Remove("/tmp"); err == nil || !strings.Contains(err.Error(), "mount root") {
+ t.Fatalf("Remove /tmp = %v, want mount-root rejection", err)
+ }
+ if err := view.RemoveAll("/tmp"); err == nil || !strings.Contains(err.Error(), "mount root") {
+ t.Fatalf("RemoveAll /tmp = %v, want mount-root rejection", err)
+ }
+ if _, err := os.Stat(tmpHost); err != nil {
+ t.Fatalf("backing dir must survive removal attempts: %v", err)
+ }
+ if err := view.Remove("/tmp/f.txt"); err != nil {
+ t.Fatalf("child removal = %v, want nil", err)
+ }
+}
diff --git a/components/execd/pkg/runtime/isolated_session_ctrl.go b/components/execd/pkg/runtime/isolated_session_ctrl.go
index a7ba64d1d..602beb99e 100644
--- a/components/execd/pkg/runtime/isolated_session_ctrl.go
+++ b/components/execd/pkg/runtime/isolated_session_ctrl.go
@@ -457,13 +457,19 @@ func (r *IsolatedRunner) CreateIsolatedSession(opts *IsolatedSessionOptions) (st
// (the default) with no overlay covering /tmp. Only that shape hosts /tmp
// on the host side, so only it can be served by the files view.
func sessionTmpBindHosted(session *isolatedSession) bool {
- switch isolation.Profile(session.opts.Profile) {
+ return optsTmpBindHosted(session.opts, session.overlays)
+}
+
+// optsTmpBindHosted is the options-level form of sessionTmpBindHosted,
+// usable during create validation before the session exists.
+func optsTmpBindHosted(opts *IsolatedSessionOptions, overlays []sessionOverlay) bool {
+ switch isolation.Profile(opts.Profile) {
case isolation.ProfileStrict, "":
default:
return false
}
- specs := make([]isolation.OverlaySpec, 0, len(session.overlays))
- for _, ov := range session.overlays {
+ specs := make([]isolation.OverlaySpec, 0, len(overlays))
+ for _, ov := range overlays {
specs = append(specs, isolation.OverlaySpec{Path: ov.path, Mode: ov.mode})
}
return !isolation.OverlaysCoverPath(specs, "/tmp")
@@ -1081,11 +1087,14 @@ func newMergedView(s *isolatedSession) vfs.FS {
// 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.
if s.tmpDir != "" {
views = append(views, isolation.OverlayView{
Path: "/tmp",
Root: s.tmpDir,
- FS: isolation.NewBindView(s.tmpDir, false, uid, gid),
+ FS: isolation.NewConfinedView(s.tmpDir, uid, gid),
})
}
@@ -1290,11 +1299,39 @@ func validateNormalizedCreate(opts *IsolatedSessionOptions) error {
if len(opts.Overlays) == 0 {
return fmt.Errorf("at least one overlay is required")
}
+ overlays := resolveSessionOverlays(opts)
// Keep the files view and the namespace in agreement: a bind whose
// destination shadows (or is shadowed by) another caller mount would be
// served by different host directories through session.run and
// session.files, so reject the overlap up front.
- return validateBindMountStack(opts.Overlays, opts.ExtraWritable, opts.Binds)
+ 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).
+ if optsTmpBindHosted(opts, overlays) {
+ tmpPrefixes := []string{"/tmp"}
+ if resolved, err := filepath.EvalSymlinks("/tmp"); err == nil && resolved != "/tmp" {
+ tmpPrefixes = append(tmpPrefixes, resolved)
+ }
+ for _, p := range opts.ExtraWritable {
+ cleaned := filepath.Clean(p)
+ for _, prefix := range tmpPrefixes {
+ if cleaned == prefix || strings.HasPrefix(cleaned, prefix+"/") {
+ return fmt.Errorf(
+ "extra_writable %q shadows the session's private /tmp mount; use binds to serve it through the files API too",
+ p,
+ )
+ }
+ }
+ }
+ }
+ return nil
}
// validateBindMountStack rejects bind destinations whose mount-stack
diff --git a/components/execd/pkg/runtime/isolated_session_overlays_test.go b/components/execd/pkg/runtime/isolated_session_overlays_test.go
index a904acab3..ffa66ac72 100644
--- a/components/execd/pkg/runtime/isolated_session_overlays_test.go
+++ b/components/execd/pkg/runtime/isolated_session_overlays_test.go
@@ -509,3 +509,67 @@ func TestNewMergedView_MultiOverlayRouting(t *testing.T) {
t.Fatalf("relative write did not resolve against the primary overlay: %v", err)
}
}
+
+// 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.
+func TestCreateIsolatedSession_ExtraWritableOnTmpRejected(t *testing.T) {
+ allowTmp := func(r *IsolatedRunner) {
+ r.allowedWritable = []string{"/tmp"}
+ }
+ // extra_writable validation requires an existing host path.
+ requireTmpCache := func(t *testing.T) {
+ t.Helper()
+ if err := os.MkdirAll("/tmp/extra-writable-test-cache", 0o755); err != nil {
+ t.Fatal(err)
+ }
+ t.Cleanup(func() { _ = os.RemoveAll("/tmp/extra-writable-test-cache") })
+ }
+
+ t.Run("hosted_strict_rejects_tmp_extra_writable", func(t *testing.T) {
+ requireTmpCache(t)
+ runner := newTestRunner(t)
+ allowTmp(runner)
+ _, err := runner.CreateIsolatedSession(&IsolatedSessionOptions{
+ Overlays: []IsolatedOverlayOptions{{Path: filepath.Join(t.TempDir(), "ws"), Mode: "rw"}},
+ ExtraWritable: []string{"/tmp/extra-writable-test-cache"},
+ })
+ if err == nil || !strings.Contains(err.Error(), "shadows the session's private /tmp") {
+ t.Fatalf("error = %v, want private /tmp shadow rejection", err)
+ }
+ })
+
+ t.Run("balanced_allows_tmp_extra_writable", func(t *testing.T) {
+ requireTmpCache(t)
+ runner := newTestRunner(t)
+ allowTmp(runner)
+ id, err := runner.CreateIsolatedSession(&IsolatedSessionOptions{
+ Profile: string(isolation.ProfileBalanced),
+ Overlays: []IsolatedOverlayOptions{{Path: filepath.Join(t.TempDir(), "ws"), Mode: "rw"}},
+ ExtraWritable: []string{"/tmp/extra-writable-test-cache"},
+ })
+ if err != nil {
+ t.Fatalf("balanced sessions share the sandbox /tmp and need no hosted dir: %v", err)
+ }
+ _ = runner.DeleteIsolatedSession(id)
+ })
+
+ t.Run("overlay_covering_tmp_allows_extra_writable", func(t *testing.T) {
+ requireTmpCache(t)
+ runner := newTestRunner(t)
+ allowTmp(runner)
+ id, err := runner.CreateIsolatedSession(&IsolatedSessionOptions{
+ Overlays: []IsolatedOverlayOptions{
+ {Path: filepath.Join(t.TempDir(), "ws"), Mode: "rw"},
+ {Path: "/tmp", Mode: "rw"},
+ },
+ ExtraWritable: []string{"/tmp/extra-writable-test-cache"},
+ })
+ if err != nil {
+ t.Fatalf("an overlay on /tmp replaces the hosted bind, so no divergence: %v", err)
+ }
+ _ = runner.DeleteIsolatedSession(id)
+ })
+}
diff --git a/docs/guides/isolation-sessions.md b/docs/guides/isolation-sessions.md
index b373cae62..c5519e7ba 100644
--- a/docs/guides/isolation-sessions.md
+++ b/docs/guides/isolation-sessions.md
@@ -326,7 +326,7 @@ The `profile` field currently controls only how `/tmp` is exposed inside the nam
| Profile | `/tmp` |
|---|---|
-| `strict` (default) | Session-private tmpfs (`--tmpfs /tmp`) |
+| `strict` (default) | Session-private, host-backed bind (`--bind <upper_root>/<session>/tmp /tmp`) |
| `balanced` | Shared with the sandbox (`--bind /tmp /tmp`) |
In the `strict` profile the private `/tmp` is backed by a host directory under the session's `upper_root` subtree, bind-mounted into the namespace, so `session.files` and `session.run` see the same `/tmp` content in both directions. The directory is created empty at session start, lives only as long as the session, and is removed with the rest of the session state on `DELETE` / idle collection. A `binds` entry or overlay sharing the `/tmp` destination still shadows it, exactly as inside the namespace. The `balanced` profile shares the sandbox's own `/tmp`, which stays outside the files API's mount view.
diff --git a/sdks/sandbox/javascript/src/api/egress.ts b/sdks/sandbox/javascript/src/api/egress.ts
index 58ce10896..36d5bb834 100644
--- a/sdks/sandbox/javascript/src/api/egress.ts
+++ b/sdks/sandbox/javascript/src/api/egress.ts
@@ -1,11 +1,11 @@
// Copyright 2026 The OpenSandbox Authors
-//
+//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
-//
+//
// http://www.apache.org/licenses/LICENSE-2.0
-//
+//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
diff --git a/sdks/sandbox/javascript/src/api/execd.ts b/sdks/sandbox/javascript/src/api/execd.ts
index 9a2d28fea..7e79df3dc 100644
--- a/sdks/sandbox/javascript/src/api/execd.ts
+++ b/sdks/sandbox/javascript/src/api/execd.ts
@@ -1649,9 +1649,12 @@ export interface components {
*/
message: string;
};
- /** @description Creates an isolated session with one or more overlay mounts. The legacy `workspace` field is kept as sugar for a single-element `overlays` list: at least one of `workspace` or `overlays` must be provided, and when both are present `workspace` is prepended to `overlays`. The session files API serves exactly the overlay and bind mounts: paths under each mount resolve as the namespace sees them, and absolute paths outside every overlay or bind are rejected instead of resolving against the workspace (unlike binds, extra_writable paths are not served by the files API unless an overlay covers them). */
+ /** @description Creates an isolated session with one or more overlay mounts. The legacy `workspace` field is kept as sugar for a single-element `overlays` list: at least one of `workspace` or `overlays` must be provided, and when both are present `workspace` is prepended to `overlays`. The session files API serves exactly the overlay and bind mounts: paths under each mount resolve as the namespace sees them, and absolute paths outside every overlay or bind are rejected instead of resolving against the workspace (unlike binds, extra_writable paths are not served by the files API unless an overlay covers them). The strict profile's private `/tmp` is a session-owned bind under the upper root and is part of that view; a caller bind or overlay on `/tmp` shadows it as inside the namespace. */
CreateIsolatedSessionRequest: {
- /** @enum {string} */
+ /**
+ * @description Isolation profile. `strict` (default) gives the session a private `/tmp` backed by a host directory that the session files API also serves; `balanced` shares the sandbox's own `/tmp`, which the files API does not serve.
+ * @enum {string}
+ */
profile?: "strict" | "balanced";
workspace?: components["schemas"]["IsolatedWorkspaceSpec"];
/** @description Independent overlay mounts inside one namespace. Each entry gets its own copy-on-write upper (or a direct/ro bind for rw/ro modes). bubblewrap applies mounts shallow-first, so a nested overlay (for example `/workspace` on top of a `/` root overlay) shadows its ancestors within its own subtree. Paths must be absolute, unique, and clean (no trailing slash, `.` or `..` segments); at most 16 mounts per session (including the legacy `workspace`). */
diff --git a/sdks/sandbox/javascript/src/api/lifecycle.ts b/sdks/sandbox/javascript/src/api/lifecycle.ts
index 560f945af..dfda68d27 100644
--- a/sdks/sandbox/javascript/src/api/lifecycle.ts
+++ b/sdks/sandbox/javascript/src/api/lifecycle.ts
@@ -1,11 +1,11 @@
// Copyright 2026 The OpenSandbox Authors
-//
+//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
-//
+//
// http://www.apache.org/licenses/LICENSE-2.0
-//
+//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -30,19 +30,21 @@ export interface paths {
};
/**
* Read sandbox network policy
- * @description For Fsb, reads persisted egress Action Binding intent in the tenant's
- * Sandbox CR, not live enforcement state. An absent binding defaults to
- * deny-first when an egress handler is configured; this is not proof of
- * enforcement on a pool without that handler. Other backends proxy the
- * sandbox-side egress service. Requires lifecycle API authentication.
+ * @description Fsb reads the egress-held policy record — the response reflects
+ * exactly what the egress enforces, not the create-time binding input.
+ * Other backends proxy the sandbox-side egress service. Requires
+ * lifecycle API authentication.
*/
get: operations["getSandboxNetworkPolicy"];
/**
* Replace the complete sandbox network policy
* @description Replaces defaultAction and all rules, rather than merging them. Fsb
- * commits the egress binding through FastPath, preserving unrelated bindings
- * with UID/generation conflict protection. Success does not imply handler
- * convergence. Other backends proxy the sandbox-side egress service.
+ * relays the replacement to the egress-held policy record through the
+ * FastPath handler relay — the ack means the egress applied it (and, with
+ * policy persistence, that it is durable). The create-time binding input
+ * is the bootstrap only; runtime changes never rewrite it, and a paused
+ * (sealed) sandbox rejects mutations until resume. Other backends proxy
+ * the sandbox-side egress service.
*/
put: operations["replaceSandboxNetworkPolicy"];
post?: never;
@@ -63,9 +65,10 @@ export interface paths {
* take priority over existing rules with the same target and replace
* them in place; within one patch payload, the first rule for a target
* wins; existing rules for other targets and the current defaultAction
- * are preserved. Fsb commits the merged binding through FastPath with
- * UID/generation conflict protection. Other backends proxy the
- * sandbox-side egress service.
+ * are preserved. Fsb composes the merge server-side (relay GET → merge
+ * → relay PUT carrying the read revision) — a concurrent writer wins
+ * and the stale merge is a 409. Other backends proxy the sandbox-side
+ * egress service.
*/
patch: operations["patchSandboxNetworkPolicy"];
trace?: never;
@@ -1716,6 +1719,11 @@ export interface components {
* @description Optional outbound network policy for the sandbox.
* Shape matches the sidecar `/policy` endpoint. If omitted or empty,
* the sidecar starts in allow-all mode until updated.
+ * For Fsb, an omitted policy still registers an egress binding,
+ * seeded with a no-op default-allow record (the sandbox behaves
+ * like a policy-less one until changed): runtime changes go
+ * through the networkpolicy endpoints (handler relay), which
+ * require that registration.
* Not supported together with `extensions.poolRef`; pooled pods are
* pre-created, so the server rejects this combination instead of
* silently ignoring the requested policy.
@@ -2484,6 +2492,7 @@ export interface operations {
401: components["responses"]["Unauthorized"];
403: components["responses"]["Forbidden"];
404: components["responses"]["NotFound"];
+ 409: components["responses"]["Conflict"];
500: components["responses"]["InternalServerError"];
/** @description Policy state is temporarily unavailable. */
503: {