Secure, Fast, and Extensible Sandbox runtime for AI agents.
fix(execd): harden Jupyter runtime token discovery and fast-fail on missing config
yutian.taoyt6e82649534fc
diff --git a/components/execd/pkg/runtime/context.go b/components/execd/pkg/runtime/context.goindex 3adc3ccef..3630c7881 100644--- a/components/execd/pkg/runtime/context.go+++ b/components/execd/pkg/runtime/context.go@@ -15,6 +15,7 @@package runtimeimport (+ "context""errors""fmt""net/http"@@ -34,6 +35,10 @@ import (// CreateContext provisions a kernel-backed session and returns its ID.// Bash language uses Jupyter kernel like other languages; for pipe-based bash sessions use CreateBashSession (session API).func (c *Controller) CreateContext(req *CreateContextRequest) (string, error) {+ if c.baseURL == "" || len(c.jupyterTokens()) == 0 {+ return "", errJupyterNotConfigured+ }+var (client *jupyter.Clientsession *jupytersession.Session@@ -41,6 +46,9 @@ func (c *Controller) CreateContext(req *CreateContextRequest) (string, error) {)err = retry.OnError(kernelWaitingBackoff, func(err error) bool {+ if errors.Is(err, errJupyterNotConfigured) {+ return false+ }log.Error("jupyter: create session failed, retrying: %v", err)return err != nil}, func() error {@@ -144,10 +152,13 @@ func (c *Controller) newIpynbPath(sessionID, cwd string) (string, error) {}// createDefaultLanguageJupyterContext prewarms a session for stateless execution.-func (c *Controller) createDefaultLanguageJupyterContext(language Language) error {+func (c *Controller) createDefaultLanguageJupyterContext(ctx context.Context, language Language) error {if c.getDefaultLanguageSession(language) != "" {return nil}+ if c.baseURL == "" || len(c.jupyterTokens()) == 0 {+ return errJupyterNotConfigured+ }var (client *jupyter.Client@@ -155,9 +166,18 @@ func (c *Controller) createDefaultLanguageJupyterContext(language Language) erroerr error)err = retry.OnError(kernelWaitingBackoff, func(err error) bool {+ if ctx != nil && ctx.Err() != nil {+ return false+ }+ if errors.Is(err, errJupyterNotConfigured) {+ return false+ }log.Error("jupyter: create default context failed, retrying: %v", err)return err != nil}, func() error {+ if ctx != nil && ctx.Err() != nil {+ return ctx.Err()+ }client, session, err = c.createJupyterContext(CreateContextRequest{Language: language,Cwd: "",@@ -179,13 +199,24 @@ func (c *Controller) createDefaultLanguageJupyterContext(language Language) erro// createJupyterContext performs the actual context creation workflow.func (c *Controller) createJupyterContext(request CreateContextRequest) (*jupyter.Client, *jupytersession.Session, error) {- token := c.jupyterToken()- if c.baseURL == "" || token == "" {+ tokens := c.jupyterTokens()+ if c.baseURL == "" || len(tokens) == 0 {return nil, nil, errJupyterNotConfigured}- client := c.jupyterClientWithToken(token)- kernel, err := c.searchKernel(client, request.Language)+ var (+ client *jupyter.Client+ kernel string+ err error+ )+ for _, token := range tokens {+ candidateClient := c.jupyterClientWithToken(token)+ kernel, err = c.searchKernel(candidateClient, request.Language)+ if err == nil {+ client = candidateClient+ break+ }+ }if err != nil {return nil, nil, err}diff --git a/components/execd/pkg/runtime/context_test.go b/components/execd/pkg/runtime/context_test.goindex 00f603c80..e4809f89c 100644--- a/components/execd/pkg/runtime/context_test.go+++ b/components/execd/pkg/runtime/context_test.go@@ -255,9 +255,117 @@ func TestJupyterTokenDiscovery_FiltersAndPrecedence(t *testing.T) {require.NoError(t, os.Chtimes(newFile, newTime, newTime))require.Equal(t, newToken, c.jupyterToken())+ require.Equal(t, []string{newToken, oldToken}, c.jupyterTokens())- // 3. Explicit token always takes precedence over runtime discovery.+ // 3. Symlinked runtime file, permissive runtime dir, and mismatched owner UID are rejected.+ targetFile := filepath.Join(runtimeRoot, "external-target.json")+ targetData, err := json.Marshal(jupyterRuntimeServerInfo{Port: port, Token: "symlink-token"})+ require.NoError(t, err)+ require.NoError(t, os.WriteFile(targetFile, targetData, 0o600))+ symlinkDir := filepath.Join(runtimeRoot, "opensandbox-jupyter.symlink")+ require.NoError(t, os.MkdirAll(symlinkDir, 0o700))+ require.NoError(t, os.Symlink(targetFile, filepath.Join(symlinkDir, "jpserver-4.json")))++ worldDirFile := writeJupyterServerFile(t, runtimeRoot, "opensandbox-jupyter.worlddir", "jpserver-5.json", jupyterRuntimeServerInfo{+ Port: port,+ Token: "world-dir-token",+ })+ require.NoError(t, os.Chmod(filepath.Dir(worldDirFile), 0o755))++ require.Equal(t, []string{newToken, oldToken}, c.jupyterTokens())++ otherUID := os.Geteuid() + 1+ c.jupyterRuntimeUID = &otherUID+ if _, hasUID := runtimeFileOwnerUID(mustStat(t, newFile)); hasUID {+ require.Empty(t, c.jupyterTokens())+ }+ c.jupyterRuntimeUID = nil++ // 4. Explicit token always takes precedence over runtime discovery.configured := NewController(baseURL, initToken)configured.jupyterRuntimeRoot = runtimeRootrequire.Equal(t, initToken, configured.jupyterToken())}++func mustStat(t *testing.T, path string) os.FileInfo {+ t.Helper()+ info, err := os.Stat(path)+ require.NoError(t, err)+ return info+}++func TestCreateContextAndRunJupyter_FastFailWhenTokenMissing(t *testing.T) {+ c := NewController("http://127.0.0.1:44771", "")+ c.jupyterRuntimeRoot = t.TempDir()++ start := time.Now()+ _, err := c.CreateContext(&CreateContextRequest{+ Language: Python,+ Cwd: t.TempDir(),+ })+ require.ErrorIs(t, err, errJupyterNotConfigured)+ require.Less(t, time.Since(start), 200*time.Millisecond)++ start = time.Now()+ err = c.Execute(&ExecuteCodeRequest{+ Language: Python,+ Code: "print(1)",+ })+ require.ErrorIs(t, err, errJupyterNotConfigured)+ require.Less(t, time.Since(start), 200*time.Millisecond)+}++func TestCreateContext_SkipsNewerUnauthenticatedDecoyRuntimeFile(t *testing.T) {+ const (+ validToken = "valid-jupyter-runtime-token"+ decoyToken = "newer-decoy-runtime-token"+ )++ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ if r.Header.Get("Authorization") != "Token "+validToken {+ w.WriteHeader(http.StatusForbidden)+ return+ }+ w.Header().Set("Content-Type", "application/json")+ switch {+ case r.Method == http.MethodGet && strings.HasSuffix(r.URL.Path, "/api/kernelspecs"):+ _, _ = w.Write([]byte(`{"default":"python","kernelspecs":{"python":{"name":"python","spec":{"language":"python","display_name":"Python"}}}}`))+ case r.Method == http.MethodPost && strings.HasSuffix(r.URL.Path, "/api/sessions"):+ w.WriteHeader(http.StatusCreated)+ _, _ = w.Write([]byte(`{"id":"sess-after-decoy","kernel":{"id":"kernel-1","name":"python"}}`))+ case r.Method == http.MethodGet && strings.HasSuffix(r.URL.Path, "/api/kernels"):+ _, _ = w.Write([]byte(`[{"id":"kernel-1","name":"python"}]`))+ default:+ require.Failf(t, "unexpected request", "%s %s", r.Method, r.URL.Path)+ }+ }))+ defer server.Close()++ runtimeRoot := t.TempDir()+ port := jupyterPortFromBaseURL(server.URL)++ realFile := writeJupyterServerFile(t, runtimeRoot, "opensandbox-jupyter.real", "jpserver-1.json", jupyterRuntimeServerInfo{+ Port: port,+ Token: validToken,+ })+ oldTime := time.Now().Add(-10 * time.Second)+ require.NoError(t, os.Chtimes(realFile, oldTime, oldTime))++ decoyFile := writeJupyterServerFile(t, runtimeRoot, "opensandbox-jupyter.decoy", "jpserver-2.json", jupyterRuntimeServerInfo{+ Port: port,+ Token: decoyToken,+ })+ newTime := time.Now().Add(-1 * time.Second)+ require.NoError(t, os.Chtimes(decoyFile, newTime, newTime))++ c := NewController(server.URL, "")+ c.jupyterRuntimeRoot = runtimeRoot++ sessionID, err := c.CreateContext(&CreateContextRequest{+ Language: Python,+ Cwd: t.TempDir(),+ })+ require.NoError(t, err)+ require.Equal(t, "sess-after-decoy", sessionID)+}+diff --git a/components/execd/pkg/runtime/ctrl.go b/components/execd/pkg/runtime/ctrl.goindex cf0e8f465..bcc472dfa 100644--- a/components/execd/pkg/runtime/ctrl.go+++ b/components/execd/pkg/runtime/ctrl.go@@ -31,6 +31,7 @@ var kernelWaitingBackoff = wait.Backoff{Duration: 500 * time.Millisecond,Factor: 1.5,Jitter: 0.1,+ Cap: 5 * time.Second,}// Controller manages code execution across runtimes.@@ -38,6 +39,7 @@ type Controller struct {baseURL stringtoken stringjupyterRuntimeRoot string+ jupyterRuntimeUID *intmu sync.RWMutexjupyterClientMap sync.Map // map[sessionID]*jupyterKerneldefaultLanguageSessions sync.Map // map[Language]stringdiff --git a/components/execd/pkg/runtime/jupyter.go b/components/execd/pkg/runtime/jupyter.goindex bd7f7c5bc..58db682a6 100644--- a/components/execd/pkg/runtime/jupyter.go+++ b/components/execd/pkg/runtime/jupyter.go@@ -18,9 +18,11 @@ import ("context""encoding/json""errors"+ "io""net/url""os""path/filepath"+ "sort""strconv""strings""time"@@ -30,6 +32,8 @@ import ("github.com/alibaba/opensandbox/execd/pkg/log")+const maxJupyterRuntimeFileSize = 64 * 1024+var errJupyterNotConfigured = errors.New("language runtime server not configured, please check your image runtime")type jupyterRuntimeServerInfo struct {@@ -44,7 +48,7 @@ func (c *Controller) runJupyter(ctx context.Context, request *ExecuteCodeRequest}if request.Context == "" {if c.getDefaultLanguageSession(request.Language) == "" {- if err := c.createDefaultLanguageJupyterContext(request.Language); err != nil {+ if err := c.createDefaultLanguageJupyterContext(ctx, request.Language); err != nil {return err}}@@ -184,19 +188,40 @@ func (c *Controller) searchKernel(client *jupyter.Client, language Language) (st}func (c *Controller) jupyterToken() string {+ tokens := c.jupyterTokens()+ if len(tokens) == 0 {+ return ""+ }+ return tokens[0]+}++func (c *Controller) jupyterTokens() []string {if c.token != "" {- return c.token+ return []string{c.token}}- return c.discoverJupyterToken()+ return c.discoverJupyterTokens()}-// discoverJupyterToken reads the token written by a standalone code-interpreter-// entrypoint in /tmp/opensandbox-jupyter.*/jpserver-*.json when execd is-// launched without bootstrap.sh (for example via fast-sandbox infraComponents).-func (c *Controller) discoverJupyterToken() string {+func (c *Controller) expectedJupyterRuntimeUID() int {+ if c.jupyterRuntimeUID != nil {+ return *c.jupyterRuntimeUID+ }+ return os.Geteuid()+}++type discoveredJupyterToken struct {+ token string+ modTime time.Time+}++// discoverJupyterTokens reads candidate tokens written by a standalone+// code-interpreter entrypoint in /tmp/opensandbox-jupyter.*/jpserver-*.json+// when execd is launched without bootstrap.sh (for example via fast-sandbox+// infraComponents), ordered from newest to oldest.+func (c *Controller) discoverJupyterTokens() []string {targetPort := jupyterPortFromBaseURL(c.baseURL)if targetPort <= 0 {- return ""+ return nil}root := c.jupyterRuntimeRootif root == "" {@@ -204,36 +229,67 @@ func (c *Controller) discoverJupyterToken() string {}matches, err := filepath.Glob(filepath.Join(root, "opensandbox-jupyter.*", "jpserver-*.json"))if err != nil {- return ""+ return nil}- var (- bestToken string- bestModTime time.Time- )+ expectedUID := c.expectedJupyterRuntimeUID()+ candidates := make([]discoveredJupyterToken, 0, len(matches))for _, match := range matches {- token, modTime, ok := readJupyterRuntimeToken(match, targetPort)+ token, modTime, ok := readJupyterRuntimeToken(match, targetPort, expectedUID)if !ok {continue}- if bestToken == "" || modTime.After(bestModTime) {- bestToken = token- bestModTime = modTime+ candidates = append(candidates, discoveredJupyterToken{+ token: token,+ modTime: modTime,+ })+ }+ sort.SliceStable(candidates, func(i, j int) bool {+ return candidates[i].modTime.After(candidates[j].modTime)+ })++ tokens := make([]string, 0, len(candidates))+ seen := make(map[string]struct{}, len(candidates))+ for _, candidate := range candidates {+ if _, exists := seen[candidate.token]; exists {+ continue}+ seen[candidate.token] = struct{}{}+ tokens = append(tokens, candidate.token)}- return bestToken+ return tokens}-func readJupyterRuntimeToken(filePath string, targetPort int) (string, time.Time, bool) {- fileInfo, err := os.Lstat(filePath)- if err != nil || !fileInfo.Mode().IsRegular() {+func readJupyterRuntimeToken(filePath string, targetPort int, expectedUID int) (string, time.Time, bool) {+ dirInfo, err := os.Lstat(filepath.Dir(filePath))+ if err != nil || !dirInfo.Mode().IsDir() || dirInfo.Mode().Perm()&0o077 != 0 {+ return "", time.Time{}, false+ }+ if uid, ok := runtimeFileOwnerUID(dirInfo); ok && uid != expectedUID {return "", time.Time{}, false}- data, err := os.ReadFile(filePath)+ file, err := openRuntimeFileNoFollow(filePath)if err != nil {return "", time.Time{}, false}+ defer file.Close()++ fileInfo, err := file.Stat()+ if err != nil || !fileInfo.Mode().IsRegular() || fileInfo.Mode().Perm()&0o022 != 0 {+ return "", time.Time{}, false+ }+ if fileInfo.Size() <= 0 || fileInfo.Size() > maxJupyterRuntimeFileSize {+ return "", time.Time{}, false+ }+ if uid, ok := runtimeFileOwnerUID(fileInfo); ok && uid != expectedUID {+ return "", time.Time{}, false+ }++ data, err := io.ReadAll(io.LimitReader(file, maxJupyterRuntimeFileSize+1))+ if err != nil || int64(len(data)) > maxJupyterRuntimeFileSize {+ return "", time.Time{}, false+ }var info jupyterRuntimeServerInfoif err := json.Unmarshal(data, &info); err != nil {diff --git a/components/execd/pkg/runtime/jupyter_runtime_other.go b/components/execd/pkg/runtime/jupyter_runtime_other.gonew file mode 100644index 000000000..1f4ecdb26--- /dev/null+++ b/components/execd/pkg/runtime/jupyter_runtime_other.go@@ -0,0 +1,37 @@+//go:build !unix++// 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 runtime++import (+ "errors"+ "os"+)++func openRuntimeFileNoFollow(filePath string) (*os.File, error) {+ info, err := os.Lstat(filePath)+ if err != nil {+ return nil, err+ }+ if !info.Mode().IsRegular() {+ return nil, errors.New("not a regular file")+ }+ return os.Open(filePath)+}++func runtimeFileOwnerUID(os.FileInfo) (int, bool) {+ return 0, false+}diff --git a/components/execd/pkg/runtime/jupyter_runtime_unix.go b/components/execd/pkg/runtime/jupyter_runtime_unix.gonew file mode 100644index 000000000..57dadb569--- /dev/null+++ b/components/execd/pkg/runtime/jupyter_runtime_unix.go@@ -0,0 +1,34 @@+//go:build unix++// 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 runtime++import (+ "os"+ "syscall"+)++func openRuntimeFileNoFollow(filePath string) (*os.File, error) {+ return os.OpenFile(filePath, os.O_RDONLY|syscall.O_NOFOLLOW|syscall.O_NONBLOCK, 0)+}++func runtimeFileOwnerUID(info os.FileInfo) (int, bool) {+ stat, ok := info.Sys().(*syscall.Stat_t)+ if !ok {+ return 0, false+ }+ return int(stat.Uid), true+}diff --git a/docs/reference/code-interpreter-image-migration.md b/docs/reference/code-interpreter-image-migration.mdindex 7ddc9a3bb..44f562602 100644--- a/docs/reference/code-interpreter-image-migration.md+++ b/docs/reference/code-interpreter-image-migration.md@@ -48,7 +48,7 @@ This migration is purely structural for monorepo maintenance. Container image co### Jupyter Authentication-When `JUPYTER_TOKEN` is not explicitly configured, the `code-interpreter` entrypoint generates a per-sandbox random token on startup and writes its server metadata to an owner-only `/tmp/opensandbox-jupyter.*/jpserver-*.json` runtime file, which `execd` discovers automatically. An explicit nonempty `JUPYTER_TOKEN` remains supported and takes precedence. When pairing a new image with an older `execd` release that does not discover runtime tokens, supply an explicit `JUPYTER_TOKEN` at sandbox creation.+When `JUPYTER_TOKEN` is not explicitly configured, the `code-interpreter` entrypoint generates a per-sandbox random token on startup and writes its server metadata to an owner-only (`0700`) `/tmp/opensandbox-jupyter.*/jpserver-*.json` runtime file, which `execd` discovers automatically after verifying directory permissions, owner UID, and kernel endpoint authentication. An explicit nonempty `JUPYTER_TOKEN` remains supported and takes precedence. When pairing a new image with an older `execd` release that does not discover runtime tokens, supply an explicit `JUPYTER_TOKEN` at sandbox creation.### Signature and Provenance Verification