Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions docs/docker-isolation.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,8 +35,8 @@ MCPProxy resolves an **isolation mode** for every stdio server. Set it globally
| 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 |
| `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). Confines **writes** only: the server still runs as the proxy's user and can read the data directory and use the admin socket (see [Honest limitations](#honest-limitations)). | 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 as the proxy's user, with the data directory and the admin socket reachable. | Everywhere. | n/a |

```json
{
Expand Down Expand Up @@ -454,6 +454,7 @@ Your options on such a host:
- **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`.
- **`none` and `sandbox` do not hide the data directory or the Unix socket.** A stdio server runs as the proxy's user, so it can read `mcp_config.json` (holds `api_key`) and `config.db` (holds the upstream OAuth tokens), and while `enable_socket` is on it can connect to `<data-dir>/mcpproxy.sock` without a key — a sandboxed child minted an agent token over it ([#1704](https://github.com/smart-mcp-proxy/mcpproxy-go/issues/1704)). Landlock does block `/proc/<pid>/environ`, so the key is safe in the environment but not on disk or over the socket. Set `enable_socket: false` for headless installs and use `docker` isolation for servers you do not trust; `mcpproxy doctor` warns when an enabled stdio server resolves to `none` or `sandbox` with the socket on. Verification table: [What the sandbox does not hide](features/sandbox-isolation.md#what-the-sandbox-does-not-hide).
- **Docker-based scanners do not run under `sandbox`/`none`.** They are skipped and the skip is surfaced via the informational `deep_scan` descriptor — it never downgrades the baseline verdict (Spec 077 FR-008). A native scanner runtime is a future enhancement (D3 option a).

## Platform support matrix
Expand Down
5 changes: 3 additions & 2 deletions docs/features/docker-isolation.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,8 @@ MCPProxy resolves an **isolation mode** for every stdio server. Set it globally
| 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. 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 |
| `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). Confines **writes** only: the server still runs as the proxy's user and can read the data directory and use the admin socket (see [Honest limitations](#honest-limitations)). | Linux 5.13+ only. macOS/Windows: documented no-op ⇒ behaves like `none`. | **No** — see [Honest limitations](#honest-limitations) |
| `none` | No confinement; the server runs directly on the host as the proxy's user, with the data directory and the admin socket reachable. | Everywhere. | n/a |

