@crewhaus/tool-navigate 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/tool-navigate",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "description": "Navigate tool — drives driver.goto(url) for the BROW agent (Section 25 BROW)",
   "main": "src/index.ts",
@@ -12,17 +12,17 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/computer-use-driver": "0.1.1",
-    "@crewhaus/errors": "0.1.1",
-    "@crewhaus/tool-builder": "0.1.1",
-    "@crewhaus/tool-catalog": "0.1.1",
+    "@crewhaus/computer-use-driver": "0.1.2",
+    "@crewhaus/errors": "0.1.2",
+    "@crewhaus/tool-builder": "0.1.2",
+    "@crewhaus/tool-catalog": "0.1.2",
     "zod": "^3.23.8"
   },
   "license": "Apache-2.0",
   "author": {
     "name": "Max Meier",
-    "email": "max@studiomax.io",
-    "url": "https://studiomax.io"
+    "email": "max@crewhaus.ai",
+    "url": "https://crewhaus.ai"
   },
   "repository": {
     "type": "git",
@@ -34,12 +34,7 @@
     "url": "https://github.com/crewhaus/factory/issues"
   },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
-  "files": [
-    "src",
-    "README.md",
-    "LICENSE",
-    "NOTICE"
-  ]
+  "files": ["src", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -1,6 +1,6 @@
-import { describe, expect, test } from "bun:test";
+import { afterEach, describe, expect, test } from "bun:test";
 import type { Driver } from "@crewhaus/computer-use-driver";
-import { NavigateError, createNavigateTool } from "./index.js";
+import { NavigateError, _setDnsLookup, createNavigateTool } from "./index.js";
 
 type GotoRecord = { calls: string[] };
 
@@ -27,18 +27,22 @@ function stubDriver(record: GotoRecord, opts: { gotoErr?: Error } = {}): Driver
 }
 
 describe("createNavigateTool", () => {
+  // A public IP literal skips DNS resolution, keeping these tests hermetic
+  // while still passing the SSRF guard (it's a public, non-loopback address).
+  const PUBLIC_URL = "https://93.184.216.34/";
+
   test("happy path: forwards url to driver.goto and returns a text confirmation", async () => {
     const record: GotoRecord = { calls: [] };
     const tool = createNavigateTool({ driver: stubDriver(record) });
 
-    const result = await tool.execute({ url: "https://example.com/" }, {});
-    expect(record.calls).toEqual(["https://example.com/"]);
+    const result = await tool.execute({ url: PUBLIC_URL }, {});
+    expect(record.calls).toEqual([PUBLIC_URL]);
     expect(Array.isArray(result)).toBe(true);
     if (!Array.isArray(result)) throw new Error("expected ToolResultContent array");
     expect(result).toHaveLength(1);
     const block = result[0];
     if (block?.type !== "text") throw new Error("expected text block");
-    expect(block.text).toBe("navigated to https://example.com/");
+    expect(block.text).toBe(`navigated to ${PUBLIC_URL}`);
   });
 
   test("schema rejects non-URL strings (and missing url)", () => {
@@ -51,15 +55,16 @@ describe("createNavigateTool", () => {
   test("driver.goto failure surfaces as NavigateError with the URL in the message", async () => {
     const record: GotoRecord = { calls: [] };
     const tool = createNavigateTool({
-      driver: stubDriver(record, { gotoErr: new Error("net::ERR_NAME_NOT_RESOLVED") }),
+      driver: stubDriver(record, { gotoErr: new Error("net::ERR_CONNECTION_REFUSED") }),
     });
     try {
-      await tool.execute({ url: "https://does-not-exist.invalid/" }, {});
+      // Public IP literal passes the SSRF guard and reaches driver.goto.
+      await tool.execute({ url: PUBLIC_URL }, {});
       throw new Error("expected NavigateError to be thrown");
     } catch (err) {
       expect(err).toBeInstanceOf(NavigateError);
-      expect((err as Error).message).toContain("https://does-not-exist.invalid/");
-      expect((err as Error).message).toContain("net::ERR_NAME_NOT_RESOLVED");
+      expect((err as Error).message).toContain(PUBLIC_URL);
+      expect((err as Error).message).toContain("net::ERR_CONNECTION_REFUSED");
     }
   });
 
@@ -76,3 +81,76 @@ describe("createNavigateTool", () => {
     expect(tool.name).toBe("Navigate");
   });
 });
+
+// SECURITY: the model picks the navigation URL and is prompt-injectable, so
+// an attacker who controls any untrusted input could steer it to file://,
+// cloud metadata, or a loopback/private host and read the result back via
+// Screenshot. The guard must run before driver.goto.
+describe("Navigate SSRF guard", () => {
+  afterEach(() => _setDnsLookup(undefined));
+
+  const expectBlocked = async (url: string) => {
+    const record: GotoRecord = { calls: [] };
+    const tool = createNavigateTool({ driver: stubDriver(record) });
+    let threw: unknown;
+    try {
+      await tool.execute({ url }, {});
+    } catch (err) {
+      threw = err;
+    }
+    expect(threw).toBeInstanceOf(NavigateError);
+    // The browser must never have been touched.
+    expect(record.calls).toEqual([]);
+  };
+
+  test.each([
+    ["file scheme", "file:///etc/passwd"],
+    ["gopher scheme", "gopher://127.0.0.1:6379/"],
+    ["data scheme", "data:text/html,<h1>x</h1>"],
+    ["loopback IPv4", "http://127.0.0.1/"],
+    ["loopback name", "http://localhost:8080/admin"],
+    ["AWS/GCP metadata", "http://169.254.169.254/latest/meta-data/iam/security-credentials/"],
+    ["RFC1918 10.x", "http://10.0.0.5/"],
+    ["RFC1918 192.168", "http://192.168.1.1/"],
+    ["RFC1918 172.16", "http://172.16.0.1/"],
+    ["CGNAT 100.64", "http://100.64.0.1/"],
+    ["0.0.0.0", "http://0.0.0.0/"],
+    ["IPv6 loopback", "http://[::1]/"],
+    ["IPv4-mapped IPv6 loopback", "http://[::ffff:127.0.0.1]/"],
+    ["IPv4-mapped IPv6 metadata", "http://[::ffff:169.254.169.254]/"],
+    ["octal-encoded loopback", "http://0177.0.0.1/"],
+    ["integer-encoded loopback", "http://2130706433/"],
+    ["mDNS .local", "http://printer.local/"],
+  ])("blocks %s", async (_label, url) => {
+    await expectBlocked(url);
+  });
+
+  test("blocks a public hostname that resolves to a private IP (DNS rebinding at check time)", async () => {
+    _setDnsLookup(async () => ({ address: "127.0.0.1", family: 4 }));
+    const record: GotoRecord = { calls: [] };
+    const tool = createNavigateTool({ driver: stubDriver(record) });
+    await expect(
+      tool.execute({ url: "http://totally-innocent.example/" }, {}),
+    ).rejects.toBeInstanceOf(NavigateError);
+    expect(record.calls).toEqual([]);
+  });
+
+  test("allows a public hostname that resolves to a public IP", async () => {
+    _setDnsLookup(async () => ({ address: "93.184.216.34", family: 4 }));
+    const record: GotoRecord = { calls: [] };
+    const tool = createNavigateTool({ driver: stubDriver(record) });
+    await tool.execute({ url: "http://example.com/" }, {});
+    expect(record.calls).toEqual(["http://example.com/"]);
+  });
+
+  test("allows a public IP literal without any DNS lookup", async () => {
+    // If DNS were consulted for an IP literal this would throw.
+    _setDnsLookup(async () => {
+      throw new Error("DNS must not be called for an IP literal");
+    });
+    const record: GotoRecord = { calls: [] };
+    const tool = createNavigateTool({ driver: stubDriver(record) });
+    await tool.execute({ url: "https://93.184.216.34/" }, {});
+    expect(record.calls).toEqual(["https://93.184.216.34/"]);
+  });
+});

package/src/index.ts

@@ -15,10 +15,16 @@
  * `tool-mouse-keyboard`.
  *
  * Scope is `"external"` because the URL request crosses a network
- * boundary; the §3 egress-classifier can hook in here later. Output
+ * boundary. Before handing the URL to the browser we run an SSRF guard
+ * (`assertSafeNavigationTarget`): the model picks this URL and the model
+ * is prompt-injectable, so an attacker who controls any untrusted input
+ * (a channel message, fetched page, MCP result) could otherwise steer it
+ * to `file:///etc/passwd`, `http://169.254.169.254/…` (cloud metadata) or
+ * a loopback admin port and read the result back via `Screenshot`. Output
  * classification is off — the response is a deterministic short string,
  * not model-generated content.
  */
+import { lookup as nodeDnsLookup } from "node:dns/promises";
 import type { Driver } from "@crewhaus/computer-use-driver";
 import { CrewhausError } from "@crewhaus/errors";
 import { buildTool } from "@crewhaus/tool-builder";
@@ -39,6 +45,176 @@ const navigateSchema = z
   })
   .strict();
 
+/** Only real web schemes — blocks file:, gopher:, chrome:, data:, about:, etc. */
+const ALLOWED_SCHEMES = new Set(["http:", "https:"]);
+
+export type DnsLookupFn = (
+  hostname: string,
+) => Promise<{ readonly address: string; readonly family: number }>;
+
+let dnsLookupFn: DnsLookupFn = nodeDnsLookup;
+
+/** Test hook: override DNS resolution. Pass `undefined` to restore the default. */
+export function _setDnsLookup(fn: DnsLookupFn | undefined): void {
+  dnsLookupFn = fn ?? nodeDnsLookup;
+}
+
+/**
+ * SSRF defenses below mirror `@crewhaus/tool-fetch` (`isPrivateIp` /
+ * `normalizeIpv4`). They are duplicated rather than imported to avoid
+ * coupling the browser bundle to tool-fetch's module-level config state —
+ * keep the copies in sync. The IPv4-mapped IPv6 handling (`::ffff:…`, both
+ * dotted and hex-compressed) is load-bearing: `new URL` normalizes
+ * `http://[::ffff:127.0.0.1]/` to `[::ffff:7f00:1]`, which would otherwise
+ * slip past a naive loopback check.
+ */
+function normalizeIpv4(raw: string): string | null {
+  const trimmed = raw.trim();
+  if (trimmed === "") return null;
+
+  const parseComponent = (s: string): number | null => {
+    if (s === "") return null;
+    let value: number;
+    if (/^0[xX][0-9a-fA-F]+$/.test(s)) {
+      value = Number.parseInt(s.slice(2), 16);
+    } else if (/^0[0-7]+$/.test(s)) {
+      value = Number.parseInt(s, 8);
+    } else if (/^[0-9]+$/.test(s)) {
+      value = Number.parseInt(s, 10);
+    } else {
+      return null;
+    }
+    return Number.isNaN(value) ? null : value;
+  };
+
+  const segments = trimmed.split(".");
+  if (segments.length > 4) return null;
+
+  const components: number[] = [];
+  for (const seg of segments) {
+    const value = parseComponent(seg);
+    if (value === null || value < 0) return null;
+    components.push(value);
+  }
+
+  const n = components.length;
+  const octets = [0, 0, 0, 0];
+  for (let i = 0; i < n - 1; i++) {
+    const c = components[i] as number;
+    if (c > 255) return null;
+    octets[i] = c;
+  }
+  const last = components[n - 1] as number;
+  const maxLast = 2 ** (8 * (4 - (n - 1)));
+  if (last >= maxLast) return null;
+  let rest = last;
+  for (let i = 3; i >= n - 1; i--) {
+    octets[i] = rest & 0xff;
+    rest = Math.floor(rest / 256);
+  }
+  return octets.join(".");
+}
+
+function isPrivateIp(addr: string): boolean {
+  const ip = addr.replace(/^\[/, "").replace(/\]$/, "");
+  const lowerIp = ip.toLowerCase();
+
+  // IPv6 unspecified / loopback / link-local / unique-local
+  if (lowerIp === "::" || lowerIp === "::1") return true;
+  if (lowerIp.startsWith("fe80:")) return true;
+  if (lowerIp.startsWith("fc") || lowerIp.startsWith("fd")) return true;
+
+  // IPv4-mapped IPv6 (e.g. ::ffff:127.0.0.1 / ::ffff:7f00:1) — classify by
+  // the embedded IPv4 address so a mapped literal can't smuggle past.
+  const mapped = lowerIp.match(/^::ffff:(.+)$/);
+  if (mapped) {
+    const tail = mapped[1] as string;
+    if (tail.includes(".")) {
+      return isPrivateIp(tail);
+    }
+    const hexGroups = tail.split(":");
+    if (hexGroups.length === 2 && hexGroups.every((g) => /^[0-9a-f]{1,4}$/.test(g))) {
+      const hi = Number.parseInt(hexGroups[0] as string, 16);
+      const lo = Number.parseInt(hexGroups[1] as string, 16);
+      return isPrivateIp([(hi >> 8) & 0xff, hi & 0xff, (lo >> 8) & 0xff, lo & 0xff].join("."));
+    }
+    return false;
+  }
+
+  // IPv4 — normalise octal/hex/integer literals to dotted-decimal first.
+  const normalized = normalizeIpv4(ip);
+  if (normalized === null) return false;
+  const parts = normalized.split(".").map((p) => Number.parseInt(p, 10));
+  if (parts.length !== 4 || parts.some((nn) => Number.isNaN(nn) || nn < 0 || nn > 255)) {
+    return false;
+  }
+  const [a, b] = parts as [number, number, number, number];
+
+  if (a === 127) return true; // 127.0.0.0/8 loopback
+  if (a === 10) return true; // 10.0.0.0/8 RFC1918
+  if (a === 169 && b === 254) return true; // 169.254.0.0/16 link-local + AWS metadata
+  if (a === 172 && b >= 16 && b <= 31) return true; // 172.16.0.0/12 RFC1918
+  if (a === 192 && b === 168) return true; // 192.168.0.0/16 RFC1918
+  if (a === 100 && b >= 64 && b <= 127) return true; // 100.64.0.0/10 CGNAT (RFC6598)
+  if (a === 192 && b === 0 && parts[2] === 0) return true; // 192.0.0.0/24 (RFC6890)
+  if (a === 198 && (b === 18 || b === 19)) return true; // 198.18.0.0/15 (RFC2544)
+  if (a === 0) return true; // 0.0.0.0/8
+  return false;
+}
+
+/**
+ * Reject anything that isn't a public http/https target before the browser
+ * sees it. This guard blocks the direct vectors — non-http(s) schemes, IP
+ * literals, loopback/mDNS names, and names that resolve to a private range
+ * at check time. The rebinding TOCTOU this check alone cannot close (the
+ * browser re-resolves DNS at connect time, and sub-resource fetches never
+ * pass through here) is closed at the connection layer by the chromium
+ * backend's DNS-pinning proxy — see `ssrf-proxy.ts` in computer-use-driver,
+ * on by default. The remote (CDP/Browserless) backend launches its browser
+ * elsewhere, so for that backend this pre-goto guard is still the only
+ * navigate-side control; pin egress at the remote browser's host.
+ */
+export async function assertSafeNavigationTarget(rawUrl: string): Promise<void> {
+  let url: URL;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    throw new NavigateError(`navigation to ${rawUrl} blocked: not a valid absolute URL`);
+  }
+  if (!ALLOWED_SCHEMES.has(url.protocol)) {
+    throw new NavigateError(
+      `navigation to ${rawUrl} blocked: only http/https is allowed (got "${url.protocol}")`,
+    );
+  }
+  const hostname = url.hostname.toLowerCase();
+  if (hostname === "localhost" || hostname.endsWith(".localhost")) {
+    throw new NavigateError(`navigation to ${rawUrl} blocked: loopback host`);
+  }
+  if (hostname.endsWith(".local")) {
+    throw new NavigateError(`navigation to ${rawUrl} blocked: mDNS host "${hostname}"`);
+  }
+  const unbracketed = hostname.replace(/^\[/, "").replace(/\]$/, "");
+  if (isPrivateIp(unbracketed)) {
+    throw new NavigateError(`navigation to ${rawUrl} blocked: private/loopback IP`);
+  }
+  // IP literals are their own target — nothing to resolve/rebind.
+  const isIpLiteral = normalizeIpv4(unbracketed) !== null || unbracketed.includes(":");
+  if (isIpLiteral) return;
+  let resolved: { readonly address: string };
+  try {
+    resolved = await dnsLookupFn(unbracketed);
+  } catch (err) {
+    throw new NavigateError(
+      `navigation to ${rawUrl} blocked: cannot resolve host: ${(err as Error).message}`,
+    );
+  }
+  if (isPrivateIp(resolved.address)) {
+    throw new NavigateError(
+      `navigation to ${rawUrl} blocked: host resolves to private IP ${resolved.address}`,
+    );
+  }
+}
+
 export type CreateNavigateToolOptions = {
   readonly driver: Driver;
 };
@@ -55,6 +231,9 @@ export function createNavigateTool(opts: CreateNavigateToolOptions): RegisteredT
     classifyOutput: false,
     scope: "external",
     execute: async (input): Promise<ToolResultContent> => {
+      // SSRF guard runs BEFORE the browser touches the URL. Throws
+      // NavigateError directly so the block reason surfaces unwrapped.
+      await assertSafeNavigationTarget(input.url);
       try {
         await opts.driver.goto(input.url);
       } catch (err) {