Create the server token at install and document the security boundary
This commit is contained in:
@@ -15,6 +15,9 @@ service manager directly. Legacy Python-managed installations require an explici
|
||||
`PIPELINES_PREFIX`; no configuration is inferred from the executable's location.
|
||||
For source development, use `go run ./cmd/pipelines help`; start the native server
|
||||
separately. Set `PIPELINES_URL` or pass `--url` to select another server.
|
||||
A loopback server started with `-token-file` requires the shared token; the CLI
|
||||
reads it from `PIPELINES_SERVER_TOKEN_FILE` or `~/.config/pipelines/server-token`
|
||||
and sends it only to loopback URLs (`docs/notes/security-boundary.md`).
|
||||
|
||||
## Dashboard and status
|
||||
|
||||
|
||||
@@ -30,7 +30,11 @@ additive conflicts.
|
||||
websocket. Home-folder access uses `expandHomePath`, `resolveInsideHome` and
|
||||
`specialFilesystem`; symlinks are operated on, not followed. Internal
|
||||
endpoints (for example `/mcp`) must not be reachable through the web proxy;
|
||||
add a proxy test. Typed input, passwords and tokens are never logged or
|
||||
add a proxy test. The server answers only loopback `Host`s, refuses
|
||||
`/connect` with an `Origin`, and requires the shared server token
|
||||
(`docs/notes/security-boundary.md`); a new local client of the server
|
||||
sends the token, and the peer relay's address policy covers new remote
|
||||
paths. Typed input, passwords and tokens are never logged or
|
||||
stored. Credentials never cross machines.
|
||||
- **Bounds.** Every retained buffer, list and payload has a limit (for example
|
||||
1 MiB output, 50 runs, 512 KiB views, 5 notifications a minute) and reports
|
||||
|
||||
@@ -0,0 +1,187 @@
|
||||
# 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.
|
||||
@@ -38,6 +38,12 @@ def server_address(config):
|
||||
return f"{config.get('bind_address') or '127.0.0.1'}:{config['server_port']}"
|
||||
|
||||
|
||||
def server_token_env(config):
|
||||
"""PIPELINES_SERVER_TOKEN_FILE for the server, the web proxy and the CLI."""
|
||||
path = (config.get("web") or {}).get("server_token_file")
|
||||
return {"PIPELINES_SERVER_TOKEN_FILE": path} if path else {}
|
||||
|
||||
|
||||
def mdns_args(config):
|
||||
"""The LAN port the server advertises over mDNS.
|
||||
|
||||
@@ -416,6 +422,9 @@ def supervise(config):
|
||||
PIPELINES_NTFY_PUBLIC_URL=config["public_url"],
|
||||
PIPELINES_NTFY_TOKEN_FILE=str(root / "secrets/publisher-token"))
|
||||
env.pop("PIPELINES_NTFY_TOKEN", None)
|
||||
# The server requires, and the proxy and every child CLI send, the
|
||||
# shared token in this file (installs from before it have none).
|
||||
env.update(server_token_env(config))
|
||||
server_command = [str(root / "bin/pipelines-server"), "-addr",
|
||||
server_address(config), "-db", str(root / "data/pipelines.db")]
|
||||
if config.get("allow_authoring") is True:
|
||||
@@ -520,6 +529,7 @@ def main():
|
||||
env.update(config.get("opencode_env", {}))
|
||||
env.update(PIPELINES_URL=f"ws://127.0.0.1:{config['server_port']}/connect",
|
||||
PIPELINES_OPENCODE=config["opencode"], PATH=config["path"])
|
||||
env.update(server_token_env(config))
|
||||
os.execve(binary, [binary, *(forwarded or ["tui"])], env)
|
||||
return
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
|
||||
@@ -359,6 +359,7 @@ class Setup:
|
||||
auth.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
|
||||
self._write_atomic(auth, (json.dumps({"password": password,
|
||||
"secret": secrets.token_urlsafe(48)}) + "\n").encode(), 0o600)
|
||||
server_token = self.ensure_server_token(auth.parent / "server-token")
|
||||
target = prefix / "lib/web"
|
||||
shutil.copytree(Path(__file__).resolve().parents[1] / "web", target, dirs_exist_ok=True,
|
||||
ignore=shutil.ignore_patterns("test", "node_modules", ".DS_Store"))
|
||||
@@ -366,8 +367,24 @@ class Setup:
|
||||
updates.mkdir(parents=True, exist_ok=True)
|
||||
return {"node": node, "script": str(target / "serve.mjs"),
|
||||
"auth_file": str(auth), "host": args.web_host, "port": args.web_port,
|
||||
"server_token_file": str(server_token),
|
||||
"root": self.install_app_web(prefix, args, web_build), "updates": str(updates)}
|
||||
|
||||
def ensure_server_token(self, path):
|
||||
"""The proxy/CLI ↔ server shared secret (docs/notes/security-boundary.md).
|
||||
|
||||
Created once (0600, beside the web auth file) and kept across reinstalls."""
|
||||
if path.is_symlink() or (path.exists() and not path.is_file()):
|
||||
raise ValueError(f"Refusing a server token that is not a regular file: {path}")
|
||||
if path.exists():
|
||||
if path.stat().st_mode & 0o077 or path.stat().st_uid != os.getuid():
|
||||
raise ValueError(f"Server token must be owned by you and private (chmod 600): {path}")
|
||||
if len(path.read_text().strip()) >= 32:
|
||||
return path
|
||||
path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
|
||||
self._write_atomic(path, (secrets.token_urlsafe(48) + "\n").encode(), 0o600)
|
||||
return path
|
||||
|
||||
def choose_password(self):
|
||||
"""The web sign-in password for a new computer, chosen by the operator.
|
||||
|
||||
|
||||
@@ -281,6 +281,7 @@ class ManageNativeTests(unittest.TestCase):
|
||||
config = self.config(root)
|
||||
config["web"] = {"node": "/bin/node", "script": "/prefix/lib/web/serve.mjs",
|
||||
"host": "0.0.0.0", "port": 8082, "auth_file": "/private/auth.json",
|
||||
"server_token_file": "/private/server-token",
|
||||
"root": str(root / "lib/app-web"), "updates": "/prefix/lib/app-updates"}
|
||||
ntfy, server, web = MagicMock(), MagicMock(), MagicMock()
|
||||
ntfy.poll.return_value = None
|
||||
@@ -299,6 +300,10 @@ class ManageNativeTests(unittest.TestCase):
|
||||
"--updates", "/prefix/lib/app-updates"])
|
||||
self.assertNotIn("PIPELINES_WEB_AUTH", call.kwargs["env"])
|
||||
self.assertEqual(call.kwargs["env"]["PIPELINES_WEB_AUTH_FILE"], "/private/auth.json")
|
||||
# The server requires and the proxy sends the shared server token.
|
||||
for spawned in popen.call_args_list:
|
||||
self.assertEqual(spawned.kwargs["env"]["PIPELINES_SERVER_TOKEN_FILE"], "/private/server-token")
|
||||
self.assertEqual(manage.server_token_env({"web": None}), {})
|
||||
web.terminate.assert_called_once()
|
||||
server.terminate.assert_called_once()
|
||||
ntfy.terminate.assert_called_once()
|
||||
|
||||
@@ -257,6 +257,24 @@ class SetupNativeTests(unittest.TestCase):
|
||||
self.assertTrue((prefix / "lib/web/src/proxySecurity.js").is_file())
|
||||
self.assertEqual(web["port"], 8082)
|
||||
|
||||
def test_server_token_is_created_private_once_beside_the_web_auth(self):
|
||||
with tempfile.TemporaryDirectory() as directory:
|
||||
installer = self.installer(directory, Recorder())
|
||||
prefix = Path(directory) / "prefix"
|
||||
installer.prepare_layout(prefix)
|
||||
with patch.object(setup_native.shutil, "which", side_effect=self.which_all()):
|
||||
web = installer.configure_web(prefix, setup_native.arguments([]))
|
||||
token = Path(web["server_token_file"])
|
||||
before = token.read_bytes()
|
||||
installer.configure_web(prefix, setup_native.arguments([]))
|
||||
self.assertEqual(token.parent, Path(web["auth_file"]).parent)
|
||||
self.assertEqual(token.read_bytes(), before)
|
||||
self.assertEqual(token.stat().st_mode & 0o777, 0o600)
|
||||
self.assertGreaterEqual(len(before.strip()), 32)
|
||||
token.chmod(0o644)
|
||||
with self.assertRaises(ValueError):
|
||||
installer.ensure_server_token(token)
|
||||
|
||||
def test_new_web_password_must_be_chosen(self):
|
||||
with tempfile.TemporaryDirectory() as directory:
|
||||
installer = self.installer(directory, Recorder())
|
||||
|
||||
Reference in New Issue
Block a user