@erichll/pi-sandbox 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.8.0 - 2026-08-18
+
+- **Trusted network domain policies.** Persistent `network.allowedDomains` and
+  `network.deniedDomains` arrays in the trusted global configuration
+  (`~/.pi/agent/extensions/pi-sandbox/config.json`, with legacy fallback) now
+  authorize matching connections statically, without the one-shot reviewer.
+  Entries use Sandbox Runtime-compatible patterns: exact domains,
+  strict-subdomain wildcards such as `*.example.com`, and an optional `:port`;
+  a bare `*` (optionally with a port) is accepted only in `deniedDomains`.
+  Values are trimmed and deduplicated, and malformed or unknown configuration
+  fails closed. Precedence is deterministic — deny, then allow, then the
+  existing one-shot reviewer — and empty arrays preserve the previous
+  behavior (no persistent network authorization, with every eligible public
+  connection reviewed once).
+- **Policy parity across execution surfaces.** The same copied network policy
+  is applied to main-agent Bash, built-in subagents, and outer-isolated
+  `pi-subagents` workers. External workers receive policy only through their
+  capability-bound supervisor registration; missing, malformed, or extra-field
+  transport becomes deny-all without disabling dynamic review for valid
+  policies.
+- **Exfiltration-risk documentation.** The README now warns that domain
+  allowlists are not a complete data-loss-prevention boundary, that
+  multi-tenant or user-uploadable destinations (for example `github.com`) can
+  themselves be exfiltration channels, and that pi-sandbox never infers or
+  silently adds domains.
+- Pin `@anthropic-ai/sandbox-runtime` to `0.0.73` (fixed version; its
+  network-policy evaluation semantics are reused by the static allow/deny
+  matching).
+
 ## 0.7.0 - 2026-08-17
 
 - **Builtin `subagent` model fail-fast.** An explicit `model` on `start`/

package/README.md

@@ -12,9 +12,10 @@ also run complete process-backed subagent trees inside independent sandboxes.
   writes outside the workspace fail closed. Runtime filesystem denials are not
   converted into dynamic grants because Sandbox Runtime does not expose a
   trustworthy filesystem ask callback.
-- Network access is denied by default. Each unmatched destination is sent to
-  `pi-auto-review` as a concrete hostname and port. An approval applies only to
-  that connection.
+- Network policy is evaluated as static deny, then static allow, then dynamic
+  review. Each unmatched public destination is sent to `pi-auto-review` as a
+  canonical hostname and concrete port. An approval applies only to that
+  connection.
 - Every Bash command and persistent subagent session owns a separate broker
   process and Sandbox Runtime manager. Concurrent workers therefore keep
   independent policy, proxy, approval, and cleanup lifecycles.
@@ -118,6 +119,53 @@ such as `return runs.run('main', { agent, task })`. The compatibility gate's
 The configuration parser rejects malformed JSON, unknown fields, and unknown
 providers instead of silently weakening isolation.
 
