feat(azure): keep az's network traffic on the emulator with an egress guard

.github/workflows/azure-smoke.yml

@@ -16,6 +16,8 @@ jobs:
     env:
       # The token's licence must include LocalStack for Azure, or the emulator refuses to start.
       LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}
+      # The list reporter prints each test step, so the run's log shows the whole tour.
+      PLAYWRIGHT_LIST_PRINT_STEPS: "1"
     steps:
       - name: Checkout code
         uses: actions/checkout@v4

docs/AZURE.md

@@ -6,6 +6,26 @@
 - It uses your Azure CLI extensions: install one with `az extension add --name <extension>`.
 - Bicep templates need the `bicep` binary on your `PATH` (for example `brew install bicep` or `winget install Microsoft.Bicep`).
 - Relative file paths in commands resolve against `LOCALSTACK_AZ_WORKDIR`, by default the directory the MCP client starts the server in.
-- `rest` calls the emulator: give it a relative URL. An absolute URL must name a local host; a `management.azure.com` URL is turned into a relative one.
-- Only `rest` URLs are checked: an endpoint given in a command, such as `--blob-endpoint` or a connection string, is used as it is.
+- For an operation that has no `az` command, use [`az rest`](https://learn.microsoft.com/cli/azure/reference-index#az-rest), which sends a raw HTTP request to the Azure API. Give it a relative URL, such as `/subscriptions/{subscriptionId}/resourcegroups?api-version=2021-04-01`. A `management.azure.com` URL is turned into a relative one. Any other absolute URL must be https on a `localhost.localstack.cloud` name, such as `https://azure.localhost.localstack.cloud:4566/...`, the names the emulator's certificate is for.
+- `az` reaches only the emulator: see [What `az` can reach](#what-az-can-reach).
 - The Docker image does not include the Azure CLI yet: run the server with npx or from source to use the Azure tool.
+
+## What `az` can reach
+
+Some `az` commands take an address to send data to, such as `--blob-endpoint` or a connection string. Without a check, a command could point that address at any server and upload a local file there. So the tool makes sure `az` can only talk to the emulator.
+
+It does this with a small local proxy, started for each command. `az` is pointed at the proxy for all its HTTP traffic. The proxy passes on https to the emulator's names (`localhost.localstack.cloud` and every name under it) and the loopback ones, and refuses everything else, including plain `http://`. If the command then fails, the answer names the refused host. Any port on those names is allowed, and every LocalStack serves the same certificate for them, so an endpoint with the wrong port can reach another LocalStack running on this machine and write there; the data stays on this machine.
+
+The proxy sends those names to this machine itself, so `az` does not need DNS to find the emulator. Your application, `kubectl` and Docker still look these names up: if your router or company DNS blocks answers that point to `127.0.0.1`, allow `localhost.localstack.cloud` there.
+
+Anything `az` would download from the internet fails, for example:
+
+- Bicep registry modules (`br:` and `br/public:`), with error BCP192: use local module files.
+- `--template-uri`, and parameter files given as URLs (`--parameters https://...`): download the file and pass its path.
+- `az extension list-available`: run it with your own Azure CLI.
+
+The proxy covers `az`, the Azure SDKs, MSAL and Bicep, which all honour `HTTPS_PROXY` and `HTTP_PROXY`. It is not a sandbox, and these are outside it:
+
+- programs that open their own connections, such as the Docker daemon behind `az acr login` and `az containerapp up --source`, a database client behind `flexible-server connect`, or the MQTT device commands of the `azure-iot` extension;
+- workloads running in the emulator (container instances, web apps, AKS clusters), which have their own network access;
+- an agent with a shell, which does not go through this tool at all.

src/lib/azure/child-env.test.ts

@@ -70,3 +70,23 @@ describe("buildAzChildEnv", () => {
     });
   });
 });
