Skip to content
Merged
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: 4 additions & 1 deletion .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
10 changes: 5 additions & 5 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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_<KEY>` env var, defined through `base.NewConfigOption`. These are *behavioral defaults*, never the enable/allow policy.

Expand All @@ -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

Expand Down
46 changes: 42 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -129,3 +157,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.
83 changes: 72 additions & 11 deletions cmd.go
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ import (
"os"
"os/exec"
"runtime"
"sort"
"strings"
"time"
"unicode"
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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 {
Expand All @@ -301,6 +330,39 @@ 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)
}
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 {
Expand Down Expand Up @@ -359,10 +421,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 {
Expand Down
86 changes: 86 additions & 0 deletions cmd_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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)
}
}
}
Loading
Loading