@celilo/e2e 0.12.0 → 0.13.1

package/src/cli/completion.ts

@@ -3,7 +3,14 @@
  * All completions are static (no DB lookups needed).
  */
 
-import { BUILD_INFRA_FLAGS, COMMANDS, DOWN_FLAGS, RUN_FLAGS, UP_PRESETS } from './command-registry';
+import {
+  BUILD_INFRA_FLAGS,
+  COMMANDS,
+  DOWN_FLAGS,
+  JSON_FLAG_COMMANDS,
+  RUN_FLAGS,
+  UP_PRESETS,
+} from './command-registry';
 import { findAllTestNames } from './module-discovery';
 
 export function getCompletions(words: string[], current: number): string[] {
@@ -62,6 +69,14 @@ export function getCompletions(words: string[], current: number): string[] {
     return filterSuggestions(['zsh', 'bash'], args[1] || '');
   }
 
+  if (JSON_FLAG_COMMANDS.includes(command) && currentIndex >= 1) {
+    const used = new Set(args.slice(1));
+    return filterSuggestions(
+      ['--json'].filter((f) => !used.has(f)),
+      args[currentIndex] || '',
+    );
+  }
+
   return [];
 }
 

package/src/cli/index.ts

@@ -11,6 +11,8 @@
  *   cele2e version
  *   cele2e shell [container]
  *   cele2e status
+ *   cele2e doctor
+ *   cele2e last [--json]
  *   cele2e load
  *   cele2e scaffold <test-name>
  */
@@ -19,11 +21,13 @@ import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, readdirSync, rmSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { parse as parseYaml } from 'yaml';
+import { diagnose, formatHolderLine, formatReport } from '../doctor';
+import { readLastRun } from '../last-run';
 import {
   E2eBusyError,
+  type LockHolder,
   acquireRunLock,
   clearLock,
-  formatBusy,
   lockStatus,
   markKept,
 } from '../run-lock';
@@ -129,6 +133,19 @@ function discoverSuiteTests(suiteRoot: string): { name: string; file: string; gr
   return out;
 }
 
