Skip to content

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.go
index 3adc3ccef..3630c7881 100644
--- a/components/execd/pkg/runtime/context.go
+++ b/components/execd/pkg/runtime/context.go
@@ -15,6 +15,7 @@
package runtime
import (
+ "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.Client
session *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) erro
err 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.go
index 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 = runtimeRoot
require.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.go
index 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 string
token string
jupyterRuntimeRoot string
+ jupyterRuntimeUID *int
mu sync.RWMutex
jupyterClientMap sync.Map // map[sessionID]*jupyterKernel
defaultLanguageSessions sync.Map // map[Language]string
diff --git a/components/execd/pkg/runtime/jupyter.go b/components/execd/pkg/runtime/jupyter.go
index 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.jupyterRuntimeRoot
if 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 jupyterRuntimeServerInfo
if 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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.md
index 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