feat(security): scanner-flow parity under sandbox isolation (MCP-34.4)

D3 option (b) from the MCP-34 spike: clean, surfaced degradation. Under a
non-Docker isolation mode (sandbox/none) the Docker-based scanner plugins
(Spec 039) cannot run, so the scan engine now skips them with an honest,
mode-specific reason pointing at MCPX_DOCKER_SNAP_APPARMOR instead of the
misleading "pull the image" guidance. The always-on in-process
tpa-descriptions scanner still runs, and the skipped Docker scanners stay in
the resolved set (recorded as failed) so the existing coverage check downgrades
the server's security_scan.status to "degraded" rather than a silent all-clear.

- Engine: new isolationMode gate in resolveScanners/checkImage
- Service: SetIsolationMode setter (+ startup WARN), wired in server.go from
  cfg.DockerIsolation.ResolvedMode()
- Tests: engine skip under sandbox/none + docker-mode back-compat guard +
  service setter propagation
- Docs: rewrite docs/docker-isolation.md to cover all three modes (docker/
  sandbox/none), the snap-docker AppArmor failure mode, the honest uid/gid
  limitation, and a platform support matrix; add sandbox option to the
  MCPX_DOCKER_SNAP_APPARMOR error doc

Co-Authored-By: Paperclip <noreply@paperclip.ing>

Author: Dumbris

docs/docker-isolation.md

@@ -1,6 +1,8 @@
-# Docker Security Isolation
+# Security Isolation (Docker · Sandbox · None)
 
