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
20 changes: 19 additions & 1 deletion docs/api/rest-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -145,7 +145,14 @@ secrets.

Setting `reveal_secret_headers: true` in
[`mcp_config.json`](../configuration/config-file.md) disables redaction on
all three channels. This is **not normally needed**: the Web UI / macOS
all three channels **for an authenticated admin only** (issue #1167). An
agent token, a server-edition non-admin user and an unauthenticated caller
keep getting masked values no matter how the flag is set. The flag has no
effect at all on the `/events` SSE stream or on the `upstream_stats` block of
`GET /api/v1/status`: those payloads are produced once for a mixed-privilege
audience with no caller to check, so they are always masked. An admin
subscribed to `/events` with the flag on receives the notify-only form of
`servers.changed` and re-fetches the raw values through `GET /api/v1/servers`. This is **not normally needed**: the Web UI / macOS
tray / CLI can edit, delete, and convert-to-secret without ever seeing
the plaintext, because the PATCH endpoint deep-merges (omitted keys are
preserved) and the [`config-to-secret`](#post-apiv1serversnameconfig-to-secret)
Expand Down Expand Up @@ -1067,6 +1074,17 @@ Events include:
- `activity.tool_call.completed` - Tool call finished
- `activity.policy_decision` - Tool call blocked by policy

The stream is rendered **per connection**. An admin subscriber (API key, Web UI,
tray over the unix socket) receives every event exactly as the event bus
published it. For an agent token limited by `allowed_servers` (issue #1166):

| Event | Delivered to a scoped subscriber |
|-------|----------------------------------|
| Names a server outside the scope, through `server_name`, `server`, `target_server` or `affected_entity` — every `activity.*`, `oauth.*` and `security.*` event | **No.** The whole frame is dropped: blanking the name still discloses the mutation, its timing, and how many servers are hidden. |
| `servers.changed` | **Yes, always** — it is coalesced last-write-wins and carries renderable state. The embedded server list is narrowed, `stats` recomputed, and a coalescer extra naming an out-of-scope server is removed. |
| `config.reloaded`, `config.saved`, `secrets.changed` | **No.** They announce mutations of the admin config document, which `GET /api/v1/config` already answers `403` for this caller. |
| Everything else (`active_profile.changed`, `activity.system.*`, `sensitive_data.detected`, `security.scanner_changed`, …) | **Yes**, unchanged: no server identity to scope. |

## Error Responses

```json
Expand Down
5 changes: 5 additions & 0 deletions docs/configuration/upstream-servers.md
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,11 @@ To disable redaction (for debugging only), set `reveal_secret_headers: true`
in `mcp_config.json`. **It's not normally needed**: the editing flow
described below works without ever exposing the plaintext to the client.

The flag reveals raw values only to an **authenticated admin**, and only on
the REST and MCP read doors. It never applies to the `/events` SSE stream or
to `upstream_stats`, and `GET /api/v1/config` is denied to agent tokens
outright (issue #1167).

Since v0.64 (issue #1148) the flag additionally requires an **authenticated**
caller. `/mcp` is deliberately unprotected by default
(`require_mcp_auth: false`), so an unauthenticated MCP client is treated as
Expand Down
87 changes: 85 additions & 2 deletions docs/features/agent-tokens.md
Original file line number Diff line number Diff line change
Expand Up @@ -172,9 +172,92 @@ mcpproxy token create --name deploy-bot --servers github,gitlab --permissions re
mcpproxy token create --name all-access --servers "*" --permissions read
```

Server scoping is enforced at two levels:
Server scoping is enforced at three levels:
1. **Tool discovery** (`retrieve_tools`) — only returns tools from allowed servers
2. **Tool execution** (`call_tool_*`) — blocks calls to out-of-scope servers
3. **Enumeration** — since issue #1166, `allowed_servers` also scopes what the
REST surface will *list*, not only what the token may call. A scoped token
sees only its own servers on `GET /api/v1/servers` (array **and** the
`stats` counters), `GET /api/v1/status` (`upstream_stats`), the `/events`
SSE stream, `GET /api/v1/tools`, `GET /api/v1/index/search`,
`GET /api/v1/diagnostics` / `doctor`, `GET /api/v1/profiles`,
`GET /api/v1/annotations/coverage` and `GET /api/v1/security/scans`.

**The whole `/api/v1/servers/{id}` subtree** answers `404 Server not found`
for a server outside the scope — `tools`, `logs`, `tool-calls`,
`diagnostics`, `scan/status`, `scan/report`, `scan/files`, `integrity`,
`tools/export`, `tools/{tool}/diff` and every sub-resource added later, since
the gate is a middleware on the subtree. It is the *same* `404` a server that
does not exist returns — byte for byte, once the echoed name is normalised —
so the response cannot be used to probe for hidden servers. `logs` matters
most: upstream stderr routinely echoes the argv and env the server process
was launched with.

**The activity, tool-call and usage doors** are scoped to records
attributable to an allowed server: `GET /api/v1/activity`,
`/activity/summary`, `/activity/usage`, `/activity/export`, `/activity/{id}`,
`GET /api/v1/tool-calls` and `/tool-calls/{id}` (plus its `/replay`). The
entitlement is applied inside the query, so `total` and the page always
describe the same record set, and a `?server=` filter narrows *within* the
scope rather than escaping it. Records with no server attribution
(`system_start`, `config_change`, …) are operator-plane events and are not
shown. On `/activity/usage`, aggregates that cannot be re-derived per server
— the tokens-saved headline and the global timeline — are omitted rather than
reported fleet-wide.

**Denied outright (`403`)** to agent tokens, because there is nothing
per-server to project:
- `GET /api/v1/config` — an admin document, and it carries the admin API key.
- `GET /api/v1/stats/tokens` — `per_server_tool_list_sizes` is keyed by every
configured server, and the scalars beside it are fleet-wide.
- `GET /api/v1/sessions`, `GET /api/v1/sessions/{id}` — an MCP session
describes a *client* and the user's workspace, with no server attribution.
- `GET /api/v1/security/overview`, `GET /api/v1/security/queue` — fleet-wide
scan and finding counts, and a queue that names every server waiting to be
scanned. A scoped caller reads its own server's verdict from
`GET /api/v1/servers/{id}/scan/status`, which the subtree gate scopes.
- `GET /api/v1/telemetry/payload` — the heartbeat carries `server_count`,
`connected_server_count`, `tool_count` and `server_docker_isolated_count`:
precisely the count oracle removed from `/status`.
- `GET /api/v1/onboarding/state`, `POST /api/v1/onboarding/mark` (which
echoes the same document) — `configured_server_count` is an inventory size
and `connected_client_ids` is the operator's MCP-client inventory.
- `GET /api/v1/secrets/refs`, `GET /api/v1/secrets/config` — values are
masked, so this is a credential *inventory* rather than a disclosure, but
it names the secrets of servers the caller may not enumerate. A strictly
narrower view of the document `GET /api/v1/config` already denies.

**Withheld rather than denied.** `GET /api/v1/status` stays open — agents
legitimately poll it for liveness — but its `activation` block is omitted for
a scoped caller. `mcp_clients_seen_ever` is the operator's MCP-client
inventory and `retrieve_tools_calls_24h` is an exact deployment-wide counter,
neither of which has a per-server part to project. The key is already absent
when telemetry is unwired, so clients tolerate its absence.

`PUT /api/v1/profiles/active` answers `403`: the active profile is
server-level shared state that decides what the Web UI and tray render, so a
read-scoped credential must not be able to change it. It is gated by the same
`config_write` policy as the other config-level writes.

On the `/events` stream, scoping applies **per event**, not only to the
`servers.changed` server list:

- An event that names a server the token may not enumerate — through
`server_name`, `server`, `target_server` or `affected_entity`, which is
every activity, OAuth and security event — is **not delivered** to that
subscriber at all. It is dropped rather than blanked, because a frame with
the name removed still discloses the mutation, its timing and the number
of servers being hidden.
- `servers.changed` is the exception and is always delivered, because it is
coalesced last-write-wins and carries the state a client renders. Its
server list is narrowed, its `stats` recomputed, and any coalescer extra
that names an out-of-scope server (`"server": "beta"`) is removed.
- `config.reloaded`, `config.saved` and `secrets.changed` announce mutations
of the admin config document and are dropped, matching the `403` on
`GET /api/v1/config`.

Admin subscribers — the API key, the Web UI, the tray over the unix socket —
receive every event unchanged; the stream is rendered per connection.

## Administrative Operations Are Admin-Only

Expand All @@ -186,7 +269,7 @@ Denied to agent tokens on both surfaces:
- **Security state**: quarantine, unquarantine, tool approve/block, and the security scanner (scan start/cancel, security approve/reject)
- **Config & registries**: applying/patching configuration (which can add/remove/enable/disable servers) and mutating registry sources — an agent must not bypass the per-server gate by rewriting config or a registry wholesale

On the MCP surface (`upstream_servers`, `quarantine_security`) these return a tool error; on the REST surface (mutating `/api/v1/servers/...`, `/api/v1/config/...`, and `/api/v1/registries/...` routes) they return **`403 Forbidden`** (`operation requires admin access`). Read-only operations stay available to scoped tokens: `upstream_servers` `list`/`tail_log`, `GET /api/v1/servers`, per-server diagnostics, config/registry reads, and `GET /api/v1/index/search` (which honors quarantine — a quarantined server's tools are withheld from search on every surface).
On the MCP surface (`upstream_servers`, `quarantine_security`) these return a tool error; on the REST surface (mutating `/api/v1/servers/...`, `/api/v1/config/...`, and `/api/v1/registries/...` routes) they return **`403 Forbidden`** (`operation requires admin access`). Read-only operations stay available to scoped tokens: `upstream_servers` `list`/`tail_log`, `GET /api/v1/servers`, per-server diagnostics, registry reads, and `GET /api/v1/index/search` (which honors quarantine — a quarantined server's tools are withheld from search on every surface). Those reads are **scope-filtered** as described above. `GET /api/v1/config` is the exception: it is an admin document (it carries the global `api_key`, every server's credentials, and a second enumeration of server names under `profiles[].servers`), so it returns `403` for an agent token rather than a filtered view.

## Profile Pinning

Expand Down
12 changes: 10 additions & 2 deletions frontend/src/views/Security.vue
Original file line number Diff line number Diff line change
Expand Up @@ -580,6 +580,12 @@ const historyPage = ref(1)
const HISTORY_PAGE_SIZE = 20
const historyTotalPages = computed(() => Math.max(1, Math.ceil(historyTotal.value / HISTORY_PAGE_SIZE)))

// The sentinel the core substitutes for a literal scanner env value on every
// API serialization path (scanner.RedactedEnvValue, #1166 round 10 P3). It is
// truthy on purpose so "is this variable set?" still answers correctly here;
// saveConfig must never send it back, or the mask would overwrite the secret.
const REDACTED_ENV_VALUE = '***'

// Scan All state
const scanAllRunning = ref(false)
const scanAllStartTime = ref<number>(0)
Expand Down Expand Up @@ -923,10 +929,12 @@ function addCustomEnv() {

async function saveConfig() {
if (!configScanner.value) return
// Only send non-empty values that aren't keyring references (new values)
// Only send non-empty values that aren't keyring references or the core's
// redaction sentinel (new values). Sending the sentinel back would store
// '***' as the scanner's real API key.
const toSend: Record<string, string> = {}
for (const [k, v] of Object.entries(configValues.value)) {
if (v && !v.startsWith('${keyring:')) {
if (v && v !== REDACTED_ENV_VALUE && !v.startsWith('${keyring:')) {
toSend[k] = v
}
}
Expand Down
2 changes: 1 addition & 1 deletion frontend/src/views/settings/fields.ts
Original file line number Diff line number Diff line change
Expand Up @@ -214,7 +214,7 @@ export const SECURITY_FIELDS: SettingField[] = [
{
key: 'reveal_secret_headers',
label: 'Show secret headers (debug)',
help: 'Normally mcpproxy redacts Authorization / API-Key header values in responses and logs. Turning this on shows them in clear text — debugging only.',
help: 'Normally mcpproxy redacts Authorization / API-Key header values in responses and logs. Turning this on shows them in clear text to an authenticated ADMIN only — agent tokens stay masked, and the /events stream and upstream_stats are always masked. Debugging only.',
control: 'toggle',
danger: {
confirmValue: true,
Expand Down
70 changes: 70 additions & 0 deletions internal/auth/context.go
Original file line number Diff line number Diff line change
Expand Up @@ -174,3 +174,73 @@ func AdminUserContext(userID, email, displayName, provider string) *AuthContext
Provider: provider,
}
}

// RevealSecretsAllowed is THE shared predicate for "may this caller be handed
// raw credential values?" (issues #1148 and #1167).
//
// Both halves are required and neither is sufficient:
//
// - flagEnabled — the operator's `reveal_secret_headers` opt-in, and
// - CanRevealSecrets() — an authenticated, non-anonymous admin identity.
//
// #1167: the MCP door already ANDed the two; the REST list, the whole-config
// read, both doctor doors and the per-server diagnostics door checked the flag
// ALONE, so a read-only agent token scoped to one server received every other
// server's Authorization header, URL query credential, argv secret and env
// secret in plaintext the moment an operator turned the flag on. Every
// request-scoped door now reads the answer from here so they cannot drift
// apart again.
//
// Fails CLOSED on absence: a nil ctx (an in-process or future background
// caller) and a ctx with no AuthContext both yield false. A payload with no
// caller has no identity to check, so it gets masked values.
func RevealSecretsAllowed(ctx context.Context, flagEnabled bool) bool {
if !flagEnabled || ctx == nil {
return false
}
return AuthContextFromContext(ctx).CanRevealSecrets()
}

// CanEnumerateServer is THE shared predicate for "may this caller SEE that a
// server named `name` exists?" (issue #1166).
//
// The MCP door has filtered upstream enumeration through
// AuthContext.CanAccessServer since Spec 028; the REST doors never did, so a
// token scoped to `allowed_servers: ["alpha"]` still enumerated every
// configured server on GET /api/v1/servers, /api/v1/config, /api/v1/tools,
// /api/v1/status and the /events stream. Reads on both surfaces now answer
// from one place.
//
// Fails OPEN on absence, deliberately and in exact mirror of
// AuthorizeServerOp: apiKeyAuthMiddleware forwards a request with NO
// AuthContext whenever the controller has no usable config (the testing /
// bootstrap passthrough), and treating that as "sees nothing" would blank the
// server list for every such caller. Absence of a token must not be stricter
// than a scoped token — it must be treated exactly as today's unrestricted
// behaviour. The unauthenticated /mcp back-compat context (AnonymousContext)
// is admin-typed and likewise unrestricted here; hiding a server's NAME from
// it is not the boundary this predicate defends, revealing its CREDENTIALS is,
// and that is what RevealSecretsAllowed refuses it.
func CanEnumerateServer(ctx context.Context, name string) bool {
if ctx == nil {
return true
}
ac := AuthContextFromContext(ctx)
if ac == nil || ac.IsAdmin() {
return true
}
return ac.CanAccessServer(name)
}

// IsScopedCaller reports whether ctx carries a non-admin identity whose
// visibility is limited by AllowedServers. It is the cheap short-circuit for
// handlers that would otherwise copy a payload just to filter it: an admin (or
// an absent context, per CanEnumerateServer) sees everything, so the payload
// can be forwarded untouched.
func IsScopedCaller(ctx context.Context) bool {
if ctx == nil {
return false
}
ac := AuthContextFromContext(ctx)
return ac != nil && !ac.IsAdmin()
}
Loading
Loading