Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,11 @@ box.SetMaxOutputEntries(100) // cap the number of top-level result entrie

A run that exceeds the step budget fails with a `starlet.MaxStepsExceededError`; one that produces too many result entries is withheld with an `OutputLimitExceededError`. Both are reachable via `errors.As`, and both are enforced on **every** run path (`Run`, `RunFile`, `RunTimeout`, `RunInspect*`, and the `RunnerConfig.Execute()` builder).

For an opt-in single-request child process, see [worker](worker/README.md).
It supplies a parent-enforced deadline, a combined stdout/stderr capture limit,
and direct-child termination/reaping. Existing execution APIs remain in-process.
The worker is not a full OS or multi-tenant sandbox.

## 🔎 Inspection without Execution

Learn what a script *would* see, and catch problems, without running it:
Expand Down
5 changes: 4 additions & 1 deletion SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,10 @@ Documentation states this boundary; it does not remove the vulnerable code.
For attacker-controlled source, the host needs a separately reviewed deployment
with process isolation and external CPU, memory, time and output limits, or an
explicit interpreter upgrade/backport with compatibility testing. Those are
host changes, not protections supplied by this package. A newer Go compiler
host deployment requirements. The opt-in [worker](worker/README.md) package
supplies direct-child termination/reaping and a combined stdout/stderr capture
limit, but does not supply CPU/RSS quotas, descendant containment or full OS
filesystem/network isolation. Existing execution APIs stay in-process. A newer Go compiler
alone does not patch the old interpreter. The library is not an in-process
security boundary for untrusted or multi-tenant script execution.

Expand Down
14 changes: 14 additions & 0 deletions cmd/starbox-worker/main.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
package main

import (
"io"
"os"

"github.com/1set/starbox/worker"
)

func run(args []string, in io.Reader, out, diagnostics io.Writer) int {
return worker.Main(args, in, out, diagnostics)
}

func main() { os.Exit(run(os.Args[1:], os.Stdin, os.Stdout, os.Stderr)) }
15 changes: 15 additions & 0 deletions cmd/starbox-worker/main_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
package main

import (
"bytes"
"strings"
"testing"
)

func TestRunActualProtocolIO(t *testing.T) {
var out, diagnostics bytes.Buffer
status := run([]string{"--protocol=1", "--max-input=4096"}, strings.NewReader("{\"protocol\":1,\"source\":\"output(42)\"}"), &out, &diagnostics)
if status != 0 || !strings.Contains(out.String(), "\"result\":42") {
t.Fatalf("status=%d out=%s diagnostics=%s", status, &out, &diagnostics)
}
}
14 changes: 14 additions & 0 deletions runner_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,20 @@ func TestRunnerConfig_Empty(t *testing.T) {
}
}

func TestRunnerConfigRejectsUnknownModuleSet(t *testing.T) {
box := starbox.New("invalid-modules")
box.SetModuleSet(starbox.ModuleSetName("unknown"))
if _, err := box.CreateRunConfig().Script("x=1").Execute(); err == nil || !strings.Contains(err.Error(), "unknown module set") {
t.Fatalf("invalid module set accepted: %v", err)
}
// A rejected first execution must leave the box usable after host correction.
box.SetModuleSet(starbox.EmptyModuleSet)
out, err := box.CreateRunConfig().Script("x=1").Execute()
if err != nil || out["x"] != int64(1) {
t.Fatalf("execution after corrected configuration: out=%v err=%v", out, err)
}
}