-MCPProxy provides Docker isolation for stdio MCP servers to enhance security by running each server in its own isolated container.
+MCPProxy can confine stdio MCP servers so a malicious or buggy server cannot freely touch the host. There are **three isolation modes** — `docker`, `sandbox`, and `none` — selected by `docker_isolation.mode` (global) or `isolation.mode` (per-server). This document covers all three; most of it describes the **Docker** mode (the default and most capable), with the **Sandbox** mode and the **scanner behaviour under each mode** in [Isolation Modes](#isolation-modes) below.
+
+> **Naming note:** the global config key is still `docker_isolation` for backward compatibility, but its `mode` field selects any of the three modes — it is not Docker-only.
 
 > **New installs:** Docker isolation is turned on automatically when mcpproxy creates its initial `mcp_config.json` and a Docker daemon is reachable (`docker info` responds within 2 seconds). If Docker isn't available at first run, isolation stays off so stdio servers still work — you can enable it later from the **Security** page in the Web UI or by editing the config below.
 >
@@ -26,6 +28,58 @@ Docker isolation automatically wraps stdio-based MCP servers in Docker container
 - **Resource Limits**: Memory and CPU limits prevent resource exhaustion
 - **Automatic Runtime Detection**: Maps commands to appropriate Docker images
 
+## Isolation Modes
+
+MCPProxy resolves an **isolation mode** for every stdio server. Set it globally with `docker_isolation.mode` and override per-server with `isolation.mode`:
+
+| Mode | What it does | Where it works | uid/gid drop |
+|------|--------------|----------------|--------------|
+| `docker` | Wraps the server in a Docker container (process/FS/network isolation, resource limits). The default and most capable mode. | Any host with a working Docker daemon. | Yes (container user) |
+| `sandbox` | Runs the server **natively** under a Linux [Landlock](https://docs.kernel.org/userspace-api/landlock.html) filesystem allowlist + `setrlimit` resource caps — **no Docker required**. For hosts where Docker isolation is unavailable or broken (e.g. snap-docker + AppArmor). | Linux 5.13+ only (Landlock). Best-effort downgrade across ABI 1–5. macOS/Windows: documented no-op ⇒ behaves like `none`. | **No** — see [Honest limitations](#honest-limitations) |
+| `none` | No confinement; the server runs directly on the host. | Everywhere. | n/a |
+
+```json
+{
+  "docker_isolation": {
+    "mode": "sandbox"
+  },
+  "mcpServers": [
+    { "name": "trusted-local", "command": "uvx", "args": ["x"], "isolation": { "mode": "none" } }
+  ]
+}
+```
+
+### Back-compat with the legacy `enabled` flag
+
+The older boolean `docker_isolation.enabled` (and per-server `isolation.enabled`) still works and is mapped to a mode:
+
+- an explicit `mode` always wins;
+- otherwise `enabled: true` ⇒ `docker`, `enabled: false` ⇒ `none`;
+- a missing/`nil` isolation config ⇒ `none`.
+
+Per-server precedence: explicit per-server `mode` → per-server legacy `enabled` → global `mode` → global legacy `enabled`. A per-server `mode` (e.g. `none` for a trusted server) overrides the global gate.
+
+### Sandbox mode (Landlock)
+
+`sandbox` mode confines a stdio server **without Docker** by applying a Linux Landlock LSM ruleset (a writable-path allowlist) plus `setrlimit` resource caps to the process before it `exec`s, then preserving the raw stdin/stdout JSON-RPC pipes. It is unaffected by `kernel.apparmor_restrict_unprivileged_userns=1` (it needs no user namespaces), which is exactly why it works where bubblewrap/userns-based sandboxes are blocked. See the spike write-up in [docs/development/sandbox-spike-mcp-34.md](development/sandbox-spike-mcp-34.md) for the mechanism comparison and PoC.
+
+### Scanner behaviour under each mode (MCP-34.4)
+
+The security **scanner plugins** (Spec 039) are Docker-based. Under a non-Docker isolation mode they cannot run, so MCPProxy **degrades cleanly and surfaces it** rather than failing silently:
+
+| Mode | Docker scanner plugins | In-process scanner (`tpa-descriptions`) | Scan result for a server with only Docker scanners |
+|------|------------------------|------------------------------------------|----------------------------------------------------|
+| `docker` | Run normally | Runs | As scanned |
+| `sandbox` / `none` | **Skipped** with an honest, mode-specific reason pointing at [`MCPX_DOCKER_SNAP_APPARMOR`](errors/MCPX_DOCKER_SNAP_APPARMOR.md) | **Still runs** | `security_scan.status: "degraded"` (a low/zero risk score from incomplete coverage is not reported as a trustworthy all-clear) |
+
+This is **decision D3 option (b)** from the [MCP-34 spike](development/sandbox-spike-mcp-34.md#recommendation-for-the-d3-scanner-question): clean, surfaced degradation. A native (non-Docker) scanner runtime — option (a) — is a larger follow-up and is not yet implemented. To run the full Docker-based scanner fleet, use `mode: docker` on a host with a working Docker daemon, or replace snap-docker with a distro Docker package (see the error doc).
+
+The skip is also logged at startup:
+
+```
+WARN  Isolation mode runs no Docker for scanner plugins; Docker-based scanners will be skipped …  {"isolation_mode": "sandbox"}
+```
+
 ## Configuration
 
 ### Global Docker Isolation
@@ -297,6 +351,34 @@ docker stats
   exists at the bundle path above, or pre-pull the image with
   `docker pull <image>`.
 
+## Snap-docker (AppArmor) failure mode
+
+On Ubuntu hosts where Docker is installed via **snap**, AppArmor's profile transition fights the security flags the scanner sandbox requires (`--security-opt no-new-privileges` + a pinned AppArmor profile), so in-container commands fail with *operation not permitted*. This is the original driver for non-Docker `sandbox` mode. Symptoms, root cause, and fixes are documented in [`docs/errors/MCPX_DOCKER_SNAP_APPARMOR.md`](errors/MCPX_DOCKER_SNAP_APPARMOR.md). The related systemd/snap-confine variant for *upstream* docker servers is detected by `mcpproxy doctor` (issue #457).
+
+Your options on such a host:
+
+1. Replace snap Docker with a distro/upstream Docker package (full Docker mode works).
+2. Set `docker_isolation.mode: "sandbox"` — stdio servers are confined natively with Landlock; Docker-based scanners degrade cleanly (see [Scanner behaviour](#scanner-behaviour-under-each-mode-mcp-344)).
+3. Set `security.scanner_disable_no_new_privileges: true` to drop the `no-new-privileges` flag from scanner containers (weakens scanner hardening; prefer 1 or 2).
+
+## Honest limitations
+
+`sandbox` mode is deliberately scoped. Known limitations:
+
+- **No uid/gid drop.** Dropping to an unprivileged uid/gid requires `CAP_SETUID`/`CAP_SETGID` (i.e. running as root). When mcpproxy runs unprivileged, the uid/gid drop is **best-effort and typically a no-op** — the sandboxed process keeps the launching user's identity. Landlock (filesystem) and `setrlimit` (resource caps) still apply. Docker mode does drop to a container user. This is an honest trade-off, not a bug.
+- **Linux-only.** Landlock is a Linux 5.13+ feature. On older kernels the launcher degrades best-effort (fewer access-right bits enforced on ABI 1). On macOS/Windows `sandbox` is a documented **no-op** and behaves like `none`.
+- **Filesystem + resources only.** Landlock confines the filesystem write-allowlist; it does not provide network namespacing. Pair with care for network-sensitive servers, or use `docker` mode with `network_mode: none`.
+- **Docker-based scanners do not run under `sandbox`/`none`.** They are skipped (the scan reports `degraded`). A native scanner runtime is a future enhancement (D3 option a).
+
+## Platform support matrix
+
+| Platform | `docker` | `sandbox` | `none` | Docker scanner plugins |
+|----------|----------|-----------|--------|------------------------|
+| Linux (kernel ≥ 5.13) | ✅ (needs Docker daemon) | ✅ Landlock + rlimits (no uid/gid drop) | ✅ | ✅ under `docker`; skipped+degraded under `sandbox`/`none` |
+| Linux (kernel < 5.13) | ✅ (needs Docker daemon) | ⚠️ best-effort: rlimits apply, Landlock partial/unavailable | ✅ | same as above |
+| macOS | ✅ (Docker Desktop) | ⚠️ no-op ⇒ effectively `none` | ✅ | ✅ under `docker`; n/a otherwise |
+| Windows | ✅ (Docker Desktop) | ⚠️ no-op ⇒ effectively `none` | ✅ | ✅ under `docker`; n/a otherwise |
+
 ## Security Considerations
 
 Docker isolation provides strong security boundaries but consider:

docs/errors/MCPX_DOCKER_SNAP_APPARMOR.md

@@ -24,7 +24,7 @@ Docker isolation works fine.
 
 ## How to fix
 
-You have three options:
+You have four options:
 
 ### 1. Switch to non-snap Docker (recommended)
 
@@ -34,7 +34,25 @@ sudo snap remove docker
 # https://docs.docker.com/engine/install/ubuntu/
 ```
 
-### 2. Disable the scanner for this server (dry-run shown by default)
+### 2. Use native `sandbox` isolation instead of Docker (no Docker daemon needed)
+
+If the real goal is to confine stdio servers on a snap-docker host, switch the
+isolation **mode** to `sandbox`. Servers are confined natively with a Linux
+Landlock filesystem allowlist + `setrlimit` (kernel 5.13+), which is unaffected
+by the snap-docker/AppArmor conflict because it needs no Docker and no user
+namespaces:
+
+```json
+{ "docker_isolation": { "mode": "sandbox" } }
+```
+
+Trade-off: the Docker-based scanner plugins cannot run under `sandbox`, so they
+are **skipped** and the affected server's `security_scan.status` becomes
+`degraded` (the always-on in-process `tpa-descriptions` scanner still runs).
+This is MCP-34.4 / D3 option (b) — clean, surfaced degradation. See
+[Security Isolation → Scanner behaviour](../docker-isolation.md#scanner-behaviour-under-each-mode-mcp-344).
+
+### 3. Disable the scanner for this server (dry-run shown by default)
 
 The error panel includes a **Disable scanner for this server** fix-step. The
 CLI equivalent:
@@ -46,7 +64,7 @@ mcpproxy upstream patch <server-name> --no-scanner --dry-run
 Drop `--dry-run` to apply. The server will still run with isolation, but
 without TPA pre-flight scanning.
 
-### 3. Run mcpproxy without isolation for that server
+### 4. Run mcpproxy without isolation for that server
 
 If you trust the upstream and don't need isolation:
 

internal/security/scanner/engine.go

@@ -32,6 +32,15 @@ type Engine struct {
 	// docker × AppArmor transition would otherwise deny entrypoint exec.
 	disableNoNewPrivileges bool
 
+	// isolationMode is the resolved global isolation mode ("docker", "sandbox",
+	// "none", or "" == docker for back-compat). Scanner *plugins* are
+	// Docker-based (Spec 039); under "sandbox"/"none" the host runs no Docker
+	// for scanners, so Docker-based scanners are cleanly skipped (prefailed with
+	// an honest, mode-specific reason) while in-process scanners still run. This
+	// is MCP-34.4 / D3 option (b): clean, surfaced degradation rather than a
+	// misleading "pull the image" failure. Set via Service.SetIsolationMode.
+	isolationMode string
+
 	// Track active scans (one per server)
 	mu          sync.Mutex
 	activeScans map[string]*ScanJob // keyed by server name
@@ -198,6 +207,18 @@ func (e *Engine) resolveScanners(requestedIDs []string) ([]resolvedScanner, erro
 		if s.InProcess {
 			return ""
 		}
+		// MCP-34.4 / D3 option (b): under a non-Docker isolation mode the host
+		// runs no Docker for scanner plugins, so Docker-based scanners cannot
+		// run at all. Skip them with an honest, mode-specific reason (pointing
+		// at the snap-docker/AppArmor failure doc) instead of the misleading
+		// "pull the image locally" guidance below — there is nothing to pull.
+		// They stay in the resolved set (recorded as failed), which downgrades
+		// the scan summary to "degraded" rather than a silent all-clear.
+		if mode := e.isolationMode; mode == "sandbox" || mode == "none" {
+			return fmt.Sprintf("Docker-based scanner %s skipped: isolation mode %q runs no Docker containers, so Docker scanner plugins cannot run on this host. "+
+				"In-process scanners still ran. To run Docker scanners, set isolation.mode to \"docker\" on a host with a working Docker daemon. "+
+				"See docs/errors/MCPX_DOCKER_SNAP_APPARMOR.md.", s.ID, mode)
+		}
 		if e.docker == nil {
 			return ""
 		}

internal/security/scanner/engine_test.go

@@ -600,6 +600,99 @@ func TestEngineInProcessScannerAlwaysAvailable(t *testing.T) {
 	}
 }
 
+// TestEngineResolveScannersSkipsDockerUnderSandbox verifies D3 option (b)
+// (MCP-34.4): when the resolved isolation mode is "sandbox" (or "none") — i.e.
+// no Docker is available to run scanner containers — Docker-based scanner
+// plugins are cleanly skipped with an honest, mode-specific prefail message
+// (referencing MCPX_DOCKER_SNAP_APPARMOR) instead of the misleading
+// "pull the image" message, while the always-on in-process scanner still runs.
+// The skipped Docker scanners are still surfaced (recorded as failed) so the
+// scan summary degrades rather than silently pretending all-clear.
+func TestEngineResolveScannersSkipsDockerUnderSandbox(t *testing.T) {
+	for _, mode := range []string{"sandbox", "none"} {
+		t.Run(mode, func(t *testing.T) {
+			dir := t.TempDir()
+			logger := zap.NewNop()
+			registry := NewRegistry(dir, logger)
+			registry.scanners["mcp-scan"].Status = ScannerStatusInstalled
+
+			// A non-nil docker runner with a real image present would normally
+			// let the Docker scanner pass checkImage; the sandbox/none gate must
+			// short-circuit before any Docker probe.
+			engine := NewEngine(nil, registry, dir, logger)
+			engine.isolationMode = mode
+
+			resolved, err := engine.resolveScanners(nil)
+			if err != nil {
+				t.Fatalf("resolveScanners: %v", err)
+			}
+
+			byID := make(map[string]resolvedScanner)
+			for _, rs := range resolved {
+				byID[rs.plugin.ID] = rs
+			}
+
+			// Docker scanner is still surfaced (visible in report) but prefailed.
+			dockerScanner, ok := byID["mcp-scan"]
+			if !ok {
+				t.Fatalf("expected mcp-scan to remain in resolved set under %s mode, got %v", mode, byID)
+			}
+			if dockerScanner.prefail == "" {
+				t.Fatalf("expected Docker scanner mcp-scan to be prefailed (skipped) under %s mode", mode)
+			}
+			if !strings.Contains(dockerScanner.prefail, mode) {
+				t.Errorf("prefail should name the isolation mode %q; got %q", mode, dockerScanner.prefail)
+			}
+			if !strings.Contains(dockerScanner.prefail, "MCPX_DOCKER_SNAP_APPARMOR") {
+				t.Errorf("prefail should reference the MCPX_DOCKER_SNAP_APPARMOR error doc; got %q", dockerScanner.prefail)
+			}
+			// The misleading "pull the image" guidance must NOT appear — you
+			// cannot pull/run Docker scanners at all under sandbox/none mode.
+			if strings.Contains(dockerScanner.prefail, "docker pull") {
+				t.Errorf("prefail must not tell the user to docker pull under %s mode; got %q", mode, dockerScanner.prefail)
+			}
+
+			// In-process scanner still runs (never prefailed).
+			inProc, ok := byID[inProcessTPAScannerID]
+			if !ok {
+				t.Fatalf("expected in-process scanner to remain available under %s mode", mode)
+			}
+			if inProc.prefail != "" {
+				t.Errorf("in-process scanner must not be prefailed under %s mode; got %q", mode, inProc.prefail)
+			}
+		})
+	}
+}
+
+// TestEngineResolveScannersDockerModeUnaffected is the back-compat guard: with
+// the default isolation mode (docker / empty) the sandbox skip path is inert,
+// so a Docker scanner with a nil docker runner resolves without a prefail (the
+// historical behaviour relied on by existing tests).
+func TestEngineResolveScannersDockerModeUnaffected(t *testing.T) {
+	for _, mode := range []string{"", "docker"} {
+		t.Run("mode="+mode, func(t *testing.T) {
+			dir := t.TempDir()
+			logger := zap.NewNop()
+			registry := NewRegistry(dir, logger)
+			registry.scanners["mcp-scan"].Status = ScannerStatusInstalled
+
+			engine := NewEngine(nil, registry, dir, logger)
+			engine.isolationMode = mode
+
+			resolved, err := engine.resolveScanners([]string{"mcp-scan"})
+			if err != nil {
+				t.Fatalf("resolveScanners: %v", err)
+			}
+			if len(resolved) != 1 {
+				t.Fatalf("expected 1 scanner, got %d", len(resolved))
+			}
+			if resolved[0].prefail != "" {
+				t.Errorf("Docker scanner unexpectedly prefailed under mode %q (nil docker runner skips image check): %q", mode, resolved[0].prefail)
+			}
+		})
+	}
+}
+
 func TestEngineParseResultsSARIF(t *testing.T) {
 	dir := t.TempDir()
 	logger := zap.NewNop()

internal/security/scanner/service.go

@@ -172,6 +172,25 @@ func (s *Service) SetScannerDisableNoNewPrivileges(disable bool) {
 	}
 }
 
+// SetIsolationMode records the resolved global isolation mode ("docker",
+// "sandbox", "none", or "" == docker) so the scan engine can decide whether
+// Docker-based scanner plugins can run. Under "sandbox"/"none" the host runs no
+// Docker for scanners, so Docker scanner plugins are cleanly skipped (the scan
+// summary degrades) while in-process scanners still run. This is MCP-34.4 / D3
+// option (b): clean, surfaced degradation on snap-docker / non-Docker hosts.
+func (s *Service) SetIsolationMode(mode string) {
+	if s.engine == nil {
+		return
+	}
+	s.engine.isolationMode = mode
+	if mode == "sandbox" || mode == "none" {
+		s.logger.Warn("Isolation mode runs no Docker for scanner plugins; Docker-based scanners "+
+			"will be skipped and the security scan will report 'degraded' for affected servers. "+
+			"In-process scanners (e.g. tpa-descriptions) still run. See docs/errors/MCPX_DOCKER_SNAP_APPARMOR.md.",
+			zap.String("isolation_mode", mode))
+	}
+}
+
 // SetFetchPackageSource toggles whether the source resolver may fetch the
 // published source of package-runner servers (npx/uvx) for scanning. See
 // SecurityConfig.ScannerFetchPackageSource (MCP-2206). Default is enabled.

internal/security/scanner/service_test.go

@@ -369,6 +369,28 @@ func newTestService(t *testing.T) (*Service, *mockStorage, *mockEmitter) {
 	return svc, store, emitter
 }
 
+// TestServiceSetIsolationMode verifies the setter propagates the resolved
+// isolation mode to the scan engine (MCP-34.4 / D3 option b), which is what
+// gates the Docker-scanner skip path. Default ("") leaves Docker behaviour
+// intact.
+func TestServiceSetIsolationMode(t *testing.T) {
+	svc, _, _ := newTestService(t)
+
+	if svc.engine.isolationMode != "" {
+		t.Fatalf("expected default isolation mode to be empty, got %q", svc.engine.isolationMode)
+	}
+
+	svc.SetIsolationMode("sandbox")
+	if svc.engine.isolationMode != "sandbox" {
+		t.Errorf("expected engine isolation mode 'sandbox', got %q", svc.engine.isolationMode)
+	}
+
+	svc.SetIsolationMode("docker")
+	if svc.engine.isolationMode != "docker" {
+		t.Errorf("expected engine isolation mode 'docker', got %q", svc.engine.isolationMode)
+	}
+}
+
 func TestServiceListScannersEmpty(t *testing.T) {
 	svc, _, _ := newTestService(t)
 

internal/server/server.go

@@ -1961,6 +1961,13 @@ func (s *Server) startCustomHTTPServer(ctx context.Context, streamableServer *se
 		if cfg != nil && cfg.Security != nil && cfg.Security.ScannerDisableNoNewPrivileges {
 			secService.SetScannerDisableNoNewPrivileges(true)
 		}
+		// MCP-34.4 / D3 option (b): tell the scanner which isolation mode is
+		// active. Under "sandbox"/"none" the host runs no Docker for scanner
+		// plugins, so they degrade cleanly (skip + "degraded" scan summary)
+		// instead of failing with a misleading "pull the image" message.
+		if cfg != nil && cfg.DockerIsolation != nil {
+			secService.SetIsolationMode(string(cfg.DockerIsolation.ResolvedMode()))
+		}
 		// Published-package-source fetch is enabled by default; only an explicit
 		// false in config disables it (MCP-2206).
 		if cfg != nil && cfg.Security != nil && cfg.Security.ScannerFetchPackageSource != nil && !*cfg.Security.ScannerFetchPackageSource {