+## Network domain policy
+
+Persistent domain authorization is accepted only from the trusted global
+`~/.pi/agent/extensions/pi-sandbox/config.json` (or its legacy trusted fallback
+when the new file is absent). Project configuration cannot override it.
+
+```json
+{
+  "network": {
+    "allowedDomains": [
+      "github.com",
+      "*.github.com",
+      "registry.npmjs.org:443"
+    ],
+    "deniedDomains": [
+      "uploads.github.com",
+      "*:22"
+    ]
+  }
+}
+```
+
+Entries support exact domains, strict-subdomain wildcards such as
+`*.example.com`, and an optional `:port` restriction. A bare `*` (optionally
+with a port) is accepted only in `deniedDomains`. Values are trimmed and
+deduplicated, and malformed or unknown configuration fails closed.
+
+The precedence is deterministic:
+
+1. A matching `deniedDomains` entry rejects the connection.
+2. Otherwise, a matching `allowedDomains` entry permits it without review.
+3. Otherwise, the canonical public hostname and port enter the existing
+   one-shot auto-review or human approval flow.
+
+Both arrays default to empty. That preserves the prior behavior: no persistent
+network authorization, with every eligible public connection reviewed once.
+The same trusted arrays are copied into main-agent Bash, built-in subagents,
+and external `pi-subagents` workers when outer isolation is enforced. Missing
+or malformed external-worker policy transport hard-denies network access.
+
+Domain allowlists are not a complete data-loss-prevention boundary. A
+multi-tenant or user-uploadable destination such as `github.com` can itself be
+an exfiltration channel; grant only the narrow domains and ports you intend.
+Real package-manager traffic may require additional hosts—for example, PyPI
+downloads commonly use `files.pythonhosted.org`. `pi-sandbox` never infers or
+silently adds those domains.
+
 To opt in to outer worker isolation for the external provider, use:
 
 ```json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erichll/pi-sandbox",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Sandbox Runtime-backed Linux and macOS sandbox with pi-auto-review approval",
   "type": "module",
   "license": "Apache-2.0",
@@ -50,7 +50,7 @@
     "test": "node --experimental-strip-types --test test/*.test.ts"
   },
   "dependencies": {
-    "@anthropic-ai/sandbox-runtime": "0.0.71",
+    "@anthropic-ai/sandbox-runtime": "0.0.73",
     "@erichll/pi-auto-review": "0.3.5"
   },
   "peerDependencies": {

package/src/config.ts

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
+import { NetworkConfigSchema } from "@anthropic-ai/sandbox-runtime";
 
 export const SUBAGENT_PROVIDERS = [
   "builtin",
@@ -19,6 +20,11 @@ export type HostIPCConfig = {
   retryOnUnixSocketError: boolean;
 };
 
+export type NetworkConfig = {
+  readonly allowedDomains: readonly string[];
+  readonly deniedDomains: readonly string[];
+};
+
 export type PiSandboxConfig = {
   subagents: {
     provider: SubagentProvider;
@@ -27,6 +33,7 @@ export type PiSandboxConfig = {
   filesystem: {
     additionalAllowRead: readonly string[];
   };
+  network: NetworkConfig;
   hostIPC: HostIPCConfig;
 };
 
@@ -45,6 +52,10 @@ export const DEFAULT_PI_SANDBOX_CONFIG: Readonly<PiSandboxConfig> = Object.freez
     filesystem: Object.freeze({
       additionalAllowRead: Object.freeze([]),
     }),
+    network: Object.freeze({
+      allowedDomains: Object.freeze([]),
+      deniedDomains: Object.freeze([]),
+    }),
     hostIPC: Object.freeze({
       mode: "off",
       preflightCommandPrefixes: Object.freeze([]),
@@ -86,11 +97,40 @@ function rejectUnknownKeys(
   }
 }
 
+function hasValidDomainLabels(
+  pattern: string,
+  allowDenyAll: boolean,
+): boolean {
+  const portMatch = pattern.match(/:([1-9][0-9]{0,4})$/);
+  const hostPattern = portMatch
+    ? pattern.slice(0, -portMatch[0].length)
+    : pattern;
+  if (portMatch && Number(portMatch[1]) > 65_535) return false;
+  if (hostPattern === "*") return allowDenyAll;
+  const hostname = hostPattern.startsWith("*.")
+    ? hostPattern.slice(2)
+    : hostPattern;
+  return (
+    hostname.length <= 253 &&
+    hostname.includes(".") &&
+    hostname.split(".").every(
+      (label) =>
+        label.length > 0 &&
+        label.length <= 63 &&
+        /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/i.test(label),
+    )
+  );
+}
+
 export function parsePiSandboxConfig(value: unknown): PiSandboxConfig {
   if (!isRecord(value)) {
     throw new Error("invalid pi-sandbox configuration: root must be an object");
   }
-  rejectUnknownKeys(value, ["subagents", "filesystem", "hostIPC"], "root");
+  rejectUnknownKeys(
+    value,
+    ["subagents", "filesystem", "network", "hostIPC"],
+    "root",
+  );
 
   if (value.subagents !== undefined && !isRecord(value.subagents)) {
     throw new Error(
@@ -154,6 +194,58 @@ export function parsePiSandboxConfig(value: unknown): PiSandboxConfig {
     );
   }
 
+  if (value.network !== undefined && !isRecord(value.network)) {
+    throw new Error(
+      "invalid pi-sandbox configuration: network must be an object",
+    );
+  }
+  const network = value.network ?? {};
+  rejectUnknownKeys(
+    network,
+    ["allowedDomains", "deniedDomains"],
+    "network",
+  );
+  const normalizeDomainList = (
+    key: "allowedDomains" | "deniedDomains",
+  ): string[] => {
+    const configured = network[key] ?? DEFAULT_PI_SANDBOX_CONFIG.network[key];
+    if (
+      !Array.isArray(configured) ||
+      configured.some(
+        (pattern) => typeof pattern !== "string" || pattern.trim() === "",
+      )
+    ) {
+      throw new Error(
+        `invalid pi-sandbox configuration: network.${key} must be an array of non-empty strings`,
+      );
+    }
+    const normalized = [
+      ...new Set(configured.map((pattern) => pattern.trim())),
+    ];
+    const invalidIndex = normalized.findIndex(
+      (pattern) => !hasValidDomainLabels(pattern, key === "deniedDomains"),
+    );
+    if (invalidIndex >= 0) {
+      throw new Error(
+        `invalid pi-sandbox configuration: network.${key}[${invalidIndex}] contains an invalid domain pattern`,
+      );
+    }
+    const candidate = {
+      allowedDomains: key === "allowedDomains" ? normalized : [],
+      deniedDomains: key === "deniedDomains" ? normalized : [],
+    };
+    const result = NetworkConfigSchema.safeParse(candidate);
+    if (!result.success) {
+      const issue = result.error.issues[0];
+      throw new Error(
+        `invalid pi-sandbox configuration: network.${key}${typeof issue?.path[1] === "number" ? `[${issue.path[1]}]` : ""} ${issue?.message ?? "contains an invalid domain pattern"}`,
+      );
+    }
+    return normalized;
+  };
+  const allowedDomains = normalizeDomainList("allowedDomains");
+  const deniedDomains = normalizeDomainList("deniedDomains");
+
   if (value.hostIPC !== undefined && !isRecord(value.hostIPC)) {
     throw new Error(
       "invalid pi-sandbox configuration: hostIPC must be an object",
@@ -204,6 +296,10 @@ export function parsePiSandboxConfig(value: unknown): PiSandboxConfig {
     filesystem: {
       additionalAllowRead: [...new Set(additionalAllowRead)],
     },
+    network: {
+      allowedDomains: [...allowedDomains],
+      deniedDomains: [...deniedDomains],
+    },
     hostIPC: {
       mode: hostIPCMode as HostIPCMode,
       preflightCommandPrefixes: [
@@ -226,6 +322,10 @@ function defaultPiSandboxConfig(): PiSandboxConfig {
         ...DEFAULT_PI_SANDBOX_CONFIG.filesystem.additionalAllowRead,
       ],
     },
+    network: {
+      allowedDomains: [...DEFAULT_PI_SANDBOX_CONFIG.network.allowedDomains],
+      deniedDomains: [...DEFAULT_PI_SANDBOX_CONFIG.network.deniedDomains],
+    },
     hostIPC: {
       mode: DEFAULT_PI_SANDBOX_CONFIG.hostIPC.mode,
       preflightCommandPrefixes: [

package/src/external-network-policy.d.mts

@@ -0,0 +1,8 @@
+export type ExternalNetworkPolicy = {
+  allowedDomains: string[];
+  deniedDomains: string[];
+};
+
+export function decodeExternalNetworkPolicy(
+  value: unknown,
+): ExternalNetworkPolicy;

package/src/external-network-policy.mjs

@@ -0,0 +1,27 @@
+import { NetworkConfigSchema } from "@anthropic-ai/sandbox-runtime";
+
+/**
+ * Decode the supervisor-owned network policy delivered during registration.
+ * Any missing, extra, or malformed data becomes a deny-all policy so a broken
+ * transport can never widen an external worker's access.
+ */
+export function decodeExternalNetworkPolicy(value) {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    Object.keys(value).some(
+      (key) => key !== "allowedDomains" && key !== "deniedDomains",
+    )
+  ) {
+    return { allowedDomains: [], deniedDomains: ["*"] };
+  }
+  const result = NetworkConfigSchema.safeParse(value);
+  if (!result.success) {
+    return { allowedDomains: [], deniedDomains: ["*"] };
+  }
+  return {
+    allowedDomains: [...result.data.allowedDomains],
+    deniedDomains: [...result.data.deniedDomains],
+  };
+}

package/src/external-supervisor.ts

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 import type { NetworkEndpoint, TrapApprovalContext } from "./approval.ts";
 import { approveDomainEndpoint } from "./approval.ts";
+import type { NetworkConfig } from "./config.ts";
 
 const MAX_FRAME_BYTES = 16 * 1024;
 const PROTOCOL_VERSION = 1;
@@ -43,7 +44,12 @@ export type ExternalWorkerSupervisor = {
 export async function createExternalWorkerSupervisor(
   approvalContext: (worker: { id: string; cwd: string }) => TrapApprovalContext,
   lifecycle: ExternalWorkerSupervisorLifecycle = {},
+  network: NetworkConfig = { allowedDomains: [], deniedDomains: [] },
 ): Promise<ExternalWorkerSupervisor> {
+  const trustedNetwork = {
+    allowedDomains: [...network.allowedDomains],
+    deniedDomains: [...network.deniedDomains],
+  };
   const directory = await mkdtemp(join(tmpdir(), "pi-sandbox-external-"));
   await chmod(directory, 0o700);
   const socketPath = join(directory, "supervisor.sock");
@@ -101,7 +107,14 @@ export async function createExternalWorkerSupervisor(
           startedAt: Date.now(),
           requests: 0,
         });
-        socket.write(`${JSON.stringify({ id: request.id, action: "allow" })}\n`);
+        socket.write(`${JSON.stringify({
+          id: request.id,
+          action: "allow",
+          network: {
+            allowedDomains: [...trustedNetwork.allowedDomains],
+            deniedDomains: [...trustedNetwork.deniedDomains],
+          },
+        })}\n`);
         lifecycle.registered?.({
           id: request.workerId as string,
           cwd: request.cwd as string,

package/src/external-worker-launcher.mjs

@@ -8,6 +8,7 @@ import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmdirSync,
 import { homedir, tmpdir } from "node:os";
 import { dirname, join, parse, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { decodeExternalNetworkPolicy } from "./external-network-policy.mjs";
 
 const realPi = process.env.PI_SANDBOX_EXTERNAL_REAL_PI_BINARY;
 const workerId = randomUUID();
@@ -32,19 +33,22 @@ function worktreeGitReadPaths(cwd) {
 function supervisorRequest(payload) {
   const socketPath = process.env.PI_SANDBOX_EXTERNAL_SUPERVISOR_SOCKET;
   const capability = process.env.PI_SANDBOX_EXTERNAL_SUPERVISOR_CAPABILITY;
-  if (!socketPath || !capability) return Promise.resolve("deny");
-  return new Promise((resolveAction) => {
+  if (!socketPath || !capability) return Promise.resolve({ action: "deny" });
+  return new Promise((resolveResponse) => {
     const socket = createConnection(socketPath);
     let buffer = "";
-    const finish = (action) => { socket.destroy(); resolveAction(action === "allow" ? "allow" : "deny"); };
+    const finish = (response) => {
+      socket.destroy();
+      resolveResponse(response?.action === "allow" ? response : { action: "deny" });
+    };
     socket.setEncoding("utf8");
-    socket.setTimeout(30_000, () => finish("deny"));
-    socket.once("error", () => finish("deny"));
+    socket.setTimeout(30_000, () => finish({ action: "deny" }));
+    socket.once("error", () => finish({ action: "deny" }));
     socket.on("data", (chunk) => {
       buffer += chunk;
       const newline = buffer.indexOf("\n");
       if (newline < 0 || Buffer.byteLength(buffer, "utf8") > 16 * 1024) return;
-      try { finish(JSON.parse(buffer.slice(0, newline)).action); } catch { finish("deny"); }
+      try { finish(JSON.parse(buffer.slice(0, newline))); } catch { finish({ action: "deny" }); }
     });
     socket.once("connect", () => socket.write(`${JSON.stringify({
       version: 1, capability, id: randomUUID(), ...payload,
@@ -55,10 +59,10 @@ function registerWorker() {
   return supervisorRequest({ type: "register", workerId, cwd: process.cwd() });
 }
 function unregisterWorker() {
-  return supervisorRequest({ type: "unregister", workerId, cwd: process.cwd() });
+  return supervisorRequest({ type: "unregister", workerId, cwd: process.cwd() }).then((response) => response.action);
 }
 function askSupervisor(hostname, port) {
-  return supervisorRequest({ type: "network", workerId, cwd: process.cwd(), hostname, port });
+  return supervisorRequest({ type: "network", workerId, cwd: process.cwd(), hostname, port }).then((response) => response.action);
 }
 
 function createMandatoryDenyPlaceholders(cwd, agentDir) {
@@ -174,6 +178,13 @@ if (!realPi) {
     join(agentDir, "sandbox.json"),
     join(agentDir, "extensions"),
   ];
+  const registration = await registerWorker();
+  if (registration.action !== "allow") {
+    process.stderr.write("pi-sandbox: external worker registration was denied\n");
+    process.exitCode = 1;
+    process.exit();
+  }
+  const registeredNetwork = decodeExternalNetworkPolicy(registration.network);
   const runtimeConfig = {
     filesystem: {
       denyRead: home === parse(home).root ? [] : [home],
@@ -200,16 +211,12 @@ if (!realPi) {
       allowGitConfig: true,
     },
     network: {
-      allowedDomains: [], deniedDomains: [], allowLocalBinding: false,
+      allowedDomains: registeredNetwork.allowedDomains,
+      deniedDomains: registeredNetwork.deniedDomains,
       allowAllUnixSockets: false, allowUnixSockets: [],
+      allowLocalBinding: false,
     },
   };
-  const registration = await registerWorker();
-  if (registration !== "allow") {
-    process.stderr.write("pi-sandbox: external worker registration was denied\n");
-    process.exitCode = 1;
-    process.exit();
-  }
   const broker = fork(new URL("./srt-broker.mjs", import.meta.url), [], {
     cwd,
     detached: true,

package/src/index.ts

@@ -19,6 +19,7 @@ import {
 import {
   loadPiSandboxConfig,
   type HostIPCConfig,
+  type NetworkConfig,
   type SubagentProvider,
 } from "./config.ts";
 import { runCommandWithHostIPC } from "./host-ipc.ts";
@@ -171,6 +172,7 @@ function sandboxOperations(
   ctx: ExtensionContext,
   turnIndex: () => number,
   additionalAllowRead: readonly string[],
+  network: NetworkConfig,
   hostIPC: HostIPCConfig,
   sandbox?: PiSandboxExtensionOptions["sandbox"],
 ): BashOperations {
@@ -222,7 +224,7 @@ function sandboxOperations(
             onData: options.onData,
             onStderr,
             shellPath,
-            policy: createDefaultPolicy(cwd, { additionalAllowRead }),
+            policy: createDefaultPolicy(cwd, { additionalAllowRead, network }),
             review: async (trap) => {
               const result = await approveSandboxTrap(trap, approvalContext);
               if (result.action === "deny" && result.reason) {
@@ -265,6 +267,7 @@ async function performRegistration(
     externalWorkerIsolation,
   );
   const additionalAllowRead = config.filesystem.additionalAllowRead;
+  const network = config.network;
   const hostIPC = options.hostIPC ?? config.hostIPC;
   const subagents =
     subagentProvider === "builtin"
@@ -292,6 +295,7 @@ async function performRegistration(
           ctx,
           () => currentTurn,
           additionalAllowRead,
+          network,
           hostIPC,
           options.sandbox,
         ),
@@ -380,7 +384,7 @@ async function performRegistration(
           cwd: ctx.cwd,
           model: params.model,
           tools: pi.getActiveTools().filter((name) => name !== "subagent"),
-          policy: createDefaultPolicy(ctx.cwd, { additionalAllowRead }),
+          policy: createDefaultPolicy(ctx.cwd, { additionalAllowRead, network }),
           sandbox: options.sandbox,
           review: async (trap: Parameters<typeof approveSandboxTrap>[0]) =>
             (await approveSandboxTrap(trap, approvalContext)).action,
@@ -546,6 +550,7 @@ async function performRegistration(
       ctx,
       () => currentTurn,
       additionalAllowRead,
+      network,
       hostIPC,
       options.sandbox,
     ),
@@ -606,6 +611,7 @@ async function performRegistration(
             registered: (worker) => fleetView?.registered(worker),
             unregistered: (worker) => fleetView?.unregistered(worker.id),
           },
+          network,
         );
         isolation = enableExternalWorkerIsolation(supervisor);
         externalIsolationFailure = undefined;
@@ -657,8 +663,8 @@ async function performRegistration(
     if (ctx.hasUI) {
       ctx.ui.notify(
         process.platform === "darwin"
-          ? `${EXTENSION_NAME} enabled: macOS Sandbox Runtime with static filesystem policy and per-connection network review`
-          : `${EXTENSION_NAME} enabled: Linux Sandbox Runtime with static filesystem policy and per-connection network review`,
+          ? `${EXTENSION_NAME} enabled: macOS Sandbox Runtime with static filesystem/domain policy and per-connection network review`
+          : `${EXTENSION_NAME} enabled: Linux Sandbox Runtime with static filesystem/domain policy and per-connection network review`,
         "info",
       );
     }

package/src/policy.ts

@@ -10,6 +10,7 @@ import {
 } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { SandboxRuntimeConfig } from "@anthropic-ai/sandbox-runtime";
+import type { NetworkConfig } from "./config.ts";
 
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const NODE_INSTALL_ROOT = dirname(dirname(process.execPath));
@@ -120,6 +121,7 @@ export type SandboxPolicy = {
 
 export type CreateDefaultPolicyOptions = {
   additionalAllowRead?: readonly string[];
+  network?: NetworkConfig;
 };
 
 export function isSecretDenyWriteBasename(name: string): boolean {
@@ -271,8 +273,8 @@ export function createDefaultPolicy(
       ],
     },
     network: {
-      allowedDomains: [],
-      deniedDomains: [],
+      allowedDomains: [...(options.network?.allowedDomains ?? [])],
+      deniedDomains: [...(options.network?.deniedDomains ?? [])],
       allowLocalBinding: false,
       allowAllUnixSockets: false,
       allowUnixSockets: [],