+
+test("no proxy variable of the server's reaches az: with no_proxy=* the egress guard would see nothing", () => {
+  const proxies = {
+    NO_PROXY: "*",
+    no_proxy: "*",
+    HTTP_PROXY: "http://corp:3128",
+    http_proxy: "http://corp:3128",
+    HTTPS_PROXY: "http://corp:3128",
+    https_proxy: "http://corp:3128",
+    ALL_PROXY: "socks5://corp:1080",
+    all_proxy: "socks5://corp:1080",
+  };
+  for (const platform of ["linux", "darwin", "win32"] as const) {
+    const env = buildAzChildEnv({ PATH: "/usr/bin", ...proxies }, platform, config, launcher);
+    expect([platform, Object.keys(env).filter((name) => /proxy/i.test(name))]).toEqual([
+      platform,
+      [],
+    ]);
+  }
+});

src/lib/azure/config.test.ts

@@ -1,4 +1,4 @@
-import { getAzureConfig, isLocalHost } from "./config";
+import { getAzureConfig, isEmulatorName, isLocalHost } from "./config";
 
 const HOME = "/home/u";
 const deps = {
@@ -47,6 +47,19 @@ describe("getAzureConfig", () => {
     }
   });
 
+  test("isEmulatorName: the names the emulator's certificate is for, not the loopback ones", () => {
+    expect(isEmulatorName("Azure.LocalHost.LocalStack.Cloud.")).toBe(true);
+    expect(isEmulatorName("localhost.localstack.cloud")).toBe(true);
+    for (const host of [
+      "localhost",
+      "127.0.0.1",
+      "[::1]",
+      "localhost.localstack.cloud.evil.example",
+    ]) {
+      expect(isEmulatorName(host)).toBe(false);
+    }
+  });
+
   test.each(["~/.azure", "~/.azure/sub", "~", "/cfg/inner"])(
     "refuses a config dir that overlaps an Azure CLI profile: %s",
     (dir) => {

src/lib/azure/config.ts

@@ -32,19 +32,24 @@ export interface AzureConfigDeps {
   isDirectory?: (p: string) => boolean;
 }
 
-/**
- * The hosts an absolute `rest` URL may name: LocalStack's public DNS names for 127.0.0.1
- * (localhost.localstack.cloud and its subdomains) and the loopback names and addresses.
- */
-export function isLocalHost(host: string): boolean {
-  const h = host
+const canonical = (host: string) =>
+  host
     .toLowerCase()
     .replace(/\.$/, "")
     .replace(/^\[(.*)\]$/, "$1");
-  return (
-    ["localhost", "127.0.0.1", "::1", "localhost.localstack.cloud"].includes(h) ||
-    h.endsWith(".localhost.localstack.cloud")
-  );
+
+/**
+ * LocalStack's public DNS names for 127.0.0.1: localhost.localstack.cloud and its subdomains,
+ * the names the emulator's certificate is for.
+ */
+export function isEmulatorName(host: string): boolean {
+  const h = canonical(host);
+  return h === "localhost.localstack.cloud" || h.endsWith(".localhost.localstack.cloud");
+}
+
+/** The hosts the egress guard tunnels to: the emulator's names and the loopback ones. */
+export function isLocalHost(host: string): boolean {
+  return isEmulatorName(host) || ["localhost", "127.0.0.1", "::1"].includes(canonical(host));
 }
 
 function isDirectory(p: string): boolean {

src/lib/azure/egress-guard.test.ts

@@ -0,0 +1,211 @@
+import http from "http";
+import net, { type AddressInfo } from "net";
+import { startEgressGuard, type EgressGuard } from "./egress-guard";
+
+// Local servers stand in for the emulator: an echo server that keeps its sockets, one that
+// closes at once, and one that counts the connections it gets.
+let echo: net.Server;
+const echoSockets: net.Socket[] = [];
+let closer: net.Server;
+let counter: net.Server;
+let echoPort: number;
+let closerPort: number;
+let counterPort: number;
+let connections = 0;
+let guard: EgressGuard;
+const dialled: Array<[number, string]> = [];
+
+const listen = (server: net.Server) =>
+  new Promise<number>((resolve) =>
+    server.listen(0, "127.0.0.1", () => resolve((server.address() as AddressInfo).port))
+  );
+const guardPort = () => Number(new URL(guard.env.HTTPS_PROXY).port);
+
+/** Sends CONNECT through the guard; resolves with its status line and the open socket. */
+function connectThrough(authority: string): Promise<{ line: string; socket: net.Socket }> {
+  return new Promise((resolve, reject) => {
+    const socket = net.connect(guardPort(), "127.0.0.1");
+    socket.once("error", reject);
+    let head = "";
+    const onData = (chunk: Buffer) => {
+      head += chunk.toString("latin1");
+      if (!head.includes("\r\n\r\n")) return;
+      socket.off("data", onData);
+      resolve({ line: head.split("\r\n")[0], socket });
+    };
+    socket.on("data", onData);
+    socket.write(`CONNECT ${authority} HTTP/1.1\r\nHost: ${authority}\r\n\r\n`);
+  });
+}
+
+/** Sends a plain-HTTP proxy request (absolute URI) through the guard. */
+function getThrough(url: string): Promise<{ status: number; reason: string }> {
+  return new Promise((resolve, reject) => {
+    const req = http.request({ host: "127.0.0.1", port: guardPort(), path: url }, (res) => {
+      res.resume();
+      res.on("end", () =>
+        resolve({ status: res.statusCode ?? 0, reason: res.statusMessage ?? "" })
+      );
+    });
+    req.on("error", reject);
+    req.end();
+  });
+}
+
+/** The guard still answers: a tunnel to the echo server opens. */
+async function stillServes() {
+  const { line, socket } = await connectThrough(`localhost:${echoPort}`);
+  socket.destroy();
+  return line;
+}
+
+beforeAll(async () => {
+  echo = net.createServer((socket) => {
+    socket.on("error", () => undefined);
+    echoSockets.push(socket);
+    socket.pipe(socket);
+  });
+  echoPort = await listen(echo);
+  // Resets once the tunnel carries data, so the reset always comes after the guard's 200.
+  closer = net.createServer((socket) => socket.once("data", () => socket.resetAndDestroy()));
+  closerPort = await listen(closer);
+  counter = net.createServer((socket) => {
+    connections += 1;
+    socket.destroy();
+  });
+  counterPort = await listen(counter);
+});
+afterAll(() => {
+  echo.close();
+  closer.close();
+  counter.close();
+});
+beforeEach(async () => {
+  dialled.length = 0;
+  connections = 0;
+  guard = await startEgressGuard({
+    connect: (port, host) => {
+      dialled.push([port, host]);
+      // 443 is the emulator's https port in the wild; the echo server stands in for it.
+      return net.connect({ port: port === 443 ? echoPort : port, host, allowHalfOpen: true });
+    },
+  });
+});
+afterEach(() => guard.close());
+
+test("points az's HTTPS_PROXY and HTTP_PROXY at itself", () => {
+  expect(guard.env.HTTPS_PROXY).toMatch(/^http:\/\/127\.0\.0\.1:\d+$/);
+  expect(guard.env.HTTP_PROXY).toBe(guard.env.HTTPS_PROXY);
+});
+
+test("tunnels to the emulator's names on loopback, without DNS", async () => {
+  for (const host of ["azure.localhost.localstack.cloud", "LOCALHOST", "127.1"]) {
+    const { line, socket } = await connectThrough(`${host}:${echoPort}`);
+    expect(line).toBe("HTTP/1.1 200 Connection Established");
+    const echoed = new Promise<string>((resolve) => socket.once("data", (d) => resolve(String(d))));
+    socket.write("ping");
+    expect(await echoed).toBe("ping");
+    socket.destroy();
+  }
+  // Nothing listens on ::1, so the dial fails and the client gets a 502.
+  const ipv6 = await connectThrough(`[::1]:${echoPort}`);
+  expect(ipv6.line).toBe("HTTP/1.1 502 Bad Gateway");
+  ipv6.socket.destroy();
+  expect(dialled).toEqual([
+    [echoPort, "127.0.0.1"],
+    [echoPort, "127.0.0.1"],
+    [echoPort, "127.0.0.1"],
+    [echoPort, "::1"],
+  ]);
+  expect(guard.refused()).toEqual([]);
+});
+
+test("URL drops the default port; a tunnel to :443 still dials 443", async () => {
+  const { line, socket } = await connectThrough("azure.localhost.localstack.cloud:443");
+  expect(line).toBe("HTTP/1.1 200 Connection Established");
+  socket.destroy();
+  expect(dialled).toEqual([[443, "127.0.0.1"]]);
+});
+
+test("refuses every other host, naming it in the 403, and never dials it", async () => {
+  const lines: string[] = [];
+  for (const authority of [
+    "storage.evil.example:443",
+    `10.0.0.5:${echoPort}`,
+    "localhost.localstack.cloud.evil.example:443",
+    "[2001:db8::1]:443",
+  ]) {
+    const { line, socket } = await connectThrough(authority);
+    lines.push(line);
+    socket.destroy();
+  }
+  // Python puts the reason phrase into its error, so az's own stderr names the host too.
+  expect(lines[0]).toBe("HTTP/1.1 403 blocked by the egress guard: storage.evil.example");
+  expect(lines.every((line) => line.startsWith("HTTP/1.1 403 "))).toBe(true);
+  expect(guard.refused()).toEqual([
+    "storage.evil.example",
+    "10.0.0.5",
+    "localhost.localstack.cloud.evil.example",
+    "[2001:db8::1]",
+  ]);
+  expect(dialled).toEqual([]);
+});
+
+test("a target that is not host:port is refused, and nothing is dialled", async () => {
+  for (const authority of [
+    `localhost:+${echoPort}`,
+    `localhost:${echoPort}.0`,
+    `localhost:${echoPort}e0`,
+    `user@localhost:${echoPort}`,
+    `localhost:${echoPort}/path`,
+    "no-port-here",
+  ]) {
+    const { line, socket } = await connectThrough(authority);
+    expect([authority, line]).toEqual([authority, "HTTP/1.1 400 Bad Request"]);
+    socket.destroy();
+  }
+  expect(dialled).toEqual([]);
+});
+
+test("plain HTTP is never relayed, not even to the emulator: 403 naming the target", async () => {
+  expect(await getThrough(`http://localhost:${counterPort}/`)).toEqual({
+    status: 403,
+    reason: `blocked by the egress guard: http://localhost:${counterPort}`,
+  });
+  expect((await getThrough("http://evil.example/upload")).status).toBe(403);
+  expect((await getThrough("/not-absolute")).status).toBe(400);
+  expect(guard.refused()).toEqual([`http://localhost:${counterPort}`, "http://evil.example"]);
+  expect(connections).toBe(0);
+  expect(dialled).toEqual([]);
+});
+
+test("a client that resets mid-tunnel takes the upstream down, and the guard keeps serving", async () => {
+  const { line, socket } = await connectThrough(`localhost:${echoPort}`);
+  expect(line).toBe("HTTP/1.1 200 Connection Established");
+  // An echo makes sure the upstream side exists before the reset.
+  const echoed = new Promise((resolve) => socket.once("data", resolve));
+  socket.write("ping");
+  await echoed;
+  const upstream = echoSockets[echoSockets.length - 1];
+  const upstreamClosed = new Promise((resolve) => upstream.once("close", resolve));
+  socket.resetAndDestroy();
+  await upstreamClosed;
+  expect(await stillServes()).toBe("HTTP/1.1 200 Connection Established");
+});
+
+test("an upstream that resets first ends the client's side of the tunnel", async () => {
+  const { line, socket } = await connectThrough(`localhost:${closerPort}`);
+  expect(line).toBe("HTTP/1.1 200 Connection Established");
+  const ended = new Promise((resolve) => socket.once("end", resolve));
+  socket.write("ping");
+  await ended;
+  socket.destroy();
+  expect(await stillServes()).toBe("HTTP/1.1 200 Connection Established");
+});
+
+test("close() ends an open tunnel", async () => {
+  const { socket } = await connectThrough(`localhost:${echoPort}`);
+  const closed = new Promise((resolve) => socket.once("close", resolve));
+  await guard.close();
+  await closed;
+});