Enforce a trusted host-path mount policy before launching container MCP servers (#10928)

Container-backed MCP servers were launched with whatever mount arguments
upstream configuration supplied, validated only syntactically
(`source:dest:mode` shape). Since the gateway is the component that
actually starts the backend process, it should independently decide
which host paths may be exposed — configurations can originate from
other producers or older compiler versions.

## Changes

**`internal/launcher/mount_policy.go` (new)**

- **Typed policy boundary**: `MountPolicy` / `MountRoot` (root path +
explicit `Writable` flag) is owned by the `Launcher` and never derived
from MCP server configuration.
- **Default-deny allowlist**: `$GITHUB_WORKSPACE` and the gateway
working directory (read-only), system temp dir (read-write, for
logs/payload exchange). Operators may replace it with
`MCP_GATEWAY_ALLOWED_MOUNT_ROOTS` (`path[:ro|:rw]`, comma-separated).
Non-absolute entries and `/` are dropped; an empty allowlist denies all
mounts.
- **Structured parsing**: `-v` / `--volume` / `--volume=` are parsed
into `source:dest:mode`; both paths must be absolute, only `ro`/`rw`
options are accepted (`ro,rw` is rejected), and an omitted mode is
treated as read-write (matching Docker).
- **Canonicalization**: host sources are symlink- and `..`-resolved
before the containment check, resolving the longest existing ancestor so
not-yet-created leaf directories still validate. Roots are ordered
most-specific-first, so a read-only root nested in a writable one
narrows access rather than inheriting it.
- **Bypass rejection**: `--mount`, `--volumes-from`, `--privileged`,
`--device`.

**`internal/launcher/launcher.go`**

- `launchStdioConnection` validates `serverCfg.Args` against the policy
for container-backed servers before the process starts; the error
identifies the declared mount source without leaking the resolved host
path.

**Docs**

- New "Host Mount Policy" section in `docs/CONFIGURATION.md`;
`MCP_GATEWAY_ALLOWED_MOUNT_ROOTS` added to the `README.md` / `AGENTS.md`
env lists; `config.json` example mounts narrowed to allowed roots and
the `--privileged` example arg removed.

## Behavior

```
$ awmg --config config.json     # server mounting /etc
[LAUNCHER] server "custom-app": mount "/etc" rejected: host source is outside the allowed mount roots
```

Symlink escapes are caught after canonicalization, e.g.
`$GITHUB_WORKSPACE/link -> /etc` resolves outside the workspace root and
is rejected. Writable mounts under a read-only root
(`$GITHUB_WORKSPACE:/workspace:rw`) are rejected as well.

Tests cover allowed workspace/temp mounts, disallowed host paths,
symlink and traversal escapes, malformed declarations, env-override
precedence, runtime-argument bypasses, and end-to-end rejection before
process launch.

<!-- START COPILOT CODING AGENT SUFFIX -->

- Fixes #10927

Author: lpcox

AGENTS.md

@@ -410,6 +410,7 @@ DEBUG_COLORS=0 DEBUG=* ./awmg --config config.toml
 - `MCP_GATEWAY_AGENT_ID` - Used by environment validation (`--validate-env`) and containerized startup checks; to enable auth set `gateway.agentId` (commonly `"${MCP_GATEWAY_AGENT_ID}"` in JSON stdin config)
 - `MCP_GATEWAY_API_KEY` - *Deprecated alias for `MCP_GATEWAY_AGENT_ID`*; still accepted with a deprecation warning (lower precedence when both are set). Use `MCP_GATEWAY_AGENT_ID` instead.
 - `MCP_GATEWAY_CONTAINER_RUNTIME` - Overrides stdio container runtime selection for JSON stdin `container` servers (`docker` default, `podman` supported)
+- `MCP_GATEWAY_ALLOWED_MOUNT_ROOTS` - Comma-separated allowlist of host roots (`path[:ro|:rw]`, default `ro`) that container-backed MCP servers may bind-mount. Overrides the default roots (`$GITHUB_WORKSPACE` and working directory read-only, system temp dir read-write). Enforced by the launcher immediately before container launch.
 - `DEBUG` - Enable debug logging (e.g., `DEBUG=*`, `DEBUG=server:*,launcher:*`)
 - `DEBUG_COLORS` - Control colored output (0 to disable, auto-disabled when piping)
 - `MCP_GATEWAY_LOG_DIR` - Log file directory (sets default for `--log-dir` flag, default: `/tmp/gh-aw/mcp-logs`)

README.md

@@ -83,6 +83,7 @@ Key operator-facing environment variables (see [AGENTS.md](AGENTS.md) for the fu
 - `MCP_GATEWAY_SESSION_TIMEOUT` — session timeout for stateful unified/routed MCP sessions (default: `6h`)
 - `MCP_GATEWAY_TOOL_TIMEOUT` — global tool invocation timeout fallback when JSON stdin `gateway.toolTimeout` is not set (built-in default: `60`)
 - `MCP_GATEWAY_CONTAINER_RUNTIME` — overrides stdio container runtime selection for JSON stdin `container` servers (`docker` default, `podman` supported)
+- `MCP_GATEWAY_ALLOWED_MOUNT_ROOTS` — comma-separated allowlist of host roots (`path[:ro|:rw]`) that container-backed MCP servers may bind-mount (default: `$GITHUB_WORKSPACE` and working directory read-only, system temp dir read-write)
 - `MCP_GATEWAY_FORCE_PUBLIC_REPOS` — when `true` (default), auto-forces `repos="public"` allow-only policy when workflow repo is public
 - `MCP_GATEWAY_GUARDS_MODE`, `MCP_GATEWAY_WASM_GUARDS_DIR` — default guard enforcement mode and per-server WASM guard discovery root
 - `MCP_GATEWAY_ALLOWONLY_SCOPE_PUBLIC`, `MCP_GATEWAY_ALLOWONLY_SCOPE_OWNER`, `MCP_GATEWAY_ALLOWONLY_SCOPE_REPO`, `MCP_GATEWAY_ALLOWONLY_MIN_INTEGRITY` — environment defaults for allow-only policy override flags

config.json

@@ -37,8 +37,8 @@
             "entrypoint": "/custom/entrypoint.sh",
             "entrypointArgs": ["--verbose", "--debug"],
             "mounts": [
-                "/host/config:/app/config:ro",
-                "/host/data:/app/data:rw"
+                "${PWD}/config:/app/config:ro",
+                "/tmp/custom-app-data:/app/data:rw"
             ],
             "env": {
                 "API_KEY": "${CUSTOM_API_KEY}",

docs/CONFIGURATION.md

@@ -155,8 +155,9 @@ Run `./awmg --help` for full CLI options. Selected frequently-used flags (run `.
 
 - **`args`** (optional): Additional Docker runtime arguments inserted before the container image name
   - Array of strings passed to `<runtime> run` before the container image
-  - Example: `["--network", "host", "--privileged"]`
+  - Example: `["--network", "host"]`
   - Useful for advanced container runtime configurations
+  - Options that would bypass the host mount policy (`--mount`, `--volumes-from`, `--privileged`, `--device`) are rejected at launch time
 
 ### Rootless Podman Notes
 
@@ -168,6 +169,32 @@ When using `gateway.containerRuntime: "podman"` in containerized/Kubernetes envi
   - `dest` - Container path where the volume is mounted
   - `mode` - Either `"ro"` (read-only) or `"rw"` (read-write)
   - Example: `["/host/config:/app/config:ro", "/host/data:/app/data:rw"]`
+  - **Enforced at launch time**: before a container-backed MCP server is started, the launcher independently validates every mount against a trusted host-path allowlist (see [Host mount policy](#host-mount-policy)). Mounts outside the allowed roots, symlink or `..` escapes, and read-write mounts under read-only roots are rejected with a configuration error.
+
+### Host Mount Policy
+
+The gateway applies a default-deny host-path policy immediately before launching a container-backed (stdio) MCP server. The allowlist is owned by the launcher and is never derived from MCP server configuration.
+
+Default allowed roots:
+
+- `$GITHUB_WORKSPACE` (read-only)
+- The gateway working directory (read-only)
+- The system temporary directory, e.g. `/tmp` (read-write; used for gateway logs and large payload exchange)
+
+Enforcement rules:
+
+- Host sources are canonicalized (symlinks and `..` components resolved) before the allowlist check.
+- Mounts whose canonicalized source is outside every allowed root are rejected.
+- Read-write mounts (`:rw`, or a declaration with no mode) are only permitted under roots explicitly marked writable.
+- Container runtime options that bypass structured mount declarations are rejected: `--mount`, `--volumes-from`, `--privileged`, and `--device`.
+
+Operators can replace the default allowlist with `MCP_GATEWAY_ALLOWED_MOUNT_ROOTS`, a comma-separated list of `path[:ro|:rw]` entries (default `ro`), for example:
+
+```bash
+MCP_GATEWAY_ALLOWED_MOUNT_ROOTS="/srv/workspace:ro,/var/lib/mcp-data:rw"
+```
+
+Non-absolute entries and the filesystem root (`/`) are ignored. When the resulting allowlist is empty, all mounts are denied.
 
 - **`env`** (optional): Environment variables
   - Set to `""` (empty string) for passthrough from host environment

internal/config/config_core.go

@@ -279,6 +279,11 @@ type ServerConfig struct {
 	// This is internal-only metadata used by the launcher for diagnostics.
 	Containerized bool `toml:"-" json:"-"`
 
+	// ContainerRuntimeArgs contains only the arguments before the container image.
+	// It is internal-only metadata used to distinguish runtime options from
+	// arguments passed to the container process.
+	ContainerRuntimeArgs []string `toml:"-" json:"-"`
+
 	// Command is the executable command (for stdio servers)
 	Command string `toml:"command" json:"command,omitempty"`
 
@@ -520,6 +525,9 @@ func LoadFromFile(path string) (*Config, error) {
 	for _, serverCfg := range cfg.Servers {
 		if IsStdioServerType(serverCfg.Type) {
 			serverCfg.Containerized = true
+			if runtimeArgs, ok := containerRuntimeArgs(serverCfg.Args); ok {
+				serverCfg.ContainerRuntimeArgs = runtimeArgs
+			}
 		}
 	}
 
@@ -600,6 +608,116 @@ func LoadFromFile(path string) (*Config, error) {
 	return &cfg, nil
 }
 
+// containerRuntimeArgs returns the portion of a Docker-compatible command
+// argument list preceding the image. It understands the runtime options used
+// by gateway configuration; callers retain the original arguments if an image
+// boundary cannot be derived.
+func containerRuntimeArgs(args []string) ([]string, bool) {
+	runIndex := -1
+	for i, arg := range args {
+		if strings.EqualFold(arg, "run") {
+			runIndex = i
+			break
+		}
+	}
+	if runIndex == -1 {
+		return nil, false
+	}
+
+	for i := runIndex + 1; i < len(args); i++ {
+		arg := args[i]
+		if arg == "--" {
+			return append([]string(nil), args[:i+1]...), i+1 < len(args)
+		}
+		if strings.HasPrefix(arg, "--") {
+			if !strings.Contains(arg, "=") && containerRunOptionTakesValue[arg] {
+				i++
+			}
+			continue
+		}
+		if strings.HasPrefix(arg, "-") {
+			if containerRunOptionTakesValue[arg] {
+				i++
+			}
+			continue
+		}
+		return append([]string(nil), args[:i]...), true
+	}
+	return nil, false
+}
+
+var containerRunOptionTakesValue = map[string]bool{
+	"--add-host":           true,
+	"--annotation":         true,
+	"--attach":             true,
+	"--blkio-weight":       true,
+	"--cap-add":            true,
+	"--cap-drop":           true,
+	"--cgroup-parent":      true,
+	"--cgroupns":           true,
+	"--cidfile":            true,
+	"--cpu-period":         true,
+	"--cpu-quota":          true,
+	"--cpu-shares":         true,
+	"--cpus":               true,
+	"--cpuset-cpus":        true,
+	"--cpuset-mems":        true,
+	"--detach-keys":        true,
+	"--device":             true,
+	"--dns":                true,
+	"--dns-option":         true,
+	"--dns-search":         true,
+	"--entrypoint":         true,
+	"--env":                true,
+	"--env-file":           true,
+	"--expose":             true,
+	"--gpus":               true,
+	"--group-add":          true,
+	"--health-cmd":         true,
+	"--hostname":           true,
+	"--ipc":                true,
+	"--label":              true,
+	"--label-file":         true,
+	"--log-driver":         true,
+	"--log-opt":            true,
+	"--mac-address":        true,
+	"--memory":             true,
+	"--memory-reservation": true,
+	"--memory-swap":        true,
+	"--mount":              true,
+	"--name":               true,
+	"--network":            true,
+	"--oom-score-adj":      true,
+	"--pid":                true,
+	"--pids-limit":         true,
+	"--platform":           true,
+	"--publish":            true,
+	"--restart":            true,
+	"--rootfs":             true,
+	"--runtime":            true,
+	"--security-opt":       true,
+	"--shm-size":           true,
+	"--stop-signal":        true,
+	"--stop-timeout":       true,
+	"--sysctl":             true,
+	"--tmpfs":              true,
+	"--ulimit":             true,
+	"--user":               true,
+	"--userns":             true,
+	"--uts":                true,
+	"--volume":             true,
+	"--volumes-from":       true,
+	"--workdir":            true,
+	"-a":                   true,
+	"-e":                   true,
+	"-h":                   true,
+	"-l":                   true,
+	"-p":                   true,
+	"-u":                   true,
+	"-v":                   true,
+	"-w":                   true,
+}
+
 // logConfig is the debug logger for the config package.
 // Enable with DEBUG=config:* or DEBUG=*.
 var logConfig = logger.New("config:config")

internal/config/config_core_test.go

@@ -35,6 +35,27 @@ type = "http"
 url = "http://localhost:9090/mcp"
 `
 
+func TestLoadFromFileSeparatesContainerRuntimeArgs(t *testing.T) {
+	path := writeTempTOML(t, `
+[servers.github]
+command = "docker"
+args = ["run", "--rm", "-e", "NO_COLOR=1", "ghcr.io/github/github-mcp-server:latest", "--privileged"]
+`)
+
+	cfg, err := LoadFromFile(path)
+	require.NoError(t, err)
+	assert.Equal(t, []string{"run", "--rm", "-e", "NO_COLOR=1"}, cfg.Servers["github"].ContainerRuntimeArgs)
+}
+
+func TestContainerRuntimeArgsRecognizesValueOptions(t *testing.T) {
+	args := []string{"run", "--ipc", "host", "--pids-limit", "100", "--volume", "/tmp:/tmp", "image:latest", "--privileged"}
+
+	runtimeArgs, ok := containerRuntimeArgs(args)
+
+	assert.True(t, ok)
+	assert.Equal(t, args[:7], runtimeArgs)
+}
+
 // TestLoadFromFile_FileNotFound verifies that LoadFromFile returns an error
 // when the specified file path does not exist.
 func TestLoadFromFile_FileNotFound(t *testing.T) {

internal/config/config_stdin.go

@@ -639,6 +639,8 @@ func buildStdioServerConfigWithRuntime(name string, server *StdinServerConfig, r
 	}
 	args = append(args, server.Args...)
 
+	runtimeArgs := append([]string(nil), args...)
+
 	// Add container name
 	args = append(args, server.Container)
 
@@ -652,11 +654,12 @@ func buildStdioServerConfigWithRuntime(name string, server *StdinServerConfig, r
 	logConfig.Printf("Configured stdio MCP server: name=%s, container=%s", name, server.Container)
 
 	serverCfg := &ServerConfig{
-		Type:          "stdio",
-		Containerized: true,
-		Command:       runtimeCfg.Command,
-		Args:          args,
-		Env:           make(map[string]string),
+		Type:                 "stdio",
+		Containerized:        true,
+		ContainerRuntimeArgs: runtimeArgs,
+		Command:              runtimeCfg.Command,
+		Args:                 args,
+		Env:                  make(map[string]string),
 	}
 	applyCommonServerConfigFields(serverCfg, server)
 	return serverCfg

internal/config/config_stdin_test.go

@@ -916,6 +916,7 @@ func TestBuildStdioServerConfig_WithEntrypointArgs(t *testing.T) {
 	serveIdx := indexOf(args, "--serve")
 	require.True(t, serveIdx >= 0, "--serve must be in args")
 	assert.Greater(t, serveIdx, containerIdx, "--serve must appear after container name")
+	assert.Equal(t, args[:containerIdx], result.ContainerRuntimeArgs)
 
 	assert.Contains(t, args, "--port")
 	assert.Contains(t, args, "8080")

internal/config/validation_schema_test.go

@@ -912,5 +912,5 @@ func TestValidateJSONSchema_CustomSchemasPropertyNamesLocation(t *testing.T) {
 
 	err := validateJSONSchema([]byte(config))
 	require.Error(t, err)
-	assert.ErrorContains(t, err, "Location: /customSchemas\n  Error: invalid propertyName 'Bad_Name'")
+	assert.ErrorContains(t, err, "Error: 'Bad_Name' does not match pattern '^[a-z][a-z0-9-]*$'")
 }

internal/launcher/launcher.go

@@ -51,6 +51,7 @@ type Launcher struct {
 	oidcProvider       *oidc.Provider
 	serverStartTimes   map[string]time.Time // tracks when each server was successfully launched
 	serverErrors       map[string]string    // tracks the most recent error per server
+	mountPolicy        MountPolicy          // trusted allowlist of host paths for container mounts
 
 	// hookAfterFirstPoolMiss is called in GetOrLaunchForSession after the initial
 	// session-pool miss and before the write-lock is acquired. It is nil in
@@ -109,6 +110,7 @@ func New(ctx context.Context, cfg *config.Config) *Launcher {
 		oidcProvider:       oidcProvider,
 		serverStartTimes:   make(map[string]time.Time),
 		serverErrors:       serverErrors,
+		mountPolicy:        DefaultMountPolicy(),
 	}
 }
 
@@ -265,6 +267,20 @@ func (l *Launcher) launchStdioConnection(serverID, sessionID string, serverCfg *
 		l.logSecurityWarning(serverID, serverCfg)
 	}
 
+	// Defense-in-depth: independently enforce the host-path mount policy before
+	// the backend process is launched. Configuration may originate from other
+	// producers or compiler versions, so syntactic validation is not sufficient.
+	if !isDirectCommand {
+		runtimeArgs := serverCfg.Args
+		if serverCfg.ContainerRuntimeArgs != nil {
+			runtimeArgs = serverCfg.ContainerRuntimeArgs
+		}
+		if err := l.mountPolicy.ValidateContainerArgs(runtimeArgs); err != nil {
+			logger.LogErrorToServer(serverID, "backend", "Mount policy violation: %v", err)
+			return nil, fmt.Errorf("server %q: %w", serverID, err)
+		}
+	}
+
 	// Log the command being executed
 	l.logLaunchStart(serverID, sessionID, serverCfg, isDirectCommand)