Skip to content
Merged
20 changes: 20 additions & 0 deletions cmd/generate-types/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -230,6 +230,7 @@ export interface PreflightResponse {
updated: string; // ISO date string
isolation?: IsolationConfig;
isolation_defaults?: IsolationDefaults; // Resolved baseline values (read-only, used as placeholders)
isolation_effective?: IsolationEffective; // Resolved isolation state + why (read-only)
oauth_status?: 'authenticated' | 'expired' | 'error' | 'none'; // OAuth authentication status
token_expires_at?: string; // ISO date string when OAuth token expires
user_logged_out?: boolean; // True if user explicitly logged out (prevents auto-reconnection)
Expand Down Expand Up @@ -282,7 +283,15 @@ export interface OAuthConfig {
}

export interface IsolationConfig {
// EFFECTIVE isolation state, after global + per-server + structural
// resolution. NOT the raw per-server override — read enabled_override for
// that. Always present on stdio servers.
enabled: boolean;
// RAW per-server override. Absent = inherit the global setting, which is a
// distinct state from an explicit false.
enabled_override?: boolean;
// RAW per-server mode override. Absent = inherit.
mode_override?: string;
image?: string;
network_mode?: string;
extra_args?: string[];
Expand All @@ -292,6 +301,17 @@ export interface IsolationConfig {
timeout?: string;
}

// IsolationEffective reports the resolved isolation state of a server and the
// rule that produced it, so the UI can explain "inherits global: docker"
// instead of rendering an ambiguous toggle. Read-only; never sent on PATCH.
export interface IsolationEffective {
mode: string; // 'docker' | 'sandbox' | 'none' — what the spawn path branches on
isolated: boolean; // actually CONFINED; not simply mode !== 'none' (see 'sandbox-unavailable')
global_mode?: string;
inherited: boolean; // no per-server enabled/mode override is set
source?: string; // 'global' | 'server-mode' | 'server-opt-out' | 'server-opt-in-ignored' | 'not-stdio' | 'already-docker' | 'sandbox-unavailable' | 'unsupported-mode'; treat unknown as 'global'
}

// IsolationDefaults reports the resolved baseline Docker isolation
// values the backend will apply when no per-server override is set.
// Populated on server-list / server-get responses; the Web UI uses these
Expand Down
10 changes: 9 additions & 1 deletion cmd/release-gate/client.go
Original file line number Diff line number Diff line change
Expand Up @@ -313,8 +313,16 @@ type addServerRequest struct {
}

// isolationRequest mirrors httpapi.IsolationRequest (the subset we use).
//
// The writable key is `enabled_override`, NOT `enabled`: on a read
// `isolation.enabled` is the EFFECTIVE state (global setting + per-server
// override + structural gates), so the write surfaces refuse it with a 400
// rather than let a read-modify-write client turn "inherits the global
// setting" into a permanent explicit override (GH #1142). Tri-state, matching
// the server: absent leaves the persisted override alone, `false` is an
// explicit opt-out.
type isolationRequest struct {
Enabled *bool `json:"enabled,omitempty"`
EnabledOverride *bool `json:"enabled_override,omitempty"`
}

func (c *Client) addServer(ctx context.Context, req addServerRequest) error {
Expand Down
37 changes: 25 additions & 12 deletions cmd/release-gate/invariants.go
Original file line number Diff line number Diff line change
Expand Up @@ -298,6 +298,29 @@ type quarantineFlowDeps struct {
ConnectTimeout time.Duration
}

// quarantineFixtureAddRequest builds the POST /api/v1/servers body for the
// quarantine-flow fixture.
//
// Isolation is opted out PER SERVER: this fixture runs a host binary and the
// matrix run may have global docker isolation enabled for the docker cell, so
// without the opt-out the docker cell would wrap the host path in a container
// and the fixture would never start.
//
// Extracted so the wire shape is unit-testable: `isolation.enabled` is
// read-only on writes (GH #1142) and a body carrying it is answered with 400,
// which would fail add-server and every invariant downstream of it.
func quarantineFixtureAddRequest(serverName, binPath string) addServerRequest {
enabled, isolate := true, false
return addServerRequest{
Name: serverName,
Command: binPath,
Args: []string{"--transport", "stdio"},
Protocol: "stdio",
Enabled: &enabled,
Isolation: &isolationRequest{EnabledOverride: &isolate},
}
}

// checkQuarantineFlow adds a fresh stdio fixture server mid-run via the
// management API and asserts the full Spec 032 lifecycle:
//
Expand Down Expand Up @@ -344,19 +367,9 @@ func checkQuarantineFlow(ctx context.Context, c *Client, deps quarantineFlowDeps
}

// Add WITHOUT an explicit quarantined value: the default path must land
// the server in quarantine (issue #370 semantics). Isolation is opted
// out per-server: this fixture runs a host binary and the matrix run may
// have global docker isolation enabled for the docker cell.
// the server in quarantine (issue #370 semantics).
if err := step("add-server", func() error {
t, f := true, false
return c.addServer(ctx, addServerRequest{
Name: deps.ServerName,
Command: binPath,
Args: []string{"--transport", "stdio"},
Protocol: "stdio",
Enabled: &t,
Isolation: &isolationRequest{Enabled: &f},
})
return c.addServer(ctx, quarantineFixtureAddRequest(deps.ServerName, binPath))
}); err != nil {
return steps, cleanup, err
}
Expand Down
45 changes: 45 additions & 0 deletions cmd/release-gate/isolation_write_contract_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
package main

import (
"encoding/json"
"testing"

"github.com/smart-mcp-proxy/mcpproxy-go/internal/httpapi"
)

// TestQuarantineFixtureAddRequestUsesWritableIsolationKey pins the gate's
// add-server body to the WRITABLE isolation key.
//
// GH #1142 made `isolation.enabled` read-only on POST /api/v1/servers: it is
// the EFFECTIVE state on reads, so the handler now answers 400 rather than
// letting a read-modify-write turn "inherits the global setting" into a
// permanent override. The gate's fixture opt-out is load-bearing — it runs a
// HOST binary and must stay native when the docker matrix cell turns global
// isolation on — so it has to keep opting out, via `enabled_override`.
//
// The assertion decodes the gate's own body with the SERVER's request type, so
// it fails exactly when the real handler would reject the request, instead of
// re-stating the gate's JSON tags back at itself.
func TestQuarantineFixtureAddRequestUsesWritableIsolationKey(t *testing.T) {
body, err := json.Marshal(quarantineFixtureAddRequest("gate-fresh-abc123", "/tmp/bin/mcpfixture-gate-fresh-abc123"))
if err != nil {
t.Fatalf("marshal add-server body: %v", err)
}

var decoded httpapi.AddServerRequest
if err := json.Unmarshal(body, &decoded); err != nil {
t.Fatalf("server-side decode of gate body %s: %v", body, err)
}
if decoded.Isolation == nil {
t.Fatalf("the per-server isolation opt-out was dropped from the gate body: %s", body)
}
if decoded.Isolation.Enabled.Set {
t.Fatalf("gate sends the read-only `isolation.enabled`; the handler answers 400 and the whole release QA gate fails: %s", body)
}
if !decoded.Isolation.EnabledOverride.Set {
t.Fatalf("gate must still opt the host fixture OUT of isolation via `enabled_override`: %s", body)
}
if decoded.Isolation.EnabledOverride.Value == nil || *decoded.Isolation.EnabledOverride.Value {
t.Fatalf("the fixture opt-out must be enabled_override=false, got %+v: %s", decoded.Isolation.EnabledOverride, body)
}
}
2 changes: 1 addition & 1 deletion docs/api/rest-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -242,7 +242,7 @@ mask string.
"enabled": true,
"quarantined": false,
"auto_approve_tool_changes": true,
"isolation": {"enabled": true, "image": "node:20"}
"isolation": {"enabled_override": true, "image": "node:20"}
}
```

Expand Down
33 changes: 33 additions & 0 deletions docs/docker-isolation.md
Original file line number Diff line number Diff line change
Expand Up @@ -173,6 +173,39 @@ Per-server `isolation.enabled: true` only takes effect when the global `docker_i

Starting in this release, MCPProxy emits a one-time warning in the main log when it detects this configuration (look for `per-server docker isolation opt-in ignored` in `~/.mcpproxy/logs/main.log`). To actually isolate those servers, flip the global flag on.

## Reading isolation state over the API

Per-server `isolation.enabled` is a **tri-state** in the config file: `true`, `false`, or **absent** — and absent means *inherit the global setting*, not *off*.

The API surfaces both halves of that, so a client never has to guess:

| Field | Meaning |
|-------|---------|
| `isolation.enabled` | The **effective** state — is this server actually CONFINED right now, after the global setting, the per-server override, the structural gates and the host's capabilities. Always present for stdio servers. **Read-only** — see below. |
| `isolation.enabled_override` | The **raw** per-server override, exactly as persisted. **Absent = inherit.** |
| `isolation.mode_override` | The raw per-server `isolation.mode` override. Absent = inherit. |
| `isolation_effective` | `{mode, isolated, global_mode, inherited, source}` — the resolved state plus *why*. |

`isolation_effective.source` is a small, extensible vocabulary: `global`, `server-mode`, `server-opt-out`, `server-opt-in-ignored`, `not-stdio`, `already-docker`, `sandbox-unavailable`, `unsupported-mode`. **Treat an unrecognized value as `global`.**

`isolated` is deliberately NOT just `mode != none`. The `sandbox` mode is enforced by Landlock, which is Linux-only and absent from some kernels; where it cannot be enforced the launcher runs the server **unconfined**, so `isolated` is `false` and `source` is `sandbox-unavailable` even though `mode` stays `sandbox` (the wrapper still applies its rlimits on Linux). A mode no version implements reports `unsupported-mode`. The read surface never claims isolation the spawn path will not deliver.

> **Changed in this release (GH #1142):** `isolation.enabled` previously carried the raw override flattened to a bool, so a server that inherited global isolation — and was genuinely running in a container — was reported as `enabled: false` and displayed as unisolated everywhere. It now reports the effective state; read `enabled_override` for the raw value.

### Writing the override

Reads and writes use **different key names on purpose**. `isolation.enabled` is a derived, read-only value; the writable key is `isolation.enabled_override`, the same key reads return the raw override under. `POST /api/v1/servers` and `PATCH /api/v1/servers/{id}` accept the tri-state there:

- **omit the key** → leave the persisted override alone;
- **`null`** → clear the override, back to inheriting the global setting;
- **`true` / `false`** → set an explicit opt-in / opt-out.

Sending `isolation.enabled` on either verb returns **400**. That is deliberate: it is the effective state on the way out, so a read-modify-write client that echoed the whole isolation object back would silently convert "inherits the global setting" into a permanent explicit override — the same corruption the effective-state reporting exists to prevent. An unrecognized `mode_override` is likewise rejected with a 400 naming the accepted vocabulary, instead of being persisted and failing the next daemon start's config validation.

Only send `enabled_override` when the user actually changed it. Fields the request omits (including `log_driver`, `log_max_size`, `log_max_files`) are preserved.

> The MCP `upstream_servers` tool's `isolation_json` argument is the raw config object, so its `enabled` field is the raw tri-state there, matching the config file. Its `mode` is validated the same way.

## Telemetry

When anonymous telemetry is enabled, MCPProxy reports two Docker-related counters at daily cadence:
Expand Down
6 changes: 6 additions & 0 deletions docs/features/sandbox-isolation.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,12 @@ stdin/stdout pass straight through with no intervening multiplexer.
| **Linux** (no Landlock) | Degraded → runs unconfined, logged |
| **macOS / Windows** | Documented **no-op** → effective `none` (Landlock is Linux-only) |

The API says so too: where the sandbox cannot be enforced, a server with
`mode: sandbox` reports `isolation.enabled: false` and
`isolation_effective.source: "sandbox-unavailable"` (its `mode` stays `sandbox`,
because on Linux the wrapper still applies its rlimits). The read surface never
claims confinement the spawn path will not deliver.

See also: [Docker Isolation](/features/docker-isolation) for the Docker mode, and
the [non-Docker sandbox spike](https://github.com/smart-mcp-proxy/mcpproxy-go/blob/main/docs/development/sandbox-spike-mcp-34.md) for the
mechanism evaluation.
23 changes: 23 additions & 0 deletions frontend/src/types/api.ts
Original file line number Diff line number Diff line change
Expand Up @@ -156,7 +156,15 @@ export interface SecurityScanReportSummary {

// Server types
export interface ServerIsolationConfig {
// EFFECTIVE isolation state, after global + per-server + structural
// resolution. NOT the raw per-server override — read enabled_override for
// that. Always present on stdio servers.
enabled: boolean
// RAW per-server override. Absent = inherit the global setting, which is a
// distinct state from an explicit false.
enabled_override?: boolean
// RAW per-server mode override. Absent = inherit.
mode_override?: string
image?: string
network_mode?: string
extra_args?: string[]
Expand All @@ -169,6 +177,20 @@ export interface ServerIsolationConfig {
// IsolationDefaults reports the resolved baseline Docker isolation
// values the backend will apply when no per-server override is set.
// Used as placeholders so "empty = inherit" is discoverable in the UI.
// IsolationEffective reports the resolved isolation state of a server and the
// rule that produced it, so the UI can explain "inherits global: docker"
// instead of rendering an ambiguous toggle. Read-only; never sent on PATCH.
export interface ServerIsolationEffective {
mode: string // 'docker' | 'sandbox' | 'none' — what the spawn path branches on
isolated: boolean // actually CONFINED; not simply mode !== 'none' (see 'sandbox-unavailable')
global_mode?: string
inherited: boolean
// 'global' | 'server-mode' | 'server-opt-out' | 'server-opt-in-ignored' |
// 'not-stdio' | 'already-docker' | 'sandbox-unavailable' | 'unsupported-mode'.
// Treat unknown values as 'global'.
source?: string
}

export interface ServerIsolationDefaults {
runtime_type?: string
image?: string
Expand Down Expand Up @@ -220,6 +242,7 @@ export interface Server {
reconnect_count?: number
isolation?: ServerIsolationConfig // Per-server Docker isolation override
isolation_defaults?: ServerIsolationDefaults // Resolved baseline values (read-only)
isolation_effective?: ServerIsolationEffective // Resolved isolation state + why (read-only)
oauth?: {
client_id: string
auth_url: string
Expand Down
20 changes: 20 additions & 0 deletions frontend/src/types/contracts.ts
Original file line number Diff line number Diff line change
Expand Up @@ -172,6 +172,7 @@ export interface Server {
updated: string; // ISO date string
isolation?: IsolationConfig;
isolation_defaults?: IsolationDefaults; // Resolved baseline values (read-only, used as placeholders)
isolation_effective?: IsolationEffective; // Resolved isolation state + why (read-only)
oauth_status?: 'authenticated' | 'expired' | 'error' | 'none'; // OAuth authentication status
token_expires_at?: string; // ISO date string when OAuth token expires
user_logged_out?: boolean; // True if user explicitly logged out (prevents auto-reconnection)
Expand Down Expand Up @@ -224,7 +225,15 @@ export interface OAuthConfig {
}

export interface IsolationConfig {
// EFFECTIVE isolation state, after global + per-server + structural
// resolution. NOT the raw per-server override — read enabled_override for
// that. Always present on stdio servers.
enabled: boolean;
// RAW per-server override. Absent = inherit the global setting, which is a
// distinct state from an explicit false.
enabled_override?: boolean;
// RAW per-server mode override. Absent = inherit.
mode_override?: string;
image?: string;
network_mode?: string;
extra_args?: string[];
Expand All @@ -234,6 +243,17 @@ export interface IsolationConfig {
timeout?: string;
}

// IsolationEffective reports the resolved isolation state of a server and the
// rule that produced it, so the UI can explain "inherits global: docker"
// instead of rendering an ambiguous toggle. Read-only; never sent on PATCH.
export interface IsolationEffective {
mode: string; // 'docker' | 'sandbox' | 'none' — what the spawn path branches on
isolated: boolean; // actually CONFINED; not simply mode !== 'none' (see 'sandbox-unavailable')
global_mode?: string;
inherited: boolean; // no per-server enabled/mode override is set
source?: string; // 'global' | 'server-mode' | 'server-opt-out' | 'server-opt-in-ignored' | 'not-stdio' | 'already-docker' | 'sandbox-unavailable' | 'unsupported-mode'; treat unknown as 'global'
}

// IsolationDefaults reports the resolved baseline Docker isolation
// values the backend will apply when no per-server override is set.
// Populated on server-list / server-get responses; the Web UI uses these
Expand Down
72 changes: 72 additions & 0 deletions frontend/src/utils/isolationState.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
import type { Server, ServerIsolationEffective } from '../types/api'

/**
* A human-readable account of a server's isolation state.
*
* `label` answers "is it isolated"; `detail` answers "why", which is the part
* a bare toggle could never express. Before GH #1142 the API reported the raw
* per-server override flattened to a bool, so a server inheriting the global
* setting looked identical to one explicitly opted out — the UI had no way to
* tell the difference and showed containerised servers as unisolated.
*/
export interface IsolationDescription {
isolated: boolean
/** e.g. "Isolated (docker)" / "Not isolated" */
label: string
/** e.g. "Inherits the global setting (docker)" */
detail: string
}

function modeLabel(mode: string | undefined): string {
return mode && mode !== 'none' ? mode : 'none'
}

/**
* Describes the resolved isolation state, or null when the backend sent no
* resolution block (an older core, or a server with no local process).
*
* Unknown `source` values degrade to the inherit story rather than to a wrong
* claim — the vocabulary is documented as extensible.
*/
export function describeIsolation(server: Server | null | undefined): IsolationDescription | null {
const eff: ServerIsolationEffective | undefined = server?.isolation_effective
if (!eff) return null

const globalMode = modeLabel(eff.global_mode)
const label = eff.isolated ? `Isolated (${modeLabel(eff.mode)})` : 'Not isolated'

let detail: string
switch (eff.source) {
case 'server-mode':
detail = `Mode set for this server: ${modeLabel(eff.mode)}`
break
case 'server-opt-out':
detail = `Turned off for this server (global setting is ${globalMode})`
break
case 'server-opt-in-ignored':
detail = 'Turned on for this server, but global isolation is off — the setting is ignored'
break
case 'not-stdio':
detail = 'No local process to isolate'
break
case 'already-docker':
detail = 'This server already runs Docker itself'
break
case 'sandbox-unavailable':
// The mode is set, but the spawn path degrades to unconfined here (any
// non-Linux host, or a Linux kernel without Landlock).
detail = 'Sandbox mode is set, but this system cannot enforce it — the server runs unconfined'
break
case 'unsupported-mode':
detail = `Isolation mode "${eff.mode}" is not one this version implements — the server runs unconfined`
break
default:
// 'global' and anything unrecognized.
detail = eff.inherited
? `Inherits the global setting (${globalMode})`
: 'Turned on for this server'
break
}

return { isolated: eff.isolated, label, detail }
}
Loading
Loading