Skip to content

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

14.0 KB
Raw Blame
// Copyright 2025 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.

//go:build !windows
// +build !windows

package runtime

import (
	"context"
	"errors"
	"fmt"
	"os"
	"os/exec"
	"os/signal"
	"os/user"
	"strconv"
	"sync"
	"syscall"
	"time"

	"github.com/alibaba/opensandbox/internal/safego"

	"github.com/alibaba/opensandbox/execd/pkg/jupyter/execute"
	"github.com/alibaba/opensandbox/execd/pkg/log"
)

const bashShell = "bash"

var forwardSignals = []os.Signal{
	syscall.SIGINT,
	syscall.SIGTERM,
	syscall.SIGHUP,
	syscall.SIGQUIT,
	syscall.SIGUSR1,
	syscall.SIGUSR2,
	syscall.SIGWINCH,
}

// subscribeCommandSignals sets up the classic-mode subscription that
// forwards application signals to a running /command process group, and
// returns the signal channel plus a stop function. In init mode
// (OSEP-0018) nothing is subscribed and the channel is nil: application
// signals are owned by forwardInitSignals, which forwards them to the
// entrypoint group (and SIGTERM triggers the shutdown sequence). An
// additional subscription here would split each in-namespace signal
// between two channels and leak HUP/USR*/WINCH into whatever /command
// happens to be running.
func subscribeCommandSignals() (chan os.Signal, func()) {
	if initModeActive() {
		return nil, func() {}
	}
	signals := make(chan os.Signal, len(forwardSignals)+1)
	signal.Notify(signals, forwardSignals...)
	return signals, func() {
		signal.Stop(signals)
		close(signals)
	}
}

// getShell returns "bash" if available, otherwise "sh". The result is cached
// for the process lifetime; tests that mutate PATH must call
// resetShellCacheForTest.
var (
	shellCacheOnce sync.Once
	shellCacheVal  string
)

func getShell() string {
	shellCacheOnce.Do(func() {
		if _, err := exec.LookPath(bashShell); err == nil {
			shellCacheVal = bashShell
		} else {
			shellCacheVal = "sh"
		}
	})
	return shellCacheVal
}

// shellCommand returns (shell, argv) for launching the preferred shell,
// prepending --noprofile --norc when Bash is selected. Extra positional
// arguments (script path, or "-c" + code) are appended after.
func shellCommand(extra ...string) (string, []string) {
	shell := getShell()
	args := make([]string, 0, 2+len(extra))
	if shell == bashShell {
		args = append(args, "--noprofile", "--norc")
	}
	args = append(args, extra...)
	return shell, args
}

func buildCredential(uid, gid *uint32) (*syscall.Credential, error) {
	if uid == nil && gid == nil {
		return nil, nil //nolint:nilnil
	}

	// An explicit uid/gid matching the identity execd already runs as needs
	// no credential switch: return nil so the launch stays on the plain exec
	// path, which is also what the no-uid request already does (#1802).
	if sameIdentityRequest(uid, gid) {
		return nil, nil //nolint:nilnil
	}

	cred := &syscall.Credential{}
	if uid != nil {
		cred.Uid = *uid
		u, err := user.LookupId(strconv.FormatUint(uint64(*uid), 10))
		if err == nil {
			if gid == nil {
				primaryGid, err := strconv.ParseUint(u.Gid, 10, 32)
				if err == nil {
					cred.Gid = uint32(primaryGid)
				}
			}

			gids, err := u.GroupIds()
			if err == nil {
				for _, g := range gids {
					id, err := strconv.ParseUint(g, 10, 32)
					if err == nil {
						cred.Groups = append(cred.Groups, uint32(id))
					}
				}
			}
		}
	}

	if gid != nil {
		cred.Gid = *gid
	}

	return cred, nil
}

// sameIdentityRequest reports whether the requested uid/gid matches the
// identity execd already runs with, making the credential machinery a
// provable no-op. A non-nil Credential always makes the child call setgroups
// (even when every id matches), and setgroups requires CAP_SETGID no matter
// what values are requested — so same-identity credentials fail with
// "fork/exec ...: operation not permitted" inside sandboxes that drop
// capabilities (#1802). A uid-only request skips the switch only when the
// user entry's primary GID and supplemental groups match the daemon's own.
func sameIdentityRequest(uid, gid *uint32) bool {
	currentUID := uint32(os.Getuid())
	currentGID := uint32(os.Getgid())
	if (uid == nil || *uid == currentUID) && (gid == nil || *gid == currentGID) {
		if gid != nil || uid == nil {
			return true
		}
		return sameProcessGroups(*uid)
	}
	return false
}

// credentialStartHint annotates command launch failures that happen while
// switching identity. With capabilities dropped the kernel rejects the
// child's setgroups/setgid/setuid calls, and the raw error surfaces as a
// bare "fork/exec ...: operation not permitted" that gives the caller no
// way to discover the missing grant (#1802).
func credentialStartHint(err error, cred *syscall.Credential) error {
	if cred == nil || !errors.Is(err, os.ErrPermission) {
		return err
	}
	return fmt.Errorf(
		"%w (switching to uid=%d gid=%d requires CAP_SETUID/CAP_SETGID, which this sandbox may not have — check the server's docker.drop_capabilities configuration; dropping these capabilities makes every identity switch fail)",
		err, cred.Uid, cred.Gid,
	)
}

