feat: add allow_exec_sugid config option for setuid binary execution (#26)

* feat: add allow_exec_sugid config option (#22)

Add opt-in execution of setuid/setgid binaries for MCP server support.
Resolves forbidden-exec-sugid violations while maintaining secure deny-by-default.

- New ExecSugid enum: Allow(bool) or Paths(Vec<String>)
- Config field with TOML syntax: false (deny), true (allow all), ["/bin/ps"]
- Profile composing with last-wins/paths-union merge semantics
- Config merge: project overrides global, paths are unioned
- CLI flag --allow-exec-sugid PATH (repeatable, path-based only)
- Seatbelt rule generation with path validation
- explain command shows sugid status; init template includes example
- 27 new tests across schema, seatbelt, config, profile, and CLI

* fix(explain): show deny for empty exec_sugid paths list

* docs: add allow_exec_sugid configuration and usage guide

- Add allow_exec_sugid examples to global and project config templates
- Document three modes: deny (default), allow all, allow specific paths
- Add CLI flag usage and merge semantics explanation
- Update PROFILES.md with custom profile example and merge rules
- Add SECURITY.md section explaining deny-by-default behavior and seatbelt rules
- Update generated seatbelt profile example with sugid rule example

* style: format code with cargo fmt

Author: Pierozi

CLAUDE.md

@@ -1,75 +1,5 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
 `sx` (sandbox-shell) is a Rust CLI that wraps shell sessions and commands in macOS Seatbelt sandboxes. It protects developers from malicious code in npm packages, untrusted repositories, and build scripts by restricting filesystem and network access.
 
-## Development Commands
-
-```bash
-# Build
-cargo build              # Debug build
-cargo build --release    # Release build (with LTO)
-
-# Test
-cargo test               # Run all tests
-cargo test test_name     # Run specific test
-cargo test --test cli_test  # Run specific integration test file
-
-# Run from source
-cargo run -- --help
-cargo run -- echo "test"
-cargo run -- --dry-run online node  # Preview seatbelt profile
-```
-
-## Architecture
-
-The codebase follows a layered architecture with clear separation of concerns:
-
-```
-src/
-├── main.rs         # Binary entry point: calls sx::run()
-├── lib.rs          # Library entry point: parses args, dispatches to commands
-├── cli/
-│   ├── args.rs     # Clap argument definitions
-│   └── commands.rs # Command implementations (init, explain, dry_run, execute)
-├── config/
-│   ├── schema.rs   # Core types: Config, NetworkMode, FilesystemConfig
-│   ├── profile.rs  # Profile system: builtin profiles (base, rust, claude, etc.)
-│   ├── global.rs   # Global config loading (~/.config/sx/config.toml)
-│   ├── project.rs  # Project config loading (.sandbox.toml)
-│   └── merge.rs    # Config/profile merging logic
-├── sandbox/
-│   ├── seatbelt.rs # Seatbelt profile generation (the core sandbox logic)
-│   ├── executor.rs # sandbox-exec invocation
-│   ├── trace.rs    # Real-time violation streaming via macOS `log stream`
-│   └── violations.rs # Violation parsing and log file handling
-├── detection/
-│   └── project_type.rs  # Auto-detect project type from marker files
-├── shell/
-│   ├── integration.rs   # Shell prompt/completion support
-│   └── prompt.rs        # Prompt indicator formatting with ANSI colors
-└── utils/
-    └── paths.rs    # Path expansion (~, environment variables)
-```
-
-### Key Data Flow
-
-1. **CLI args** (`cli/args.rs`) → parsed by Clap
-2. **Config loading** (`config/`) → global + project configs merged
-3. **Profile composition** (`config/profile.rs`) → profiles stacked (base + rust + online, etc.)
-4. **Seatbelt generation** (`sandbox/seatbelt.rs`) → generates macOS sandbox-exec profile
-5. **Execution** (`sandbox/executor.rs`) → spawns `sandbox-exec -f profile.sb command`
-
-### Security Model
-
-The sandbox uses a **deny-by-default** approach:
-- **Reads**: Denied by default, only explicit `allow_read` paths are accessible (system paths like `/usr`, `/bin`, `/Library`, `/System`)
-- **Writes**: Denied by default, allowed only for working directory + explicit `allow_write` paths
-- **Network**: Configurable (offline/localhost/online)
-
 **Critical Seatbelt Rules**:
 1. Root literal `(allow file-read* (literal "/"))` is required for path traversal - processes need to read `/` to resolve paths
 2. Seatbelt uses last-match-wins semantics when rules have matching filter types - deny rules after allow rules take precedence for nested paths (e.g., allow `/home` then deny `/home/.ssh`)
@@ -78,14 +8,6 @@ The sandbox uses a **deny-by-default** approach:
 **Configuration Options**:
 - `inherit_base = false` in `.sandbox.toml` skips the base profile for full custom control over allowed paths
 
-### Profile System
-
-Profiles are composable configurations that stack on top of each other. Order matters - later profiles override network mode but merge filesystem paths.
-
-Built-in profiles: `base`, `online`, `localhost`, `rust`, `claude`, `gpg`
-
-Custom profiles can be added to `~/.config/sx/profiles/name.toml`.
-
 ## Programming Rules
 
 Produce code following **LEAN, CLEAN, MINIMAL but thoughtful KISS & YAGNI principle**.

docs/CONFIGURATION.md

@@ -13,6 +13,7 @@ default_profiles = ["base"]      # always include these
 shell = "/bin/zsh"               # shell inside sandbox
 prompt_indicator = true          # show [sx:mode] in prompt
 inherit_base = true              # include base profile
+# allow_exec_sugid = ["/bin/ps"] # allow specific setuid/setgid binaries
 
 [filesystem]
 allow_read = [
@@ -49,6 +50,7 @@ profiles = ["rust"]              # profiles for this project
 network = "localhost"            # override network mode
 inherit_global = true            # inherit from global config
 inherit_base = true              # include base profile (false for full custom)
+# allow_exec_sugid = ["/bin/ps"] # allow specific setuid/setgid binaries
 
 [filesystem]
 allow_read = ["./vendor"]
@@ -78,6 +80,32 @@ pass_env = ["MYPROJECT_TOKEN"]
 
 Use with `sx myproject -- command`.
 
+## Setuid/Setgid Execution
+
+Some binaries like `/bin/ps` are setuid/setgid. Seatbelt blocks these by default with `forbidden-exec-sugid`. Use `allow_exec_sugid` to opt in.
+
+Three modes:
+
+| Value | Effect |
+|-------|--------|
+| `false` (default) | Deny all setuid/setgid execution |
+| `true` | Allow all setuid/setgid execution |
+| `["/bin/ps"]` | Allow only listed binaries |
+
+```toml
+# .sandbox.toml
+[sandbox]
+allow_exec_sugid = ["/bin/ps", "/usr/bin/newgrp"]
+```
+
+CLI flag (repeatable, path-based only):
+
+```bash
+sx --allow-exec-sugid /bin/ps --allow-exec-sugid /usr/bin/newgrp -- ps aux
+```
+
+**Merge semantics:** when both global and project configs specify path lists, paths are unioned. Otherwise project overrides global.
+
 ## Precedence
 
 1. CLI flags (highest)

docs/PROFILES.md

@@ -100,6 +100,7 @@ Create in `~/.config/sx/profiles/`:
 ```toml
 # ~/.config/sx/profiles/mycompany.toml
 network_mode = "online"
+allow_exec_sugid = ["/bin/ps"]  # allow specific setuid/setgid binaries
 
 [filesystem]
 allow_read = ["/opt/mycompany"]
@@ -129,3 +130,4 @@ profiles = ["rust", "localhost"]
 1. **Network mode:** last profile with a mode wins
 2. **Filesystem paths:** union (no duplicates)
 3. **Env vars:** union of pass/deny lists
+4. **Exec sugid:** path lists are unioned; mixing paths and booleans → last wins

docs/SECURITY.md

@@ -52,6 +52,20 @@ Everything else (`~/.config/gh`, `~/.netrc`, `~/.gnupg`…) is blocked by deny-b
 
 Even with `online`, your credentials can't be read. Can't exfiltrate what you can't see.
 
+### Setuid/Setgid Execution
+
+Setuid/setgid binaries (e.g., `/bin/ps`, `/usr/bin/newgrp`) are denied by default. Seatbelt raises `forbidden-exec-sugid` when a sandboxed process tries to execute one.
+
+Opt in selectively via `allow_exec_sugid`:
+
+| Mode | Seatbelt rule |
+|------|---------------|
+| Deny (default) | No rule — blocked by `(deny default)` |
+| Allow all | `(allow process-exec* (with no-sandbox))` |
+| Specific paths | `(allow process-exec (with no-sandbox) (literal "/bin/ps"))` |
+
+Paths are validated against injection attacks (no quotes, newlines, or null bytes).
+
 ### Environment Sanitization
 
 Blocked by default:
@@ -71,6 +85,10 @@ Blocked by default:
 (allow process-exec)
 (allow signal (target self))
 
+; Setuid/setgid execution denied (default)
+; Or, if allow_exec_sugid = ["/bin/ps"]:
+; (allow process-exec (with no-sandbox) (literal "/bin/ps"))
+
 ; Required for path resolution
 (allow file-read* (literal "/"))
 (allow file-read-metadata)  ; Required for DNS resolution

src/cli/args.rs

@@ -83,6 +83,10 @@ pub struct Args {
     #[arg(long = "deny-read", value_name = "PATH")]
     pub deny_read: Vec<String>,
 
+    /// Allow execution of setuid/setgid binary at PATH (e.g., /bin/ps)
+    #[arg(long = "allow-exec-sugid", value_name = "PATH")]
+    pub allow_exec_sugid: Vec<String>,
+
     /// Profiles to apply (e.g., online, rust, claude)
     #[arg(value_name = "PROFILES")]
     pub profiles: Vec<String>,

src/cli/commands.rs

@@ -9,8 +9,8 @@ use std::path::{Path, PathBuf};
 use super::args::Args;
 use crate::config::project::{load_project_config, PROJECT_CONFIG_NAME};
 use crate::config::{
-    compose_profiles, load_global_config, load_profiles, merge_configs, Config, NetworkMode,
-    Profile,
+    compose_profiles, load_global_config, load_profiles, merge_configs, Config, ExecSugid,
+    NetworkMode, Profile,
 };
 use crate::detection::project_type::detect_project_types;
 use crate::sandbox::executor::execute_sandboxed_with_trace;
@@ -44,6 +44,19 @@ pub fn explain(args: &Args) -> Result<()> {
     println!("Network Mode: {:?}", context.params.network_mode);
     println!();
 
+    // Exec sugid
+    match &context.params.allow_exec_sugid {
+        ExecSugid::Allow(true) => println!("Setuid/Setgid Execution: ALLOW ALL"),
+        ExecSugid::Paths(paths) if !paths.is_empty() => {
+            println!("Setuid/Setgid Execution: specific binaries");
+            for path in paths {
+                println!("  + {}", path);
+            }
+        }
+        _ => println!("Setuid/Setgid Execution: denied (default)"),
+    }
+    println!();
+
     // Working directory
     println!("Working Directory (full access):");
     println!("  {}", context.params.working_dir.display());
@@ -275,6 +288,9 @@ fn build_sandbox_params(
     // Determine network mode (CLI > profile > config)
     let network_mode = determine_network_mode(args, profile, config);
 
+    // Determine exec sugid policy (CLI > profile > config)
+    let allow_exec_sugid = determine_exec_sugid(args, profile, config);
+
     // Collect paths with expansions
     let mut allow_read = collect_allow_read_paths(config, profile, &args.allow_read);
     let mut deny_read = collect_deny_read_paths(config, profile, &args.deny_read);
@@ -324,6 +340,7 @@ fn build_sandbox_params(
         allow_write: allow_write.into_iter().map(PathBuf::from).collect(),
         allow_list_dirs: allow_list_dirs.into_iter().map(PathBuf::from).collect(),
         raw_rules,
+        allow_exec_sugid,
     }
 }
 
@@ -346,6 +363,22 @@ fn determine_network_mode(args: &Args, profile: &Profile, config: &Config) -> Ne
         .unwrap_or(config.sandbox.default_network)
 }
 
+/// Determine exec sugid policy with precedence: CLI > profile > config
+fn determine_exec_sugid(args: &Args, profile: &Profile, config: &Config) -> ExecSugid {
+    // CLI paths take highest precedence
+    if !args.allow_exec_sugid.is_empty() {
+        return ExecSugid::Paths(args.allow_exec_sugid.clone());
+    }
+
+    // Profile setting
+    if let Some(sugid) = &profile.allow_exec_sugid {
+        return sugid.clone();
+    }
+
+    // Config setting
+    config.sandbox.allow_exec_sugid.clone()
+}
+
 /// Collect allow-read paths from config, profile, and CLI
 fn collect_allow_read_paths(config: &Config, profile: &Profile, cli: &[String]) -> Vec<String> {
     let mut paths = Vec::new();
@@ -398,6 +431,10 @@ profiles = []
 # Default network mode: "offline", "online", or "localhost"
 # network = "offline"
 
+# Allow execution of setuid/setgid binaries (default: false)
+# false = deny all, true = allow all, or list specific paths
+# allow_exec_sugid = ["/bin/ps"]
+
 [filesystem]
 # Additional paths this project needs to read
 allow_read = []

src/config/merge.rs

@@ -1,4 +1,4 @@
-use super::schema::{Config, FilesystemConfig, SandboxConfig, ShellConfig};
+use super::schema::{Config, ExecSugid, FilesystemConfig, SandboxConfig, ShellConfig};
 use std::collections::HashSet;
 
 /// Merge two configurations, with project taking precedence
@@ -47,6 +47,19 @@ fn merge_sandbox(global: &SandboxConfig, project: &SandboxConfig) -> SandboxConf
         // Merge profiles (using pre-filtered global_profiles)
         profiles: merge_unique_strings(&global_profiles, &project.profiles),
         network: project.network,
+        allow_exec_sugid: merge_exec_sugid(&global.allow_exec_sugid, &project.allow_exec_sugid),
+    }
+}
+
+/// Merge ExecSugid: if both are Paths, union-merge; otherwise project overrides global.
+fn merge_exec_sugid(global: &ExecSugid, project: &ExecSugid) -> ExecSugid {
+    // If project is default (deny all), keep global
+    if project.is_default() && !global.is_default() {
+        return global.clone();
+    }
+    match (global, project) {
+        (ExecSugid::Paths(g), ExecSugid::Paths(p)) => ExecSugid::Paths(merge_unique_strings(g, p)),
+        _ => project.clone(),
     }
 }
 

src/config/mod.rs

@@ -11,4 +11,4 @@ pub use profile::{
     ProfileFilesystem, ProfileShell,
 };
 pub use project::load_project_config;
-pub use schema::{Config, NetworkMode};
+pub use schema::{Config, ExecSugid, NetworkMode};

src/config/profile.rs

@@ -1,4 +1,4 @@
-use crate::config::schema::NetworkMode;
+use crate::config::schema::{ExecSugid, NetworkMode};
 use serde::{Deserialize, Serialize};
 use std::collections::HashSet;
 use std::path::Path;
@@ -64,6 +64,9 @@ pub struct Profile {
     /// Raw seatbelt rules (advanced)
     #[serde(default)]
     pub seatbelt: Option<ProfileSeatbelt>,
+    /// Allow execution of setuid/setgid binaries
+    #[serde(default)]
+    pub allow_exec_sugid: Option<ExecSugid>,
 }
 
 /// Profile filesystem configuration
@@ -275,6 +278,25 @@ pub fn compose_profiles(profiles: &[Profile]) -> Profile {
         // Shell: merge unique env vars
         merge_unique(&mut result.shell.pass_env, &profile.shell.pass_env);
         merge_unique(&mut result.shell.deny_env, &profile.shell.deny_env);
+
+        // ExecSugid: Paths union-merge, otherwise last-set wins
+        if let Some(incoming) = &profile.allow_exec_sugid {
+            match (&result.allow_exec_sugid, incoming) {
+                (Some(ExecSugid::Paths(existing)), ExecSugid::Paths(new)) => {
+                    let mut merged = existing.clone();
+                    let existing_set: HashSet<&str> = existing.iter().map(|s| s.as_str()).collect();
+                    for path in new {
+                        if !existing_set.contains(path.as_str()) {
+                            merged.push(path.clone());
+                        }
+                    }
+                    result.allow_exec_sugid = Some(ExecSugid::Paths(merged));
+                }
+                _ => {
+                    result.allow_exec_sugid = Some(incoming.clone());
+                }
+            }
+        }
     }
 
     result