feat: sandbox --best-effort for container environments (#289)

Adds graceful degradation when user namespace creation is blocked
(k8s default seccomp, AppArmor). Landlock and seccomp containment
layers still apply. Network scanning uses proxy-based routing.

- --best-effort flag on sandbox and mcp proxy commands
- --env flag for passing env vars to sandboxed processes
- Pure Go netlink loopback (no ip binary dependency)
- io_uring returns EPERM instead of KILL (Node.js 22 compat)
- readlink syscall added to seccomp allowlist
- secretDirs checks existence (container compat)
- Dynamic bridge proxy port in best-effort mode
- Config: sandbox.best_effort with hot-reload + enterprise merge
- Docs: sandbox setup guide with deployment environments table

Author: luckyPipewrench

CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Sandbox `--best-effort` flag: gracefully degrades when user namespace creation is blocked (e.g. k8s containers with default seccomp). Landlock and seccomp containment layers still apply. Network scanning uses proxy-based routing instead of kernel-enforced namespace isolation.
+- Sandbox `--env` flag: pass environment variables to sandboxed processes (KEY or KEY=VALUE, repeatable). Validates against dangerous keys (LD_PRELOAD, NODE_OPTIONS, etc.) that could subvert containment.
+- MCP proxy `--sandbox-best-effort` flag: parity with `pipelock sandbox --best-effort` for MCP stdio wrapping mode.
+- Pure Go netlink loopback: sandbox uses raw netlink syscalls to bring up loopback inside network namespaces. No `ip` binary required. Works in minimal container images without iproute2.
+
+### Fixed
+- Seccomp io_uring handling: changed from KILL_PROCESS to EPERM so runtimes like Node.js 22 that probe io_uring at startup can gracefully fall back to epoll instead of crashing.
+- Seccomp `readlink` syscall: added `SYS_READLINK` (nr 89) to the allowlist. Node.js/libuv uses the legacy readlink syscall directly, not readlinkat.
+- Sandbox secret dir validation: `secretDirs()` now only protects directories that actually exist. Prevents false validation errors in containers.
+- Sandbox bridge proxy dynamic port: in best-effort mode, uses dynamic port instead of hardcoded 8888.
+- Config reload detection: `sandbox.best_effort` changes detected during hot reload. Per-agent `best_effort` propagated through enterprise merge.
+- Config validation: `sandbox.best_effort` and `sandbox.strict` mutually exclusive.
+
 ## [2.0.0] - 2026-03-22
 
 ### Added

README.md

@@ -6,7 +6,6 @@
 
 [![CI](https://github.com/luckyPipewrench/pipelock/actions/workflows/ci.yaml/badge.svg)](https://github.com/luckyPipewrench/pipelock/actions/workflows/ci.yaml)
 [![Security](https://github.com/luckyPipewrench/pipelock/actions/workflows/security.yaml/badge.svg)](https://github.com/luckyPipewrench/pipelock/actions/workflows/security.yaml)
-[![Pipelock Security Scan](https://github.com/luckyPipewrench/pipelock/actions/workflows/pipelock.yaml/badge.svg)](https://github.com/luckyPipewrench/pipelock/actions/workflows/pipelock.yaml)
 [![Go Report Card](https://goreportcard.com/badge/github.com/luckyPipewrench/pipelock)](https://goreportcard.com/report/github.com/luckyPipewrench/pipelock)
 [![GitHub Release](https://img.shields.io/github/v/release/luckyPipewrench/pipelock)](https://github.com/luckyPipewrench/pipelock/releases)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/luckyPipewrench/pipelock/badge)](https://scorecard.dev/viewer/?uri=github.com/luckyPipewrench/pipelock)
@@ -233,12 +232,13 @@ DLP runs before DNS resolution, designed to catch secrets before any DNS query l
 
 See [docs/bypass-resistance.md](docs/bypass-resistance.md) for the full evasion test matrix.
 
-### Process Sandbox (Linux)
+### Process Sandbox
 
-Unprivileged process containment using Landlock LSM, network namespaces, and seccomp. No root, no Docker, no containers. The agent runs in an isolated environment with controlled filesystem access, no direct network egress, and a filtered syscall set. Works with any command — MCP servers, standalone agents, or arbitrary processes.
+Unprivileged process containment using OS-native kernel primitives. On Linux: Landlock LSM restricts filesystem access, seccomp filters dangerous syscalls, and network namespaces force all traffic through pipelock's scanner (no direct egress). On macOS: sandbox-exec profiles restrict filesystem and network. In containers, use `--best-effort` for Landlock + seccomp containment when namespace creation is restricted (network scanning uses proxy-based routing instead of kernel enforcement).
 
 ```bash
 pipelock sandbox --config pipelock.yaml -- python agent.py
+pipelock sandbox --best-effort -- python agent.py  # containers
 pipelock mcp proxy --sandbox --config pipelock.yaml -- npx server
 ```
 

docs/configuration.md

@@ -1405,32 +1405,37 @@ rules:
 
 ## Sandbox
 
-Process containment for agent commands using Linux kernel primitives. The agent runs in a restricted namespace with controlled filesystem access, no direct network, and a filtered syscall set.
+Process containment for agent commands using Linux kernel primitives. The agent runs in a restricted environment with controlled filesystem access, no direct network, and a filtered syscall set.
 
 ```yaml
 sandbox:
   enabled: true
+  best_effort: false              # degrade gracefully when namespace isolation unavailable
+  strict: false                   # error if any layer unavailable (mutually exclusive with best_effort)
   workspace: /home/user/project   # agent working directory (default: CWD)
   filesystem:                     # optional Landlock overrides (default policy works for most agents)
     allow_read:
       - /usr/share/data
+      - /app/                     # application code in containers
     allow_write:
       - /tmp/agent-work
 ```
 
 | Field | Default | Description |
 |-------|---------|-------------|
 | `enabled` | `false` | Enable sandbox containment |
+| `best_effort` | `false` | Skip namespace isolation when unavailable (e.g. containers). Landlock + seccomp still apply. |
+| `strict` | `false` | Error if any containment layer is unavailable. Mutually exclusive with `best_effort`. |
 | `workspace` | CWD | Agent working directory (resolved to absolute at startup) |
 | `filesystem.allow_read` | `[]` | Additional read-only filesystem paths |
 | `filesystem.allow_write` | `[]` | Additional writable paths (workspace is always writable) |
 
 If `filesystem` is omitted, the default Landlock policy is used (safe for Python/Node/Go agents without config). Read access grants execute (Landlock bundling). Write paths are also executable.
 
 **Containment layers:**
-- **Landlock LSM:** Restricts filesystem access to declared paths. Read-only and read-write grants are explicit. Allowlist model.
-- **Network namespaces:** Agent runs in an isolated network namespace. For MCP (stdio), no network is needed. For standalone agents, traffic routes through pipelock's bridge proxy.
-- **Seccomp BPF:** Syscall allowlist blocks dangerous operations (ptrace, mount, io_uring, module loading, kexec). Clone flags are filtered to prevent namespace escape.
+- **Landlock LSM:** Restricts filesystem access to declared paths. Allowlist model. Protected directories (`~/.ssh`, `~/.aws`, `~/.kube`, etc.) are denied. Only dirs that exist on the system are checked.
+- **Network namespaces:** Agent runs in an isolated network namespace. All traffic is kernel-forced through pipelock's bridge proxy. Raw socket bypass is impossible. For MCP (stdio), no network is needed.
+- **Seccomp BPF:** Syscall allowlist (~130 safe syscalls for Go/Python/Node.js). Blocks ptrace, mount, module loading, kexec (KILL). io_uring returns EPERM (allows runtimes like Node.js 22 to fall back to epoll). Clone flags filtered to prevent namespace escape.
 
 **Usage:**
 ```bash
@@ -1439,9 +1444,26 @@ pipelock mcp proxy --sandbox --config pipelock.yaml -- npx server
 
 # Sandbox a standalone command
 pipelock sandbox --config pipelock.yaml -- python agent.py
+
+# Pass environment variables to sandboxed process
+pipelock sandbox --env API_KEY --env HOME=/app -- node server.js
+
+# Best-effort mode for containers (Landlock + seccomp, no namespace)
+pipelock sandbox --best-effort -- python agent.py
+
+# Check sandbox capabilities without launching
+pipelock sandbox --dry-run --json -- python agent.py
 ```
 
-**Requirements:** Linux 5.13+ (Landlock ABI v1). Unprivileged — no root, no Docker, no special capabilities. Not available on macOS or Windows (hard error with explanation).
+**Environments:**
+
+| Environment | Layers | Notes |
+|-------------|--------|-------|
+| Bare metal / VM (Linux) | 3/3 | Full containment: Landlock + seccomp + network namespace |
+| Containers (`--best-effort`) | 2/3 | Landlock + seccomp. Network via HTTP_PROXY + NetworkPolicy. |
+| macOS | sandbox-exec | Apple SBPL profiles for filesystem + network restriction |
+
+**Requirements:** Linux 5.13+ (Landlock ABI v1). Unprivileged on bare metal. macOS 13+ for sandbox-exec. Containers may need `--best-effort` if default seccomp blocks `CLONE_NEWUSER`.
 
 ## Config Audit Scoring (v2.0)
 

enterprise/config.go

@@ -385,6 +385,9 @@ func MergeAgentProfile(base *config.Config, profile *config.AgentProfile) (*conf
 		if profile.Sandbox.Strict != nil {
 			merged.Sandbox.Strict = *profile.Sandbox.Strict
 		}
+		if profile.Sandbox.BestEffort != nil {
+			merged.Sandbox.BestEffort = *profile.Sandbox.BestEffort
+		}
 		if profile.Sandbox.Workspace != "" {
 			merged.Sandbox.Workspace = profile.Sandbox.Workspace
 		}

enterprise/config_test.go

@@ -911,6 +911,42 @@ func TestMergeAgentProfile_SandboxFSAppendToNilBase(t *testing.T) {
 	}
 }
 
+func TestMergeAgentProfile_SandboxBestEffortOverride(t *testing.T) {
+	cfg := testConfig()
+	cfg.Sandbox.BestEffort = false
+
+	bestEffort := true
+	profile := &config.AgentProfile{
+		Sandbox: &config.AgentSandboxOverride{
+			BestEffort: &bestEffort,
+		},
+	}
+	merged, err := MergeAgentProfile(cfg, profile)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !merged.Sandbox.BestEffort {
+		t.Error("expected sandbox.best_effort=true (explicit override)")
+	}
+}
+
+func TestMergeAgentProfile_SandboxBestEffortInherits(t *testing.T) {
+	cfg := testConfig()
+	cfg.Sandbox.BestEffort = true
+
+	// Profile with nil BestEffort — should inherit from base.
+	profile := &config.AgentProfile{
+		Sandbox: &config.AgentSandboxOverride{},
+	}
+	merged, err := MergeAgentProfile(cfg, profile)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !merged.Sandbox.BestEffort {
+		t.Error("expected sandbox.best_effort=true (inherited from base)")
+	}
+}
+
 func TestResolvePublicKey_InvalidHex(t *testing.T) {
 	cfg := testConfig()
 	cfg.LicensePublicKey = "not-valid-hex"

internal/cli/mcp.go

@@ -128,6 +128,7 @@ func mcpProxyCmd() *cobra.Command {
 	var agentName string
 	var sandboxEnabled bool
 	var sandboxStrict bool
+	var sandboxBestEffort bool
 	var sandboxWorkspace string
 
 	cmd := &cobra.Command{
@@ -496,15 +497,15 @@ Environment passthrough (subprocess mode only):
 
 			// Subprocess mode.
 			serverCmd := args[dashIdx:]
-			// --sandbox-strict implies --sandbox.
-			if sandboxStrict {
+			// --sandbox-strict and --sandbox-best-effort imply --sandbox.
+			if sandboxStrict || sandboxBestEffort {
 				sandboxEnabled = true
 			}
 			useSandbox := sandboxEnabled || cfg.Sandbox.Enabled
 
-			// Reject config-enabled sandbox with remote modes.
-			if cfg.Sandbox.Enabled && (hasUpstream || hasListen) {
-				return errors.New("sandbox.enabled cannot be used with --upstream or --listen (cannot sandbox a remote server)")
+			// Reject sandbox with remote modes.
+			if useSandbox && (hasUpstream || hasListen) {
+				return errors.New("sandbox cannot be used with --upstream or --listen (cannot sandbox a remote server)")
 			}
 
 			// Sandboxed MCP proxy: child in isolated namespace.
@@ -532,13 +533,19 @@ Environment passthrough (subprocess mode only):
 				defer cancel()
 
 				mcpStrict := sandboxStrict || cfg.Sandbox.Strict
+				mcpBestEffort := sandboxBestEffort || cfg.Sandbox.BestEffort
+
+				if mcpStrict && mcpBestEffort {
+					return errors.New("--sandbox-strict and --sandbox-best-effort are mutually exclusive")
+				}
 
 				launchCfg := sandbox.LaunchConfig{
-					Ctx:       ctx,
-					Command:   serverCmd,
-					Workspace: workspace,
-					Strict:    mcpStrict,
-					ExtraEnv:  extraEnv,
+					Ctx:        ctx,
+					Command:    serverCmd,
+					Workspace:  workspace,
+					Strict:     mcpStrict,
+					BestEffort: mcpBestEffort,
+					ExtraEnv:   extraEnv,
 				}
 				if cfg.Sandbox.FS != nil {
 					p := sandbox.DefaultPolicy(workspace)
@@ -652,6 +659,7 @@ Environment passthrough (subprocess mode only):
 	cmd.Flags().StringVar(&agentName, "agent", "", "agent profile name (resolves to config profile for policy/scanner)")
 	cmd.Flags().BoolVar(&sandboxEnabled, "sandbox", false, "run child in sandbox (Landlock + seccomp + network namespace, Linux only)")
 	cmd.Flags().BoolVar(&sandboxStrict, "sandbox-strict", false, "strict sandbox: error on missing layers, private /dev/shm, block clone3 (implies --sandbox)")
+	cmd.Flags().BoolVar(&sandboxBestEffort, "sandbox-best-effort", false, "degrade gracefully when namespace isolation is unavailable (implies --sandbox)")
 	cmd.Flags().StringVar(&sandboxWorkspace, "workspace", "", "sandbox workspace directory (default: current directory)")
 	return cmd
 }

internal/cli/sandbox.go

@@ -30,8 +30,10 @@ func sandboxCmd() *cobra.Command {
 	var workspace string
 	var configFile string
 	var strict bool
+	var bestEffort bool
 	var dryRun bool
 	var jsonOutput bool
+	var envVars []string
 
 	cmd := &cobra.Command{
 		Use:   "sandbox [flags] -- COMMAND [ARGS...]",
@@ -45,9 +47,14 @@ func sandboxCmd() *cobra.Command {
 Agent HTTP/HTTPS traffic is routed through pipelock's full scanner pipeline
 (DLP, SSRF, blocklist, rate limiting, entropy analysis) via a bridge proxy.
 
+Use --best-effort inside containers where user namespace creation is blocked
+(e.g. Kubernetes with default seccomp). Landlock and seccomp are still applied;
+network scanning uses proxy-based routing instead of kernel-enforced isolation.
+
 Examples:
   pipelock sandbox -- python agent.py
   pipelock sandbox --workspace /home/user/project -- node server.js
+  pipelock sandbox --best-effort -- python agent.py  # inside containers
   pipelock sandbox --config pipelock.yaml -- bash -c "curl https://example.com"`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			dashIdx := cmd.ArgsLenAtDash()
@@ -75,6 +82,11 @@ Examples:
 			workspace, _ = filepath.Abs(workspace)
 
 			useStrict := strict || cfg.Sandbox.Strict
+			useBestEffort := bestEffort || cfg.Sandbox.BestEffort
+
+			if useStrict && useBestEffort {
+				return errors.New("--strict and --best-effort are mutually exclusive")
+			}
 
 			// Dry-run: preflight check without launching.
 			if dryRun {
@@ -141,11 +153,30 @@ Examples:
 				_ = srv.Serve(&singleConnListener{conn: conn})
 			}
 
+			// Resolve --env flags: KEY=VALUE passes as-is, bare KEY inherits from parent.
+			var extraEnv []string
+			for _, e := range envVars {
+				key, _, hasValue := strings.Cut(e, "=")
+				if key == "" {
+					return errors.New("--env requires a non-empty variable name")
+				}
+				if sandbox.IsDangerousEnvKey(key) {
+					return fmt.Errorf("--env %s is blocked: this variable can subvert sandbox containment", key)
+				}
+				if hasValue {
+					extraEnv = append(extraEnv, e)
+				} else if val, found := os.LookupEnv(e); found {
+					extraEnv = append(extraEnv, e+"="+val)
+				}
+			}
+
 			launchCfg := sandbox.StandaloneLaunchConfig{
 				Ctx:          ctx,
 				Command:      command,
 				Workspace:    workspace,
 				Strict:       useStrict,
+				BestEffort:   useBestEffort,
+				ExtraEnv:     extraEnv,
 				ProxyHandler: proxyHandler,
 			}
 
@@ -164,6 +195,8 @@ Examples:
 	cmd.Flags().StringVar(&workspace, "workspace", "", "sandbox workspace directory (default: current directory)")
 	cmd.Flags().StringVarP(&configFile, "config", "c", "", "config file path")
 	cmd.Flags().BoolVar(&strict, "strict", false, "strict mode: error if any containment layer is unavailable, mount private /dev/shm, block clone3")
+	cmd.Flags().BoolVar(&bestEffort, "best-effort", false, "degrade gracefully when namespace isolation is unavailable (e.g. inside containers)")
+	cmd.Flags().StringArrayVar(&envVars, "env", nil, "pass environment variable to sandboxed process (KEY or KEY=VALUE, repeatable)")
 	cmd.Flags().BoolVar(&dryRun, "dry-run", false, "check sandbox capabilities without launching (exit 0=capabilities ok, 1=degraded, 2=error)")
 	cmd.Flags().BoolVar(&jsonOutput, "json", false, "output dry-run result as JSON")
 	return cmd

internal/config/config.go

@@ -216,21 +216,23 @@ type FileSentry struct {
 // Sandbox config is startup-only and reload-immutable: changing these
 // values in a config reload has no effect on an already-running sandbox.
 type Sandbox struct {
-	Enabled   bool               `yaml:"enabled"`
-	Strict    bool               `yaml:"strict"`    // error if any containment layer is unavailable
-	Workspace string             `yaml:"workspace"` // agent working dir; resolved to absolute at startup
-	FS        *SandboxFilesystem `yaml:"filesystem"`
+	Enabled    bool               `yaml:"enabled"`
+	Strict     bool               `yaml:"strict"`      // error if any containment layer is unavailable
+	BestEffort bool               `yaml:"best_effort"` // degrade gracefully when namespace isolation unavailable (e.g. containers)
+	Workspace  string             `yaml:"workspace"`   // agent working dir; resolved to absolute at startup
+	FS         *SandboxFilesystem `yaml:"filesystem"`
 }
 
 // AgentSandboxOverride controls per-agent sandbox settings.
 // Nil pointer fields mean "inherit from global sandbox config."
 // Scoped to mcp proxy --agent and agent listeners. pipelock sandbox
 // CLI does not support per-agent resolution.
 type AgentSandboxOverride struct {
-	Enabled   *bool              `yaml:"enabled,omitempty"`
-	Strict    *bool              `yaml:"strict,omitempty"`
-	Workspace string             `yaml:"workspace,omitempty"`
-	FS        *SandboxFilesystem `yaml:"filesystem,omitempty"`
+	Enabled    *bool              `yaml:"enabled,omitempty"`
+	Strict     *bool              `yaml:"strict,omitempty"`
+	BestEffort *bool              `yaml:"best_effort,omitempty"`
+	Workspace  string             `yaml:"workspace,omitempty"`
+	FS         *SandboxFilesystem `yaml:"filesystem,omitempty"`
 }
 
 // SandboxFilesystem overrides the default Landlock policy. If nil, the
@@ -2408,6 +2410,11 @@ func (c *Config) Validate() error {
 		}
 	}
 
+	// Sandbox: best_effort and strict are mutually exclusive.
+	if c.Sandbox.BestEffort && c.Sandbox.Strict {
+		return fmt.Errorf("sandbox: best_effort and strict are mutually exclusive")
+	}
+
 	// Sandbox: validate filesystem paths even when disabled (CLI can override enabled).
 	if c.Sandbox.FS != nil {
 		for _, p := range c.Sandbox.FS.AllowRead {
@@ -2804,6 +2811,9 @@ func sandboxChanged(old, updated *Config) bool {
 	if old.Sandbox.Strict != updated.Sandbox.Strict {
 		return true
 	}
+	if old.Sandbox.BestEffort != updated.Sandbox.BestEffort {
+		return true
+	}
 	if old.Sandbox.Workspace != updated.Sandbox.Workspace {
 		return true
 	}
@@ -2855,7 +2865,7 @@ func agentSandboxChanged(old, updated *AgentSandboxOverride) bool {
 	if old == nil {
 		return false
 	}
-	if !boolPtrEqual(old.Enabled, updated.Enabled) || !boolPtrEqual(old.Strict, updated.Strict) {
+	if !boolPtrEqual(old.Enabled, updated.Enabled) || !boolPtrEqual(old.Strict, updated.Strict) || !boolPtrEqual(old.BestEffort, updated.BestEffort) {
 		return true
 	}
 	if old.Workspace != updated.Workspace {