Files
PaperClipAI/server/src/__tests__/local-agent-process-boundary.test.ts
T
DottaandClaude Opus 5.5 0904a65d82 fix(server): local board boundary identifies agent processes on Linux it cannot inspect (#21209)
## 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 <noreply@anthropic.com>
2026-11-12 16:52:06 -06:00

354 lines
16 KiB
TypeScript

import { execFile } from "node:child_process";
import http from "node:http";
import type { AddressInfo } from "node:net";
import type { Server } from "node:http";
import express from "express";
import { afterAll, beforeAll, describe, expect, it } from "vitest";
import type { Db } from "@paperclipai/db";
import { actorMiddleware } from "../middleware/auth.js";
import {
chainBelongsToAgentRun,
createLocalAgentProcessBoundary,
type LocalProcessInspector,
findPeerPidInDarwinNetstat,
findSocketInProcNet,
} from "../middleware/local-agent-process-boundary.js";
const supported = process.platform === "linux" || process.platform === "darwin";
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",
localAgentProcessBoundary: createLocalAgentProcessBoundary({ serverEnvironment }),
}));
app.get("/api/whoami", (req, res) => {
res.json({ type: req.actor.type, source: req.actor.source ?? null });
});
return new Promise((resolve) => {
const server = app.listen(0, host, () => {
const { port } = server.address() as AddressInfo;
resolve({ server, url: `http://${host.includes(":") ? `[${host}]` : host}:${port}/api/whoami` });
});
});
}
const fetchScript = "fetch(process.argv[1]).then(r => r.text()).then(t => process.stdout.write(t))";
function runChild(command: string, args: string[], env: NodeJS.ProcessEnv): Promise<{ type: string; source: string | null }> {
return new Promise((resolve, reject) => {
execFile(command, args, { env, timeout: 20_000 }, (error, stdout) => {
if (error) reject(error);
else resolve(JSON.parse(stdout));
});
});
}
function operatorEnvironment(): NodeJS.ProcessEnv {
const env = { ...process.env };
for (const key of ["PAPERCLIP_RUN_ID", "PAPERCLIP_AGENT_ID", "PAPERCLIP_AGENT_KEY_ID", "PAPERCLIP_RUNNER_INSTANCE_ID"]) {
delete env[key];
}
return env;
}
describe.skipIf(!supported)("implicit local board access from local processes", () => {
let server: Server;
let url: string;
beforeAll(async () => {
({ server, url } = await startServer({}));
});
afterAll(async () => {
await new Promise((resolve) => server.close(resolve));
});
it("keeps board access for an operator process without credentials", async () => {
await expect(runChild(process.execPath, ["-e", fetchScript, url], operatorEnvironment()))
.resolves.toEqual({ type: "board", source: "local_implicit" });
});
it("keeps board access for requests from the server process itself", async () => {
const body = await fetch(url).then((response) => response.json());
expect(body).toEqual({ type: "board", source: "local_implicit" });
});
it("refuses board access to an agent-run process calling without credentials", async () => {
await expect(runChild(process.execPath, ["-e", fetchScript, url], {
...operatorEnvironment(),
PAPERCLIP_RUN_ID: "11111111-1111-4111-8111-111111111111",
})).resolves.toEqual({ type: "none", source: "none" });
});
it("refuses board access when an agent's tool clears its environment before calling", async () => {
const agentProcess = [
"const { execFileSync } = require('node:child_process');",
"process.stdout.write(execFileSync(process.execPath, ['-e', process.argv[1], process.argv[2]], { env: {} }));",
].join("\n");
await expect(runChild(process.execPath, ["-e", agentProcess, fetchScript, url], {
...operatorEnvironment(),
PAPERCLIP_AGENT_ID: "22222222-2222-4222-8222-222222222222",
})).resolves.toEqual({ type: "none", source: "none" });
});
it("keeps board access for an operator whose own server runs inside the same agent execution", async () => {
const runId = "33333333-3333-4333-8333-333333333333";
const nested = await startServer({ PAPERCLIP_RUN_ID: runId });
try {
await expect(runChild(process.execPath, ["-e", fetchScript, nested.url], {
...operatorEnvironment(),
PAPERCLIP_RUN_ID: runId,
})).resolves.toEqual({ type: "board", source: "local_implicit" });
} finally {
await new Promise((resolve) => nested.server.close(resolve));
}
});
});
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 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(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", () => {
const output = [
"Active Internet connections (including servers)",
"Proto Recv-Q Send-Q Local Address Foreign Address (state) rxbytes txbytes rhiwat shiwat process:pid state options",
"tcp4 0 0 127.0.0.1.3100 127.0.0.1.54321 ESTABLISHED 0 0 408300 146988 node:100 00002 00000000",
"tcp4 0 0 127.0.0.1.54321 127.0.0.1.3100 ESTABLISHED 0 0 408300 146988 Google Chrome He:200 00002 00000000",
].join("\n");
const peer = { address: "127.0.0.1", port: 54321 };
const server = { address: "127.0.0.1", port: 3100 };
expect(findPeerPidInDarwinNetstat(output, peer, server)).toBe(200);
expect(findPeerPidInDarwinNetstat(output.replace("process:pid", "pid"), peer, server)).toBe("unsupported");
});
it("treats processes under the runner daemon as an agent run but not the daemon itself", () => {
const daemon = { pid: 10, ppid: 1, executable: "/opt/paperclip/paperclip-runnerd", environment: new Map() };
const shell = { pid: 11, ppid: 10, executable: "/bin/bash", environment: new Map() };
expect(chainBelongsToAgentRun([daemon], {})).toBe(false);
expect(chainBelongsToAgentRun([shell, daemon], {})).toBe(true);
});
});
describe("process lookups under connection bursts", () => {
it("shares one lookup at a time across parallel connections and keeps the server responsive", async () => {
let active = 0;
let maxActive = 0;
let scans = 0;
const scannedSockets: number[] = [];
const inspector: LocalProcessInspector = {
async findPeerPids(sockets) {
scans += 1;
active += 1;
maxActive = Math.max(maxActive, active);
scannedSockets.push(sockets.length);
await new Promise((resolve) => setTimeout(resolve, 300));
active -= 1;
return sockets.map(() => 4242);
},
async ancestries(pids) {
return new Map(pids.map((pid) => [pid, [{ pid, ppid: 1, executable: "/usr/bin/browser", environment: new Map() }]]));
},
async ancestorPids(pid) {
return [pid];
},
};
const app = express();
app.use(actorMiddleware({} as Db, {
deploymentMode: "local_trusted",
localAgentProcessBoundary: createLocalAgentProcessBoundary({ inspector, serverEnvironment: {} }),
}));
app.get("/api/whoami", (req, res) => { res.json({ type: req.actor.type }); });
const server = await new Promise<Server>((resolve) => {
const started = app.listen(0, "127.0.0.1", () => resolve(started));
});
const { port } = server.address() as AddressInfo;
const request = (abortAfterMs?: number) => new Promise<string>((resolve) => {
const req = http.get({ host: "127.0.0.1", port, path: "/api/whoami", agent: false }, (res) => {
let body = "";
res.on("data", (chunk) => { body += chunk; });
res.on("end", () => resolve(body));
});
req.on("error", () => resolve("aborted"));
if (abortAfterMs !== undefined) setTimeout(() => req.destroy(), abortAfterMs);
});
try {
const timerStarted = Date.now();
const timerDelay = new Promise<number>((resolve) => setTimeout(() => resolve(Date.now() - timerStarted - 50), 50));
const first = await Promise.all([
...Array.from({ length: 12 }, () => request()),
request(20),
request(20),
timerDelay,
]);
const bodies = first.slice(0, 12);
expect(bodies.every((body) => JSON.parse(body as string).type === "board")).toBe(true);
expect(first.slice(12, 14)).toEqual(["aborted", "aborted"]);
expect(first[14] as number).toBeLessThan(250);
expect(maxActive).toBe(1);
expect(scans).toBeLessThanOrEqual(2);
const scanned = scannedSockets.reduce((sum, count) => sum + count, 0);
expect(scanned).toBeGreaterThanOrEqual(12);
expect(scanned).toBeLessThanOrEqual(14);
expect(JSON.parse(await request())).toEqual({ type: "board" });
} finally {
await new Promise((resolve) => server.close(resolve));
}
});
});
describe("process lookups for a mixed batch", () => {
it("keeps an identified agent process refused when another connection in the batch cannot be identified", async () => {
const inspector: LocalProcessInspector = {
async findPeerPids(sockets) {
return sockets.map((socket) => socket.remotePort === 1001 ? "unsupported" : 2002);
},
async ancestries(pids) {
return new Map(pids.map((pid) => [pid, [{
pid, ppid: 1, executable: "/usr/bin/agent", environment: new Map([["PAPERCLIP_RUN_ID", "run-1"]]),
}]]));
},
async ancestorPids(pid) {
return [pid];
},
};
const boundary = createLocalAgentProcessBoundary({ inspector, serverEnvironment: {} });
const hidden = { remoteAddress: "127.0.0.1", remotePort: 1001, localAddress: "127.0.0.1", localPort: 3100 };
const agent = { remoteAddress: "127.0.0.1", remotePort: 1002, localAddress: "127.0.0.1", localPort: 3100 };
const [hiddenResult, agentResult] = await Promise.all([boundary.classify(hidden), boundary.classify(agent)]);
expect(hiddenResult).toBe("unsupported");
expect(agentResult).toBe("agent_run");
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<string, string>() },
{ pid: 30, ppid: 1, executable: "/opt/browser/browser", environment: new Map<string, string>() },
];
const agentChain = (pid: number) => [
{ pid, ppid: 40, executable: "/usr/bin/python3", environment: new Map<string, string>() },
{ pid: 40, ppid: 1, executable: "/bin/sh", environment: new Map([["PAPERCLIP_RUN_ID", "run-1"]]) },
];
function boundaryFor(candidates: number[] | null, chains: Record<number, ReturnType<typeof operatorChain>>) {
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");
});
});