Skip to content

Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.

11.8 KB
Raw Blame
/**
 * What a Bot's browser is allowed to navigate to.
 *
 * A computer-use browser is an SSRF engine pointed at your own network unless something stops it.
 * The Bot runs inside the deployment, so `http://localhost:5432`, the cloud metadata endpoint at
 * 169.254.169.254, and every RFC1918 address are all reachable from it and none of them are reachable
 * from the person's laptop. A model that has been talked into "check what is on 10.0.0.5" would
 * otherwise do exactly that and screenshot the result back into the transcript.
 *
 * This is an allow-list of schemes plus a deny-list of destinations, applied before the request is
 * made rather than after. It is deliberately dumb: no DNS resolution, no redirect following, no
 * cleverness that could disagree with what the browser eventually does. The gateway sits in front
 * of every action, which is where policy per Bot belongs; this is the floor that holds even without it.
 */

const ALLOWED_PROTOCOLS = new Set(["http:", "https:"]);

/**
 * Addresses no deployment may ever open, including one that opted into private hosts.
 *
 * Reading instance metadata is how a container's cloud credentials leave it, and there is no
 * development task that needs it, so it is not covered by the private-host escape hatch.
 */
const NEVER_ALLOWED_HOSTNAMES = new Set([
  "169.254.169.254",
  "metadata.google.internal",
  "metadata.goog",
  // The same endpoint over IPv6. A container with an IPv6 stack reaches its credentials here and
  // nowhere in the quad-form list above says so.
  "fd00:ec2::254",
  /*
   * The ECS and Fargate task-role endpoint. Not the instance metadata address above, and on Fargate
   * it is the only one there is: a task's IAM credentials are served from it, which is exactly what
   * this list exists to keep a Bot away from, and docs/deployment.md documents Fargate as a target.
   */
  "169.254.170.2",
  // Alibaba Cloud's equivalent, which also sits outside the usual link-local handling because
  // 100.64.0.0/10 is carrier-grade NAT rather than private space.
  "100.100.100.200",
]);

/**
 * Is this the address of a cloud metadata service?
 *
 * Exported because the same question is asked outside browsing: an MCP server address an
 * administrator types is refused on the same grounds, and the answer has to come from one list.
 * Two copies drift, and the copy that misses an alias is the one that lets a credential endpoint
 * through.
 *
 * Canonicalises first, so the trailing-dot and IPv6 spellings are seen through here as well.
 */
export function isNeverAllowedHostname(hostname: string): boolean {
  return NEVER_ALLOWED_HOSTNAMES.has(canonicalHostname(hostname.toLowerCase()));
}

/** Hostnames inside the deployment. Reachable only when a deployment opts in. */
const INTERNAL_HOSTNAMES = new Set([
  "localhost",
  "127.0.0.1",
  "0.0.0.0",
  "::1",
]);

/**
 * Any name under `.localhost`.
 *
 * RFC 6761 reserves the whole `.localhost` zone for loopback, and Chromium resolves `app.localhost`
 * to 127.0.0.1 without asking DNS, so `http://admin.localhost:5432` reaches the same service as
 * `http://localhost:5432`. The exact-name list above only holds the bare `localhost`.
 */
function isLocalhostName(hostname: string): boolean {
  return hostname === "localhost" || hostname.endsWith(".localhost");
}

export type TargetVerdict =
  | { allowed: true; url: string }
  | { allowed: false; reason: string };

/**
 * The hostname reduced to the one form the lists below are written in.
 *
 * A URL can carry the same destination several ways and the browser resolves all of them:
 * `metadata.google.internal.` with the root dot, and any of the IPv6 spellings that carry an IPv4
 * address in their last 32 bits. Matching the string a caller happened to type means a deny list with
 * a door in it, so every form is reduced here before anything is compared.
 *
 * `new URL()` has already done the parts of this that are its business: it lower-cases the host,
 * compresses IPv6, and turns `127.1` into `127.0.0.1`. What it does not do is unwrap an embedded IPv4
 * or drop the root dot, because both are legal and it is not the one deciding anything.
 */
