mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-19 16:29:42 +01:00
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:
1 parent
b51f1cb55f
commit
0904a65d82
3 files changed
+180
-36
No files matched your search
@@ -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";
|
||||
});
|
||||
}
|
||||
|
||||
|
||||
Reference in new issue
Block a user