func TestRunnerConfig_Full(t *testing.T) {
box := starbox.New("aloha")
box.SetModuleSet(starbox.SafeModuleSet)
Expand Down
56 changes: 56 additions & 0 deletions worker/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# Single-request worker

This opt-in package launches a trusted worker executable for each request.
Build the command from the same reviewed checkout:

go build -o /absolute/trusted/path/starbox-worker ./cmd/starbox-worker

Use positive budgets and an explicit executable path:

runner, err := worker.New(worker.Config{
Executable: "/absolute/trusted/path/starbox-worker",
Timeout: 2 * time.Second,
MaxRequestBytes: 1 << 20,
MaxOutputBytes: 64 << 10,
})
// Check err before calling Run.
result, err := runner.Run(context.Background(), worker.Request{
Source: "print(\"hello\"); output({\"ok\": True})",
})

The request limit counts the encoded protocol message, including source modules.
The output limit counts stdout and stderr together, including result framing and
error/fatal diagnostics. Exactly the limit is allowed; the first excess byte
causes termination and an ErrOutputLimit result. Retained output never exceeds
the limit. A failed or truncated response does not expose a successful Payload.

Each worker accepts one protocol-v1 request on stdin and exits. print and log
write to stderr; stdout carries the structured completion and optional JSON
result from output(value). Functions and other JSON-incompatible results fail
explicitly. A script error is a *RemoteError, distinct from a crash, malformed
protocol or external deadline. No arbitrary Go globals, callbacks, module
loaders or host filesystem cross the protocol.

Source modules are a finite map of relative .star paths in a new memory
filesystem. Only log is enabled as a builtin module; this is not the existing
Safe or Full module profile. Unknown loads cannot fall back to the host's
working directory. Each request has a private working directory and an empty
environment except required Windows SystemRoot.

The supervisor kills the direct worker when the external deadline/cancellation
or captured-output limit fires, waits for it exactly once, closes its parent
pipe endpoints and joins the I/O goroutines before returning. Reaped and
PipesClosed report that cleanup. Output ordering across the two streams is
unspecified; a byte limit can split UTF-8 diagnostics.

This does not limit CPU usage or RSS, contain descendants, restrict the entire
OS filesystem/network, or provide an untrusted multi-tenant sandbox. A child can
allocate while constructing a result before emitting any bytes. A kernel task
that cannot be interrupted may delay Wait. The trusted executable path must be
immutable to the host's threat model; protocol=1 is not proof of binary origin.

Existing starbox.New, Run and RunnerConfig APIs keep their in-process behavior.
Go 1.19 and the fixed interpreter/module requirements remain unchanged. No
runtime downloading, module-version resolution or automatic PATH discovery is
performed.

182 changes: 182 additions & 0 deletions worker/protocol.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,182 @@
package worker

import (
"bytes"
"encoding/json"
"flag"
"fmt"
"io"
"io/fs"
"sort"
"strings"
"unicode/utf8"

"github.com/1set/starbox"
"github.com/1set/starlet"
"github.com/1set/starlet/dataconv"
"github.com/psanford/memfs"
"go.starlark.net/starlark"
"go.uber.org/zap"
"go.uber.org/zap/zapcore"
)

type wireRequest struct {
Protocol int `json:"protocol"`
Request
}
type wireResponse struct {
Protocol int `json:"protocol"`
OK bool `json:"ok"`
Result json.RawMessage `json:"result,omitempty"`
Error string `json:"error,omitempty"`
Kind string `json:"kind,omitempty"`
}

func decodeOne(data []byte, value interface{}) error {
decoder := json.NewDecoder(bytes.NewReader(data))
decoder.DisallowUnknownFields()
if err := decoder.Decode(value); err != nil {
return fmt.Errorf("%w: %v", ErrProtocol, err)
}
if err := decoder.Decode(new(interface{})); err != io.EOF {
return fmt.Errorf("%w: extra or malformed message", ErrProtocol)
}
return nil
}
func validateRequest(request Request, limit int64) error {
remaining := limit
add := func(s string) error {
if !utf8.ValidString(s) {
return fmt.Errorf("%w: invalid UTF-8", ErrProtocol)
}
if int64(len(s)) > remaining {
return ErrInputLimit
}
remaining -= int64(len(s))
return nil
}
if err := add(request.Source); err != nil {
return err
}
if err := add(request.Filename); err != nil {
return err
}
for name, source := range request.Modules {
if !fs.ValidPath(name) || !strings.HasSuffix(name, ".star") {
return fmt.Errorf("%w: module must be a relative .star path", ErrProtocol)
}
for _, builtin := range starlet.GetAllBuiltinModuleNames() {
if name == builtin+".star" {
return fmt.Errorf("%w: reserved module name", ErrProtocol)
}
}
if err := add(name); err != nil {
return err
}
if err := add(source); err != nil {
return err
}
}
return nil
}

// Serve reads exactly one bounded protocol-v1 request and writes one response.
// It accepts no host filesystem or Go callbacks. The caller must supervise this
// process; byte quotas do not bound the child's intermediate encoding memory.
func Serve(in io.Reader, out, diagnostics io.Writer, maxInput int64) error {
if maxInput <= 0 || maxInput == int64(^uint64(0)>>1) {
return fmt.Errorf("%w: invalid input budget", ErrProtocol)
}
data, err := io.ReadAll(io.LimitReader(in, maxInput+1))
if err != nil {
return err
}
if int64(len(data)) > maxInput {
return ErrInputLimit
}
request := wireRequest{}
if err := decodeOne(data, &request); err != nil {
return err
}
if request.Protocol != 1 {
return fmt.Errorf("%w: unsupported version", ErrProtocol)
}
if err := validateRequest(request.Request, maxInput); err != nil {
return err
}
return json.NewEncoder(out).Encode(execute(request.Request, diagnostics))
}
func execute(request Request, diagnostics io.Writer) wireResponse {
response := wireResponse{Protocol: 1}
fail := func(kind string, err error) wireResponse {
response.Kind = kind
response.Error = err.Error()
return response
}
box := starbox.NewWithPolicy("worker", starbox.Policy{Modules: starbox.ModuleAllow{Names: []string{"log"}}})
box.SetModuleSet(starbox.EmptyModuleSet)
box.AddNamedModules("log")
box.SetPrintFunc(func(_ *starlark.Thread, message string) { _, _ = fmt.Fprintln(diagnostics, message) })
logger := zap.New(zapcore.NewCore(zapcore.NewJSONEncoder(zap.NewProductionEncoderConfig()), zapcore.AddSync(diagnostics), zap.DebugLevel))
box.SetLogger(logger.Sugar())
memory := memfs.New()
names := make([]string, 0, len(request.Modules))
for name := range request.Modules {
names = append(names, name)
}
sort.Strings(names)
for _, name := range names {
if slash := strings.LastIndex(name, "/"); slash >= 0 {
if err := memory.MkdirAll(name[:slash], 0700); err != nil {
return fail("module", err)
}
}
if err := memory.WriteFile(name, []byte(request.Modules[name]), 0600); err != nil {
return fail("module", err)
}
}
box.SetFS(memory)
box.AddResultBuiltin("output")
box.GetMachine().SetOutputConversionEnabled(false)
filename := request.Filename
if filename == "" {
filename = "worker.star"
}
source := request.Source
if source == "" {
source = "\n"
}
if _, err := box.CreateRunConfig().FileName(filename).Script(source).Execute(); err != nil {
return fail(starbox.ClassifyRunError(err).Kind.String(), err)
}
if value, set := box.GetResult(); set {
result, err := dataconv.EncodeStarlarkJSON(value)
if err != nil {
return fail("result", err)
}
response.Result = json.RawMessage(result)
}
response.OK = true
return response
}

// Main is the command's actual noninteractive I/O boundary. Build the executable
// from the same reviewed module; protocol=1 is not a module-version claim.
func Main(args []string, in io.Reader, out, diagnostics io.Writer) int {
flags := flag.NewFlagSet("starbox-worker", flag.ContinueOnError)
flags.SetOutput(diagnostics)
protocol := flags.Int("protocol", 0, "required protocol version")
input := flags.Int64("max-input", 0, "required request byte limit")
if err := flags.Parse(args); err != nil {
return 2
}
if *protocol != 1 || *input <= 0 || flags.NArg() != 0 {
_, _ = fmt.Fprintln(diagnostics, "protocol=1 and a positive max-input are required")
return 2
}
if err := Serve(in, out, diagnostics, *input); err != nil {
_, _ = fmt.Fprintln(diagnostics, err)
return 2
}
return 0
}
Loading
Loading