feat(cli): --allow-path / --allow-read-path for per-session filesystem grants (#100)

* feat(cli): --allow-path / --allow-read-path for per-session filesystem grants

Add two repeatable flags that grant filesystem access to an extra
directory or file for a single session, without authoring a profile:

  --allow-path       read+write (appended to AllowRead + AllowWrite)
  --allow-read-path  read-only  (appended to AllowRead only)

Both accept a directory or a file and reuse the existing per-session
AllowRead/AllowWrite plumbing, so they work on Linux (bubblewrap +
Landlock) and macOS (Seatbelt) with no sandbox-layer changes. Grants
are applied after profile merge and watch overrides, and nothing is
persisted. Non-existent paths are tolerated, matching --allow.

Tests: unit test for the flag-merge helper, macOS Seatbelt rule test
(rw vs read-only, incl. a file case), Linux bind-mount test, and smoke
tests covering write-allowed, read-only (write denied), and a negative
control.

* fix(linux): correct session allow-path test + extract writableBindArgs

The Linux test asserted buildDenyByDefaultMounts emits a writable --bind for
--allow-path, but that function only does read-only binds; the writable --bind
for AllowWrite lives in WrapCommandLinuxWithOptions. Extract that inline logic
into writableBindArgs so the test can verify both layers (read --ro-bind for
all grants, writable --bind only for --allow-path). Also fix gosec G301 by
tightening test dir perms to 0o750.

* docs(readme): document --allow-path / --allow-read-path session grants

* docs(readme): show --allow-path / --allow-read-path in basic commands

Author: tito

README.md

@@ -124,6 +124,10 @@ greywall --proxy socks5://localhost:1080 -- npm install
 # Expose a port for inbound connections (e.g., dev servers)
 greywall -p 3000 -c "npm run dev"
 
+# Grant an extra directory/file for this run (read+write, or read-only)
+greywall --allow-path /tmp/work -- mytool
+greywall --allow-read-path /data/refs -- mytool
+
 # Enable debug logging
 greywall -d -- curl https://example.com
 

cmd/greywall/main.go

@@ -55,6 +55,8 @@ var (
 	ignoreVars             []string
 	skipVersionCheck       bool
 	allowDests             []string
+	allowPaths             []string
+	allowReadPaths         []string
 	blankProfile           bool
 	watch                  bool
 )
@@ -99,6 +101,8 @@ Examples:
   greywall -p 3000 -c "npm run dev"                             # Expose port 3000
   greywall -f 5432 -- psql -h localhost                          # Forward host port into sandbox
   greywall --learning -- opencode                                # Learn filesystem needs
+  greywall --allow-path /tmp/work -- mytool      # Grant rw to an extra dir/file for this run
+  greywall --allow-read-path /data/refs -- mytool # Grant read-only to a dir/file for this run
   greywall --secret MY_VAR -- command            # Protect a custom env var
   greywall --inject ANTHROPIC_API_KEY -- command  # Inject from proxy dashboard
 
@@ -146,6 +150,8 @@ Configuration file format:
 	rootCmd.Flags().BoolVar(&skipVersionCheck, "skip-version-check", false, "Skip greyproxy version check (for testing)")
 	_ = rootCmd.Flags().MarkHidden("skip-version-check")
 	rootCmd.Flags().StringArrayVar(&allowDests, "allow", nil, "Allow a network destination for this session (e.g. --allow api.example.com:443)")
+	rootCmd.Flags().StringArrayVar(&allowPaths, "allow-path", nil, "Allow read+write access to a directory or file for this session (repeatable, e.g. --allow-path /tmp/work)")
+	rootCmd.Flags().StringArrayVar(&allowReadPaths, "allow-read-path", nil, "Allow read-only access to a directory or file for this session (repeatable, e.g. --allow-read-path /data/refs)")
 	rootCmd.Flags().BoolVar(&blankProfile, "blank", false, "With --learning, skip default profile network rules (start from scratch)")
 	rootCmd.Flags().BoolVar(&watch, "watch", false, "Watch mode: skip profile loading, allow all network (logged on dashboard), permissive filesystem — observability only, no deny-by-default")
 
@@ -409,6 +415,16 @@ func runCommand(cmd *cobra.Command, args []string) error {
 		fmt.Fprintf(os.Stderr, "[greywall] Watch mode: no profile, all network allowed (logged on dashboard), permissive filesystem\n")
 	}
 
+	// Session-scoped filesystem grants from --allow-path / --allow-read-path.
+	// Applied after profile merge and watch overrides so they always take effect.
+	// Nothing is persisted; the sandbox resolves and binds these paths for this
+	// run only. Non-existent paths are tolerated (Linux skips them, macOS Seatbelt
+	// ignores them), matching the lenient behaviour of --allow.
+	applySessionAllowPaths(cfg, allowPaths, allowReadPaths)
+	if debug && (len(allowPaths) > 0 || len(allowReadPaths) > 0) {
+		fmt.Fprintf(os.Stderr, "[greywall] Session allow: %d rw, %d read-only path(s)\n", len(allowPaths), len(allowReadPaths))
+	}
+
 	// Learning mode setup
 	if learning {
 		if err := sandbox.CheckLearningAvailable(); err != nil {
@@ -1428,6 +1444,21 @@ parseCommand:
 	}
 }
 
+// applySessionAllowPaths grants session-scoped filesystem access from the
+// --allow-path (read+write) and --allow-read-path (read-only) CLI flags.
+// Read-write paths are appended to both AllowRead and AllowWrite; read-only
+// paths are appended to AllowRead only. The underlying sandbox plumbing
+// (NormalizePath + per-platform binding) handles directories and files alike.
+func applySessionAllowPaths(cfg *config.Config, rwPaths, roPaths []string) {
+	if len(roPaths) > 0 {
+		cfg.Filesystem.AllowRead = append(cfg.Filesystem.AllowRead, roPaths...)
+	}
+	if len(rwPaths) > 0 {
+		cfg.Filesystem.AllowRead = append(cfg.Filesystem.AllowRead, rwPaths...)
+		cfg.Filesystem.AllowWrite = append(cfg.Filesystem.AllowWrite, rwPaths...)
+	}
+}
+
 // mergeUnique combines two string slices, removing duplicates while preserving order.
 func mergeUnique(a, b []string) []string {
 	if len(a) == 0 {

cmd/greywall/main_test.go

@@ -1,7 +1,85 @@
 // Package main implements the greywall CLI.
 package main
 
-import "testing"
+import (
+	"slices"
+	"testing"
+
+	"github.com/GreyhavenHQ/greywall/internal/config"
+)
+
+// TestApplySessionAllowPaths verifies that --allow-path grants read+write while
+// --allow-read-path grants read-only, both appended to the session config.
+func TestApplySessionAllowPaths(t *testing.T) {
+	tests := []struct {
+		name      string
+		rwPaths   []string
+		roPaths   []string
+		baseRead  []string
+		baseWrite []string
+		wantRead  []string
+		wantWrite []string
+	}{
+		{
+			name:      "no flags leaves config untouched",
+			wantRead:  nil,
+			wantWrite: nil,
+		},
+		{
+			name:      "allow-path adds to both read and write",
+			rwPaths:   []string{"/tmp/work"},
+			wantRead:  []string{"/tmp/work"},
+			wantWrite: []string{"/tmp/work"},
+		},
+		{
+			name:      "allow-read-path adds to read only",
+			roPaths:   []string{"/data/refs"},
+			wantRead:  []string{"/data/refs"},
+			wantWrite: nil,
+		},
+		{
+			name:      "both flags combine: rw in both, ro in read only",
+			rwPaths:   []string{"/tmp/out"},
+			roPaths:   []string{"/data/refs", "/data/reference.csv"},
+			wantRead:  []string{"/data/refs", "/data/reference.csv", "/tmp/out"},
+			wantWrite: []string{"/tmp/out"},
+		},
+		{
+			name:      "appends to existing config paths",
+			rwPaths:   []string{"/tmp/work"},
+			baseRead:  []string{"/existing/read"},
+			baseWrite: []string{"/existing/write"},
+			wantRead:  []string{"/existing/read", "/tmp/work"},
+			wantWrite: []string{"/existing/write", "/tmp/work"},
+		},
+		{
+			name:      "multiple rw paths repeatable",
+			rwPaths:   []string{"/tmp/a", "/tmp/b"},
+			wantRead:  []string{"/tmp/a", "/tmp/b"},
+			wantWrite: []string{"/tmp/a", "/tmp/b"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cfg := &config.Config{
+				Filesystem: config.FilesystemConfig{
+					AllowRead:  tt.baseRead,
+					AllowWrite: tt.baseWrite,
+				},
+			}
+
+			applySessionAllowPaths(cfg, tt.rwPaths, tt.roPaths)
+
+			if !slices.Equal(cfg.Filesystem.AllowRead, tt.wantRead) {
+				t.Errorf("AllowRead = %v, want %v", cfg.Filesystem.AllowRead, tt.wantRead)
+			}
+			if !slices.Equal(cfg.Filesystem.AllowWrite, tt.wantWrite) {
+				t.Errorf("AllowWrite = %v, want %v", cfg.Filesystem.AllowWrite, tt.wantWrite)
+			}
+		})
+	}
+}
 
 // TestProxyIdentity is the regression test for #96. The greyproxy session
 // container name and the SOCKS5 login are both derived from proxyIdentity, so

docs/cli-reference.md

@@ -29,6 +29,8 @@ greywall <subcommand> [args...]
 | `--debug` | `-d` | Verbose output: proxy activity, filter decisions, sandbox command |
 | `--monitor` | `-m` | Show only violations and blocked requests (audit mode) |
 | `--learning` | | Trace filesystem access with strace/eslogger and auto-generate a profile |
+| `--allow-path <path>` | | Grant read+write access to a directory **or** file for this session only (repeatable). Nothing is persisted. See [below](#--allow-path-and---allow-read-path). |
+| `--allow-read-path <path>` | | Grant read-only access to a directory **or** file for this session only (repeatable). Nothing is persisted. |
 | `--secret <VAR>` | | Treat an environment variable as a credential even if it doesn't match the auto-detection rules (repeatable). See [Credential Protection](./credential-protection). |
 | `--inject <LABEL>` | | Inject a credential stored in the greyproxy dashboard into the sandbox by label (repeatable) |
 | `--ignore-secret <VAR>` | | Exclude a variable from credential detection even if it matches the heuristics (repeatable) |
@@ -74,6 +76,31 @@ greywall -f 5432 -f 6379 -- make test
 
 See [Concepts](./concepts#port-forwarding-platform-differences) for the full explanation of the platform difference.
 
+### `--allow-path` and `--allow-read-path`
+
+Greywall is deny-by-default for the filesystem: a sandboxed command can only touch the current working directory (plus system paths). When you just need one extra directory or file for a single run — a scratch/temp dir, a sibling project, a reference dataset — these flags grant it **for that session only**. Nothing is written to disk and no profile is created or modified; for a persistent grant, use `filesystem.allowRead` / `filesystem.allowWrite` in your [config](./configuration).
+
+- `--allow-path` grants **read+write**.
+- `--allow-read-path` grants **read-only** (writes stay blocked).
+
+Both are repeatable and accept either a **directory or a file**. Paths may be absolute, relative (resolved against the CWD), or `~`-prefixed.
+
+```bash
+# Read+write scratch directory for this run
+greywall --allow-path /tmp/work -- mytool
+
+# Several extra paths at once
+greywall --allow-path /tmp/work --allow-path ~/.cache/foo -- mytool
+
+# Read-only reference data (a single file here); writes to it are denied
+greywall --allow-read-path /data/reference.csv -- mytool
+
+# Mix: read-only inputs, read+write output
+greywall --allow-read-path /data/refs --allow-path /tmp/out -- mytool
+```
+
+These compose with profiles — they are added on top of whatever a profile already allows.
+
 ## Subcommands
 
 ### `greywall check`

internal/sandbox/linux.go

@@ -1006,6 +1006,49 @@ func buildDenyByDefaultMounts(cfg *config.Config, cwd string, dbusBridge *DbusBr
 	return args
 }
 
+// writableBindArgs returns bwrap --bind args that make the configured writable
+// paths actually writable, overriding the read-only root. It covers the default
+// system write paths plus cfg.Filesystem.AllowWrite (which includes the
+// read+write grants from --allow-path). These binds are appended after the
+// read-only binds from buildDenyByDefaultMounts, so for a path that is both
+// readable and writable the later --bind wins. Only existing paths are bound;
+// bwrap rejects a missing source.
+func writableBindArgs(cfg *config.Config) []string {
+	writablePaths := make(map[string]bool)
+
+	// Default write paths (system paths needed for operation).
+	for _, p := range GetDefaultWritePaths() {
+		// Skip /dev paths (handled by --dev) and /tmp paths (handled by --tmpfs).
+		if strings.HasPrefix(p, "/dev/") || strings.HasPrefix(p, "/tmp/") || strings.HasPrefix(p, "/private/tmp/") {
+			continue
+		}
+		writablePaths[p] = true
+	}
+
+	// User-specified allowWrite paths.
+	if cfg != nil && cfg.Filesystem.AllowWrite != nil {
+		for _, p := range ExpandGlobPatterns(cfg.Filesystem.AllowWrite) {
+			writablePaths[p] = true
+		}
+
+		// Non-glob paths, normalized.
+		for _, p := range cfg.Filesystem.AllowWrite {
+			normalized := NormalizePath(p)
+			if !ContainsGlobChars(normalized) {
+				writablePaths[normalized] = true
+			}
+		}
+	}
+
+	var args []string
+	for p := range writablePaths {
+		if fileExists(p) {
+			args = append(args, "--bind", p, p)
+		}
+	}
+	return args
+}
+
 // isSystemMountPoint returns true if the path is a top-level system directory
 // that gets mounted directly under --tmpfs / (bwrap auto-creates these).
 func isSystemMountPoint(path string) bool {
@@ -1171,39 +1214,8 @@ func WrapCommandLinuxWithOptions(cfg *config.Config, command string, proxyBridge
 	// deny (the sandbox is already permissive with home + cwd writable).
 	if !opts.Learning && !opts.Watch {
 
-		writablePaths := make(map[string]bool)
-
-		// Add default write paths (system paths needed for operation)
-		for _, p := range GetDefaultWritePaths() {
-			// Skip /dev paths (handled by --dev) and /tmp paths (handled by --tmpfs)
-			if strings.HasPrefix(p, "/dev/") || strings.HasPrefix(p, "/tmp/") || strings.HasPrefix(p, "/private/tmp/") {
-				continue
-			}
-			writablePaths[p] = true
-		}
-
-		// Add user-specified allowWrite paths
-		if cfg != nil && cfg.Filesystem.AllowWrite != nil {
-			expandedPaths := ExpandGlobPatterns(cfg.Filesystem.AllowWrite)
-			for _, p := range expandedPaths {
-				writablePaths[p] = true
-			}
-
-			// Add non-glob paths
-			for _, p := range cfg.Filesystem.AllowWrite {
-				normalized := NormalizePath(p)
-				if !ContainsGlobChars(normalized) {
-					writablePaths[normalized] = true
-				}
-			}
-		}
-
 		// Make writable paths actually writable (override read-only root)
-		for p := range writablePaths {
-			if fileExists(p) {
-				bwrapArgs = append(bwrapArgs, "--bind", p, p)
-			}
-		}
+		bwrapArgs = append(bwrapArgs, writableBindArgs(cfg)...)
 
 		// Handle denyRead paths - hide them
 		// For directories: use --tmpfs to replace with empty tmpfs

internal/sandbox/macos_test.go

@@ -440,6 +440,48 @@ func TestMacOS_DenyReadUserPaths(t *testing.T) {
 	}
 }
 
+// TestMacOS_SessionAllowPaths verifies the Seatbelt profile distinguishes
+// read+write grants (--allow-path) from read-only grants (--allow-read-path):
+// a read-write path gets both a read-data and a file-write* allow, while a
+// read-only path gets a read-data allow but NO file-write* allow. Covers both
+// a directory and a single file (the file case must not get a write rule).
+func TestMacOS_SessionAllowPaths(t *testing.T) {
+	rwDir := "/home/user/scratch"
+	roDir := "/home/user/reference"
+	roFile := "/home/user/reference.csv"
+
+	params := MacOSSandboxParams{
+		Command:         "echo test",
+		DefaultDenyRead: true,
+		Cwd:             "/home/user/project",
+		// --allow-path appends to both read and write; --allow-read-path to read only.
+		ReadAllowPaths:  []string{roDir, roFile, rwDir},
+		WriteAllowPaths: []string{rwDir},
+	}
+
+	profile := GenerateSandboxProfile(params)
+
+	// Read-write path: present as both a read allow and a write allow.
+	if !strings.Contains(profile, fmt.Sprintf(`(subpath %q)`, rwDir)) {
+		t.Errorf("rw path %q missing read allow\nProfile:\n%s", rwDir, profile)
+	}
+	wantWrite := fmt.Sprintf("(allow file-write*\n  (subpath %q)", rwDir)
+	if !strings.Contains(profile, wantWrite) {
+		t.Errorf("rw path %q missing file-write* allow\nExpected: %s\nProfile:\n%s", rwDir, wantWrite, profile)
+	}
+
+	// Read-only directory and file: read allow present, write allow absent.
+	for _, ro := range []string{roDir, roFile} {
+		if !strings.Contains(profile, fmt.Sprintf(`(subpath %q)`, ro)) {
+			t.Errorf("read-only path %q missing read allow\nProfile:\n%s", ro, profile)
+		}
+		unwantedWrite := fmt.Sprintf("(allow file-write*\n  (subpath %q)", ro)
+		if strings.Contains(profile, unwantedWrite) {
+			t.Errorf("read-only path %q must NOT have a file-write* allow\nProfile:\n%s", ro, profile)
+		}
+	}
+}
+
 // TestExpandMacOSTmpPaths verifies that /tmp and /private/tmp paths are properly mirrored.
 func TestExpandMacOSTmpPaths(t *testing.T) {
 	tests := []struct {