// sameProcessGroups reports whether the given uid's user entry resolves to
// the primary GID and supplemental groups the daemon already runs with, i.e.
// whether building a credential for that uid would be a no-op group-wise.
func sameProcessGroups(uid uint32) bool {
	u, err := user.LookupId(strconv.FormatUint(uint64(uid), 10))
	if err != nil {
		return false
	}
	primaryGid, err := strconv.ParseUint(u.Gid, 10, 32)
	if err != nil || uint32(primaryGid) != uint32(os.Getgid()) {
		return false
	}
	entryGroups, err := u.GroupIds()
	if err != nil {
		return false
	}
	processGroups, err := syscall.Getgroups()
	if err != nil || len(entryGroups) != len(processGroups) {
		return false
	}
	seen := make(map[uint32]bool, len(processGroups))
	for _, g := range processGroups {
		seen[uint32(g)] = true
	}
	for _, g := range entryGroups {
		id, err := strconv.ParseUint(g, 10, 32)
		if err != nil || !seen[uint32(id)] {
			return false
		}
	}
	return true
}

// runCommand executes shell commands and streams their output.
func (c *Controller) runCommand(ctx context.Context, request *ExecuteCodeRequest) error {
	session := c.newContextID()

	signals, stopSignals := subscribeCommandSignals()
	defer stopSignals()

	stdout, stderr, err := c.stdLogDescriptor(session)
	if err != nil {
		return fmt.Errorf("failed to get stdlog descriptor: %w", err)
	}
	stdoutPath := c.stdoutFileName(session)
	stderrPath := c.stderrFileName(session)
	defer func() {
		_ = stdout.Close()
		_ = stderr.Close()
		removeCommandOutputFiles(stdoutPath, stderrPath)
	}()

	startAt := time.Now()
	log.Info("command: received %v", log.SanitizeCommand(request.commandContent()))
	cmd, err := prepareCommand(ctx, request)
	if err != nil {
		return fmt.Errorf("resolve request cwd %s: %w", request.Cwd, err)
	}

	cred, err := buildCredential(request.Uid, request.Gid)
	if err != nil {
		return fmt.Errorf("failed to build credential: %w", err)
	}
	cmd.SysProcAttr = &syscall.SysProcAttr{
		Setpgid:    true,
		Credential: cred,
	}

	cmd.Stdout = stdout
	cmd.Stderr = stderr

	done := make(chan struct{}, 1)
	var wg sync.WaitGroup
	wg.Add(2)
	safego.Go(func() {
		defer wg.Done()
		c.tailStdPipe(stdoutPath, request.Hooks.OnExecuteStdout, done)
	})
	safego.Go(func() {
		defer wg.Done()
		c.tailStdPipe(stderrPath, request.Hooks.OnExecuteStderr, done)
	})

	mp, err := launchManaged(cmd)
	if err != nil {
		close(done)
		wg.Wait()
		startErr := credentialStartHint(err, cred)
		request.Hooks.OnExecuteInit(session)
		request.Hooks.OnExecuteError(&execute.ErrorOutput{
			EName:     "CommandExecError",
			EValue:    startErr.Error(),
			Traceback: []string{startErr.Error()},
		})
		log.Error("command: start failed: %v", startErr)
		return nil
	}

	kernel := &commandKernel{
		pid:          cmd.Process.Pid,
		stdoutPath:   stdoutPath,
		stderrPath:   stderrPath,
		startedAt:    startAt,
		running:      true,
		content:      request.commandContent(),
		isBackground: false,
	}
	c.storeCommandKernel(session, kernel)
	request.Hooks.OnExecuteInit(session)

	safego.Go(func() {
		for {
			select {
			case <-done:
				// cmd.Wait() has returned (or start failed). The pid is
				// about to be — or already has been — reaped, so we
				// must not signal it. Execute()'s defer cancel() fires
				// after every foreground command, including successful
				// ones, so without this gate the SIGKILL below would
				// run on a recycled pid/pgid and could kill an
				// unrelated process group.
				return
			case <-ctx.Done():
				// Re-check `done` to avoid a race with cmd.Wait()
				// returning concurrently. If cmd.Wait() has just
				// finished, the leader pid may be reaped and recycled
				// at any moment; signaling -pid would then target a
				// foreign process group.
				select {
				case <-done:
					return
				default:
				}
				// Genuine cancellation (timeout, client disconnect,
				// Interrupt). Kill the whole process group so children
				// don't outlive the cancelled context.
				if cmd.Process != nil {
					_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
				}
				return
			case sig := <-signals:
				if sig == nil {
					continue
				}
				// DO NOT forward syscall.SIGURG to children processes.
				if sig != syscall.SIGCHLD && sig != syscall.SIGURG {
					_ = syscall.Kill(-cmd.Process.Pid, sig.(syscall.Signal))
				}
			}
		}
	})

	err = mp.Wait()
	close(done)
	wg.Wait()
	if err != nil {
		var eName, eValue string
		var eCode int
		var exitCodePtr *int
		var traceback []string

		var exitCodeErr exitCoder
		if errors.As(err, &exitCodeErr) {
			exitCode := exitCodeErr.ExitCode()
			eName = "CommandExecError"
			eValue = strconv.Itoa(exitCode)
			eCode = exitCode
			exitCodePtr = &exitCode
		} else {
			eName = "CommandExecError"
			eValue = err.Error()
			eCode = 1
		}
		traceback = []string{err.Error()}

		request.Hooks.OnExecuteError(&execute.ErrorOutput{
			EName:     eName,
			EValue:    eValue,
			Traceback: traceback,
			ExitCode:  exitCodePtr,
		})

		log.Error("command: run failed: %v", err)
		c.markCommandFinished(session, eCode, err.Error())
		return nil
	}

	c.markCommandFinished(session, 0, "")
	request.Hooks.OnExecuteComplete(time.Since(startAt))
	return nil
}

