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>
This commit is contained in:
DottaandClaude Opus 5.5 authored and GitHub committed 2026-11-12 16:52:06 -06:00
1 parent b51f1cb55f
commit 0904a65d82
3 files changed
+180 -36

No files matched your search

+1 -1
View File
@@ -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`
@@ -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<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");
});
});
@@ -37,8 +37,10 @@ export interface LocalProcessInfo {
environment: Map<string, string>;
}
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<LocalPeerOwner[] | "unsupported">;
ancestries(pids: readonly number[], stopAt: ReadonlySet<number>): Promise<Map<number, LocalProcessInfo[] | null>>;
ancestorPids(pid: number): Promise<number[] | null>;
}
@@ -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<boolean> {
return realUid !== undefined && Number(realUid) === process.getuid?.();
}
async function readProcNetTables(): Promise<string[] | null> {
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<LocalProcessInfo | null> {
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<string, number>();
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<string, number>();
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<LocalPeerClassification[]> {
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<number, LocalProcessInfo[] | null>();
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";
});
}