+/**
+ * Say out loud when we cleared this session's own kept stack. Silence would be
+ * worse than the old refusal: the operator asked for a kept stack, and it is
+ * gone now for a reason they should be able to read.
+ */
+function noteAutoRelease(holder: LockHolder | null): void {
+  if (!holder) return;
+  console.log(
+    `Auto-released your own kept stack (${holder.test}, held since ${holder.startedAt}) and continuing.`,
+  );
+  console.log('Use `cele2e run --reuse` instead if you meant to run against it.');
+}
+
 function runScript(script: string, args: string[], env?: Record<string, string>): never {
   const result = spawnSync(join(BIN_DIR, script), args, {
     stdio: 'inherit',
@@ -155,6 +172,8 @@ Commands:
   version           Show cele2e version
   shell [container] Shell into a running container (default: management)
   status            Show run-lock holder + network status (exit 3 if busy)
+  doctor            Check the environment a run needs (run's implicit preflight)
+  last              Show the most recent run's results dir + counts
   release           Free a run-lock left by --keep/up (does not tear down)
   load              Load cached Docker images from tarball
   scaffold <name>   Generate a new test file from template
@@ -180,6 +199,9 @@ Options for \`down\`:
   --keep            Stop containers but preserve volumes
   --all             Also stop competing module containers
 
+Options for \`doctor\` / \`last\` / \`status\`:
+  --json            Machine-readable output
+
 Options for \`build-infra\`:
   --save            Save Docker images to tarball after build
   --skip-modules    Skip .netapp packaging (only rebuild Docker images)
@@ -341,7 +363,11 @@ switch (command) {
     // kept state (cleared by `cele2e down`/`release`) to stop a concurrent run
     // from wiping it.
     try {
-      acquireRunLock({ test: 'up', runId: process.env.CELE2E_RUN_ID ?? crypto.randomUUID() });
+      const outcome = acquireRunLock({
+        test: 'up',
+        runId: process.env.CELE2E_RUN_ID ?? crypto.randomUUID(),
+      });
+      noteAutoRelease(outcome.autoReleasedOwnKept);
       markKept();
     } catch (err) {
       if (err instanceof E2eBusyError) {
@@ -385,7 +411,19 @@ switch (command) {
     if (lock.free) {
       console.log('  free');
     } else if (lock.holder) {
-      console.log(`  BUSY — ${formatBusy(lock.holder)}`);
+      // Heartbeat age is always printed: a wedged holder keeps a live PID, so
+      // the only thing separating "slow" from "hung for 32 minutes" is how long
+      // ago it last beat — previously visible only by reading beatAt by hand.
+      console.log(`  BUSY — ${formatHolderLine(lock.holder)}`);
+      if (lock.suspect) {
+        console.log(
+          '  ⚠ SUSPECT: the process is alive but has stopped beating. It is probably wedged;',
+        );
+        console.log(`    inspect or kill pid ${lock.holder.pid}, then \`cele2e down\`.`);
+      }
+      if (lock.ownKept) {
+        console.log('  This is YOUR OWN kept stack — the next `cele2e run` auto-releases it.');
+      }
     }
     console.log('');
 
@@ -410,6 +448,48 @@ switch (command) {
     break;
   }
 
+  case 'doctor': {
+    // The single "is my environment sane?" answer. `run` calls the same
+    // diagnose() as its preflight, so what doctor reports is exactly what a run
+    // will refuse on — no second, drifting copy of the rules.
+    const report = diagnose({ pkgDir: PKG_DIR });
+    if (args.includes('--json')) {
+      console.log(JSON.stringify(report, null, 2));
+      process.exit(report.ok ? 0 : 1);
+    }
+    console.log('=== cele2e doctor ===');
+    for (const line of formatReport(report)) console.log(line);
+    console.log('');
+    console.log(
+      report.ok ? 'Environment looks runnable.' : 'Environment is NOT runnable — see fixes above.',
+    );
+    process.exit(report.ok ? 0 : 1);
+    break;
+  }
+
+  case 'last': {
+    // Which results directory was MINE? Inferring it from `ls -t results` returns
+    // the newest run, which after a refused start is somebody else's — a suite
+    // that never executed then reads as a clean pass.
+    const last = readLastRun();
+    if (args.includes('--json')) {
+      console.log(JSON.stringify(last));
+      process.exit(last ? 0 : 1);
+    }
+    if (!last) {
+      console.error('No cele2e run recorded yet.');
+      process.exit(1);
+    }
+    console.log(`runId:      ${last.runId}`);
+    console.log(`resultsDir: ${last.resultsDir}`);
+    console.log(`status:     ${last.status}`);
+    console.log(
+      `results:    ${last.passed} passed, ${last.failed} failed${last.skipped > 0 ? `, ${last.skipped} skipped (blocked by an earlier stage)` : ''} of ${last.total}`,
+    );
+    process.exit(0);
+    break;
+  }
+
   case 'load':
     runScript('e2e-load', args);
     break;
@@ -422,10 +502,11 @@ switch (command) {
     // build-infra mutates the shared Docker images — serialize against runs.
     // Released via the lock's exit handler (runBuild may process.exit on failure).
     try {
-      acquireRunLock({
+      const outcome = acquireRunLock({
         test: 'build-infra',
         runId: process.env.CELE2E_RUN_ID ?? crypto.randomUUID(),
       });
+      noteAutoRelease(outcome.autoReleasedOwnKept);
     } catch (err) {
       if (err instanceof E2eBusyError) {
         console.error(err.message);

package/src/container-manager.ts

@@ -1,14 +1,17 @@
 import { type ExecSyncOptions, execSync, spawn } from 'node:child_process';
-import { existsSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { basename, join, resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
 import { startBrowser } from './browser';
 import { MIN_CLI_VERSION, checkCliVersion } from './cli-version-contract';
 import {
   SHARED_PROJECT_NAME,
+  firewallZoneLegs,
   generateTestComposeYaml,
   getAllMachines,
 } from './docker-compose-generator';
+import { explainBuildFailure } from './doctor';
 import { ensureSharedInfra } from './shared-infra';
 import { SIMULATOR_IPS } from './simulator-ips';
 import { startSocksProxy } from './socks-proxy';
@@ -20,8 +23,15 @@ import type {
   NetworkHandle,
   ProxyOptions,
   SocksProxyHandle,
+  TopologyPreset,
+} from './types';
+import {
+  CeliloCommandError,
+  ZONE_GATEWAYS,
+  ZONE_SUBNETS,
+  greenwaveRouterIp,
+  internalNatIp,
 } from './types';
-import { CeliloCommandError, ZONE_GATEWAYS, ZONE_SUBNETS, internalNatIp } from './types';
 
 /** Package root — where docker/, config/, simulators/ live */
 const PACKAGE_ROOT = join(__dirname, '..');
@@ -499,7 +509,11 @@ async function streamingBuild(
         console.log('[progress:done] images built');
         resolve();
       } else {
-        reject(new Error(`docker compose build failed (exit ${code}):\n${stderr.slice(-500)}`));
+        reject(
+          new Error(
+            `docker compose build failed (exit ${code}):\n${stderr.slice(-500)}${explainBuildFailure(stderr)}`,
+          ),
+        );
       }
     });
   });
@@ -515,11 +529,15 @@ function buildNetworkHandle(
   projectName: string,
   composeDir: string,
   celiloRoot: string | undefined,
+  topology: TopologyPreset,
 ): NetworkHandle {
   // Track host-side resources spawned via the handle (SOCKS proxies,
   // Playwright browsers). stop() tears these down before the docker
   // network itself.
   const activeProxies: SocksProxyHandle[] = [];
+  /** Services plugged into the undeclared segment, and the subnet it uses. */
+  const attachedToAlienSegment = new Set<string>();
+  let alienSegmentSubnet = '';
   const activeBrowsers: BrowserHandle[] = [];
 
   const handle: NetworkHandle = {
@@ -597,11 +615,35 @@ function buildNetworkHandle(
       await new Promise((r) => setTimeout(r, 500));
     },
 
-    async deployFirewall(opts = {}): Promise<void> {
-      const zones = opts.zones ?? ['dmz', 'app', 'secure'];
+    async deployFirewall(opts = {}): Promise<ExecResult> {
+      // Everything the firewall declares is derived from the topology it is
+      // wired for. `opts.zones` used to select which zones got
+      // `provided_networks`, and that cannot survive interface classification:
+      // `provided_networks` IS what writes `network.<zone>.subnet`, so a leg
+      // left out of it has no declared subnet, classifies `alien`, and the
+      // converge refuses on a firewall celilo has never understood.
+      //
+      // That is the real rule, not a harness quirk. A firewall holding an
+      // address on a segment celilo has no subnet for is one celilo cannot
+      // describe. So the wired legs and the declared zones are ONE list (D8),
+      // and a test wanting fewer legs changes the topology.
+      //
+      // The old `opts.zones` never said which NICs the box has — the compose
+      // topology decides that, and it wires fw-main to every segmented zone
+      // regardless of what a test passed. Roughly twenty call sites passed
+      // `['dmz']` against a four-leg firewall, so every one of them
+      // under-declared the hardware. Deriving from the topology makes that
+      // structurally impossible rather than something each test author has to
+      // remember, and removes a hand-maintained copy of a list the compose
+      // generator already owns.
+      //
+      // `external` is excluded from provided_networks: it is the residual, has
+      // no subnet, and is not a zone modules are placed in.
+      const declaredZones = firewallZoneLegs(topology);
+      const providedZones = declaredZones.filter((zone) => zone !== 'external');
       const firewallIp = ZONE_GATEWAYS.internal; // fw-main on internal
       const natIp = opts.natIp ?? internalNatIp();
-      const providedNetworks = zones.map((zone) => ({
+      const providedNetworks = providedZones.map((zone) => ({
         zone,
         subnet: ZONE_SUBNETS[zone],
         gateway: ZONE_GATEWAYS[zone],
@@ -637,13 +679,119 @@ function buildNetworkHandle(
       await handle.celilo('module import iptables');
       await handle.celilo(`module config set iptables firewall_ip ${firewallIp}`);
       await handle.celilo(`module config set iptables nat_ip ${natIp}`);
-      await handle.celilo(
-        `module config set iptables zones '${JSON.stringify(['internal', ...zones])}'`,
-      );
+      await handle.celilo(`module config set iptables zones '${JSON.stringify(declaredZones)}'`);
       await handle.celilo(
         `module config set iptables provided_networks '${JSON.stringify(providedNetworks)}'`,
       );
-      await handle.celilo('module deploy iptables', 180_000);
+      // `check: false` returns the failed deploy instead of throwing, so a test
+      // can assert on WHAT the refusal said. Interface classification refuses
+      // by design (D12 onboarding), and a refusal is only useful if it names
+      // the interface — which is an assertion about output, not about an
+      // exception having been raised.
+      return opts.check === false
+        ? await handle.celilo('module deploy iptables', { check: false, timeoutMs: 180_000 })
+        : await handle.celilo('module deploy iptables', 180_000);
+    },
+
+    async attachAlienSegment(opts: {
+      subnet: string;
+      containers: string[];
+    }): Promise<Record<string, string>> {
+      // A REAL cable into a REAL port. Interface classification is about what
+      // celilo finds on the box, so a test that fakes the finding — a dummy
+      // link, a stubbed interface table — is testing its own fixture. This
+      // creates an actual docker network celilo has no subnet for and plugs
+      // real containers into it, which is what an operator hanging an
+      // unmanaged switch off a spare port produces: a new interface, a global
+      // address, and something live on the other side to prove reachability
+      // with.
+      //
+      // The subnet is the caller's, and it must not be one of ZONE_SUBNETS —
+      // the whole point is that celilo cannot attribute it.
+      const netName = `${projectName}_alien-seg`;
+      alienSegmentSubnet = opts.subnet;
+      run(`docker network create --driver bridge --subnet ${opts.subnet} ${netName}`, {
+        timeout: 20_000,
+      });
+
+      const assigned: Record<string, string> = {};
+      opts.containers.forEach((service, index) => {
+        // .2 upward: .1 is the bridge itself.
+        const ip = opts.subnet.replace(/\.0\/\d+$/, `.${index + 2}`);
+        const id = run(`docker compose -p ${projectName} -f ${COMPOSE_FILE} ps -q ${service}`, {
+          cwd: composeDir,
+          timeout: 20_000,
+        });
+        if (!id) throw new Error(`attachAlienSegment: no container for service '${service}'`);
+
+        // `docker network connect` EXITS NONZERO on a container that already has
+        // a default route — "failed to set gateway while updating gateway: file
+        // exists" — while attaching the interface perfectly well: the address
+        // lands, the veth is up, and traffic flows both ways. Every container in
+        // this topology routes through the firewall, so every attach hits it.
+        // `docker network inspect` is no help either; it lists no containers for
+        // this network whether the attach worked or not.
+        //
+        // So neither the exit code nor docker's own view can be believed, and
+        // the address on the box is the only trustworthy signal. Verified below
+        // rather than assumed — a half-completed attach really does leave an
+        // address behind with no working wire, which is precisely the state that
+        // would make a classification test pass for the wrong reason.
+        try {
+          run(`docker network connect --ip ${ip} ${netName} ${id}`, { timeout: 20_000 });
+        } catch {}
+
+        const check = dockerExec(projectName, composeDir, service, 'ip -o addr show scope global');
+        if (!check.stdout.includes(ip)) {
+          throw new Error(
+            `attachAlienSegment: '${service}' has no ${ip} after connecting to ${netName}:\n${check.stdout}`,
+          );
+        }
+        assigned[service] = ip;
+        attachedToAlienSegment.add(service);
+      });
+      return assigned;
+    },
+
+    async detachAlienSegment(): Promise<void> {
+      const netName = `${projectName}_alien-seg`;
+      for (const service of attachedToAlienSegment) {
+        const id = run(`docker compose -p ${projectName} -f ${COMPOSE_FILE} ps -q ${service}`, {
+          cwd: composeDir,
+          timeout: 20_000,
+        });
+        if (id) {
+          try {
+            run(`docker network disconnect -f ${netName} ${id}`, { timeout: 20_000 });
+          } catch {}
+        }
+      }
+      try {
+        run(`docker network rm ${netName}`, { timeout: 20_000 });
+      } catch {}
+
+      // VERIFY, for the same reason attach does. A lingering address on a dead
+      // wire is still an interface celilo cannot attribute, so a test that goes
+      // on to expect a clean converge would fail somewhere far from the cause.
+      for (const service of attachedToAlienSegment) {
+        const check = dockerExec(projectName, composeDir, service, 'ip -o addr show scope global');
+        const prefix = alienSegmentSubnet.replace(/\.\d+\/\d+$/, '').replace(/\./g, '\\.');
+        const orphan = new RegExp(`(\\S+)\\s+inet\\s+${prefix}\\.\\d+`).exec(check.stdout);
+        if (orphan) {
+          dockerExec(projectName, composeDir, service, `ip link del ${orphan[1]}`);
+        }
+      }
+      attachedToAlienSegment.clear();
+    },
+
+    async deployGreenwave(): Promise<void> {
+      const routerIp = greenwaveRouterIp();
+      await handle.celilo(`machine add ${routerIp} --ssh-user root --earmark greenwave`);
+      await handle.celilo('module import greenwave');
+      await handle.celilo(`module config set greenwave router_ip ${routerIp}`);
+      await handle.celilo('module secret set greenwave router_username admin');
+      await handle.celilo('module secret set greenwave router_password admin');
+      await handle.celilo('module deploy greenwave', 180_000);
     },
 
     async socksProxy(options: ProxyOptions = {}): Promise<SocksProxyHandle> {
@@ -889,7 +1037,7 @@ export async function startNetwork(config: NetworkConfig): Promise<NetworkHandle
   // means the test is replacing the infra resolver with a module under test
   // (e.g., knot-unbound-internal). The bare target machine has no DNS server
   // until its module deploys, so this wait would always time out. Management
-  // can still resolve names via the fallback `nameserver 100.100.0.1` in
+  // can still resolve names via the fallback `nameserver 203.0.113.1` in
   // its resolv.conf during deploy.
   //
   // The resolver-under-test may sit in ANY zone, not just `internal`: ISS-0156
@@ -1063,7 +1211,7 @@ export async function startNetwork(config: NetworkConfig): Promise<NetworkHandle
           config.managementZone === 'secure-mgmt' || (config.secureMgmtMachines ?? []).length > 0
             ? `network.secure-mgmt.subnet=${ZONE_SUBNETS['secure-mgmt']} network.secure-mgmt.gateway=${ZONE_GATEWAYS['secure-mgmt']} `
             : ''
-        }dns.primary=100.100.0.1 \
+        }dns.primary=203.0.113.1 \
         dns.fallback=1.0.0.1,8.8.8.8`,
     );
     if (initResult.exitCode !== 0) {
@@ -1095,7 +1243,7 @@ export async function startNetwork(config: NetworkConfig): Promise<NetworkHandle
   // Emit project name so the runner can persist it if --keep is set
   console.log(`[e2e:project] ${projectName}`);
 
-  return buildNetworkHandle(projectName, composeDir, celiloRoot);
+  return buildNetworkHandle(projectName, composeDir, celiloRoot, config.topology);
 }
 
 /**
@@ -1106,6 +1254,26 @@ export async function startNetwork(config: NetworkConfig): Promise<NetworkHandle
  *
  * If the project doesn't exist, throws with an actionable error.
  */
+/**
+ * Which topology a already-running stack was built with, read back from its
+ * generated compose file. `direct-internet` is the one where fw-main holds a leg
+ * on `isp-external`; everything else is `default`.
+ */
+function topologyFromComposeFile(composePath: string): TopologyPreset {
+  try {
+    const compose = parseYaml(readFileSync(composePath, 'utf-8')) as {
+      services?: Record<string, { networks?: Record<string, unknown> }>;
+    };
+    return compose.services?.['fw-main']?.networks?.['isp-external']
+      ? 'direct-internet'
+      : 'default';
+  } catch {
+    // An unreadable compose file means the stack was not built by this
+    // generator; `default` is the topology the fleet runs and the safer guess.
+    return 'default';
+  }
+}
+
 export function reconnectNetwork(projectName: string): NetworkHandle {
   const composeDir = PACKAGE_ROOT;
 
@@ -1128,5 +1296,14 @@ export function reconnectNetwork(projectName: string): NetworkHandle {
   console.log(`[progress:done] reconnected to existing network (${projectName})`);
   console.log(`[e2e:project] ${projectName}`);
 
-  return buildNetworkHandle(projectName, composeDir, findCeliloRoot());
+  // `--reuse` has no NetworkConfig to read, so the topology is recovered from the
+  // compose file that built the running stack — the same artifact the generator
+  // wrote. Guessing a default here would silently mis-declare the firewall's legs
+  // on exactly the runs used for debugging.
+  return buildNetworkHandle(
+    projectName,
+    composeDir,
+    findCeliloRoot(),
+    topologyFromComposeFile(join(composeDir, COMPOSE_FILE)),
+  );
 }

package/src/docker-compose-generator.ts

@@ -7,6 +7,7 @@ import type { MachineSpec, NetworkConfig, TopologyPreset, Zone } from './types';
 import {
   ZONE_GATEWAYS,
   ZONE_SUBNETS,
+  externalWanIp,
   greenwaveRouterIp,
   internalResolverIp,
   zoneIp,
@@ -146,16 +147,50 @@ const PROTECTED_SUBNETS = (['dmz', 'app', 'secure', 'secure-mgmt'] as const)
   .map((zone) => ZONE_SUBNETS[zone])
   .join(' ');
 
+/**
+ * The zone legs fw-main actually holds, per topology — the SINGLE source of truth
+ * for "which networks is the customer firewall wired to".
+ *
+ * This exists because `deployFirewall`'s `opts.zones` was doing two jobs at once:
+ * saying which zones get `provided_networks` written to system config, AND
+ * standing in as a claim about the box's hardware. It was only ever the first.
+ * The compose file below is what decides the second, and roughly twenty call
+ * sites passed `['dmz']` while the generator wired four legs regardless — so
+ * every one of them under-declared, silently.
+ *
+ * Both the compose services and `deployFirewall` read this, so a test cannot
+ * under-declare by omission and a new leg cannot be added in one place only.
+ * `packages/e2e/tests/firewall-zone-legs.test.ts` holds them to each other.
+ */
+export type FirewallLeg = Zone | 'external';
+
+export function firewallZoneLegs(topology: TopologyPreset): FirewallLeg[] {
+  const segmented: FirewallLeg[] = ['internal', 'dmz', 'app', 'secure'];
+  return topology === 'direct-internet' ? [...segmented, 'external'] : segmented;
+}
+
+/**
+ * The compose `networks:` block for fw-main, derived from {@link firewallZoneLegs}
+ * so the wiring and the declaration cannot drift. `external` is the public leg and
+ * lives on the `isp-external` docker network rather than a zone-named one.
+ */
+function firewallNetworks(topology: TopologyPreset): Record<string, { ipv4_address: string }> {
+  const nets: Record<string, { ipv4_address: string }> = {};
+  for (const zone of firewallZoneLegs(topology)) {
+    if (zone === 'external') {
+      nets['isp-external'] = { ipv4_address: externalWanIp() };
+    } else {
+      nets[zone] = { ipv4_address: ZONE_GATEWAYS[zone] };
+    }
+  }
+  return nets;
+}
+
 function defaultTopologyServices(config: NetworkConfig): Record<string, unknown> {
   return {
     'fw-main': baseService({
       build: { context: '.', dockerfile: 'docker/Dockerfile.firewall' },
-      networks: {
-        internal: { ipv4_address: ZONE_GATEWAYS.internal },
-        dmz: { ipv4_address: ZONE_GATEWAYS.dmz },
-        app: { ipv4_address: ZONE_GATEWAYS.app },
-        secure: { ipv4_address: ZONE_GATEWAYS.secure },
-      },
+      networks: firewallNetworks('default'),
       cap_add: ['NET_ADMIN', 'SYS_ADMIN'],
       // A firewall may also terminate a VPN (the admin tunnel the `wireguard`
       // module owns). wireguard-go needs the tun device; the kernel module is
@@ -169,7 +204,7 @@ function defaultTopologyServices(config: NetworkConfig): Record<string, unknown>
       build: { context: '.', dockerfile: 'docker/Dockerfile.greenwave-sim' },
       networks: {
         internal: { ipv4_address: greenwaveRouterIp() },
-        'isp-external': { ipv4_address: '100.100.0.100' },
+        'isp-external': { ipv4_address: '203.0.113.100' },
       },
       cap_add: ['NET_ADMIN', 'SYS_ADMIN'],
       // A firewall may also terminate a VPN (the admin tunnel the `wireguard`
@@ -194,13 +229,7 @@ function directInternetTopologyServices(): Record<string, unknown> {
   return {
     'fw-main': baseService({
       build: { context: '.', dockerfile: 'docker/Dockerfile.firewall' },
-      networks: {
-        internal: { ipv4_address: ZONE_GATEWAYS.internal },
-        dmz: { ipv4_address: ZONE_GATEWAYS.dmz },
-        app: { ipv4_address: ZONE_GATEWAYS.app },
-        secure: { ipv4_address: ZONE_GATEWAYS.secure },
-        'isp-external': { ipv4_address: '100.100.0.100' },
-      },
+      networks: firewallNetworks('direct-internet'),
       cap_add: ['NET_ADMIN', 'SYS_ADMIN'],
       // A firewall may also terminate a VPN (the admin tunnel the `wireguard`
       // module owns). wireguard-go needs the tun device; the kernel module is
@@ -302,7 +331,7 @@ export function generateSharedInfraYaml(): string {
     build: { context: '.', dockerfile: 'docker/Dockerfile.pebble' },
     networks: { 'internet-external': { ipv4_address: SIMULATOR_IPS.PEBBLE } },
     cap_add: ['NET_ADMIN'],
-    command: '-config /config/pebble-config.json -dnsserver 100.100.0.1:53',
+    command: '-config /config/pebble-config.json -dnsserver 203.0.113.1:53',
     volumes: [
       './config/pebble/pebble-config.json:/config/pebble-config.json:ro',
       './config/pebble/pebble-tls.crt:/config/pebble-tls.crt:ro',
@@ -325,7 +354,7 @@ export function generateSharedInfraYaml(): string {
   // celilo's `public_dns` check resolves from.
   //
   // A peer of comcast-resolver, not a replacement: the fleet is configured to
-  // use THAT one (`system init` writes dns.primary=100.100.0.1), and celilo
+  // use THAT one (`system init` writes dns.primary=203.0.113.1), and celilo
   // refuses to accept a resolver it already asks as evidence about the public
   // internet — a check that used the fleet's own resolver would pass whatever
   // the internet sees, which is the celilo#626 blindness one layer up. So the
@@ -357,13 +386,13 @@ export function generateSharedInfraYaml(): string {
   // External website prober simulator — mimics isitup.org's /api.json endpoint.
   // Sits on internet-external so probe requests exercise the real public-facing
   // path (target domain → DNS → ISP → firewall → Caddy). Uses comcast-resolver
-  // at 100.100.0.1 as DNS so it can recursively resolve the simulated public
+  // at 203.0.113.1 as DNS so it can recursively resolve the simulated public
   // zones (e.g. iamtheinternet.org).
   services.isitup = baseService({
     build: { context: '.', dockerfile: 'docker/Dockerfile.isitup' },
     networks: { 'internet-external': { ipv4_address: SIMULATOR_IPS.ISITUP } },
     cap_add: ['NET_ADMIN'],
-    dns: ['100.100.0.1'],
+    dns: ['203.0.113.1'],
   });
 
   // celilo.computer static site simulator — serves install.sh and the docs
@@ -375,7 +404,7 @@ export function generateSharedInfraYaml(): string {
     build: { context: '.', dockerfile: 'docker/Dockerfile.celilo-website-sim' },
     networks: { 'internet-external': { ipv4_address: SIMULATOR_IPS.WEBSITE } },
     cap_add: ['NET_ADMIN'],
-    dns: ['100.100.0.1'],
+    dns: ['203.0.113.1'],
   });
 
   // npm-compat registry simulator — serves @celilo/* tarballs to install.sh's
@@ -452,7 +481,7 @@ export function generateTestComposeYaml(config: NetworkConfig, celiloRoot?: stri
     // Only when celilo-mgr lives off the internal LAN — keeps the default
     // topology's generated compose byte-identical for every existing test.
     ...(needsSecureMgmt ? { 'secure-mgmt': zoneNetworkDef('secure-mgmt') } : {}),
-    'isp-external': networkDef('100.100.0.0/24', '100.100.0.250'),
+    'isp-external': networkDef('203.0.113.0/24', '203.0.113.250'),
     // internet-external is owned by shared infra; real-internet is per-test
     // (it just bridges fw-ext ↔ comcast-resolver, no shared service uses it).
     // real-internet uses Docker's default gateway (.1) because fw-ext's
@@ -588,7 +617,7 @@ export function generateTestComposeYaml(config: NetworkConfig, celiloRoot?: stri
   services['fw-ext'] = baseService({
     build: { context: '.', dockerfile: 'docker/Dockerfile.router' },
     networks: {
-      'isp-external': { ipv4_address: '100.100.0.101' },
+      'isp-external': { ipv4_address: '203.0.113.101' },
       'internet-external': { ipv4_address: '100.64.0.1' },
       'real-internet': { ipv4_address: '172.30.0.5' },
     },
@@ -599,7 +628,7 @@ export function generateTestComposeYaml(config: NetworkConfig, celiloRoot?: stri
   services['comcast-resolver'] = baseService({
     build: { context: '.', dockerfile: 'docker/Dockerfile.resolver' },
     networks: {
-      'isp-external': { ipv4_address: '100.100.0.1' },
+      'isp-external': { ipv4_address: '203.0.113.1' },
       'real-internet': { ipv4_address: '172.30.0.4' },
     },
     cap_add: ['NET_ADMIN'],
@@ -720,7 +749,7 @@ export function generateComposeYaml(config: NetworkConfig, celiloRoot = '..'): s
     dmz: zoneNetworkDef('dmz'),
     app: zoneNetworkDef('app'),
     secure: zoneNetworkDef('secure'),
-    'isp-external': networkDef('100.100.0.0/24', '100.100.0.250'),
+    'isp-external': networkDef('203.0.113.0/24', '203.0.113.250'),
     'internet-external': networkDef('100.64.0.0/24', '100.64.0.250'),
     'real-internet': {
       driver: 'bridge',
@@ -774,7 +803,7 @@ export function generateComposeYaml(config: NetworkConfig, celiloRoot = '..'): s
   services['fw-ext'] = baseService({
     build: { context: '.', dockerfile: 'docker/Dockerfile.router' },
     networks: {
-      'isp-external': { ipv4_address: '100.100.0.101' },
+      'isp-external': { ipv4_address: '203.0.113.101' },
       'internet-external': { ipv4_address: '100.64.0.1' },
       'real-internet': { ipv4_address: '172.30.0.5' },
     },
@@ -785,7 +814,7 @@ export function generateComposeYaml(config: NetworkConfig, celiloRoot = '..'): s
   services['comcast-resolver'] = baseService({
     build: { context: '.', dockerfile: 'docker/Dockerfile.resolver' },
     networks: {
-      'isp-external': { ipv4_address: '100.100.0.1' },
+      'isp-external': { ipv4_address: '203.0.113.1' },
       'real-internet': { ipv4_address: '172.30.0.4' },
     },
     cap_add: ['NET_ADMIN'],
@@ -847,7 +876,7 @@ export function generateComposeYaml(config: NetworkConfig, celiloRoot = '..'): s
     build: { context: '.', dockerfile: 'docker/Dockerfile.pebble' },
     networks: { 'internet-external': { ipv4_address: SIMULATOR_IPS.PEBBLE } },
     cap_add: ['NET_ADMIN'],
-    command: '-config /config/pebble-config.json -dnsserver 100.100.0.1:53',
+    command: '-config /config/pebble-config.json -dnsserver 203.0.113.1:53',
     volumes: [
       './config/pebble/pebble-config.json:/config/pebble-config.json:ro',
       './config/pebble/pebble-tls.crt:/config/pebble-tls.crt:ro',