function canonicalHostname(hostname: string): string {
  // The root dot. `example.com.` and `example.com` are the same name to DNS and to Chromium.
  const name = hostname.replace(/\.+$/, "");

  if (!name.startsWith("[") || !name.endsWith("]")) return name;
  const inner = name.slice(1, -1);

  const groups = expandIpv6(inner);
  if (!groups) return inner;
  return embeddedIpv4(groups) ?? inner;
}

/**
 * The IPv4 address an IPv6 one is carrying, if it is carrying one.
 *
 * Three prefixes put a whole IPv4 address in the low 32 bits and all three reach it: `::ffff:0:0/96`
 * is what a dual-stack socket uses, `64:ff9b::/96` is the well-known NAT64 prefix and translates on
 * any IPv6-only network with a gateway, and `::/96` is the deprecated compatible form. Whichever way
 * it was written, the destination is the IPv4 address, so that is what the rules should see.
 *
 * `::` and `::1` also have zeros in the top 96 bits and are NOT this: their low bits are 0.0.0.0 and
 * 0.0.0.1, which are not addresses anybody routes to. Anything in 0.0.0.0/8 is therefore left alone
 * and handled as the IPv6 address it is.
 */
function embeddedIpv4(groups: number[]): string | null {
  const [a, b, c, d, e, f, high = 0, low = 0] = groups;
  const zeros = a === 0 && b === 0 && c === 0 && d === 0 && e === 0;
  const mapped = zeros && f === 0xffff;
  const compatible = zeros && f === 0;
  const nat64 =
    a === 0x64 && b === 0xff9b && c === 0 && d === 0 && e === 0 && f === 0;

  if (!mapped && !compatible && !nat64) return null;
  /*
   * Only the compatible form keeps its 0.0.0.0/8 addresses as IPv6. `::` and `::1` live there and are
   * what `isPrivateIpv6` below recognises.
   *
   * The mapped and NAT64 forms are different: `[::ffff:0.0.0.0]` is what a dual-stack socket calls
   * 0.0.0.0, and 0.0.0.0 reaches every port bound on this host. Left wrapped it matched neither the
   * internal hostname list, which holds the bare quad form, nor `isPrivateIpv6`, which sees `ffff` in
   * the sixth group and moves on. Verified before the change: `[::ffff:0.0.0.0]:5432` was allowed
   * with the private-host opt-in off.
   */
  if (compatible && high >> 8 === 0) return null;

  return [high >> 8, high & 255, low >> 8, low & 255].join(".");
}

/**
 * The IPv6 ranges that are this deployment rather than the internet.
 *
 * Loopback, link-local (`fe80::/10`) and unique-local (`fc00::/7`, which is where cloud providers put
 * internal endpoints) are the IPv6 answers to the RFC1918 list above. The unspecified address is here
 * too: `[::]` reaches localhost the same way `0.0.0.0` does.
 */
function isPrivateIpv6(hostname: string): boolean {
  if (!hostname.includes(":")) return false;
  const groups = expandIpv6(hostname);
  if (!groups) return false;

  if (groups.every((group) => group === 0)) return true; // ::
  if (groups.slice(0, 7).every((group) => group === 0) && groups[7] === 1) {
    return true; // ::1
  }

  const [first] = groups as [number, ...number[]];
  if (first >= 0xfe80 && first <= 0xfebf) return true; // fe80::/10
  if (first >= 0xfc00 && first <= 0xfdff) return true; // fc00::/7
  return false;
}

/** The eight groups of an IPv6 address, or null if it is not one. Compression is expanded. */
function expandIpv6(hostname: string): number[] | null {
  const halves = hostname.split("::");
  if (halves.length > 2) return null;

  const parse = (part: string) =>
    part === ""
      ? []
      : part.split(":").map((group) => Number.parseInt(group, 16));
  const head = parse(halves[0] ?? "");
  const tail = halves.length === 2 ? parse(halves[1] ?? "") : [];
  if ([...head, ...tail].some((group) => Number.isNaN(group))) return null;

  const missing = 8 - head.length - tail.length;
  if (halves.length === 1) return head.length === 8 ? head : null;
  if (missing < 0) return null;
  return [...head, ...Array(missing).fill(0), ...tail];
}

