From 78f8c29d615aa2f11c1455cbaf125d87f8ecda11 Mon Sep 17 00:00:00 2001 From: Kevin Tang <73975146+vt128@users.noreply.github.com> Date: Mon, 21 Sep 2026 01:17:23 +0800 Subject: [PATCH 1/4] [fix] keep the command splitter within the Go 1.19 floor --- README.md | 10 ++++++++++ go.mod | 2 +- go.sum | 8 +++++--- 3 files changed, 16 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 5fceb4b..bc3d1ac 100644 --- a/README.md +++ b/README.md @@ -129,3 +129,13 @@ option table, defaults, and accessors. ## License MIT + +### Go compatibility + +The library supports Go 1.19 and keeps `go.starlark.net` pinned to +`v0.0.0-20260324133313-ffb3f39dd27a`. The command splitter uses +`bitbucket.org/creachadair/shell v0.0.7` (Go 1.16): v0.0.8 raised its declared +minimum to Go 1.20 while changing only comments in the runtime source. The +older pin preserves the same command-splitting implementation without imposing +that additional dependency requirement. Use a supported patched Go toolchain +for production applications. diff --git a/go.mod b/go.mod index ce88f30..59736e3 100644 --- a/go.mod +++ b/go.mod @@ -3,7 +3,7 @@ module github.com/starpkg/cmd go 1.19 require ( - bitbucket.org/creachadair/shell v0.0.8 + bitbucket.org/creachadair/shell v0.0.7 github.com/1set/starlet v0.2.3 github.com/starpkg/base v0.1.2 go.starlark.net v0.0.0-20260324133313-ffb3f39dd27a diff --git a/go.sum b/go.sum index ac77a61..21b1406 100644 --- a/go.sum +++ b/go.sum @@ -1,5 +1,5 @@ -bitbucket.org/creachadair/shell v0.0.8 h1:3yM6JcAfaGWzjzcCamTblzSIWXm/YSs0PFGIzBm2HTo= -bitbucket.org/creachadair/shell v0.0.8/go.mod h1:vINzudofoUXZSJ5tREgpy+Etyjsag3ait5WOWImEVZ0= +bitbucket.org/creachadair/shell v0.0.7 h1:Z96pB6DkSb7F3Y3BBnJeOZH2gazyMTWlvecSD4vDqfk= +bitbucket.org/creachadair/shell v0.0.7/go.mod h1:oqtXSSvSYr4624lnnabXHaBsYW6RD80caLi2b3hJk0U= github.com/1set/starlet v0.2.3 h1:9YuS1Pa7ND6wetV2GRgY8RG7yLn30OqUY+4g4bk2/2Q= github.com/1set/starlet v0.2.3/go.mod h1:txkHyqtkqb1j9zBM0lOTwf6oW9vwtnsoLyUfqe9UeQo= github.com/1set/starlight v0.2.1 h1:07XiRr4XJ9p8rSL/A4XDC7sDInGszpXIP5jASCIZo10= @@ -10,7 +10,8 @@ github.com/chzyer/readline v0.0.0-20180603132655-2972be24d48e h1:fY5BOSpyZCqRo5O github.com/chzyer/readline v0.0.0-20180603132655-2972be24d48e/go.mod h1:nSuG5e5PlCu98SY8svDHJxuZscDgtXS6KTTbou5AhLI= github.com/chzyer/test v0.0.0-20180213035817-a1ea475d72b1 h1:q763qf9huN11kDQavWsoZXJNW3xEE4JJyHa5Q25/sd8= github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= -github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI= +github.com/google/go-cmp v0.5.6 h1:BKbKCqvP6I+rmFHt06ZmyQtvB8xAkWdhFyr0ZUNZcxQ= +github.com/google/go-cmp v0.5.6/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0= github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= github.com/h2so5/here v0.0.0-20200815043652-5e14eb691fae h1:ghqI9EdSyyIL2iuOM9UIGVO7kEYQFVLKAUIFoOea5MY= @@ -37,5 +38,6 @@ go.uber.org/zap v1.24.0 h1:FiJd5l1UOLj0wCgbSE0rwwXHzEdAZS6hiiSnxJN/D60= go.uber.org/zap v1.24.0/go.mod h1:2kMP+WWQ8aoFoedH3T2sq6iJ2yDWpHbP0f6MQbS9Gkg= golang.org/x/sys v0.5.0 h1:MUK/U/4lj1t1oPg0HfuXDN/Z1wv31ZJ/YcPiGccS4DU= golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= google.golang.org/protobuf v1.33.0 h1:uNO2rsAINq/JlFpSdYEKIZ0uKD/R9cpdv0T+yoGwGmI= gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= From fa465628dec6586d5ba8934c099bbe58d4696442 Mon Sep 17 00:00:00 2001 From: Kevin Tang <73975146+vt128@users.noreply.github.com> Date: Mon, 21 Sep 2026 01:42:07 +0800 Subject: [PATCH 2/4] [ci] refresh shared workflow and coverage authentication --- .github/workflows/build.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index fc97a2c..f039560 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -10,11 +10,14 @@ permissions: read-all jobs: ci: + permissions: + contents: read + id-token: write # Reusable CI lives in 1set/meta — the single source of truth for every # Star* module's pipeline. Pinned to a commit SHA for supply-chain safety; # bump the pin when meta's workflow changes (Dependabot github-actions can # automate this). - uses: 1set/meta/.github/workflows/go-ci.yml@5d86667e7264f012655dab2644dfa44e09597445 + uses: 1set/meta/.github/workflows/go-ci.yml@496f38088eff1a37bae1b43d158146a8a9d83a37 with: go-floor: "1.19" doc-coverage: true From 957a23fb7d4a3043eb6f4a4e3495268e544cf256 Mon Sep 17 00:00:00 2001 From: Kevin Tang <73975146+vt128@users.noreply.github.com> Date: Mon, 21 Sep 2026 17:49:29 +0800 Subject: [PATCH 3/4] [fix] require host grants for script environment keys --- CLAUDE.md | 10 +++--- README.md | 36 +++++++++++++++++++--- cmd.go | 77 ++++++++++++++++++++++++++++++++++++++++------- cmd_test.go | 86 ++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/API.md | 22 +++++++++++--- run_test.go | 87 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 6 files changed, 292 insertions(+), 26 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index d44d550..c7d2973 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -33,12 +33,12 @@ docker run --rm -v "$PWD":/src -v "$HOME/go/pkg/mod":/go/pkg/mod -w /src golang: The whole module is **one source file, `cmd.go`**, structured as a *policy gate in front of `os/exec`*. There is exactly one path from a script call to a spawned process, and every hardening check sits on it. -- **`Module`** — holds a `base.ConfigurableModule` (+ its `Extend()` view for typed config reads) plus two **host-policy** fields that are *not* config keys: `enabled` and `allow []string`. They are set only in Go and can never be read from a script or an env var. -- **Constructors** — `NewModule()` (disabled, default config), `NewModuleWithConfig(...)` (disabled, preset config), `NewModuleWithAllow(allow ...)` (**enabled** with an allowlist). There is deliberately no allow-*setter* method: enabling and the allowlist are bound together at construction. +- **`Module`** — holds a `base.ConfigurableModule` (+ its `Extend()` view for typed config reads) plus immutable **host-policy** fields that are *not* config keys: `enabled`, `allow`, `envKeys` and `allowAll`. They are set only in Go and can never be read from a script or an env var. +- **Constructors** — `NewModule()` (disabled, default config), `NewModuleWithConfig(...)` (disabled, preset config), `NewModuleWithAllow(allow ...)` (**enabled** with an allowlist). `NewModuleWithPolicy(Policy{Commands, EnvKeys})` adds copied exact environment-key grants; `NewModuleWithAllow` grants no environment overrides. There is deliberately no allow-*setter* method: grants are bound at construction. - **`LoadModule()`** — registers the two script-facing builtins: **`run`** (`m.run`) and **`which`** (`m.starWhich`), merged with the config-backed module surface from `base`. -- **`run` (the gate)** — the ordered pipeline: unpack args → require non-empty command → `sanitizeCommand` (UTF-8 + reject control/format chars) → split to argv via `creachadair/shell` (with a Windows backslash-doubling workaround) → join to a *canonical* string → `commandAllowed` check → resolve config defaults → `executeArgv`. The disabled-module check is the **first** thing `run` does. +- **`run` (the gate)** — the ordered pipeline: unpack args → require non-empty command → `sanitizeCommand` (UTF-8 + reject control/format chars) → split to argv via `creachadair/shell` (with a Windows backslash-doubling workaround) → join to a *canonical* string → `commandAllowed` check → resolve config defaults → validate every merged environment key against host policy → `executeArgv`. The disabled-module check is the **first** thing `run` does. - **`which` (`starWhich`)** — `exec.LookPath` only; returns the path or `None`. It does **not** execute, so it works even on a disabled module. -- **`executeArgv`** — the actual `exec.CommandContext` call (timeout from the thread context), env assembly (process env + extra `env=`), stdin wiring, and the stdout/stderr capture matrix driven by `capture_output`/`combine_output`/`realtime_output`. Returns a `ProcessResult`. +- **`executeArgv`** — the actual `exec.CommandContext` call (timeout from the thread context), env assembly (minimal host environment + approved config/call values), stdin wiring, and the stdout/stderr capture matrix driven by `capture_output`/`combine_output`/`realtime_output`. Returns a `ProcessResult`. - **`ProcessResult` → `createResultStruct`** — marshals the Go result into a `starlarkstruct` with `success`/`exit_code`/`pid`/`stdout`/`stderr`/`output`/`error`/`start_time`/`end_time`/`duration` (times via `go.starlark.net/lib/time`). - **Config** — six keys (`timeout`, `cwd`, `env`, `combine_output`, `realtime_output`, `capture_output`), each with a `CMD_` env var, defined through `base.NewConfigOption`. These are *behavioral defaults*, never the enable/allow policy. @@ -51,7 +51,7 @@ The PKG-09 security posture is the reason this module exists in its current form 3. **Allowlist matches at a word boundary.** `commandAllowed` matches an entry as a prefix of the canonical (single-space-joined) argv only when followed by end-of-string or a space: `"git"` permits `git status` but not `gitleaks`. Don't loosen this to a bare `strings.HasPrefix`. 4. **Unicode hardening before matching.** `sanitizeCommand` rejects invalid UTF-8, control characters, and Unicode format/zero-width characters (category `Cf`: zero-width space, BiDi overrides, BOM) — these can hide or reorder text so a command looks allowlisted while resolving to something else. Sanitize *before* splitting/matching, never after. 5. **No host panics from script input.** `run`/`which` validate and return script-level errors (empty command, unclosed quotes, denied command); they must not panic the host. -6. **Backward compatibility.** Config defaults reproduce historical behavior (`capture_output` defaults true; `timeout` 0 = no limit). The enable-gate is the one *new* lever and it defaults to off, so a host that already passes an allowlist is unaffected; a host that doesn't gets the safe (disabled) default. +6. **Backward compatibility.** Config defaults reproduce historical behavior (`capture_output` defaults true; `timeout` 0 = no limit). The enable-gate is the one *new* lever and it defaults to off, so a host that does not grant execution gets the safe (disabled) default. Restricted scripts that supply environment overrides must migrate to `NewModuleWithPolicy` with explicit keys; trusted allow-all retains its environment behavior. ## Test organization diff --git a/README.md b/README.md index bc3d1ac..0d0abde 100644 --- a/README.md +++ b/README.md @@ -34,12 +34,40 @@ script or by environment variables: the caller is fully trusted (e.g. a CLI behind a `--dangerously-allow-all` style flag). The input hardening above (argv-only, no shell, Unicode rejection) still applies; only the allowlist is skipped. Prefer `NewModuleWithAllow` with a - specific allowlist whenever the command set is known. - -The enable flag, allowlist, and allow-all decision are **not** configuration keys -— they are set in Go via `NewModuleWithAllow` / `NewModuleWithAllowAll` and cannot + specific allowlist whenever the command set is known. This trusted mode also + permits arbitrary environment overrides; dynamic-linker variables are still + stripped. +6. **Host-controlled environment keys.** `NewModuleWithAllow` permits no + script/config environment overrides. Use `NewModuleWithPolicy` with + `Policy{Commands: ..., EnvKeys: ...}` to grant exact keys. The same check + applies to `env=`, `set_env()` and `CMD_ENV` before a process starts. + Names are case-sensitive on Unix and case-insensitive on Windows; prefixes + and wildcards are not expanded. + +The enable flag, command/environment grants, and allow-all decision are **not** configuration keys +— they are set in Go via `NewModuleWithAllow`, `NewModuleWithPolicy` or +`NewModuleWithAllowAll` and cannot be widened by a script or environment variable. +### Environment grants and compatibility + +Scripts using `env=`, `set_env()` or `CMD_ENV` with `NewModuleWithAllow` must +migrate to explicit environment grants. For example: + +```go +module := cmd.NewModuleWithPolicy(cmd.Policy{ + Commands: []string{"go env GOOS"}, + EnvKeys: []string{"GOOS"}, +}) +``` + +Granting a key permits arbitrary values for every allowed command: review the +selected programs before granting keys such as `PATH`, `BASH_ENV`, +`GIT_CONFIG_*` or interpreter startup options. Grants do not expose additional +host environment variables. These checks govern the module's config and call +inputs; the host must also prevent untrusted scripts from mutating process-wide +environment or executable files through other modules. + ### Cross-platform note Because there is no shell, the first token must be a real **executable on diff --git a/cmd.go b/cmd.go index e33fb75..859ddc2 100644 --- a/cmd.go +++ b/cmd.go @@ -19,6 +19,7 @@ import ( "os" "os/exec" "runtime" + "sort" "strings" "time" "unicode" @@ -68,16 +69,41 @@ type ProcessResult struct { } // Module wraps the ConfigurableModule with specific functionality for command execution. -// enabled, allow and allowAll are host policy (set in Go) and are never +// enabled, allow, envKeys and allowAll are host policy (set in Go) and are never // overridable by a script or by environment variables. type Module struct { cfgMod *base.ConfigurableModule ext *base.ConfigurableModuleExt enabled bool allow []string + envKeys []string allowAll bool } +// Policy grants command prefixes and script-controlled environment keys. +// Commands uses the same word-boundary matching as NewModuleWithAllow. EnvKeys +// grants exact names (case-insensitive on Windows), never prefixes or wildcards. +// Each granted key permits arbitrary values, so the host must review its meaning +// for every allowed command. Neither field is script-settable. An empty policy +// permits no commands or environment overrides. +type Policy struct { + Commands []string + EnvKeys []string +} + +// NewModuleWithPolicy returns an enabled module with a copy of the host policy. +// Every key in env=, set_env() and CMD_ENV must be explicitly granted. This does +// not grant access to additional host environment values; the existing minimal +// host-environment inheritance remains in force. Dynamic-linker variables are +// always stripped before execution, even if explicitly granted. +func NewModuleWithPolicy(policy Policy) *Module { + m := NewModule() + m.enabled = true + m.allow = append([]string(nil), policy.Commands...) + m.envKeys = append([]string(nil), policy.EnvKeys...) + return m +} + // NewModule creates a new instance of Module with default configurations. // The module is DISABLED: run() returns an error until the host enables it with // an allowlist via NewModuleWithAllow. @@ -109,12 +135,10 @@ func NewModuleWithConfig(cwd string, env map[string]string, timeout float64, com // Each entry is a prefix matched against the canonical command (argv joined by a // single space) at a word boundary: "git" permits "git status" but not // "gitleaks"; "go test" permits "go test ./..." but not "go build". An empty -// allowlist enables the module but permits nothing (deny-all). +// allowlist enables the module but permits nothing (deny-all). No script/config +// environment overrides are permitted; use NewModuleWithPolicy to grant keys. func NewModuleWithAllow(allow ...string) *Module { - m := NewModule() - m.enabled = true - m.allow = append([]string(nil), allow...) - return m + return NewModuleWithPolicy(Policy{Commands: allow}) } // NewModuleWithAllowAll returns a module that is ENABLED and permits EVERY @@ -126,7 +150,9 @@ func NewModuleWithAllow(allow ...string) *Module { // other path (sanitizeCommand rejects control / zero-width characters, and // execution stays argv-only — never a shell). Like enable and allow, the // allow-all decision is Go-host state bound at construction: nothing a script -// does, and no environment variable, can set or widen it. +// does, and no environment variable, can set or widen it. This trusted mode also +// permits arbitrary environment overrides; dynamic-linker variables are still +// stripped before execution. func NewModuleWithAllowAll() *Module { m := NewModule() m.enabled = true @@ -290,6 +316,9 @@ func (m *Module) run(thread *starlark.Thread, b *starlark.Builtin, args starlark captureOutputBool := getBoolWithDefault(captureOutput, m.ext.GetBool(configKeyCaptureOutput, true)) envMap := buildEnvMap(m.cfgMod, env) + if err := m.checkEnvAllowed(envMap); err != nil { + return none, err + } result, err := executeArgv(thread, parts, cwdStr, timeoutFloat, stdinStr, combineOutputBool, realtimeOutputBool, captureOutputBool, envMap) if err != nil { @@ -301,6 +330,33 @@ func (m *Module) run(thread *starlark.Thread, b *starlark.Builtin, args starlark // Helper functions for argument processing +// checkEnvAllowed checks the merged config/call environment before any process +// is started. Sorting keeps the first rejected key deterministic; errors never +// include values, which may contain credentials. +func (m *Module) checkEnvAllowed(env map[string]string) error { + keys := make([]string, 0, len(env)) + for key := range env { + keys = append(keys, key) + } + sort.Strings(keys) + for _, key := range keys { + if key == "" || strings.ContainsAny(key, "=\x00") { + return fmt.Errorf("cmd: invalid environment variable name %q", key) + } + allowed := m.allowAll + for _, grant := range m.envKeys { + if key == grant || (runtime.GOOS == "windows" && strings.ToUpper(key) == strings.ToUpper(grant)) { + allowed = true + break + } + } + if !allowed { + return fmt.Errorf("cmd: environment variable %q is not permitted by the host policy", key) + } + } + return nil +} + // getStringWithDefault returns the first non-empty string from the given options. // A null value yields the empty string (let the OS/process default apply). func getStringWithDefault(val *types.NullableStringOrBytes, fallbacks ...string) string { @@ -359,10 +415,9 @@ var safeHostEnvKeys = []string{ // allowlisted binary and bypass the command allowlist. Covers the glibc/musl // (LD_*), macOS (DYLD_*), and AIX (LDR_*) loader families. // -// Note: this closes the universal loader-injection class only. App-specific -// env vars that also run code (e.g. GIT_CONFIG_*, BASH_ENV, interpreter startup -// hooks) are an open-ended surface a blocklist cannot fully cover; constraining -// script-supplied env to an allowlist is tracked separately. +// Restricted modules also require an explicit host grant for each config/call +// key before reaching this final filter. The trusted allow-all mode still uses +// this filter without restricting application-specific environment keys. func stripDangerousEnv(env map[string]string) map[string]string { out := make(map[string]string, len(env)) for k, v := range env { diff --git a/cmd_test.go b/cmd_test.go index 6fd3e78..51c28cf 100644 --- a/cmd_test.go +++ b/cmd_test.go @@ -8,9 +8,13 @@ package cmd // - constructor policy state (enabled/allow are Go-host only) // - argument defaulting helpers (cwd / timeout / bool) // - env map building (config default + per-call override) +// - host environment grants: exact keys, immutable policy, full module surface // - result struct shaping (capture/combine output matrix) import ( + "reflect" + "runtime" + "sort" "strings" "testing" "time" @@ -454,3 +458,85 @@ func TestSafeHostEnvIncludesProxyAndCA(t *testing.T) { } } } + +// --- Host environment grants ------------------------------------------------- + +func TestEnvironmentPolicy(t *testing.T) { + commands, keys := []string{"go version"}, []string{"APP_SETTING", "MixedCase"} + m := NewModuleWithPolicy(Policy{Commands: commands, EnvKeys: keys}) + commands[0], keys[0] = "other", "BASH_ENV" + if !commandAllowed("go version", m.allow) || commandAllowed("other", m.allow) { + t.Fatal("command policy was not copied") + } + for _, tc := range []struct { + key string + allowed bool + }{ + {"APP_SETTING", true}, {"APP_SETTING_EXTRA", false}, {"APP_", false}, + {"MixedCase", true}, {"mixedcase", runtime.GOOS == "windows"}, + {"BASH_ENV", false}, {"PATH", false}, {"Path", false}, {"", false}, + {"APP_SETTING=INJECTED", false}, {"APP_SETTING\x00", false}, + } { + err := m.checkEnvAllowed(map[string]string{tc.key: "fixture-value"}) + if (err == nil) != tc.allowed { + t.Errorf("key %q: err=%v, allowed=%v", tc.key, err, tc.allowed) + } + } + if err := m.checkEnvAllowed(nil); err != nil { + t.Errorf("empty overrides: %v", err) + } + wildcard := NewModuleWithPolicy(Policy{EnvKeys: []string{"APP_*"}}) + if err := wildcard.checkEnvAllowed(map[string]string{"APP_SETTING": "x"}); err == nil { + t.Error("environment grant must not expand a wildcard") + } + all := NewModuleWithAllowAll() + if err := all.checkEnvAllowed(map[string]string{"APP_SETTING": "x"}); err != nil { + t.Errorf("trusted allow-all rejected environment: %v", err) + } + for _, key := range []string{"", "bad=name", "bad\x00name"} { + if err := all.checkEnvAllowed(map[string]string{key: "x"}); err == nil { + t.Errorf("allow-all accepted invalid name %q", key) + } + } + for i := 0; i < 20; i++ { + err := m.checkEnvAllowed(map[string]string{"Z_BAD": "z", "A_BAD": "a"}) + if err == nil || !strings.Contains(err.Error(), `"A_BAD"`) { + t.Errorf("first denial must be deterministic: %v", err) + } + } +} + +func TestHostPolicyModuleSurface(t *testing.T) { + want := []string{ + "get_capture_output", "get_combine_output", "get_cwd", "get_env", "get_realtime_output", "get_timeout", + "run", "set_capture_output", "set_combine_output", "set_cwd", "set_env", "set_realtime_output", "set_timeout", "which", + } + for _, m := range []*Module{NewModule(), NewModuleWithAllow("go"), NewModuleWithPolicy(Policy{Commands: []string{"go"}, EnvKeys: []string{"GOOS"}}), NewModuleWithAllowAll()} { + values, err := m.LoadModule()() + if err != nil { + t.Fatal(err) + } + if len(values) != 1 || values[ModuleName] == nil { + t.Fatalf("unexpected module exports: %v", values.Keys()) + } + got := values[ModuleName].(starlark.HasAttrs).AttrNames() + sort.Strings(got) + if !reflect.DeepEqual(got, want) { + t.Errorf("script-facing surface changed: %v, want %v", got, want) + } + } +} + +func BenchmarkRunWithoutEnvironmentOverrides(b *testing.B) { + m := NewModuleWithAllow("cmd-benchmark-missing-executable") + fn := starlark.NewBuiltin("cmd.run", m.run) + thread := &starlark.Thread{} + args := starlark.Tuple{starlark.String("cmd-benchmark-missing-executable")} + b.ReportAllocs() + b.ResetTimer() + for i := 0; i < b.N; i++ { + if _, err := starlark.Call(thread, fn, args, nil); err != nil { + b.Fatal(err) + } + } +} diff --git a/docs/API.md b/docs/API.md index 477a77b..4f8db7b 100644 --- a/docs/API.md +++ b/docs/API.md @@ -42,7 +42,7 @@ globbing) are **not** interpreted. Pass environment variables explicitly via - `command` (string, required): the command line, split into argv (no shell) - `cwd` (string, optional): working directory (default: the `cwd` config option, else the current directory) -- `env` (dict, optional): extra environment variables, merged on top of the `env` config option. The child does **not** inherit the host's full environment: only an allowlist of safe, non-secret operational variables (e.g. `PATH`, `HOME`, `TZ`, proxy/CA settings) is passed through, so host secrets are withheld. Dynamic-linker preload variables (`LD_*`/`DYLD_*`/`LDR_*`) are stripped even when supplied here. +- `env` (dict, optional): extra environment variables, merged on top of the `env` config option. In restricted modules every merged key must be explicitly granted through `Policy.EnvKeys`; `NewModuleWithAllow` grants none. Unknown keys raise an error before execution. The child does **not** inherit the host's full environment: only an allowlist of safe, non-secret operational variables (e.g. `PATH`, `HOME`, `TZ`, proxy/CA settings) is passed through, so host secrets are withheld. Dynamic-linker preload variables (`LD_*`/`DYLD_*`/`LDR_*`) are stripped even when supplied here. - `stdin` (string, optional): input written to the command's standard input - `timeout` (float, optional): max execution time in seconds (default: the `timeout` config option; `0` = no limit) - `combine_output` (bool, optional): combine stdout and stderr into `output` (default: the `combine_output` config option, normally `false`) @@ -59,6 +59,7 @@ globbing) are **not** interpreted. Pass environment variables explicitly via format/zero-width character - `command` has invalid syntax or unclosed quotes (cannot be split into argv) - the command's canonical form is not permitted by the allowlist +- a merged environment key is not granted by the host policy, or its name is empty or contains `=`/NUL A command that runs but exits non-zero does **not** raise; it returns a `ProcessResult` with `success = False` and the non-zero `exit_code`. A command @@ -172,7 +173,9 @@ widened by a script or an environment variable. - `NewModule()` — a **disabled** module with default config; `run()` always errors. - `NewModuleWithConfig(cwd, env, timeout, combineOutput, realtimeOutput, captureOutput)` — a **disabled** module with preset config defaults. -- `NewModuleWithAllow(allow ...string)` — an **enabled** module with the given allowlist. +- `NewModuleWithAllow(allow ...string)` — an **enabled** module with the given command allowlist and no script/config environment grants. +- `NewModuleWithPolicy(policy Policy)` — an **enabled** module with copied command and environment grants. `Policy.Commands` uses the same command matching; `Policy.EnvKeys` permits exact environment names (case-insensitive only on Windows). Empty command grants still deny every command; an empty environment grant permits no overrides. No wildcard or prefix expansion is performed. +- `NewModuleWithAllowAll()` — a trusted module permitting every command and arbitrary environment overrides. Input hardening and dynamic-linker stripping remain in force. Each allowlist entry is a prefix matched against the canonical command (argv joined by single spaces) at a word boundary: `"git"` permits `git status` but @@ -180,8 +183,17 @@ not `gitleaks`; `"go test"` permits `go test ./...` but not `go build`. An empty allowlist enables the module but permits nothing (deny-all). There is deliberately no allow-*setter*: enabling and the allowlist are bound -together at construction. To enable execution you must construct the module via -`NewModuleWithAllow(...)`; `NewModuleWithConfig(...)` returns a disabled module. +together at construction. The policy also checks values supplied through +`set_env()` and `CMD_ENV`; these sources cannot create new key grants. +`NewModuleWithConfig(...)` returns a disabled module. + +**Migration:** a script that supplies environment values to a restricted module +now needs explicit host grants. For example, construct +`NewModuleWithPolicy(Policy{Commands: []string{"go env GOOS"}, EnvKeys: []string{"GOOS"}})`. +Each grant permits arbitrary values for that key, so review it against every +allowed executable. Dynamic-linker variables remain stripped even if granted. +This does not authorize additional host-environment inheritance or protect +against another module mutating the process-wide environment/executable files. ```go // Go host: enable cmd with an allowlist @@ -211,7 +223,7 @@ accessor — never a getter — but this module has none.) | Option | Getter | Setter | Type | Env var | Default | Description | |--------|--------|--------|------|---------|---------|-------------| | `cwd` | `get_cwd` | `set_cwd` | string | `CMD_CWD` | current directory | Default working directory for commands | -| `env` | `get_env` | `set_env` | dict | `CMD_ENV` | `{}` | Environment variables added to every command | +| `env` | `get_env` | `set_env` | dict | `CMD_ENV` | `{}` | Environment defaults added to every command; merged keys remain subject to host grants | | `timeout` | `get_timeout` | `set_timeout` | float | `CMD_TIMEOUT` | `0` | Default timeout in seconds (`0` = no limit) | | `combine_output` | `get_combine_output` | `set_combine_output` | bool | `CMD_COMBINE_OUTPUT` | `false` | Combine stdout and stderr into `output` | | `realtime_output` | `get_realtime_output` | `set_realtime_output` | bool | `CMD_REALTIME_OUTPUT` | `false` | Echo output to the console in real time | diff --git a/run_test.go b/run_test.go index 6273200..5f28f1a 100644 --- a/run_test.go +++ b/run_test.go @@ -12,10 +12,12 @@ package cmd_test // documented ProcessResult field shape) // - failed execution result shape (nonzero exit; allowed-but-missing binary) // - NewModuleWithConfig stays disabled (host policy is construction-bound) +// - script environment policy: config and per-call values cannot widen host grants // - cross-platform execution (real argv run + stdout capture proven per-OS; // this section runs in CI on ubuntu/macos/windows) import ( + "fmt" "os/exec" "runtime" "strings" @@ -183,7 +185,7 @@ run("go version\nrm -rf /") // --- run options ------------------------------------------------------------- func TestRunOptions(t *testing.T) { - module := cmd.NewModuleWithAllow("go", "cat") + module := cmd.NewModuleWithPolicy(cmd.Policy{Commands: []string{"go", "cat"}, EnvKeys: []string{"GOOS"}}) t.Run("env is passed to the child", func(t *testing.T) { // `go env GOOS` reports the GOOS read from the process environment, so @@ -441,3 +443,86 @@ print("pwd:", r.stdout.strip()) t.Errorf("PWD should equal cwd %q, got:\n%s", dir, out) } } + +// --- Script environment policy ---------------------------------------------- + +func TestRestrictedEnvironmentDefaultDeny(t *testing.T) { + for _, key := range []string{ + "GIT_CONFIG_COUNT", "GIT_CONFIG_KEY_0", "GIT_CONFIG_VALUE_0", "BASH_ENV", "ENV", + "PYTHONSTARTUP", "PERL5OPT", "NODE_OPTIONS", "RUBYOPT", "PATH", "Path", + "HOME", "SHELL", "ComSpec", "GOFLAGS", "LD_PRELOAD", "DYLD_INSERT_LIBRARIES", + "LDR_PRELOAD", "APP_SETTING", + } { + for _, source := range []string{"argument", "setter", "environment"} { + t.Run(key+"/"+source, func(t *testing.T) { + extra := fmt.Sprintf("{%q: %q}", key, "fixture-value") + script := `load("cmd", "run", "set_env")` + "\n" + switch source { + case "argument": + script += "run(\"go version\", env=" + extra + ")" + case "setter": + script += "set_env(" + extra + ")\nrun(\"go version\")" + case "environment": + t.Setenv("CMD_ENV", extra) + script += "run(\"go version\")" + } + _, err := runScript(cmd.NewModuleWithAllow("go"), script) + if err == nil || !strings.Contains(err.Error(), "environment variable") { + t.Fatalf("ungranted key %q accepted via %s: %v", key, source, err) + } + if strings.Contains(err.Error(), "fixture-value") { + t.Errorf("policy error must not echo environment values: %v", err) + } + }) + } + } +} + +func TestEnvironmentPolicyIntegration(t *testing.T) { + for _, source := range []string{"argument", "setter", "environment"} { + t.Run(source, func(t *testing.T) { + m := cmd.NewModuleWithPolicy(cmd.Policy{Commands: []string{"go env GOOS"}, EnvKeys: []string{"GOOS"}}) + script := `load("cmd", "run", "set_env")` + "\n" + switch source { + case "argument": + script += `r = run("go env GOOS", env={"GOOS": "js"})` + case "setter": + script += "set_env({\"GOOS\": \"js\"})\nr = run(\"go env GOOS\")" + case "environment": + t.Setenv("CMD_ENV", `{"GOOS":"js"}`) + script += `r = run("go env GOOS")` + } + out, err := runScript(m, script+"\nprint(r.success)\nprint(r.stdout.strip())") + if err != nil || !strings.Contains(out, "True\njs") { + t.Fatalf("granted environment not delivered: out=%q err=%v", out, err) + } + }) + } + t.Run("call override cannot hide a denied config key", func(t *testing.T) { + m := cmd.NewModuleWithPolicy(cmd.Policy{Commands: []string{"go"}, EnvKeys: []string{"GOOS"}}) + _, err := runScript(m, ` +load("cmd", "run", "set_env") +set_env({"GOOS": "linux", "BASH_ENV": "fixture"}) +run("go env GOOS", env={"GOOS": "js"}) +`) + if err == nil || !strings.Contains(err.Error(), "BASH_ENV") { + t.Fatalf("config environment escaped policy: %v", err) + } + }) + t.Run("empty commands still deny execution", func(t *testing.T) { + _, err := runScript(cmd.NewModuleWithPolicy(cmd.Policy{EnvKeys: []string{"GOOS"}}), `load("cmd", "run")`+"\n"+`run("go version")`) + if err == nil || !strings.Contains(err.Error(), "command") { + t.Fatalf("environment grant enabled an ungranted command: %v", err) + } + }) + t.Run("allow-all retains trusted environment", func(t *testing.T) { + out, err := runScript(cmd.NewModuleWithAllowAll(), ` +load("cmd", "run") +r = run("go env GOOS", env={"GOOS": "js"}) +print(r.stdout.strip()) +`) + if err != nil || strings.TrimSpace(out) != "js" { + t.Fatalf("allow-all behavior changed: out=%q err=%v", out, err) + } + }) +} From 3ea7c0340092783ccd5f5c5bc60c0ae923e5b30a Mon Sep 17 00:00:00 2001 From: Kevin Tang <73975146+vt128@users.noreply.github.com> Date: Mon, 21 Sep 2026 17:58:16 +0800 Subject: [PATCH 4/4] [refactor] Separate environment grants from validation (STAR-95) --- cmd.go | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/cmd.go b/cmd.go index 859ddc2..1f35590 100644 --- a/cmd.go +++ b/cmd.go @@ -343,20 +343,26 @@ func (m *Module) checkEnvAllowed(env map[string]string) error { if key == "" || strings.ContainsAny(key, "=\x00") { return fmt.Errorf("cmd: invalid environment variable name %q", key) } - allowed := m.allowAll - for _, grant := range m.envKeys { - if key == grant || (runtime.GOOS == "windows" && strings.ToUpper(key) == strings.ToUpper(grant)) { - allowed = true - break - } - } - if !allowed { + if !m.envKeyAllowed(key) { return fmt.Errorf("cmd: environment variable %q is not permitted by the host policy", key) } } return nil } +// envKeyAllowed matches exact host grants using the child environment's case rules. +func (m *Module) envKeyAllowed(key string) bool { + if m.allowAll { + return true + } + for _, grant := range m.envKeys { + if key == grant || (runtime.GOOS == "windows" && strings.ToUpper(key) == strings.ToUpper(grant)) { + return true + } + } + return false +} + // getStringWithDefault returns the first non-empty string from the given options. // A null value yields the empty string (let the OS/process default apply). func getStringWithDefault(val *types.NullableStringOrBytes, fallbacks ...string) string {