// runBackgroundCommand executes shell commands in detached mode.
func (c *Controller) runBackgroundCommand(ctx context.Context, cancel context.CancelFunc, request *ExecuteCodeRequest) error {
	session := c.newContextID()
	request.Hooks.OnExecuteInit(session)

	pipe, err := c.combinedOutputDescriptor(session)
	if err != nil {
		cancel()
		return fmt.Errorf("failed to get combined output descriptor: %w", err)
	}
	stdoutPath := c.combinedOutputFileName(session)
	stderrPath := c.combinedOutputFileName(session)

	// Classic-mode signal subscription (no-op in init mode; the channel is
	// never consumed, keeping today's behavior of not dying on SIGHUP etc.).
	_, stopSignals := subscribeCommandSignals()
	defer stopSignals()

	startAt := time.Now()
	log.Info("command: received %v", log.SanitizeCommand(request.commandContent()))
	cmd, err := prepareCommand(ctx, request)
	if err != nil {
		cancel()
		_ = pipe.Close()
		return fmt.Errorf("resolve cwd: %w", err)
	}

	cred, err := buildCredential(request.Uid, request.Gid)
	if err != nil {
		cancel()
		_ = pipe.Close()
		return fmt.Errorf("build credential: %w", err)
	}
	cmd.SysProcAttr = &syscall.SysProcAttr{
		Setpgid:    true,
		Credential: cred,
	}

	cmd.Stdout = pipe
	cmd.Stderr = pipe

	// use DevNull as stdin so interactive programs exit immediately.
	devNull, err := os.Open(os.DevNull)
	if err == nil {
		cmd.Stdin = devNull
		defer devNull.Close()
	}

	mp, err := launchManaged(cmd)
	kernel := &commandKernel{
		pid:          -1,
		stdoutPath:   stdoutPath,
		stderrPath:   stderrPath,
		startedAt:    startAt,
		running:      true,
		content:      request.commandContent(),
		isBackground: true,
	}
	if err != nil {
		cancel()
		_ = pipe.Close()
		startErr := credentialStartHint(err, cred)
		log.Error("command: start failed: %v", startErr)
		kernel.running = false
		c.storeCommandKernel(session, kernel)
		c.markCommandFinished(session, 255, startErr.Error())
		return fmt.Errorf("failed to start commands: %w", startErr)
	}

	// Register the kernel synchronously so that GetCommandStatus callers
	// can find the session immediately after Execute returns. Previously
	// this happened inside the goroutine, creating a race where the HTTP
	// handler could return before the kernel was stored.
	kernel.pid = cmd.Process.Pid
	c.storeCommandKernel(session, kernel)

	done := make(chan struct{})
	safego.Go(func() {
		defer pipe.Close()

		err = mp.Wait()
		close(done)
		cancel()
		if err != nil {
			log.Error("command: run failed: %v", err)
			exitCode := 1
			var exitCodeErr exitCoder
			if errors.As(err, &exitCodeErr) {
				exitCode = exitCodeErr.ExitCode()
			}
			c.markCommandFinished(session, exitCode, err.Error())
			return
		}
		c.markCommandFinished(session, 0, "")
	})

	// ensure we kill the whole process group if the context is cancelled (e.g., timeout).
	safego.Go(func() {
		select {
		case <-done:
			// The command exited on its own (the cancel() above also fires
			// ctx). Leave the group alone, as the foreground path does: its
			// children keep running, and an empty group's pgid may be reused.
			return
		case <-ctx.Done():
			// Re-check done: mp.Wait() may have returned concurrently.
			select {
			case <-done:
				return
			default:
			}
			if cmd.Process != nil {
				_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL) // best-effort
			}
		}
	})

	request.Hooks.OnExecuteComplete(time.Since(startAt))
	return nil
}

func newShellCommand(ctx context.Context, code string) *exec.Cmd {
	return exec.CommandContext(ctx, getShell(), "-c", code)
}