Files
pipelines/docs/notes/security-boundary.md
T

188 lines
11 KiB
Markdown

# Security boundary: the Go server's front door and the peer relay
Fixes from the 2026-11-10 security review (one HIGH, two LOW).
## Threats
1. **HIGH: DNS rebinding reached the unauthenticated Go API.** The server
(`127.0.0.1:8080`) had no authentication. `websocket.Accept` only checks
`Origin == Host`, so a malicious page that rebinds its own name to
127.0.0.1 sent a matching Host and Origin and got `101`. From there it could
send `terminal_open`/`terminal_input` (a shell as the operator).
Reproduced on the pre-fix build:
`curl -H "Host: rebind.example:57577" -H "Origin: http://rebind.example:57577" …/connect`
returned `101`, and `/healthz` answered for any Host.
2. **LOW: any local process had full control.** Other OS users, containers
(`host.docker.internal`) and anything else that could reach loopback were
trusted.
3. **LOW: peer relay SSRF.** Any signed-in user could register
`ws://<any host>/connect`. The proxy then fetched `/login`, `/files`,
`/artifacts`, `/updates` and `/connect` from that host, including loopback
services and `169.254.169.254`.
## Fix
### Go server request boundary (`internal/server/request_boundary.go`)
Every route goes through `guardRequests` before the mux: `/connect`, `/files`,
`/chat-uploads`, `/artifacts`, `/discovery`, `/mcp/chat/…` and `/healthz`.
- **Host.** If the connection arrived on a loopback local address, `Host` must
be a loopback literal (`127.x.x.x`, `localhost`, `[::1]`) with the port the
connection reached. Anything else gets `421 Misdirected Request`. A
connection that arrived on another interface can only exist when the server
was explicitly bound beyond loopback (`bind_address`, Docker). Its Host is
not checked; the token still is.
- **Origin.** `/connect` refuses any request that carries `Origin` with `403`.
Browsers always send it on a WebSocket upgrade. The web proxy strips it. The
CLI and TUI (`coder/websocket` Dial) and the native app (`dart:io`
`WebSocket.connect`) send none.
- **Token.** When the server runs with `-token-file` (or
`PIPELINES_SERVER_TOKEN_FILE`), every request must carry
`X-Pipelines-Token: <token>`. A missing or wrong token gets `401`, compared
in constant time. There are two exemptions:
- `/mcp/chat/<token>`: harnesses register the URL and cannot add headers.
The endpoint already has 64-character per-chat tokens, a loopback check
and a no-Origin check.
- `/healthz`: a bare `{"healthy":…}`, still subject to the Host rule.
The header is removed before any handler sees it. The server exports the
file's absolute path (never the token) as `PIPELINES_SERVER_TOKEN_FILE` to
the stages, chats and CLI calls it launches. A server started without a
token file logs that, and only the Host and Origin rules apply. Docker and
scratch servers work this way.
### The shared secret (`internal/servertoken`, `web/src/serverToken.js`)
- **File:** a new private file, `server-token`, next to the web sign-in file.
By default that is `~/.config/pipelines/server-token`, or
`$XDG_CONFIG_HOME/pipelines/server-token`. It holds 64 URL-safe characters
(`secrets.token_urlsafe(48)`).
- The web auth file's secret is not reused. Rotating the cookie secret or
password (`scripts/password.py`) must not break the server link, and the
other way round.
- **Permission model:** the file is mode 0600, owned by the operator, and its
directory is 0700. Readers refuse a symlink, a non-regular file, a file
owned by another user, any group/other bits, or a token shorter than 32
characters:
- the Go server and CLI (`servertoken.Read`)
- the proxy (`serverToken`)
- the installer
Processes of the same OS user can read it, which is the trust boundary.
Other users, containers without the file mounted, and browsers cannot.
- **Installer:** `./install` (`scripts/setup-native.py` `ensure_server_token`)
creates the file if it is missing and keeps it on reinstall. It records the
path in the manifest as `web.server_token_file`. `scripts/manage.py` sets
`PIPELINES_SERVER_TOKEN_FILE` for the server, the proxy (whose environment
is derived from the server's) and `pipelines` CLI/TUI invocations. A
manifest from before this change has no key, and nothing changes until
`./install` runs again.
### How each client authenticates
| Client | How |
|---|---|
| Web proxy (`web/serve.mjs`) | Adds `X-Pipelines-Token` to `/connect`, `/files`, `/artifacts/`, `/chat-uploads` and `/api/discovery` upstream requests. It drops any client-supplied copy first, sets `Host` to the upstream loopback address and strips `Origin`. Browsers authenticate to the proxy with the sign-in cookie. If the token file is unreadable or unsafe, the proxy answers 503. |
| CLI, TUI, automation (`internal/client.Dial`) | Reads `PIPELINES_SERVER_TOKEN_FILE`, else the default path, and sends the header only when the dialed URL is loopback (`127.x`, `::1`, `localhost`). Remote servers are reached through their own web proxy, so the token never leaves the machine. With no file it sends nothing. An unsafe or explicitly named but missing file is an error. |
| Stages and chats launched by the server | Inherit `PIPELINES_SERVER_TOKEN_FILE` from the server, and their `pipelines` calls go through `client.Dial`. Chat hosts that outlived a restart fall back to the default path. |
| Harness MCP registration | `/mcp/chat/<per-chat token>` on the loopback base, with no server token (exempt). |
| Native app and browser app | Always through the web proxy (cookie). The app never dials 8080 directly. |
| Peer relay to another machine | Uses that machine's proxy sign-in cookie. The local server token is never forwarded (tested). |
| `manage.py` health checks | `/healthz` (exempt). |
### Peer relay address policy (`web/src/peerAddress.js`)
- **Allowed by default:**
- tailnet addresses: `100.64.0.0/10` and `fd7a:115c:a1e0::/48`
- private LAN addresses: RFC 1918 and IPv6 unique-local `fc00::/7`
- public addresses, only for `*.ts.net` names (Funnel) or hosts that this
machine's own `/api/discovery` returned
- **Always refused:** unspecified, multicast and reserved addresses.
- **Refused unless widened:** loopback (`127/8`, `::1`, `::ffff:127…`),
link-local (`169.254/16`, `fe80::/10`), metadata (`169.254.169.254`,
Tailscale's `100.100.100.100` and `fd7a:115c:a1e0::53`, AWS
`fd00:ec2::/32`) and other public addresses.
- **Explicit widening:** `PIPELINES_PEER_ALLOW=loopback,public,link-local,metadata`
or `any`, set in the proxy's environment.
- **DNS pinning:** each registration and each relayed request resolves the
name once and checks every answer; one refused answer refuses the name. The
connection then goes to the checked address through the request's `lookup`.
`Host` and TLS SNI stay the original name. A rebinding answer between check
and connect cannot redirect it.
- **Registration responses:**
- A registration whose addresses are all refused gets `400` with
`error: "Server address is not allowed (<category>)"` and
`refused_endpoints`. No request is sent.
- When only some addresses are refused, they are listed in
`refused_endpoints`.
- `insecure_transport: true` is set on `POST` and `GET /api/peers/<id>` when
a `ws://` endpoint is used, because the password and cookie travel as
plain HTTP. **App follow-up (not done):** show a warning before sending a
password when `insecure_transport` is set.
## Residual risks
- A local process of the same user can read the token. That user is the trust
boundary.
- If the server is down and another local user binds its port, the CLI would
send the token to that impostor. Keep the service running. A
challenge-response handshake would close this gap but is out of scope here.
- A server bound beyond loopback skips the Host rule for non-loopback
connections. The token and Origin rules still protect it when a token is
configured; an unconfigured server bound beyond loopback remains open.
## Verification
- Go (`umask 022; go test ./...`): all packages ok. New tests:
- `internal/server` `TestBoundary*`: rebinding and other Hosts get 421 on
every route, loopback Hosts are accepted, Origin on `/connect` gets 403,
the token is required and accepted, `/healthz` and `/mcp` are exempt, the
token never reaches handlers, and a library dial sends no Origin.
- `internal/client` `TestDial*`: the CLI sends the token to 127.0.0.1 and
localhost and never to remote hosts, and it refuses an unsafe file.
- `internal/servertoken`.
- `internal/installation` `TestEnvironmentPointsLocalClientsAtTheServerToken`.
- Web (`cd web && node --test test/`): 26/26 pass. New tests:
- `serverToken.test.mjs`: the proxy sends the token on files, artifacts,
uploads, discovery and the upgrade, replaces a forged one, and the relay
never forwards it.
- `peerAddress.test.mjs`: classification; loopback, metadata, link-local
and public refused; tailnet, LAN, ts.net and discovered hosts accepted;
pinning; a refused peer is never contacted; `insecure_transport`.
- Installer: `python3 -m unittest test_manage_native test_setup_native`, 78
tests OK.
- Scratch end-to-end: isolated HOME and DB, OS-chosen ports, server with
`PIPELINES_SERVER_TOKEN_FILE`, proxy from this tree.
```
1 rebinding upgrade (Host+Origin rebind.example): 421
2 rebinding upgrade even with the token: 421
3 other Host 10.0.0.5:<port> on /healthz: 421
4 other Host on /files with token: 421
5 loopback upgrade without token: 401
6 loopback /discovery without token: 401
7 loopback upgrade with token + same-host Origin: 403
8 loopback upgrade with token (no Origin): 101
9 /healthz (token-exempt) on localhost:<port>: 200
--- CLI with the token file (default path): {"type":"pong","id":"cli-1",…}
--- CLI without a token file: {"error":"failed to WebSocket dial: expected handshake response status code 101 but got 401","type":"error"}
--- browser flow through the proxy:
proxy sign-in: 303
proxy /files (reaches server, token added): 404 file not found
proxy /api/discovery: 200
proxy /connect ping reply: pong ok
proxy /connect from cross-origin page: refused
```
## Deploying
1. Run `./install`. It creates `~/.config/pipelines/server-token` (0600) if
missing, records `web.server_token_file` in the manifest and copies the
new `manage.py`, `serve.mjs` and binaries.
2. Restart the service when no run or chat is active. The supervisor starts
the server and the proxy together, both with `PIPELINES_SERVER_TOKEN_FILE`,
so they switch at once.
3. CLI and TUI sessions that are already open hold an old connection; new
invocations read the token.