From 0904a65d826b91cdbab6271ea05197ffc80b3b4d Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Thu, 12 Nov 2026 16:52:06 -0600 Subject: [PATCH] fix(server): local board boundary identifies agent processes on Linux it cannot inspect (#21209) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - In `local_trusted` mode, the operator's own local processes get implicit board access without credentials > - #21181 added a local board boundary. It refuses implicit board access to requests that come from an agent run's process tree > - On Linux CI hosts, the boundary sometimes did not decide a loopback request. It logged a warning and kept the earlier permissive behavior for that request > - The cause was not IPv6. IPv4 and IPv6 loopback lookups worked. The gap was a connection that belonged to a same-user process that the server cannot inspect > - This pull request makes the Linux boundary decide those connections from the process ancestry that the server can read, and refuse them when that ancestry is not clearly the operator's > - The benefit is that the local board boundary now holds on Linux for IPv4 and IPv6 loopback, and the operator's browser and CLI keep working ## Linked Issues or Issue Description Refs #21181 **What happened?** On Linux CI hosts, the local board boundary sometimes could not attribute a loopback request to a process. It then logged that it could not identify the local process and kept the earlier permissive behavior for that request. In one chat eval cohort, 37 of 191 server logs contained this warning. The warning is logged once per server process. **Expected behavior** The boundary decides every uncredentialed loopback request on Linux. A request from an agent run gets no implicit board access. Requests from the operator's browser and CLI keep implicit board access. **Actual behavior** Some requests on Linux were not decided by the boundary, and they got implicit board access. ## What Changed - The Linux inspector now records which same-user processes it cannot inspect. Before, it only recorded that one existed. - The Linux TCP table lookup now also returns the socket's owner UID. It covers `/proc/net/tcp` and `/proc/net/tcp6`, including IPv4-mapped addresses. - If no inspectable process owns the connection, the server reads the TCP tables again. If the connection is gone, has changed, or belongs to a different user, the request is refused. - If the connection is still open and same-user, the server checks every process it cannot inspect. Implicit board access stays only if each one has a readable parent chain that does not belong to an agent run. Otherwise the request is refused. - The "cannot identify" fallback now applies only when the platform has no inspector, or when Linux cannot read the TCP tables. The server keeps logging a warning in that case. - `doc/DEPLOYMENT-MODES.md` describes the new Linux behavior. **How the operator is recognized** - Browser and CLI processes are normal same-user processes. The server reads their open sockets and environment, so their requests are classified as before. - A browser helper process that the server cannot inspect is still the operator when its readable parent chain leads to the browser and has no agent-run markers. - The server's own requests and requests from the server's ancestors stay the operator, as before. - Connections owned by other users were refused before, and they are still refused. ## Verification - `pnpm --dir server exec vitest run src/__tests__/local-agent-process-boundary.test.ts` passes on macOS (15 passed, 10 Linux-only skipped). - The same file ran on Linux (Docker, `node:24-bookworm`, non-root user, IPv6 loopback on). Result: 25 passed. - Red check on Linux with the previous boundary and the new tests: the agent-run cases for processes the server cannot inspect failed for both `127.0.0.1` and `::1`. The operator cases passed. - New Linux-only tests run real processes over `127.0.0.1` and `::1`: - an operator process keeps board access - an agent-run process is refused - an operator process the server cannot inspect keeps board access - an agent-run process the server cannot inspect is refused - New platform-independent tests cover the classification rules and the `/proc/net/tcp6` fixture parsing. - A paid chat-feature run on Linux CI, with temporary diagnostic logging on a separate branch, checks the server logs for the warning and for refused operator requests. The results will be in a PR comment. ## Risks - A rare operator tool that the server cannot inspect, and whose parent chain the server cannot read, now loses implicit board access. Such a tool can use a board API key. - The extra TCP table read happens only when a connection has no inspectable owner. Normal requests do no extra work. - Platforms without process inspection keep the previous behavior. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Anthropic Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use (shell, file edits, Docker on Linux) and extended reasoning. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 --- doc/DEPLOYMENT-MODES.md | 2 +- .../local-agent-process-boundary.test.ts | 135 +++++++++++++++++- .../local-agent-process-boundary.ts | 79 ++++++---- 3 files changed, 180 insertions(+), 36 deletions(-) diff --git a/doc/DEPLOYMENT-MODES.md b/doc/DEPLOYMENT-MODES.md index 0375a6c23c9..eb8791aaf2a 100644 --- a/doc/DEPLOYMENT-MODES.md +++ b/doc/DEPLOYMENT-MODES.md @@ -83,7 +83,7 @@ Paperclip now treats **bind** as a separate concern from auth: - loopback-only host binding - no human login flow - optimized for fastest local startup -- implicit board access belongs to the operator's own local processes. On Linux and macOS, a request that comes from inside an agent run's process tree receives no implicit board access and must authenticate with the run's own credentials. Other platforms keep the previous behavior. +- implicit board access belongs to the operator's own local processes. On Linux and macOS, a request that comes from inside an agent run's process tree receives no implicit board access and must authenticate with the run's own credentials. On Linux, a request whose process the server cannot inspect receives implicit board access only when every same-user process that the server cannot inspect has a readable operator parent chain outside any agent run. Requests over IPv4 and IPv6 loopback are covered. If the platform has no process inspection, or `/proc/net/tcp` and `/proc/net/tcp6` cannot be read, the server keeps the previous behavior and logs a warning. Other platforms keep the previous behavior. ## `authenticated + private` diff --git a/server/src/__tests__/local-agent-process-boundary.test.ts b/server/src/__tests__/local-agent-process-boundary.test.ts index f58843cf71c..94ac1feadaa 100644 --- a/server/src/__tests__/local-agent-process-boundary.test.ts +++ b/server/src/__tests__/local-agent-process-boundary.test.ts @@ -11,12 +11,12 @@ import { createLocalAgentProcessBoundary, type LocalProcessInspector, findPeerPidInDarwinNetstat, - findSocketInodeInProcNet, + findSocketInProcNet, } from "../middleware/local-agent-process-boundary.js"; const supported = process.platform === "linux" || process.platform === "darwin"; -function startServer(serverEnvironment: NodeJS.ProcessEnv): Promise<{ server: Server; url: string }> { +function startServer(serverEnvironment: NodeJS.ProcessEnv, host = "127.0.0.1"): Promise<{ server: Server; url: string }> { const app = express(); app.use(actorMiddleware({} as Db, { deploymentMode: "local_trusted", @@ -26,9 +26,9 @@ function startServer(serverEnvironment: NodeJS.ProcessEnv): Promise<{ server: Se res.json({ type: req.actor.type, source: req.actor.source ?? null }); }); return new Promise((resolve) => { - const server = app.listen(0, "127.0.0.1", () => { + const server = app.listen(0, host, () => { const { port } = server.address() as AddressInfo; - resolve({ server, url: `http://127.0.0.1:${port}/api/whoami` }); + resolve({ server, url: `http://${host.includes(":") ? `[${host}]` : host}:${port}/api/whoami` }); }); }); } @@ -106,16 +106,87 @@ describe.skipIf(!supported)("implicit local board access from local processes", }); }); +const nonDumpableFetch = [ + "import ctypes, sys, urllib.request", + "ctypes.CDLL(None).prctl(4, 0, 0, 0, 0)", + "sys.stdout.write(urllib.request.urlopen(sys.argv[1]).read().decode())", +].join("\n"); + +const launchNonDumpableFetch = [ + "const { execFileSync } = require('node:child_process');", + "const env = process.argv[3] === 'clear' ? { PATH: process.env.PATH } : process.env;", + "process.stdout.write(execFileSync('python3', ['-c', process.argv[1], process.argv[2]], { env }));", +].join("\n"); + +describe.skipIf(process.platform !== "linux").each(["127.0.0.1", "::1"])( + "implicit local board access from Linux processes over %s loopback", + (host) => { + let server: Server; + let url: string; + + beforeAll(async () => { + ({ server, url } = await startServer({}, host)); + }); + + afterAll(async () => { + await new Promise((resolve) => server.close(resolve)); + }); + + it("keeps board access for an operator process", async () => { + await expect(runChild(process.execPath, ["-e", fetchScript, url], operatorEnvironment())) + .resolves.toEqual({ type: "board", source: "local_implicit" }); + }); + + it("refuses board access to an agent-run process", async () => { + await expect(runChild(process.execPath, ["-e", fetchScript, url], { + ...operatorEnvironment(), + PAPERCLIP_RUN_ID: "44444444-4444-4444-8444-444444444444", + })).resolves.toEqual({ type: "none", source: "none" }); + }); + + it("keeps board access for an operator process the server cannot inspect", async () => { + await expect(runChild(process.execPath, ["-e", launchNonDumpableFetch, nonDumpableFetch, url, "keep"], operatorEnvironment())) + .resolves.toEqual({ type: "board", source: "local_implicit" }); + }); + + it("refuses board access to an agent-run process the server cannot inspect", async () => { + await expect(runChild(process.execPath, ["-e", launchNonDumpableFetch, nonDumpableFetch, url, "clear"], { + ...operatorEnvironment(), + PAPERCLIP_AGENT_ID: "55555555-5555-4555-8555-555555555555", + })).resolves.toEqual({ type: "none", source: "none" }); + }); + + it("refuses board access to an uninspectable agent-run process without a readable parent", async () => { + await expect(runChild("python3", ["-c", nonDumpableFetch, url], { + ...operatorEnvironment(), + PAPERCLIP_RUN_ID: "66666666-6666-4666-8666-666666666666", + })).resolves.toEqual({ type: "none", source: "none" }); + }); + }, +); + describe("local process identification", () => { - it("finds the client socket inode in a Linux TCP table", () => { + it("finds the client socket in a Linux TCP table", () => { const table = [ " sl local_address rem_address st tx_queue rx_queue tr tm->when retrnsmt uid timeout inode", " 0: 0100007F:0C1C 00000000:0000 0A 00000000:00000000 00:00000000 00000000 1000 0 111 1 0 100 0 0 10 0", " 1: 0100007F:D431 0100007F:0C1C 01 00000000:00000000 00:00000000 00000000 1000 0 222 1 0 20 4 30 10 -1", " 2: 0100007F:0C1C 0100007F:D431 01 00000000:00000000 00:00000000 00000000 1000 0 333 1 0 20 4 30 10 -1", ].join("\n"); - expect(findSocketInodeInProcNet(table, { address: "127.0.0.1", port: 54321 }, { address: "127.0.0.1", port: 3100 })) - .toBe("222"); + expect(findSocketInProcNet(table, { address: "127.0.0.1", port: 54321 }, { address: "127.0.0.1", port: 3100 })) + .toEqual({ inode: "222", uid: 1000 }); + }); + + it("finds IPv6 and IPv4-mapped loopback client sockets in a Linux TCP6 table", () => { + const table = [ + " sl local_address remote_address st tx_queue rx_queue tr tm->when retrnsmt uid timeout inode", + " 0: 00000000000000000000000001000000:D431 00000000000000000000000001000000:0C1C 01 00000000:00000000 00:00000000 00000000 1001 0 444 1 0 20 4 30 10 -1", + " 1: 0000000000000000FFFF00000100007F:D432 0000000000000000FFFF00000100007F:0C1C 01 00000000:00000000 00:00000000 00000000 1002 0 555 1 0 20 4 30 10 -1", + ].join("\n"); + expect(findSocketInProcNet(table, { address: "::1", port: 54321 }, { address: "::1", port: 3100 })) + .toEqual({ inode: "444", uid: 1001 }); + expect(findSocketInProcNet(table, { address: "127.0.0.1", port: 54322 }, { address: "127.0.0.1", port: 3100 })) + .toEqual({ inode: "555", uid: 1002 }); }); it("finds the client process in macOS netstat output and refuses unknown formats", () => { @@ -230,3 +301,53 @@ describe("process lookups for a mixed batch", () => { expect(await boundary.grantsImplicitBoard(agent)).toBe(false); }); }); + +describe("connections owned by processes the server cannot inspect", () => { + const operatorChain = (pid: number) => [ + { pid, ppid: 30, executable: "/opt/browser/browser", environment: new Map() }, + { pid: 30, ppid: 1, executable: "/opt/browser/browser", environment: new Map() }, + ]; + const agentChain = (pid: number) => [ + { pid, ppid: 40, executable: "/usr/bin/python3", environment: new Map() }, + { pid: 40, ppid: 1, executable: "/bin/sh", environment: new Map([["PAPERCLIP_RUN_ID", "run-1"]]) }, + ]; + + function boundaryFor(candidates: number[] | null, chains: Record>) { + const inspector: LocalProcessInspector = { + async findPeerPids(sockets) { + return sockets.map(() => candidates ? { candidates } : null); + }, + async ancestries(pids) { + return new Map(pids.map((pid) => [pid, chains[pid] ?? null])); + }, + async ancestorPids(pid) { + return [pid]; + }, + }; + return createLocalAgentProcessBoundary({ inspector, serverEnvironment: {} }); + } + + const socket = { remoteAddress: "::1", remotePort: 2001, localAddress: "::1", localPort: 3100 }; + + it("keeps board access when every uninspectable process belongs to the operator", async () => { + const boundary = boundaryFor([31, 32], { 31: operatorChain(31), 32: operatorChain(32) }); + expect(await boundary.classify({ ...socket })).toBe("operator"); + }); + + it("refuses board access when any uninspectable process belongs to an agent run", async () => { + const boundary = boundaryFor([31, 41], { 31: operatorChain(31), 41: agentChain(41) }); + expect(await boundary.classify({ ...socket })).toBe("agent_run"); + expect(await boundary.grantsImplicitBoard({ ...socket })).toBe(false); + }); + + it("refuses board access when an uninspectable process has no readable ancestry", async () => { + expect(await boundaryFor([31, 33], { 31: operatorChain(31) }).classify({ ...socket })).toBe("agent_run"); + expect(await boundaryFor([31, 34], { 31: operatorChain(31), 34: operatorChain(34).slice(0, 1) }) + .classify({ ...socket })).toBe("agent_run"); + }); + + it("refuses board access when the connection's owner cannot be found", async () => { + const boundary = boundaryFor(null, {}); + expect(await boundary.classify({ ...socket })).toBe("agent_run"); + }); +}); diff --git a/server/src/middleware/local-agent-process-boundary.ts b/server/src/middleware/local-agent-process-boundary.ts index 68516a39f5c..a68e126e2fc 100644 --- a/server/src/middleware/local-agent-process-boundary.ts +++ b/server/src/middleware/local-agent-process-boundary.ts @@ -37,8 +37,10 @@ export interface LocalProcessInfo { environment: Map; } +export type LocalPeerOwner = number | null | "unsupported" | { candidates: number[] }; + export interface LocalProcessInspector { - findPeerPids(sockets: readonly LocalPeerEndpoints[]): Promise<(number | null | "unsupported")[] | "unsupported">; + findPeerPids(sockets: readonly LocalPeerEndpoints[]): Promise; ancestries(pids: readonly number[], stopAt: ReadonlySet): Promise>; ancestorPids(pid: number): Promise; } @@ -73,11 +75,11 @@ function decodeProcNetAddress(hex: string): string | null { return groups.join(":"); } -export function findSocketInodeInProcNet( +export function findSocketInProcNet( table: string, peer: { address: string; port: number }, server: { address: string; port: number }, -): string | null { +): { inode: string; uid: number } | null { for (const line of table.split("\n").slice(1)) { const fields = line.trim().split(/\s+/); if (fields.length < 10) continue; @@ -87,7 +89,7 @@ export function findSocketInodeInProcNet( if (Number.parseInt(localPortHex, 16) !== peer.port || Number.parseInt(remotePortHex, 16) !== server.port) continue; if (decodeProcNetAddress(localHex) !== peer.address || decodeProcNetAddress(remoteHex) !== server.address) continue; const inode = fields[9]; - if (inode && inode !== "0") return inode; + if (inode && inode !== "0") return { inode, uid: Number(fields[7]) }; } return null; } @@ -141,6 +143,22 @@ async function ownedByServerUser(pid: string): Promise { return realUid !== undefined && Number(realUid) === process.getuid?.(); } +async function readProcNetTables(): Promise { + const tables = await Promise.all(["/proc/net/tcp", "/proc/net/tcp6"].map((file) => + readFile(file, "utf8").catch(() => null))); + const readable = tables.filter((table): table is string => table !== null); + return readable.length ? readable : null; +} + +function findSocketInTables(tables: readonly string[], socket: LocalPeerEndpoints) { + const { peer, server } = endpoints(socket); + for (const table of tables) { + const found = findSocketInProcNet(table, peer, server); + if (found) return found; + } + return null; +} + function endpoints(socket: LocalPeerEndpoints) { return { peer: { address: normalizeLoopbackAddress(socket.remoteAddress), port: socket.remotePort }, @@ -165,25 +183,19 @@ async function linuxProcessInfo(pid: number): Promise { const linuxInspector: LocalProcessInspector = { async findPeerPids(sockets) { - const tables = await Promise.all(["/proc/net/tcp", "/proc/net/tcp6"].map((file) => - readFile(file, "utf8").catch(() => null))); - if (tables.every((table) => table === null)) return "unsupported"; - const inodes = sockets.map((socket) => { - const { peer, server } = endpoints(socket); - return tables.map((table) => table ? findSocketInodeInProcNet(table, peer, server) : null) - .find((value) => value !== null) ?? null; - }); - const wanted = new Map(); - for (const inode of inodes) if (inode) wanted.set(`socket:[${inode}]`, 0); + const tables = await readProcNetTables(); + if (!tables) return "unsupported"; + const found = sockets.map((socket) => findSocketInTables(tables, socket)); + const wanted = new Set(found.flatMap((entry) => entry ? [`socket:[${entry.inode}]`] : [])); const owners = new Map(); - let unreadable = false; + const hidden: number[] = []; if (wanted.size) { const others = (await readdir("/proc").catch(() => [] as string[])) .filter((entry) => /^\d+$/.test(entry) && Number(entry) !== process.pid); for (const pid of [String(process.pid), ...others]) { if (owners.size === wanted.size) break; const fds = await readdir(`/proc/${pid}/fd`).catch(async (error: NodeJS.ErrnoException) => { - if ((error.code === "EACCES" || error.code === "EPERM") && await ownedByServerUser(pid)) unreadable = true; + if ((error.code === "EACCES" || error.code === "EPERM") && await ownedByServerUser(pid)) hidden.push(Number(pid)); return [] as string[]; }); for (const fd of fds) { @@ -192,9 +204,15 @@ const linuxInspector: LocalProcessInspector = { } } } - return inodes.map((inode) => { - if (!inode) return null; - return owners.get(`socket:[${inode}]`) ?? (unreadable ? "unsupported" : null); + const unowned = found.some((entry) => entry && !owners.has(`socket:[${entry.inode}]`)); + const after = unowned && hidden.length ? await readProcNetTables() : null; + return found.map((entry, index): LocalPeerOwner => { + if (!entry) return null; + const owner = owners.get(`socket:[${entry.inode}]`); + if (owner !== undefined) return owner; + const current = after ? findSocketInTables(after, sockets[index]!) : null; + if (!current || current.inode !== entry.inode || entry.uid !== process.getuid?.()) return null; + return { candidates: hidden }; }); }, async ancestorPids(pid) { @@ -353,18 +371,23 @@ export function createLocalAgentProcessBoundary(options: LocalAgentProcessBounda async function classifyBatch(sockets: readonly LocalPeerEndpoints[]): Promise { if (!inspector) return sockets.map(() => "unsupported"); - const peerPids = await inspector.findPeerPids(sockets); - if (peerPids === "unsupported") return sockets.map(() => "unsupported"); + const owners = await inspector.findPeerPids(sockets); + if (owners === "unsupported") return sockets.map(() => "unsupported"); const stopAt = await stopSet(); - const outside = [...new Set(peerPids.filter((pid): pid is number => typeof pid === "number" && !stopAt.has(pid)))]; + const pids = owners.flatMap((owner) => + typeof owner === "number" ? [owner] : owner !== null && typeof owner === "object" ? owner.candidates : []); + const outside = [...new Set(pids.filter((pid) => !stopAt.has(pid)))]; const chains = outside.length ? await inspector.ancestries(outside, stopAt) : new Map(); - return peerPids.map((pid): LocalPeerClassification => { - if (pid === "unsupported") return "unsupported"; - if (pid === null) return "agent_run"; - if (stopAt.has(pid)) return "operator"; + const operatorPid = (pid: number, minimumChain: number) => { + if (stopAt.has(pid)) return true; const chain = chains.get(pid); - if (!chain) return "agent_run"; - return chainBelongsToAgentRun(chain, serverEnvironment) ? "agent_run" : "operator"; + return Boolean(chain) && chain!.length >= minimumChain && !chainBelongsToAgentRun(chain!, serverEnvironment); + }; + return owners.map((owner): LocalPeerClassification => { + if (owner === "unsupported") return "unsupported"; + if (owner === null) return "agent_run"; + if (typeof owner === "number") return operatorPid(owner, 0) ? "operator" : "agent_run"; + return owner.candidates.length && owner.candidates.every((pid) => operatorPid(pid, 2)) ? "operator" : "agent_run"; }); }