```json
{
Expand Down Expand Up @@ -424,6 +424,7 @@ See [Shutdown Behavior](/operations/shutdown-behavior) for detailed subprocess l
- **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 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. For network-sensitive servers, use `docker` mode with `network_mode: none`.
- **`none` and `sandbox` do not hide the data directory or the Unix socket.** A stdio server runs as the proxy's user, so it can read `mcp_config.json` (holds `api_key`) and `config.db` (holds the upstream OAuth tokens), and while `enable_socket` is on it can connect to `<data-dir>/mcpproxy.sock` without a key — a sandboxed child minted an agent token over it ([#1704](https://github.com/smart-mcp-proxy/mcpproxy-go/issues/1704)). Landlock does block `/proc/<pid>/environ`, so the key is safe in the environment but not on disk or over the socket. Set `enable_socket: false` for headless installs and use `docker` isolation for servers you do not trust; `mcpproxy doctor` warns when an enabled stdio server resolves to `none` or `sandbox` with the socket on. Verification table: [What the sandbox does not hide](/features/sandbox-isolation#what-the-sandbox-does-not-hide).
- **Docker-based scanners do not run under `sandbox`/`none`.** They are skipped and the skip is surfaced via the informational `deep_scan` descriptor — it never downgrades the baseline verdict (Spec 077 FR-008). A native scanner runtime is a future enhancement.

## Platform support matrix
Expand Down
67 changes: 65 additions & 2 deletions docs/features/sandbox-isolation.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,8 +38,11 @@ back-compat; `mode` supersedes it (see MCP-34.2).
- **Filesystem write allowlist.** Reads stay broad (the runtime can load
interpreters, `node_modules`, and `site-packages` from anywhere), but **writes**
are denied outside a small allowlist: the server's `working_dir`, the OS temp
dir, and the common package caches (`~/.npm`, `~/.cache`, `~/.local/share`).
Tightening reads is deferred — a read allowlist breaks tool discovery.
dir, `/dev/null`, and the common package caches (`~/.npm`, `~/.cache`,
`~/.local/share`). Tightening reads is deferred — a read allowlist breaks
tool discovery. (`/dev/null` is on the list because the read-only `/` rule
does not let a confined `sh -c '… 2>/dev/null'`, Node's `stdio: "ignore"`
or Python's `subprocess.DEVNULL` open the device for writing.)
- **Resource limits.** Core dumps are disabled (`RLIMIT_CORE=0`, so in-memory
secrets can't spill to disk) and the descriptor table is capped
(`RLIMIT_NOFILE`).
Expand All @@ -61,6 +64,66 @@ stdin/stdout pass straight through with no intervening multiplexer.
the server still starts but runs **unconfined**, and the host log records a
`DEGRADED/unconfined` diagnostic. This favors availability; use `docker` mode
when you need a hard guarantee.
- **The data directory and the admin socket stay reachable.** In `none` and
`sandbox` mode a stdio server runs as the proxy's user and can read the data
directory and, if `enable_socket` is on, use the admin socket. Set
`enable_socket: false` for headless installs and use `docker` isolation for
servers you do not trust. Details and the verification table are in
[What the sandbox does not hide](#what-the-sandbox-does-not-hide).
- **Snap-packaged runtimes do not start.** Landlock requires `no_new_privs`,
and `snap-confine` needs privileges that flag forbids, so a `uvx` or `node`
installed from a snap fails with *snap-confine is packaged without necessary
permissions*. Use a non-snap install of the runtime (the official `uv`
installer, a distro package, `nvm`).

## What the sandbox does not hide

Landlock confines **writes**. It does not change who the server runs as, and
it does not hide files or sockets the proxy's user can reach. Two things in
the data directory matter here:

- `mcp_config.json` holds `api_key`; `config.db` holds the upstream OAuth
tokens. The directory is `0700` and the files `0600`, but the child runs as
the same user, so that does not help.
- `mcpproxy.sock` (on by default, `enable_socket: true`) is the local admin
endpoint. Connections to it are trusted **without an API key**, because the
OS already authenticated the peer as the same user — which a stdio child is.

Verified by a contributor on `main` (Linux, Landlock ABI 8) with
`enable_socket` at its default and the key passed as `MCPPROXY_API_KEY`
([#1704](https://github.com/smart-mcp-proxy/mcpproxy-go/issues/1704)); a stdio
child ran a probe script:

| | `none` | `sandbox` (Landlock) | `docker` (rootless Podman) |
|---|---|---|---|
| Read `mcp_config.json` (has `api_key`) | read | read | not visible (data dir not mounted) |
| Read `config.db` (OAuth tokens) | read | read | not visible |
| `api_key` in the child's environment | no | no | no |
| Connect to `<data-dir>/mcpproxy.sock` with no key | **yes**, `GET /api/v1/status` returns data | **yes**, same | the socket is not visible |
| Mint a token over the socket (`POST /api/v1/tokens`, read+write+destructive, all servers) | same socket | **201, `mcp_agt_…` returned** | n/a |
| `GET /api/v1/config` over the socket | same socket | returns the config, `api_key` masked | n/a |
| Read the proxy's `/proc/<pid>/environ` (has `MCPPROXY_API_KEY`) | **yes** | **no**, permission denied (a Landlock domain cannot reach processes outside it) | n/a |

So in `sandbox` mode the environment is protected, but the unauthenticated
socket gives the child admin on its own, and hiding the files would not help.
With `enable_socket: false` the socket row disappears; the files remain
readable in `none` and `sandbox`.

What to do:

- **Headless installs** (no tray): set `enable_socket: false`. The tray is the
only socket client, so a headless service loses nothing.
- **Servers you do not trust**: use `docker` isolation
(`docker_isolation.mode: "docker"`, or per-server `isolation.mode`). The
container does not mount the data directory, so neither the files nor the
socket are visible.
- `mcpproxy doctor` reports every enabled stdio server that resolves to `none`
or `sandbox` while `enable_socket` is on, so a config that drifts into this
state is visible without re-reading this page.

The same exposure applies to a server-edition container that runs stdio
children next to its `/data` volume unless Docker isolation is turned on
there.

## Platform support

Expand Down
3 changes: 2 additions & 1 deletion docs/getting-started/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -281,7 +281,7 @@ sudo tee /etc/mcpproxy/mcp_config.json >/dev/null <<EOF
"listen": "0.0.0.0:8080",
"api_key": "${API_KEY}",
"data_dir": "/var/lib/mcpproxy",
"enable_socket": true,
"enable_socket": false,
"enable_web_ui": true,
"require_mcp_auth": false,
"mcpServers": []
Expand All @@ -300,6 +300,7 @@ curl -H "X-API-Key: ${API_KEY}" http://<server-ip>:8080/api/v1/status
- **Always set a non-empty `api_key`.** The REST API enforces it, but a network-reachable instance with an obvious or empty key is one `curl` away from full tool execution.
- **Put a firewall in front.** If only one workstation needs access, prefer binding to a single LAN IP (e.g. `"listen": "192.168.1.10:8080"`) or restrict port 8080 in `ufw`/`firewalld` to known source addresses.
- **Consider `require_mcp_auth: true`** if you also want the `/mcp` endpoint to require the API key. It's `false` by default for AI-client compatibility.
- **Headless? Set `enable_socket: false` and use `docker` isolation for stdio servers.** The Unix socket in the data directory trusts every same-user connection without a key, and a stdio server under isolation `none` or `sandbox` runs as the service user: it can read `mcp_config.json` and `config.db` and mint agent tokens over the socket. The tray is the only socket client, so a headless service loses nothing by turning it off; `docker` isolation keeps the data directory out of the server's view. `mcpproxy doctor` warns about the combination. See [What the sandbox does not hide](/features/sandbox-isolation#what-the-sandbox-does-not-hide).
- **Don't expose to the public internet without TLS in front.** Run nginx/Caddy/Traefik as a reverse proxy with HTTPS, or tunnel via Tailscale/WireGuard/SSH. The built-in HTTP server is not designed to be a public ingress.

:::
Expand Down
1 change: 1 addition & 0 deletions docs/socket-communication.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ MCPProxy uses platform-specific local IPC for secure, low-latency communication
- **Socket/Pipe connections**: Trusted by default (skip API key validation)
- **TCP connections**: Require API key authentication
- **Middleware**: `internal/httpapi/server.go` checks connection source via context
- **Trust boundary**: "trusted by default" means every process running as the same user — including the stdio MCP servers mcpproxy itself spawns under isolation `none` or `sandbox` (Landlock confines writes only). Such a server can mint agent tokens over the socket without a key. On headless installs set `enable_socket: false` (the tray is the only socket client); run stdio servers you do not trust under `docker` isolation, which does not mount the data directory. `mcpproxy doctor` reports the combination. See [What the sandbox does not hide](/features/sandbox-isolation#what-the-sandbox-does-not-hide).

## File Locations

Expand Down
50 changes: 49 additions & 1 deletion internal/config/doctor_findings.go
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
package config

import (
"fmt"
"strconv"
"strings"
)

// MsgRequireMCPAuthOverridden is the boot notice and doctor finding text of
// contracts/config-keys.md for an explicit require_mcp_auth: false under an
// enabled server-edition block (Spec 107 FR-029).
Expand All @@ -14,5 +20,47 @@ func DoctorFindings(cfg *Config) []string {
if cfg == nil {
return nil
}
return serverEditionDoctorFindings(cfg)
var out []string
if f := StdioSocketExposureFinding(cfg); f != "" {
out = append(out, f)
}
return append(out, serverEditionDoctorFindings(cfg)...)
}

// StdioSocketExposureFinding is the GH #1704 doctor finding: every enabled
// stdio server whose resolved isolation mode is none or sandbox while
// enable_socket is on, in config order. Such a child runs as the proxy's user,
// so it can read the data directory (mcp_config.json with api_key, config.db
// with OAuth tokens) and connect to the admin socket in that directory, which
// trusts every connection without a key — a sandboxed child minted an agent
// token over it. Landlock confines writes only; neither mode hides either.
// Servers resolved to docker, servers that run docker themselves and servers
// with no child process are not listed. Returns "" when there is nothing to
// report.
func StdioSocketExposureFinding(cfg *Config) string {
if cfg == nil || !cfg.EnableSocket {
return ""
}
var exposed []string
for _, s := range cfg.Servers {
if s == nil || !s.Enabled || s.Command == "" || IsDockerCommand(s.Command) {
// No child process, or the server already runs in a container of its
// own (the structural gate only fires for non-none modes, so check it
// here too).
continue
}
if ResolveIsolation(cfg.DockerIsolation, s).Mode == IsolationModeDocker {
continue
}
exposed = append(exposed, strconv.Quote(s.Name))
}
if len(exposed) == 0 {
return ""
}
return fmt.Sprintf("%d enabled stdio server(s) run under isolation none or sandbox while enable_socket is true (%s): "+
"a stdio server runs as the proxy's user, can read the data directory (mcp_config.json holds api_key, config.db holds OAuth tokens) "+
"and can mint agent tokens over the admin socket in that directory without a key; the sandbox mode confines writes only. "+
"Set enable_socket: false on headless installs and use docker isolation (docker_isolation.mode: \"docker\", or per-server isolation.mode) for servers you do not trust. "+
"See https://docs.mcpproxy.app/features/sandbox-isolation/",
len(exposed), strings.Join(exposed, ", "))
}
Loading
Loading