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

11 KiB

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.