function isPrivateIpv4(hostname: string): boolean {
  const parts = hostname.split(".");
  if (parts.length !== 4) return false;
  const octets = parts.map((part) => Number.parseInt(part, 10));
  if (octets.some((value) => Number.isNaN(value) || value < 0 || value > 255)) {
    return false;
  }
  const [a, b] = octets as [number, number, number, number];
  if (a === 10) return true;
  if (a === 127) return true;
  if (a === 169 && b === 254) return true; // link-local, includes metadata
  if (a === 172 && b >= 16 && b <= 31) return true;
  if (a === 192 && b === 168) return true;
  return false;
}

/**
 * Decide whether an address a supervisor handed back may be called at all.
 *
 * Deliberately not {@link checkNavigationTarget}. That one judges where a Bot may browse, and its
 * private-host rule is exactly wrong here: our own supervisor answers with `http://127.0.0.1:<port>`
 * for a container on this machine, so applying it would refuse the normal case.
 *
 * What survives is what holds however the address was produced. The scheme must be one we speak, and
 * the cloud metadata addresses are refused whatever anything says, because that is how a container's
 * credentials leave it and no supervisor has a reason to name one.
 *
 * This matters because the address stops being ours. With a hosted provider (A10) it arrives from a
 * third party's API and goes straight into `fetch` carrying this deployment's computer token, so it
 * is worth one check that it is an address rather than a surprise.
 */
export function checkComputerAddress(raw: string): TargetVerdict {
  let url: URL;
  try {
    url = new URL(raw);
  } catch {
    return {
      allowed: false,
      reason: `The computer's address is not a URL: ${raw}`,
    };
  }

  if (!ALLOWED_PROTOCOLS.has(url.protocol)) {
    return {
      allowed: false,
      reason: `A computer must be reached over http or https, not ${url.protocol.replace(":", "")}.`,
    };
  }

  // Canonicalised for the same reason navigation is: the address reaches a fetch either way, so the
  // spellings that gate has to see through are the spellings this one has to see through.
  if (isNeverAllowedHostname(url.hostname)) {
    return {
      allowed: false,
      reason:
        "That address holds this deployment's own cloud credentials, so it is never called as a computer.",
    };
  }

  return { allowed: true, url: url.toString() };
}

/**
 * Decide whether a Bot may navigate here.
 *
 * Returns a reason rather than throwing, because the caller renders it to a person: "that address is
 * inside the deployment" is actionable, and a stack trace is not.
 */
export function checkNavigationTarget(
  raw: string,
  options: { allowPrivateHosts?: boolean } = {},
): TargetVerdict {
  let url: URL;
  try {
    url = new URL(raw);
  } catch {
    return { allowed: false, reason: "That is not a web address." };
  }

  if (!ALLOWED_PROTOCOLS.has(url.protocol)) {
    return {
      allowed: false,
      reason: `Only web addresses are allowed, and that one is ${url.protocol.replace(":", "")}.`,
    };
  }

  const hostname = canonicalHostname(url.hostname.toLowerCase());

  // Checked before the opt-in, so no configuration can reach it.
  if (isNeverAllowedHostname(hostname)) {
    return {
      allowed: false,
      reason:
        "That address holds OpenBot's own cloud keys, so the Bot can never open it.",
    };
  }

  // A local deployment legitimately browses its own services. It is opt-in, never the default, so a
  // production deployment cannot reach its own network by forgetting to set something.
  if (options.allowPrivateHosts) {
    return { allowed: true, url: url.toString() };
  }

  if (
    INTERNAL_HOSTNAMES.has(hostname) ||
    isLocalhostName(hostname) ||
    isPrivateIpv4(hostname) ||
    isPrivateIpv6(hostname)
  ) {
    return {
      allowed: false,
      reason:
        "That address is inside OpenBot's own network, so the Bot can't open it.",
    };
  }

  return { allowed: true, url: url.toString() };
}